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

本页目录

  • 一般逻辑
  • 如何放置
  • 输入和输出
  • 后端选择
  • 配置
  • FPS 和分辨率推断
  • 内省
  • 深度对齐
  • 用法
  • 重用现有相机
  • RVC4 AUTO 分辨率参考
  • 高级后端调优
  • 功能示例
  • 参考
Claude CodeCodexCursor
Luxonis 智能体工具包为你常用的编程智能体加载 Luxonis 上下文与技能,更快地基于 OAK 开发应用。
安装工具包
最后更新
Supported on:RVC2RVC4
深度旨在统一和简化您从 Luxonis 深度感知设备获取深度的方式——涵盖 RVC2、RVC4 和未来所有 Luxonis 平台。一个节点,一个 API:创建 Depth,请求深度图(以及伴随的置信度图),然后让 Depth 处理其余部分。您不再需要了解设备上的哪些传感器最适合深度,如何组合它们,哪种算法适合您的硬件,何时神经深度优于经典立体深度,或者哪个预设与哪个后端配对。Depth 抽象了这些选择——它选择最佳传感器或传感器组合、匹配的后端以及适合您的设备和约束的正确配置,然后为您连接图。在每个设备上,Depth 从可用的深度感知硬件开始——立体对、ToF 传感器或两者——并通过适合的后端进行路由。在底层,这可能解析为 StereoDepth、NeuralDepth、NeuralAssistedStereo、GPUStereo 或 ToF。Depth 还通过相同的 API 通过 setAlignTo() 处理深度对齐。Depth 还会告诉您它选择了什么。连接后,getResolvedAlgorithm() 和 getResolvedConfig() 返回自动选择的算法和配置——检查它们,保存以备后用,或者如果您喜欢结果,可以在下次运行时明确固定它们。该读数也是您了解底层后端的地图:当您需要对过滤器、预设或模型设置进行更精细的控制时,使用解析值直接使用 StereoDepth、NeuralDepth 或匹配节点构建管道,而无需通过 Depth。请参阅 内省 和 高级后端调优。

一般逻辑

Depth 旨在开箱即用,无需用户输入——创建节点,它会为您的设备选择最佳传感器、后端和配置。您还可以传递一些基本约束,例如 FPS 和分辨率,Depth 会处理内部传感器和算法选择以满足这些约束。当您固定 FPS 时,Depth 会将输出速率精确保持在您请求的值。输出分辨率可能与您请求的不同:每个后端都有原生和支持的大小,Depth 会为您的目标选择最合适的配置文件。Depth 本身包含深度图所在的分辨率和坐标系的所有信息,因此下游 DepthAI 节点可以直接摄取它。

如何放置

Python

Python
1import depthai as dai
2
3with dai.Pipeline() as pipeline:
4    depth = pipeline.create(dai.node.Depth)
5    depthQueue = depth.depth.createOutputQueue()

C++

C++
1#include <depthai/depthai.hpp>
2
3dai::Pipeline pipeline;
4auto depth = pipeline.create<dai::node::Depth>();
5auto depthQueue = depth->depth().createOutputQueue();

输入和输出

Depth 暴露了两个公共输出。传感器节点在内部获取——节点发现设备第一个立体对上的现有 Camera 节点和 ToF 传感器节点,并在底层创建任何缺失的传感器节点,包括 ToF。
  • depth — 来自活动后端的深度图。当使用 setAlignTo() 时,此输出与目标图像对齐。
  • confidence — 来自活动后端的置信度图。保持在后端原生参考系中(未对齐)。对于 ToF 后端,这是振幅。
没有公共图输入端口。在首次访问输出之前使用 setAlignTo() 将深度与另一个相机输出(例如,彩色流)对齐。

后端选择

