# DepthAI Nodes

## Overview

`depthai-nodes` is an open-source Python library for DepthAI v3 pipelines. It combines inference and parser nodes with host-side
postprocessing, image utilities, and message handling.

The library includes:

 * [Pipeline nodes](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
   for model loading, parser selection, filtering, cropping, and visualization.
 * [Message
   helpers](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message.md) for
   creating native DepthAI messages and grouping results in custom containers.
 * [Runtime
   integrations](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/runtime.md),
   including an ONNX Runtime helper for the OAK4 DSP.

Inference wrappers create native DepthAI nodes internally. The choice of parser implementation and where it runs are separate
concerns; the library is not limited to host-only inference or postprocessing.

Browse the [API
reference](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference.md) for
signatures and configuration options. The [GitHub repository](https://github.com/luxonis/depthai-nodes) contains the source and
examples.

## Installation

The current package requires Python 3.10 or newer and DepthAI 3.9 or newer. Install the published package with:

```bash
python -m pip install depthai-nodes
```

To work from source:

```bash
git clone https://github.com/luxonis/depthai-nodes.git
cd depthai-nodes
python -m pip install -e .
```

## Inference and parser selection

[`ParsingNeuralNetwork`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsing_neural_network.md)
creates a `dai.node.NeuralNetwork` and the native DepthAI parser nodes described by the model's [NN
Archive](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md) heads.

Its `build(input, nnSource, fps=None)` method accepts a camera or an upstream output. For `nnSource`, provide a Model Zoo
reference string, a `dai.NNModelDescription`, or a `dai.NNArchive`. Wrap a local archive path in `dai.NNArchive(path)`; a plain
string is treated as a Model Zoo reference.

Choose the helper that matches your pipeline:

| Helper | Purpose |
| --- | --- |
|
[`ParsingNeuralNetwork`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsing_neural_network.md)
| Inference with native DepthAI parsers selected from archive metadata. |
|
[`HostParsingNeuralNetwork`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_parsing_neural_network.md)
| The same inference wrapper with Python host parsers from `depthai-nodes`. The underlying neural-network node is unchanged. |
|
[`ParserGenerator`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parser_generator.md)
| Create parsers from archive heads when assembling a pipeline yourself. `hostOnly=False` selects native parsers; `hostOnly=True`
selects this package's Python parsers. |
|
[`ExtendedNeuralNetwork`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/extended_neural_network.md)
| Wrap `ParsingNeuralNetwork` with input resizing and coordinate remapping for generic image streams. Currently unsupported on
RVC2. |

Native parsers are not guaranteed to run on the device: execution placement depends on DepthAI, the parser, and the platform.
There is no automatic fallback to a Python parser when a native parser is unavailable; select `HostParsingNeuralNetwork`
explicitly when you need the Python implementation.

For a single-head model, read `nn.out`. For multiple heads, use `nn.getOutput(head_index)` for an individual stream, or
`nn.outputs` for synchronized `dai.MessageGroup` messages keyed by string head indexes such as `"0"` and `"1"`. `nn.out` is only
available for a single head, and `nn.outputs` requires multiple heads. Use `nn.getParser(...)` to access a parser's configuration
methods. See [ParsingNeuralNetwork outputs and
methods](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsing_neural_network.md)
for details.

## Host parsers

The Python parsers can be imported from `depthai_nodes.node` or `depthai_nodes.node.parsers`. They consume neural-network tensors
in `dai.NNData` and emit native DepthAI messages. The archive metadata, tensor names, and tensor shapes must match the selected
parser; a model's task alone does not establish compatibility.

| Parser | Task | Output |
| --- | --- | --- |
|
[`DetectionParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/detection.md)
| Generic bounding boxes and scores | `dai.ImgDetections` |
|
[`YOLOExtendedParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/yolo.md)
| Supported YOLO detection, instance segmentation, and pose variants | `dai.ImgDetections` |
|
[`RFDETRParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/rf_detr.md)
| RF-DETR detection and optional instance masks | `dai.ImgDetections` |
|
[`YuNetParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/yunet.md)
| Face detection | `dai.ImgDetections` |
|
[`SCRFDParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/scrfd.md)
| SCRFD detection | `dai.ImgDetections` |
|
[`MPPalmDetectionParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/mediapipe_palm_detection.md)
| MediaPipe palm detection | `dai.ImgDetections` |
|
[`PPTextDetectionParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/ppdet.md)
| PaddleOCR text detection | `dai.ImgDetections` |
|
[`ClassificationParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/classification.md)
| Class labels and scores | `dai.beta.Classifications` |
|
[`ClassificationSequenceParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/classification_sequence.md)
| Sequence classification, including text recognition | `dai.beta.Classifications` |
|
[`SegmentationParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/segmentation.md)
| Semantic segmentation | `dai.SegmentationMask` |
|
[`FastSAMParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/fastsam.md)
| Prompted segmentation | `dai.SegmentationMask` |
|
[`KeypointParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/keypoints.md)
| 2D or 3D keypoints | `dai.beta.Keypoints` |
|
[`SuperAnimalParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/superanimal_landmarker.md)
| Animal landmarks | `dai.beta.Keypoints` |
|
[`HRNetParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/hrnet.md)
| Body keypoints from heatmaps | `dai.beta.Keypoints` |
|
[`XFeatMonoParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/xfeat.md)
| Feature extraction and matching from one source | `dai.TrackedFeatures` |
|
[`XFeatStereoParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/xfeat.md)
| Feature matching between two sources | `dai.TrackedFeatures` |
|
[`LaneDetectionParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/lane_detection.md)
| UFLD lane points | `dai.beta.Clusters` |
|
[`MLSDParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/mlsd.md)
| Line detection | `dai.beta.Lines` |
|
[`EmbeddingsParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/embeddings.md)
| Embedding tensors | `dai.NNData` |
|
[`RegressionParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/regression.md)
| Regression values | `dai.beta.Predictions` |
|
[`MapOutputParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/map_output.md)
| Numeric maps, such as depth estimates | `dai.beta.Map2D` |
|
[`ImageOutputParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/image_output.md)
| Image-to-image results | `dai.ImgFrame` |

Detection messages can include keypoints or instance masks when supported by the model and parser. XFeat parsers encode matched
point pairs in a `dai.TrackedFeatures` message; consult their API entries for reference-frame selection and input configuration.

## Utility and helper nodes

| Node | Purpose |
| --- | --- |
|
[`ApplyColormap`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_colormap.md)
| Colorize maps and masks into image frames. |
|
[`ApplyDepthColormap`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_depth_colormap.md)
| Colorize depth or disparity with percentile normalization; non-positive values appear black. |
|
[`DepthMerger`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/depth_merger.md)
| Combine detections with aligned depth and device calibration to produce `dai.SpatialImgDetections`. |
|
[`HostSpatialsCalc`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_spatials_calc.md)
| Compute spatial coordinates from depth regions on the host. |
|
[`FrameCropper`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/frame_cropper.md)
| Crop and resize frames using detections or groups of `dai.ImageManipConfig` messages. |
| [`Tiling`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/tiling.md)
| Generate groups of tile configurations for downstream cropping, with runtime configuration updates. |
|
[`ImgFrameOverlay`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_frame_overlay.md)
| Blend two image streams. |
|
[`CoordinatesMapper`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/coordinates_mapper.md)
| Map supported messages from crops or tiles into a target image transformation. |
|
[`ImgDetectionsFilter`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_detections_filter.md)
| Filter detections by label, confidence, or area, with suppression, sorting, and count limits. |
|
[`InstanceToSemanticMask`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/instance_to_semantic_mask.md)
| Convert instance IDs in a mask to detection class labels. |
|
[`GatherData`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/gather_data.md)
| Gather timestamp-matched messages around a reference into `GatheredData`. By default, the expected count comes from the
reference's detections. |
|
[`MessageCollector`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/message_collector.md)
| Batch messages from one stream within half a frame interval into a `Collection`. A newer out-of-window message triggers
emission; there is no final flush when the stream stops. |
|
[`SnapsUploader`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/snaps_uploader.md)
| Upload `SnapData` through the native Luxonis Hub EventsManager, with configurable offline caching. |

To implement custom nodes, use
[`BaseHostNode`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_host_node.md)
for synchronized `process()` callbacks or
[`BaseThreadedHostNode`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_threaded_host_node.md)
for your own `run()` loop.
[`BaseParser`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/base_parser.md)
provides the common neural-network input and parsed-output interface for custom parsers.

## Messages

Parser outputs use native types such as `dai.ImgDetections`, `dai.SegmentationMask`, and the `dai.beta` types listed above. Access
classifications, keypoints, and numeric maps through `dai.beta.Classifications`, `dai.beta.Keypoints`, and `dai.beta.Map2D`,
respectively.

The package provides three custom containers:

| Message | Purpose |
| --- | --- |
|
[`Collection`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/collection.md)
| A collection whose items share one runtime type. |
|
[`GatheredData`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/gathered_data.md)
| A `Collection` with a reference message; assigning the reference copies its timestamps and sequence number. |
|
[`SnapData`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/snap_data.md)
| A snap name, `dai.FileGroup`, optional tags, and string metadata for Luxonis Hub uploads. |

Use [message
creators](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/creators.md)
to construct native messages from arrays, and [message
utilities](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/utils.md)
for copying and detection geometry. Creator functions populate payloads; when emitting messages from a pipeline, also set the
appropriate timestamps, sequence number, and image transformation. Consult [the message
reference](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message.md) for
payload conventions and copy behavior.

## ONNX Runtime on OAK4

[`onnx_qnn_session()`](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/runtime/onnx_qnn.md)
creates an ONNX Runtime session for the OAK4 DSP through the QNN execution provider. It supports compiled-context caching and
configurable CPU fallback. This helper returns an ONNX Runtime session for use outside the DepthAI node graph.

The helper expects a model with static input shapes and the `onnxruntime` variant of `oakapp-base`, which supplies the QNN plugin
and device setup. Installing `depthai-nodes` alone does not provide that environment. See the [ONNX Runtime with QNN
guide](https://docs.luxonis.com/software-v3/ai-inference/inference/onnx-runtime-qnn.md) for setup and usage.