此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 概述
  • 安装
  • 推理和解析器选择
  • 主机解析器
  • 实用程序和辅助节点
  • 消息
  • OAK4 上的 ONNX Runtime
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包

DepthAI 节点

最后更新

概述

depthai-nodes 是一个用于 DepthAI v3 管道的开源 Python 库。它结合了推理和解析器节点,以及主机端后处理、图像实用程序和消息处理。该库包括:
  • 管道节点,用于模型加载、解析器选择、过滤、裁剪和可视化。
  • 消息助手,用于创建原生 DepthAI 消息并将结果分组到自定义容器中。
  • 运行时集成,包括用于 OAK4 DSP 的 ONNX Runtime 助手。
推理封装器在内部创建原生 DepthAI 节点。解析器实现的选择及其运行位置是独立的问题;该库不限于仅主机推理或后处理。浏览 API 参考 以获取签名和配置选项。 GitHub 存储库包含源代码和示例。

安装

当前软件包需要 Python 3.10 或更高版本和 DepthAI 3.9 或更高版本。使用以下命令安装已发布的软件包:
Command Line
1python -m pip install depthai-nodes
从源代码工作:
Command Line
1git clone https://github.com/luxonis/depthai-nodes.git
2cd depthai-nodes
3python -m pip install -e .

推理和解析器选择

ParsingNeuralNetwork 创建一个 dai.node.NeuralNetwork 和模型 NN Archive 头描述的原生 DepthAI 解析器节点。它的 build(input, nnSource, fps=None) 方法接受一个摄像头或上游输出。对于 nnSource,提供一个模型动物园引用字符串、一个 dai.NNModelDescription 或一个 dai.NNArchive。将本地存档路径封装在 dai.NNArchive(path) 中;纯字符串被视为模型动物园引用。选择与您的管道匹配的助手:
助手用途
ParsingNeuralNetwork使用从存档元数据中选择的原生 DepthAI 解析器进行推理。
HostParsingNeuralNetwork相同的推理封装器,带有来自 depthai-nodes 的 Python 主机解析器。底层神经网络节点保持不变。
ParserGenerator在自行组装管道时从存档头创建解析器。hostOnly=False 选择原生解析器;hostOnly=True 选择此包的 Python 解析器。
ExtendedNeuralNetwork将 ParsingNeuralNetwork 与输入大小调整和坐标重映射结合,用于通用图像流。目前在 RVC2 上不支持。
原生解析器不保证在设备上运行:执行位置取决于 DepthAI、解析器和平台。当原生解析器不可用时,不会自动回退到 Python 解析器;当您需要 Python 实现时,请明确选择 HostParsingNeuralNetwork。对于单头模型,读取 nn.out。对于多头模型,使用 nn.getOutput(head_index) 获取单个流,或使用 nn.outputs 获取以字符串头索引(例如 "0" 和 "1")为键的同步 dai.MessageGroup 消息。nn.out 仅适用于单头模型,而 nn.outputs 需要多头模型。使用 nn.getParser(...) 访问解析器的配置方法。有关详细信息,请参阅 ParsingNeuralNetwork 输出和方法。

主机解析器

