# DepthAI 节点

## 概述

在 DepthAI 管线中，消息 用于在 节点 之间传递信息。 虽然 DepthAI 原生支持多种消息和节点类型，但某些用例需要额外的 Host 端组件来进行后处理、过滤、可视化或更高级的管线组合。

depthai-nodes 是一个开源的 Python 库，提供用于 DepthAI v3 管线的 Host 端节点和消息类型。 它通过解析器、实用程序和辅助节点扩展了标准 DepthAI 工作流，这些节点在主机上运行，同时与管线的其余部分保持兼容。

该库包含两个主要模块：

 * node：Host 端管线组件
 * message：用于这些组件的更丰富的消息类型

更多示例和包级文档，请参阅 [GitHub 仓库](https://github.com/luxonis/depthai-nodes) 和 [API
参考](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/api-reference.md)。

## 安装

depthai-nodes 需要 Python 3.10 或更高版本，并设计用于 depthai v3 管线。

从 PyPI 安装：

```bash
pip install depthai-nodes
```

如果希望从源码构建，克隆仓库并本地安装：

```bash
git clone git@github.com:luxonis/depthai-nodes.git
cd depthai-nodes
pip install .
```

## 模块

### Node

node 模块提供了一系列自定义节点对象，扩展了标准 DepthAI 节点的功能。 这些节点分为 解析器、实用程序 和 辅助 类别。

#### 典型工作流

