OverviewCloudSoftwareHardware
OAK Apps
DepthAI
AI
Software Stack
Troubleshooting

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
  • Configuration Parameters
  • Node Output (Result)
  • Availability and rollout status
  • Feedback
  • Reference

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.
React Flow

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.

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
C++

Python

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()

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

  • 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

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

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)

Need assistance?

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