DepthAI Library

DepthAI library for interfacing with Luxonis DepthAI hardware. It’s written in C++ and offers Python bindings out of the box.

Important — You’re viewing the v3.x.y branch.

• For production projects that still rely on v2, check out the v2_stable branch.
• Need to migrate? Follow the step-by-step v2 → v3 Porting Guide.

Documentation

Documentation is available over at Luxonis DepthAI API

Examples

Examples for both C++ and Python are available in the examples folder. To see how to build and run them see README.md for more information. To build the examples in C++ configure with the following option added:

cmake -S. -Bbuild -D'DEPTHAI_BUILD_EXAMPLES=ON'
cmake --build build

Beta features

The beta namespace is a staging area for experimental DepthAI features. It allows new features to be developed and iterated on quickly before they are promoted to the main depthai namespace.

Beta features are well-developed, but minor API and behavioral changes may occur between DepthAI releases without notice.

In C++, beta nodes are available under dai::beta::node:

auto node = pipeline.create<dai::beta::node::ImgDetectionsFilter>();

In Python, they are available under dai.beta.node:

node = pipeline.create(dai.beta.node.ImgDetectionsFilter)

On-device execution of Beta nodes is supported only on RVC4. If running Beta nodes on RVC2, DepthAI automatically configures beta nodes to run on the host.

Dependencies

• CMake >= 3.20
• C/C++17 compiler
• [Linux] libudev >= 1.0.0
• [optional] OpenCV 4 (required if building examples and for record and replay)
• [optional] PCL (required for point cloud example)

To install libudev on Debian based systems (Ubuntu, etc.): sudo apt install libudev-dev

To install OpenCV: MacOS: brew install opencv Linux: sudo apt install libopencv-dev Windows: choco install opencv

To install PCL: MacOS: brew install pcl Linux: sudo apt install libpcl-dev

Using Python bindings

Installing the latest pre-released version of the library can be done with:

python3 -m pip install --extra-index-url https://artifacts.luxonis.com/artifactory/luxonis-python-release-local/ --pre -U depthai

or by running:

python3 examples/python/install_requirements.py on the branch you want to install

For more specific information about Python bindings, see Python README.

Building

Make sure submodules are updated

git submodule update --init --recursive

Then configure and build

cmake -S . -B build
cmake --build build --parallel [num CPU cores]

On Windows it’s often required to specify the location of the OpenCV installation. In case you used chocolatey to install OpenCV, you can use the following command:

cmake -S . -B build -DOpenCV_DIR=C:/tools/opencv/build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel [num CPU cores]

ℹ️ To speed up build times, use cmake --build build --parallel [num CPU cores].

File truncated at 100 lines see the full file

Changelog for package depthai

3.10.0 (2026-09-07)

## Features

• [_Beta_] Stitching node
  • Stitches frames from two different sensors based on matching features in the overlap of the images
  • Supports two stitching modes:
    • Panorama stitching based on the image overlap
    • Planar projection onto a configurable plane
  • A [panorama example](https://github.com/luxonis/depthai-core/blob/main/examples/python/HostNodes/stitching_panorama.py) and a [planar projection example](https://github.com/luxonis/depthai-core/blob/main/examples/python/HostNodes/stitching_planar_projection.py) are available
• [*RVC4*] Align node
  • A generic way to align [Transformable]{.title-ref} messages or `ImgFrame`s with each other in any order
  • Can align an [ImgFrame]{.title-ref} to any transformable message type
  • Supports transforming custom messages if they override the [transformTo]{.title-ref} function and the node runs on the host. A [Python example](https://github.com/luxonis/depthai-core/blob/main/examples/python/Align/custom_message_align.py) and a [C++ example](https://github.com/luxonis/depthai-core/blob/main/examples/cpp/Align/custom_message_align.cpp) are available
  • [ImgDetections]{.title-ref} alignment is shown in a [C++ example](https://github.com/luxonis/depthai-core/blob/main/examples/cpp/Align/img_detections_align.cpp) and a [Python example](https://github.com/luxonis/depthai-core/blob/main/examples/python/Align/img_detections_align.py)
• Message save and load functions
  • DepthAI messages can be written to a file and then read back with the new API: [msg.save("name.dai")]{.title-ref} and [msg.load("name.dai")]{.title-ref}
  • The saved file is a binary protobuf envelope
  • The following messages are supported: [ImgFrame]{.title-ref}, [NNData]{.title-ref}, [ImgDetections]{.title-ref}, [SpatialImgDetections]{.title-ref}, [SegmentationMask]{.title-ref}, [PointCloudData]{.title-ref}, [RGBDData]{.title-ref}, [IMUData]{.title-ref}, and [ImgAnnotations]{.title-ref}
• [*RVC4*] ToF undistortion
  • [setOutputUndistortion]{.title-ref} lets you undistort the ToF depth frame
• Extrinsics now carry a `toDeviceId` field
  • Used together with [toCameraSocket]{.title-ref} for better transformation handling in multi-device setups
  • The field is automatically populated with the ID of the device that created the message, because that is the device [toCameraSocket]{.title-ref} refers to

## Bug fixes

• [*RVC2*] VideoEncoder checks parameter coherency
  • Unvalidated parameters caused significant performance degradation when rendering a video stream with incorrect parameters
• [RVC2] The LEON OS unwind section now uses the standard [.eh_frame]{.title-ref} naming, so the linker cleans up stale unwind records
• [getMaskData]{.title-ref} bindings for [SpatialImgDetections]{.title-ref} and [ImgDetections]{.title-ref} now return a generic [py::object]{.title-ref}
• Device discovery functions (for example [getAllConnectedDevices]{.title-ref}) now release the GIL, which prevents stuttering of a running pipeline
• Four-point transform in ImageManip now properly handles normalized coordinates
• Rotation is now properly applied to [addCropRotatedRect]{.title-ref} when coordinates are normalized
• Stricter intrinsics matrix validation
• The device health check is now more robust when the device is in use
• DetectionParser only considers outputs with [_yolo]{.title-ref} in the name when validating the number of strides

## Misc

• [RVC4] Optimized the loading of NN models and reduced the RAM footprint by half
• Added a DepthAI-specific reviewer skill for easier development and a faster merge process
• Embedded visualizer updated to 3.9.6:
  • Improved performance and stability

## Known issues

• Downgrading from OS 1.40.0 to any OS between 1.24.0 and 1.31.1 causes an STM flash error that leads to a device crash when running any pipeline. To fix the issue, downgrade to OS 1.35.0 first, before you downgrade to the above OS range

## [RVC4] Luxonis OS compatibility

Integration tested with Luxonis OS 1.30.1, 1.35.0, and 1.40.0.

3.9.0 (2026-08-17)

File truncated at 100 lines see the full file