16工程契约数值诊断系统排错上线门禁

Engineering Implementation & Debugging

从“结果不对”到
可复现的责任层

6D 系统最昂贵的错误往往不是公式不会，而是两个都“合理”的模块对同一数组赋予不同语义。本专题把隐式假设提升为 machine-checkable contract，并用独立证据定位第一失败层。

打开故障注入实验室先冻结 artifact contract

十秒版

先记住七条

01
先查 contract，再调算法：frame、方向、单位、ordering、像素域、timestamp 和 asset hash。
02
合法数值也可能语义错误：det=1、q norm=1、round-trip=0 抓不到 inverse、wxyz 或 degree/radian。
03
图像变换必须带着 K 和标签走：crop、resize、pad、flip、畸变域与 pixel convention。
04
低 residual 不等于正确：退化、多解、outlier、ICP local basin 和 reflection 都可拟合得很好。
05
静态/动态、近/远、中心/边缘 A/B 比盲目换模型更快定位 calibration、time、K 或 distortion。
06
真值必须独立：同一 pipeline 生成的 overlay、label 和 closure 可能一起错。
07
失败是数据：NaN、timeout、no-solution、stale 与 abstain 有显式 status、owner 和 denominator。

01 · Artifact Contract

每个数组都要能回答：它是谁、在哪个 frame、什么单位、何时有效、由什么版本产生

不要靠变量名和团队默契传递物理语义。数据落盘、消息传输、缓存、模型输入输出和机器人接口都使用同一可验证 manifest。

字段组	至少声明	禁止的隐含假设
Identity	sample / scene / object / instance / camera / robot / task IDs	字符串和整数也要有 namespace；数组下标不能偷偷充当 object ID
Transform	from/to frame、map direction、active/passive、column/row、handedness	`extrinsic`、`camera_pose`、`T` 都不是充分字段名
Rotation	matrix / quaternion / axis-angle / Euler；xyzw/wxyz；Euler sequence 与 intrinsic/extrinsic	quaternion norm=1 或 det=1 只证明数值合法，不证明 convention 相同
Translation	unit、origin、reference point、scale policy 与 valid range	m/mm、CAD unit 与 normalized object scale 必须在边界换算一次
Camera	resolution、K/D/P、distortion model、raw/rectified domain、ROI/binning	每个 image/tensor 使用与自己像素域一致的 camera model
Image transform	crop/resize/pad/flip/rotate 的顺序、参数、interpolation 与 pixel convention	image、mask、keypoint、bbox、flow、depth、normal 和 pose label 同步
Depth / modality	encoding、unit/depth_scale、invalid/no-return、registered-to、timestamp/clock	同尺寸不代表 RGB-D 已对齐；0、NaN、±Inf 的语义不能猜
Asset	CAD hash/version、unit、origin、axes、diameter、symmetry、mesh/texture/collision variants	可视化 mesh、evaluation mesh、collision mesh 和 network template 可能不同
Estimate	timestamp、source/model/config/checkpoint/preprocess hash、score/uncertainty/status	NaN、timeout、no-solution 与 abstain 是显式状态，不可伪造成 identity pose
Runtime	library/driver/device/precision、seed/determinism、latency、valid interval	同 seed 不保证跨 release、CPU/GPU 或 nondeterministic kernel 完全复现

Typed SE(3) artifact, not an anonymous 4×4 array

{}^{A}\mathbf T_B(t)=\begin{bmatrix}{}^{A}\mathbf R_B(t)&{}^{A}\mathbf t_B(t)\\\mathbf0^{\mathsf T}&1\end{bmatrix},\qquad \mathbf p_A={}^{A}\mathbf T_B\,\mathbf p_B

字段同时携带 from=B、to=A、column-vector mapping、right-handed、translation unit、timestamp/clock、source/version 与 validity。矩阵值本身无法恢复这些元数据。

Pose artifact manifest · 最小可执行示例

pose:
  map: object -> camera_optical      # {}^C T_O
  vector: column · active · right_handed
  rotation: matrix3x3 · row_major_storage · projected_to_SO3=false
  translation_unit: metre
  timestamp: exposure_time · clock=camera_hw · valid_until=...
