# node

Python API: `depthai_nodes.node`

Pipeline nodes for inference, postprocessing, and host-side message handling.

Create nodes with `pipeline.create(...)` and connect their input and output ports. The classes in this package integrate native
DepthAI inference and parsers with Python postprocessing, image utilities, and custom message handling.

Table of Contents

Contents

 * [Inference and parser
   selection](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
 * [Host parser
   catalogue](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md) *
   [Object
   detection](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
    * [Classification and
      segmentation](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
    * [Keypoints and feature
      matching](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
    * [Other
      outputs](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
 * [Utility nodes](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
   * [Image and depth
   processing](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
    * [Detection
      processing](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
    * [Message handling and
      uploads](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)
 * [Extending the
   package](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node.md)

## 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)
builds a neural network and the native DepthAI parsers specified by an NN Archive. It exposes parser output through `out` and
`getOutput()` and the underlying network's passthrough streams.
[HostParsingNeuralNetwork](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_parsing_neural_network.md)
offers the same interface with the Python parser implementations from this package.
[ExtendedNeuralNetwork](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/extended_neural_network.md)
adds input resizing and optional coordinate remapping around `ParsingNeuralNetwork`.

[ParserGenerator](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parser_generator.md)
creates parsers from NN Archive head metadata. Its `hostOnly=False` default selects native DepthAI parsers; `hostOnly=True`
selects this package's implementations. This flag selects the implementation, not the device on which it executes. Native parser
placement also depends on DepthAI and the device platform. On RVC2, this package reports that non-detection native parsers and
detection parsers with mask outputs run on the host. Most native parsers are in `dai.beta.node`; detection and segmentation
parsers are in `dai.node`.

`ParsingNeuralNetwork` accepts an archive object, a Model Zoo reference, or a `dai.NNModelDescription` through `nnSource`. For a
local archive, construct `dai.NNArchive(path)` first. `ExtendedNeuralNetwork` accepts the same source forms through `nnSource`.
See
[ParsingNeuralNetwork.build](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsing_neural_network.md)
and
[ExtendedNeuralNetwork.build](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/extended_neural_network.md)
for accepted inputs and configuration.

> **Example**
> Build native segmentation inference from a Model Zoo reference:

```text
import depthai as dai
from depthai_nodes.node import ParsingNeuralNetwork

with dai.Pipeline() as pipeline:
    camera = pipeline.create(dai.node.Camera).build()
    nn = pipeline.create(ParsingNeuralNetwork).build(
        camera,
        nnSource="luxonis/mediapipe-selfie-segmentation:256x144",
    )
    results = nn.out.createOutputQueue()
    pipeline.start()
    mask = results.get()
```

Replace `ParsingNeuralNetwork` with `HostParsingNeuralNetwork` to select the host parser implementation.

## Host parser catalogue

Host parsers consume `dai.NNData` and emit native DepthAI messages. Model metadata must match the parser's expected tensor names
and shapes. All parsers in this catalogue can be imported from either `depthai_nodes.node` or `depthai_nodes.node.parsers`.

### Object detection

 * [DetectionParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/detection.md):
   generic bounding-box and score tensors.
 * [YOLOExtendedParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/yolo.md):
   supported YOLO detection, pose, and instance segmentation variants.
 * [YuNetParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/yunet.md)
   and
   [SCRFDParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/scrfd.md):
   face detection.
 * [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.
 * [PPTextDetectionParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/ppdet.md):
   PaddleOCR text detection.
 * [RFDETRParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/rf_detr.md):
   RF-DETR detections and optional instance masks.

These parsers emit `dai.ImgDetections` with the fields supported by the model.

### Classification and segmentation

 * [ClassificationParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/classification.md):
   class names and scores in `dai.beta.Classifications`.
 * [ClassificationSequenceParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/classification_sequence.md):
   per-step classifications, including text recognition, in `dai.beta.Classifications`.
 * [SegmentationParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/segmentation.md):
   semantic masks in `dai.SegmentationMask`.
 * [FastSAMParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/fastsam.md):
   prompted segmentation in `dai.SegmentationMask`.

### Keypoints and feature matching

 * [KeypointParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/keypoints.md):
   2D or 3D keypoint tensors.
 * [HRNetParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/hrnet.md):
   body keypoints from heatmaps.
 * [SuperAnimalParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/superanimal_landmarker.md):
   animal landmarks from heatmaps.

These keypoint parsers emit `dai.beta.Keypoints`.
[XFeatMonoParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/xfeat.md)
emits `dai.TrackedFeatures` from one source;
[XFeatStereoParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/xfeat.md)
matches features between two sources and emits paired `dai.TrackedFeatures`.

### Other outputs

 * [LaneDetectionParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/lane_detection.md):
   UFLD lane points in `dai.beta.Clusters`.
 * [MLSDParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/mlsd.md):
   line detections in `dai.beta.Lines`.
 * [EmbeddingsParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/embeddings.md):
   passes through `dai.NNData` embedding outputs.
 * [RegressionParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/regression.md):
   regression values in `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, including depth estimates, in `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 in `dai.ImgFrame`.

## Utility nodes

### Image and depth processing

 * [ApplyColormap](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_colormap.md):
   colorizes 2D maps and masks into `dai.ImgFrame` messages.
 * [ApplyDepthColormap](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_depth_colormap.md):
   uses percentile normalization for depth or disparity; non-positive values are excluded from normalization and displayed as
   black.
 * [DepthMerger](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/depth_merger.md):
   combines 2D detections and aligned depth into `dai.SpatialImgDetections` using device calibration.
 * [HostSpatialsCalc](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_spatials_calc.md):
   computes 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):
   crops and resizes frames using detections or groups of `dai.ImageManipConfig` messages, emitting one frame per crop.
 * [Tiling](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/tiling.md):
   produces tiled `dai.ImageManipConfig` groups and accepts runtime configuration changes.
 * [ImgFrameOverlay](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_frame_overlay.md):
   blends two `dai.ImgFrame` streams.

### Detection processing

 * [CoordinatesMapper](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/coordinates_mapper.md):
   maps supported messages from crops or tiles into a target image transformation, including map and mask pixels.
 * [ImgDetectionsFilter](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_detections_filter.md):
   filters native detections by label, confidence, or area, with optional 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):
   replaces instance IDs with detection class labels.

> **Example**
> With an existing pipeline and detection-producing `nn.out` stream:

```text
from depthai_nodes.node import ImgDetectionsFilter

filtered = pipeline.create(ImgDetectionsFilter).build(nn.out)
filtered.keepLabels([0]).minConfidence(0.5).sortByConfidence().takeFirstK(10)
```

This keeps class 0 detections, orders them by descending confidence, and retains at most ten. `rejectLabels([0])` excludes class 0
instead.

### Message handling and uploads

 * [GatherData](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/gather_data.md):
   collects a configurable number of timestamp-matched messages per reference into
   [depthai_nodes.message.GatheredData](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/gathered_data.md).
   The default count is the number of detections in the reference message.
 * [MessageCollector](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/message_collector.md):
   batches messages within half a frame interval into
   [depthai_nodes.message.Collection](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/collection.md),
   emitting when a newer timestamp falls outside the matching window.
 * [SnapsUploader](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/snaps_uploader.md):
   accepts
   [depthai_nodes.message.SnapData](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/message/snap_data.md)
   and delegates uploads and optional offline caching to the native EventsManager.

## Extending the package

[BaseHostNode](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_host_node.md)
supplies platform-specific image formats and logging for synchronized `process()` callbacks.
[BaseThreadedHostNode](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_threaded_host_node.md)
provides the same setup for nodes with their own `run()` loop.
[BaseParser](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers/base_parser.md)
defines the common NNData input and parsed-message output interface.

Parser implementations separate tensor extraction, array computation, and message emission. Document tensor layouts and coordinate
conventions on the processing helper and preserve input metadata when emitting results.

## Child Pages

 * [parsers](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsers.md)
 * [utils](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/utils.md)
 * [apply_colormap](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_colormap.md)
 * [apply_depth_colormap](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/apply_depth_colormap.md)
 * [base_host_node](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_host_node.md)
 * [base_threaded_host_node](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/base_threaded_host_node.md)
 * [coordinates_mapper](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/coordinates_mapper.md)
 * [depth_merger](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/depth_merger.md)
 * [extended_neural_network](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/extended_neural_network.md)
 * [frame_cropper](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/frame_cropper.md)
 * [gather_data](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/gather_data.md)
 * [host_parsing_neural_network](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_parsing_neural_network.md)
 * [host_spatials_calc](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/host_spatials_calc.md)
 * [img_detections_filter](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_detections_filter.md)
 * [img_frame_overlay](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/img_frame_overlay.md)
 * [instance_to_semantic_mask](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/instance_to_semantic_mask.md)
 * [message_collector](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/message_collector.md)
 * [parser_generator](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parser_generator.md)
 * [parsing_neural_network](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/parsing_neural_network.md)
 * [snaps_uploader](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/snaps_uploader.md)
 * [tiling](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/depthai-nodes-api-reference/node/tiling.md)