使用 Algorithm.AUTO(默认),Depth 会根据您的目标 FPS 和立体分辨率选择设备可以运行的最佳后端。
算法底层节点平台注意事项
STEREOStereoDepth所有始终可用作基线。
NEURALNeuralDepthRVC4模型从设备模型目录中自动选择。
NEURAL_ASSISTED_STEREONeuralAssistedStereoRVC4立体 + 神经辅助。
GPU_STEREOGPUStereoRVC4需要带 GPU 的设备。
TOFToF所有需要连接 ToF 传感器。
AUTO 的平台默认值:
  • RVC4 — 按优先级顺序扫描后端:NeuralDepth → NeuralAssistedStereo → StereoDepth → GPUStereo,匹配 FPS 和分辨率约束。
  • 其他平台 — 连接 ToF 传感器时使用 ToF;否则使用 StereoDepth。

配置

所有配置必须在首次访问 depth 或 confidence 输出之前进行。使用 build() 设置 FPS、分辨率、算法和配置:
API效果
build(fps=None)仅设置目标立体 FPS(AUTO 算法)。
build(algorithm, fps=None, stereo_size=None)设置算法和可选的 FPS / 立体帧大小。
build(algorithm, config, fps=None, stereo_size=None)固定算法和配置。algorithm 不能是 AUTO。
您还可以使用单独的设置器:setAlgorithm()、setConfig() 和 setAlignTo()。配置类型(algorithm → 接受的配置):
  • NEURAL → DeviceModelZoo(例如 NEURAL_DEPTH_SMALL)
  • STEREO → StereoDepth.PresetMode(例如 DEFAULT)
  • NEURAL_ASSISTED_STEREO、GPU_STEREO、TOF → 无配置(None / std::monostate)

FPS 和分辨率推断

FPS 和分辨率按以下顺序独立推断:
  1. 显式 build() 参数(fps、stereo_size)
  2. 第一个立体对上现有的左右 Camera 节点(匹配请求的输出大小)
  3. 设备默认值(30 FPS;来自相机功能的分辨率)
如果 FPS 和分辨率都已固定但没有后端可以同时满足两者,则 Depth 节点会抛出错误。否则,FPS 保持在请求的值,并且输出分辨率从所选后端最合适的原生或支持的配置文件中选择——这可能与您请求的大小不同。

内省

Getter返回
getRequestedAlgorithm()您设置的算法(默认 AUTO)。
getRequestedConfig()您固定的配置,如果自动则为 None。
getResolvedAlgorithm()实际连接的算法(首次访问 depth 后有效)。
getResolvedConfig()实际使用的配置(首次访问 depth 后有效)。
要重现 AUTO 选择,请在一次运行后读取解析值,并在后续运行中将其固定到第二个节点:
Python
1# 第一次运行:解析并保存值
2resolved_algorithm = depth.getResolvedAlgorithm()
3resolved_config = depth.getResolvedConfig()
4
5# 后续运行:在新 Depth 节点上重用它们
6depth = pipeline.create(dai.node.Depth)
7depth.build(resolved_algorithm, resolved_config)

深度对齐

在首次访问输出之前调用 setAlignTo(),将深度输出与另一个图像源(例如,彩色相机输出)对齐。只有 depth 对齐;confidence 保持在后端帧中。Depth 自动选择对齐路径:
平台 / 后端对齐路径
RVC2 + STEREOStereoDepth 原生 (inputAlignTo)
RVC2 + 其他后端主机 ImageAlign
RVC4(所有后端)设备上 ImageAlign
Python
1colorOut = colorCam.requestOutput((1280, 800))
2depth.setAlignTo(colorOut)

用法

Python

Python
1import depthai as dai
2
3with dai.Pipeline() as pipeline:
4    # 零配置 AUTO — 设备的最佳后端
5    depth = pipeline.create(dai.node.Depth)
6
7    # 受限 AUTO
8    # depth.build(fps=30, stereo_size=(640, 400))
9
10    # 固定后端,自动配置
11    # depth.build(dai.node.Depth.Algorithm.STEREO)
12
13    # 完全显式
14    # depth.build(
15    #     dai.node.Depth.Algorithm.NEURAL,
16    #     dai.DeviceModelZoo.NEURAL_DEPTH_SMALL,
17    #     fps=30,
18    # )
19
20    depthQueue = depth.depth.createOutputQueue()
21    confidenceQueue = depth.confidence.createOutputQueue()
22
23    pipeline.build()
24    print("Resolved:", depth.getResolvedAlgorithm(), depth.getResolvedConfig())
25
26    pipeline.start()
27    while pipeline.isRunning():
28        depthFrame = depthQueue.get()
29        # 处理 depthFrame

