AutoCalibration

Supported on:RVC2 RVC4

AutoCalibration is a host node that runs automatic stereo calibration workflows in a pipeline and provides calibration quality results during runtime.It is important to separate the two layers:

AutoCalibration is a host node that you add to your pipeline.
Internally, it controls and uses DynamicCalibration in the background.
DEPTHAI_AUTOCALIBRATION is a global deployment switch for automatic calibration.

Three ways to enable automatic calibration

Choose based on how much control you need:

Global variable (DEPTHAI_AUTOCALIBRATION) Best for deployed pipelines where you want to enable automatic behavior without changing code.
AutoCalibration host node Best when you want explicit pipeline-level control over mode, retries, validation, flashing, and result handling.
Pipeline setter (pipeline.setAutoCalibrationMode(...)) Best when you want lightweight code-level control without adding the AutoCalibration host node.

Automatic calibration via global variable

Use one of the following environment values:

Command Line

1DEPTHAI_AUTOCALIBRATION=ON_START
2DEPTHAI_AUTOCALIBRATION=CONTINUOUS
3DEPTHAI_AUTOCALIBRATION=OFF

These values run automatic calibration without adding node-level API handling in your application.

From DepthAI 3.6, automatic calibration is enabled by default in ON_START mode.

Use DEPTHAI_AUTOCALIBRATION=OFF or pipeline.setAutoCalibrationMode(...OFF) to disable it.

Behavior notes

Applies to stereo 1280x800 and 640x400 pipelines.
Flashes calibration as user calibration.
Factory calibration remains untouched.
If your pipeline already includes a DynamicCalibration node or an AutoCalibration node, AutoCalibrationMode - based automatic procedure is not initialized.

In both ON_START and CONTINUOUS procedures, the new calibration is flashed as user calibration. This overwrites the existing user calibration currently stored on the device.

ON_START procedure

Runs automatic calibration during startup and then continues with normal pipeline execution.

Example

Command Line

1DEPTHAI_AUTOCALIBRATION=ON_START python3 examples/Stereo/stereo.py

Optional detailed logs:

Command Line

1DEPTHAI_LEVEL=info DEPTHAI_AUTOCALIBRATION=ON_START python3 examples/Stereo/stereo.py

If startup calibration fails validation, no new calibration is flashed.Typical startup timing depends on scene coverage and retries:

Fast path: about 2.5s.
Common retry path: about 6s.
Worst-case retries (maxIterations = 10): up to about 25s.

CONTINUOUS procedure

Runs calibration continuously during runtime, adapting to changing thermal/mechanical conditions.

Example

Command Line

1DEPTHAI_AUTOCALIBRATION=CONTINUOUS python3 examples/Stereo/stereo.py

Optional detailed logs:

Command Line

1DEPTHAI_LEVEL=info DEPTHAI_AUTOCALIBRATION=CONTINUOUS python3 examples/Stereo/stereo.py

This mode adds ongoing processing overhead, unlike ON_START.

Automatic calibration via pipeline setter

Use pipeline.setAutoCalibrationMode(...) when you want explicit mode control in code without adding the AutoCalibration host node.

Python

1pipeline = dai.Pipeline()
2pipeline.setAutoCalibrationMode(dai.Pipeline.AutoCalibrationMode.ON_START)
3# Or run continuously:
4# pipeline.setAutoCalibrationMode(dai.Pipeline.AutoCalibrationMode.CONTINUOUS)
5
6# Disable automatic calibration
7pipeline.setAutoCalibrationMode(dai.Pipeline.AutoCalibrationMode.OFF)

C++

1dai::Pipeline pipeline;
2pipeline.setAutoCalibrationMode(dai::Pipeline::AutoCalibrationMode::ON_START);
3// Or run continuously:
4// pipeline.setAutoCalibrationMode(dai::Pipeline::AutoCalibrationMode::CONTINUOUS);
5
6// Disable automatic calibration
7pipeline.setAutoCalibrationMode(dai::Pipeline::AutoCalibrationMode::OFF);

If both DEPTHAI_AUTOCALIBRATION and pipeline.setAutoCalibrationMode(...) are set, the pipeline-local mode set in code overrides the environment variable.

AutoCalibration host node in your pipeline

Use this approach when you want explicit control and direct access to runtime outputs.

Example

The examples below use 1280x800 stereo inputs, but the same AutoCalibration workflow also supports 640x400.

Python

1import cv2 as cv
2import numpy as np
3import depthai as dai
4
5# Create pipeline
6with dai.Pipeline() as pipeline:
7    device = pipeline.getDefaultDevice()
8    botchCalibration(device)
9
10    camLeft = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_B)
11    camRight = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_C)
12    stereo = pipeline.create(dai.node.StereoDepth)
13
14    dcWorker = pipeline.create(dai.node.AutoCalibration).build(camLeft, camRight)
15    dcWorker.initialConfig.maxIterations = 2
16    dcWorker.initialConfig.sleepingTime = 10
17    dcWorker.initialConfig.flashCalibration = False 
18    dcWorker.initialConfig.mode = dai.AutoCalibrationConfig.CONTINUOUS  # ON_START
19    dcWorker.initialConfig.validationSetSize = 5 
20    dcWorker.initialConfig.dataConfidenceThreshold = 0.7
21    workerOutputQueue = dcWorker.output.createOutputQueue()
22
23    videoQueueLeft = camLeft.requestOutput((1280, 800), fps=30)
24    videoQueueRight = camRight.requestOutput((1280, 800), fps=30)
25
26    videoQueueLeft.link(stereo.left)
27    videoQueueRight.link(stereo.right)
28
29    stereoOut = stereo.depth.createOutputQueue()
30    pipeline.start()
31
32    while pipeline.isRunning():
33        workerOutput = workerOutputQueue.tryGet()
34        if workerOutput is not None:
35            if workerOutput.passed:
36                print("Passed")
37                print(f"dataConfidence = {workerOutput.dataConfidence}")
38                print(f"calibrationConfidence = {workerOutput.calibrationConfidence}")
39            else:
40                print("Did not pass")
41
42        depth = stereoOut.get()
43        cv.imshow("Depth", depth)
44
45        if cv.waitKey(1) == ord("q"):
46            break
47        
48    pipeline.stop()