对于大多数 AI 用例，ParsingNeuralNetwork 是主要入口点。 它会创建底层的 NeuralNetwork 节点以及所选模型所需的解析器节点。 模型来源可以是 Luxonis Models 引用、本地 [NN
存档](https://docs.luxonis.com/software-v3/ai-inference/nn-archive.md) 或 dai.NNModelDescription。

相关辅助工具包括：

 * HostParsingNeuralNetwork：同一工作流的 Host 端版本
 * ParserGenerator：当需要从 NN 存档生成解析器节点时使用

#### 解析器

解析器节点用于解释 AI 模型的输出。 其主要目的是封装和抽象后处理逻辑，使用户能够直接与清晰、结构化的输出进行交互。 根据解析器的不同，输出可以是标准 DepthAI 消息（如 dai.ImgDetections、dai.TrackedFeatures 或
dai.ImgFrame），也可以是自定义的 depthai_nodes.message 类型。

以下是可用解析器节点的概述，包括对应任务和使用示例。 我们仅列出少量示例，更多示例可在 [Luxonis Models](https://models.luxonis.com/) 上找到。 有关每个解析器的详细信息，请参阅
[解析器节点文档](https://github.com/luxonis/depthai-nodes/tree/main/depthai_nodes/node#parser-nodes)。

| 解析器 | 任务 | 使用示例 |
| --- | --- | --- |
| `YOLOExtendedParser` | 目标检测 | [YOLOv8 实例分割
Nano](https://models.luxonis.com/luxonis/yolov8-instance-segmentation-nano/9c1ea8c4-7ab4-46d2-954b-de237c7b4a05), [YOLOv8 Nano
姿态估计](https://models.luxonis.com/luxonis/yolov8-nano-pose-estimation/12acd8d7-25c0-4a07-9dff-ab8c5fcae7b1) |
| `YuNetParser` | 目标检测 | [YuNet](https://models.luxonis.com/luxonis/yunet/5d635f3c-45c0-41d2-8800-7ca3681b1915) |
| `SCRFDParser` | 目标检测 | [SCRFD
行人检测](https://models.luxonis.com/luxonis/scrfd-person-detection/c3830468-3178-4de6-bc09-0543bbe28b1c) |
| `MPPalmDetectionParser` | 目标检测 | [MediaPipe
手掌检测](https://models.luxonis.com/luxonis/mediapipe-palm-detection/9531aba9-ef45-4ad3-ae03-808387d61bf3) |
| `PPTextDetectionParser` | 目标检测 | [Paddle
文本检测](https://models.luxonis.com/luxonis/paddle-text-detection/131d855c-60b1-4634-a14d-1269bb35dcd2) |
| `ClassificationParser` | 分类 |
[EfficientNet-Lite](https://models.luxonis.com/luxonis/efficientnet-lite/fdacd30d-97f4-4c55-843f-8b7e872d8acb) |
| `ClassificationSequenceParser` | 分类 | [Paddle
文本识别](https://models.luxonis.com/luxonis/paddle-text-recognition/9ae12b58-3551-49b1-af22-721ba4bcf269) |
| `SegmentationParser` | 分割 |
[DeepLab-V3-Plus](https://models.luxonis.com/luxonis/deeplab-v3-plus/1189a661-fd0a-44fd-bc9e-64b94d60cb49) |
| `FastSAMParser` | 分割 | [FastSAM s](https://models.luxonis.com/luxonis/fastsam-s/4af2416c-2ba4-4c85-97d0-fd26f089fc69) |
| `KeypointParser` | 关键点检测 | [MediaPipe
手部地标](https://models.luxonis.com/luxonis/mediapipe-hand-landmarker/42815cca-deab-4860-b4a9-d44ebbe2988a) |
| `SuperAnimalParser` | 关键点检测 | [SuperAnimal
地标检测](https://models.luxonis.com/luxonis/superanimal-landmarker/894cf1a2-23fb-4c96-8944-a0d1be38a7c7) |
| `HRNetParser` | 关键点检测 | [Lite-HRNet](https://models.luxonis.com/luxonis/lite-hrnet/c7c9e353-9f6d-43e1-9b45-8edeae82db70) |
| `XFeatMonoParser` | 特征匹配 | [XFeat](https://models.luxonis.com/luxonis/xfeat/6c2790a1-bf68-4e89-a4b3-5c9ae68183b5) |
| `XFeatStereoParser` | 特征匹配 | [XFeat](https://models.luxonis.com/luxonis/xfeat/6c2790a1-bf68-4e89-a4b3-5c9ae68183b5) |
| `LaneDetectionParser` | 其他 |
[超快速车道检测](https://models.luxonis.com/luxonis/ultra-fast-lane-detection/b15d067f-2cde-48a0-85bf-52e1174b1ac0) |
| `MLSDParser` | 其他 | [M-LSD](https://models.luxonis.com/luxonis/m-lsd/9e3e01d8-2303-4113-bf69-cb10ec56ad5b) |
| `EmbeddingsParser` | 其他 | [ArcFace](https://models.luxonis.com/luxonis/arcface/e24a577e-e2ff-4e4f-96b7-4afb63155eac) |
| `RegressionParser` | 其他 | [头部姿态估计](https://models.luxonis.com/luxonis/head-pose-estimation/068ac18a-de71-4a6e-9f0f-42776c0ef980)
|
| `MapOutputParser` | 其他 | [Depth Anything
V2](https://models.luxonis.com/luxonis/depth-anything-v2/c5bf9763-d29d-4b10-8642-fbd032236383) |
| `ImageOutputParser` | 其他 | [Zero-DCE](https://models.luxonis.com/luxonis/zero-dce/8eaae754-6195-4766-a39c-2d19a856a492) |

#### 工具与辅助节点

该组包含旨在协助常见任务的节点，例如数据处理、过滤和管道管理。 它还包含作为构建自定义节点实现模板的抽象基节点。

以下是可用工具与辅助节点的简要概述，以及它们对应的任务和用途说明。
您可以在[工具与辅助节点文档](https://github.com/luxonis/depthai-nodes/tree/main/depthai_nodes/node#utility--helper-nodes)中找到关于每个节点的更多信息。

| 节点 | 任务 | 用途 |
| --- | --- | --- |
| `BaseHostNode` | 抽象类 | 主机节点基类 |
| `BaseThreadedHostNode` | 抽象类 | 多线程主机节点基类 |
| `ApplyColormap` | 图像处理 | 应用颜色映射 |
| `ApplyDepthColormap` | 图像处理 | 应用基于百分位归一化的深度或视差着色 |
| `DepthMerger` | 图像处理 | 合并深度与检测结果 |
| `FrameCropper` | 图像处理 | 从检测结果或上游 manip-config 组中裁剪并调整图像区域大小 |
| `ImgFrameOverlay` | 图像处理 | 叠加两张图像 |
| `Tiling` | 图像处理 | 生成平铺的 `dai.ImageManipConfig` 组，用于下游裁剪管道 |
| `ExtendedNeuralNetwork` | 神经网络处理 | 针对模型动物园和神经网络存档源，围绕 `dai.node.NeuralNetwork` 的便捷封装 |
| `ParsingNeuralNetwork` | 神经网络处理 | 为给定模型创建 `NeuralNetwork` 节点及相关解析器 |
| `HostParsingNeuralNetwork` | 神经网络处理 | 主机端 `ParsingNeuralNetwork` 实现 |
| `ParserGenerator` | 神经网络处理 | 从给定的神经网络存档生成解析器 |
| `CoordinatesMapper` | 检测与过滤 | 针对支持的消息，在图像变换空间之间重新映射坐标 |
| `HostSpatialsCalc` | 检测与过滤 | 使用深度数据和校准信息计算主机端空间坐标 |
| `ImgDetectionsFilter` | 检测与过滤 | 过滤检测消息 |
| `InstanceToSemanticMask` | 检测与过滤 | 将实例 ID 掩码转换为语义掩码 |
| `GatherData` | 数据管理 | 将多条消息合并为一条 |
| `MessageCollector` | 数据管理 | 收集来自同一数据流中具有相同时间戳的消息，组成单个集合 |
| `SnapsUploader` | 云集成 | 将 `SnapData` 消息上传至 Luxonis Hub 事件 API |

### 消息

message 模块提供了一组自定义消息类型，扩展了标准的 DepthAI 消息。 这些自定义类型使得处理各种 AI 模型的输出并将其集成到可视化或处理管道中更加容易。

以下是库中当前实现的消息类型快速概览。
有关字段级别的详细信息，请参阅[消息类型文档](https://github.com/luxonis/depthai-nodes/tree/main/depthai_nodes/message#message-types)和[API
参考](https://docs.luxonis.com/software-v3/ai-inference/inference/depthai-nodes/api-reference.md)。

| 消息类型 | 存储内容 |
| --- | --- |
| `Classifications` | 带有概率分数的对象类别标签 |
| `Cluster` | 一组相关点 |
| `Clusters` | 多个 `Cluster` 对象 |
| `Collection` | 消息或其他同类型项的类型化集合 |
| `GatheredData` | 参考数据以及为该参考收集的消息 |
| `Keypoints` | 关键点，以及可选的骨架边 |
| `Line` | 带有置信度的线条坐标 |
| `Lines` | 多个 `Line` 对象 |
| `Map2D` | 二维浮点数组 |
| `Prediction` | 单浮点数值 |
| `Predictions` | 多个 `Prediction` 对象 |
| `SegmentationMask` | 二维整数数组 |
| `SnapData` | 单个快照事件，包含文件、标签和用于 Luxonis Hub 上传的额外元数据 |