Python 解析器可以从 depthai_nodes.node 或 depthai_nodes.node.parsers 导入。它们以 dai.NNData 形式消耗神经网络张量并发出原生 DepthAI 消息。存档元数据、张量名称和张量形状必须与所选解析器匹配;模型的任务本身并不能确定兼容性。
解析器任务输出
DetectionParser通用边界框和分数dai.ImgDetections
YOLOExtendedParser支持的 YOLO 检测、实例分割和姿态变体dai.ImgDetections
RFDETRParserRF-DETR 检测和可选实例掩码dai.ImgDetections
YuNetParser人脸检测dai.ImgDetections
SCRFDParserSCRFD 检测dai.ImgDetections
MPPalmDetectionParserMediaPipe 手掌检测dai.ImgDetections
PPTextDetectionParserPaddleOCR 文本检测dai.ImgDetections
ClassificationParser类别标签和分数dai.beta.Classifications
ClassificationSequenceParser序列分类,包括文本识别dai.beta.Classifications
SegmentationParser语义分割dai.SegmentationMask
FastSAMParser提示分割dai.SegmentationMask
KeypointParser2D 或 3D 关键点dai.beta.Keypoints
SuperAnimalParser动物地标dai.beta.Keypoints
HRNetParser热图中的身体关键点dai.beta.Keypoints
XFeatMonoParser从一个源进行特征提取和匹配dai.TrackedFeatures
XFeatStereoParser两个源之间的特征匹配dai.TrackedFeatures
LaneDetectionParserUFLD 车道点dai.beta.Clusters
MLSDParser线检测dai.beta.Lines
EmbeddingsParser嵌入张量dai.NNData
RegressionParser回归值dai.beta.Predictions
MapOutputParser数字地图,例如深度估计dai.beta.Map2D
ImageOutputParser图像到图像的结果dai.ImgFrame
检测消息可以包含关键点或实例掩码,如果模型和解析器支持。XFeat 解析器将匹配的点对编码到 dai.TrackedFeatures 消息中;请查阅其 API 条目以了解参考帧选择和输入配置。

实用程序和辅助节点

节点用途
ApplyColormap将地图和掩码着色为图像帧。
ApplyDepthColormap使用百分位归一化对深度或视差进行着色;非正值显示为黑色。
DepthMerger将检测与对齐的深度和设备校准结合,生成 dai.SpatialImgDetections。
HostSpatialsCalc在主机上从深度区域计算空间坐标。
FrameCropper使用检测或 dai.ImageManipConfig 消息组裁剪和调整帧大小。
Tiling生成用于下游裁剪的瓦片配置组,并支持运行时配置更新。
ImgFrameOverlay混合两个图像流。
CoordinatesMapper将支持的消息从裁剪或瓦片映射到目标图像变换。
ImgDetectionsFilter按标签、置信度或面积过滤检测,支持抑制、排序和计数限制。
InstanceToSemanticMask将掩码中的实例 ID 转换为检测类别标签。
GatherData将时间戳匹配的消息围绕参考收集到 GatheredData 中。默认情况下,预期计数来自参考的检测。
MessageCollector在半帧间隔内将一个流中的消息批量收集到 Collection 中。较新的超出窗口消息会触发发送;当流停止时没有最终刷新。
SnapsUploader通过原生 Luxonis Hub EventsManager 上传 SnapData,支持可配置的离线缓存。
要实现自定义节点,请使用 BaseHostNode 进行同步 process() 回调,或使用 BaseThreadedHostNode 进行您自己的 run() 循环。 BaseParser 为自定义解析器提供了通用的神经网络输入和解析输出接口。

消息

解析器输出使用原生类型,例如 dai.ImgDetections、dai.SegmentationMask 和上面列出的 dai.beta 类型。通过 dai.beta.Classifications、dai.beta.Keypoints 和 dai.beta.Map2D 分别访问分类、关键点和数字地图。该软件包提供了三个自定义容器:
消息用途
Collection包含相同运行时类型项的集合。
GatheredData带有参考消息的 Collection;分配参考会复制其时间戳和序列号。
SnapData快照名称、dai.FileGroup、可选标签和用于 Luxonis Hub 上传的字符串元数据。
使用 消息创建器 从数组构造原生消息,并使用 消息实用程序 进行复制和检测几何。创建器函数填充有效负载;在从管道发出消息时,还要设置适当的时间戳、序列号和图像变换。请查阅 消息参考 以了解有效负载约定和复制行为。

OAK4 上的 ONNX Runtime

onnx_qnn_session() 通过 QNN 执行提供程序为 OAK4 DSP 创建 ONNX Runtime 会话。它支持编译上下文缓存和可配置的 CPU 回退。此助手返回一个 ONNX Runtime 会话,用于 DepthAI 节点图之外。该助手需要一个具有静态输入形状的模型和 oakapp-base 的 onnxruntime 变体,它提供 QNN 插件和设备设置。单独安装 depthai-nodes 不提供该环境。请参阅 ONNX Runtime with QNN 指南 以了解设置和使用。