camera: image_domain=rectified · width/height · P_hash · preprocess_hash
asset: object_id · mesh_hash · unit=millimetre · origin_hash · symmetry_hash
producer: model/checkpoint/config/code hashes · dtype/device · status
quality: score_semantics · covariance_perturbation · failure_reason

02 · Evidence Ladder & Differential Diagnosis

从最便宜、最确定的检查开始；在第一失败层停止扩散

一次只改变一个因素，保存输入和证据，并为每个现象提出至少两个竞争假设。最终 optimizer log 没有资格越过更早的 schema / geometry gate。

L0 · File / transport

路径、key、shape、dtype、endianness、finite、row stride、message timestamp

文件计数/checksum、schema validator、first non-finite index

L1 · Contract

frame、direction、unit、ordering、pixel/depth domain、asset lineage

manifest diff、sentinel transform、unit/range assertions

L2 · Algebra

SO(3)/SE(3)、bottom row、inverse/compose、quaternion norm、reflection

RᵀR、det、T·T⁻¹、known point、Jacobian finite difference

L3 · Sensor geometry

K/D/P、crop/resize、RGB-D registration、cheirality、render domain

project↔back-project、raw↔rectified A/B、depth histogram

L4 · Observation

correspondence、visibility、mask、point support、symmetry mode、timestamp

matches overlay、per-point residual、static/dynamic and near/far slices

L5 · Solver

degeneracy、conditioning、initial basin、robust sampling、termination、multi-solution

spectrum/condition、top-K solutions、seed/init sweep、held-out residual

L6 · System

hand-eye/TCP、TF graph、latency、cache/version、thread/queue、robot state

fixed target closure、speed reversal、cold start、artifact atomic-load test

L7 · Task

grasp/contact/clearance/insertion/safety outcome 与 recovery

pose/grasp/motion oracle、hardware sentinel、failure-stage denominator

Static ↔ dynamic

只在运动时坏

优先查 timestamp、clock、rolling shutter、latency、robot interpolation 与 compliance，而非静态 K。

Near ↔ far

误差随距离增长

优先查 focal/scale/depth model；固定像素偏移更像 principal point / crop / pad。

Center ↔ edge

边缘呈径向结构

优先查 distortion/rectification 和 pixel domain；全图固定偏移更像 K′/frame。

Cold ↔ warm / old ↔ new

启动或版本相关

优先查 cache、partial deploy、config shadowing、device/precision 和 nondeterminism。

Interactive Lab

注入一个故障，看哪些检查能抓住它、哪些“好指标”仍会通过

第一栏展示合法矩阵的语义错误；第二栏实际复合 pixel affine、K 和 depth back-projection；第三栏用第一失败 gate 路由 PnP、ICP、时间、NaN、reflection 与版本问题。

reference contract decoded artifact invalid / behind camera 低 round-trip error 只证明代数自洽，不证明 frame、单位或语义正确

Schema contract

metadata before math

——

SO(3) invariants

‖RᵀR−I‖F / det R

——

Geometry

positive depth / translation

——

Independent overlay

reference reprojection RMSE

—独立 2D observation，不复用待测 pose 生成标签

Algebraic closure

T · T⁻¹

—错误方向、单位和 quaternion 仍可完美可逆

Route

—

——

先验证 contract，再验证数值。 det=1、正交、quaternion norm=1 都无法识别“合法但语义错误”的旋转；必须再用已知点、真实图像、固定 target、robot touch 或独立传感器做 semantic sentinel。

03 · Transform, Rotation & Numerical Hygiene

不变量负责拒绝非法值；sentinel 负责拒绝错误语义

旋转正交化是恢复 manifold 的数值操作，不是修复 frame、单位或标签的万能胶。每次自动 correction 都应计数并设置幅度门禁。

SO(3) input gate

\|\mathbf R^{\mathsf T}\mathbf R-\mathbf I\|_F<\varepsilon_R,\qquad |\det\mathbf R-1|<\varepsilon_d,\qquad \operatorname{isfinite}(\mathbf R,\mathbf t)

阈值依赖 dtype 与链长度。det≈−1 是 reflection；det≈1 仍无法判断 active/passive、frame direction、Euler order 或 quaternion ordering。

Nearest proper rotation after SVD

\mathbf M=\mathbf U\boldsymbol\Sigma\mathbf V^{\mathsf T},\qquad \Pi_{\mathrm{SO}(3)}(\mathbf M)=\mathbf U\,\operatorname{diag}\!\left(1,1,\det(\mathbf U\mathbf V^{\mathsf T})\right)\mathbf V^{\mathsf T}

最后一项阻止 reflection。若 correction 很大，应 block 并追查模型/积分，而非静默投影后继续。

Quaternion normalization and sign-invariant comparison

\bar{\mathbf q}=\mathbf q/\|\mathbf q\|_2,\qquad d_{\mathrm{SO}(3)}(\mathbf q,\hat{\mathbf q})=2\arccos\!\left(\operatorname{clip}(|\mathbf q^{\mathsf T}\hat{\mathbf q}|,0,1)\right)

先确认 component ordering 和 rotation convention；q 与 −q 是同一 rotation。normalize 无法修复 wxyz/xyzw。

问题	典型 signature	最小隔离实验 / 修复
m ↔ mm / deg ↔ rad	translation 恰差 10³；角度随输入周期跳变但 R 仍正交	接口内部只用 SI；字段名携带单位；range histogram + known baseline
T_AB ↔ T_BA	axes 朝向合理但物体在相机后、机器人走反方向	用一个非原点 known point 验证 map direction；不要只测 T·T⁻¹
左乘 ↔ 右乘 / 行 ↔ 列	单变换正常，组合两条边后才错；translation 被错误旋转	冻结列向量契约；用非交换 transforms 做 compose unit test
active ↔ passive	数值像 inverse/transpose；Euler 符号整体相反	写“向量被旋转”还是“基被改变”，并给物理 axes sentinel
right ↔ left handed	mirror overlay、法向/三角面翻转、det=-1 或隐式轴翻转后 det=1	每次 handedness conversion 显式矩阵化，检查 winding / normal / image axes
xyzw ↔ wxyz	R 仍合法，某些特殊旋转甚至碰巧正确	序列化用具名字段或 scalar_first；测试 identity 与非对称 sentinel quaternion
q ↔ −q	逐元素 quaternion loss / 插值突然跳，但旋转矩阵相同	比较用 \|qᵀq̂\| 或 SO(3) geodesic；序列可 canonicalize 但保留 double-cover 语义
Euler 顺序	同三个角生成完全不同姿态；接近 gimbal lock 不连续	API 记录 sequence、intrinsic/extrinsic 与 rad；内部优化改用 Lie / quaternion
rotation drift	长期复合后 RᵀR 偏离 I；inverse 用 transpose 不再准确	监控 orthogonality；必要时投影到 SO(3)，同时追查积分/精度根因
SVD reflection	Umeyama/Kabsch/Procrustes residual 很低但 det=-1	R=U diag(1,1,det(UVᵀ)) Vᵀ；并报告 correction 是否触发
4×4 bottom row	反序列化/拼接后最后一行为 0、NaN 或透视项	断言 `[0,0,0,1]`、finite、shape 与 contiguous semantics
dtype / tolerance	float32 长链、极小物体或大坐标下误差放大；allclose 默认误判	按单位与任务选 atol/rtol；测试 shape/dtype，关键标定和求解保留 float64

前置回看：坐标系与刚体变换、数学与刚体几何、旋转与姿态表示。

04 · Camera Preprocess, Distortion & RGB-D

camera model 必须对应当前像素数组，而不是原始传感器的某个历史分辨率

把 crop/resize/pad 看作 pixel homogeneous transform A；raw、undistorted、rectified、network input、RGB 与 depth 都是不同 domain。

Image affine and updated intrinsics

