Kinematic foundations: the reading and its companion files

Extract the whole zip file first, then open chapter-01.pdf from the extracted folder. The links in the PDF open files from this folder, so a copy of the PDF alone has no working links, and a PDF opened from inside the zip has none either. Keep the folder together.

Some PDF viewers do not follow links to local files. Some viewers drop the part of a link after the question mark, and then a module opens in its default state instead of the state the reading describes. In both cases open README.html in a browser and use the same link in its table below.

This package was built on 2026-10-18.

Python for the scripts

Every script in this folder needs Python 3 with NumPy. Create one virtual environment for them, because a system Python often refuses pip install with the message “externally-managed-environment”. On macOS and Linux:

python3 -m venv cs549-env
source cs549-env/bin/activate
python -m pip install numpy matplotlib

On Windows the commands are py -m venv cs549-env, then cs549-env\Scripts\activate, then the same pip line. On Debian and Ubuntu, python3 -m venv needs the package python3-venv. If a script on Windows stops with a UnicodeEncodeError, set PYTHONUTF8=1 first. The Drake section below adds two packages to the same environment.

What is inside

• chapter-01.pdf is the reading.
• code/reading_example.py is the runnable NumPy example that follows §10 of the reading. Run it from this folder with python code/reading_example.py. It prints the values of the reading’s table of printed lines.
• code/kinematics_note.py is the longer script that the reading names. It reproduces the reading’s main worked numbers and ends with “all frozen numbers reproduced”. Run it with python code/kinematics_note.py --no-figures. Without that flag it also draws two figures of the long reading into fig/ and needs Matplotlib. Its last section, the Panda arm in three dimensions, runs only when the drake package is installed. Otherwise the script says why it skips that section and still checks every other number. The numbers of the Franka Research 3 (FR3) chain come from drake/01c-fr3-grasp-chain/fr3_grasp_chain.py, not from this script.
• code/fk_chain_walkthrough.py prints the factors, intermediate products and coordinate checks of §4.1, which asks you to run it. code/two_link.py is the helper that these scripts import. code/make_figures.py draws Figures 1, 3, 8.2 and C.1 of the reading and one figure of the long reading into fig/; it needs Matplotlib.
• modules/ holds the four browser modules of the browser-module table under “Explore the demonstrations” (page 59 of the reading). Open a module’s index.html in any current browser. No installation is needed. The rotations module needs WebGL, the browser’s 3D graphics. It loads the three.js library from a content delivery network, so it needs an internet connection when it opens. Each module folder has a guide, notes.md, as a Markdown text file.
• drake/ holds the Drake demonstrations of the Drake table (page 60) and their guides, drake/README.md, drake/01c-fr3-grasp-chain/README.md and drake/01b-redundancy-self-motion/panel/notes.md. These demonstrations are optional enrichment. The required parts of the reading do not depend on them.
• fig/ holds the three static pictures that the Drake table names as fallbacks. The figures that the reading credits to Deck 03 are inside the PDF.

Running the Drake demonstrations (optional enrichment)

The Drake demonstrations are optional enrichment. Skip this section unless you want to run them. The Drake scripts need the drake, numpy and scipy packages and a browser for the Meshcat viewer. Drake 1.46.0, the version the course tested, installs only on these systems:

• a Mac with Apple silicon and macOS 15 or newer, with Python 3.12 or 3.13;
• Linux on x86-64 with glibc 2.34 or newer (for example Ubuntu 22.04 or newer), with Python 3.10 to 3.13; the Windows Subsystem for Linux (WSL) counts as Linux here, but the course has not tested it.

It does not install on Python 3.14 or newer, on the macOS system Python 3.9, or on an Intel Mac. Create the environment with a Python in that range, named explicitly:

python3.12 -m venv drake-env
source drake-env/bin/activate
python -m pip install drake==1.46.0 numpy scipy

The course tested these scripts with Drake 1.46.0 and Python 3.12.14 on a Mac with Apple silicon and macOS 26, in print mode. A newer Drake installs only with a newer Python and was not tested with these scripts. The first run of a Panda script downloads Drake’s model files, about 140 MB (170 MB on disk), so it needs an internet connection.

Run a script from this folder, for example python drake/01-fk-jacobian/fk_jacobian_demo.py --meshcat, and open the address it prints. Without --meshcat, a script prints its numbers and exits. Run the fingertip-only script with --app and open the address printed after “Demo app at”. The file drake/01b-redundancy-self-motion/panel/index.html works only while that script serves it. fr3_grasp_chain.py prints Drake warnings about fields of the robot description that Drake ignores; they are expected, and its guide explains them.

About the guides

Each notes.md file under modules/ and drake/ is a short guide that says how to open its demonstration. The scripts in drake/ are the same as in the course materials’ demos/ folder, whose guide (https://oz-oguz.github.io/cs549-materials/demos/) explains the one-time Drake setup. Comments and usage lines in the scripts mention files of the course repository, such as Deck 03’s lecture notes, that are not in this folder; the scripts do not need them.

Addresses that start with /run/

The reading mentions addresses such as /run/self-motion. The lecturer uses them to start a demonstration during the lecture. Run the scripts directly instead, as above.

Files the reading names that are not in this folder, and paths that differ

The links of the reading

Every link below opens the same file as the matching link in the PDF. “IK” is inverse kinematics, and “FR3” is the Franka Research 3 arm.

Requirements in one place