DepthAI Python Library

3.5.0 · active · verified Thu Apr 16

The `depthai` Python library provides an API to interact with Luxonis OAK (OpenCV AI Kit) devices, enabling users to build sophisticated computer vision and AI applications with on-device processing. It supports various nodes for camera input, neural inference, depth estimation, and data output. The current version is 3.5.0, with a rapid release cadence introducing new features and improvements, often alongside firmware updates.

Common errors

```
RuntimeError: No device found
```
cause The OAK device is not connected, not powered, or there are USB/permissions issues.

fix Ensure the OAK device is properly connected to a USB 3.0 port and powered. Check USB cable integrity. On Linux, ensure correct udev rules are installed (e.g., `curl -fL https://docs.luxonis.com/install_dependencies.sh | bash`).
```
AttributeError: 'ColorCamera' object has no attribute 'setPreviewSize'
```
cause This error often indicates using v2.x API calls with a v3.x library, or vice-versa, or an incorrect method name.

fix If upgrading from v2 to v3, consult the migration guide. For v3.x, instead of `setPreviewSize` for output, use `camRgb.setVideoSize(width, height)` for video stream or `camRgb.setStillSize(width, height)` for still images, or link `camRgb.preview` to an `ImageManip` node for custom scaling.
```
ValueError: Camera resolution not supported by device
```
cause The selected camera resolution or framerate is not supported by the specific OAK device model or its sensor.

fix Refer to your OAK device's specifications for supported resolutions and framerates for each camera sensor. Adjust `camRgb.setResolution()` or `camMono.setResolution()` accordingly. Sometimes, lower framerates might enable higher resolutions.
```
dai.XLinkError: X_LINK_ERROR
```
cause A general XLink communication error, often due to exceeding USB bandwidth, firmware issues, or a malformed pipeline causing a crash on the device.

fix Reduce bandwidth (lower resolution, framerate, or fewer streams). Update device firmware (`python3 -m depthai.auto_update`). Simplify the pipeline to isolate the problematic node or connection. Check logs for more specific errors if available.

Warnings

breaking Major API changes occurred between v2.x and v3.x, impacting pipeline creation, node configuration, and data access. Code written for v2.x is generally not compatible with v3.x.
Fix: Refer to the official DepthAI v2 to v3 migration guide on Luxonis documentation. Key changes include using `pipeline.create(dai.node.NodeName)` for node instantiation and updated setters for node properties (e.g., `setResolution` instead of `setPreviewSize`).
gotcha Device firmware must be compatible with the installed `depthai` library version. Mismatched firmware can lead to connection issues, unexpected behavior, or errors.
Fix: Ensure your OAK device firmware is updated to a compatible version using `python3 -m depthai.auto_update`. Check the release notes for your `depthai` version for recommended firmware.
gotcha OAK devices have limited processing capabilities and USB bandwidth. Running multiple high-resolution/high-framerate streams or complex neural networks can hit performance limits.
Fix: Optimize pipeline design by using lower resolutions/framerate where possible, offloading processing to the host, or leveraging the device's hardware accelerators efficiently. Monitor CPU/memory usage on the device if available.
gotcha The `AutoCalibration` feature (introduced in v3.5.0) can be implicitly enabled via the `DEPTHAI_AUTOCALIBRATION` environment variable (`ON_START` or `CONTINUOUS`), potentially altering device behavior without explicit code.
Fix: Be aware of this environment variable. If unexpected calibration behavior occurs, check if `DEPTHAI_AUTOCALIBRATION` is set in your environment. For explicit control, use the `dai.node.AutoCalibration` node in your pipeline.

Install

pip install depthai Core library
pip install depthai[full] Full installation (includes OpenCV, blobconverter, etc.)

Imports

dai
wrong:
```
import depthai
```
correct:
```
import depthai as dai
```
The standard convention is to import `depthai` as `dai` for brevity and consistency with examples.
Pipeline
```
pipeline = dai.Pipeline()
```
Device
```
with dai.Device(pipeline) as device:
```

ColorCamera

camRgb = pipeline.create(dai.node.ColorCamera)

XLinkOut

xoutRgb = pipeline.create(dai.node.XLinkOut)

Quickstart

This quickstart code initializes a DepthAI pipeline to capture a 1080p color stream from the OAK-D's RGB camera, resizes it to 300x300 for preview, and displays it using OpenCV. Ensure `opencv-python` is installed (`pip install opencv-python`).

import depthai as dai
import cv2

# Create pipeline
pipeline = dai.Pipeline()

# Define source and output nodes
camRgb = pipeline.create(dai.node.ColorCamera)
xoutRgb = pipeline.create(dai.node.XLinkOut)

xoutRgb.setStreamName("rgb")

# Properties for ColorCamera
camRgb.setPreviewSize(300, 300) # Output resolution for preview stream
camRgb.setBoardSocket(dai.CameraBoardSocket.RGB)
camRgb.setResolution(dai.ColorCameraProperties.SensorResolution.THE_1080_P)
camRgb.setInterleaved(False) # Non-interleaved (separate R, G, B planes)

# Link nodes: camera preview output to XLinkOut input
camRgb.preview.link(xoutRgb.input)

# Connect to device and start pipeline
with dai.Device(pipeline) as device:
    print(f"Connected to OAK-D with MxId: {device.get=}")

    # Get output queue for the RGB stream
    qRgb = device.getOutputQueue(name="rgb", maxSize=4, blocking=False)

    while True:
        inRgb = qRgb.tryGet()

        if inRgb is not None:
            # Get a NumPy array from the image frame and display it
            frame = inRgb.getCvFrame()
            cv2.imshow("rgb", frame)

        # Wait for 'q' key to exit
        if cv2.waitKey(1) == ord('q'):
            break

view raw JSON →