C++

1#include <iostream>
2#include <memory>
3#include <opencv2/opencv.hpp>
4#include <vector>
5
6#include "depthai/depthai.hpp"
7int main() {
8    dai::Pipeline pipeline;
9
10    // Create device
11    auto device = pipeline.getDefaultDevice();
12
13    // Nodes
14    auto camLeft = pipeline.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_B);
15    auto camRight = pipeline.create<dai::node::Camera>()->build(dai::CameraBoardSocket::CAM_C);
16    auto stereo = pipeline.create<dai::node::StereoDepth>();
17
18    // AutoCalibration node
19    auto dcWorker = pipeline.create<dai::node::AutoCalibration>();
20    dcWorker->build(camLeft, camRight);
21
22    auto config = dcWorker->initialConfig;
23    config->maxIterations = 2;
24    config->sleepingTime = 10;
25    config->flashCalibration = false;
26    config->mode = dai::AutoCalibrationConfig::CONTINUOUS;
27    config->validationSetSize = 5;
28    config->dataConfidenceThreshold = 0.7;
29
30    // Links
31    camLeft->requestOutput({1280, 800})->link(stereo->left);
32    camRight->requestOutput({1280, 800})->link(stereo->right);
33
34    // Queues
35    auto workerOutputQueue = dcWorker->output.createOutputQueue();
36    auto stereoOut = stereo->depth.createOutputQueue();
37
38    pipeline.start();
39
40    while(pipeline.isRunning()) {
41        auto workerOutput = workerOutputQueue->tryGet<dai::AutoCalibrationResult>();
42        if(workerOutput != nullptr) {
43            if(workerOutput->passed) {
44                std::cout << "Passed. Confidence: " << workerOutput->dataConfidence << std::endl;
45            } else {
46                std::cout << "Did not pass." << std::endl;
47            }
48        }
49
50        auto depth = stereoOut->get<dai::ImgFrame>();
51        cv::imshow("Depth", depth);
52
53        if(cv::waitKey(1) == 'q') break;
54    }
55
56    return 0;
57}

Configuration Parameters

Configure behavior through auto_calib.initialConfig:

mode Selects the automatic calibration procedure (ON_START or CONTINUOUS).
flashCalibration If true, calibration is flashed as user calibration after successful validation.
maxIterations Maximum number of calibration attempts.
sleepingTime Delay between calibration attempts/iterations.
validationSetSize Number of validation samples used before accepting calibration.

Node Output (Result)

The node provides AutoCalibrationResult messages. Common fields:

passed Whether calibration/validation succeeded.
dataQuality Quality indicator of the collected calibration data.
calibrationConfidence Confidence score for the resulting calibration.

Availability and rollout status

DepthAI 3.5.0 provides startup automatic calibration as an opt-in beta through DEPTHAI_AUTOCALIBRATION.
From DepthAI 3.6, automatic calibration is enabled by default in ON_START mode.
Use DEPTHAI_AUTOCALIBRATION=OFF or pipeline.setAutoCalibrationMode(...OFF) to disable it.

Install example:

Command Line

1python3 -m pip install depthai==3.5.0

Feedback

AutoCalibration is an actively evolving feature. If you want to help shape it, use the node in real deployments and share feedback with us on GitHub: what worked well, what failed, and what parameters or outputs you want to see improved. We prioritize API improvements based on user feedback.

If you encounter issues or want API improvements, report them via:

Forum: discuss.luxonis.com
GitHub: luxonis/depthai-core
For calibration data collection during debugging, use Stereo Tuning Assistance and attach the captured zip folder.

Reference

class

dai::node::AutoCalibration

variable

std::shared_ptr< AutoCalibrationConfig > initialConfig

variable

Output output

function

std::shared_ptr< AutoCalibration > build(const std::shared_ptr< Camera > & cameraLeft, const std::shared_ptr< Camera > & cameraRight)

function

~AutoCalibration()

function

void run()

function

void setRunOnHost(bool runOnHost)

function

bool runOnHost()

function

void buildInternal()

inline function

DeviceNodeCRTP()

inline function

DeviceNodeCRTP(const std::shared_ptr< Device > & device)

inline function

DeviceNodeCRTP(std::unique_ptr< Properties > props)

inline function

DeviceNodeCRTP(std::unique_ptr< Properties > props, bool confMode)

inline function

DeviceNodeCRTP(const std::shared_ptr< Device > & device, std::unique_ptr< Properties > props, bool confMode)

enum

dai::DynamicCalibrationControl DCC

Need assistance?

Head over to Discussion Forum for technical support or any other questions you might have.

ON THIS PAGE

AutoCalibrationView as Markdown

Three ways to enable automatic calibration

Automatic calibration via global variable

Behavior notes

ON_START procedure

Example

CONTINUOUS procedure

Example

Automatic calibration via pipeline setter

Python

C++

AutoCalibration host node in your pipeline

Example

Python

C++

Configuration Parameters

Node Output (Result)

Availability and rollout status

Feedback

Reference

dai::node::AutoCalibration

dai::DynamicCalibrationControl DCC

Need assistance?

AutoCalibration