Robotic Systems (draft)

Kris Hauser

University of Illinois at Urbana-Champaign

Last update: 7/6/2024

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 four 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.
  • Newer versions of Jupyter Lab don't support equation numbering and do not support older extensions that provide equation numbering.

Jupyter Installation:

  1. Install software for running the notebook:

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

pip install klampt
pip install klampt_jupyter

(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. )

Then, to enable Klampt-jupyter-extension on Jupyterlab, run

jupyter labextension enable klampt_jupyter

Classical Jupyter notebook

To use classical Jupyter Notebook, install all items mentioned above, as well as jupyter_contrib_nbextensions for LaTeX and table of content support.

Then run

jupyter nbextension enable --py klampt_jupyter

You may need --sys-prefix, --user, or --system to the latter call.

To enable the best reading experience on Jupyter Notebook, 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 Jupyterlab or Jupyter Notebook from the RoboticSystemsBook directory using the console command:
cd RoboticSystemsBook
jupyter lab

or jupyter notebook if you are using classical 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)

VSCode issues

VSCode is becoming ever more popular, and it can almost be used like a local Jupyter installation, but its notebook rendering has many limitations. Specifically:

  • Equation numbering and cross-referencing is broken, so you are likley to see equation rendering / cross-reference error messages in red.
  • The nice code-folding extension of Jupyter notebook is not supported, so you will see large code blocks that interrupt the flow of the text.

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.