AutoCalibration

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 recognized by depthai-core.

Two 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.

Automatic calibration via global variable

Use one of the following environment values:

Command Line

1DEPTHAI_AUTOCALIBRATION=ON_START
2DEPTHAI_AUTOCALIBRATION=CONTINUOUS

These are recognized by depthai-core and run automatic calibration without adding node-level API handling in your application.

Behavior notes

Applies to stereo 1280x800 pipelines.
Flashes calibration as user calibration.
Factory calibration remains untouched.
If your pipeline already integrates DynamicCalibration directly, this 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.

AutoCalibration host node in your pipeline

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

Example

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.

When flashing is enabled and a calibration passes validation, the previous user calibration on the device is overwritten.

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

Startup automatic calibration is available for depthai versions greater than 3.5.0.
DepthAI 3.5.0 provides this as an opt-in beta through DEPTHAI_AUTOCALIBRATION.

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

AutoCalibration

Two ways to enable automatic calibration

Automatic calibration via global variable

Behavior notes

ON_START procedure

Example

CONTINUOUS procedure

Example

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?