Depth,请求深度图(以及伴随的置信度图),然后让 Depth 处理其余部分。您不再需要了解设备上的哪些传感器最适合深度,如何组合它们,哪种算法适合您的硬件,何时神经深度优于经典立体深度,或者哪个预设与哪个后端配对。Depth 抽象了这些选择——它选择最佳传感器或传感器组合、匹配的后端以及适合您的设备和约束的正确配置,然后为您连接图。在每个设备上,Depth 从可用的深度感知硬件开始——立体对、ToF 传感器或两者——并通过适合的后端进行路由。在底层,这可能解析为 StereoDepth、NeuralDepth、NeuralAssistedStereo、GPUStereo 或 ToF。Depth 还通过相同的 API 通过 setAlignTo() 处理深度对齐。Depth 还会告诉您它选择了什么。连接后,getResolvedAlgorithm() 和 getResolvedConfig() 返回自动选择的算法和配置——检查它们,保存以备后用,或者如果您喜欢结果,可以在下次运行时明确固定它们。该读数也是您了解底层后端的地图:当您需要对过滤器、预设或模型设置进行更精细的控制时,使用解析值直接使用 StereoDepth、NeuralDepth 或匹配节点构建管道,而无需通过 Depth。请参阅 内省 和 高级后端调优。Depth 自动选择的算法和配置可能会在 DepthAI 版本之间发生变化,因为我们会不断完善每个平台上的最佳方案。将 Depth 视为 Luxonis 设备最佳深度的不断发展的来源——它随着每次 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()输入和输出
depth— 来自活动后端的深度图。当使用setAlignTo()时,此输出与目标图像对齐。confidence— 来自活动后端的置信度图。保持在后端原生参考系中(未对齐)。对于 ToF 后端,这是振幅。
setAlignTo() 将深度与另一个相机输出(例如,彩色流)对齐。后端选择
Algorithm.AUTO(默认),Depth 会根据您的目标 FPS 和立体分辨率选择设备可以运行的最佳后端。| 算法 | 底层节点 | 平台 | 注意事项 |
|---|---|---|---|
STEREO | StereoDepth | 所有 | 始终可用作基线。 |
NEURAL | NeuralDepth | RVC4 | 模型从设备模型目录中自动选择。 |
NEURAL_ASSISTED_STEREO | NeuralAssistedStereo | RVC4 | 立体 + 神经辅助。 |
GPU_STEREO | GPUStereo | RVC4 | 需要带 GPU 的设备。 |
TOF | ToF | 所有 | 需要连接 ToF 传感器。 |
AUTO 的平台默认值:- RVC4 — 按优先级顺序扫描后端:NeuralDepth → NeuralAssistedStereo → StereoDepth → GPUStereo,匹配 FPS 和分辨率约束。
- 其他平台 — 连接 ToF 传感器时使用 ToF;否则使用 StereoDepth。
在 RVC4 上,
AUTO 从不选择 ToF。如果您的设备带有 ToF 传感器并且您想要该后端,请明确固定 Algorithm.TOF。配置
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 和分辨率推断
- 显式
build()参数(fps、stereo_size) - 第一个立体对上现有的左右 Camera 节点(匹配请求的输出大小)
- 设备默认值(30 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 + STEREO | StereoDepth 原生 (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重用现有相机
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 @ 30RVC4 AUTO 分辨率参考
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 节点的深度和置信度;通过 CLI 练习
build()重载。
参考
include/depthai/pipeline/node/Depth.hpp 中有文档。class
dai::node::Depth
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
function
Depth(Depth &&)function
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()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()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
enumerator
AUTO
enumerator
STEREO
enumerator
NEURAL
enumerator
NEURAL_ASSISTED_STEREO
enumerator
TOF
enumerator
GPU_STEREO
enumerator
TOF_STEREO_FUSION
需要帮助?
请访问讨论论坛以获取技术支持或您可能有的任何其他问题。