diff --git a/README.md b/README.md index f790cf0..e746380 100644 --- a/README.md +++ b/README.md @@ -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) ## Overview @@ -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-.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 @@ -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 @@ -144,8 +155,18 @@ CUVSLAM_BUILD_DIR= 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-ubuntu` | +| 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. @@ -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 diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index dc93f31..a8af6c3 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -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) @@ -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). @@ -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). @@ -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). @@ -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 @@ -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). diff --git a/cuvslam-skills/cuvslam-onboard/SKILL.md b/cuvslam-skills/cuvslam-onboard/SKILL.md index 316d8ed..848532a 100644 --- a/cuvslam-skills/cuvslam-onboard/SKILL.md +++ b/cuvslam-skills/cuvslam-onboard/SKILL.md @@ -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. ```bash python3 -m venv .venv && source .venv/bin/activate diff --git a/cuvslam-skills/cuvslam-troubleshoot/SKILL.md b/cuvslam-skills/cuvslam-troubleshoot/SKILL.md index 9683c70..64a3825 100644 --- a/cuvslam-skills/cuvslam-troubleshoot/SKILL.md +++ b/cuvslam-skills/cuvslam-troubleshoot/SKILL.md @@ -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 @@ -51,7 +55,7 @@ CUVSLAM_BUILD_DIR= 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 diff --git a/examples/multisensor/README.md b/examples/multisensor/README.md index 3580430..05a2e8d 100644 --- a/examples/multisensor/README.md +++ b/examples/multisensor/README.md @@ -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. diff --git a/examples/realsense/README.md b/examples/realsense/README.md index 3692bf9..e52c8a8 100644 --- a/examples/realsense/README.md +++ b/examples/realsense/README.md @@ -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. diff --git a/python/docs/api.rst b/python/docs/api.rst index eb58052..bfca42f 100644 --- a/python/docs/api.rst +++ b/python/docs/api.rst @@ -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 --------- diff --git a/python/docs/index.rst b/python/docs/index.rst index bcc06bc..e302afc 100644 --- a/python/docs/index.rst +++ b/python/docs/index.rst @@ -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