Getting Started#

Installation#

System Requirements#

This Developer Preview of the cuMotion library is provided as a set of shared object files and Python wheel files for the following platform configurations.

Platform	Python	CUDA	Tested OS	Download
Jetson Orin	3.10	12.6	JetPack 6.2.1	Latest Release
Jetson Thor	3.12	13.0	JetPack 7.0	Latest Release
x86_64 + NVIDIA GPU (Turing or later)	3.10	12.6	Ubuntu 22.04	Latest Release
x86_64 + NVIDIA GPU (Turing or later)	3.12	13.0	Ubuntu 24.04	Latest Release

Only Linux-based operating systems are supported in the current release.

The software has been tested on Jetson AGX Orin and Jetson AGX Thor but is expected to work on other Jetson Orin configurations (e.g., Jetson Orin NX).

On x86-based computers, an NVIDIA GPU of the Turing generation (e.g., GeForce RTX 2080) or later is required. For optimal performance on Blackwell GPUs (e.g., RTX PRO 6000, GeForce RTX 5080), the CUDA 13 variant of the cuMotion package is recommended. See the CUDA Toolkit Release Notes for details on the minimum GPU driver version required for a given CUDA version.

Basic Installation#

Download the cuMotion package for your desired platform from Releases and extract the contents:

tar xzvf cumotion-<version>-<python_version>-<cuda_version>-<arch>.tar.gz && \
    cd cumotion-<version>-<python_version>-<cuda_version>-<arch>

Python Installation#

To install the Python package, it’s recommended to first create a virtual environment:

python -m venv .venv && \
    source .venv/bin/activate

Then install the cuMotion wheel file found in python_wheels/:

pip install python_wheels/cumotion-*.whl

An optional cumotion_vis package is available for enabling visualization in some of the cuMotion Python examples. It relies on Open3D, which is not easily installable on Jetson, but may be installed on x86 platforms as follows:

pip install python_wheels/cumotion_vis-*.whl

Note

The cumotion_vis Python package provides simple visualization helpers and is not developed to the same standards as the cuMotion library itself. It should be considered unsupported example code, provided for illustration.

Using cuMotion from C++#

A complete set of C++ headers is provided in the include/ directory, alongside shared object files in lib/. The headers make use of the C++17 standard.

cuMotion makes use of the following libraries internally:

yaml-cpp (version 0.7.0)
urdfdom (version 3.0.1)
TinyXML (version 2.6.2)
console_bridge (version 1.0.1)

Please see the NOTICE file for attributions and licenses pertaining to these components.

The only library that must be installed separately is Eigen. Under Debian or Ubuntu, it may be installed as follows:

sudo apt install -y libeigen3-dev

Any development environment and build system may be used to compile and link against cuMotion, but configuration files for use with CMake’s find_package() command are provided for convenience.

If cuMotion is installed in /opt/cumotion/, CMake’s find_package() command should succeed in finding it automatically. If cuMotion is installed in any other location, set the cumotion_ROOT cache variable when configuring your project as follows:

cmake -Dcumotion_ROOT=<full_path_to_cumotion_directory> <other_cmake_args>

Assuming Eigen is installed and the above CMake cache variable is set, adding the following to your CMakeLists.txt should suffice to find the cuMotion library and link against it:

# Find the package
find_package(cumotion)

# Link against the library
target_link_libraries(my_target PRIVATE cumotion::cumotion)

See examples/CMakeLists.txt for a simple example of a CMake project using the cuMotion library.

Running the Examples#

The cuMotion library ships with a handful of examples, meant to illustrate use of the library and verify correct installation.

C++

Use of CMake is recommended. After following the instructions in the section above to install cuMotion and its dependencies, navigate to the examples/ directory and build the examples as follows:

cd examples && \
    cmake -Dcumotion_ROOT=<full_path_to_cumotion_directory> -B build . && \
    cmake --build build

If cuMotion is installed in /opt/cumotion/, this may be simplified as follows:

cd examples && \
    cmake -B build . && \
    cmake --build build

After building the examples, try running one or more of the resulting executables in build/:

cd build && \
    ./franka_trajectory_optimizer_obstacle_example

Note

The C++ examples do not currently provide visualization, but the text output should indicate planning success.

Python

Ensure that the cumotion package is installed in your local environment:

pip show cumotion

Then navigate to the python/examples/ directory:

cd python/examples

And run any of the Python examples, e.g.,

python trajectory_optimizer_examples/franka_trajectory_optimizer_obstacle_example.py

Running the Python Tests#

A set of Python tests is provided in the cuMotion package under python/tests/, where they mainly serve as additional examples of how to use the API. Running the tests can also be useful, however, for validating the system configuration and installation of cuMotion.

After activating the virtual environment where cuMotion is installed, first install the test dependencies as follows:

pip install -r python/tests/requirements.txt

Then run the tests using pytest:

python -m pytest

All tests are expected to pass, but some tests are known to be sensitive to platform-specific differences in floating-point rounding, so a failure does not necessarily indicate a problem.