{"id":8081,"library":"depthai","title":"DepthAI Python Library","description":"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.","status":"active","version":"3.5.0","language":"en","source_language":"en","source_url":"https://github.com/luxonis/depthai-core/tree/main/bindings/python","tags":["computer vision","robotics","embedded","camera","AI","OAK","Luxonis"],"install":[{"cmd":"pip install depthai","lang":"bash","label":"Core library"},{"cmd":"pip install depthai[full]","lang":"bash","label":"Full installation (includes OpenCV, blobconverter, etc.)"}],"dependencies":[{"reason":"Commonly used for displaying frames and image processing. Included with `depthai[full]`.","package":"opencv-python","optional":true},{"reason":"Used for converting models to MyriadX blob format for on-device inference. Included with `depthai[full]`.","package":"blobconverter","optional":true}],"imports":[{"note":"The standard convention is to import `depthai` as `dai` for brevity and consistency with examples.","wrong":"import depthai","symbol":"dai","correct":"import depthai as dai"},{"symbol":"Pipeline","correct":"pipeline = dai.Pipeline()"},{"symbol":"Device","correct":"with dai.Device(pipeline) as device:"},{"symbol":"ColorCamera","correct":"camRgb = pipeline.create(dai.node.ColorCamera)"},{"symbol":"XLinkOut","correct":"xoutRgb = pipeline.create(dai.node.XLinkOut)"}],"quickstart":{"code":"import depthai as dai\nimport cv2\n\n# Create pipeline\npipeline = dai.Pipeline()\n\n# Define source and output nodes\ncamRgb = pipeline.create(dai.node.ColorCamera)\nxoutRgb = pipeline.create(dai.node.XLinkOut)\n\nxoutRgb.setStreamName(\"rgb\")\n\n# Properties for ColorCamera\ncamRgb.setPreviewSize(300, 300) # Output resolution for preview stream\ncamRgb.setBoardSocket(dai.CameraBoardSocket.RGB)\ncamRgb.setResolution(dai.ColorCameraProperties.SensorResolution.THE_1080_P)\ncamRgb.setInterleaved(False) # Non-interleaved (separate R, G, B planes)\n\n# Link nodes: camera preview output to XLinkOut input\ncamRgb.preview.link(xoutRgb.input)\n\n# Connect to device and start pipeline\nwith dai.Device(pipeline) as device:\n    print(f\"Connected to OAK-D with MxId: {device.get=}\")\n\n    # Get output queue for the RGB stream\n    qRgb = device.getOutputQueue(name=\"rgb\", maxSize=4, blocking=False)\n\n    while True:\n        inRgb = qRgb.tryGet()\n\n        if inRgb is not None:\n            # Get a NumPy array from the image frame and display it\n            frame = inRgb.getCvFrame()\n            cv2.imshow(\"rgb\", frame)\n\n        # Wait for 'q' key to exit\n        if cv2.waitKey(1) == ord('q'):\n            break\n","lang":"python","description":"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`)."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"Device firmware must be compatible with the installed `depthai` library version. Mismatched firmware can lead to connection issues, unexpected behavior, or errors.","severity":"gotcha","affected_versions":"All"},{"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.","message":"OAK devices have limited processing capabilities and USB bandwidth. Running multiple high-resolution/high-framerate streams or complex neural networks can hit performance limits.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.5.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"The OAK device is not connected, not powered, or there are USB/permissions issues.","error":"RuntimeError: No device found"},{"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.","cause":"This error often indicates using v2.x API calls with a v3.x library, or vice-versa, or an incorrect method name.","error":"AttributeError: 'ColorCamera' object has no attribute 'setPreviewSize'"},{"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.","cause":"The selected camera resolution or framerate is not supported by the specific OAK device model or its sensor.","error":"ValueError: Camera resolution not supported by 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.","cause":"A general XLink communication error, often due to exceeding USB bandwidth, firmware issues, or a malformed pipeline causing a crash on the device.","error":"dai.XLinkError: X_LINK_ERROR"}]}