Robotic Systems (draft)

Kris Hauser

University of Illinois at Urbana-Champaign

Last update: 12/28/2020

Table of Contents

About

This book is a work in progress! The source material is my lecture notes from courses at Indiana University, Duke University, and University of Illinois at Urbana-Champaign, which are progressively being converted to Jupyter Notebook and HTML format.

The conversion tools that I am using may create broken matrix equations, links, references, or incorrectly formatted figures. I am trying to correct them as I go, but I may miss some. If you notice anything that needs correcting, please email me at kkhauser@illinois.edu. Or better yet, make the corrections in the notebook directly and issue a Git pull request.

Options for Working with Jupyter Notebook

The book comes in HTML and Jupyter Notebook formats, and running the full Jupyter Notebook provides the most complete experience, with inline quizzes and code examples that you can visualize and edit live in your browser.

There are three routes to running the Jupyter notebooks:

Running on Binder

Binder is a very nice service that we've pre-configured to have all dependencies needed to run this book. Just click here:

Binder

That's it!

Binder pros:

  • Stupidly easy to start.
  • Runs everywhere.
  • Almost completely full-featured; runs interactive Klamp't visualizations.
  • Integrates nicely with Github; automatically gets updates to the Github repo.

Binder cons:

  • Relative slow boot time (10–20s).
  • Can't easily save / restore your work – you will need to manually Download or Save to Browser Storage.

Running on Google Colab

I am progressively updating the book to be compatible with Google Colab, and this is the second-easiest way to get started. Just click on the following link:

Open In Colab

Colab pros:

  • Runs everywhere
  • Integrates nicely with Github; automatically gets updates to the Github repo.
  • Klamp't can output static visualizations of 3D worlds and animations

Colab cons:

  • Equations are not numbered and cross-references don't work.
  • Need to insert / run extra code cells to enable interactive quizzes and code.
  • Klamp't visualization windows are not interactive due to Colab incompatibility with custom IPython widgets.
  • The Table of Contents feature only works with cells that start with a header. These are being updated slowly...

Colab installation:

No installation needed.

To run interactive quizzes and code, you will need to insert and run a code cell containing the following code:

%cd ~
!git clone --depth 1 https://github.com/krishauser/RoboticSystemsBook
%cd RoboticSystemsBook
import rsbook_code
!pip install klampt

which will import the code examples for this book and install Klampt.

Jupyter Notebook installation on local machine

Jupyter Notebook is the native source of this book, and installing this on your machine will allow you to run truly interactive examples.

Jupyter pros

  • Runs interactive Klamp't windows.
  • All features supported.
  • Can switch to native OpenGL visualization for more features, if desired.
  • Closer to production robotics code.

Jupyter cons

  • Need to install on your local machine. Possible compability issues with other Python installs, e.g., Anaconda.

Jupyter Installation:

  1. Install software for running the notebook:

On most systems (Linux, Windows, OSX), the Klamp't Python API can be installed using pip as follows:

pip install klampt

(Note that the Klamp't source is the most up-to-date way to install Klamp't, and is mostly pain-free on Linux and OSX platforms. )

To install Klampt-jupyter-extension, run

git clone https://github.com/krishauser/Klampt-jupyter-extension.git
cd Klampt-jupyter-extension
make install-user
cd ..

Next, to enable the best reading experience, we will install the jupyter_contrib_nbextensions package and enable the "(some) LaTeX environments for Jupyter", "Table of Contents", and "Codefolding" Jupyter Notebook plugins. To do so, run

pip install jupyter_contrib_nbextensions
jupyter contrib nbextension install --user
jupyter nbextension enable --py widgetsnbextension
jupyter nbextension enable codefolding/main
jupyter nbextension enable latex_envs/latex_envs
jupyter nbextension enable toc2/main
jupyter nbextension enable equation-numbering/main
  1. Download the book source from Github:
git clone https://github.com/krishauser/RoboticSystemsBook
  1. Run Jupyter Notebook from the RoboticSystemsBook directory using the console command:
cd RoboticSystemsBook
jupyter notebook

This will launch a web browser interface to Jupyter.

  1. Open the Jupyter Notebook files to browse (this page is named Book.ipynb). Happy reading!

(Note: you must run Jupyter in the RoboticSystemsBook folder to have access to the interactive quizzes and exercises, which use code in the rsbook_code folder)

Known issues

Jupyter Notebook LaTeX rendering uses MathJAX inside Markdown, which occasionally has trouble rendering complex equations. If you see stray code like = \begin{equation} etc, this is a known rendering problem with multiple matrices. It seems like this problem is more prevalent in static HTML and Colab; try opening the book in a native Jupyter Notebook or on Binder if these rendering issues prevent you from understanding the equation.

In [ ]: