鱼眼摄像头畸变矫正这个活儿，我前后折腾过六七套方案。最早图省事，直接把普通镜头的针孔模型套上去，结果画面中心勉强能看，边角越矫越糊，直线变成波浪线；后来老老实实啃cv2.fisheye标定，又撞上“RMS 报得很漂亮、可画面还是歪的”这种玄学问题；再后来要做批量视频处理，标定流程太慢，逼着我搞了一套完全不依赖标定板的映射表方案，十分钟就能把一批素材全部拉直。Python 配 OpenCV 在这件事上其实已经相当成熟，但真正决定画面“能不能看”的，往往不是那几行 API 调用，而是模型选择、采样边界、参数标定这些脏活累活。
这篇内容讲的是鱼眼摄像头畸变矫正的两条实战路线：一条是基于棋盘格标定的物理建模法，另一条是基于等距投影假设的免标定重映射法。前者精度高、可逆、能反推真实光线方向，适合做三维重建、测距、视觉定位这类不能糊弄的场景；后者几乎零准备成本，改几个参数就能出图，适合视频转码、大屏预览、快速验证这类对绝对精度不敏感但对速度敏感的场合。无论你是刚拿到第一颗鱼眼模组、还在纠结棋盘格到底要几乘几的新手，还是已经在产线里跑矫正流水线、想搞明白为什么边缘总有一圈彩虹边的老手，下面这些内容应该都能直接抄走用。
1. 鱼眼畸变的物理本质与两条技术路线的分野
1.1 鱼眼镜头为什么“装得下”却“拉不直”
先得把一件事说清楚：鱼眼图像的弯曲不是“镜头做坏了”，而是几何上的必然妥协。
理想针孔模型的成像关系是r = f · tanθ，其中 θ 是物方入射光线与光轴的夹角，r 是像面上的成像高度，f 是焦距。这个式子有个致命问题：当 θ 逼近 90° 时，tanθ 趋于无穷大，意味着像面要无限大才能装下半视场 90° 的光线。所以纯针孔结构在物理上根本做不出 180° 视场。
鱼眼镜头的解法是换一种投影关系。最常见的是等距投影：r = f · θ。θ 和 r 变成线性关系，半视场角 180° 对应 r = f·π，像面尺寸完全可控。除此之外还有正交投影r = f·sinθ、等立体角投影r = 2f·tan(θ/2)等等，不同厂商会根据用途挑不同的映射曲线，有些甚至用混合模型。
打个生活化的比方：你想把一整个橘子皮平铺在桌面上，要么把它撕开几道口子，要么就得忍受它被强行拉伸变形。鱼眼镜头选了后者——它用“非相似成像”把 180° 甚至 200° 的世界压缩进一块小小的传感器，代价就是画面里的直线全部变成弧线，越靠边弯得越狠。这个“压缩”过程是确定性的、可逆的，所以矫正的本质不是“修复”，而是按已知的映射规则把像素搬回它该在的位置。
除了这种全局的桶形弯曲，实际模组还会叠加两类干扰：一是主点偏移，也就是光轴在传感器上的落点并不在图像几何中心，可能偏几十个像素；二是装配误差带来的切向畸变，镜头和传感器平面不完全平行时产生。这两样东西加起来，就是为什么“我按公式算出来还是歪的”的根源。
1.2 标定法与重映射法：一个求参数，一个套模型
两条路线的核心区别，在于畸变参数从哪儿来。
标定法的逻辑是：拿一块已知几何尺寸的棋盘格，在画面里摆各种姿势拍一堆照片，让算法去解一个最优化问题——什么样的内参矩阵 K 和畸变系数 D，能让“三维棋盘格角点投影到图像上”的位置和“实际检测到的角点位置”误差最小。解出来的 K 和 D 就是这颗镜头的“身份证”，之后所有去畸变操作都基于它。这条路的好处是有物理依据、可逆、能处理主点偏移和切向畸变；坏处是需要采集数据，而且标定质量几乎完全取决于采集质量。
重映射法的逻辑是：我不关心你这颗镜头具体偏了多少，我只假设你服从某条已知的投影曲线（比如等距投影），再根据画面尺寸和视场角反推出焦距，然后对输出图像的每一个像素，反算它应该去源图像的哪个位置采样。整个过程不需要任何标定板，只需要知道“这颗镜头的水平视场角大概是多少”。好处是快、零准备、批量友好；坏处是它假设了理想对称模型，一旦主点偏得厉害或者镜头本身不是纯等距投影，边缘就会露馅。
下面这张表是我自己选型时用的判断依据，可以直接对照：
| 对比维度 | 标定法（fisheye 模块） | 免标定重映射法 |
|---|---|---|
| 前期准备 | 需采集 15~25 张棋盘格图 | 只需知道视场角，或拍一条直线 |
| 单次耗时 | 采集 10 分钟 + 解算 10 秒 | 改参数 1 分钟 |
| 精度上限 | 亚像素级，可反投影验证 | 像素级，边缘误差较大 |
| 能否处理主点偏移 | 能，自动解出 | 需手工给 center 参数 |
| 能否处理切向畸变 | 能 | 不能 |
| 结果可逆性 | 可（能反算光线方向） | 弱（映射表可逆但无物理意义 |
| 典型用途 | 测距、三维重建、视觉定位 | 视频转码、预览、快速验证 |
我个人的经验是：只要这个项目里“像素位置”会参与任何几何计算，就老老实实走标定法；如果只是想把画面变得好看、让人眼能看懂，重映射法完全够用，而且省下来的时间可以用来干别的。
2. 方法一：棋盘格标定 + 去畸变完整落地
2.1 采集环节：这里翻车的概率比写代码高得多
我见过太多人代码写得一丝不苟，结果标定出来一塌糊涂，问题全出在采集上。这一节列的东西看起来琐碎，但每一条都是拿时间换来的。
棋盘格内角点数量千万别搞错。OpenCV 的pattern_size参数指的是内角点个数，不是格子数。一块 10×7 个格子的棋盘，内角点是 9×6。我第一次就填成 (10,7)，findChessboardCorners一直返回 False，调了两个小时以为是光照问题。
打印质量和平整度决定上限。用普通 A4 纸打印再用手拿着拍，纸面轻微弯曲就会让角点检测产生系统性偏差。正确做法是打印后贴在一块硬质平板上，或者直接买亚克力材质的标定板。表面要做哑光处理，反光的标定板在某个角度下角点会直接消失。
采集姿态要覆盖全画面。这是最容易被忽略的一条。很多人举着板子在画面正中央拍二十张，每张只转一点点角度。这样标出来的结果，中心区域误差极小，四个边角基本没约束，去畸变之后边缘依然是弯的——因为算法从来没见过边缘的数据。我的采集清单是这样的：
- 正对中心，板子占画面 1/3，拍 3 张；
- 板子移到画面左上、右上、左下、右下四个角，各拍 2~3 张，注意让板子的边角贴近画面边界；
- 板子倾斜 30°~45°，绕 X 轴和 Y 轴各来几组，覆盖不同朝向；
- 补几张板子占画面 1/2 的大特写，提升内参精度。
总量控制在 15~25 张。少于 12 张基本解不稳，多于 30 张收益递减还拖慢解算。
分辨率必须和实际使用一致。用 1920×1080 采集、用 1280×720 去畸变，内参直接用会全体偏移。要么统一分辨率，要么按比例缩放 K（下面 4.3 节会讲具体算法）。
注意：采集时不要让标定板被画面边界裁掉，角点检测需要完整的棋盘区域。板子贴边可以，但四个外角必须完整可见。
2.2 标定代码逐段拆解与参数含义
代码不长，但每一行都有讲究。先看完整实现：
import cv2 import numpy as np import glob # 内角点数量，不是格子数 PATTERN = (9, 6) SQUARE_SIZE = 25.0 # 单格实际边长，单位毫米，只影响平移量，不影响内参 # 构造棋盘格的三维坐标（Z=0 平面） objp = np.zeros((PATTERN[0] * PATTERN[1], 1, 3), np.float64) objp[:, 0, :2] = np.mgrid[0:PATTERN[0], 0:PATTERN[1]].T.reshape(-1, 2) * SQUARE_SIZE objpoints, imgpoints = [], [] criteria_sub = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 1e-6) for fname in sorted(glob.glob("calib/*.jpg")): img = cv2.imread(fname) gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) ok, corners = cv2.findChessboardCorners( gray, PATTERN, flags=cv2.CALIB_CB_ADAPTIVE_THRESH | cv2.CALIB_CB_NORMALIZE_IMAGE) if not ok: print("角点检测失败，跳过:", fname) continue corners = cv2.cornerSubPix(gray, corners, (5, 5), (-1, -1), criteria_sub) objpoints.append(objp) imgpoints.append(corners) h, w = gray.shape[:2] K = np.eye(3, dtype=np.float64) D = np.zeros((4, 1), dtype=np.float64) flags = (cv2.fisheye.CALIB_RECOMPUTE_EXTRINSIC | cv2.fisheye.CALIB_FIX_SKEW | cv2.fisheye.CALIB_CHECK_COND) rms, K, D, rvecs, tvecs = cv2.fisheye.calibrate( objpoints, imgpoints, (w, h), K, D, flags=flags, criteria=(cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 100, 1e-6)) print("RMS 重投影误差:", rms) print("内参 K:\n", K) print("畸变系数 D:\n", D.ravel()) np.savez("fisheye_calib.npz", K=K, D=D, size=(w, h))几个参数必须解释清楚，否则你只会复制粘贴，出了问题无从下手。
CALIB_FIX_SKEW的作用是假设图像传感器的 x、y 轴严格正交（skew 系数为 0）。现代 CMOS 传感器这个假设几乎总成立，加上它能减少一个自由度、提升解的稳定性。除非你怀疑镜头模组装配有明显倾斜，否则一直开着。
CALIB_RECOMPUTE_EXTRINSIC让每次迭代都重新计算每张图的外参（旋转和平移），而不是沿用上一轮的结果。鱼眼畸变模型是非线性的，外参不重算很容易在迭代中漂移，导致某些图的重投影误差突然爆炸。
CALIB_CHECK_COND是个“保险丝”，会在条件数过高（也就是解病态）时直接抛出异常。调试阶段强烈建议开着，它能让你第一时间发现“某几张图的姿态太相似，等于没提供新信息”这类问题。稳定之后再考虑关掉，因为它在某些边缘情况下会误报。
还有一个容易踩的坑：objpoints和imgpoints的数据类型。fisheye.calibrate内部对这两个数组的类型很挑剔，objpoints里每个元素必须是(N, 1, 3)形状的float64，imgpoints里的角点必须是(N, 1, 2)形状。类型不对会直接触发断言失败，报错信息还特别含糊，只说Assertion failed，不告诉你是哪一步。我建议统一用np.float64构造，别偷懒。
2.3 怎么判断标定结果是真的好还是“数字好看”
RMS 重投影误差是最容易误读的指标。它是所有角点重投影误差的均方根，单位是像素。经验上：小于 0.3 属于优秀，0.3~0.8 可以接受，超过 1.0 就得回去查采集数据了。
但 RMS 有个陷阱：它是全局平均值，会掩盖局部问题。你完全可能拿到一个 0.25 的漂亮 RMS，实际上去畸变之后边缘依然弯得离谱——原因是那几张覆盖边缘的图误差被中心那十几张低误差图平均掉了。
所以我的做法是逐图看误差：
proj_errs = [] for i in range(len(objpoints)): proj, _ = cv2.fisheye.projectPoints( objpoints[i], rvecs[i], tvecs[i], K, D) err = cv2.norm(imgpoints[i], proj, cv2.NORM_L2) / len(proj) proj_errs.append(err) print(f"图 {i:02d} 重投影误差: {err:.4f} px") proj_errs = np.array(proj_errs) print("最大误差:", proj_errs.max(), "对应图号:", proj_errs.argmax())跑完这段，如果发现某几张图的误差是其他图的五倍以上，基本可以断定那几张图的角点检测有问题——可能是反光、可能是运动模糊、也可能是板子被裁掉了一角。直接把这几张从objpoints/imgpoints里剔掉重跑，通常 RMS 和实际效果都会一起改善。
还有一个更直观的定性检查：把矫正后的图打出来，找一条现实世界里确实笔直的线（墙角、桌沿、门框），看它在矫正后是否真的直了。像素指标是给机器看的，最终验收还是得靠眼睛。
2.4 生成映射表与 balance 参数的取舍
标定完拿到 K 和 D，下一步是去畸变。很多教程直接用cv2.fisheye.undistortImage，一行搞定。但这个方法内部每次调用都会重新计算映射表，处理视频流时性能会很难看。正确做法是一次性构建映射表，然后循环 remap：
data = np.load("fisheye_calib.npz") K, D, (w, h) = data["K"], data["D"], tuple(data["size"]) balance = 0.0 # 0 = 保留全部原始像素（黑边多），1 = 裁掉黑边（视野变窄） new_K = cv2.fisheye.estimateNewCameraMatrixForUndistortRectify( K, D, (w, h), np.eye(3), balance=balance, new_size=(w, h), fov_scale=1.0) map1, map2 = cv2.fisheye.initUndistortRectifyMap( K, D, np.eye(3), new_K, (w, h), cv2.CV_16SC2) img = cv2.imread("test.jpg") undist = cv2.remap(img, map1, map2, interpolation=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0, 0, 0))balance这个参数值得单独说。它控制新相机矩阵的焦距取值：balance=0时取允许范围内的最小焦距，画面保留全部源像素，代价是四角出现大面积黑色空洞；balance=1时取最大焦距，黑边被裁干净，但视野明显收窄，边缘的画质损失也被放大。
实际项目里我一般取0.2~0.4，在“视野够用”和“黑边不至于太丑”之间找平衡。如果你的下游任务是目标检测，黑边其实无所谓，取 0 让网络看到更多有效像素更好；如果是要给人看的预览画面，取 0.5 左右裁得干净些。
new_size也可以设得比原图小，比如(w//2, h//2)，这样输出的画面没有黑边，实际有效分辨率反而更高——因为黑边占的那部分像素本来就是空的。这个技巧在带宽受限的场景里特别好用。
3. 方法二：基于等距投影的免标定重映射
3.1 从输出像素反推源像素：一次完整的推导
这条路的思路和标定法正好相反。标定法是“先算参数、再算映射”，重映射法是“直接构造映射”。
核心等式只有两个。源图像侧，等距投影假设下，像面上的点到主点的距离 r 与入射角 θ 成线性关系：
r = f_src · θ输出图像侧，我们希望输出是一张正常的透视（针孔）图，那么输出像素到画面中心的距离 d 和该像素对应的入射角 θ 满足：
d = f_out · tanθ把两式联立，就能从输出像素的坐标反推出 θ，进而算出源图像上的采样位置：
θ = arctan(d / f_out) r = f_src · θ u_src = cx + r · cos(φ) v_src = cy + r · sin(φ)其中 φ 是该像素相对中心的方位角，arctan2直接给出。
两个焦距怎么定？f_src由源镜头的视场角决定。等距模型下，画面半宽对应半视场角，所以：
f_src = (src_w / 2) / radians(fov_deg / 2)f_out则由你希望输出画面覆盖多大视场角决定：
f_out = (out_w / 2) / tan(radians(out_fov_deg / 2))这两个式子里的fov_deg就是这颗镜头的水平视场角，说明书上一般会写；没有说明书就按 180° 估，然后用下面 3.3 节的手工调参法修正。
提示：这个推导只对“圆对称”的鱼眼成立——也就是畸变只跟到主点的距离有关，跟方向无关。绝大多数鱼眼模组满足这个假设，但如果你的镜头是那种非对称的超广角（比如某些车载广角），边缘会有方向性的拉伸，这条路会露馅。
3.2 完整实现：30 行代码构建映射表
把推导翻译成代码，就是下面这段。注意所有中间计算都用float32，最后返回的map_x/map_y直接喂给cv2.remap：
import numpy as np import cv2 def build_equidistant_maps(src_size, fov_deg=180.0, out_size=None, out_fov_deg=90.0, center=None): """ src_size : (w, h) 源鱼眼图尺寸 fov_deg : 源镜头水平视场角，典型值 180 out_size : (w, h) 输出尺寸，None 则与源尺寸相同 out_fov_deg : 期望输出画面的水平视场角，越小越聚焦中心 center : (cx, cy) 主点，None 则取图像几何中心 """ sw, sh = src_size ow, oh = out_size if out_size is not None else (sw, sh) cx, cy = center if center is not None else ((sw - 1) / 2.0, (sh - 1) / 2.0) f_src = (sw / 2.0) / np.deg2rad(fov_deg / 2.0) f_out = (ow / 2.0) / np.tan(np.deg2rad(out_fov_deg / 2.0)) xs = np.arange(ow, dtype=np.float32) - (ow - 1) / 2.0 ys = np.arange(oh, dtype=np.float32) - (oh - 1) / 2.0 X, Y = np.meshgrid(xs, ys) theta = np.arctan(np.sqrt(X * X + Y * Y) / f_out) phi = np.arctan2(Y, X) r = f_src * theta map_x = (cx + r * np.cos(phi)).astype(np.float32) map_y = (cy + r * np.sin(phi)).astype(np.float32) return map_x, map_y # 使用示例 img = cv2.imread("fisheye_test.jpg") h, w = img.shape[:2] mx, my = build_equidistant_maps((w, h), fov_deg=180.0, out_size=(w, h), out_fov_deg=95.0) undist = cv2.remap(img, mx, my, cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(20, 20, 20)) cv2.imwrite("undist_free.jpg", undist)验证一下边界情况是否合理：输出画面中心 (X=0, Y=0) 时 θ=0、r=0，映射回源图主点，位置正确；输出画面右边界中点 X = ow/2 时，X/f_out = tan(radians(out_fov_deg/2))，反解出的 θ 正好等于radians(out_fov_deg/2)，也就是“输出图水平方向覆盖的入射角范围确实是 out_fov_deg”。这个自洽性检查很有必要，改参数前跑一遍能省不少事。
3.3 不知道视场角怎么办：直线约束的土办法
现实里最常见的窘境是：手上这颗模组是拆机件，根本查不到视场角参数。这时候有一个特别土但极其有效的办法——用直线约束反推焦距。
原理很简单：现实世界里的直线，在矫正之后必须还是直线。所以你可以拍一张包含长直边（墙角、门框、桌子边缘）的图，然后手动滑动视场角参数，看哪条直线最先被拉直。参数太小，画面会向里凹；参数太大，直线会向外鼓。调到刚刚好的那个值，就是这颗镜头的等效视场角。
写成半自动脚本也不复杂，用cv2.createTrackbar挂一个 150~220 的滑条，实时 remap 显示：
import cv2 import numpy as np img = cv2.imread("line_test.jpg") h, w = img.shape[:2] cv2.namedWindow("tune") cv2.createTrackbar("fov", "tune", 180, 220, lambda v: None) while True: fov = cv2.getTrackbarPos("fov", "tune") mx, my = build_equidistant_maps((w, h), fov_deg=float(fov), out_fov_deg=90.0) out = cv2.remap(img, mx, my, cv2.INTER_LINEAR) cv2.putText(out, f"fov={fov}", (20, 40), cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2) cv2.imshow("tune", out) if cv2.waitKey(30) == 27: break cv2.destroyAllWindows()这个方法我用来标定过七八颗来源不明的模组，直线拉直之后的视场角普遍在 175~195 之间，跟后续用棋盘格标定法解出来的值相差不超过 5°。对于只看效果不看精度的场景，完全够用。
同样地，如果画面中心明显偏了（比如镜头装歪，主点跑到 55% 宽度处），也可以在这套脚本里加热键微调center参数。判断标准是：把画面正中央对准一个明确的点状目标，然后左右上下微调 center，直到这个点在输出图里依然位于正中心。
3.4 这条路什么时候会翻车
免标定方案不是万能的，我踩过的边界很明确，列出来供你判断：
主点偏移大且无法手工修正的场景。如果主点偏了 50 像素以上，你又没法用交互式调参确认位置，输出画面会整体旋转或拉伸，直线看起来还是歪的，只是歪的方式变了。这时候老实用标定法。
镜头不是纯等距投影的场景。有些广角模组用的是r = f·tan(θ/2)这类等立体角投影，或者干脆是混合模型。用等距模型硬套，画面会呈现“中心正常、中间段压扁、边缘又拉伸”的分层感。补救办法是把build_equidistant_maps里的r = f_src * theta换成r = f_src * np.sin(theta)（正交模型）或者r = 2 * f_src * np.tan(theta / 2)（等立体角模型），三种模型各试一遍，看哪种直线拉得最直就用哪种。我把这个小技巧叫做“三模型试错法”，实测大概能覆盖九成以上的常见模组。
解析度不足以支撑大视场展开的场景。这是个物理限制，不是算法问题。鱼眼图边缘的像素被极度压缩，原本 1 个像素代表的立体角在边缘可能只有中心的五分之一。当你把边缘区域展开放大到输出画面里，本质上是在做插值放大，画质必然下降。out_fov_deg设得越大，边缘被放大的比例越高，模糊和锯齿越明显。我的经验值是：1280 宽的源图，out_fov_deg不要超过 110°，否则边缘画质会难看到没法用。
4. 视频流场景下的工程化处理
4.1 映射表复用与分辨率迁移
视频处理和单张图片的最大区别是：映射表绝对不能每帧重算。initUndistortRectifyMap或者build_equidistant_maps的开销在几十毫秒量级，每帧调一次，帧率直接就废了。
正确的结构是：启动时算一次，存进内存，之后每帧只做remap这一件事：
class FisheyeUndistorter: def __init__(self, mode, **kwargs): self.map1 = None self.map2 = None self.mode = mode self.kwargs = kwargs def prepare(self, src_size, out_size): sw, sh = src_size ow, oh = out_size if self.mode == "calib": K, D = self.kwargs["K"], self.kwargs["D"] new_K = cv2.fisheye.estimateNewCameraMatrixForUndistortRectify( K, D, (sw, sh), np.eye(3), balance=self.kwargs.get("balance", 0.3), new_size=(ow, oh)) self.map1, self.map2 = cv2.fisheye.initUndistortRectifyMap( K, D, np.eye(3), new_K, (ow, oh), cv2.CV_16SC2) else: self.map1, self.map2 = build_equidistant_maps( (sw, sh), fov_deg=self.kwargs.get("fov_deg", 180.0), out_size=(ow, oh), out_fov_deg=self.kwargs.get("out_fov_deg", 95.0), center=self.kwargs.get("center")) return self def __call__(self, frame): return cv2.remap(frame, self.map1, self.map2, interpolation=cv2.INTER_LINEAR, borderMode=cv2.BORDER_CONSTANT, borderValue=(0, 0, 0))内存上有一点要注意：CV_16SC2格式的映射表，两个通道各占 2 字节，加上map2的 2 字节，1280×720 大概占 4~5 MB。如果你要同时处理多路视频，或者分辨率上到 4K，这个开销就值得算一算了。§4.2 里的优化手段会提到怎么压。
4.2 性能数据与几个提速手段
我在一台普通的四核笔记本 CPU 上测过，1280×720 的cv2.remap，INTER_LINEAR插值，单帧耗时大约 3~6 ms。也就是说纯 remap 环节理论上能跑到 160 fps 以上，瓶颈通常不在这一步，而在解码和后续处理。
如果确实觉得不够快，下面几个手段是按“性价比”排序的：
| 手段 | 效果 | 代价 |
|---|---|---|
| 映射表用 CV_16SC2 而非 CV_32FC2 | 提速约 30%，内存减半 | 无，精度足够 |
| 插值改 INTER_NEAREST | 再提速 40% | 边缘锯齿明显，慎用 |
| 输出尺寸降为源图的 1/2 | 提速约 3 倍 | 有效分辨率下降 |
| 启用 OpenCL（UMat） | 视显卡而定，2~5 倍 | 首次编译有开销，需硬件支持 |
| 多进程分发到多个核 | 接近线性扩展 | 帧序需要自己维护 |
我个人最常用的是第一条。CV_16SC2用的是定点数表示坐标，配合map2存插值权重，精度损失肉眼几乎看不出来，但速度提升实实在在。只有在做亚像素级几何测量时才需要回到CV_32FC2。
第二条我不太推荐——鱼眼矫正之后边缘本来就已经是插值放大的模糊区域，再用最近邻采样，锯齿会非常刺眼。真追求速度不如走第三条，直接降分辨率输出。
4.3 标定结果跨分辨率迁移的正确姿势
这个坑我必须单独说，因为踩得太疼了。
标定是在 1920×1080 下做的，现在要处理 1280×720 的流，能不能直接把 K 和 D 拿来用？答案是：D 可以，K 不行。
原因在于畸变系数 D 是在归一化像平面坐标下定义的，跟你用多大分辨率采样无关。但内参矩阵 K 里的fx, fy, cx, cy都是像素单位的量，分辨率一变，它们必须按比例缩放：
def scale_intrinsics(K, D, scale): """把标定内参从原分辨率等比缩放到 scale 倍的分辨率""" K_new = K.copy() K_new[0, 0] *= scale # fx K_new[1, 1] *= scale # fy K_new[0, 2] *= scale # cx K_new[1, 2] *= scale # cy return K_new, D.copy() # D 保持不变 # 从 1920x1080 标定结果迁移到 1280x720 K_new, D_new = scale_intrinsics(K, D, 1280.0 / 1920.0)如果缩放比例不是整数关系（比如从 1920 缩到 1000），按这个公式算出来的结果依然正确，因为它是纯线性缩放。唯一需要注意的是cx, cy的缩放基准：严格来说主点坐标的缩放应该用(new_w - 1) / (old_w - 1)而不是new_w / old_w，两者差别极小，一般可以忽略，但如果你的分辨率很低（比如 320 宽），这个半像素的偏差就会显现出来。
还有一点：缩放之后new_K也要重新用estimateNewCameraMatrixForUndistortRectify算，别把老的分辨率下的new_K硬套上去，否则画面会被莫名其妙地裁掉一块。
5. 常见问题速查与踩坑实录
5.1 现象、根因与对策对照表
下面这张表是我这几年攒下来的问题库，基本都是“报错信息完全看不出原因”的那类：
| 现象 | 最可能的根因 | 对策 |
|---|---|---|
findChessboardCorners全部返回 False | pattern_size填成了格子数 | 改成内角点数，9×6 格子填 (8,5) |
| 同上，只对部分图成功 | 反光或运动模糊 | 换哑光板、提高快门、降低增益 |
fisheye.calibrate断言失败 | objpoints或imgpoints类型/形状不对 | 统一用(N,1,3)的float64 |
| RMS 很低但边缘仍弯 | 采集姿态覆盖不全 | 补拍四角贴边的图，剔除高误差图重跑 |
| 矫正后画面整体倾斜 | 主点解偏或采集时板子姿态单一 | 加CALIB_FIX_PRINCIPAL_POINT重跑对比 |
| 矫正后四角大片黑边 | balance取 0 | 调到 0.3~0.5，或缩小new_size |
| 边缘出现彩色条纹 | remap 采样越界，读到非法内存 | 设BORDER_CONSTANT并指定borderValue |
| 视频帧率只有个位数 | 每帧重算映射表 | 改成启动时算一次，循环复用 |
| 换分辨率后画面偏移 | K 未按比例缩放 | 用scale_intrinsics缩放 fx/fy/cx/cy |
| 免标定方案边缘分层 | 投影模型选错 | 等距/正交/等立体角三种模型逐一试 |
5.2 几个只有真动手才会知道的经验
第一条：标定板不要用手拿着。我最早图方便，一只手举着板子一只手点鼠标，结果那一批图的误差普遍在 1.2 像素以上。后来换成用夹子固定在桌面支架上，同样的代码同样的板子，误差直接降到 0.4。人的手在按快门那一刻的微小抖动，在高频角点检测面前是藏不住的。
第二条：cornerSubPix的窗口大小别乱设。默认的(11,11)在低分辨率图上容易把邻近的角点也卷进来，导致检测出来的角点位置“粘”在一起。我用(5,5)或者(7,7)更多，尤其当标定板在画面里占比很小时。这个参数的影响在 RMS 上不一定马上显现，但在去畸变的边缘区域会明显表现出来。
第三条：不要迷信balance=1的“干净画面”。新手常见的心理是“我受不了黑边，必须裁干净”。但balance=1时，原本位于画面最外圈的鱼眼信息被整块裁掉，实际可用视场可能从 180° 掉到 120° 以下。如果你的应用需要广角监控，这个损失是致命的。宁可有黑边，也别把视野裁没了——黑边可以在后续做裁剪或者填充，信息丢了就真没了。
第四条：两种方法可以混着用。我最近一个项目就是这么干的：先用免标定法快速出一版效果图给产品经理确认视觉方向（十分钟），确认之后再走完整标定流程出正式版本（半天）。前者用来沟通，后者用来交付，节奏上舒服很多。另外，免标定法调出来的 fov 值，其实可以当作标定法的CALIB_USE_INTRINSIC_GUESS初值——用f_src反推fx，能显著减少标定迭代陷入局部最优的概率。
第五条：一定要留一份原始数据和标定结果的存档。标定文件（K、D、分辨率）和采集用的那批原图，一起打包存起来，命名里带上镜头编号和日期。我吃过一次亏——产线上十几颗镜头混在一起，标定文件全叫calib.npz，最后完全分不清哪个是哪个，只能全部重来。后来改成lens_03_20240315.npz这种命名，再也没出过事。
最后再分享一个我常用来快速验证映射表质量的小动作：把map_x和map_y各自归一化到 0~255 存成灰度图，看一眼。正常情况下这两张图应该是平滑的渐变，中心一个亮点向外扩散。如果看到明显的折痕、突变或者大片同色区域，说明映射表里有折叠或者越界，这时候别急着看矫正结果，先去查参数——因为你在彩色图上很可能根本看不出来，只会在某些特定角度下突然发现画面被撕裂了一块。这个检查只要两秒钟，但能帮你省掉大半天。
