Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 34 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
![Demo](examples/assets/tutorial_multicamera_edex.gif)


### [ArXiv paper](https://www.arxiv.org/abs/2506.04359) | [Python API](https://nvidia-isaac.github.io/cuVSLAM/python/) | [C++ API](https://nvidia-isaac.github.io/cuVSLAM/cpp/) | [ROS2](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_visual_slam)
### [Latest release](https://github.com/nvidia-isaac/cuVSLAM/releases/latest) | [ArXiv paper](https://www.arxiv.org/abs/2506.04359) | [Python API](https://nvidia-isaac.github.io/cuVSLAM/python/) | [C++ API](https://nvidia-isaac.github.io/cuVSLAM/cpp/) | [ROS2](https://github.com/NVIDIA-ISAAC-ROS/isaac_ros_visual_slam)
Comment thread
vikuznetsov-nvidia marked this conversation as resolved.

## Overview

Expand Down Expand Up @@ -73,6 +73,9 @@ To use cuVSLAM in a ROS2 environment:
- [cuVSLAM Technical Report](https://www.arxiv.org/abs/2506.04359)
- [PyCuVSLAM API Documentation](https://nvidia-isaac.github.io/cuVSLAM/python/)
- [cuVSLAM C++ API Documentation](https://nvidia-isaac.github.io/cuVSLAM/cpp/)
- Version-matched offline API documentation is available as `cuvslam-docs-<version>.tar.gz` on the
[latest release](https://github.com/nvidia-isaac/cuVSLAM/releases/latest). Extract it and open
`python/index.html` or `cpp/index.html`.

# Performance

Expand Down Expand Up @@ -107,19 +110,27 @@ PyCuVSLAM is the Python wrapper (bindings) for the cuVSLAM library.
Pre-built wheels are available on the [cuVSLAM releases page](https://github.com/nvidia-isaac/cuVSLAM/releases)
for the following configurations:

| Ubuntu | Python | CUDA | Architectures |
|--------|--------|------|---------------|
| 22.04 | 3.10 | 12, 13 | x86_64, aarch64 |
| 24.04+ | 3.12+ | 12, 13 | x86_64, aarch64 |
| Target | Ubuntu | Python wheel tag | CUDA wheel tag | Architecture |
|--------|--------|------------------|----------------|--------------|
| Desktop/server | 22.04 | `cp310` (Python 3.10) | `cu12`, `cu13` | x86_64 |
| Desktop/server | 24.04 | `cp312-abi3` (Python 3.12+) | `cu12`, `cu13` | x86_64 |
| Jetson Orin | 22.04 (JetPack 6.x) | `cp310` (Python 3.10) | `cu12` | aarch64 |
| Jetson Thor | 24.04 (JetPack 7.x) | `cp312-abi3` (Python 3.12+) | `cu13` | aarch64 |

**Prerequisite**: [CUDA Toolkit 12 or 13](https://developer.nvidia.com/cuda/toolkit) must be installed separately (not included in the wheels).
Only the combinations listed above are provided as pre-built wheels. The `cp312-abi3` wheels use Python's stable ABI
and are compatible with Python 3.12 and later. Other Python, CUDA, or Jetson combinations require an
[installation from source](#install-from-source).

**Prerequisite**: [CUDA Toolkit 12 or 13](https://developer.nvidia.com/cuda/toolkit) must be installed separately
(not included in the wheels). Its major version must match the wheel's `cu12` or `cu13` tag.

Official wheels include cuNLS support for `Multisensor` mode; no separate cuNLS installation is required.

To install (virtual environment is recommended):

1. Go to the [releases page](https://github.com/nvidia-isaac/cuVSLAM/releases).
2. Download the wheel matching your CUDA version (`cu12` or `cu13`), Python version, and platform (`x86_64` or `aarch64`).
1. Go to the [latest release](https://github.com/nvidia-isaac/cuVSLAM/releases/latest).
2. Download the wheel matching the table above. On Jetson, also match the device family: Orin uses `cu12`/`cp310`;
Thor uses `cu13`/`cp312-abi3`.
3. Install with pip:

```bash
Expand All @@ -144,8 +155,18 @@ CUVSLAM_BUILD_DIR=<path-to-cuvslam-build> pip install python/

## Pre-built Libraries

Pre-built C++ libraries are available on the [releases page](https://github.com/nvidia-isaac/cuVSLAM/releases)
for Ubuntu 22.04/24.04 on x86_64 and Jetson(aarch64) with CUDA 12 and CUDA 13.
Pre-built C++ SDK archives are available on the
[latest release](https://github.com/nvidia-isaac/cuVSLAM/releases/latest):

| Target | Ubuntu | CUDA | Archive slug |
|--------|--------|------|--------------|
| Desktop/server | 22.04 or 24.04 | 12.6.3 or 13.2.0 | `x86_64-cuda<version>-ubuntu<version>` |
| Jetson Orin | 22.04 (JetPack 6.x) | 12.6.3 | `orin-cuda12.6.3-ubuntu22.04` |
| Jetson Thor | 24.04 (JetPack 7.x) | 13.0.1 | `thor-cuda13.0.1-ubuntu24.04` |

The desktop/server row represents four archives covering both Ubuntu versions with both listed CUDA versions. Select
the archive matching your target, Ubuntu version, and CUDA version. Each archive contains `bin/libcuvslam.so`,
`bin/cuvslam_api_launcher`, and the public headers under `include/cuvslam/`.

For Python usage, [pre-built wheels](#install-from-wheels) are the recommended approach.

Expand Down Expand Up @@ -266,8 +287,9 @@ RERUN=1 ctest --output-on-failure

**Q**: What Python versions are supported by PyCuVSLAM?

**A**: Pre-built wheels are available for Python 3.10 (Ubuntu 22.04) and Python 3.12 or later (Ubuntu 24.04+).
When built from source, PyCuVSLAM supports Python 3.9 and later.
**A**: Pre-built wheels use `cp310` for Python 3.10 on Ubuntu 22.04 and `cp312-abi3` for Python 3.12 or later on
Ubuntu 24.04. Jetson wheels are limited to Orin with `cu12`/`cp310` and Thor with `cu13`/`cp312-abi3`; see the
[wheel table](#install-from-wheels). When built from source, PyCuVSLAM supports Python 3.9 and later.


# Troubleshooting
Expand Down
23 changes: 12 additions & 11 deletions TROUBLESHOOTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
## Overview

This document describes how to troubleshoot cuVSLAM when the system is installed and runs successfully but the computed
pose is not sufficiently accurate. For installation or build issues, see the relevant sections of the documentation.
pose is not sufficiently accurate. For installation or build issues, see
[Install PyCuVSLAM](README.md#install-pycuvslam) and [Build cuVSLAM](README.md#build-cuvslam).

![Troubleshooting](doc/images/troubleshooting.png)

Expand Down Expand Up @@ -88,7 +89,7 @@ cuvslam::Odometry::Config::debug_dump_directory
**Python API**

```python
Odometry.Config.debug_dump_directory
cuvslam.core.Odometry.Config.debug_dump_directory
```

See [Python API Reference](https://nvidia-isaac.github.io/cuVSLAM/python/api.html#cuvslam.core.Odometry.Config.debug_dump_directory).
Expand Down Expand Up @@ -360,7 +361,7 @@ cuvslam::Odometry::Config::rectified_stereo_camera
**Python API**

```python
cuvslam.Odometry.Config.rectified_stereo_camera
cuvslam.core.Odometry.Config.rectified_stereo_camera
```

See [Python API Reference](https://nvidia-isaac.github.io/cuVSLAM/python/api.html#cuvslam.core.Odometry.Config.rectified_stereo_camera).
Expand Down Expand Up @@ -431,7 +432,7 @@ cuvslam::Odometry::Config::use_denoising
**Python API**

```python
Odometry.Config.use_denoising
cuvslam.core.Odometry.Config.use_denoising
```

See [Python API Reference](https://nvidia-isaac.github.io/cuVSLAM/python/api.html#cuvslam.core.Odometry.Config.use_denoising).
Expand All @@ -452,12 +453,12 @@ Mono → RGBD → Stereo Inertial → Stereo → Multicamera; Multisensor depend

Multisensor (see [examples/multisensor/](examples/multisensor/README.md)) does not slot at a fixed
position — its accuracy scales with the sensor set it is given. It requires at least one RGB-D
camera or one overlapping camera pair and currently supports pinhole cameras only. A single
RGB-D + IMU rig is roughly RGBD-class. A multi-stereo + RGB-D + IMU rig may approach or exceed
Multicamera under favorable conditions, but this is an empirical expectation rather than a
guarantee; benchmark the actual rig and environment. Use Multisensor when you have a
mixed-camera-type rig or want IMU fusion on a non-stereo configuration; otherwise prefer the mode
that exactly matches your rig.
camera or one overlapping camera pair, a cuNLS-enabled build, and currently supports pinhole cameras only. Official
release wheels include cuNLS. Multisensor is experimental and may be inaccurate or fail for some sensor configurations
and scenes. A single RGB-D + IMU rig is roughly RGBD-class. A multi-stereo + RGB-D + IMU rig may approach or exceed
Multicamera under favorable conditions, but this is an empirical expectation rather than a guarantee; benchmark the
actual rig and environment. Use Multisensor when you have a mixed-camera-type rig or want IMU fusion on a non-stereo
configuration; otherwise prefer the mode that exactly matches your rig.

### Adjust motion prediction

Expand All @@ -476,7 +477,7 @@ cuvslam::Odometry::Config::use_motion_model
**Python API**

```python
Odometry.Config.use_motion_model
cuvslam.core.Odometry.Config.use_motion_model
```

See [Python API Reference](https://nvidia-isaac.github.io/cuVSLAM/python/api.html#cuvslam.core.Odometry.Config.use_motion_model).
Expand Down
15 changes: 10 additions & 5 deletions cuvslam-skills/cuvslam-onboard/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,12 +48,17 @@ Once the user provides a path, use it consistently throughout all subsequent com

## 2. Install PyCuVSLAM (Quickest Path)

Pre-built wheels from https://github.com/nvidia-isaac/cuVSLAM/releases:
Pre-built wheels from https://github.com/nvidia-isaac/cuVSLAM/releases/latest:

| Ubuntu | Python | CUDA | Arch |
|--------|--------|------|------|
| 22.04 | 3.10 | 12, 13 | x86_64, aarch64 |
| 24.04+ | 3.12+ | 12, 13 | x86_64, aarch64 |
| Target | Ubuntu | Python wheel tag | CUDA wheel tag | Arch |
|--------|--------|------------------|----------------|------|
| Desktop/server | 22.04 | `cp310` (Python 3.10) | `cu12`, `cu13` | x86_64 |
| Desktop/server | 24.04 | `cp312-abi3` (Python 3.12+) | `cu12`, `cu13` | x86_64 |
| Jetson Orin | 22.04 (JetPack 6.x) | `cp310` (Python 3.10) | `cu12` | aarch64 |
| Jetson Thor | 24.04 (JetPack 7.x) | `cp312-abi3` (Python 3.12+) | `cu13` | aarch64 |

Only these combinations are provided. The installed CUDA major must match the wheel's `cu12` or `cu13` tag; use a
source build for other combinations.
Comment thread
vikuznetsov-nvidia marked this conversation as resolved.

```bash
python3 -m venv .venv && source .venv/bin/activate
Expand Down
8 changes: 6 additions & 2 deletions cuvslam-skills/cuvslam-troubleshoot/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,11 @@ cmake -S . -B build && cmake --build build --parallel $(nproc)
```

### PyCuVSLAM install
Pre-built wheels: https://github.com/nvidia-isaac/cuVSLAM/releases
Pre-built wheels: https://github.com/nvidia-isaac/cuVSLAM/releases/latest

- x86_64: Ubuntu 22.04 / Python 3.10 has `cu12` and `cu13`; Ubuntu 24.04 / Python 3.12+ has `cu12` and `cu13`.
- Jetson Orin: Ubuntu 22.04 / Python 3.10 / `cu12` only.
- Jetson Thor: Ubuntu 24.04 / Python 3.12+ / `cu13` only.

From source (after building C++ lib):
```bash
Expand All @@ -51,7 +55,7 @@ CUVSLAM_BUILD_DIR=<path-to-build> pip install python/
- **Missing CUDA**: Set `CUDAToolkit_ROOT=/usr/local/cuda` or install CUDA Toolkit
- **git-lfs not installed**: `apt install git-lfs && git lfs pull` (binary test data)
- **CMake too old**: Need 3.19+
- **Wheel ABI mismatch**: Match Python version (3.10 for Ubuntu 22.04, 3.12+ for 24.04)
- **Wheel ABI mismatch**: Match the Python tag, CUDA major, architecture, and Jetson family using the matrix above.

## Tracking Issues

Expand Down
2 changes: 1 addition & 1 deletion examples/multisensor/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ RGB-D cameras (`lcam_front`, `lcam_back`) plus a synthetic IMU from the

## Requirements

- Use an official wheel or build with `USE_CUNLS=ON`.
- Use an official release wheel, which includes cuNLS, or build from source with `USE_CUNLS=ON`.
- Configure at least one RGB-D camera in `depth_camera_ids`, or provide at least one camera pair with overlapping
frustums. A single RGB-D camera is valid, with or without an IMU.
- Use pinhole cameras. Other camera models are not supported by the current solver.
Expand Down
5 changes: 3 additions & 2 deletions examples/realsense/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,5 +121,6 @@ For a stereo + IMU multisensor smoke test using the same IR streams as the stere
python3 run_vio.py
```

> **Note:** Multisensor mode requires a cuNLS-enabled PyCuVSLAM build. The default source build enables cuNLS; if
> cuVSLAM was configured with `-DUSE_CUNLS=OFF`, these multisensor examples are unavailable.
> **Note:** Multisensor mode requires a cuNLS-enabled PyCuVSLAM build. Official release wheels include cuNLS, and the
> default source build enables it. If cuVSLAM was configured with `-DUSE_CUNLS=OFF`, these multisensor examples are
> unavailable.
2 changes: 1 addition & 1 deletion python/docs/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Tracker class
.. autoclass:: Tracker
:members:
:undoc-members:
:exclude-members: save_map, localize_in_map, OdometryMode, MulticameraMode
:exclude-members: OdometryMode, MulticameraMode

Functions
---------
Expand Down
2 changes: 1 addition & 1 deletion python/docs/index.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Welcome to PyCuVSLAM API documentation!
=======================================

PyCuVSLAM is a Python bindings for the cuVSLAM (CUDA-accelerated Visual SLAM) library.
PyCuVSLAM provides Python bindings for the cuVSLAM (CUDA-accelerated Visual SLAM) library.

.. toctree::
:maxdepth: 2
Expand Down
Loading