\tilde{\mathbf p}'=\mathbf A\tilde{\mathbf p},\qquad \mathbf K'=\mathbf A\mathbf K,\qquad \mathbf A=\begin{bmatrix}s_x&0&p_x-s_xc_x\\0&s_y&p_y-s_yc_y\\0&0&1\end{bmatrix}

这里 c_x,c_y 表示 raw crop offset，p_x,p_y 表示 resize 后 pad。更复杂 rotate/flip 继续左乘 A；如果产生 reflection，3D pose label 的处理需另行定义。

Pinhole back-projection closure

\mathbf p_C=z\mathbf K^{-1}[u,v,1]^{\mathsf T}=\left[\frac{(u-c_x)z}{f_x},\frac{(v-c_y)z}{f_y},z\right]^{\mathsf T}

pixel、K 与 z 必须属于同一相机/rectification/registration domain；z 是 optical-axis depth，不一定等于 Euclidean range。

Radial/tangential distortion domain

x_d=x(1+k_1r^2+k_2r^4+k_3r^6)+2p_1xy+p_2(r^2+2x^2),\quad r^2=x^2+y^2

不要把 raw distorted pixel 与 ideal K projection 直接比较；fisheye/rational 等模型使用各自公式，D 为空也可能表示已经 rectified。

Depth encoding to metric value

z_{\mathrm{SI}}=d_{\mathrm{raw}}\,s_d\,10^{-3}\quad\text{for a BOP-style }s_d\text{ that yields millimetres}

BOP 每图 depth_scale 乘 raw depth 得 mm；ROS 16UC1 常见 mm、32FC1 常见 m，但必须服从 producer contract，不能只靠 dtype 猜。

问题	signature	修复 / 证据
Raw K 用于 resized tensor	误差随像素离主点距离增大	`p′=Ap, K′=AK`；K 与 preprocess manifest 同源生成
Crop 与 resize 顺序错	principal point 发生固定但比例相关偏移	按执行顺序复合 pixel affine，不手写散落的 cx/cy 修补
非等比 resize	x 基本正确、y 系统偏移	分别维护 sx/sy，更新 fx/fy/cx/cy
Pad / letterbox 未计入	所有点固定偏 pad offset，中心附近也错	将 pad translation 放入 A；训练标签与推理反变换共用实现
Horizontal flip	2D 标签翻了，3D pose / object symmetry 未同步	图像增强与 pose action 明确；反射不是普通 SO(3) rotation
Raw / undistorted / rectified 混用	中心好、边缘呈径向/切向结构	记录 distortion model 与 domain；K/D 或 P/R 成套使用
Pixel center / align_corners	resize 往返出现约 0.5 px 偏置，低分辨率更明显	冻结 sampling convention 与 library/version；用 impulse-grid regression
16UC1 / 32FC1 深度	点云放大 1000 倍或完全缩小	encoding + scale 决定 SI；BOP depth = raw·depth_scale mm
Invalid depth	0 被当作相机中心，NaN 悄悄污染 SVD/ICP	invalid mask 先于数值计算；统计 valid fraction 与 first bad index
RGB-D 未注册	彩色边缘与深度边缘固定错位，近物更明显	用 depth K 与 RGB←depth extrinsic 重投影，或消费声明已注册的产品
Timestamp / rolling shutter	静态正确、运动才偏；行方向误差有梯度	用 exposure time、readout model 与共同 clock；arrival time 不可替代
Channel / normalization	网络输出整体退化但几何自检均正常	记录 RGB/BGR、range、mean/std、gamma/bit-depth；保存首层输入 checksum

前置回看：相机模型与成像几何、RGB、RGB-D 与多模态流程。

05 · CAD, Labels & Dataset Integrity

pose 的含义绑定具体 asset；换 mesh origin 就等于换了坐标系

资产、标签、增强、split 和 symmetry 都进入数据版本。一个漂亮 overlay 可能只是 render mesh 与 label 同源地一起错。

01

CAD unit / scale

mesh 以 mm 保存却按 m 渲染；normalized category shape 被当 metric

bbox/diameter/range gate + physical ruler sentinel

02

Origin / canonical axes

轮廓能对上但 translation/rotation 与公开标签恒定差一边

asset transform 单独版本化；不要改 pose label 吸收 CAD origin

03

Mesh variants

render mesh、evaluation mesh、collision mesh 或 simplified mesh 混用

每个用途独立 hash；明确 model-to-variant fixed transform

04

Symmetry metadata

预测视觉等价却被误报，或任务关键键位被错误合并

proper symmetry group + task equivalence；版本化 continuous/discrete sampling

05

Normals / winding

point-to-plane ICP 方向异常、渲染背面剔除、吸盘法向反转

recompute/visualize normals，检查 orientation consistency 与 face winding

06

Texture / color space

synthetic 模板和 real input 系统色偏

ICC/gamma/linear-sRGB、tone mapping 与 texture version 进入 manifest

07

Label augmentation

image crop/flip 了，mask/keypoints/pose/K 未同步

同一 typed transform 应用于所有 annotation；做 round-trip property test

08

Split / leakage

validation 异常高、换实例/场景暴跌

按 physical instance/scene/session 分组；hash 查重；冻结 split manifest

Asset-frame migration must preserve the physical pose

{}^{C}\mathbf T_{O'}={}^{C}\mathbf T_O\,{}^{O}\mathbf T_{O'},\qquad \mathbf p_C={}^{C}\mathbf T_O\mathbf p_O={}^{C}\mathbf T_{O'}\mathbf p_{O'}

mesh recenter/scale/axis migration 是显式 asset transform；不能只改 vertex 而保留旧 pose annotations。

避免同源闭环。若 GT pose、rendered mask、bbox、visible mask 和 quality check 全由同一错误 CAD origin/K/transform 生成，它们可以彼此完全一致。至少保留人工 landmark、真实深度、独立 tracker/touch 或第二实现作为外部 sentinel。

工程回看：真实数据标注、仿真与合成数据、对称性、歧义与不确定性。

06 · PnP, Registration & Optimizer Diagnosis

求解器先证明“问题可解且数据可信”，再报告最优值

保存输入 support、inlier mask、candidate set、initialization、condition spectrum、termination reason 与 held-out evidence。只留最终 R/t 和一个 residual 无法复盘。

Reprojection objective with an explicit valid/inlier set

E_{\mathrm{PnP}}(\mathbf R,\mathbf t)=\frac{1}{|\mathcal I|}\sum_{i\in\mathcal I}\rho\!\left(\left\|\mathbf u_i-\pi(\mathbf K,\mathbf D,\mathbf R\mathbf X_i+\mathbf t)\right\|_2^2\right)

I、pixel domain、K/D、robust loss 与 unit 都属于协议；低 E 不能排除 planar ambiguity、mirror、wrong asset 或同源 correspondences。

3D support planarity diagnostic

\mathbf C=\frac1N\sum_i(\mathbf X_i-\bar{\mathbf X})(\mathbf X_i-\bar{\mathbf X})^{\mathsf T},\quad \lambda_1\ge\lambda_2\ge\lambda_3,\quad \eta_{\mathrm{plane}}=\lambda_3/\lambda_1

η 很小提示近共面，λ₂/λ₁ 很小再提示近共线；阈值需按噪声、尺度和 solver 设定，不是通用常数。

Point-to-plane ICP objective

E_{\mathrm{ICP}}(\mathbf T)=\sum_{(i,j)\in\mathcal K}w_{ij}\left[\mathbf n_j^{\mathsf T}(\mathbf T\mathbf p_i-\mathbf q_j)\right]^2

K、normal、weight/reject、max correspondence distance、initial T 与 overlap 决定 basin；小 point-to-plane residual 可能仍沿平面切向错很远。

问题	signature	必须保存 / 隔离
PnP correspondence	object/image point index 错、重复、坐标域不一致	先画逐点连线和 residual vector；核对 undistort / K / object unit
PnP planar / collinear	多个低 reprojection 解、深度/姿态跳变	检查 centered 3D spectrum、保留 `solvePnPGeneric` 多解、加 non-planar/depth/temporal evidence
PnP cheirality / mirror	点在相机后或 planar mirror 解偶发胜出	所有 control points 正深度 + silhouette/depth/temporal validation
RANSAC	threshold 单位/像素域错，confidence 高但 inliers 错	记录 sampler/seed/threshold/iterations、inlier mask 与 post-refinement residual
Conditioning / scaling	rotation 与 translation 数量级差导致 normal equation 病态	center/scale data、报告 singular spectrum/κ，使用适合参数化与 robust loss
ICP initial basin	低 RMSE 但落到错误局部表面	global/coarse init、overlap/fitness、reverse check、multi-start 与 independent keypoints
ICP correspondence gate	阈值太大吸入背景，太小则 0 correspondences	按 resolution/noise/initial error sweep threshold；报告 correspondence count
Point-to-plane normals	平面收敛快但切向无约束，法向错则方向错误	normal orientation/scale、Hessian eigenvalues、point-to-point cross-check
Symmetry / multi-mode	solver 在等价 modes 间跳，平均 pose 落到无效中间	输出 set/distribution，在 quotient/task space 评估；不要直接平均 rotations
Termination	“converged”只因步长小/迭代上限，残差或独立误差仍大	同时门禁 finite、gradient/step、support、held-out、physical closure 与 task risk

算法回看：2D–3D 对应与 PnP、3D–3D 对齐与点云配准、位姿评测与误差分析。

07 · Time, Runtime & Reproducibility

离线正确只是必要条件；在线系统还要保证值没有过期、版本没有撕裂、失败没有被伪装

吞吐率不是 latency，arrival time 不是 exposure time，seed 不是完全复现，热更新也不是原子部署。每个 estimate 都有 age 和 valid_until。

First-order motion error from timestamp mismatch

\|\delta\mathbf p\|\lesssim \|\mathbf v\|\,|\Delta t|+\|\boldsymbol\omega\|\,|\Delta t|\,\ell

静态 A/B 可隔离 temporal term；ℓ 是被观测/接触点 lever arm。还需考虑 rolling-shutter row time、queue jitter 与 controller actuation delay。

Absolute + relative numerical test tolerance

|a-b|\le \mathrm{atol}+\mathrm{rtol}|b|

atol 要按单位和接近零的物理容差选；rtol 处理尺度。默认 allclose 可能对小量过松，broadcast/equal_nan 也可能掩盖 shape/NaN bug。

NaN / Inf

进入 optimizer 后才爆炸，堆栈远离首个坏点

每层 finite gate + sample/stage index；JSON 用显式 status/null 而非非标准 NaN

Shape broadcasting

代码不报错但 batch/point 轴错误复用

typed dimensions、strict shape tests；禁止依赖隐式 broadcasting 通过测试

Device / precision

CPU 正常、GPU/FP16 偶发异常

记录 device/dtype/autocast；关键 SVD/solve 和 reductions 做 float64/FP32 A/B

Nondeterminism

同 seed 仍波动，跨 release/platform 不一致

锁版本/硬件/algorithm；deterministic mode + 多次重放，接受性能代价

Stale queue

显示的是新图，pose 来自旧帧；延迟随负载变

frame_id + exposure timestamp + sequence，丢弃过期结果并测 end-to-end age

Cache / partial deploy

新 checkpoint 配旧 CAD/K/preprocess，冷启动与热更新结果不同

manifest 原子加载、content hash、cache namespace 与 cold-start CI

Serialization

matrix flatten order、int truncation、JSON null/duplicate key 变化

schema round-trip golden test；禁止依赖 object key ordering

Config shadowing

CLI/env/YAML 默认值覆盖来源不明

启动时打印 resolved config + provenance；未知字段报错，不静默忽略

Concurrency

共享 buffer 被复用、GPU async 未同步、callback 乱序

immutable message / copy ownership、sequence assertions、同步计时与 race tests

Silent failure

no pose/timeout 被替成 identity 或上一帧

status enum + reason + valid_until；下游必须显式处理 abstain/stale/failure

Atomic deployment tuple

release_id = hash(
  code_commit, resolved_config, model_arch, checkpoint,
  preprocess, camera_intrinsics, distortion/registration,
  CAD/eval/collision assets, symmetry metadata,
  robot URDF/kinematics, hand-eye, TCP, controller,
  libraries/drivers, device/precision, schema version
)
estimate.status ∈ {ok, abstain, no_solution, timeout, stale, invalid_input, runtime_error}

系统回看：机器人坐标变换与系统标定、机器人抓取与操作。

08 · Debug Views Are Measurement Instruments

每张图回答一个假设；所有 overlay 都标出 frame、domain、timestamp 和 scale

可视化不能只用于演示。它应能下钻到 sample、point、edge、stage 与 version，并与机器可读 residual 使用同一数据但独立实现关键投影。

RGB overlay

projected model axes / bbox / silhouette 与原图

方向、K、畸变、crop、粗 pose；看不出 depth unit/occluded geometry 的全部问题

Depth residual

rendered Z 与 measured Z，仅在可见且有效像素比较

depth scale、z translation、occlusion、RGB-D registration；受 sensor bias / missing depth 影响

Point / match vectors

每个 correspondence、inlier/outlier 和 residual arrow

index、pixel domain、局部坏区域、RANSAC；平均 RMSE 会掩盖结构

3D overlay

CAD/point cloud/axes/frustum/trajectory 同一 world frame

scale、origin、handedness、registration；viewer 的 up/forward 约定也要标注

Frame graph

每条 edge 的方向、age、source、covariance 和 loop closure

错 frame、stale transform、重复 broadcaster；树可连通不等于外参准确

Error slices

near/far、center/edge、static/dynamic、view/load/temp、object/visibility

从 signature 缩小责任层；全局均值不足以定位

Time plot

exposure、arrival、inference、command、actuation 与 queue age

offset、jitter、stale result 和 throughput/latency混淆

Physical sentinel

固定标定板、已知 CAD pose、touch point、robot gauge 或独立 tracker

打破同源数据闭环；必须独立于被测 artifact 和 solver

Depth residual on mutually visible valid pixels

r_Z(u)=Z_{\mathrm{sensor}}(u)-Z_{\mathrm{render}}(u;\mathbf T),\qquad u\in\Omega_{\mathrm{valid}}\cap\Omega_{\mathrm{visible}}

同时画 signed map、histogram 与 image-location slices；不要把 missing depth、occluded model 或邻物 surface 当 pose residual。

Fixed vector everywhere

K principal point / crop / TCP / fixed extrinsic

改变 depth、view、speed 后仍固定，优先查 constant edge 与 pixel offset。

Grows with radius

distortion / focal / scale

中心小、边缘大，按 radial direction 画 residual。

Grows with depth

focal / translation scale / depth model

分 near/far 及 pixel/mm 两域，避免投影效应混淆。

Only with speed / direction

timestamp / rolling shutter / backlash / flex

静态—动态、正向—反向、轻载—重载三组 A/B。

09 · Test Pyramid, Logging & Regression

测试物理不变量、跨表示等价性和失败路径，而不只测 happy-path API 返回值

golden truth 独立于被测 pipeline；每个生产事故缩成最小 regression sample。CI 同时跑 schema、数值、静态构建、runtime 和代表性真实数据。

Unit

inverse/compose、projection/backprojection、quaternion/Euler、K affine、depth scale

非对称数值、非零 translation、非交换 transforms 与 failure cases

Property

随机 SE(3) round-trip、SO(3)、A·K pixel closure、augmentation round-trip

seed 固定但覆盖多尺度/边界；反例 shrinking 后加入 regression

Golden artifact

少量人工确认的 image/depth/CAD/K/pose 与期望 overlay/metrics

文件 hash + human-reviewed snapshot；不由当前 pipeline 自己生成真值

Metamorphic

单位换算、frame change、image resize、symmetry action 后物理结果应不变

测试等变/不变关系，比单个预期数字更能抓 contract bug

Differential

两 library/solver/precision/CPU-GPU/old-new 版本同输入对比

先统一 convention；差异保留 per-sample evidence，不只均值

Integration

数据读取→preprocess→estimate→render→evaluate 与 camera→robot chain

