尧图网站建设 
Ultralytics Simple Utilities 实战指南自动标注、数据集转换与可视化工具全解析【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读Ultralytics 不仅提供 YOLO 系列检测、分割、姿态估计模型还在ultralytics包中内置了一套高度工程化的工具函数与类覆盖数据自动标注、数据集格式转换、边界框运算、图像可视化绘制与代码性能分析等高频场景。本篇指南以仓库文档 docs/en/usage/simple-utilities.md 为骨架结合其底层源码逐项拆解这些 Simple Utilities 的调用方式、参数语义与内部实现读完后你将能够直接在真实项目中完成数据准备—格式转换—训练前校验—结果可视化的全链路编程。工具总览Ultralytics 常用工具的三个层次按功能定位这些工具大致可分为三类文章中会依次展开数据处理层位于 ultralytics/data/ 模块自动标注、COCO/掩膜/多边形格式互转、图像压缩、数据集自动划分几何运算层位于 ultralytics/utils/ops.py、ultralytics/utils/instance.py边界框格式转换、缩放、面积计算、Bboxes封装类可视化绘制层位于 ultralytics/utils/plotting.py、ultralytics/solutions/solutions.pyAnnotator基础标注、扫线标注、自适应矩形/圆形标签。每个工具都是可直接from ... import ...的独立函数或类无需初始化任何框架级组件非常适合写进数据处理脚本或训练流水线。一、数据处理自动标注与格式转换1.1 使用 YOLO SAM 自动标注新数据集auto_annotate人工标注目标检测/分割数据集是耗时且昂贵的过程。官方推荐的工作流是先用一个在合理规模数据上训练好的 YOLO 检测模型框出物体再让 SAMSegment Anything Model以这些框为提示box prompt生成高质量分割掩膜从而自动产出 YOLO 分割格式的标签。from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolo26n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )该函数无返回值标签文件会直接落盘。结合源码 ultralytics/data/annotator.py 可以看到它的完整签名与默认值实际生产中使用时可显式覆盖def auto_annotate( data: str | Path, det_model: str yolo26x.pt, # YOLO 检测模型权重路径或名称 sam_model: str sam_b.pt, # SAM 分割模型 device: str , # 为空时自动选择可填 cpu/cuda/0 conf: float 0.25, # 检测置信度阈值 iou: float 0.45, # NMS 去重的 IoU 阈值 imgsz: int 640, # 检测阶段输入图缩放尺寸 max_det: int 300, # 每张图最大检测数 classes: list[int] | None None,# 只保留指定类别的检测结果 output_dir: str | Path | None None, ) - None:源码实现逻辑annotator.py值得关注output_dir缺省时标签自动保存到输入目录同级的数据目录名_auto_annotate_labels文件夹无需手动建目录mkdir(exist_okTrue, parentsTrue)检测阶段以streamTrue流式推理内存友好SAM 阶段使用sam_model(result.orig_img, bboxesboxes, ...)即把检测框作为 SAM 的 box 提示只分割框内目标比整图分割更快更准输出的每个.txt文件与图片同名每行格式为class_id x1 y1 x2 y2 ...归一化多边形坐标源码特别判断len(s) 3点数不足 3 个的多边形如退化轮廓不会写入因为加载器不接受这种无效行。自动标注得到的是一份分割segmentation数据集。如果你同时需要目标检测的边界框标签可以用 1.7 节的segments2boxes由分割结果反推水平框。运行细节见参考页 annotator.auto_annotate。1.2 训练前可视化校验标注visualize_image_annotations标注质量直接决定检测效果。visualize_image_annotations可在训练前把 YOLO 格式标注叠加回原图快速定位错标、漏标。它读取图片与同名.txt绘制边界框、写入类别名并根据背景亮度自适应文字颜色保证可读性。from ultralytics.data.utils import visualize_image_annotations label_map { # 定义数据集中所有标注类别的映射 0: person, 1: car, } # 可视化 visualize_image_annotations( path/to/image.jpg, # 输入图片路径 path/to/annotations.txt, # 该图片对应的标注文件路径 label_map, )从实现看ultralytics/data/utils.py该函数内部解析class x_center y_center width height五列归一化 YOLO 标签行乘以图像宽高还原为像素坐标每个类别的框使用 plotting 模块的colors()分配稳定颜色文字颜色则按经典亮度公式0.2126R 0.7152G 0.0722B动态判定亮度低于 0.5 用白字、否则用黑字。最终通过 Matplotlib 的plt.Rectangleax.text渲染并plt.show()。1.3 分割掩膜图转 YOLO 分割格式convert_segment_masks_to_yolo_seg当你从第三方工具如某些标注平台拿到的是逐像素二值掩膜图mask image目录而非多边形坐标时可用该函数一键转成 YOLO 分割标签。源码 ultralytics/data/converter.py 的签名是def convert_segment_masks_to_yolo_seg(masks_dir: str, output_dir: str, classes: int): ...masks_dir存放png/jpg掩膜图的目录output_dir转换后标签的输出目录classes数据集总类别数——COCO 数据集为 80。from ultralytics.data.converter import convert_segment_masks_to_yolo_seg convert_segment_masks_to_yolo_seg(masks_dirpath/to/masks_dir, output_dirpath/to/output_dir, classes80)注意文档示例中classes指的是全数据集类别总数而非最大类别索引类别推断依赖该数值配合颜色编码判断。转换结果会按图像名生成*.txt保存到输出目录。1.4 COCO JSON 标注转 YOLO 格式convert_cocoCOCO 的 JSON 标注instances_*.json并不能直接被 YOLO 训练使用需要转换成 YOLO 的class x_center y_center w h文本格式。目标检测纯框数据集请将use_segments、use_keypoints均置为Falsefrom ultralytics.data.converter import convert_coco convert_coco( coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )底层实现 ultralytics/data/converter.py 有几个关键行为参数面完整签名为convert_coco(labels_dir../coco/annotations/, save_dircoco_converted/, use_segmentsFalse, use_keypointsFalse, cls91to80True, lvisFalse)。输出目录若已存在会自动递增命名increment_path并在save_dir下建立labels/与images/目录骨架逐文件扫描labels_dir下所有.json跳过iscrowd标注COCO 原始框是左上角 宽高代码先换算为中心点再做w/h归一化cls91to80True时通过coco91_to_coco80_class()把 COCO 91 类编号映射到 YOLO 习惯的 80 类连续编号经典的数据集格式说明见 COCO 数据集文档use_segmentsTrue时额外输出多边形分割行若某标注的多边形缺失、为空或是 RLE 格式代码会退化为用包围框四角构造四边形并打印警告日志此外还支持lvisTrue走 LVIS 数据集转换分支。转换细节与所有分支行为见参考页 convert_coco。1.5 获取边界框的宽、高与面积get_bbox_dimension模型推理得到xyxy坐标后常常需要统计每个目标的宽、高、面积例如做目标尺寸分布分析。Annotator类提供了静态方法get_bbox_dimensionultralytics/utils/plotting.pyimport cv2 from ultralytics import YOLO from ultralytics.utils.plotting import Annotator model YOLO(yolo26n.pt) # 加载预训练或微调后的模型 # 处理图像 source cv2.imread(path/to/image.jpg) results model(source) # 提取结果 annotator Annotator(source, examplemodel.names) for box in results[0].boxes.xyxy.cpu(): width, height, area annotator.get_bbox_dimension(box) print(fBounding Box Width {width.item()}, Height {height.item()}, Area {area.item()})该方法接收(x_min, y_min, x_max, y_max)格式的框返回(width, height, area)三元组可直接配合results对象做批量统计。预测结果的boxes/masks等字段说明见 预测模式文档。1.6 已有边界框数据转分割标签yolo_bbox2segment如果手里只有检测框x y w h标注希望升级成分割标注可以用yolo_bbox2segment它以每个检测框为提示喂给 SAM 生成多边形从而免去二次人工标注。使用前请把数据整理成如下目录结构images与labels平级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把归一化xywh框还原为像素并转成xyxy后作为 bbox 提示生成masks.xyn小于 3 个点的退化多边形同样会被丢弃。函数细节与目录约定见参考页 yolo_bbox2segment。1.7 分割多边形转水平边界框segments2boxes反过来若数据集已是 分割格式每行class_id 归一化多边形点列可以轻松转成水平框x y w h。把每条多边形reshape(-1, 2)后传给segments2boxesultralytics/utils/ops.pyimport numpy as np from ultralytics.utils.ops import segments2boxes segments np.array( [ [805, 392, 797, 400, 812, 402, 808, 714, 808, 392], [115, 398, 113, 400, 150, 410, 150, 400, 149, 298], [267, 412, 265, 413, 300, 420, 300, 413, 299, 412], ], dtypenp.float32, ) segments2boxes([s.reshape(-1, 2) for s in segments]) # array([[804.5, 553. , 15. , 322. ], # [131.5, 354. , 37. , 112. ], # [282.5, 416. , 35. , 8. ]], # dtypefloat32) # xywh 边界框返回的每一行是[x_center, y_center, width, height]。这正是 1.1 节自动标注后补生成检测框标签所推荐组合使用的函数。二、通用实用工具Utilities2.1 图片压缩compress_one_imagecompress_one_image用于在保持宽高比与画质的前提下压缩单张图片若原图最大边已经不超过上限则不做缩放。默认实现位于 ultralytics/data/utils.pyfrom pathlib import Path from ultralytics.data.utils import compress_one_image for f in Path(path/to/dataset).rglob(*.jpg): compress_one_image(f)完整签名是compress_one_image(f, f_newNone, max_dim1920, quality50)f_new缺省时原地覆盖原文件max_dim1920最长边上限像素quality50JPEG 压缩质量百分比。源码采用双后端策略优先用 PIL 处理并会关闭MAX_IMAGE_PIXELS限制以避免超 1.7 亿像素大图的DecompressionBombErrorRGBA/LA 模式先转 RGB 再存 JPEGsave(..., optimizeTrue)做体积优化。若 PIL 抛异常则自动回退 OpenCV用cv2.INTER_AREA高质量插值缩放。很适合在训练前批量瘦身高分辨率数据集加速加载。2.2 数据集自动划分 train/val/testautosplitautosplit会自动把图片目录划分成train/val/test三份并在图片目录的父级生成持久化的autosplit_train.txt、autosplit_val.txt、autosplit_test.txt每个文件写入对应图片的相对路径from ultralytics.data.split import autosplit autosplit( pathpath/to/images, weights(0.9, 0.1, 0.0), # (train, validation, test) 划分比例 annotated_onlyFalse, # 为 True 时只切分存在同名标注 txt 的图片 )注意它与训练时fraction参数 的区别autosplit生成的是持久文件后续可直接把autosplit_train.txt的路径当作数据集path使用而fraction是每次训练临时抽取的可复现子集相关归一化逻辑见 ultralytics/data/utils.py 的get_split_fraction。源码细节ultralytics/data/split.pyweights需三元素求和为 1划分使用random.seed(0)保证结果可复现仅当annotated_onlyTrue时通过img2label_paths检查图片是否存在同目录标签文件只有带标签的图片才参与切分旧的分割文件在重新运行前会被自动清除。2.3 多边形转二值掩膜polygon2mask将单个多边形列表形式按指定图像尺寸渲染为二值掩膜mask。多边形需为交替 x、y 坐标的扁平一维数组即N个点展开成2N个数⚠️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, # (高, 宽) 元组 [polygon], # 以列表形式传入 color255, # 8-bit 掩膜的填充值 downsample_ratio1, )底层实现 ultralytics/data/utils.py 先np.zeros(imgsz, dtypenp.uint8)建底图再用cv2.fillPoly填充这也解释了为何要求偶数点随后按downsample_ratio用cv2.resize下采样。注释还说明先填充再缩放是为了与mask-ratio1的损失计算方式保持一致。同一文件中的polygons2masks与polygons2masks_overlap是面向多个多边形/重叠实例的批量扩展版本可在需要多类别掩膜时参考。三、边界框Bounding Boxes工具箱3.1 Bboxes统一管理边界框的类Bboxes类封装了水平边界框最常见的操作——格式互转、缩放、面积、加偏移等避免手写一堆numpy切片。其实现位于 ultralytics/utils/instance.py支持xyxy、xywh、ltwh三种格式要求输入为 NumPy 数组import numpy as np 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) print(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]] # )areas()instance.pyxyxy格式用(x2-x1)*(y2-y1)xywh/ltwh用w*hconvert(format)instance.py原地将内部格式在xyxy、xywh、ltwh间切换非法格式会直接断言报错。完整属性与方法清单见Bboxes参考页。 以下若干函数的功能都能通过Bboxes类方法完成如果你更习惯面向函数式编程可直接使用接下来的独立导入方式。3.2 图像缩放时同步缩放框scale_boxes对图像做缩放/拉伸预处理后框坐标必须随之更新否则标注会错位。ultralytics.utils.ops.scale_boxes正是干这件事的ops.pyimport 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, # 传入 None 时由两图尺寸自动计算缩放比与 padding paddingFalse, xywhFalse, # True 时输入输出为 xywh否则为 xyxy ) print(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]] # )实现要点ops.py当ratio_padNone时按gain min(旧h/新h, 旧w/新w)计算等比缩放系数并推导 YOLO 式 letterbox 的居中 paddingpaddingTrue时先减去 padding 再除 gain最后经clip_boxes把越界坐标裁剪回图内。支持传入 PyTorch Tensor 或 NumPy 数组并保持输入输出格式一致。3.3 坐标格式转换XYXY → XYWHxyxy2xywh把(x1, y1, x2, y2)左上角 右下角转为(x, y, width, height)中心点 宽高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) print(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]] # )其中(x1, y1)为左上角、(x2, y2)为右下角。可以看到输出与 3.1 节boxes.convert(xywh)的结果完全一致——两类 API 殊途同归可按使用习惯任选。3.4 其余全部格式转换函数Ultralytics 在 ultralytics/utils/ops.py 中提供了一整套对称的转换函数覆盖xyxy、xywh、ltwh左上角 宽高以及归一化与非归一化之间的互换from ultralytics.utils.ops import ( ltwh2xywh, ltwh2xyxy, xywh2ltwh, # xywh → 左上角坐标 w, h xywh2xyxy, xywhn2xyxy, # 归一化 → 像素坐标 xyxy2ltwh, # xyxy → 左上角坐标 w, h xyxy2xywhn, # 像素坐标 → 归一化 ) for func in (ltwh2xywh, ltwh2xyxy, xywh2ltwh, xywh2xyxy, xywhn2xyxy, xyxy2ltwh, xyxy2xywhn): print(help(func)) # 打印各函数 docstring用help()即可查看每个函数精确的输入输出约定更完整的文档见 ultralytics.utils.ops 参考页。四、可视化与标注绘制PlottingUltralytics 提供Annotator系列类适合在检测框boxes、姿态关键点keypoints、旋转框OBB等多种预测结果之上叠加可视化。4.1 基础 Annotator水平框与旋转框标注基础类 Annotator 的初始化参数包括line_width缺省自动按图尺寸定宽、font_size缺省自动、font需为 ImageFont 兼容字体如Arial.ttf与pil选择 PIL 或 OpenCV 渲染后端。水平边界框示例import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors names { 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, # True 走 PILFalse 走 OpenCV ) 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()旋转框 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 y3 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, pilFalse, ) for obb in obb_boxes: c_idx, *obb obb obb np.array(obb).reshape(-1, 4, 2).squeeze() label f{obb_names.get(int(c_idx))} ann.box_label( obb, label, colorcolors(c_idx, True), ) image_with_obb ann.result()核心绘制入口是box_labelplotting.py它同时完成画框与写标签标签带背景色块colors(cls, bgrTrue)按类别索引返回稳定颜色。实际处理检测结果时类别名建议直接取model.names见 处理预测结果colors()与Annotator的更多属性请参考Annotator参考页。4.2 扫线Sweep标注与跨线计数sweep_annotator是 SolutionAnnotator继承自Annotator的解决方案专用标注器提供的能力适合在视频中拖拽一条竖向扫线并实时统计越线目标数。它把检测框、分割掩膜、跟踪 ID、类别名与计数标签整合到同一画面上import sys import cv2 import numpy as np from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors # 用户自定义视频路径与模型文件 cap cv2.VideoCapture(path/to/video.mp4) model YOLO(modelyolo26s-seg.pt) # 模型文件如 yolo26s.pt 或 yolo26m-seg.pt if not cap.isOpened(): print(Error: Could not open video.) sys.exit() # 初始化视频写入器 w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) video_writer cv2.VideoWriter(ultralytics.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) masks None # 存储掩膜数据的变量 f 0 # 帧计数用于启用鼠标事件 line_x w # 扫线的横坐标 dragging False # 拖拽状态布尔标记 classes model.names # 用于绘制标签的模型类别名 window_name Ultralytics Sweep Annotator def drag_line(event, x, _, flags, param): 鼠标回调函数在视频帧上拖拽一条竖直扫线。 global line_x, dragging if event cv2.EVENT_LBUTTONDOWN or (flags cv2.EVENT_FLAG_LBUTTON): line_x max(0, min(x, w)) dragging True while cap.isOpened(): # 逐帧读取 ret, im0 cap.read() if not ret: break f f 1 # 帧计数 1 count 0 # 每帧重置计数 results model.track(im0, persistTrue)[0] if f 1: cv2.namedWindow(window_name) cv2.setMouseCallback(window_name, drag_line) annotator SolutionAnnotator(im0) if results.boxes.is_track: if results.masks is not None: masks [np.array(m, dtypenp.int32) for m in results.masks.xy] boxes results.boxes.xyxy.tolist() track_ids results.boxes.id.int().cpu().tolist() clss results.boxes.cls.cpu().tolist() for mask, box, cls, t_id in zip(masks or [None] * len(boxes), boxes, clss, track_ids): color colors(t_id, True) # 为每个跟踪目标分配不同颜色 label f{classes[cls]}:{t_id} if mask is not None and mask.size 0: if box[0] line_x: count 1 cv2.polylines(im0, [mask], True, color, 2) x, y mask.min(axis0) (w_m, _), _ cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1) cv2.rectangle(im0, (x, y - 20), (x w_m, y), color, -1) cv2.putText(im0, label, (x, y - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1) else: if box[0] line_x: count 1 annotator.box_label(boxbox, colorcolor, labellabel) # 绘制可拖拽的扫线 annotator.sweep_annotator(line_xline_x, line_yh, labelfCOUNT:{count}) cv2.imshow(window_name, im0) video_writer.write(im0) if cv2.waitKey(1) 0xFF ord(q): break # 释放资源 cap.release() video_writer.release() cv2.destroyAllWindows()关键点解读model.track(im0, persistTrue)启用跨帧跟踪跟踪模式文档见 track.md配合results.boxes.id拿到稳定目标 ID有分割掩膜时用cv2.polylines描轮廓否则退化为annotator.box_label画框判定条件box[0] line_x表示目标框左边缘越过扫线则计数 1SolutionAnnotator.sweep_annotatorsolutions.py绘制扫线与COUNT:实时计数文本。该方法完整签名与参数见参考页 sweep_annotator。4.3 自适应矩形 / 圆形标签标注adaptive_label⚠️ 版本说明自Ultralytics v8.3.167起circle_label与text_label被统一为adaptive_label函数通过shape参数指定标注类型矩形annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shaperect)圆形annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shapecircle)该 API 会根据目标尺寸自动自适应字号与画布避免小目标上文字溢出。以下给出两种形状的完整视频标注循环示例。圆形标注Circle Annotationimport cv2 from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors model YOLO(yolo26s.pt) names model.names cap cv2.VideoCapture(path/to/video.mp4) w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) writer cv2.VideoWriter(Ultralytics circle annotation.avi, cv2.VideoWriter_fourcc(*MJPG), fps, (w, h)) while True: ret, im0 cap.read() if not ret: break annotator SolutionAnnotator(im0) results model.predict(im0)[0] boxes results.boxes.xyxy.cpu() clss results.boxes.cls.cpu().tolist() for box, cls in zip(boxes, clss): annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shapecircle) writer.write(im0) cv2.imshow(Ultralytics circle annotation, im0) if cv2.waitKey(1) 0xFF ord(q): break writer.release() cap.release() cv2.destroyAllWindows()矩形文本标注Text Annotationimport cv2 from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors model YOLO(yolo26s.pt) names model.names cap cv2.VideoCapture(path/to/video.mp4) w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) writer cv2.VideoWriter(Ultralytics text annotation.avi, cv2.VideoWriter_fourcc(*MJPG), fps, (w, h)) while True: ret, im0 cap.read() if not ret: break annotator SolutionAnnotator(im0) results model.predict(im0)[0] boxes results.boxes.xyxy.cpu() clss results.boxes.cls.cpu().tolist() for box, cls in zip(boxes, clss): annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shaperect) writer.write(im0) cv2.imshow(Ultralytics text annotation, im0) if cv2.waitKey(1) 0xFF ord(q): break writer.release() cap.release() cv2.destroyAllWindows()两段示例的差异仅在shape参数circle在目标中心绘制圆形自适应标签rect在框左上绘制带背景的文本条。adaptive_label的具体实现solutions.py与字号自适应策略见参考页 SolutionAnnotator.adaptive_label。五、杂项工具5.1 代码段耗时分析Profile需要精确测量一段代码的运行耗时可把 Profile 当作上下文管理器或装饰器使用。它在计时前后会做 GPU 同步如 CUDA保证测量包含真实执行时间from ultralytics.utils.ops import Profile with Profile(devicecuda:0) as dt: pass # 待测操作 print(dt) # Elapsed time is 9.5367431640625e-07 sProfile继承自contextlib.ContextDecorator因此同样支持Profile()修饰函数。源码实现ops.py会依据device参数在进入/退出时同步对应的加速设备。5.2 Ultralytics 支持的图片 / 视频格式常量当需要在程序里判断某文件后缀是否被 Ultralytics 支持时不必硬编码格式集合直接导入 ultralytics/data/utils.py 中的IMG_FORMATS与VID_FORMATS预测模式支持格式清单见 image/video formatsfrom ultralytics.data.utils import IMG_FORMATS, VID_FORMATS print(IMG_FORMATS) # {avif, bmp, dng, heic, heif, jp2, jpeg, jpg, mpo, png, tif, tiff, webp} print(VID_FORMATS) # {asf, avi, gif, m4v, mkv, mov, mp4, mpeg, mpg, ts, wmv, webm}可见 Ultralytics 默认覆盖 13 种图片格式与 12 种视频格式含heic/heif/avif等现代格式。5.3 make_divisible返回大于等于x且能被y整除的最小整数。模型结构设计中常用来把通道数对齐到某个网络的整除约束如 8/16/32 对齐from ultralytics.utils.ops import make_divisible make_divisible(7, 3) # 9 make_divisible(7, 2) # 8实现非常简单ops.pymath.ceil(x / divisor) * divisor当divisor是 PyTorch Tensor 时先取最大值再转为 int方便直接传模型权重相关的除数。六、常见问题FAQ6.1 Ultralytics 包内包含哪些能提升 ML 工作流的工具主要包括用于数据集自动标注的 auto_annotate、把 COCO 转 YOLO 的 convert_coco、图像压缩、数据集自动划分以及边界框格式转换与Annotator可视化等。这些工具能显著减少人工操作、保证数据一致性并提升数据准备效率具体分布在 ultralytics/data/ 与 ultralytics/utils/ 模块内。6.2 如何用 Ultralytics 自动给数据集打标签使用 1.1 节的auto_annotate把预训练 YOLO 检测模型与 SAM 系列模型如mobile_sam.pt组合使用即可为图片目录批量生成分割格式标签from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolo26n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )其运行机制详见 auto_annotate 参考页。若需点击式掩膜的人工半自动方案可参考仓库中 SAM-2、SAM-3 与 SAM 模型文档使用检测/分割/OBB 任务的预训练或微调模型输出作为标注来源。6.3 如何把 COCO 标注转换为 YOLO 格式用convert_coco纯检测数据把use_segments、use_keypoints均设为Falsefrom ultralytics.data.converter import convert_coco convert_coco( coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )可选参数含 LVIS 分支详见 convert_coco 参考页。转换为 YOLO 格式前的准备工作可参考 COCO-to-YOLO 转换指南。6.4 如何分析数据集的组成与分布Ultralytics 生态提供了自动化的数据集分析能力如 Platform 的Charts标签页可查看划分占比、各类别数量直方图、图像尺寸分布与标注位置的 2D 热力图帮助训练前发现类别不均衡与离群样本。在本地也可用本篇 1.2 节的visualize_image_annotations逐图目检并用 3.1 节Bboxes.areas()、1.5 节get_bbox_dimension自行统计框宽高与面积分布。6.5 如何把边界框转换为分割标签将x y w h检测标签升级为分割标签使用yolo_bbox2segment前提是按 1.6 节的目录结构组织好images/与labels/from ultralytics.data.converter import yolo_bbox2segment yolo_bbox2segment( im_dirpath/to/images, save_dirNone, # 缺省保存在 images 目录同级 labels-segment sam_modelsam_b.pt, )实现细节与目录约定参见 yolo_bbox2segment 参考页。反向操作分割多边形 →xywh框则用 1.7 节的segments2boxes。总结与延伸阅读Simple Utilities 的价值在于把数据管线中最琐碎、最易出错的环节标注生成、格式转换、坐标运算、绘制渲染收敛成签名清晰、行为可预期的函数与类且大多直接依赖同一仓库内的训练/推理基础设施行为与训练链路完全一致。建议在编写数据处理脚本前先在 docs/en/reference/data/annotator.md、docs/en/reference/data/converter.md、docs/en/reference/data/split.md、docs/en/reference/utils/ops.md、docs/en/reference/utils/instance.md、docs/en/reference/utils/plotting.md 与 docs/en/reference/solutions/solutions.md 中核对目标函数的最新签名。想继续深入可按需阅读模型侧YOLO26 模型文档、SAM 模型文档、SAM-2、SAM-3数据侧COCO 数据集、分割数据集格式使用侧训练参数与 fraction、预测结果处理与支持格式。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics Simple Utilities 实战指南：自动标注、数据集转换与可视化工具全解析
Ultralytics Simple Utilities 实战指南自动标注、数据集转换与可视化工具全解析【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics导读Ultralytics 不仅提供 YOLO 系列检测、分割、姿态估计模型还在ultralytics包中内置了一套高度工程化的工具函数与类覆盖数据自动标注、数据集格式转换、边界框运算、图像可视化绘制与代码性能分析等高频场景。本篇指南以仓库文档 docs/en/usage/simple-utilities.md 为骨架结合其底层源码逐项拆解这些 Simple Utilities 的调用方式、参数语义与内部实现读完后你将能够直接在真实项目中完成数据准备—格式转换—训练前校验—结果可视化的全链路编程。工具总览Ultralytics 常用工具的三个层次按功能定位这些工具大致可分为三类文章中会依次展开数据处理层位于 ultralytics/data/ 模块自动标注、COCO/掩膜/多边形格式互转、图像压缩、数据集自动划分几何运算层位于 ultralytics/utils/ops.py、ultralytics/utils/instance.py边界框格式转换、缩放、面积计算、Bboxes封装类可视化绘制层位于 ultralytics/utils/plotting.py、ultralytics/solutions/solutions.pyAnnotator基础标注、扫线标注、自适应矩形/圆形标签。每个工具都是可直接from ... import ...的独立函数或类无需初始化任何框架级组件非常适合写进数据处理脚本或训练流水线。一、数据处理自动标注与格式转换1.1 使用 YOLO SAM 自动标注新数据集auto_annotate人工标注目标检测/分割数据集是耗时且昂贵的过程。官方推荐的工作流是先用一个在合理规模数据上训练好的 YOLO 检测模型框出物体再让 SAMSegment Anything Model以这些框为提示box prompt生成高质量分割掩膜从而自动产出 YOLO 分割格式的标签。from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolo26n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )该函数无返回值标签文件会直接落盘。结合源码 ultralytics/data/annotator.py 可以看到它的完整签名与默认值实际生产中使用时可显式覆盖def auto_annotate( data: str | Path, det_model: str yolo26x.pt, # YOLO 检测模型权重路径或名称 sam_model: str sam_b.pt, # SAM 分割模型 device: str , # 为空时自动选择可填 cpu/cuda/0 conf: float 0.25, # 检测置信度阈值 iou: float 0.45, # NMS 去重的 IoU 阈值 imgsz: int 640, # 检测阶段输入图缩放尺寸 max_det: int 300, # 每张图最大检测数 classes: list[int] | None None,# 只保留指定类别的检测结果 output_dir: str | Path | None None, ) - None:源码实现逻辑annotator.py值得关注output_dir缺省时标签自动保存到输入目录同级的数据目录名_auto_annotate_labels文件夹无需手动建目录mkdir(exist_okTrue, parentsTrue)检测阶段以streamTrue流式推理内存友好SAM 阶段使用sam_model(result.orig_img, bboxesboxes, ...)即把检测框作为 SAM 的 box 提示只分割框内目标比整图分割更快更准输出的每个.txt文件与图片同名每行格式为class_id x1 y1 x2 y2 ...归一化多边形坐标源码特别判断len(s) 3点数不足 3 个的多边形如退化轮廓不会写入因为加载器不接受这种无效行。自动标注得到的是一份分割segmentation数据集。如果你同时需要目标检测的边界框标签可以用 1.7 节的segments2boxes由分割结果反推水平框。运行细节见参考页 annotator.auto_annotate。1.2 训练前可视化校验标注visualize_image_annotations标注质量直接决定检测效果。visualize_image_annotations可在训练前把 YOLO 格式标注叠加回原图快速定位错标、漏标。它读取图片与同名.txt绘制边界框、写入类别名并根据背景亮度自适应文字颜色保证可读性。from ultralytics.data.utils import visualize_image_annotations label_map { # 定义数据集中所有标注类别的映射 0: person, 1: car, } # 可视化 visualize_image_annotations( path/to/image.jpg, # 输入图片路径 path/to/annotations.txt, # 该图片对应的标注文件路径 label_map, )从实现看ultralytics/data/utils.py该函数内部解析class x_center y_center width height五列归一化 YOLO 标签行乘以图像宽高还原为像素坐标每个类别的框使用 plotting 模块的colors()分配稳定颜色文字颜色则按经典亮度公式0.2126R 0.7152G 0.0722B动态判定亮度低于 0.5 用白字、否则用黑字。最终通过 Matplotlib 的plt.Rectangleax.text渲染并plt.show()。1.3 分割掩膜图转 YOLO 分割格式convert_segment_masks_to_yolo_seg当你从第三方工具如某些标注平台拿到的是逐像素二值掩膜图mask image目录而非多边形坐标时可用该函数一键转成 YOLO 分割标签。源码 ultralytics/data/converter.py 的签名是def convert_segment_masks_to_yolo_seg(masks_dir: str, output_dir: str, classes: int): ...masks_dir存放png/jpg掩膜图的目录output_dir转换后标签的输出目录classes数据集总类别数——COCO 数据集为 80。from ultralytics.data.converter import convert_segment_masks_to_yolo_seg convert_segment_masks_to_yolo_seg(masks_dirpath/to/masks_dir, output_dirpath/to/output_dir, classes80)注意文档示例中classes指的是全数据集类别总数而非最大类别索引类别推断依赖该数值配合颜色编码判断。转换结果会按图像名生成*.txt保存到输出目录。1.4 COCO JSON 标注转 YOLO 格式convert_cocoCOCO 的 JSON 标注instances_*.json并不能直接被 YOLO 训练使用需要转换成 YOLO 的class x_center y_center w h文本格式。目标检测纯框数据集请将use_segments、use_keypoints均置为Falsefrom ultralytics.data.converter import convert_coco convert_coco( coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )底层实现 ultralytics/data/converter.py 有几个关键行为参数面完整签名为convert_coco(labels_dir../coco/annotations/, save_dircoco_converted/, use_segmentsFalse, use_keypointsFalse, cls91to80True, lvisFalse)。输出目录若已存在会自动递增命名increment_path并在save_dir下建立labels/与images/目录骨架逐文件扫描labels_dir下所有.json跳过iscrowd标注COCO 原始框是左上角 宽高代码先换算为中心点再做w/h归一化cls91to80True时通过coco91_to_coco80_class()把 COCO 91 类编号映射到 YOLO 习惯的 80 类连续编号经典的数据集格式说明见 COCO 数据集文档use_segmentsTrue时额外输出多边形分割行若某标注的多边形缺失、为空或是 RLE 格式代码会退化为用包围框四角构造四边形并打印警告日志此外还支持lvisTrue走 LVIS 数据集转换分支。转换细节与所有分支行为见参考页 convert_coco。1.5 获取边界框的宽、高与面积get_bbox_dimension模型推理得到xyxy坐标后常常需要统计每个目标的宽、高、面积例如做目标尺寸分布分析。Annotator类提供了静态方法get_bbox_dimensionultralytics/utils/plotting.pyimport cv2 from ultralytics import YOLO from ultralytics.utils.plotting import Annotator model YOLO(yolo26n.pt) # 加载预训练或微调后的模型 # 处理图像 source cv2.imread(path/to/image.jpg) results model(source) # 提取结果 annotator Annotator(source, examplemodel.names) for box in results[0].boxes.xyxy.cpu(): width, height, area annotator.get_bbox_dimension(box) print(fBounding Box Width {width.item()}, Height {height.item()}, Area {area.item()})该方法接收(x_min, y_min, x_max, y_max)格式的框返回(width, height, area)三元组可直接配合results对象做批量统计。预测结果的boxes/masks等字段说明见 预测模式文档。1.6 已有边界框数据转分割标签yolo_bbox2segment如果手里只有检测框x y w h标注希望升级成分割标注可以用yolo_bbox2segment它以每个检测框为提示喂给 SAM 生成多边形从而免去二次人工标注。使用前请把数据整理成如下目录结构images与labels平级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把归一化xywh框还原为像素并转成xyxy后作为 bbox 提示生成masks.xyn小于 3 个点的退化多边形同样会被丢弃。函数细节与目录约定见参考页 yolo_bbox2segment。1.7 分割多边形转水平边界框segments2boxes反过来若数据集已是 分割格式每行class_id 归一化多边形点列可以轻松转成水平框x y w h。把每条多边形reshape(-1, 2)后传给segments2boxesultralytics/utils/ops.pyimport numpy as np from ultralytics.utils.ops import segments2boxes segments np.array( [ [805, 392, 797, 400, 812, 402, 808, 714, 808, 392], [115, 398, 113, 400, 150, 410, 150, 400, 149, 298], [267, 412, 265, 413, 300, 420, 300, 413, 299, 412], ], dtypenp.float32, ) segments2boxes([s.reshape(-1, 2) for s in segments]) # array([[804.5, 553. , 15. , 322. ], # [131.5, 354. , 37. , 112. ], # [282.5, 416. , 35. , 8. ]], # dtypefloat32) # xywh 边界框返回的每一行是[x_center, y_center, width, height]。这正是 1.1 节自动标注后补生成检测框标签所推荐组合使用的函数。二、通用实用工具Utilities2.1 图片压缩compress_one_imagecompress_one_image用于在保持宽高比与画质的前提下压缩单张图片若原图最大边已经不超过上限则不做缩放。默认实现位于 ultralytics/data/utils.pyfrom pathlib import Path from ultralytics.data.utils import compress_one_image for f in Path(path/to/dataset).rglob(*.jpg): compress_one_image(f)完整签名是compress_one_image(f, f_newNone, max_dim1920, quality50)f_new缺省时原地覆盖原文件max_dim1920最长边上限像素quality50JPEG 压缩质量百分比。源码采用双后端策略优先用 PIL 处理并会关闭MAX_IMAGE_PIXELS限制以避免超 1.7 亿像素大图的DecompressionBombErrorRGBA/LA 模式先转 RGB 再存 JPEGsave(..., optimizeTrue)做体积优化。若 PIL 抛异常则自动回退 OpenCV用cv2.INTER_AREA高质量插值缩放。很适合在训练前批量瘦身高分辨率数据集加速加载。2.2 数据集自动划分 train/val/testautosplitautosplit会自动把图片目录划分成train/val/test三份并在图片目录的父级生成持久化的autosplit_train.txt、autosplit_val.txt、autosplit_test.txt每个文件写入对应图片的相对路径from ultralytics.data.split import autosplit autosplit( pathpath/to/images, weights(0.9, 0.1, 0.0), # (train, validation, test) 划分比例 annotated_onlyFalse, # 为 True 时只切分存在同名标注 txt 的图片 )注意它与训练时fraction参数 的区别autosplit生成的是持久文件后续可直接把autosplit_train.txt的路径当作数据集path使用而fraction是每次训练临时抽取的可复现子集相关归一化逻辑见 ultralytics/data/utils.py 的get_split_fraction。源码细节ultralytics/data/split.pyweights需三元素求和为 1划分使用random.seed(0)保证结果可复现仅当annotated_onlyTrue时通过img2label_paths检查图片是否存在同目录标签文件只有带标签的图片才参与切分旧的分割文件在重新运行前会被自动清除。2.3 多边形转二值掩膜polygon2mask将单个多边形列表形式按指定图像尺寸渲染为二值掩膜mask。多边形需为交替 x、y 坐标的扁平一维数组即N个点展开成2N个数⚠️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, # (高, 宽) 元组 [polygon], # 以列表形式传入 color255, # 8-bit 掩膜的填充值 downsample_ratio1, )底层实现 ultralytics/data/utils.py 先np.zeros(imgsz, dtypenp.uint8)建底图再用cv2.fillPoly填充这也解释了为何要求偶数点随后按downsample_ratio用cv2.resize下采样。注释还说明先填充再缩放是为了与mask-ratio1的损失计算方式保持一致。同一文件中的polygons2masks与polygons2masks_overlap是面向多个多边形/重叠实例的批量扩展版本可在需要多类别掩膜时参考。三、边界框Bounding Boxes工具箱3.1 Bboxes统一管理边界框的类Bboxes类封装了水平边界框最常见的操作——格式互转、缩放、面积、加偏移等避免手写一堆numpy切片。其实现位于 ultralytics/utils/instance.py支持xyxy、xywh、ltwh三种格式要求输入为 NumPy 数组import numpy as np 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) print(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]] # )areas()instance.pyxyxy格式用(x2-x1)*(y2-y1)xywh/ltwh用w*hconvert(format)instance.py原地将内部格式在xyxy、xywh、ltwh间切换非法格式会直接断言报错。完整属性与方法清单见Bboxes参考页。 以下若干函数的功能都能通过Bboxes类方法完成如果你更习惯面向函数式编程可直接使用接下来的独立导入方式。3.2 图像缩放时同步缩放框scale_boxes对图像做缩放/拉伸预处理后框坐标必须随之更新否则标注会错位。ultralytics.utils.ops.scale_boxes正是干这件事的ops.pyimport 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, # 传入 None 时由两图尺寸自动计算缩放比与 padding paddingFalse, xywhFalse, # True 时输入输出为 xywh否则为 xyxy ) print(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]] # )实现要点ops.py当ratio_padNone时按gain min(旧h/新h, 旧w/新w)计算等比缩放系数并推导 YOLO 式 letterbox 的居中 paddingpaddingTrue时先减去 padding 再除 gain最后经clip_boxes把越界坐标裁剪回图内。支持传入 PyTorch Tensor 或 NumPy 数组并保持输入输出格式一致。3.3 坐标格式转换XYXY → XYWHxyxy2xywh把(x1, y1, x2, y2)左上角 右下角转为(x, y, width, height)中心点 宽高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) print(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]] # )其中(x1, y1)为左上角、(x2, y2)为右下角。可以看到输出与 3.1 节boxes.convert(xywh)的结果完全一致——两类 API 殊途同归可按使用习惯任选。3.4 其余全部格式转换函数Ultralytics 在 ultralytics/utils/ops.py 中提供了一整套对称的转换函数覆盖xyxy、xywh、ltwh左上角 宽高以及归一化与非归一化之间的互换from ultralytics.utils.ops import ( ltwh2xywh, ltwh2xyxy, xywh2ltwh, # xywh → 左上角坐标 w, h xywh2xyxy, xywhn2xyxy, # 归一化 → 像素坐标 xyxy2ltwh, # xyxy → 左上角坐标 w, h xyxy2xywhn, # 像素坐标 → 归一化 ) for func in (ltwh2xywh, ltwh2xyxy, xywh2ltwh, xywh2xyxy, xywhn2xyxy, xyxy2ltwh, xyxy2xywhn): print(help(func)) # 打印各函数 docstring用help()即可查看每个函数精确的输入输出约定更完整的文档见 ultralytics.utils.ops 参考页。四、可视化与标注绘制PlottingUltralytics 提供Annotator系列类适合在检测框boxes、姿态关键点keypoints、旋转框OBB等多种预测结果之上叠加可视化。4.1 基础 Annotator水平框与旋转框标注基础类 Annotator 的初始化参数包括line_width缺省自动按图尺寸定宽、font_size缺省自动、font需为 ImageFont 兼容字体如Arial.ttf与pil选择 PIL 或 OpenCV 渲染后端。水平边界框示例import cv2 as cv import numpy as np from ultralytics.utils.plotting import Annotator, colors names { 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, # True 走 PILFalse 走 OpenCV ) 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()旋转框 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 y3 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, pilFalse, ) for obb in obb_boxes: c_idx, *obb obb obb np.array(obb).reshape(-1, 4, 2).squeeze() label f{obb_names.get(int(c_idx))} ann.box_label( obb, label, colorcolors(c_idx, True), ) image_with_obb ann.result()核心绘制入口是box_labelplotting.py它同时完成画框与写标签标签带背景色块colors(cls, bgrTrue)按类别索引返回稳定颜色。实际处理检测结果时类别名建议直接取model.names见 处理预测结果colors()与Annotator的更多属性请参考Annotator参考页。4.2 扫线Sweep标注与跨线计数sweep_annotator是 SolutionAnnotator继承自Annotator的解决方案专用标注器提供的能力适合在视频中拖拽一条竖向扫线并实时统计越线目标数。它把检测框、分割掩膜、跟踪 ID、类别名与计数标签整合到同一画面上import sys import cv2 import numpy as np from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors # 用户自定义视频路径与模型文件 cap cv2.VideoCapture(path/to/video.mp4) model YOLO(modelyolo26s-seg.pt) # 模型文件如 yolo26s.pt 或 yolo26m-seg.pt if not cap.isOpened(): print(Error: Could not open video.) sys.exit() # 初始化视频写入器 w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) video_writer cv2.VideoWriter(ultralytics.avi, cv2.VideoWriter_fourcc(*mp4v), fps, (w, h)) masks None # 存储掩膜数据的变量 f 0 # 帧计数用于启用鼠标事件 line_x w # 扫线的横坐标 dragging False # 拖拽状态布尔标记 classes model.names # 用于绘制标签的模型类别名 window_name Ultralytics Sweep Annotator def drag_line(event, x, _, flags, param): 鼠标回调函数在视频帧上拖拽一条竖直扫线。 global line_x, dragging if event cv2.EVENT_LBUTTONDOWN or (flags cv2.EVENT_FLAG_LBUTTON): line_x max(0, min(x, w)) dragging True while cap.isOpened(): # 逐帧读取 ret, im0 cap.read() if not ret: break f f 1 # 帧计数 1 count 0 # 每帧重置计数 results model.track(im0, persistTrue)[0] if f 1: cv2.namedWindow(window_name) cv2.setMouseCallback(window_name, drag_line) annotator SolutionAnnotator(im0) if results.boxes.is_track: if results.masks is not None: masks [np.array(m, dtypenp.int32) for m in results.masks.xy] boxes results.boxes.xyxy.tolist() track_ids results.boxes.id.int().cpu().tolist() clss results.boxes.cls.cpu().tolist() for mask, box, cls, t_id in zip(masks or [None] * len(boxes), boxes, clss, track_ids): color colors(t_id, True) # 为每个跟踪目标分配不同颜色 label f{classes[cls]}:{t_id} if mask is not None and mask.size 0: if box[0] line_x: count 1 cv2.polylines(im0, [mask], True, color, 2) x, y mask.min(axis0) (w_m, _), _ cv2.getTextSize(label, cv2.FONT_HERSHEY_SIMPLEX, 0.5, 1) cv2.rectangle(im0, (x, y - 20), (x w_m, y), color, -1) cv2.putText(im0, label, (x, y - 5), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (255, 255, 255), 1) else: if box[0] line_x: count 1 annotator.box_label(boxbox, colorcolor, labellabel) # 绘制可拖拽的扫线 annotator.sweep_annotator(line_xline_x, line_yh, labelfCOUNT:{count}) cv2.imshow(window_name, im0) video_writer.write(im0) if cv2.waitKey(1) 0xFF ord(q): break # 释放资源 cap.release() video_writer.release() cv2.destroyAllWindows()关键点解读model.track(im0, persistTrue)启用跨帧跟踪跟踪模式文档见 track.md配合results.boxes.id拿到稳定目标 ID有分割掩膜时用cv2.polylines描轮廓否则退化为annotator.box_label画框判定条件box[0] line_x表示目标框左边缘越过扫线则计数 1SolutionAnnotator.sweep_annotatorsolutions.py绘制扫线与COUNT:实时计数文本。该方法完整签名与参数见参考页 sweep_annotator。4.3 自适应矩形 / 圆形标签标注adaptive_label⚠️ 版本说明自Ultralytics v8.3.167起circle_label与text_label被统一为adaptive_label函数通过shape参数指定标注类型矩形annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shaperect)圆形annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shapecircle)该 API 会根据目标尺寸自动自适应字号与画布避免小目标上文字溢出。以下给出两种形状的完整视频标注循环示例。圆形标注Circle Annotationimport cv2 from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors model YOLO(yolo26s.pt) names model.names cap cv2.VideoCapture(path/to/video.mp4) w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) writer cv2.VideoWriter(Ultralytics circle annotation.avi, cv2.VideoWriter_fourcc(*MJPG), fps, (w, h)) while True: ret, im0 cap.read() if not ret: break annotator SolutionAnnotator(im0) results model.predict(im0)[0] boxes results.boxes.xyxy.cpu() clss results.boxes.cls.cpu().tolist() for box, cls in zip(boxes, clss): annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shapecircle) writer.write(im0) cv2.imshow(Ultralytics circle annotation, im0) if cv2.waitKey(1) 0xFF ord(q): break writer.release() cap.release() cv2.destroyAllWindows()矩形文本标注Text Annotationimport cv2 from ultralytics import YOLO from ultralytics.solutions.solutions import SolutionAnnotator from ultralytics.utils.plotting import colors model YOLO(yolo26s.pt) names model.names cap cv2.VideoCapture(path/to/video.mp4) w, h, fps (int(cap.get(x)) for x in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS)) writer cv2.VideoWriter(Ultralytics text annotation.avi, cv2.VideoWriter_fourcc(*MJPG), fps, (w, h)) while True: ret, im0 cap.read() if not ret: break annotator SolutionAnnotator(im0) results model.predict(im0)[0] boxes results.boxes.xyxy.cpu() clss results.boxes.cls.cpu().tolist() for box, cls in zip(boxes, clss): annotator.adaptive_label(box, labelnames[int(cls)], colorcolors(cls, True), shaperect) writer.write(im0) cv2.imshow(Ultralytics text annotation, im0) if cv2.waitKey(1) 0xFF ord(q): break writer.release() cap.release() cv2.destroyAllWindows()两段示例的差异仅在shape参数circle在目标中心绘制圆形自适应标签rect在框左上绘制带背景的文本条。adaptive_label的具体实现solutions.py与字号自适应策略见参考页 SolutionAnnotator.adaptive_label。五、杂项工具5.1 代码段耗时分析Profile需要精确测量一段代码的运行耗时可把 Profile 当作上下文管理器或装饰器使用。它在计时前后会做 GPU 同步如 CUDA保证测量包含真实执行时间from ultralytics.utils.ops import Profile with Profile(devicecuda:0) as dt: pass # 待测操作 print(dt) # Elapsed time is 9.5367431640625e-07 sProfile继承自contextlib.ContextDecorator因此同样支持Profile()修饰函数。源码实现ops.py会依据device参数在进入/退出时同步对应的加速设备。5.2 Ultralytics 支持的图片 / 视频格式常量当需要在程序里判断某文件后缀是否被 Ultralytics 支持时不必硬编码格式集合直接导入 ultralytics/data/utils.py 中的IMG_FORMATS与VID_FORMATS预测模式支持格式清单见 image/video formatsfrom ultralytics.data.utils import IMG_FORMATS, VID_FORMATS print(IMG_FORMATS) # {avif, bmp, dng, heic, heif, jp2, jpeg, jpg, mpo, png, tif, tiff, webp} print(VID_FORMATS) # {asf, avi, gif, m4v, mkv, mov, mp4, mpeg, mpg, ts, wmv, webm}可见 Ultralytics 默认覆盖 13 种图片格式与 12 种视频格式含heic/heif/avif等现代格式。5.3 make_divisible返回大于等于x且能被y整除的最小整数。模型结构设计中常用来把通道数对齐到某个网络的整除约束如 8/16/32 对齐from ultralytics.utils.ops import make_divisible make_divisible(7, 3) # 9 make_divisible(7, 2) # 8实现非常简单ops.pymath.ceil(x / divisor) * divisor当divisor是 PyTorch Tensor 时先取最大值再转为 int方便直接传模型权重相关的除数。六、常见问题FAQ6.1 Ultralytics 包内包含哪些能提升 ML 工作流的工具主要包括用于数据集自动标注的 auto_annotate、把 COCO 转 YOLO 的 convert_coco、图像压缩、数据集自动划分以及边界框格式转换与Annotator可视化等。这些工具能显著减少人工操作、保证数据一致性并提升数据准备效率具体分布在 ultralytics/data/ 与 ultralytics/utils/ 模块内。6.2 如何用 Ultralytics 自动给数据集打标签使用 1.1 节的auto_annotate把预训练 YOLO 检测模型与 SAM 系列模型如mobile_sam.pt组合使用即可为图片目录批量生成分割格式标签from ultralytics.data.annotator import auto_annotate auto_annotate( datapath/to/new/data, det_modelyolo26n.pt, sam_modelmobile_sam.pt, devicecuda, output_dirpath/to/save_labels, )其运行机制详见 auto_annotate 参考页。若需点击式掩膜的人工半自动方案可参考仓库中 SAM-2、SAM-3 与 SAM 模型文档使用检测/分割/OBB 任务的预训练或微调模型输出作为标注来源。6.3 如何把 COCO 标注转换为 YOLO 格式用convert_coco纯检测数据把use_segments、use_keypoints均设为Falsefrom ultralytics.data.converter import convert_coco convert_coco( coco/annotations/, use_segmentsFalse, use_keypointsFalse, cls91to80True, )可选参数含 LVIS 分支详见 convert_coco 参考页。转换为 YOLO 格式前的准备工作可参考 COCO-to-YOLO 转换指南。6.4 如何分析数据集的组成与分布Ultralytics 生态提供了自动化的数据集分析能力如 Platform 的Charts标签页可查看划分占比、各类别数量直方图、图像尺寸分布与标注位置的 2D 热力图帮助训练前发现类别不均衡与离群样本。在本地也可用本篇 1.2 节的visualize_image_annotations逐图目检并用 3.1 节Bboxes.areas()、1.5 节get_bbox_dimension自行统计框宽高与面积分布。6.5 如何把边界框转换为分割标签将x y w h检测标签升级为分割标签使用yolo_bbox2segment前提是按 1.6 节的目录结构组织好images/与labels/from ultralytics.data.converter import yolo_bbox2segment yolo_bbox2segment( im_dirpath/to/images, save_dirNone, # 缺省保存在 images 目录同级 labels-segment sam_modelsam_b.pt, )实现细节与目录约定参见 yolo_bbox2segment 参考页。反向操作分割多边形 →xywh框则用 1.7 节的segments2boxes。总结与延伸阅读Simple Utilities 的价值在于把数据管线中最琐碎、最易出错的环节标注生成、格式转换、坐标运算、绘制渲染收敛成签名清晰、行为可预期的函数与类且大多直接依赖同一仓库内的训练/推理基础设施行为与训练链路完全一致。建议在编写数据处理脚本前先在 docs/en/reference/data/annotator.md、docs/en/reference/data/converter.md、docs/en/reference/data/split.md、docs/en/reference/utils/ops.md、docs/en/reference/utils/instance.md、docs/en/reference/utils/plotting.md 与 docs/en/reference/solutions/solutions.md 中核对目标函数的最新签名。想继续深入可按需阅读模型侧YOLO26 模型文档、SAM 模型文档、SAM-2、SAM-3数据侧COCO 数据集、分割数据集格式使用侧训练参数与 fraction、预测结果处理与支持格式。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考