Kornia 边界框对象式 API 深度指南：Boxes 与 Boxes3D 的格式转换、几何变换与掩码生成

计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载导读本文围绕 Kornia 的kornia.geometry.boxes模块系统讲解面向对象的 2D / 3D 边界框容器Boxes、Boxes3D与VideoBoxes。你将掌握五种边界框格式xyxy、xyxy_plus、xywh、vertices、vertices_plus的转换约定、transform_boxes/translate/pad/clamp等几何操作、鞋带公式面积计算、掩码mask生成以及它们如何与数据增强管线无缝衔接可直接落地到检测框后处理、增强同步变换与 3D 空间数据处理等场景。模块定位对象式 API 与函数式 API 的分工在 Kornia 中边界框处理存在两套并行接口函数式 API位于 kornia/geometry/bbox.py直接以角点张量2D 为(B, 4, 2)3D 为(B, 8, 3)为输入提供validate_bbox、infer_bbox_shape、bbox_to_mask、nms、transform_bbox、bbox_generator等自由函数对象式 API位于 kornia/geometry/boxes.py对应文档页 docs/source/geometry.boxes.rst提供Boxes、Boxes3D、VideoBoxes三个容器类把张量连同格式信息、批量信息一起封装支持格式转换、变换与填充。官方文档对二者的定位写得很清楚函数式 API 处理以角点张量表示的 2D 与 3D 边界框见 docs/source/geometry.bbox.rst而对象式 API 则封装一个盒子张量并提供格式转换xyxy、xywh、顶点、变换与填充见 docs/source/geometry.boxes.rst。两者在 docs/source/geometry.rst 的geometry子模块目录中相邻列出。模块导出的公开符号只有三个类定义于 kornia/geometry/boxes.py__all__ [Boxes, Boxes3D, VideoBoxes]核心数据结构内部统一使用包含式顶点表示无论你以哪种格式输入Boxes在内部都统一存储为包含式inclusive顶点四边形vertices_plus形式每个 2D 盒子是 4 个浮点(x, y)顶点按顺时针顺序排列左上、右上、右下、左下形状为(N, 4, 2)非批量或(B, N, 4, 2)批量内部约定width xmax - xmin 1、height ymax - ymin 1即多算一格的包含式算术与排他式exclusive的xyxy/xywh/vertices不同。这里的关键设计是构造函数不转换任何格式只是把mode当作一个标签保存真正执行格式转换的是from_tensor导入与to_tensor导出。构造函数与from_tensor的整数输入策略也不同详见后文边界与注意事项。顶点顺序在_boxes_to_polygonskornia/geometry/boxes.py中体现先以xmin, ymin铺满 4 个顶点再分别对右上、右下、左下三点加上width - 1/height - 1的偏移从而生成顺时针四边形。# (N, 4) 的 xyxy 张量 boxes_xyxy torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]]) boxes Boxes.from_tensor(boxes_xyxy, modexyxy) boxes.data # 内部存储为 (2, 4, 2) 的包含式顶点五种格式模式与转换矩阵from_tensor/to_tensor支持五种模式均为小写匹配可概括为下表模式含义输入/输出形状范围约定xyxyxmin, ymin, xmax, ymax(N, 4)/(B, N, 4)排他式width xmax - xminxyxy_plusxmin, ymin, xmax, ymax(N, 4)/(B, N, 4)包含式width xmax - xmin 1xywhxmin, ymin, width, height(N, 4)/(B, N, 4)排他式vertices顺时针 4 顶点左上、右上、右下、左下(N, 4, 2)/(B, N, 4, 2)排他式导入时每个坐标减 1vertices_plus顺时针 4 顶点(N, 4, 2)/(B, N, 4, 2)包含式即内部存储形式转换逻辑集中在_boxes_to_quadrilateralskornia/geometry/boxes.py中xyxy/xyxy_plus模式先由xmax - xmin推出宽高xywh直接取宽高然后统一经_boxes_to_polygons生成四边形vertices模式则把输入顶点坐标减 1 转为包含式。from_tensor的 docstring 还给出了可复现的往返示例kornia/geometry/boxes.py。导出时的轴对齐归约to_tensorkornia/geometry/boxes.py不是简单取回data而是先用amin/amax归约出轴对齐包围盒再按目标模式导出boxes torch.stack([batched_boxes.amin(dim-2), batched_boxes.amax(dim-2)], dim-2)...因此对旋转过的四边形导出会丢失旋转信息to_tensor(vertices_plus)并不等于datato_tensor的默认模式是对象记录的mode构造函数默认vertices_plus而from_tensor会记住输入时的模式往返测试示例kornia/geometry/boxes.py验证了from_tensorto_tensor(xyxy)的往返一致性。列表输入与填充序列Boxes支持以每张图盒子数不等的列表形式创建构造函数内部通过_merge_box_listkornia/geometry/boxes.py用pad_sequence把各张量的盒子数补齐到最大N并记录每张图的填充数_N。导出时as_padded_sequenceTrue返回补零后的稠密张量as_padded_sequenceFalse默认返回裁剪回原始长度的张量列表。对应测试见test_boxes_list_to_tensor_listtests/geometry/test_boxes.py。创建与导出实战推荐统一用from_tensor导入、to_tensor导出import torch from kornia.geometry.boxes import Boxes, Boxes3D # 2D从 xyxy 导入 boxes_xyxy torch.as_tensor([[0, 3, 1, 4], [5, 1, 8, 4]]) boxes Boxes.from_tensor(boxes_xyxy, modexyxy) assert (boxes_xyxy boxes.to_tensor(modexyxy)).all() # 2D从 xywh 导入并导出为顶点 boxes_xywh torch.as_tensor([[10.0, 10.0, 50.0, 30.0]]) boxes2 Boxes.from_tensor(boxes_xywh, modexywh) verts boxes2.to_tensor(modevertices) # (1, 4, 2) # 3D从 xyzxyz 导入 boxes_xyzxyz torch.as_tensor([[0, 3, 6, 1, 4, 8], [5, 1, 3, 8, 4, 9]]) boxes3d Boxes3D.from_tensor(boxes_xyzxyz, modexyzxyz) assert (boxes3d.to_tensor(modexyzxyz) boxes_xyzxyz).all()from_tensor默认开启validate_boxesTrue会拒绝非有限坐标NaN/Inf并在xy*模式下拒绝非正宽高。构造函数的形状校验位于 kornia/geometry/boxes.py非(N, 4, 2)/(B, N, 4, 2)形状会直接抛出ValueError。几何操作变换、平移、填充与裁剪变换transform_boxes / transform_boxes_transform_boxeskornia/geometry/boxes.py对每个顶点应用齐次变换矩阵底层调用_transform_boxeskornia/geometry/boxes.py后者把四边形展平后交给kornia.geometry.linalg.transform_points批量变换再恢复原形状M torch.tensor([[1.0, 0.0, 10.0], [0.0, 1.0, 20.0], [0.0, 0.0, 1.0]]) boxes_t boxes.transform_boxes(M) # 非原地返回新对象 boxes.transform_boxes_(M) # 原地返回 self2D 要求M形状为(3, 3)或(B, 3, 3)批量数必须与盒子批量一致注意原地版本是把内部张量重新绑定到新结果因此在调用前取得的data引用不会再与容器共享内存测试test_convention_transform_boxes_in_place_rebinds_datatests/geometry/test_boxes.py。平移translatetranslatekornia/geometry/boxes.py接收形状(B, 2)的逐图(x, y)位移内部构造单位矩阵eye_like(3, size)并把size写入平移列后调用transform_boxes。目前仅实现methodwarpmethodfast会抛NotImplementedError。填充与反填充pad / unpadpad/unpadkornia/geometry/boxes.py以(left, right, top, bottom)顺序、形状(B, 4)的padding_size为参数。只有left和top会改变坐标原点pad给所有顶点加上left/topunpad则减去。二者都原地修改并返回 self支持(B, 4)单行广播到整个批量。数据增强中的RandomCrop正是通过pad路由边界框的。裁剪clampclampkornia/geometry/boxes.py把每个顶点独立限制在topleft(B, 2)最小x, y与botright(B, 2)最大x, y范围内。实现用torch.where逐坐标比较——遇到NaN边界时比较结果为False坐标保持原值而不是变成NaN。完全在界外的盒子会被压扁到最近的边界而非被删除。合并与定点写入merge / index_putmergekornia/geometry/boxes.py沿盒子轴拼接两个Boxes批量(B, N, 4, 2)(B, M, 4, 2)→(B, NM, 4, 2)若任一方来自列表会按每张图重新打包使真实盒子排在填充之前并合并_N填充计数index_putkornia/geometry/boxes.py镜像torch.Tensor.index_put_语义用于在批量中替换部分盒子的坐标同时保留Boxes包装与元数据两者默认都不原地修改。尺寸、面积与筛选get_boxes_shapeget_boxes_shapekornia/geometry/boxes.py返回(heights, widths)元组注意顺序是高在前数值与to_tensor(xywh, as_padded_sequenceTrue)完全一致采用包含式1约定boxes_xyxy torch.tensor([[[1, 1, 2, 2], [1, 1, 3, 2]]]) boxes Boxes.from_tensor(boxes_xyxy) boxes.get_boxes_shape() # (tensor([[1., 1.]]), tensor([[1., 2.]]))compute_area鞋带公式compute_areakornia/geometry/boxes.py先以顶点算数质心为基准用atan2求每个角相对质心的角度并按角度排序保证顶点按正确环绕序进入鞋带公式Shoelace formula从而对旋转四边形也能得到多边形面积。对轴对齐盒子其结果等价于(width - 1) * (height - 1)包含式顶点下的排他面积这与get_boxes_shape相乘得到的width * height存在约定差异源码中以 warning 注明跟踪于 issue #4010。filter_boxes_by_areafilter_boxes_by_areakornia/geometry/boxes.py接受可选的min_area/max_area阈值把面积越界的盒子坐标置零而不是从张量中删除从而保持(B, N, ...)形状不变阈值判定基于compute_area的面积约定。inplaceFalse时返回筛选后的克隆。掩码生成to_maskto_maskkornia/geometry/boxes.py把 2D 盒子转为二值掩码覆盖区域为 1其余为 0。签名是to_mask(height, width)注意与函数式bbox_to_mask(width, height)的参数顺序相反此差异在源码中注明跟踪于 issue #4014输出形状为(N, height, width)或(B, N, height, width)dtype 与盒子一致。实现细节先把盒子导出为排他式xyxyclamp 到[0, width]/[0, height]四舍五入为整数填充采用半开区间[xmin, xmax)、[ymin, ymax)因此完全在图像外的盒子不填充任何像素CPU / MPS 走循环路径逐通道切片赋值CUDA 与图捕获导出走向量化路径坐标网格比较两条路径产出相同掩码需要梯度的盒子张量会被拒绝RuntimeError当前接口不可微分列表创建的盒子会为每个填充项保留一个空掩码通道。docstring 给出了可运行示例kornia/geometry/boxes.pyboxes Boxes(torch.tensor([[ [1., 1.], [4., 1.], [4., 3.], [1., 3.], ]])) boxes.to_mask(5, 5) # tensor([[[0., 0., 0., 0., 0.], # [0., 1., 1., 1., 1.], # [0., 1., 1., 1., 1.], # [0., 1., 1., 1., 1.], # [0., 0., 0., 0., 0.]]])Boxes3D八顶点六面体的三维封装Boxes3Dkornia/geometry/boxes.py对应 3D 空间中的盒子hexahedron六面体每个盒子是 8 个浮点(x, y, z)顶点顺序为前上左、前上右、前下右、前下左再依次为四个后顶点存储形状(N, 8, 3)或(B, N, 8, 3)。内部同样采用包含式约定width/height/depth max - min 1。3D 格式模式from_tensor接受三种导入模式形状(N, 6)/(B, N, 6)模式含义xyzxyzxmin, ymin, zmin, xmax, ymax, zmax排他式xyzxyz_plus同上但含1的包含式xyzwhdxmin, ymin, zmin, width, height, depth排他式to_tensor额外支持vertices/vertices_plus顶点导出模式形状(N, 8, 3)。顶点展开由_boxes3d_to_polygons3dkornia/geometry/boxes.py实现先构造前 4 顶点再沿z轴加上depth - 1克隆出后 4 顶点。需要注意的两点差异源码中均以 warning 注明Boxes3D.to_tensor的默认导出模式恒为xyzxyz与存储标签无关跟踪于 issue #4251而 2D 的Boxes.to_tensor默认使用存储模式xyzxyz模式下xmax xmin会被validate_boxes拒绝而xyzxyz_plus会接受。3D 变换与掩码transform_boxeskornia/geometry/boxes.py要求M为(4, 4)或(B, 4, 4)的齐次矩阵非原地调用返回标注为xyzxyz_plus的新对象to_mask(depth, height, width)kornia/geometry/boxes.py输出(N, depth, height, width)或(B, N, depth, height, width)的三维掩码导出排他式xyzxyz后按半开区间填充图捕获导出路径同样采用坐标网格比较get_boxes_shape返回(depths, heights, widths)深度在前。docstring 中给出了 3D 掩码的完整示例kornia/geometry/boxes.py一个1x1x1到3x3x2的盒子在4x5x5体积中产生两个填充平面。VideoBoxes带时间通道的视频盒子VideoBoxeskornia/geometry/boxes.py是Boxes的视频专用子类处理形状(B, T, N, 4, 2)的视频批次盒子B批、T帧、N盒。设计要点from_tensor仅接受(B, T, N, 4, 2)张量内部展平为(B*T, N, 4, 2)存储并记录temporal_channel_size T列表输入会抛ValueErrorto_tensor恢复时间轴to_tensor(xyxy)得到(B, T, N, 4)变换矩阵必须按展平帧提供(B*T, 3, 3)单个(3, 3)矩阵会抛ValueError继承自Boxes的transform_boxes、translate、clamp、filter_boxes_by_area、merge均通过clone返回新对象并保留temporal_channel_size。与数据增强管线的集成Boxes是 Kornia 增强系统的一等公民数据类型kornia/augmentation/base.py 的transform_boxes接收Boxes输入按batch_prob在变换结果与未变换结果之间混合并在自动混合精度autocast下还原 dtype最终复用未变换容器以保留mode/_N/_is_batched等元数据各 2D 几何增强的apply_transform_box见 kornia/augmentation/_2d/geometric/base.py直接把增强采样得到的变换矩阵交给input.transform_boxes_(transform)AugmentationSequential在管线包含视频序列时会用VideoBoxes.from_tensor包装输入见 kornia/augmentation/container/augment.py使to_tensor在几何变换后恢复时间轴RandomCrop等需要裁剪坐标的增强通过Boxes.pad路由边界框pad的 docstring 明确说明该用途见 kornia/geometry/boxes.py。增强中边界框的输入约定见 kornia/augmentation/container/augment.pybbox使用(B, N, 4, 2)顶点格式bbox_xyxy/bbox_xywh使用(B, N, 4)统一按Boxes的包含式xyxy_plus约定读写——这比排他式xyxy每轴宽一格。边界与注意事项重要约定差异从源码 docstring 与测试tests/geometry/test_boxes.py可以确认以下需要注意的约定使用时务必留意包含式1算术与其他生态不同KorniaBoxes的1约定与 torchvision、COCO、albumentations 不一致属于跨库已知差异跟踪于 issue #3934亚单位跨度会被破坏归一化到[0, 1]且某轴跨度小于 1 的盒子在xyxy/xywh/vertices三种转换模式下会因-1反转四边形而被静默损坏issue #4061xyxy_plus与vertices_plus不受影响旋转盒子的导出有损to_tensor一律先做轴对齐归约旋转、剪切后的四边形导出必然丢失旋转信息整数输入策略分裂构造函数默认拒绝整数张量除非raise_if_not_floating_pointFalse而from_tensor会静默把整数转为torch.get_default_dtype()issue #4012。列表输入则以第一个元素的 dtype 为准其余元素会被强制转换尚未实现的功能trim、translate(methodfast)以及clamp的元组边界均未实现调用会抛NotImplementedErrorissue #4017顶点模式未做校验validate_boxesTrue时xy*模式会校验非有限坐标与非正尺寸但顶点模式不校验issue #4177梯度与可微分性to_mask拒绝需要梯度的盒子不可微分to_tensor本身可微分其amin/amax归约在顶点恰好并列极值时把梯度均分给并列顶点属于合法次梯度测试test_convention_to_tensor_tie_gradient_is_an_even_subgradient_1396tests/geometry/test_boxes.py对此有专门验证。总结kornia.geometry.boxes提供了 Kornia 中最完整、最规范的边界框抽象Boxes2D 四边形、Boxes3D3D 六面体与VideoBoxes视频时间轴三个容器统一以包含式顶点为内部表示通过from_tensor/to_tensor在五种格式间自由转换并原生支持transform_boxes、translate、pad/unpad、clamp、merge、compute_area、filter_boxes_by_area与to_mask等几何操作。它既是检测框后处理的实用工具也是数据增强管线中边界框同步变换的官方载体。配合函数式 kornia/geometry/bbox.py 接口可以覆盖从格式校验、NMS 到掩码生成的全部边界框处理需求。赞分享计算机视觉人工智能深度学习图像处理【免费下载链接】kornia Geometric Computer Vision Library for Spatial AI项目地址https://gitcode.com/gh_mirrors/ko/kornia点击查看免费下载相关推荐Kornia 面向对象边界框 API 完全指南Boxes / Boxes3D / VideoBoxes 的格式转换、变换与填充Kornia 面向对象边界框 API 完全指南Boxes / Boxes3D / VideoBoxes 的格式转换、变换与填充 导读 kornia.geome计算机视觉深度学习人工智能图像处理微信/QQ/TIM消息总被撤回这款免费开源补丁三步搞定防撤回——RevokeMsgPatcher 2.1实战记录微信/QQ/TIM消息总被撤回这款免费开源补丁三步搞定防撤回——RevokeMsgPatcher 2.1实战记录 如果你也经历过消息刚看完就被撤回了的憋屈计算机视觉深度学习人工智能图像处理Elixir代码生成Erlang抽象格式转换Elixir代码生成Erlang抽象格式转换 引言 在Elixir生态系统中代码生成Code Generation是一个强大而核心的功能。Elixir通编程语言编译器标准库语言运行时并发编程上一篇openeuler/oec-application完全指南如何快速验证应用与openEuler的兼容性下一篇Shoelace 安装与引入完全指南CDN、npm、按需加载与打包配置详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考