用 OpenCV 做相机标定：棋盘格与 ChArUco 完整代码

pip install "opencv-python>=4.7" numpy

calib/
├── calib_common.py        # 标定、结果报告、YAML 读写
├── calib_checkerboard.py  # 棋盘格标定
├── calib_charuco.py       # ChArUco 标定
├── undistort.py           # 去畸变
├── pose_check.py          # 求位姿、检查重投影误差
└── images/                # 标定图像

"""标定、结果报告与 YAML 读写（OpenCV 4.7+）。"""
import time

import cv2
import numpy as np


def calibrate_and_report(obj_points, img_points, image_size, names, flags=0):
    """标定并打印 RMS、参数及其标准差、误差最大的几张图。返回 (rms, K, dist)。"""
    (rms, K, dist, rvecs, tvecs,
     std_intr, std_extr, per_view) = cv2.calibrateCameraExtended(
        obj_points, img_points, image_size, None, None, flags=flags)
    n_pts = sum(len(p) for p in img_points)
    print(f"图像 {len(img_points)} 张，角点 {n_pts} 个，RMS 重投影误差 {rms:.4f} px")
    # std_intr 的顺序：fx fy cx cy k1 k2 p1 p2 k3 k4 k5 k6 s1 s2 s3 s4 τx τy
    labels = ["fx", "fy", "cx", "cy", "k1", "k2", "p1", "p2", "k3"]
    values = [K[0, 0], K[1, 1], K[0, 2], K[1, 2], *dist.ravel()[:5]]
    for name, v, s in zip(labels, values, std_intr.ravel()):
        print(f"  {name} = {v:12.6f}  ± {s:.6f}")
    worst = np.argsort(per_view.ravel())[::-1][:3]
    print("误差最大的 3 张：" + "，".join(f"{names[i]} {per_view[i, 0]:.3f} px" for i in worst))
    return rms, K, dist


def save_yaml(path, K, dist, image_size, rms, note=""):
    fs = cv2.FileStorage(path, cv2.FILE_STORAGE_WRITE)
    fs.write("calibration_time", time.strftime("%Y-%m-%d %H:%M:%S"))
    fs.write("note", note)
    fs.write("image_width", int(image_size[0]))
    fs.write("image_height", int(image_size[1]))
    fs.write("camera_matrix", K)
    fs.write("distortion_coefficients", dist)
    fs.write("rms_px", float(rms))
    fs.release()


def load_yaml(path):
    fs = cv2.FileStorage(path, cv2.FILE_STORAGE_READ)
    if not fs.isOpened():
        raise FileNotFoundError(path)
    K = fs.getNode("camera_matrix").mat()
    dist = fs.getNode("distortion_coefficients").mat()
    size = (int(fs.getNode("image_width").real()), int(fs.getNode("image_height").real()))
    fs.release()
    return K, dist, size

"""棋盘格标定：findChessboardCornersSB + calibrateCamera（OpenCV 4.7+）。
用法：python calib_checkerboard.py "images/*.png"
"""
import glob
import sys

import cv2
import numpy as np

from calib_common import calibrate_and_report, save_yaml

# ---- 按实际标定板修改 ----
SQUARES_X, SQUARES_Y = 11, 8      # 方格数（横向 × 纵向），不是角点数
SQUARE_MM = 25.0                  # 方格边长，mm
IMAGE_GLOB = sys.argv[1] if len(sys.argv) > 1 else "images/*.png"
# --------------------------

pattern = (SQUARES_X - 1, SQUARES_Y - 1)   # 内角点数 = 方格数 - 1
objp = np.zeros((pattern[0] * pattern[1], 3), np.float32)
objp[:, :2] = np.mgrid[0:pattern[0], 0:pattern[1]].T.reshape(-1, 2) * SQUARE_MM

# EXHAUSTIVE：检测更稳；ACCURACY：亚像素精度更高（较慢）。光照不均时可再加 CALIB_CB_NORMALIZE_IMAGE
flags = cv2.CALIB_CB_EXHAUSTIVE | cv2.CALIB_CB_ACCURACY
obj_points, img_points, names = [], [], []
image_size = None
for path in sorted(glob.glob(IMAGE_GLOB)):
    gray = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
    if gray is None:
        continue
    if image_size is None:
        image_size = gray.shape[::-1]          # (宽, 高)
    elif gray.shape[::-1] != image_size:
        sys.exit(f"{path} 的分辨率与其他图像不同")
    found, corners = cv2.findChessboardCornersSB(gray, pattern, flags=flags)
    if not found:
        print(f"[跳过] {path}：未检测到完整棋盘格")
        continue
    obj_points.append(objp)
    img_points.append(corners)
    names.append(path)