真实文件/message schema、timestamps、cache cold-start 与 failure status

Hardware-in-loop

固定 target、touch、slow motion、speed reversal、load/workspace sweep

先安全低速；静态/动态 A/B 定位 calibration/time/control

Release / monitor

manifest compatibility、latency P95、drift heartbeat、risk/abstain 与 rollback

门禁阈值来自部署 envelope；报警携带 owner 和最小复现实例

Minimum debug record per estimate

sample/instance/task IDs · raw file/message checksums
image/depth/K/D/P/preprocess + asset/symmetry hashes
all frame edges with timestamp/clock/age/source
candidate poses, scores, covariance, inlier/correspondence masks
solver method/init/thresholds/iterations/termination/spectrum
projection/depth/closure/held-out/task residuals
runtime stage timestamps, device/dtype, resolved config/release_id
status + first_failure_stage + owner + recovery/action

10 · Incident Playbook & Release Gate

不要问“哪一个模型更好”，先问“最早在哪一层违反了哪条契约”

发布前主动注入 unit、inverse、quaternion、K、depth、reflection、degeneracy、NaN、time 和 cache faults，确认系统能阻断并给出正确 owner。

Release gate · 允许 pose 进入评测或机器人之前

每个 pose 是否声明 from/to、map direction、row/column、active/passive、handedness、rotation representation/order 和 unit？
是否检查 shape/dtype/finite、4×4 bottom row、RᵀR、det R、q norm、translation/depth range 与 cheirality？
是否用非对称 known point / axes / physical sentinel 验证语义，而不只做 inverse round-trip？
当前 image/tensor 的 resolution、crop/resize/pad/flip affine、raw/rectified domain 与 K/D/P 是否同版本？
depth encoding、depth_scale、invalid/no-return、RGB↔depth registration、timestamp/clock 是否显式？
CAD/eval/collision/render assets 的 unit、origin、axes、diameter、normal、symmetry 与 hash 是否冻结？
augmentation 是否同步 image/mask/keypoint/bbox/depth/normal/K/pose，并有 round-trip property test？
PnP 是否保存 correspondences/inliers/multi-solutions、检查 planarity/condition/cheirality，并用 silhouette/depth/temporal evidence选解？
ICP 是否保存 initial T、overlap/fitness、threshold/correspondence count、normal、condition 与 reverse/independent check？
optimizer 的 convergence 是否同时受 finite、support、condition、held-out/physical residual 和 task tolerance 门禁？
是否用 static/dynamic、near/far、center/edge、view/load/temp、CPU/GPU 与 cold/warm A/B 定位 signature？
estimate 是否携带 exposure timestamp、clock、age/valid_until；queue 是否丢弃 stale result？
release 是否原子绑定 code/config/checkpoint/preprocess/K/assets/symmetry/robot calibration/driver/library/device/precision？
NaN/Inf、no-solution、timeout、stale、abstain 是否为显式状态，且 JSON/数据库不会静默替换为 identity/上一帧？
测试是否覆盖 unit/property/golden/metamorphic/differential/integration/HIL，并把事故样本永久加入 regression？
日志是否足以离线重放到 point/stage，并含 first failure、threshold、version、latency P50/P95 与 raw evidence？
overlay/depth/frame graph 是否标注 domain/frame/unit/timestamp，且关键 sentinel 不与待测 pipeline 同源？
最终门禁是否由任务容差、风险与 deployment envelope 决定，并支持 abstain、rollback、recalibrate 与人工接管？

Freeze

冻结输入与版本

不在原数据上继续覆盖。

→

Reproduce

最小离线重放

确认 deterministic envelope。

→

Bracket

找第一失败层

用 contract / invariant / sentinel。

→

Isolate

单因素 A/B

指派 owner，不扩散修补。

→

Prevent

加 gate 与 regression

修 root cause 并验证 rollback。

坐标/相机/求解/运行契约的原始与官方来源展开查看 ROS REP/tf2/sensor_msgs、OpenCV、HZ、Umeyama、Higham、ICP、BOP、SciPy、NumPy、PyTorch 与 RFC 8259