Ultralytics YOLO Simple Utilities 实用工具全指南数据标注、格式转换、边界框处理与可视化开发【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10本指南系统梳理 Ultralytics YOLOYOLOv10 同框架内置的ultralytics工具函数与类覆盖数据集自动标注、COCO/YOLO 格式互转、边界框坐标换算、图像压缩、数据集自动划分、标注可视化与代码性能分析等高频场景。读完本文你将掌握这些工具的真实签名、默认参数、调用方式与底层实现逻辑能够直接在自己的数据流水线与开发工作流中复用。概述为什么需要这些小工具ultralytics包自带大量可支撑、增强并加速工作流的工具函数它们分布在数据、坐标运算、可视化等多个子模块中。这些工具不仅实用而且是学习 Python 工程化编码的优秀参考——例如 ultralytics/utils/ops.py 中的坐标换算函数、ultralytics/utils/instance.py 中的Bboxes类都体现了类型断言、原地/拷贝运算、向量化处理的规范写法。下面按Data / Utilities / Bounding Boxes / Plotting / Miscellaneous五大类逐一展开。数据工具DataYOLO Data Explorer用文本查询探索数据集YOLO Explorer 于8.1.0周年更新中加入是理解数据集的强大工具核心能力之一是通过文本查询在数据集中检索目标实例。从源码看其实现位于 ultralytics/data/explorer/explorer.pyExplorer类基于 LanceDB 向量数据库与 DuckDB 构建初始化时要求lancedb0.4.3与duckdb0.9.2query()支持传入单张/多张图片路径或 ndarray检索相似图片sql_query()支持对数据表执行 SQL 风格查询利用 LanceDB 谓词下推similarity_search()与plot_similarity_index()分别执行向量相似检索与相似度索引可视化。建议结合 docs/en/datasets/explorer/index.md 阅读完整用法。自动标注 / 生成分割标注auto_annotate数据集标注是极度消耗资源与时间的过程。如果你已有一个在合理规模数据上训练好的 YOLO 目标检测模型就可以用它配合 SAM 模型 对新增数据自动标注输出分割格式from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolov8n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )该函数无返回值标注结果以 YOLO 分割格式写入output_dir下的*.txt文件。其实现位于 ultralytics/data/annotator.py关键流程如下用YOLO(det_model)加载检测模型用SAM(sam_model)加载分割模型若未指定output_dir默认保存到data目录同级、名为data 目录名_auto_annotate_labels的文件夹以det_model(data, streamTrue, devicedevice)流式推理得到检测框对每个检测结果用sam_model(result.orig_img, bboxesboxes, ...)生成分割掩码将masks.xyn归一化分割点按class_id x1 y1 x2 y2 ...的格式写入文本文件。注意函数默认的det_model为yolov8x.pt、sam_model为sam_b.ptdevice默认为空字符串自动选择 CPU/GPU。更多细节见 annotator.auto_annotate 参考文档。可与下文 segments2boxes 组合使用额外生成检测框标注。将 COCO 格式转换为 YOLO 格式convert_coco使用convert_coco可将 COCO JSON 标注转换为标准 YOLO 格式。对于目标检测边界框数据集use_segments与use_keypoints均应设为Falsefrom ultralytics.data.converter import convert_coco convert_coco( ../datasets/coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )实现位于 ultralytics/data/converter.py函数签名与行为要点convert_coco( labels_dir../coco/annotations/, # 存放 COCO annotations 的目录 save_dircoco_converted/, # 输出目录 use_segmentsFalse, # 是否输出分割标注 use_keypointsFalse, # 是否输出关键点标注 cls91to80True, # 是否将 91 类 COCO 映射为 80 类 )底层处理逻辑遍历labels_dir下所有*.json文件使用increment_path避免输出目录冲突COCO 框格式为[左上角 x, 左上角 y, 宽度, 高度]转换时先box[:2] box[2:] / 2将左上角原点换算为中心点再按图像宽高归一化跳过iscrowd标注与宽高非正的框当cls91to80True时通过coco91_to_coco80_class()完成类别索引映射该表定义了 91 索引到 80 索引的完整对应索引位置为None表示该类别被剔除use_segmentsTrue时对多段分割调用merge_multi_segment合并为单段use_keypointsTrue时输出cls box keypoints行。完整参数说明见 converter.convert_coco 参考文档。同文件还提供convert_dota_to_yolo_obbDOTA 数据集转 YOLO OBB 格式、coco80_to_coco91_class等配套函数。边界框转分割标注yolo_bbox2segment已有x y w h边界框数据时可用yolo_bbox2segment生成分割标注。图像与标注文件需按以下目录结构组织data |__ images ├─ 001.jpg ├─ 002.jpg ├─ .. └─ NNN.jpg |__ labels ├─ 001.txt ├─ 002.txt ├─ .. └─ NNN.txtfrom ultralytics.data.converter import yolo_bbox2segment yolo_bbox2segment( im_dirpath/to/images, save_dirNone, # 默认保存在 images 目录下的 labels-segment sam_modelsam_b.pt )实现逻辑ultralytics/data/converter.py先通过YOLODataset加载检测数据集若labels[0][segments]非空则提示已检测到分割标注无需生成并直接返回否则用SAM(sam_model)对每张图的检测框经xywh2xyxy转为像素坐标生成掩码存入masks.xyn最终写入save_dir默认im_dir同级labels-segment目录。更多信息见 yolo_bbox2segment 参考文档。分割转边界框segments2boxes若数据集使用分割数据集格式可轻松将其转换为水平up-right边界框x y w h格式from ultralytics.utils.ops import segments2boxes segments np.array( [[805, 392, 797, 400, ..., 808, 714, 808, 392], [115, 398, 113, 400, ..., 150, 400, 149, 298], [267, 412, 265, 413, ..., 300, 413, 299, 412], ] ) segments2boxes([s.reshape(-1,2) for s in segments]) array([[ 741.66, 631.12, 133.31, 479.25], [ 146.81, 649.69, 185.62, 502.88], [ 281.81, 636.19, 118.12, 448.88]], dtypefloat32) # xywh bounding boxes实现于 ultralytics/utils/ops.pydef segments2boxes(segments): boxes [] for s in segments: x, y s.T # 取所有点的 x、y 坐标 boxes.append([x.min(), y.min(), x.max(), y.max()]) # 计算外包 xyxy return xyxy2xywh(np.array(boxes)) # 再转为 xywh即先求分割点集的外接矩形xyxy再换算为中心点加宽高的xywh格式。原理细节见 ops.segments2boxes 参考文档。通用工具Utilities图像压缩compress_one_imagecompress_one_image在保持宽高比与质量的前提下压缩单张图片。若输入图像尺寸小于最大边长则不会进行缩放from pathlib import Path from ultralytics.data.utils import compress_one_image for f in Path(path/to/dataset).rglob(*.jpg): compress_one_image(f)实现位于 ultralytics/data/utils.pycompress_one_image(f, f_newNone, max_dim1920, quality50)f输入图片路径f_new输出路径未指定时原地覆盖输入文件max_dim输出图片的最大边长默认 1920 像素qualityJPEG 压缩质量百分比默认 50%优先使用 PIL 处理im.resize等比缩放后以quality与optimizeTrue保存PIL 失败时回退到 OpenCV使用cv2.INTER_AREA插值缩放。该函数无返回值。它在HUBDatasetStats.process_images()中也被用于生成数据集预览图调用compress_one_image(f, self.im_dir / Path(f).name)。自动划分数据集autosplitautosplit自动将数据集划分为train/val/test并把划分结果保存到autosplit_*.txt文件。注意它使用随机采样与训练时的fraction参数见 train 模式参数不是一回事from ultralytics.data.utils import autosplit autosplit( pathpath/to/images, weights(0.9, 0.1, 0.0), # (train, validation, test) 划分比例 annotated_onlyFalse # True 时仅划分有标注文件的图片 )实现要点ultralytics/data/utils.py递归收集path下所有IMG_FORMATS图片random.seed(0)保证可复现用random.choices([0, 1, 2], weightsweights, kn)为每张图分配划分生成autosplit_train.txt、autosplit_val.txt、autosplit_test.txt三个文件写入相对路径写入前会删除已存在的同名文件annotated_onlyTrue时通过img2label_paths检查对应.txt标签是否存在仅保留有标签的图片。完整细节见 data.utils.autosplit 参考文档。多边形转二值掩码polygon2mask将单个多边形列表形式转换为指定图像尺寸的二值掩码。多边形形式为[N, 2]N为构成轮廓的(x, y)点数量。⚠️ 警告N必须始终为偶数点以x,y交替展平存放。import numpy as np from ultralytics.data.utils import polygon2mask imgsz (1080, 810) polygon np.array( [805, 392, 797, 400, ..., 808, 714, 808, 392], # (238, 2) ) mask polygon2mask( imgsz, # 图像尺寸 (height, width) 元组 [polygon], # 多边形需以列表传入 color255, # 8-bit 二值填充值 downsample_ratio1 )实现逻辑ultralytics/data/utils.py先创建np.zeros(imgsz, dtypenp.uint8)将多边形 reshape 为(N, -1, 2)后调用cv2.fillPoly填充最后按downsample_ratio缩放先填充后缩放是为了与mask-ratio1时的损失计算方式保持一致。同模块还提供polygons2masks批量与polygons2masks_overlap重叠掩码合并。边界框工具Bounding Boxes水平边界框实例管理Bboxes 类Bboxes类用于管理边界框数据支持坐标格式互转、框尺寸缩放、面积计算、偏移等操作from ultralytics.utils.instance import Bboxes boxes Bboxes( bboxesnp.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ), formatxyxy, ) boxes.areas() array([ 4.1104e05, 99216, 68000, 55772, 20347, 2288.5]) boxes.convert(xywh) boxes.bboxes array( [[ 413.93, 494.05, 782.1, 525.56], [ 146.95, 650.63, 196.8, 504.15], [ 739.6, 634.62, 140.25, 484.85], [ 283.25, 631.67, 123.46, 451.74], [ 31.505, 711.99, 63.01, 322.91], [ 16.31, 289.67, 32.503, 70.41]] )从 ultralytics/utils/instance.py 源码可见支持三种格式xyxy左上/右下角、xywh中心点 x/y 宽高即 YOLO 格式、ltwh左上角 宽高即 COCO 格式__init__会断言格式合法、二维数组且列数为 4一维输入会被提升为(1, 4)convert(format)按当前格式动态选择xyxy2xywh、xywh2xyxy、ltwh2xywh等底层函数完成互转areas()先将框转为xyxy再计算(x2-x1)*(y2-y1)另有mul(scale)四维缩放、add(offset)四维偏移、concatenate合并多个 Bboxes等方法。更多属性与方法见 Bboxes 参考文档。 提示下文的许多函数以及更多功能都可以通过Bboxes类访问但如果你更习惯直接调用函数可以按后续小节独立导入。缩放边界框scale_boxes图像放大/缩小时可用scale_boxes让对应边界框坐标同步缩放import cv2 as cv import numpy as np from ultralytics.utils.ops import scale_boxes image cv.imread(ultralytics/assets/bus.jpg) *(h, w), c image.shape resized cv.resize(image, None, (), fx1.2, fy1.2) *(new_h, new_w), _ resized.shape xyxy_boxes np.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ) new_boxes scale_boxes( img1_shape(h, w), # 原图尺寸 boxesxyxy_boxes, # 原图上的框 img0_shape(new_h, new_w), # 缩放后图像的尺寸缩放目标 ratio_padNone, paddingFalse, xywhFalse, ) new_boxes array( [[ 27.454, 277.52, 965.98, 908.2], [ 58.262, 478.27, 294.42, 1083.3], [ 803.36, 470.63, 971.66, 1052.4], [ 265.82, 486.96, 413.98, 1029], [ 0, 660.64, 75.612, 1048.1], [ 0.0701, 305.35, 39.073, 389.84]] )实现要点ultralytics/utils/ops.py未提供ratio_pad时按gain min(img1_shape[0]/img0_shape[0], img1_shape[1]/img0_shape[1])计算缩放比例并推导 letterbox 式的 paddingpaddingTrue时默认先减去 padding 再乘gain还原到无 letterbox的坐标系paddingFalse时直接按比例缩放xywhTrue表示输入为xywh格式。边界框格式互转XYXY → XYWH将边界框从(x1, y1, x2, y2)转为(x, y, width, height)格式其中(x1, y1)为左上角、(x2, y2)为右下角import numpy as np from ultralytics.utils.ops import xyxy2xywh xyxy_boxes np.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ) xywh xyxy2xywh(xyxy_boxes) xywh array( [[ 413.93, 494.05, 782.1, 525.56], [ 146.95, 650.63, 196.8, 504.15], [ 739.6, 634.62, 140.25, 484.85], [ 283.25, 631.67, 123.46, 451.74], [ 31.505, 711.99, 63.01, 322.91], [ 16.31, 289.67, 32.503, 70.41]] )实现上对每一维分别计算x (x1x2)/2y (y1y2)/2w x2-x1h y2-y1。全部边界框转换函数ultralytics.utils.ops提供了完整的坐标格式转换家族from ultralytics.utils.ops import xywh2xyxy from ultralytics.utils.ops import xywhn2xyxy # 归一化 → 像素 from ultralytics.utils.ops import xyxy2xywhn # 像素 → 归一化 from ultralytics.utils.ops import xywh2ltwh # xywh → 左上角坐标, w, h from ultralytics.utils.ops import xyxy2ltwh # xyxy → 左上角坐标, w, h from ultralytics.utils.ops import ltwh2xywh from ultralytics.utils.ops import ltwh2xyxy各函数典型签名与语义均可同时接受 NumPy 数组与 PyTorch Tensor并断言最后一维为 4xywh2xyxy(x)中心点格式转角点格式dwx[2]/2、dhx[3]/2向四周展开xywhn2xyxy(x, w640, h640, padw0, padh0)归一化中心格式转像素角点格式可附加 pad 偏移xyxy2xywhn(x, w640, h640, clipFalse, eps0.0)像素角点转归一化中心格式clipTrue时先裁剪到图像边界xywh2ltwh(x)/xyxy2ltwh(x)转左上角 宽高COCO 风格前者只需平移-w/2, -h/2后者只需计算w x2-x1ltwh2xywh(x)/ltwh2xyxy(x)上述的逆变换。更多细节可阅读各函数 docstring 或 ultralytics.utils.ops 参考文档。绘图工具Plotting绘制标注Annotator 类Ultralytics 内置Annotator类可用于标注任意类型数据最常配合目标检测框、姿态关键点与旋转框 OBB 使用。水平边界框标注import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors names { # 也可直接使用 model.names见 working with results 0: person, 5: bus, 11: stop sign, } image cv.imread(ultralytics/assets/bus.jpg) ann Annotator( image, line_widthNone, # 默认自适应 font_sizeNone, # 默认自适应 fontArial.ttf, # 需与 ImageFont 兼容 pilFalse, # False 使用 OpenCV 绘制True 使用 PIL ) xyxy_boxes np.array( [[ 5, 22.878, 231.27, 804.98, 756.83,], # class-idx x1 y1 x2 y2 [ 0, 48.552, 398.56, 245.35, 902.71,], [ 0, 669.47, 392.19, 809.72, 877.04,], [ 0, 221.52, 405.8, 344.98, 857.54,], [ 0, 0, 550.53, 63.01, 873.44,], [11, 0.0584, 254.46, 32.561, 324.87,]] ) for nb, box in enumerate(xyxy_boxes): c_idx, *box box label f{str(nb).zfill(2)}:{names.get(int(c_idx))} ann.box_label(box, label, colorcolors(c_idx, bgrTrue)) image_with_bboxes ann.result()Annotator的初始化会依据是否传入 PIL 图像、标签是否含非 ASCII 字符自动选择 PIL 或 OpenCV 渲染路径ultralytics/utils/plotting.pyline_width未指定时按图像尺寸自适应max(round(sum(shape)/2 * 0.003), 2)。box_label支持rotatedTrue绘制多边形旋转框result()返回标注后的np.asarray图像此外还有show()与save()便捷方法。colors(c_idx, bgrTrue)从内置调色板取色内部为 TABLEAU_COLORS 风格的 10 色循环调色板。旋转边界框OBB标注import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors obb_names {10: small vehicle} obb_image cv.imread(datasets/dota8/images/train/P1142__1024__0___824.jpg) obb_boxes np.array( [[ 0, 635, 560, 919, 719, 1087, 420, 803, 261,], # class-idx x1 y1 x2 y2 x3 y2 x4 y4 [ 0, 331, 19, 493, 260, 776, 70, 613, -171,], [ 9, 869, 161, 886, 147, 851, 101, 833, 115,] ] ) ann Annotator( obb_image, line_widthNone, # 默认自适应 font_sizeNone, # 默认自适应 fontArial.ttf, # 需与 ImageFont 兼容 pilFalse, # False 使用 OpenCV 绘制 ) for obb in obb_boxes: c_idx, *obb obb obb np.array(obb).reshape(-1, 4, 2).squeeze() label f{names.get(int(c_idx))} ann.box_label( obb, label, colorcolors(c_idx, True), rotatedTrue, ) image_with_obb ann.result()OBB 的 8 个坐标先reshape(-1, 4, 2)成 4 个角点再以rotatedTrue交给box_label内部会走draw.polygon/cv2.polylines分支绘制多边形。更多细节见 Annotator 参考文档。杂项工具Miscellaneous代码性能分析ProfileProfile用于测量代码运行耗时既可作为with上下文管理器也可作为装饰器from ultralytics.utils.ops import Profile with Profile(devicedevice) as dt: pass # 待测操作 print(dt) Elapsed time is 9.5367431640625e-07 s实现位于 ultralytics/utils/ops.py继承contextlib.ContextDecorator__init__(self, t0.0, deviceNone)可传入初始时间与设备cuda bool(device and str(device).startswith(cuda))即当device以cuda开头时计时使用 CUDA 事件torch.cuda.Event否则使用time.perf_counter——这使得 GPU 推理耗时测量也能精确。Ultralytics 支持的图片/视频格式常量如需在代码中以编程方式获取 Ultralytics 支持的图片与视频格式可直接使用如下常量from ultralytics.data.utils import IMG_FORMATS from ultralytics.data.utils import VID_FORMATS print(IMG_FORMATS) (bmp, dng, jpeg, jpg, mpo, png, tif, tiff, webp, pfm)定义于 ultralytics/data/utils.pyIMG_FORMATS {bmp, dng, jpeg, jpg, mpo, png, tif, tiff, webp, pfm} VID_FORMATS {asf, avi, gif, m4v, mkv, mov, mp4, mpeg, mpg, ts, wmv, webm}它们同时被数据集校验verify_image/verify_image_label、autosplit、HUBDatasetStats等内部逻辑广泛使用。取整到可整除make_divisible计算最接近x、且能被y整除的整数from ultralytics.utils.ops import make_divisible make_divisible(7, 3) 9 make_divisible(7, 2) 8实现为math.ceil(x / divisor) * divisorultralytics/utils/ops.py即向上取整保证结果不小于x。该函数在网络结构设计如通道数对齐与推理尺寸对齐中经常被用到若传入torch.Tensor的divisor会先取int(divisor.max())。实践建议与组合用法数据流水线组合convert_coco完成格式统一 →autosplit划分数据集 →compress_one_image压缩训练图像可在训练前一站式完成数据准备半自动标注链路auto_annotate生成分割标注后用segments2boxes反推xywh检测框实现检测 分割双任务数据集的同时扩增yolo_bbox2segment则面向相反方向已有检测框补充分割可视化与调试Annotator配合Bboxes/scale_boxes/各转换函数可以快速绘制缩放前后的框验证增强流程的正确性格式约定提醒xywh的中心点表示是 YOLO 训练标签的标准格式归一化后即xywhn而 COCO 使用ltwh跨框架迁移数据时务必使用ultralytics.utils.ops中的转换函数避免坐标语义错位。以上工具的完整签名与参考实现均可通过 docs/en/reference 下的对应参考文档进一步查阅也可直接阅读仓库源码 ultralytics/data/utils.py、ultralytics/utils/ops.py、ultralytics/utils/instance.py、ultralytics/utils/plotting.py 与 ultralytics/data/annotator.py。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics YOLO Simple Utilities 实用工具全指南：数据标注、格式转换、边界框处理与可视化开发
Ultralytics YOLO Simple Utilities 实用工具全指南数据标注、格式转换、边界框处理与可视化开发【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10本指南系统梳理 Ultralytics YOLOYOLOv10 同框架内置的ultralytics工具函数与类覆盖数据集自动标注、COCO/YOLO 格式互转、边界框坐标换算、图像压缩、数据集自动划分、标注可视化与代码性能分析等高频场景。读完本文你将掌握这些工具的真实签名、默认参数、调用方式与底层实现逻辑能够直接在自己的数据流水线与开发工作流中复用。概述为什么需要这些小工具ultralytics包自带大量可支撑、增强并加速工作流的工具函数它们分布在数据、坐标运算、可视化等多个子模块中。这些工具不仅实用而且是学习 Python 工程化编码的优秀参考——例如 ultralytics/utils/ops.py 中的坐标换算函数、ultralytics/utils/instance.py 中的Bboxes类都体现了类型断言、原地/拷贝运算、向量化处理的规范写法。下面按Data / Utilities / Bounding Boxes / Plotting / Miscellaneous五大类逐一展开。数据工具DataYOLO Data Explorer用文本查询探索数据集YOLO Explorer 于8.1.0周年更新中加入是理解数据集的强大工具核心能力之一是通过文本查询在数据集中检索目标实例。从源码看其实现位于 ultralytics/data/explorer/explorer.pyExplorer类基于 LanceDB 向量数据库与 DuckDB 构建初始化时要求lancedb0.4.3与duckdb0.9.2query()支持传入单张/多张图片路径或 ndarray检索相似图片sql_query()支持对数据表执行 SQL 风格查询利用 LanceDB 谓词下推similarity_search()与plot_similarity_index()分别执行向量相似检索与相似度索引可视化。建议结合 docs/en/datasets/explorer/index.md 阅读完整用法。自动标注 / 生成分割标注auto_annotate数据集标注是极度消耗资源与时间的过程。如果你已有一个在合理规模数据上训练好的 YOLO 目标检测模型就可以用它配合 SAM 模型 对新增数据自动标注输出分割格式from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolov8n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )该函数无返回值标注结果以 YOLO 分割格式写入output_dir下的*.txt文件。其实现位于 ultralytics/data/annotator.py关键流程如下用YOLO(det_model)加载检测模型用SAM(sam_model)加载分割模型若未指定output_dir默认保存到data目录同级、名为data 目录名_auto_annotate_labels的文件夹以det_model(data, streamTrue, devicedevice)流式推理得到检测框对每个检测结果用sam_model(result.orig_img, bboxesboxes, ...)生成分割掩码将masks.xyn归一化分割点按class_id x1 y1 x2 y2 ...的格式写入文本文件。注意函数默认的det_model为yolov8x.pt、sam_model为sam_b.ptdevice默认为空字符串自动选择 CPU/GPU。更多细节见 annotator.auto_annotate 参考文档。可与下文 segments2boxes 组合使用额外生成检测框标注。将 COCO 格式转换为 YOLO 格式convert_coco使用convert_coco可将 COCO JSON 标注转换为标准 YOLO 格式。对于目标检测边界框数据集use_segments与use_keypoints均应设为Falsefrom ultralytics.data.converter import convert_coco convert_coco( ../datasets/coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )实现位于 ultralytics/data/converter.py函数签名与行为要点convert_coco( labels_dir../coco/annotations/, # 存放 COCO annotations 的目录 save_dircoco_converted/, # 输出目录 use_segmentsFalse, # 是否输出分割标注 use_keypointsFalse, # 是否输出关键点标注 cls91to80True, # 是否将 91 类 COCO 映射为 80 类 )底层处理逻辑遍历labels_dir下所有*.json文件使用increment_path避免输出目录冲突COCO 框格式为[左上角 x, 左上角 y, 宽度, 高度]转换时先box[:2] box[2:] / 2将左上角原点换算为中心点再按图像宽高归一化跳过iscrowd标注与宽高非正的框当cls91to80True时通过coco91_to_coco80_class()完成类别索引映射该表定义了 91 索引到 80 索引的完整对应索引位置为None表示该类别被剔除use_segmentsTrue时对多段分割调用merge_multi_segment合并为单段use_keypointsTrue时输出cls box keypoints行。完整参数说明见 converter.convert_coco 参考文档。同文件还提供convert_dota_to_yolo_obbDOTA 数据集转 YOLO OBB 格式、coco80_to_coco91_class等配套函数。边界框转分割标注yolo_bbox2segment已有x y w h边界框数据时可用yolo_bbox2segment生成分割标注。图像与标注文件需按以下目录结构组织data |__ images ├─ 001.jpg ├─ 002.jpg ├─ .. └─ NNN.jpg |__ labels ├─ 001.txt ├─ 002.txt ├─ .. └─ NNN.txtfrom ultralytics.data.converter import yolo_bbox2segment yolo_bbox2segment( im_dirpath/to/images, save_dirNone, # 默认保存在 images 目录下的 labels-segment sam_modelsam_b.pt )实现逻辑ultralytics/data/converter.py先通过YOLODataset加载检测数据集若labels[0][segments]非空则提示已检测到分割标注无需生成并直接返回否则用SAM(sam_model)对每张图的检测框经xywh2xyxy转为像素坐标生成掩码存入masks.xyn最终写入save_dir默认im_dir同级labels-segment目录。更多信息见 yolo_bbox2segment 参考文档。分割转边界框segments2boxes若数据集使用分割数据集格式可轻松将其转换为水平up-right边界框x y w h格式from ultralytics.utils.ops import segments2boxes segments np.array( [[805, 392, 797, 400, ..., 808, 714, 808, 392], [115, 398, 113, 400, ..., 150, 400, 149, 298], [267, 412, 265, 413, ..., 300, 413, 299, 412], ] ) segments2boxes([s.reshape(-1,2) for s in segments]) array([[ 741.66, 631.12, 133.31, 479.25], [ 146.81, 649.69, 185.62, 502.88], [ 281.81, 636.19, 118.12, 448.88]], dtypefloat32) # xywh bounding boxes实现于 ultralytics/utils/ops.pydef segments2boxes(segments): boxes [] for s in segments: x, y s.T # 取所有点的 x、y 坐标 boxes.append([x.min(), y.min(), x.max(), y.max()]) # 计算外包 xyxy return xyxy2xywh(np.array(boxes)) # 再转为 xywh即先求分割点集的外接矩形xyxy再换算为中心点加宽高的xywh格式。原理细节见 ops.segments2boxes 参考文档。通用工具Utilities图像压缩compress_one_imagecompress_one_image在保持宽高比与质量的前提下压缩单张图片。若输入图像尺寸小于最大边长则不会进行缩放from pathlib import Path from ultralytics.data.utils import compress_one_image for f in Path(path/to/dataset).rglob(*.jpg): compress_one_image(f)实现位于 ultralytics/data/utils.pycompress_one_image(f, f_newNone, max_dim1920, quality50)f输入图片路径f_new输出路径未指定时原地覆盖输入文件max_dim输出图片的最大边长默认 1920 像素qualityJPEG 压缩质量百分比默认 50%优先使用 PIL 处理im.resize等比缩放后以quality与optimizeTrue保存PIL 失败时回退到 OpenCV使用cv2.INTER_AREA插值缩放。该函数无返回值。它在HUBDatasetStats.process_images()中也被用于生成数据集预览图调用compress_one_image(f, self.im_dir / Path(f).name)。自动划分数据集autosplitautosplit自动将数据集划分为train/val/test并把划分结果保存到autosplit_*.txt文件。注意它使用随机采样与训练时的fraction参数见 train 模式参数不是一回事from ultralytics.data.utils import autosplit autosplit( pathpath/to/images, weights(0.9, 0.1, 0.0), # (train, validation, test) 划分比例 annotated_onlyFalse # True 时仅划分有标注文件的图片 )实现要点ultralytics/data/utils.py递归收集path下所有IMG_FORMATS图片random.seed(0)保证可复现用random.choices([0, 1, 2], weightsweights, kn)为每张图分配划分生成autosplit_train.txt、autosplit_val.txt、autosplit_test.txt三个文件写入相对路径写入前会删除已存在的同名文件annotated_onlyTrue时通过img2label_paths检查对应.txt标签是否存在仅保留有标签的图片。完整细节见 data.utils.autosplit 参考文档。多边形转二值掩码polygon2mask将单个多边形列表形式转换为指定图像尺寸的二值掩码。多边形形式为[N, 2]N为构成轮廓的(x, y)点数量。⚠️ 警告N必须始终为偶数点以x,y交替展平存放。import numpy as np from ultralytics.data.utils import polygon2mask imgsz (1080, 810) polygon np.array( [805, 392, 797, 400, ..., 808, 714, 808, 392], # (238, 2) ) mask polygon2mask( imgsz, # 图像尺寸 (height, width) 元组 [polygon], # 多边形需以列表传入 color255, # 8-bit 二值填充值 downsample_ratio1 )实现逻辑ultralytics/data/utils.py先创建np.zeros(imgsz, dtypenp.uint8)将多边形 reshape 为(N, -1, 2)后调用cv2.fillPoly填充最后按downsample_ratio缩放先填充后缩放是为了与mask-ratio1时的损失计算方式保持一致。同模块还提供polygons2masks批量与polygons2masks_overlap重叠掩码合并。边界框工具Bounding Boxes水平边界框实例管理Bboxes 类Bboxes类用于管理边界框数据支持坐标格式互转、框尺寸缩放、面积计算、偏移等操作from ultralytics.utils.instance import Bboxes boxes Bboxes( bboxesnp.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ), formatxyxy, ) boxes.areas() array([ 4.1104e05, 99216, 68000, 55772, 20347, 2288.5]) boxes.convert(xywh) boxes.bboxes array( [[ 413.93, 494.05, 782.1, 525.56], [ 146.95, 650.63, 196.8, 504.15], [ 739.6, 634.62, 140.25, 484.85], [ 283.25, 631.67, 123.46, 451.74], [ 31.505, 711.99, 63.01, 322.91], [ 16.31, 289.67, 32.503, 70.41]] )从 ultralytics/utils/instance.py 源码可见支持三种格式xyxy左上/右下角、xywh中心点 x/y 宽高即 YOLO 格式、ltwh左上角 宽高即 COCO 格式__init__会断言格式合法、二维数组且列数为 4一维输入会被提升为(1, 4)convert(format)按当前格式动态选择xyxy2xywh、xywh2xyxy、ltwh2xywh等底层函数完成互转areas()先将框转为xyxy再计算(x2-x1)*(y2-y1)另有mul(scale)四维缩放、add(offset)四维偏移、concatenate合并多个 Bboxes等方法。更多属性与方法见 Bboxes 参考文档。 提示下文的许多函数以及更多功能都可以通过Bboxes类访问但如果你更习惯直接调用函数可以按后续小节独立导入。缩放边界框scale_boxes图像放大/缩小时可用scale_boxes让对应边界框坐标同步缩放import cv2 as cv import numpy as np from ultralytics.utils.ops import scale_boxes image cv.imread(ultralytics/assets/bus.jpg) *(h, w), c image.shape resized cv.resize(image, None, (), fx1.2, fy1.2) *(new_h, new_w), _ resized.shape xyxy_boxes np.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ) new_boxes scale_boxes( img1_shape(h, w), # 原图尺寸 boxesxyxy_boxes, # 原图上的框 img0_shape(new_h, new_w), # 缩放后图像的尺寸缩放目标 ratio_padNone, paddingFalse, xywhFalse, ) new_boxes array( [[ 27.454, 277.52, 965.98, 908.2], [ 58.262, 478.27, 294.42, 1083.3], [ 803.36, 470.63, 971.66, 1052.4], [ 265.82, 486.96, 413.98, 1029], [ 0, 660.64, 75.612, 1048.1], [ 0.0701, 305.35, 39.073, 389.84]] )实现要点ultralytics/utils/ops.py未提供ratio_pad时按gain min(img1_shape[0]/img0_shape[0], img1_shape[1]/img0_shape[1])计算缩放比例并推导 letterbox 式的 paddingpaddingTrue时默认先减去 padding 再乘gain还原到无 letterbox的坐标系paddingFalse时直接按比例缩放xywhTrue表示输入为xywh格式。边界框格式互转XYXY → XYWH将边界框从(x1, y1, x2, y2)转为(x, y, width, height)格式其中(x1, y1)为左上角、(x2, y2)为右下角import numpy as np from ultralytics.utils.ops import xyxy2xywh xyxy_boxes np.array( [[ 22.878, 231.27, 804.98, 756.83,], [ 48.552, 398.56, 245.35, 902.71,], [ 669.47, 392.19, 809.72, 877.04,], [ 221.52, 405.8, 344.98, 857.54,], [ 0, 550.53, 63.01, 873.44,], [ 0.0584, 254.46, 32.561, 324.87,]] ) xywh xyxy2xywh(xyxy_boxes) xywh array( [[ 413.93, 494.05, 782.1, 525.56], [ 146.95, 650.63, 196.8, 504.15], [ 739.6, 634.62, 140.25, 484.85], [ 283.25, 631.67, 123.46, 451.74], [ 31.505, 711.99, 63.01, 322.91], [ 16.31, 289.67, 32.503, 70.41]] )实现上对每一维分别计算x (x1x2)/2y (y1y2)/2w x2-x1h y2-y1。全部边界框转换函数ultralytics.utils.ops提供了完整的坐标格式转换家族from ultralytics.utils.ops import xywh2xyxy from ultralytics.utils.ops import xywhn2xyxy # 归一化 → 像素 from ultralytics.utils.ops import xyxy2xywhn # 像素 → 归一化 from ultralytics.utils.ops import xywh2ltwh # xywh → 左上角坐标, w, h from ultralytics.utils.ops import xyxy2ltwh # xyxy → 左上角坐标, w, h from ultralytics.utils.ops import ltwh2xywh from ultralytics.utils.ops import ltwh2xyxy各函数典型签名与语义均可同时接受 NumPy 数组与 PyTorch Tensor并断言最后一维为 4xywh2xyxy(x)中心点格式转角点格式dwx[2]/2、dhx[3]/2向四周展开xywhn2xyxy(x, w640, h640, padw0, padh0)归一化中心格式转像素角点格式可附加 pad 偏移xyxy2xywhn(x, w640, h640, clipFalse, eps0.0)像素角点转归一化中心格式clipTrue时先裁剪到图像边界xywh2ltwh(x)/xyxy2ltwh(x)转左上角 宽高COCO 风格前者只需平移-w/2, -h/2后者只需计算w x2-x1ltwh2xywh(x)/ltwh2xyxy(x)上述的逆变换。更多细节可阅读各函数 docstring 或 ultralytics.utils.ops 参考文档。绘图工具Plotting绘制标注Annotator 类Ultralytics 内置Annotator类可用于标注任意类型数据最常配合目标检测框、姿态关键点与旋转框 OBB 使用。水平边界框标注import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors names { # 也可直接使用 model.names见 working with results 0: person, 5: bus, 11: stop sign, } image cv.imread(ultralytics/assets/bus.jpg) ann Annotator( image, line_widthNone, # 默认自适应 font_sizeNone, # 默认自适应 fontArial.ttf, # 需与 ImageFont 兼容 pilFalse, # False 使用 OpenCV 绘制True 使用 PIL ) xyxy_boxes np.array( [[ 5, 22.878, 231.27, 804.98, 756.83,], # class-idx x1 y1 x2 y2 [ 0, 48.552, 398.56, 245.35, 902.71,], [ 0, 669.47, 392.19, 809.72, 877.04,], [ 0, 221.52, 405.8, 344.98, 857.54,], [ 0, 0, 550.53, 63.01, 873.44,], [11, 0.0584, 254.46, 32.561, 324.87,]] ) for nb, box in enumerate(xyxy_boxes): c_idx, *box box label f{str(nb).zfill(2)}:{names.get(int(c_idx))} ann.box_label(box, label, colorcolors(c_idx, bgrTrue)) image_with_bboxes ann.result()Annotator的初始化会依据是否传入 PIL 图像、标签是否含非 ASCII 字符自动选择 PIL 或 OpenCV 渲染路径ultralytics/utils/plotting.pyline_width未指定时按图像尺寸自适应max(round(sum(shape)/2 * 0.003), 2)。box_label支持rotatedTrue绘制多边形旋转框result()返回标注后的np.asarray图像此外还有show()与save()便捷方法。colors(c_idx, bgrTrue)从内置调色板取色内部为 TABLEAU_COLORS 风格的 10 色循环调色板。旋转边界框OBB标注import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors obb_names {10: small vehicle} obb_image cv.imread(datasets/dota8/images/train/P1142__1024__0___824.jpg) obb_boxes np.array( [[ 0, 635, 560, 919, 719, 1087, 420, 803, 261,], # class-idx x1 y1 x2 y2 x3 y2 x4 y4 [ 0, 331, 19, 493, 260, 776, 70, 613, -171,], [ 9, 869, 161, 886, 147, 851, 101, 833, 115,] ] ) ann Annotator( obb_image, line_widthNone, # 默认自适应 font_sizeNone, # 默认自适应 fontArial.ttf, # 需与 ImageFont 兼容 pilFalse, # False 使用 OpenCV 绘制 ) for obb in obb_boxes: c_idx, *obb obb obb np.array(obb).reshape(-1, 4, 2).squeeze() label f{names.get(int(c_idx))} ann.box_label( obb, label, colorcolors(c_idx, True), rotatedTrue, ) image_with_obb ann.result()OBB 的 8 个坐标先reshape(-1, 4, 2)成 4 个角点再以rotatedTrue交给box_label内部会走draw.polygon/cv2.polylines分支绘制多边形。更多细节见 Annotator 参考文档。杂项工具Miscellaneous代码性能分析ProfileProfile用于测量代码运行耗时既可作为with上下文管理器也可作为装饰器from ultralytics.utils.ops import Profile with Profile(devicedevice) as dt: pass # 待测操作 print(dt) Elapsed time is 9.5367431640625e-07 s实现位于 ultralytics/utils/ops.py继承contextlib.ContextDecorator__init__(self, t0.0, deviceNone)可传入初始时间与设备cuda bool(device and str(device).startswith(cuda))即当device以cuda开头时计时使用 CUDA 事件torch.cuda.Event否则使用time.perf_counter——这使得 GPU 推理耗时测量也能精确。Ultralytics 支持的图片/视频格式常量如需在代码中以编程方式获取 Ultralytics 支持的图片与视频格式可直接使用如下常量from ultralytics.data.utils import IMG_FORMATS from ultralytics.data.utils import VID_FORMATS print(IMG_FORMATS) (bmp, dng, jpeg, jpg, mpo, png, tif, tiff, webp, pfm)定义于 ultralytics/data/utils.pyIMG_FORMATS {bmp, dng, jpeg, jpg, mpo, png, tif, tiff, webp, pfm} VID_FORMATS {asf, avi, gif, m4v, mkv, mov, mp4, mpeg, mpg, ts, wmv, webm}它们同时被数据集校验verify_image/verify_image_label、autosplit、HUBDatasetStats等内部逻辑广泛使用。取整到可整除make_divisible计算最接近x、且能被y整除的整数from ultralytics.utils.ops import make_divisible make_divisible(7, 3) 9 make_divisible(7, 2) 8实现为math.ceil(x / divisor) * divisorultralytics/utils/ops.py即向上取整保证结果不小于x。该函数在网络结构设计如通道数对齐与推理尺寸对齐中经常被用到若传入torch.Tensor的divisor会先取int(divisor.max())。实践建议与组合用法数据流水线组合convert_coco完成格式统一 →autosplit划分数据集 →compress_one_image压缩训练图像可在训练前一站式完成数据准备半自动标注链路auto_annotate生成分割标注后用segments2boxes反推xywh检测框实现检测 分割双任务数据集的同时扩增yolo_bbox2segment则面向相反方向已有检测框补充分割可视化与调试Annotator配合Bboxes/scale_boxes/各转换函数可以快速绘制缩放前后的框验证增强流程的正确性格式约定提醒xywh的中心点表示是 YOLO 训练标签的标准格式归一化后即xywhn而 COCO 使用ltwh跨框架迁移数据时务必使用ultralytics.utils.ops中的转换函数避免坐标语义错位。以上工具的完整签名与参考实现均可通过 docs/en/reference 下的对应参考文档进一步查阅也可直接阅读仓库源码 ultralytics/data/utils.py、ultralytics/utils/ops.py、ultralytics/utils/instance.py、ultralytics/utils/plotting.py 与 ultralytics/data/annotator.py。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考