if len(img_points) < 10:
    sys.exit(f"有效图像只有 {len(img_points)} 张，至少需要 10 张（建议 15–30 张）")
rms, K, dist = calibrate_and_report(obj_points, img_points, image_size, names)
save_yaml("camera_checkerboard.yaml", K, dist, image_size, rms,
          note=f"checkerboard {SQUARES_X}x{SQUARES_Y} {SQUARE_MM} mm")
print("已保存 camera_checkerboard.yaml")

"""ChArUco 标定：CharucoDetector + matchImagePoints + calibrateCamera（OpenCV 4.7+）。
用法：python calib_charuco.py "images/*.png"
"""
import glob
import sys

import cv2

from calib_common import calibrate_and_report, save_yaml

# ---- 按实际标定板修改（与板上标签一致）----
SQUARES_X, SQUARES_Y = 11, 8          # 方格数（横向 × 纵向）
SQUARE_MM, MARKER_MM = 25.0, 18.75    # 方格边长、标记边长，mm
DICTIONARY = cv2.aruco.DICT_5X5_1000
LEGACY_PATTERN = False                # 仅当板子按 OpenCV 4.6 之前的规则生成且纵向方格数为偶数时设为 True
MIN_CORNERS = 8                       # 每张图至少需要的角点数
IMAGE_GLOB = sys.argv[1] if len(sys.argv) > 1 else "images/*.png"
# ------------------------------------------

CV_VERSION = tuple(int(v) for v in cv2.__version__.split(".")[:2])
dictionary = cv2.aruco.getPredefinedDictionary(DICTIONARY)
board = cv2.aruco.CharucoBoard((SQUARES_X, SQUARES_Y), SQUARE_MM, MARKER_MM, dictionary)
if LEGACY_PATTERN:
    board.setLegacyPattern(True)      # OpenCV 4.8 起提供
detector = cv2.aruco.CharucoDetector(board)

obj_points, img_points, names = [], [], []
image_size = None
for path in sorted(glob.glob(IMAGE_GLOB)):
    gray = cv2.imread(path, cv2.IMREAD_GRAYSCALE)
    if gray is None:
        continue
    if image_size is None:
        image_size = gray.shape[::-1]
    elif gray.shape[::-1] != image_size:
        sys.exit(f"{path} 的分辨率与其他图像不同")
    ch_corners, ch_ids, marker_corners, marker_ids = detector.detectBoard(gray)
    n = 0 if ch_ids is None else len(ch_ids)
    if n < MIN_CORNERS or board.checkCharucoCornersCollinear(ch_ids):
        print(f"[跳过] {path}：角点 {n} 个，不足或共线")
        continue
    if CV_VERSION >= (4, 8):
        obj, img = board.matchImagePoints(ch_corners, ch_ids)   # 按角点 ID 配对三维点与像点
    else:  # 4.7.x 的 CharucoBoard.matchImagePoints 有缺陷，直接按 ID 取角点的板坐标
        obj = board.getChessboardCorners()[ch_ids.ravel()].reshape(-1, 1, 3)
        img = ch_corners
    obj_points.append(obj)
    img_points.append(img)
    names.append(path)

if len(img_points) < 10:
    sys.exit(f"有效图像只有 {len(img_points)} 张，至少需要 10 张（建议 15–30 张）")
rms, K, dist = calibrate_and_report(obj_points, img_points, image_size, names)
save_yaml("camera_charuco.yaml", K, dist, image_size, rms,
          note=f"charuco {SQUARES_X}x{SQUARES_Y} {SQUARE_MM}/{MARKER_MM} mm")
print("已保存 camera_charuco.yaml")

$ python calib_charuco.py "images/charuco/*.png"
图像 20 张，角点 1168 个，RMS 重投影误差 0.0988 px
  fx =  1400.082656  ± 0.509335
  fy =  1398.691877  ± 0.472190
  cx =   965.088410  ± 0.513075
  cy =   598.313778  ± 0.513679
  k1 =    -0.209922  ± 0.000631
  k2 =     0.084476  ± 0.001519
  p1 =     0.000559  ± 0.000052
  p2 =    -0.000473  ± 0.000062
  k3 =    -0.011580  ± 0.001237
误差最大的 3 张：images/charuco/img_17.png 0.347 px，images/charuco/img_16.png 0.174 px，images/charuco/img_04.png 0.072 px
已保存 camera_charuco.yaml

