计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载kornia 在kornia.geometry.keypoints模块中提供了面向对象的 2D/3D 关键点 API通过Keypoints与Keypoints3D两个类将点集张量包装为带类型校验、几何变换与填充能力的一等对象。本文基于该模块的官方文档与仓库源码完整讲解其数据结构约定、构造校验、张量互转、索引切片、几何变换、填充/去填充等核心能力并延伸到VideoKeypoints与数据增强容器中的集成用法帮助你在特征匹配、目标跟踪、三维重建与增强管道中直接落地这套 API。模块定位为什么需要关键点封装类在 Kornia 的几何体系中kornia.geometry.keypoints模块提供的是关键点的面向对象 APIObject-oriented API。官方文档对其定位描述为Keypoints与Keypoints3D类包装一个点集张量a tensor of points并向外提供**变换transformations与填充padding**能力适用于物体识别、跟踪与三维重建等场景。与直接操作原始torch.Tensor相比这套封装带来几个实际收益形状语义明确构造时强制校验张量布局杜绝把(N, 3)或(B, N, 4)等非法形状当作关键点误用类型安全默认拒绝整数坐标保证后续几何运算在浮点域内进行统一操作入口变换、填充、索引、克隆等操作都收敛到类方法上与同模块的 Boxes 等几何容器保持一致的编程模型增强管道集成数据增强容器可以直接把关键点作为一等输入类型处理见下文增强容器中的集成。核心实现位于 kornia/geometry/keypoints.py公开导出两个主类Keypoints2D与Keypoints3D3D另外模块内还实现了面向视频序列的VideoKeypoints子类。数据结构与坐标约定2D 关键点(N, 2)与(B, N, 2)Keypoints类内部维护一个坐标张量支持两种布局源码见 keypoints.py 的构造校验布局形状含义未批处理unbatched(N, 2)单幅图像/单帧中的 N 个点批处理batched(B, N, 2)B 个样本每个含 N 个点最后一维始终存储(x, y)坐标。构造时通过self._is_batched False if keypoints.ndim 2 else Truekeypoints.py记录批处理状态。3D 关键点(N, 3)与(B, N, 3)Keypoints3D采用同样的设计只是最后一维扩展为(x, y, z)布局为(N, 3)或(B, N, 3)keypoints.py。形状校验规则构造器对形状有严格限制keypoints.pyif len(keypoints.shape) 0: # 0 维标量会被 reshape 为 (-1, 2)且使用 reshape 而非 view # 避免产生与输入无关的新张量而干扰 torch.jit 的追踪 keypoints keypoints.reshape((-1, 2)) if not (2 keypoints.ndim 3 and keypoints.shape[-1:] (2,)): raise ValueError(fKeypoints shape must be (N, 2) or (B, N, 2). Got {keypoints.shape}.)即维度只允许 2 或 3且最后一维必须严格等于 23D 类对应为 3。测试 tests/geometry/test_keypoints.py 验证了Keypoints(torch.rand(3, 3))与Keypoints(torch.rand(3, 4, 2, 2))都会被拒绝。构造与输入校验两个类的构造函数签名一致Keypoints(keypoints: Union[torch.Tensor, List[torch.Tensor]], raise_if_not_floating_point: bool True) Keypoints3D(keypoints: Union[torch.Tensor, List[torch.Tensor]], raise_if_not_floating_point: bool True)参数语义如下keypoints原始点集张量也支持传入List[torch.Tensor]此时内部会调用_merge_keypoint_list合并列表但目前该辅助函数在源码中raise NotImplementedErrorkeypoints.py因此实际使用时以单个张量为准raise_if_not_floating_point默认True若输入张量不是浮点类型则直接抛出ValueError提示Coordinates must be in floating point若设为False则自动调用.float()转换后继续使用。构造过程的校验链两个类完全一致类型校验非张量输入抛出TypeError测试 test_keypoints.py浮点校验整数张量默认抛出ValueErrortest_keypoints.py 同时验证了raise_if_not_floating_pointFalse时 int32 会被转为 float32形状校验见上一节。import torch from kornia.geometry.keypoints import Keypoints # 合法构造Nx2 与 BxNx2 kp_unbatched Keypoints(torch.rand(10, 2)) kp_batched Keypoints(torch.rand(3, 10, 2)) # 非法输入非张量 / 整数坐标 / 错误形状 # Keypoints(not a tensor) # TypeError # Keypoints(torch.ones(5, 2, dtypetorch.int32)) # ValueError默认 # Keypoints(torch.rand(3, 3)) # ValueError # 关闭浮点校验整数自动转 float32 kp Keypoints(torch.ones(5, 2, dtypetorch.int32), raise_if_not_floating_pointFalse) assert kp.dtype torch.float32基础属性与张量互转属性访问属性返回内容源码位置shape底层坐标张量的形状即(N, 2)或(B, N, 2)3D 为(N, 3)/(B, N, 3)keypoints.pydata原始坐标张量(..., 2)最后一维为(x, y)keypoints.pydevice坐标张量所在设备keypoints.pydtype坐标张量的数据类型keypoints.py与张量互转from_tensor/to_tensor# 类方法校验并包装张量 kp Keypoints.from_tensor(torch.rand(5, 2)) # 返回 Keypoints 实例 kp3d Keypoints3D.from_tensor(torch.rand(5, 3)) # 返回 Keypoints3D 实例 # 实例方法还原为原始张量 (B, N, 2)/(B, N, 3) raw kp.to_tensor()to_tensor的as_padded_sequence参数用于关键点来自列表的场景当前实现中该路径会抛出NotImplementedErrorkeypoints.py默认直接返回内部self._data。测试 test_keypoints.py 验证了to_tensor()与输入数据逐元素一致。克隆与类型转换kp2 kp.clone() # 深度拷贝修改 kp2.data 不影响 kp.data kp.type(torch.float64) # 原地转换坐标 dtype返回 selfclone()通过Keypoints(self._data.clone(), False)实现keypoints.py测试验证了克隆后两者互不影响test_keypoints.py。索引、切片与定点写入Keypoints/Keypoints3D支持与张量类似的索引操作# 切片返回新的 Keypoints 实例不共享修改 sub kp[:5] # 取出前 5 个点sub.shape (5, 2) sub kp[torch.tensor([0, 2, 4])] # 也支持张量索引 # 赋值把另一组 Keypoints 的值写回 new_kp Keypoints(torch.zeros(5, 2)) kp[:5] new_kp # 底层执行 self._data[key] value._data # 定点写入类似 Tensor.index_put_ idx (torch.tensor([0, 1, 2]),) kp2 kp.index_put(idx, torch.ones(3, 2)) # 非原地克隆后写入返回新对象 kp.index_put(idx, torch.ones(3, 2), inplaceTrue) # 原地直接修改 self 并返回index_put的签名keypoints.py接受indices被Tensor.index_put_接受的索引元组/列表、values原始张量或另一个Keypoints对象以及inplace开关非原地模式下先clone()再写回保证原对象不变。对应测试见 test_keypoints.py。几何变换transform_keypoints用法与矩阵约定transform_keypoints是 2D 关键点封装中最核心的几何能力keypoints.pydef transform_keypoints(self, M: torch.Tensor, inplace: bool False) - Keypoints:M变换矩阵形状为(3, 3)单组或(B, 3, 3)每组对应一个矩阵要求2 M.ndim 3且M.shape[-2:] (3, 3)否则抛ValueErrorinplace为True时直接改写self._data并返回self否则返回一个新的Keypoints对象便捷方法transform_keypoints_(M)等价于transform_keypoints(M, inplaceTrue)keypoints.py。示例平移变换与测试 test_keypoints.py 中的期望值一致data torch.tensor([[[1.0, 0.0], [0.0, 1.0]]]) # (1, 2, 2)B1, N2 kp Keypoints(data) M torch.eye(3).unsqueeze(0) # (1, 3, 3) M[0, 0, 2] 2.0 # 平移 x 方向 2 M[0, 1, 2] 3.0 # 平移 y 方向 3 kp_t kp.transform_keypoints(M) # kp_t.data tensor([[[3., 3.], [2., 4.]]]) # 每个点 (x2, y3) # 原地版本 kp.transform_keypoints_(M)底层实现transform_pointstransform_keypoints内部实际调用的是 kornia/geometry/linalg.py 中的transform_points(trans_01, points_1)。该底层函数输入变换矩阵形状为(B, D1, D1)点集为(B, N, D)输出(B, N, D)此处 D2校验批大小必须一致或为 1允许广播且矩阵最后一维比点集最后一维大 1对空点集points_1.shape[-2] 0提前返回避免 reshape 推断-1时崩溃——这意味着可以安全地对无标注的空关键点集做变换内部会先 reshape 到统一的BxNxD再执行批矩阵乘法bmm。因此transform_keypoints的梯度可以一直回传到输入点集测试 test_keypoints.py 使用torch.float64对Keypoints(x).transform_keypoints(M).data做了gradcheck验证同一测试文件中的test_dynamo也验证了该操作可被torch.compile/dynamo 优化路径正确执行。批处理注意点当关键点为(B, N, 2)时M可以是(B, 3, 3)每样本独立变换也可以是(1, 3, 3)广播到所有样本。测试 test_keypoints.py 展示了用(1, 3, 3)矩阵对(2, 4, 2)批关键点整体平移的场景。填充与去填充pad/unpad在图像增强如随机裁剪、填充后关键点坐标需要随图像坐标系一起平移。Keypoints.pad/unpad即为此设计keypoints.pydef pad(self, padding_size: torch.Tensor) - Keypoints: ... def unpad(self, padding_size: torch.Tensor) - Keypoints: ...padding_size形状必须为(B, 4)按(left, right, top, bottom)顺序组织否则抛RuntimeErrorpad 逻辑x left_paddingy top_padding只有 left 与 top 会改变坐标原点unpad 逻辑x - left_paddingy - top_padding即 pad 的逆操作。这一约定与同仓库 Boxes 的pad完全一致padding_size is ordered as(left, right, top, bottom). Onlyleftandtopchange the coordinate origin保证同一增强管道中框与点使用同一套填充语义。data torch.zeros(2, 4, 2) # (B2, N4, 2) kp Keypoints(data) padding torch.tensor([[1.0, 0.0, 2.0, 0.0], # 样本0left1, top2 [0.0, 0.0, 3.0, 0.0]]) # 样本1left0, top3 kp.pad(padding) # 样本0: x 1, y 2 # 样本1: x 0, y 3 kp.unpad(padding) # 撤销填充回到原始坐标对应测试见 test_keypoints.py其中pad后kp.data[0, :, 0]全为 1.0x 加了 left1kp.data[0, :, 1]全为 2.0y 加了 top2。Keypoints3D3D 关键点的现状与边界Keypoints3D提供了与Keypoints对齐的构造校验、形状约束(N, 3)/(B, N, 3)、shape/data属性、from_tensor/to_tensor、clone、索引与切片能力可直接用于三维点集管理。但需要特别说明的是从当前源码看3D 关键点的部分几何操作尚未实现keypoints.py方法当前状态pad/unpadraise NotImplementedError签名中padding_size规划为(B, 6)对应三维 left/right/top/bottom 及深度方向的填充语义transform_keypoints/transform_keypoints_raise NotImplementedErrordocstring 中矩阵形状仍沿用 2D 的(3, 3)/(B, 3, 3)实现待完善测试 test_keypoints.py 明确断言了这些方法会抛出NotImplementedError。因此在实际项目中目前应把Keypoints3D定位为3D 关键点的结构化容器负责布局校验、属性访问、克隆与张量互转几何变换部分可自行结合transform_points其 D 维可扩展到 3等底层函数处理并关注 Kornia 后续版本对Keypoints3D变换/填充能力的补齐。VideoKeypoints视频序列关键点kornia.augmentation.container.augment等视频增强场景需要处理(B, T, N, 2)布局B批大小T帧数/时间通道N点数。VideoKeypoints是Keypoints的子类keypoints.py用于封装这类时间序列关键点from kornia.geometry.keypoints import VideoKeypoints data torch.rand(2, 5, 10, 2) # (B, T, N, 2) vkp VideoKeypoints.from_tensor(data) # 内部 reshape 为 (B*T, N, 2) assert vkp.temporal_channel_size 5 # 时间维度被记录 out vkp.to_tensor() # 还原为 (B, T, N, 2)关键实现点from_tensor只接受(B, T, N, 2)张量其余输入抛ValueErrorkeypoints.py内部以boxes.size(1)记录temporal_channel_size并将数据view(batch * time, -1, 2)存储——这样即可复用父类的单帧操作逻辑to_tensor重写为out.view(-1, self.temporal_channel_size, ...)把内部形状还原成(B, T, N, 2)transform_keypoints与clone均会保留temporal_channel_size保证变换/克隆后仍能正确还原时间维keypoints.py。测试见 test_keypoints.py覆盖了构造、temporal_channel_size记录、to_tensor往返一致性与异常输入。在数据增强容器中的集成Keypoints/VideoKeypoints并非孤立类它们已被 Kornia 增强体系作为一等数据类型接入。在 kornia/augmentation/container/augment.py 的_preproc_keypoints中可以看到完整的数据流视频序列当容器处于contains_video_sequential模式时输入张量或张量列表先统一转为浮点再通过VideoKeypoints.from_tensor包装必要时用.type(dtype)还原原始 dtype2D 单帧输入若已是Keypoints实例则直接透传否则用Keypoints.from_tensor包装非浮点输入先转float()3D 增强当前路径会抛出NotImplementedError(3D keypoint handlers are not yet supported.)——从源码看3D 增强容器对关键点的支持仍在规划中使用时需注意这一限制。增强结束后_postproc_keypointaugment.py负责把Keypoints还原为用户传入的原始类型张量或Keypoints对象。此外2D 增强基类如 kornia/augmentation/_2d/base.py与各类几何增强算子如 crop.py也都声明了接受Keypoints输入的接口。这意味着你可以把关键点与其他数据类型图像、掩膜、框一起送入增强容器实现图像变换的同时关键点同步变换。正确性保障测试与验证模块的完整行为由 tests/geometry/test_keypoints.py 覆盖可作为使用时的行为参考冒烟与基数test_smoke、test_cardinality、test_batched/test_unbatched验证构造与形状记录互转test_from_tensor/test_to_tensor验证与张量往返一致索引test_getitem/test_setitem/test_index_put含原地模式验证切片与定点写入变换test_transform_keypoints/test_transform_keypoints_inplace/test_transform_keypoints_batched验证平移结果test_gradcheck验证可微性test_dynamo验证编译兼容填充test_pad/test_unpad验证 left/top 语义异常路径test_exception/test_transform_exception/test_pad_exception验证非法输入均被拦截整数坐标test_int_input_raises_by_default与test_int_input_converted_when_not_raising验证raise_if_not_floating_point两种行为3D 边界test_not_implemented明确记录Keypoints3D.pad/unpad/transform_keypoints当前未实现。由于Keypoints并非nn.Module测试中test_smoke_jit与test_module均为跳过状态test_keypoints.py即该类不参与 JIT 模块化与nn.Module的常规测试流程。使用建议小结优先用封装类而非裸张量在涉及关键点的检测、匹配、跟踪与增强流程中用Keypoints.from_tensor包装一次即可获得形状/类型校验与统一的transform_keypoints、pad/unpad操作入口牢记坐标与填充约定坐标最后一维按(x, y)3D 为(x, y, z)排列padding_size按(left, right, top, bottom)排列且只有 left/top 平移坐标与Boxes语义一致3D 能力边界Keypoints3D目前适合做容器与张量互转几何变换与填充需等待实现补齐或自行调用底层transform_points视频场景使用VideoKeypoints(B, T, N, 2)布局请走VideoKeypoints.from_tensor变换与克隆后仍可通过to_tensor还原时间维增强管道联动把关键点直接传给增强容器或其中的几何增强算子图像与关键点会同步经历同一变换减少手工同步坐标的出错概率。参考资料官方 API 文档见 docs/source/geometry.keypoints.rst核心实现见 kornia/geometry/keypoints.py底层点变换见 kornia/geometry/linalg.py行为测试见 tests/geometry/test_keypoints.py。赞分享计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载相关推荐Kornia 几何关键点面向对象 API 完全指南Keypoints 与 Keypoints3D 的使用与原理Kornia 几何关键点面向对象 API 完全指南Keypoints 与 Keypoints3D 的使用与原理 Kornia 的 kornia.geometr计算机视觉深度学习人工智能图像处理TBOOX/TBOX布尔对象真假值的面向对象封装TBOOX/TBOX布尔对象真假值的面向对象封装 引言为什么需要布尔对象 在C语言开发中我们经常需要处理布尔值Boolean——表示真true或后端Frost暗色模式实战利用Dark系列区块模式快速打造深色商业网站的完整教程Frost暗色模式实战利用Dark系列区块模式快速打造深色商业网站的完整教程 Frost 是 WP Engine 打造的终极 WordPress 区块主题内上一篇CopilotKit 语音输入 Demo 的声音素材指南为 CrewAI Conversational Flows 准备 sample.wav下一篇Metabase 原生 SQL 可选变量Optional Variables完全指南用 [[ ]] 让查询子句智能显隐创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考