# 深度

深度旨在统一和简化您从 Luxonis 深度感知设备获取深度的方式——涵盖 RVC2、RVC4 和未来所有 Luxonis 平台。一个节点，一个 API：创建 `Depth`，请求深度图（以及伴随的置信度图），然后让 Depth
处理其余部分。您不再需要了解设备上的哪些传感器最适合深度，如何组合它们，哪种算法适合您的硬件，何时神经深度优于经典立体深度，或者哪个预设与哪个后端配对。Depth
抽象了这些选择——它选择最佳传感器或传感器组合、匹配的后端以及适合您的设备和约束的正确配置，然后为您连接图。

在每个设备上，Depth 从可用的深度感知硬件开始——立体对、ToF 传感器或两者——并通过适合的后端进行路由。在底层，这可能解析为
[StereoDepth](/software-v3/depthai/depthai-components/nodes/stereo_depth.md)、[NeuralDepth](https://docs.luxonis.com/zh/software-v3/depthai/depthai-components/nodes/neural_depth.md)、[NeuralAssistedStereo](https://docs.luxonis.com/zh/software-v3/depthai/depthai-components/nodes/neural_assisted_stereo.md)、[GPUStereo](https://docs.luxonis.com/zh/software-v3/depthai/depthai-components/nodes/gpu_stereo.md)
或 [ToF](/software-v3/depthai/depthai-components/nodes/tof.md)。Depth 还通过相同的 API 通过 `setAlignTo()`
处理深度对齐。

Depth 还会告诉您它选择了什么。连接后，`getResolvedAlgorithm()` 和 `getResolvedConfig()`
返回自动选择的算法和配置——检查它们，保存以备后用，或者如果您喜欢结果，可以在下次运行时明确固定它们。该读数也是您了解底层后端的地图：当您需要对过滤器、预设或模型设置进行更精细的控制时，使用解析值直接使用
[StereoDepth](/software-v3/depthai/depthai-components/nodes/stereo_depth.md)、[NeuralDepth](https://docs.luxonis.com/zh/software-v3/depthai/depthai-components/nodes/neural_depth.md)
或匹配节点构建管道，而无需通过 Depth。请参阅 [内省](#Introspection) 和 [高级后端调优](#Advanced%20backend%20tuning)。

> **Note**
> Depth 自动选择的算法和配置可能会在 DepthAI 版本之间发生变化，因为我们会不断完善每个平台上的最佳方案。将 Depth 视为 Luxonis 设备最佳深度的不断发展的来源——它随着每次 DepthAI 升级而改进。

## 一般逻辑

Depth 旨在开箱即用，无需用户输入——创建节点，它会为您的设备选择最佳传感器、后端和配置。您还可以传递一些基本约束，例如 FPS 和分辨率，Depth 会处理内部传感器和算法选择以满足这些约束。

当您固定 FPS 时，Depth 会将输出速率精确保持在您请求的值。输出分辨率可能与您请求的不同：每个后端都有原生和支持的大小，Depth 会为您的目标选择最合适的配置文件。Depth 本身包含深度图所在的分辨率和坐标系的所有信息，因此下游 DepthAI
节点可以直接摄取它。

## 如何放置

#### Python

```python
import depthai as dai

with dai.Pipeline() as pipeline:
    depth = pipeline.create(dai.node.Depth)
    depthQueue = depth.depth.createOutputQueue()
```

#### C++

```cpp
#include <depthai/depthai.hpp>

dai::Pipeline pipeline;
auto depth = pipeline.create<dai::node::Depth>();
auto depthQueue = depth->depth().createOutputQueue();
```

## 输入和输出

Depth 暴露了两个公共输出。传感器节点在内部获取——节点发现设备第一个立体对上的现有
[Camera](/software-v3/depthai/depthai-components/nodes/camera.md) 节点和
[ToF](/software-v3/depthai/depthai-components/nodes/tof.md) 传感器节点，并在底层创建任何缺失的传感器节点，包括 ToF。

 * `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。

> **Note**
> 在 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 和分辨率推断

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
# 第一次运行：解析并保存值
resolved_algorithm = depth.getResolvedAlgorithm()
resolved_config = depth.getResolvedConfig()

# 后续运行：在新 Depth 节点上重用它们
depth = pipeline.create(dai.node.Depth)
depth.build(resolved_algorithm, resolved_config)
```

## 深度对齐

在首次访问输出之前调用 `setAlignTo()`，将深度输出与另一个图像源（例如，彩色相机输出）对齐。只有 `depth` 对齐；`confidence` 保持在后端帧中。

Depth 自动选择对齐路径：

| 平台 / 后端 | 对齐路径 |
| --- | --- |
| RVC2 + `STEREO` | StereoDepth 原生 (`inputAlignTo`) |
| RVC2 + 其他后端 | 主机 [ImageAlign](/software-v3/depthai/depthai-components/nodes/image_align.md) |
| RVC4（所有后端） | 设备上 ImageAlign |

```python
colorOut = colorCam.requestOutput((1280, 800))
depth.setAlignTo(colorOut)
```

## 用法

#### Python

```python
import depthai as dai

with dai.Pipeline() as pipeline:
    # 零配置 AUTO — 设备的最佳后端
    depth = pipeline.create(dai.node.Depth)

    # 受限 AUTO
    # depth.build(fps=30, stereo_size=(640, 400))

    # 固定后端，自动配置
    # depth.build(dai.node.Depth.Algorithm.STEREO)

    # 完全显式
    # depth.build(
    #     dai.node.Depth.Algorithm.NEURAL,
    #     dai.DeviceModelZoo.NEURAL_DEPTH_SMALL,
    #     fps=30,
    # )

    depthQueue = depth.depth.createOutputQueue()
    confidenceQueue = depth.confidence.createOutputQueue()

    pipeline.build()
    print("Resolved:", depth.getResolvedAlgorithm(), depth.getResolvedConfig())

    pipeline.start()
    while pipeline.isRunning():
        depthFrame = depthQueue.get()
        # 处理 depthFrame
```

#### C++

```cpp
#include <depthai/depthai.hpp>

dai::Pipeline pipeline;
auto depth = pipeline.create<dai::node::Depth>();

// 固定后端，自动配置
// depth->build(dai::node::Depth::Algorithm::STEREO);

auto depthQueue = depth->depth().createOutputQueue();
auto confidenceQueue = depth->confidence().createOutputQueue();

pipeline.build();
std::cout << "Resolved algorithm: " << static_cast<int>(depth->getResolvedAlgorithm()) << std::endl;

pipeline.start();
while(pipeline.isRunning()) {
    auto depthFrame = depthQueue->get<dai::ImgFrame>();
    // 处理 depthFrame
}
```

### 重用现有相机

如果您在设备的第一个立体对上已经有左右 Camera 节点，Depth 会重用它们并匹配它们的大小和 FPS。您的相机将保留在 Depth 的子树之外。

```python
left = pipeline.create(dai.node.Camera).build(stereoPair.left, (640, 400), 30)
right = pipeline.create(dai.node.Camera).build(stereoPair.right, (640, 400), 30)

depth = 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 不会暴露每个后端的每个调优旋钮。对于高级配置，请固定特定后端并使用专用节点文档：

 * [StereoDepth](/software-v3/depthai/depthai-components/nodes/stereo_depth.md)
 * [NeuralDepth](/software-v3/depthai/depthai-components/nodes/neural_depth.md)
 * [NeuralAssistedStereo](/software-v3/depthai/depthai-components/nodes/neural_assisted_stereo.md)
 * [GPUStereo](/software-v3/depthai/depthai-components/nodes/gpu_stereo.md)
 * [ToF](/software-v3/depthai/depthai-components/nodes/tof.md)

有关深度精度指南，请参阅 [深度精度](/hardware/platform/depth/depth-accuracy.md)。

## 功能示例

 * [深度](/software-v3/depthai/examples/depth/unified_depth.md) — 可视化 Depth 节点的深度和置信度；通过 CLI 练习 `build()`
   重载。

## 参考

Depth 节点 API 在 depthai-core 的
[`include/depthai/pipeline/node/Depth.hpp`](https://github.com/luxonis/depthai-core/blob/main/include/depthai/pipeline/node/Depth.hpp)
中有文档。

### dai::node::Depth

Kind: class

Depth node. Unified depth output from StereoDepth , NeuralDepth , NeuralAssistedStereo , ToF , or GPUStereo .

With Algorithm::AUTO, the backend is chosen from device capabilities, target FPS, and stereo resolution. On RVC4 this prefers
NeuralDepth when available; on other platforms it uses ToF when a ToF sensor is connected, otherwise StereoDepth . Use build() to
pin algorithm, FPS, or resolution before the first depth() / confidence() access. Use setAlignTo() to align depth to another
camera output.

#### std::uint32_t Algorithm

Kind: enum

Backend selection for the Depth node.

##### AUTO

Kind: enum_value

##### STEREO

Kind: enum_value

##### NEURAL

Kind: enum_value

##### NEURAL_ASSISTED_STEREO

Kind: enum_value

##### TOF

Kind: enum_value

##### GPU_STEREO

Kind: enum_value

##### TOF_STEREO_FUSION

Kind: enum_value

#### std::variant< std::monostate, DeviceModelZoo, StereoDepth::PresetMode > Config

Kind: typedef

Algorithm-specific configuration (DeviceModelZoo for NEURAL, StereoDepth::PresetMode for STEREO, or std::monostate for backends
without a selectable profile).

#### Depth(const Depth &)

Kind: function

#### Depth & operator=(const Depth &)

Kind: function

#### Depth(Depth &&)

Kind: function

#### Depth & operator=(Depth &&)

Kind: function

#### ~Depth()

Kind: function

#### Depth()

Kind: function

#### std::shared_ptr< Depth > build(std::optional< float > fps)

Kind: function

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

#### std::shared_ptr< Depth > build(Algorithm algorithm, std::optional< float > fps)

Kind: function

Set algorithm and optional FPS before wiring. parameters: algorithm: Backend to use; fps: Requested stereo camera FPS

#### std::shared_ptr< Depth > build(Algorithm algorithm, std::optional< float > fps, std::optional< std::pair< uint32_t, uint32_t >> size)

Kind: function

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

#### std::shared_ptr< Depth > build(Algorithm algorithm, Config config, std::optional< float > fps, std::optional< std::pair< uint32_t, uint32_t >> size)

Kind: function

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

#### Node::Output & depth()

Kind: function

Output depth map from the active backend.

#### Node::Output & confidence()

Kind: function

Output confidence map from the active backend. When ToF is active, this forwards the actual ToF confidence output.

#### std::shared_ptr< Depth > setAlignTo(Node::Output & alignTo)

Kind: function

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

#### Algorithm getRequestedAlgorithm()

Kind: function

Get the requested algorithm selection.

#### std::shared_ptr< Depth > setAlgorithm(Algorithm algorithm)

Kind: function

Set the requested algorithm before wiring. parameters: algorithm: Backend to use; AUTO re-enables auto-selection

#### const std::optional< Config > & getRequestedConfig()

Kind: function

Get the requested config override, if any. return: Config override, or std::nullopt when config is auto-picked

#### std::shared_ptr< Depth > setConfig(Config config)

Kind: function

Pin the algorithm-specific config. Only takes effect together with a concrete (non-AUTO) algorithm. parameters: config:
Algorithm-specific configuration

#### Algorithm getResolvedAlgorithm()

Kind: function

Get the algorithm actually wired (AUTO resolved). Valid after first depth() access.

#### const Config & getResolvedConfig()

Kind: function

Get the resolved algorithm-specific config.

#### void buildInternal()

Kind: function

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.

### 需要帮助？

请访问[讨论论坛](https://discuss.luxonis.com/)以获取技术支持或您可能有的任何其他问题。