C++

C++
1#include <depthai/depthai.hpp>
2
3dai::Pipeline pipeline;
4auto depth = pipeline.create<dai::node::Depth>();
5
6// 固定后端,自动配置
7// depth->build(dai::node::Depth::Algorithm::STEREO);
8
9auto depthQueue = depth->depth().createOutputQueue();
10auto confidenceQueue = depth->confidence().createOutputQueue();
11
12pipeline.build();
13std::cout << "Resolved algorithm: " << static_cast<int>(depth->getResolvedAlgorithm()) << std::endl;
14
15pipeline.start();
16while(pipeline.isRunning()) {
17    auto depthFrame = depthQueue->get<dai::ImgFrame>();
18    // 处理 depthFrame
19}

重用现有相机

如果您在设备的第一个立体对上已经有左右 Camera 节点,Depth 会重用它们并匹配它们的大小和 FPS。您的相机将保留在 Depth 的子树之外。
Python
1left = pipeline.create(dai.node.Camera).build(stereoPair.left, (640, 400), 30)
2right = pipeline.create(dai.node.Camera).build(stereoPair.right, (640, 400), 30)
3
4depth = pipeline.create(dai.node.Depth)  # 从相机推断 640x400 @ 30

RVC4 AUTO 分辨率参考

在功能齐全的 RVC4 设备上(所有后端可用,完整的 NeuralDepth 模型目录),AUTO 大致按以下方式解析常见的(分辨率,FPS)组合。NEURAL 行使用张量覆盖带(模型原生大小的 ≈ ±√2);其他后端使用简单的最大分辨率上限。FPS 门限为 targetFps × 0.9。
分辨率 5 FPS 15 FPS 30 FPS 60 FPS
320×240 NEURAL 384X240 NEURAL 384X240 NEURAL 384X240 NEURAL 384X240
480×300 NEURAL 576X360 NEURAL 576X360 NEURAL 576X360 NEURAL 480X300
640×400 NEURAL 864X540 NEURAL 864X540 NEURAL 576X360 NEURAL 480X300
640×480 NEURAL 864X540 NEURAL 864X540 NEURAL 576X360 NEURAL 480X300
960×600 NEURAL 1056X660 NEURAL 960X600 NEURAL_ASSISTED_STEREO NEURAL_ASSISTED_STEREO
1280×720 NEURAL 1248X780 NEURAL 960X600 NEURAL_ASSISTED_STEREO NEURAL_ASSISTED_STEREO
1280×800 NEURAL 1248X780 NEURAL 960X600 NEURAL_ASSISTED_STEREO NEURAL_ASSISTED_STEREO
1920×1080 GPU_STEREO GPU_STEREO* GPU_STEREO* GPU_STEREO*
2592×1944 GPU_STEREO GPU_STEREO* GPU_STEREO* GPU_STEREO*
* — 没有配置文件在该分辨率下满足 FPS 门限,因此 AUTO 会放弃 FPS 门限,并选择具有最高可用 FPS(GPU_STEREO,约 5 FPS)的适合分辨率的配置文件。这些是尽力而为的,不保证达到请求的 FPS。如果 NeuralDepth 或 NeuralAssistedStereo 不可用,NEURAL/NAS 单元格会回退到 STEREO(按 FPS 预设:当所需 FPS ≤ 16 时为 DEFAULT,否则当所需 FPS ≤ 30 时为 FAST_ACCURACY/FAST_DENSITY),受 StereoDepth 的 1280×1280 上限限制。如果 GPUStereo 不可用,高分辨率行会回退到最后的 STEREO FAST_ACCURACY(超出 StereoDepth 上限的分辨率会尽力而为)。

高级后端调优

