
主要功能
- 恢复深度性能——将视差图恢复到最佳视觉质量。
- 无需目标——在自然场景中操作;只需移动相机即可捕捉多样的视图。
- 快速执行——通常在几秒钟内完成。
- 健康监测——无需刷新新校准即可随时运行诊断。
- 多传感器支持——支持经典立体重新校准和 3 传感器/FFC 工作流程。
自动校准选项
DynamicCalibration 之上运行自动校准:- 使用 AutoCalibration 主机节点,用于在管道内进行显式节点级控制。
- 使用
DEPTHAI_AUTOCALIBRATION进行部署时启用,无需更改管道代码。 - 使用
Pipeline.setAutoCalibrationMode()的直接设置器来启用自动校准,而无需使用 AutoCalibration 主机节点。
从
DepthAI 3.6 开始,自动校准默认在 ON_START 模式下启用。使用 OFF 禁用它。如果您的管道已包含 DynamicCalibration 节点或 AutoCalibration 节点,则不应用 AutoCalibrationMode。动态校准库 (DCL) 的使用
DynamicCalibration 节点进行动态校准工作流程。动态校准将 DynamicCalibrationControl 消息作为输入,其中包含一个命令(例如 ApplyCalibration、Calibrate 等,请参阅消息定义中所有可用的命令)。该节点在四个输出队列之一中返回输出:calibrationOutput,消息类型为 DynamicCalibrationResult,qualityOutput,消息类型为 CalibrationQualitycoverageOutput,消息类型为 CoverageDatametricsOutput,消息类型为 CalibrationMetrics
初始化 DynamicCalibration 节点
DynamicCalibration 节点需要来自同一设备的同步相机流。经典设置使用两个相机,而多传感器工作流程也可以连接 RGB 流。以下是基本的立体设置:Python
1import depthai as dai
2
3# 初始化管道
4pipeline = dai.Pipeline()
5
6# 创建相机节点
7cam_left = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_B)
8cam_right = pipeline.create(dai.node.Camera).build(dai.CameraBoardSocket.CAM_C)
9
10# 请求全分辨率 NV12 输出
11left_out = cam_left.requestFullResolutionOutput()
12right_out = cam_right.requestFullResolutionOutput()
13
14# 初始化 DynamicCalibration 节点
15dyn_calib = pipeline.create(dai.node.DynamicCalibration)
16
17# 将相机链接到 DynamicCalibration
18left_out.link(dyn_calib.left)
19right_out.link(dyn_calib.right)
20
21device = pipeline.getDefaultDevice()
22calibration = device.readCalibration()
23device.setCalibration(calibration)
24
25pipeline.start()
26while pipeline.isRunning():
27 ...向节点发送命令
Python
1# 初始化命令输入队列
2command_input = dyn_calib.inputControl.createInputQueue()
3# 发送命令的示例
4command_input.send(dai.DynamicCalibrationControl.startCalibration())StartCalibration()- 开始校准过程。StopCalibration()- 停止校准过程。Calibrate(force=False, keepCameraCenters=True)- 根据加载的数据计算新的校准。- force - 对加载的数据没有限制
- keepCameraCenters - 保持当前相机中心固定。对于自由形式/未知基线校准,将其设置为
False。
CalibrationQuality(force=False)- 传统质量检查命令。- force - 对加载的数据没有限制
LoadImage()- 从设备加载一张图像。ComputeCalibrationMetrics(calibration)- 计算校准指标,如dataConfidence和calibrationConfidence。ApplyCalibration(calibration)- 将校准应用于设备。SetPerformanceMode(performanceMode)- 发送将使用的性能模式。ResetData()- 删除所有以前加载的数据。
从节点接收数据
coverageOutput→ 覆盖率统计信息 (CoverageData)calibrationOutput→ 校准结果 (DynamicCalibrationResult)qualityOutput→ 传统校准质量输出 (CalibrationQuality)metricsOutput→ 校准统计信息和数据质量 (CalibrationMetrics)
Python
1# 用于接收新校准的队列
2calibration_output = dyn_calib.calibrationOutput.createOutputQueue()
3# 用于接收覆盖率的队列
4coverage_output = dyn_calib.coverageOutput.createOutputQueue()
5# 用于检查校准质量的队列
6quality_output = dyn_calib.qualityOutput.createOutputQueue()
7# 用于检查校准指标的队列
8metrics_output = dyn_calib.metricsOutput.createOutputQueue()DynamicCalibrationResult、CoverageData、CalibrationQuality 和 CalibrationMetrics 的参考资料,以查看输出的确切数据结构。对于运行时校准健康检查,请优先使用 ComputeCalibrationMetrics(...) 和 metricsOutput。从
DepthAI 3.8.0 开始,CalibrationQuality(...) 应被视为已弃用。该节点仍接受该命令以实现兼容性,但当前运行时在 qualityOutput 上返回空的 CalibrationQuality 结果并记录弃用警告。将此 API 替换为:- 旧:
CalibrationQuality() - 新:
calibrate()或startCalibration() - 旧:
dai.DynamicCalibrationControl.calibrationQuality()或dai.DynamicCalibrationControl.Commands.CalibrationQuality() - 新:
dai.DynamicCalibrationControl.calibrate()或dai.DynamicCalibrationControl.startCalibration() - 从
calibrationOutput读取比较数据:DynamicCalibrationResult.calibrationData.calibrationDifference
读取覆盖率数据
LoadImage 命令)或在连续校准期间(运行 StartCalibration 命令后)加载时,覆盖率数据通过 coverageOutput 接收。覆盖率以
coveragePerCell 的形式提供,这是一个以 CameraBoardSocket 为键的映射。较旧的 coveragePerCellA / coveragePerCellB 字段仅作为前两个连接传感器的已弃用兼容性别名保留,应考虑在未来版本中删除。Python
1# 加载单个图像
2command_input.send(dai.DynamicCalibrationControl.loadImage())
3
4# 加载后获取覆盖率
5coverage = coverage_output.get()
6print(f"Coverage = {coverage.meanCoverage}")Python
1command_input.send(dai.DynamicCalibrationControl.startCalibration())
2
3while pipeline.isRunning():
4 # 阻塞读取
5 coverage = coverage_output.get()
6 print(f"Coverage = {coverage.meanCoverage}")
7
8 # 非阻塞读取
9 coverage = coverage_output.tryGet()
10 if coverage:
11 print(f"Coverage = {coverage.meanCoverage}")读取校准数据
dai.DynamicCalibrationControl.startCalibration()— 开始收集数据并尝试校准。dai.DynamicCalibrationControl.calibrate(force=False, keepCameraCenters=True)— 使用现有加载数据进行校准(图像必须事先使用LoadImage命令加载,如下例所示)。
calibrationData 下,其中包含 newCalibration、currentCalibration、calibrationDifference 和 dataConfidence。CalibrationQuality 和 DynamicCalibrationResult 可以报告 pairwiseRotationDifference,以套接字对为键。这是建议检查的旋转增量输出,包括成对校准,因为它与较新的基于套接字的结果模型保持一致。将较旧的单个 rotationChange 字段视为传统兼容性输出。手动图像加载Python
1# 加载单个图像
2command_input.send(dai.DynamicCalibrationControl.loadImage())
3
4# 发送校准命令
5command_input.send(dai.DynamicCalibrationControl.calibrate(force=False))
6
7# 加载后获取校准
8calibration = calibration_output.get()
9print(f"Calibration = {calibration.info}")Python
1# 开始收集数据并尝试校准
2command_input.send(dai.DynamicCalibrationControl.startCalibration())
3
4while pipeline.isRunning():
5 # 阻塞读取
6 calibration = calibration_output.get()
7 print(f"Calibration = {calibration.info}")
8
9 # 非阻塞读取
10 calibration = calibration_output.tryGet()
11 if calibration:
12 print(f"Calibration = {calibration.info}")性能模式
Python
1# 设置性能模式
2dynCalibInputControl.send(
3 dai.DynamicCalibrationControl.setPerformanceMode(
4 dai.DynamicCalibrationControl.PerformanceMode.OPTIMIZE_PERFORMANCE
5 )
6)Python
1dai.DynamicCalibrationControl.PerformanceMode.OPTIMIZE_PERFORMANCE # 最严格的模式
2dai.DynamicCalibrationControl.PerformanceMode.DEFAULT # 宽松但通常足够
3dai.DynamicCalibrationControl.PerformanceMode.OPTIMIZE_SPEED # 优化速度而非性能
4dai.DynamicCalibrationControl.PerformanceMode.STATIC_SCENERY # 不严格
5dai.DynamicCalibrationControl.PerformanceMode.SKIP_CHECKS # 跳过所有内部检查
6dai.DynamicCalibrationControl.PerformanceMode.RELAXED_COVERAGE # 在校准操作前允许较低的覆盖率多传感器和 FFC 工作流程
- 使用
dynCalib.left和dynCalib.right作为主立体对。 - 可选地连接
dynCalib.rgb以实现 3 传感器工作流程,例如CAM_A + CAM_B + CAM_C。 - 当基线已知且只需校正方向漂移时,优先使用
keepCameraCenters=True。 - 对于自由形式重新校准,其中也必须解决平移问题,例如没有可靠基线的新 FFC 布局,请使用
keepCameraCenters=False。 - 从
coveragePerCell读取覆盖率,而不是假设只存在两个传感器。
示例
动态校准交互式可视化工具
使用以下命令,您可以克隆并运行校准集成。
Command Line
1git clone https://github.com/luxonis/depthai-core.git
2cd depthai-core/
3python3 -m venv venv
4source venv/bin/activate
5python3 examples/python/install_requirements.py
6python3 examples/python/DynamicCalibration/calibration_integration.py动态校准无法完全恢复工厂指定的绝对深度精度。请使用工厂工具进行生产级重新校准。
场景指南
- 包含多个深度的纹理对象。
- 避免空白墙壁或无特征表面。
- 缓慢移动相机以覆盖整个视场;避免突然移动。
| 建议 | 原始图像与特征覆盖(绿色) |
|---|---|
| ✅确保丰富的纹理和视觉细节 - 丰富的纹理、边缘和均匀分布在视场中的物体创造了理想的校准条件 | ![]() |
| 🚫避免平坦或无特征的表面 - 缺乏纹理表面或视觉上独特的物体提供的可用特征很少 | ![]() |
| 🚫避免反射和透明表面 - 反射和透明表面会产生错误的 3D 特征 | ![]() |
| 🚫避免黑暗场景 - 低对比度、阴影和光线不足的场景产生的可检测特征很少 | ![]() |
| 🚫避免重复图案 - 许多图案区域看起来太相似,难以区分 | ![]() |
PerformanceMode 调优
| 模式 | 何时使用 |
|---|---|
DEFAULT | 精度与速度平衡。 |
STATIC_SCENERY | 相机固定,场景稳定。 |
OPTIMIZE_SPEED | 最快的校准,精度降低。 |
OPTIMIZE_PERFORMANCE | 在特征丰富的场景中实现最大精度。 |
SKIP_CHECKS | 自动化管道,忽略保证场景质量的内部检查。 |
为了获得最高精度,请将 OPTIMIZE_PERFORMANCE 与动态、特征丰富的环境结合使用。
限制和注意事项
- 支持的设备 — 动态校准适用于:
- 所有立体 OAK Series 2 相机(不包括 FFC)
- 所有立体 OAK Series 4 相机
- DepthAI 版本 — 需要 DepthAI 3.0 或更高版本。
- 重新校准参数 — 仅更新外参; 内参保持不变。
- 操作系统支持 — 适用于 Linux、MacOS 和 Windows。
- 绝对深度规格 — DCL 提高了相对深度感知;绝对精度可能仍与原始工厂规格略有不同。
故障排除
| 症状 | 可能原因 | 修复 |
|---|---|---|
| 高重投影误差 | 板配置中模型名称或 HFOV 不正确 | 验证板 JSON 和相机规格 |
| “成功”DCL 后深度仍然不正确 | 左右相机交换 | 交换插座或更新板配置并重新校准 |
nullopt 质量报告 | 场景覆盖不足 | 移动相机以捕捉更丰富的纹理 |
运行时错误:"设备上的校准太旧,无法执行动态校准,需要完全重新校准!" | 设备校准太旧,动态重新校准无法提供任何好处。 | 需要更新的设备 |
另请参阅
- 动态校准一般信息页面
- 手动立体和 ToF 校准指南
- 如果您需要自动校准操作,请查看 AutoCalibration 文档页面。