$ python calib_checkerboard.py "images/checkerboard/*.png"
图像 20 张，角点 1400 个，RMS 重投影误差 0.0653 px
  fx =  1399.643084  ± 0.299660
  fy =  1398.112794  ± 0.292270
  cx =   964.652290  ± 0.308468
  cy =   597.496384  ± 0.279134
  k1 =    -0.209976  ± 0.000442
  k2 =     0.084172  ± 0.001378
  p1 =     0.000527  ± 0.000027
  p2 =    -0.000401  ± 0.000029
  k3 =    -0.010926  ± 0.001504
误差最大的 3 张：images/checkerboard/img_15.png 0.143 px，images/checkerboard/img_00.png 0.140 px，images/checkerboard/img_18.png 0.135 px
已保存 camera_checkerboard.yaml

%YAML:1.0
---
calibration_time: "2026-10-05 22:03:38"
note: "charuco 11x8 25.0/18.75 mm"
image_width: 1920
image_height: 1200
camera_matrix: !!opencv-matrix
   rows: 3
   cols: 3
   dt: d
   data: [ 1399.8680813405788, 0., 965.6048456126922, 0.,
       1398.4599648420738, 598.9485686496929, 0., 0., 1. ]
distortion_coefficients: !!opencv-matrix
   rows: 1
   cols: 5
   dt: d
   data: [ -0.21004663424619494, 0.084939668454632522,
       0.00058300578928788672, -0.00045062490225190887,
       -0.011936195358638548 ]
rms_px: 0.10582644798264869

"""读取 YAML 标定结果并对图像去畸变。
用法：python undistort.py camera_charuco.yaml input.png
"""
import sys

import cv2

from calib_common import load_yaml

K, dist, (w, h) = load_yaml(sys.argv[1])
img = cv2.imread(sys.argv[2])
if img is None or img.shape[1] != w or img.shape[0] != h:
    sys.exit("图像读取失败，或分辨率与标定时不一致（裁剪/binning 后需重新标定或换算内参）")

# alpha=0：裁掉边缘无效区域；alpha=1：保留全部原始像素（四周会出现黑边）
new_K, roi = cv2.getOptimalNewCameraMatrix(K, dist, (w, h), alpha=0)
# 同一相机反复处理时，映射表只需计算一次
map1, map2 = cv2.initUndistortRectifyMap(K, dist, None, new_K, (w, h), cv2.CV_16SC2)
out = cv2.remap(img, map1, map2, interpolation=cv2.INTER_LINEAR)
cv2.imwrite("undistorted.png", out)
print("新相机矩阵：\n", new_K.round(2))

"""用标定结果求 ChArUco 标定板位姿，画出检测结果与坐标轴，并手工计算重投影误差。
用法：python pose_check.py camera_charuco.yaml image.png
"""
import sys

import cv2
import numpy as np

from calib_common import load_yaml

K, dist, _ = load_yaml(sys.argv[1])
dictionary = cv2.aruco.getPredefinedDictionary(cv2.aruco.DICT_5X5_1000)
board = cv2.aruco.CharucoBoard((11, 8), 25.0, 18.75, dictionary)
detector = cv2.aruco.CharucoDetector(board)

img = cv2.imread(sys.argv[2])
ch_corners, ch_ids, _, _ = detector.detectBoard(cv2.cvtColor(img, cv2.COLOR_BGR2GRAY))
if ch_ids is None or len(ch_ids) < 6:
    sys.exit("角点太少")
obj = board.getChessboardCorners()[ch_ids.ravel()]          # 各版本通用的配对方式
ok, rvec, tvec = cv2.solvePnP(obj, ch_corners, K, dist)    # 标定板 -> 相机 的位姿

proj, _ = cv2.projectPoints(obj, rvec, tvec, K, dist)
err = np.linalg.norm(proj.reshape(-1, 2) - ch_corners.reshape(-1, 2), axis=1)
print(f"角点 {len(err)} 个，重投影 RMS {np.sqrt((err ** 2).mean()):.3f} px，最大 {err.max():.3f} px")
print("标定板原点在相机坐标系中的位置 (mm)：", tvec.ravel().round(1))

# OpenCV 5.0 的 detectBoard 返回 (N,2)/(N,)，4.x 返回 (N,1,2)/(N,1)；绘制前统一形状
cv2.aruco.drawDetectedCornersCharuco(img, ch_corners.reshape(-1, 1, 2), ch_ids.reshape(-1, 1), (0, 0, 255))
cv2.drawFrameAxes(img, K, dist, rvec, tvec, 50)             # 坐标轴长 50 mm
cv2.imwrite("pose.png", img)

$ python pose_check.py camera_charuco.yaml images/charuco/img_03.png
角点 70 个，重投影 RMS 0.061 px，最大 0.142 px
标定板原点在相机坐标系中的位置 (mm)： [-469.8 -130.3  637.5]