# Depth

Depth is here to unify and simplify how you get depth from Luxonis depth-enabled devices — across RVC2, RVC4, and every future
Luxonis platform. One node, one API: create `Depth`, request a depth map (and a companion confidence map), and let Depth handle
the rest. You no longer need to learn which sensors on your device are best for depth, how to combine them, which algorithm fits
your hardware, when neural depth beats classical stereo, or which preset to pair with each backend. Depth abstracts those choices
away — it picks the best sensors or sensor combination, the matching backend, and the right config for your device and
constraints, then wires the graph for you.

On each device, Depth starts from the depth-capable hardware available — a stereo pair, a ToF sensor, or both — and routes through
the backend that fits. Under the hood, that may resolve to
[StereoDepth](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/stereo_depth.md),
[NeuralDepth](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/neural_depth.md),
[NeuralAssistedStereo](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/neural_assisted_stereo.md),
[GPUStereo](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/gpu_stereo.md), or
[ToF](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/tof.md). Depth also handles depth alignment through
the same API via `setAlignTo()`.

Depth also tells you what it chose. After wiring, `getResolvedAlgorithm()` and `getResolvedConfig()` return the auto-selected
algorithm and config — inspect them, store them for later, or pin them explicitly on the next run if you like the result. That
readout is also your map to the underlying backend: when you need finer control over filters, presets, or model settings, use the
resolved values to build the pipeline with
[StereoDepth](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/stereo_depth.md),
[NeuralDepth](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/neural_depth.md), or the matching node
directly, without going through Depth. See [Introspection](#Introspection) and [Advanced backend
tuning](#Advanced%20backend%20tuning).

> **Note**
> The algorithms and configs Depth selects automatically may change between DepthAI releases as we refine what works best on each platform. Treat Depth as an ever-evolving source of the best possible depth for Luxonis devices — it improves with every DepthAI upgrade.

## General logic

Depth is designed to work out of the box with no user input — create the node and it picks the best sensors, backend, and config
for your device. You can also pass a few basic constraints, such as FPS and resolution, and Depth handles the internal sensor and
algorithm selection to satisfy them.

When you pin FPS, Depth keeps the output rate exactly at the value you requested. Output resolution may differ from what you asked
for: each backend has native and supported sizes, and Depth selects the best-fitting profile for your target. Depth itself carries
all the information about the resolution and coordinate system the depth map lives in, so downstream DepthAI nodes can ingest it
directly.

## How to place it

#### 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();
```

## Inputs and Outputs

Depth exposes two public outputs. Sensor nodes are sourced internally — the node discovers existing
[Camera](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/camera.md) nodes on the device's first stereo pair
and [ToF](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/tof.md) sensor nodes, and creates any missing
sensor nodes under the hood, including ToF.

 * `depth` — Depth map from the active backend. When `setAlignTo()` is used, this output is aligned to the target image.
 * `confidence` — Confidence-like map from the active backend. Stays in the backend's native frame of reference (not aligned). For
   the ToF backend, this is amplitude.

There are no public graph input ports. Use `setAlignTo()` before first output access to align depth to another camera output (for
example, a color stream).

## Backend selection

With `Algorithm.AUTO` (the default), Depth picks the best backend the device can run, given your target FPS and stereo resolution.

| Algorithm | Underlying node | Platform | Notes |
| --- | --- | --- | --- |
| `STEREO` | StereoDepth | All | Always available as a baseline. |
| `NEURAL` | NeuralDepth | RVC4 | Model auto-selected from the device model catalog. |
| `NEURAL_ASSISTED_STEREO` | NeuralAssistedStereo | RVC4 | Stereo + neural assist. |
| `GPU_STEREO` | GPUStereo | RVC4 | Requires device with GPU. |
| `TOF` | ToF | All | Requires a connected ToF sensor. |

Platform defaults with `AUTO`:

 * RVC4 — Scans backends in priority order: NeuralDepth → NeuralAssistedStereo → StereoDepth → GPUStereo, matching FPS and
   resolution constraints.
 * Other platforms — Uses ToF when a ToF sensor is connected; otherwise StereoDepth.

> **Note**
> On RVC4, `AUTO` never selects ToF. Pin `Algorithm.TOF` explicitly on devices with a ToF sensor if you want that backend.

## Configuration

All configuration must happen before the first `depth` or `confidence` output access.

Use `build()` to set FPS, resolution, algorithm, and config:

| API | Effect |
| --- | --- |
| `build(fps=None)` | Set target stereo FPS only (`AUTO` algorithm). |
| `build(algorithm, fps=None, stereo_size=None)` | Set algorithm and optional FPS / stereo frame size. |
| `build(algorithm, config, fps=None, stereo_size=None)` | Pin both algorithm and config. `algorithm` must not be `AUTO`. |

You can also use individual setters: `setAlgorithm()`, `setConfig()`, and `setAlignTo()`.

Config type (`algorithm` → accepted config):

 * `NEURAL` → `DeviceModelZoo` (for example `NEURAL_DEPTH_SMALL`)
 * `STEREO` → `StereoDepth.PresetMode` (for example `DEFAULT`)
 * `NEURAL_ASSISTED_STEREO`, `GPU_STEREO`, `TOF` → no config (`None` / `std::monostate`)

### FPS and resolution inference

FPS and resolution are inferred independently from, in order:

 1. Explicit `build()` arguments (`fps`, `stereo_size`)
 2. Existing left/right Camera nodes on the first stereo pair (matching requested output size)
 3. Device defaults (30 FPS; resolution from camera features)

If both FPS and resolution are pinned but no backend can serve both, the Depth node throws an error. Otherwise, FPS is kept at the
requested value and the output resolution is chosen from the best-fitting native or supported profile of the selected backend —
which may differ from your requested size.

### Introspection

| Getter | Returns |
| --- | --- |
| `getRequestedAlgorithm()` | Algorithm you set (default `AUTO`). |
| `getRequestedConfig()` | Config you pinned, or `None` if auto. |
| `getResolvedAlgorithm()` | Algorithm actually wired (valid after first `depth` access). |
| `getResolvedConfig()` | Config actually used (valid after first `depth` access). |

To reproduce an `AUTO` selection, read the resolved values after one run and pin them on a second node in a subsequent run:

```python
# First run: resolve and save the values
resolved_algorithm = depth.getResolvedAlgorithm()
resolved_config = depth.getResolvedConfig()

# Subsequent run: reuse them on a new Depth node
depth = pipeline.create(dai.node.Depth)
depth.build(resolved_algorithm, resolved_config)
```

## Depth alignment

Call `setAlignTo()` before first output access to align the depth output to another image source (for example, a color camera
output). Only `depth` is aligned; `confidence` stays in the backend frame.

Depth picks the alignment path automatically:

| Platform / backend | Alignment path |
| --- | --- |
| RVC2 + `STEREO` | StereoDepth native (`inputAlignTo`) |
| RVC2 + other backends | Host [ImageAlign](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/image_align.md)
|
| RVC4 (all backends) | On-device ImageAlign |

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

## Usage

#### Python

```python
import depthai as dai

with dai.Pipeline() as pipeline:
    # Zero-config AUTO — best backend for the device
    depth = pipeline.create(dai.node.Depth)

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

    # Pin backend, auto-config
    # depth.build(dai.node.Depth.Algorithm.STEREO)

    # Fully explicit
    # 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()
        # process depthFrame
```

#### C++

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

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

// Pin backend with auto-config
// 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>();
    // process depthFrame
}
```

### Reusing existing cameras

If you already have left/right Camera nodes on the device's first stereo pair, Depth reuses them and matches their size and FPS.
Your cameras stay outside Depth's subtree.

```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)  # infers 640x400 @ 30 from cameras
```

## RVC4 AUTO resolution reference

On a fully capable RVC4 device (all backends available, full NeuralDepth model catalog), `AUTO` resolves common (resolution, FPS)
combinations approximately as follows. NEURAL rows use a tensor-cover band (≈ ±√2 around the model's native size); other backends
use a simple max-resolution cap. The FPS gate is `targetFps × 0.9`.

| Resolution | 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* |

`*` — No profile meets the FPS gate at that resolution, so AUTO drops the FPS gate and picks the resolution-fitting profile with
the highest available FPS (GPU_STEREO, ~5 FPS). These are best-effort, not guaranteed at the requested FPS.

If NeuralDepth or NeuralAssistedStereo is unavailable, NEURAL/NAS cells fall back to `STEREO` (preset by FPS: `DEFAULT` when
required FPS ≤ 16, else `FAST_ACCURACY`/`FAST_DENSITY` when required FPS ≤ 30), subject to StereoDepth's 1280×1280 cap. If
GPUStereo is unavailable, high-resolution rows fall back to the last-resort `STEREO` `FAST_ACCURACY` (resolution beyond
StereoDepth's cap is served best-effort).

## Advanced backend tuning

Depth does not expose every tuning knob of each backend. For advanced configuration, pin a specific backend and use the dedicated
node documentation:

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

For depth accuracy guidance, see [Depth Accuracy](https://docs.luxonis.com/hardware/platform/depth/depth-accuracy.md).

## Examples of functionality

 * [Depth](https://docs.luxonis.com/software-v3/depthai/examples/depth/unified_depth.md) — Visualize depth and confidence from the
   Depth node; exercise `build()` overloads via CLI.

## Reference

The Depth node API is documented in depthai-core at
[`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

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

Kind: enum

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

### Need assistance?

Head over to [Discussion Forum](https://discuss.luxonis.com/) for technical support or any other questions you might have.