Depth 不会暴露每个后端的每个调优旋钮。对于高级配置,请固定特定后端并使用专用节点文档:有关深度精度指南,请参阅 深度精度。

功能示例

  • 深度 — 可视化 Depth 节点的深度和置信度;通过 CLI 练习 build() 重载。

参考

Depth 节点 API 在 depthai-core 的 include/depthai/pipeline/node/Depth.hpp 中有文档。
class

dai::node::Depth

#include Depth.hpp
using
Config = std::variant< std::monostate, DeviceModelZoo, StereoDepth::PresetMode >
Algorithm-specific configuration (DeviceModelZoo for NEURAL, StereoDepth::PresetMode for STEREO, or std::monostate for backends without a selectable profile).
function
Depth(const Depth &)
function
Depth & operator=(const Depth &)
function
Depth(Depth &&)
function
Depth & operator=(Depth &&)
function
~Depth()
function
Depth()
function
std::shared_ptr< Depth > build(std::optional< float > fps)
Set stereo camera FPS for stereo-based backends. Must be called before first depth() or confidence() access.
Parameters
  • fps: Requested FPS; uses Camera default if not set
function
std::shared_ptr< Depth > build(Algorithm algorithm, std::optional< float > fps)
Set algorithm and optional FPS before wiring.
Parameters
  • algorithm: Backend to use
  • fps: Requested stereo camera FPS
function
std::shared_ptr< Depth > build(Algorithm algorithm, std::optional< float > fps, std::optional< std::pair< uint32_t, uint32_t >> size)
Set algorithm, optional FPS, and preferred depth output size before wiring.
Parameters
  • algorithm: Backend to use
  • fps: Requested stereo camera FPS
  • size: preferred depth output size. Used when no upstream Camera is present
function
std::shared_ptr< Depth > build(Algorithm algorithm, Config config, std::optional< float > fps, std::optional< std::pair< uint32_t, uint32_t >> size)
Set algorithm and config before wiring. algorithm must not be AUTO.
Parameters
  • algorithm: Backend to use
  • config: Algorithm-specific configuration
  • fps: Requested stereo camera FPS
  • size: preferred depth output size. Used when no upstream Camera is present
function
Node::Output & depth()
Output depth map from the active backend.
function
Node::Output & confidence()
Output confidence map from the active backend. When ToF is active, this forwards the actual ToF confidence output.
function
std::shared_ptr< Depth > setAlignTo(Node::Output & alignTo)
Align depth output to another image source. Must be called before first depth() or confidence() access. Only depth() is aligned; confidence() stays in the backend frame.
Parameters
  • alignTo: Output to align depth to
inline function
Algorithm getRequestedAlgorithm()
Get the requested algorithm selection.
function
std::shared_ptr< Depth > setAlgorithm(Algorithm algorithm)
Set the requested algorithm before wiring.
Parameters
  • algorithm: Backend to use; AUTO re-enables auto-selection
inline function
const std::optional< Config > & getRequestedConfig()
Get the requested config override, if any.
Returns
Config override, or std::nullopt when config is auto-picked
function
std::shared_ptr< Depth > setConfig(Config config)
Pin the algorithm-specific config. Only takes effect together with a concrete (non-AUTO) algorithm.
Parameters
  • config: Algorithm-specific configuration
inline function
Algorithm getResolvedAlgorithm()
Get the algorithm actually wired (AUTO resolved). Valid after first depth() access.
inline function
const Config & getResolvedConfig()
Get the resolved algorithm-specific config.
function
void buildInternal()
Function called from within the create function to build the node. This function is useful for initialization, setting up inputs and outputs = stuff that cannot be perform in the constuctor.
enum

std::uint32_t Algorithm

Backend selection for the Depth node.
enumerator
AUTO
enumerator
STEREO
enumerator
NEURAL
enumerator
NEURAL_ASSISTED_STEREO
enumerator
TOF
enumerator
GPU_STEREO
enumerator
TOF_STEREO_FUSION

需要帮助?

请访问讨论论坛以获取技术支持或您可能有的任何其他问题。