Getting Started#

Installation#

System Requirements#

The current release of the cuMotion library is provided as a shared library and Python wheel files for both Linux and Windows on x86-based computers, as well Jetson Orin, Jetson Thor, and DGX Spark.

Under Linux, the library is compatible with GCC 11.4 and later (corresponding to libstdc++ symbol version GLIBCXX_3.4.30). It has been tested on Ubuntu 22.04 and 24.04.
Under Windows, the library is compatible with the Visual Studio 2019 toolchain and later.
On both platforms, Python wheel files are provided for all actively-supported Python versions at the time of release, currently consisting of Python 3.10 through 3.14, inclusive.

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). The Jetson Thor (CUDA 13.0) package has also been optimized for and tested on DGX Spark.

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.

Linux#

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

Microsoft Windows#

Platform	CUDA	Tested OS	Download
x86_64 + NVIDIA GPU (Turing or later)	13.0	Windows 11	Latest Release

Basic Installation#

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

Linux

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

export CUMOTION_ROOT=$(pwd)

Windows

Extract the archive (.zip file) and navigate to the extracted directory.

$env:CUMOTION_ROOT = $(pwd)

Python Installation#

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

Linux

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

Windows

python -m venv .venv
.venv\Scripts\activate

Then install the cuMotion wheel file found in python_wheels/ that corresponds to your Python version. As an example, the “Python tag” for Python 3.12 is cp312, and the corresponding wheel may be installed as follows:

Linux

pip install python_wheels/cumotion-*-cp312-*.whl

Windows

pip install (Get-Item python_wheels/cumotion-*-cp312-*.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 or DGX Spark, but may be installed on x86 platforms as follows:

Linux

pip install python_wheels/cumotion_vis-*.whl

Windows

pip install (Get-Item 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 the cuMotion shared library: lib/libcumotion.so on Linux, or bin\cumotion.dll and lib\cumotion.lib on Windows. The headers make use of the C++17 standard.

cuMotion uses 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.

Linux

Under Debian or Ubuntu, it may be installed as follows:

sudo apt install -y libeigen3-dev

Windows

Download the source for Eigen 3.4.0, extract it, and then build and install. Since Eigen is a header-only library, this simply copies the headers and generates the CMake configuration files:

cd eigen-3.4.0
cmake -B build -DCMAKE_INSTALL_PREFIX=<eigen_install_path>
cmake --build build --target install

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.

Linux

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:

cmake -Dcumotion_ROOT=$CUMOTION_ROOT <other_cmake_args>

Windows

Set the cumotion_ROOT and Eigen3_ROOT cache variables when configuring your project:

cmake -Dcumotion_ROOT=$env:CUMOTION_ROOT -DEigen3_ROOT=<eigen_install_path> <other_cmake_args>

With Eigen and the CMake cache variables configured as described above, 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.

Linux

cd examples && \
    cmake -Dcumotion_ROOT=$CUMOTION_ROOT -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

Windows

cd examples
cmake -Dcumotion_ROOT=$env:CUMOTION_ROOT -DEigen3_ROOT=<eigen_install_path> -B build .
cmake --build build --config Release

If the above command fails to find the CUDA compiler, the following, more explicit variant may help:

cmake -Dcumotion_ROOT=$env:CUMOTION_ROOT -DEigen3_ROOT=<eigen_install_path> -DCUDA_PATH=$CUDA_PATH -B build .

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

build\Release\franka_trajectory_optimizer_obstacle_example.exe

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

Install the dependencies for the examples:

pip install -r requirements.txt

Visualization for the examples can be enabled by adding the following optional dependency:

Linux

pip install ../../python_wheels/cumotion_vis-*.whl

Windows

pip install (Get-Item ../../python_wheels/cumotion_vis-*.whl)

Note

The cumotion_vis package is only supported on x86 platforms, in a desktop environment (e.g. no SSH forwarding), and with Python versions 3.10-3.12.

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.