You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This package lets you use the ZED stereo camera in Python 3. The Python API is a wrapper around the ZED SDK which is written in C++ optimized code. We make the ZED SDK accessible from external Python code using Cython.
4
4
5
+
## Table of Contents
6
+
7
+
-[Getting started](#getting-started)
8
+
-[Prerequisites](#prerequisites)
9
+
-[Installing the Python API](#installing-the-python-api)
10
+
-[Running the install script](#running-the-install-script)
11
+
-[Use the plugin](#use-the-plugin)
12
+
-[Code](#code)
13
+
-[Run the tutorials](#run-the-tutorials)
14
+
-[Run the examples](#run-the-examples)
15
+
-[GPU data retrieval using CuPy](#GPU-data-retrieval-using-CuPy)
16
+
-[Validate your CuPy setup](#validate-your-CuPy-setup)
-["PyTorch on Jetson requiring NumPy 1.x while pyzed requires NumPy 2.x"](#pytorch-on-jetson-requiring-numpy-1x-while-pyzed-requires-numpy-2x)
20
+
-["CuPy failed to load libnvrtc.so.1x"](#cupy-failed-to-load-libnvrtc-so1x)
21
+
-[Compiling the Python API from source (only for developers of the python wrapper)](#compiling-the-python-api-from-source-only-for-developers-of-the-python-wrapper)
22
+
-[Support](#support)
23
+
5
24
## Getting started
6
25
7
26
- First, download the latest version of the ZED SDK on [stereolabs.com](https://www.stereolabs.com/developers)
8
27
- For more information, read the ZED [Documentation](https://www.stereolabs.com/docs/app-development/python/install/) and [API documentation](https://www.stereolabs.com/docs/api/python/) or our [Community page](https://community.stereolabs.com)
9
28
10
29
### Prerequisites
11
30
12
-
To start using the ZED SDK in Python, you will need to install the following dependencies on your system:
13
-
14
-
-[ZED SDK 5.0](https://www.stereolabs.com/developers/) and its dependency [CUDA](https://developer.nvidia.com/cuda-downloads)
15
-
16
-
For the ZED SDK 4.2 compatible version, use the [zedsdk_4.X branch](https://github.com/stereolabs/zed-python-api/tree/zedsdk_4.X) or the [4.2 release tag](https://github.com/stereolabs/zed-python-api/releases/tag/v4.2)
17
-
18
-
- Python 3.8+ x64
19
-
-[Cython >= 3.0.0](http://cython.org/#download)
20
-
-[Numpy >= 2.0](https://numpy.org/install/)
21
-
- OpenCV Python (optional)
22
-
- PyOpenGL (optional)
31
+
To start using the ZED SDK in Python, you will need to install the following dependencies on your system:
32
+
33
+
- To use pyzed
34
+
-[ZED SDK 5.1](https://www.stereolabs.com/developers/) and its dependency [CUDA](https://developer.nvidia.com/cuda-downloads)
35
+
- For the ZED SDK 5.0 compatible version, use the [zedsdk_5.X branch](https://github.com/stereolabs/zed-python-api/tree/zedsdk_5.X) or the [5.0.7 release tag](https://github.com/stereolabs/zed-python-api/releases/tag/v5.0.7)
36
+
- For the ZED SDK 4.2 compatible version, use the [zedsdk_4.X branch](https://github.com/stereolabs/zed-python-api/tree/zedsdk_4.X) or the [4.2 release tag](https://github.com/stereolabs/zed-python-api/releases/tag/v4.2)
37
+
- Python 3.8+ x64
38
+
-[Cython >= 3.0.0](http://cython.org/#download)
39
+
-[Numpy >= 2.0](https://numpy.org/install/)
40
+
- To use most of our samples (optional)
41
+
- OpenCV Python
42
+
- PyOpenGL
43
+
- To profit from the GPU acceleration and getting the data on the GPU (optional)
44
+
-[CuPy](https://cupy.dev/)
23
45
24
46
Please check your python version with the following command. The result should be 3.8 or higher.
25
47
@@ -91,8 +113,7 @@ Import the packages in your Python terminal or file like this:
91
113
import pyzed.sl as sl
92
114
```
93
115
94
-
Vectors operations like norm, sum, square, dot, cross, distance but also simple operations can be done with
95
-
Numpy package.
116
+
Vectors operations like norm, sum, square, dot, cross, distance but also simple operations can be done with numpy package on CPU or CuPy package on GPU.
96
117
97
118
### Run the tutorials
98
119
@@ -102,6 +123,85 @@ The [tutorials](https://github.com/stereolabs/zed-examples/tree/master/tutorials
102
123
103
124
Please refer to the [examples](https://github.com/stereolabs/zed-examples) README for more informations.
104
125
126
+
## GPU data retrieval using CuPy
127
+
128
+
`CuPy` is a NumPy/SciPy-compatible Array Library for GPU-accelerated Computing with Python (see https://cupy.dev/) and the ZED Python API support getting data in its format.
129
+
130
+
Calling `mat.get_data(sl.MEM_GPU, deep_copy=False)` on a `sl.Mat` object will give you a `cupy.ndarray` object.
131
+
132
+
### Validate your CuPy setup
133
+
134
+
**Prerequisites**:
135
+
- A plugged camera
136
+
- pyzed
137
+
- [Numpy >= 2.0](https://numpy.org/install/)
138
+
- [CuPy](https://cupy.dev/) (corresponding to your CUDA version)
139
+
140
+
You can use script the script `cupy/test_cupy_integration.py`. The script will:
141
+
- Open a connected ZED camera.
142
+
- Retrieve an image.
143
+
- Run some operations and benchmark on the retrieved image.
144
+
- Display on the terminal the results of the tests.
145
+
146
+
Without deep-diving into the script content, you can just look at what it prints to validate everything is fine with your setup.
147
+
148
+
For example, on an Orin NX16 with a ZED X
149
+
150
+
```
151
+
> python test_cupy_integration.py
152
+
✅ CuPy detected - GPU acceleration available
153
+
CuPy version: 13.5.1
154
+
CUDA version: 12080
155
+
ZED SDK CuPy Integration Test
156
+
========================================
157
+
Opening ZED camera...
158
+
[2025-07-31 12:54:15 UTC][ZED][INFO] Logging level INFO
159
+
[2025-07-31 12:54:16 UTC][ZED][INFO] Using GMSL input... Switched to default resolution HD1200
160
+
[2025-07-31 12:54:19 UTC][ZED][INFO] [Init] Camera FW version: 2001
161
+
[2025-07-31 12:54:19 UTC][ZED][INFO] [Init] Video mode: HD1200@30
162
+
[2025-07-31 12:54:19 UTC][ZED][INFO] [Init] Serial Number: S/N 48922857
### "PyTorch on Jetson requiring NumPy 1.x while pyzed requires NumPy 2.x"
226
+
227
+
By default, PyTorch on Jetson requires NumPy 1.x (see NVidia's doc [Install PyTorch on Jetson Platform](https://docs.nvidia.com/deeplearning/frameworks/install-pytorch-jetson-platform/index.html)). Since pyzed requires NumPy 2.x, it can lead to:
228
+
229
+
```
230
+
A module that was compiled using NumPy 1.x cannot be run in
231
+
NumPy 2.2.6 as it may crash. To support both 1.x and 2.x
232
+
versions of NumPy, modules must be compiled with NumPy 2.0.
233
+
Some module may need to rebuild instead e.g. with 'pybind11>=2.12'.
234
+
235
+
If you are a user of the module, the easiest solution will be to
236
+
downgrade to 'numpy<2' or try to upgrade the affected module.
237
+
We expect that some modules will need time to support NumPy 2.
238
+
```
239
+
240
+
To fix this, until NVidia releases its wheels for PyTorch on Jetson with NumPy 2.x, you can either:
241
+
- compile PyTorch from source with NumPy 2.x: see [this post](https://forums.developer.nvidia.com/t/pytorch-environment-and-zed-sdk-conflicts-on-jetpack-6-2/334056/5) for more information.
242
+
- compile pyzed from source with NumPy 1.x: see [zed-python-api/src](https://github.com/stereolabs/zed-python-api/tree/master/src) for more information.
243
+
244
+
### "CuPy failed to load libnvrtc.so.1x"
245
+
246
+
If an __error__ like `CuPy failed to load libnvrtc.so.12` happens when using GPU retrieval, it indicates a mismatch between the installed CuPy version (e.g. cupy-cuda11x) and the CUDA runtime libraries (e.g. 12.x)
125
247
126
248
## Compiling the Python API from source (only for developers of the python wrapper)
0 commit comments