相机投影核心约定深度解析：Kornia `kornia.geometry.camera` 的坐标系、整数像素中心、depth 双重含义与 `z = 0` 策略

相机投影核心约定深度解析Korniakornia.geometry.camera的坐标系、整数像素中心、depth 双重含义与z 0策略【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址: https://gitcode.com/kornia/kornia导读Kornia 在kornia.geometry.camera子包中为相机投影核心PinholeCamera类与project_points/unproject_points等函数式 API沉淀了一整套可执行约定世界到相机的外参方向、整数像素中心、depth 的两种语义以及z 0的投影行为。本文以迁移日志条目 changelog.d/migration-008.added.md 为主线结合源码实现、文档页与测试用例executable pins完整解析这些约定及其边界行为帮助你在相机标定、双目几何、深度反投影等场景中避免半像素偏移这类静默错误。一、背景为什么投影核心需要一份书面约定kornia.geometry.camera是 Kornia 几何子库中负责相机建模与投影的模块公开的 API 包括见 kornia/geometry/camera/init.py类式 APIPinholeCamera、StereoCamera、PinholeCamerasList函数式 APIproject_points/unproject_points透视投影、project_points_z1/unproject_points_z1规范化 z1 平面、project_points_orthographic/unproject_points_orthographic正交投影、cam2pixel/pixel2cam以及仿射与 Kannala-Brandt 两类畸变模型投影是几何视觉的公共地基标定、PnP、三角化、深度反投影、位姿估计全都依赖它。而相机约定在不同生态OpenCV、COLMAP、OpenGL、ARKit、PyTorch3D之间存在静默差异——形状依然匹配、图像看起来依然合理但重建结果会差半像素、甚至镜像。这正是迁移条目migration-008.added.md记录的工作PR #4294把投影核心的约定文档化并用可执行的测试把它钉住pins同时把已知的 scale 规则、别名、guard 与遗留 API 限制登记在专门的 issue 中跟踪。注意本文所称的约定与限制均以当前仓库源码中的Convention:/.. warning::注释块为准它们是这些文档化约定的第一手出处。二、PinholeCamera的帧约定世界到相机还是相机到世界PinholeCamera是投影核心的类式入口其约定块写在 kornia/geometry/camera/pinhole.py 的类 docstring 中intrinsics是(B, 4, 4)标定矩阵左上角3×3块为[[fx, 0, cx], [0, fy, cy], [0, 0, 1]]extrinsics是(B, 4, 4)的 world-to-camera 变换[R | t]即 OpenCV / COLMAP 语义project接收世界点计算K (R X t)得到像素unproject是其逆——接收像素与相机系深度返回世界点函数式 API 则工作在相机系project_points/unproject_points只接收K、不接收外参因此不会在帧之间移动。类式与函数式两条路径的投影实现可以在源码中对照# PinholeCamera.project完整 4x4 乘积 P self.intrinsics self.extrinsics return convert_points_from_homogeneous(transform_points(P, point_3d)) # project_points仅相机系 K无外参 xy_coords convert_points_from_homogeneous(point_3d) return denormalize_points_with_intrinsics(xy_coords, camera_matrix)对应关系见 perspective.py 与 pinhole.py。一个易错点是unproject_points的返回位于相机系无法返回世界坐标只有PinholeCamera.unproject才是世界系的反投影二者按需取用。PinholeCamera的构造会对形状做严格校验intrinsics/extrinsics必须是B×4×4或B×N×4×4height/width必须是(B,)一维张量且四者 batch 维与设备必须一致_check_valid、_check_valid_params、_check_consistent_device。注意project要求文档化的(B, 4, 4)布局(B, N, 4, 4)的直接投影限制被记录在 issue #4266 中见下文。PinholeCamera还提供了fx/fy/cx/cy/tx/ty/tz、camera_matrix、rotation_matrix、translation_vector等属性以及scale/scale_/clone/from_parameters等操作StereoCamerastereo.py同样遵循整数像素中心与整数像素中心深度约定供双目几何使用。三、整数像素中心cx (W - 1) / 2而不是W / 2PinholeCamera的第二个核心约定是整数像素中心integer pixel centres像素坐标是(u, v) (x, y) (列, 行)像素(0, 0)的中心位于(0, 0)——这正是kornia.geometry.create_meshgrid枚举的网格因此居中图像的像主点位于cx (W - 1) / 2、cy (H - 1) / 2半像素约定如 COLMAP把像素角点放在原点同一像主点会在每个轴上大半个像素。这一约定与 OpenCV / Kalibr 一致而 COLMAP 的 FAQ 明确指出 OpenCV and Kalibr place integer coordinates at pixelcenters。其完整对照表含grid_sample的align_corners语义记录在文档页 docs/source/get-started/camera-conventions.rst并从该表导出三条换算规则约定像素 (0,0) 中心居中 W×H 图像的像主点OpenCV / 整数Kornia(0.0, 0.0)((W-1)/2, (H-1)/2)COLMAP / 半像素(0.5, 0.5)(W/2, H/2)cx_colmap cx_opencv 0.5cy同理焦距与畸变系数不变图像按尺度s缩放时两种约定的主点缩放公式不同OpenCV 为cx s * cx (s - 1) / 2COLMAP 为cx s * cx仅在s 1时一致归一化到单位方格的 intrinsics首像素中心在(0.5/W, 0.5/H)属于半像素约定按图像尺寸缩放后的形式换算为整数中心像素需要fx_px W * fx_n、cx_px W * cx_n - 0.5。对应测试钉位于 tests/geometry/camera/test_perspective.pytest_convention_integer_pixel_centres_put_the_principal_point_at_w_minus_one_half用H2, W3的网格刻意让行列数不等避免转置读取碰巧通过验证——在cx1, cy0.5下首末像素反投影互为精确相反数光轴(0, 0, 1)恰好落在像主点(1, 0.5)上若误用半像素的cx1.5, cy1.0则两者都不成立。grid kornia.geometry.create_meshgrid(2, 3, normalized_coordinatesFalse) # - [[0, 0], [1, 0], [2, 0], [0, 1], [1, 1], [2, 1]] # cx (3 - 1) / 2 1, cy (2 - 1) / 2 0.5, fx fy 1 unproject_points([[0., 0.]], depth1, K) # - [[-1, -0.5, 1]] unproject_points([[2., 1.]], depth1, K) # - [[ 1, 0.5, 1]]四、depth 的两种含义相机系z还是欧氏射线长度迁移条目记录的第三类约定是depth 的两种含义默认语义depth是反投影结果的相机系z坐标第二种语义当unproject_points以normalizeTrue调用时depth_to_3d/depth_to_3d_v2的normalize_points标志同理depth被读作欧氏射线长度反投影点具有该范数、而z分量更小。源码实现非常直观perspective.pyxy normalize_points_with_intrinsics(point_2d, camera_matrix) xyz convert_points_to_homogeneous(xy) if normalize: xyz F.normalize(xyz, dim-1, p2.0) # 归一化到单位范数 return xyz * depthnormalizeFalse时xyz的z分量恒为 1乘上 depth 后z depthnormalizeTrue时先做 L2 归一化再乘 depth结果的范数等于 depth、z严格小于 depth。单目深度网络对预测的是z还是射线长度并无统一约定选择错误会移动所有不在主射线上的反投影点。测试钉test_convention_normalize_makes_depth_the_ray_lengthtests/geometry/camera/test_perspective.py用偏离主点的像素(29, 53)cx4 ≠ cy3使两种读法可区分验证K [[100, 0, 4], [0, 100, 3], [0, 0, 1]] unproject_points([[29., 53.]], depth2, K) # - [[0.5, 1.0, 2.0]] z depth unproject_points([[29., 53.]], depth2, K, normalizeTrue) # - [[0.436, 0.873, 1.746]] norm depth五、z 0策略投影核心的边界行为第四个被钉住的约定是z 0时的投影行为。透视投影的标准公式是u fx * X/Z cx但z 0意味着除零。不同入口对同一输入给出了不同的答案均不抛异常这是文档明确记录、并由测试 pin 住的行为入口z 0时的行为project_points/PinholeCamera.project跳过透视除法对未除的点应用K得到fx*x cx有限值project_points_z1/Z1Projection.project直接除零各分量按分子符号得到inf/-inf/nan分子为零时nancam2pixel有限但巨大的~1e14量级数值project_points的源码路径解释了前者convert_points_from_homogeneous会把|z| 1e-8的点屏蔽为除数 1因此z 0的点实际走不除法分支输出K·[x, y, z]^T的归一化结果perspective.py。测试钉test_wart_project_points_skips_the_divide_at_zero_4267tests/geometry/camera/test_perspective.py把它钉在精确值上K [[100, 0, 4], [0, 100, 3], [0, 0, 1]] project_points([[1., 2., 0.]], K) # - [[104., 203.]] 即 fx*14, fy*23无除法 project_points([[1., 2., -4.]], K) # - [[-21., -47.]] 相机背后的点被同样静默投影与之形成对照project_points_z1明确声明其前置条件是z 0点在相机前方但该前置条件不被校验在z 0处每个输出分量都是inf/-inf/nanprojection_z1.py。测试注释指出project_points_z1、PinholeCamera.project、project_points与cam2pixel四个入口在z 0处给出四种不同答案这一不一致被登记为 issue #4267测试 pin 的是当前行为而非契约待问题修复后应删除。这些测试的命名以wart_/convention_区分两类角色convention_*钉住的是被认定为正确并延续的约定如整数像素中心、depth 语义wart_*钉住的是已知缺陷的当前行为如z0除零策略注释明确标注 Pins the CURRENT value; NOT a contract; delete when #4267 is repaired。这套命名规范本身就是 migration-008 引入的可执行钉工程实践。六、已知限制与遗留 API五个被跟踪的问题迁移条目特意强调投影核心的已知限制没有悄悄修掉而是以当前行为为准文档化、并登记在独立 issue 中跟踪修复。源码中的.. warning::块一一对应Issue限制内容出处#4263PinholeCamera.scale/scale_以cx s * cx半像素规则缩放主点与库内其余部分的整数像素中心不一致pinhole.py、pinhole.py#4265scale_在整数height/width上使用浮点尺度因子会抛RuntimeError且抛出时相机已处于部分缩放状态scale则会把整数尺寸提升为浮点pinhole.py#4266(B, N, 4, 4)形状的相机存储无法直接用于project需要(B, 4, 4)仅PinholeCamerasList的共享校验器接受前者pinhole.py#4267z 0处多个投影入口行为不一致见第五节perspective.py、projection_z1.py#4268遗留 12 向量 APIpinhole_matrix的输出以eye(4) eps构建float32/float64下结构性零与一都携带eps且该遗留 API 未在任何 API 参考页导出pinhole.py其中pinhole_matrix接收遗留的 12 向量布局(fx, fy, cx, cy, height, width, rx, ry, rz, tx, ty, tz)(rx, ry, rz)为角轴旋转docstring 明确标注其已被PinholeCamera及camera_matrix属性取代Superseded。使用遗留接口时需自行处理eps问题eps0.0返回精确矩阵。七、跨库边界实践把约定落在代码里这些约定不只是文档它们直接决定你在标定数据接入、深度网络输出转点云、位姿换算时写下的公式像素坐标Kornia 的网格是整数中心的create_meshgrid(normalized_coordinatesFalse)枚举0..W-1接入 COLMAP 标定结果时主点要加0.5接入归一化 intrinsics 时用fx_px W * fx_n、cx_px W * cx_n - 0.5。外参方向Kornia 的extrinsics与 OpenCV、COLMAP 同为 world-to-cameraCOLMAPimages.txt的四元数平移无需取逆只需四元数转矩阵需要 camera-to-world 位姿时用 conversions.py 中的worldtocam_to_camtoworld_Rt/camtoworld_to_worldtocam_Rt按转置计算刚性逆(R^T, -R^T t)。depth 语义把单目深度网络的输出喂给unproject_points前先确认它预测的是相机系z还是射线长度后者必须传normalizeTruedepth_to_3d系函数对应normalize_points标志。边界输入z 0的点不会被拒绝。若你的管线不允许相机背后的点出现应在调用前自行校验而不是依赖投影函数抛错。完整的跨库对照OpenCV / COLMAP / OpenGL / ARKit / ARCore / PyTorch3D / Direct3D 的轴方向、手性、像素中心与对应转换器见文档页 docs/source/get-started/camera-conventions.rst其每个非 Kornia 单元格均标注了上游文档依据可作为跨生态换算的权威速查表。小结migration-008.added.md对应的是一次约定工程kornia.geometry.camera的投影核心从此有了书面的坐标系约定world-to-camera 外参、整数像素中心、depth 双重语义、z 0策略配套的可执行测试把每条约定钉在当前行为上convention_*为契约、wart_*为已知缺陷五个已知限制#4263、#4265、#4266、#4267、#4268被显式登记、按当前行为文档化。对使用者而言这意味着接入标定与深度数据前先对齐像素中心与 depth 语义规避scale的主点规则差异并对z 0输入保持警惕——这些约定本身就是避免半像素偏移这类静默错误的第一道防线。【免费下载链接】kornia 空间人工智能的几何计算机视觉库项目地址: https://gitcode.com/kornia/kornia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考