CVAT 数据集导出实战Ultralytics YOLO 四种标注格式的归档结构、标签文件规范与源码级解析【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvatCVAT 将标注数据导出为 Ultralytics YOLO 格式族Detection、Oriented Bounding Box、Segmentation、Pose 四个子格式以便直接对接 YOLOv8/YOLO11 等框架的训练流程。本文基于 CVAT 官方文档 Ultralytics YOLO 格式说明 与后端实现源码完整拆解导出/导入的 ZIP 归档结构、data.yaml配置、各类别标签文件的逐字段规范、坐标归一化规则与 Track 支持机制并给出 cvat/apps/dataset_manager/formats/yolo.py 中的注册与转换链证据读完即可理解导出物的每个字段从何而来、导入时如何被还原。Ultralytics YOLO 格式家族Ultralytics YOLO 不是一个单一格式而是一个由四个子格式组成的格式族分别对应不同的标注任务Detection目标检测基于矩形框Bounding BoxOriented Bounding Box旋转框标注适用于存在明显朝向的细长目标Segmentation实例分割基于多边形Polygon或掩码MaskPose姿态估计基于骨骼点Skeleton。每个子格式都要求数据集附带data.yaml配置文件标签以逐目标一行的.txt文件组织坐标全部归一化。Ultralytics YOLO 导出支持的标注类型与限制从 格式文档 的导出章节可确认各子格式的输入要求子格式支持的 CVAT 标注属性Attributes轨迹TracksDetectionBounding Boxes不支持支持Oriented Bounding BoxOriented Bounding Boxes不支持支持SegmentationPolygons、Masks不支持支持PoseSkeletons不支持支持需要注意两点属性不被支持即 CVAT 标签上挂的属性在导出后会丢失轨迹支持但 Detection 子格式需要专门选择带 Track 的导出项见下文源码分析。导出 ZIP 归档结构导出结果为.zip归档结构如下完整继承官方文档示例archive.zip/ ├── data.yaml # configuration file ├── train.txt # list of train subset image paths │ ├── images/ │ ├── train/ # directory with images for train subset │ │ ├── image1.jpg │ │ ├── image2.jpg │ │ ├── image3.jpg │ │ └── ... ├── labels/ │ ├── train/ # directory with annotations for train subset │ │ ├── image1.txt │ │ ├── image2.txt │ │ ├── image3.txt │ │ └── ... # train.txt: images/subset/image1.jpg images/subset/image2.jpg ... # data.yaml: path: ./ # dataset root dir train: train.txt # train images (relative to path) # Ultralytics YOLO Pose specific field # First number is the number of points in a skeleton. # If there are several skeletons with different number of points, it is the greatest number of points # Second number defines the format of point info in annotation txt files kpt_shape: [17, 3] # Classes names: 0: person 1: bicycle 2: car # ... # image_name.txt: # content depends on format # Ultralytics YOLO Detection: # label_id - id from names field of data.yaml # cx, cy - relative coordinates of the bbox center # rw, rh - relative size of the bbox # label_id cx cy rw rh 1 0.3 0.8 0.1 0.3 2 0.7 0.2 0.3 0.1 # Ultralytics YOLO Oriented Bounding Boxes: # xn, yn - relative coordinates of the n-th point # label_id x1 y1 x2 y2 x3 y3 x4 y4 1 0.3 0.8 0.1 0.3 0.4 0.5 0.7 0.5 2 0.7 0.2 0.3 0.1 0.4 0.5 0.5 0.6 # Ultralytics YOLO Segmentation: # xn, yn - relative coordinates of the n-th point # label_id x1 y1 x2 y2 x3 y3 ... 1 0.3 0.8 0.1 0.3 0.4 0.5 2 0.7 0.2 0.3 0.1 0.4 0.5 0.5 0.6 0.7 0.5 # Ultralytics YOLO Pose: # cx, cy - relative coordinates of the bbox center # rw, rh - relative size of the bbox # xn, yn - relative coordinates of the n-th point # vn - visibility of n-th point. 2 - visible, 1 - partially visible, 0 - not visible # if second value in kpt_shape is 3: # label_id cx cy rw rh x1 y1 v1 x2 y2 v2 x3 y3 v3 ... 1 0.3 0.8 0.1 0.3 0.3 0.8 2 0.1 0.3 2 0.4 0.5 2 0.0 0.0 0 0.0 0.0 0 2 0.3 0.8 0.1 0.3 0.7 0.2 2 0.3 0.1 1 0.4 0.5 0 0.5 0.6 2 0.7 0.5 2 # if second value in kpt_shape is 2: # label_id cx cy rw rh x1 y1 x2 y2 x3 y3 ... 1 0.3 0.8 0.1 0.3 0.3 0.8 0.1 0.3 0.4 0.5 0.0 0.0 0.0 0.0 2 0.3 0.8 0.1 0.3 0.7 0.2 0.3 0.1 0.4 0.5 0.5 0.6 0.7 0.5 # Note, that if there are several skeletons with different number of points, # smaller skeletons are padded with points with coordinates 0.0 0.0 and visibility 0关键约定每个标注文件与图像一一对应frame_000001.txt是frame_000001.jpg的标注扩展名换为.txt之外文件名不变data.yaml的names字段是类别字典标签文件中的label_id即names的下标训练时框架由此把 id 还原为类名kpt_shape是 Pose 专属字段第一个数是骨骼点数若存在点数不同的多个骨骼取最大值第二个数决定点信息在 txt 中的编码方式——3表示每点带可见性x, y, v 三元组2表示仅坐标x, y 二元组点数不同的骨骼会被补齐较小的骨骼用坐标0.0 0.0且可见性为0的点填充到最大点数保证所有行的字段数一致。坐标归一化与越界警告所有坐标必须归一化到[0, 1]区间x 坐标与宽度除以图像宽度y 坐标与高度除以图像高度。官方文档给出了一条重要的实战警告在 CVAT 中允许把对象或其部分放置在图像边界之外此时归一化后坐标会落在[0, 1]范围之外而YOLOv8 框架会直接忽略含此类坐标的标注行。也就是说导出前若发现目标大量越界需要在 CVAT 中先把对象拉回图像内否则训练时这些标注会静默丢失。导出时的 Track 支持Detection 子格式可以保存轨迹使用Ultralytics YOLO Detection Track格式导出时track id 会追加在对应标注行的末尾# label_id cx cy rw rh optional track_id 1 0.3 0.8 0.1 0.3 1 2 0.7 0.2 0.3 0.1即同一轨迹在不同帧中的行尾携带相同的整数 id而普通 Detection 导出的行尾没有这个字段。源码级实现格式注册与导出调用链CVAT 后端的所有导出/导入格式集中在 cvat/apps/dataset_manager/formats/yolo.py 中通过 cvat/apps/dataset_manager/formats/registry.py 提供的exporter/importer装饰器注册到EXPORT_FORMATS/IMPORT_FORMATS两个全局字典字典键为名称 版本如Ultralytics YOLO Detection 1.0这正是前端下拉列表和 REST API 里看到的格式名。Ultralytics 家族的导出器注册如下yolo.pyexporter(nameUltralytics YOLO Detection, extZIP, version1.0) def _export_yolo_ultralytics_detection(*args, **kwargs): _export_common(*args, format_nameyolo_ultralytics_detection, **kwargs) exporter(nameUltralytics YOLO Detection Track, extZIP, version1.0) def _export_yolo_ultralytics_detection_track(*args, **kwargs): _export_common(*args, format_nameyolo_ultralytics_detection, write_track_idTrue, **kwargs) exporter(nameUltralytics YOLO Segmentation, extZIP, version1.0) def _export_yolo_ultralytics_segmentation(dst_file, temp_dir, instance_data, *, save_imagesFalse): with GetCVATDataExtractor(instance_data, include_imagessave_images) as extractor: dataset StreamDataset.from_extractors(extractor, envdm_env) dataset.transform(EllipsesToMasks) dataset dataset.transform(masks_to_polygons) dataset.export(temp_dir, yolo_ultralytics_segmentation, save_mediasave_images) make_zip_archive(temp_dir, dst_file)由此可以得到三个实现层面的事实Detection 与 Detection Track 共用同一个底层格式。二者都调用 datumaro 的yolo_ultralytics_detection导出器区别仅在于 Track 版本多传了一个write_track_idTrue参数——这就是行尾追加 track id行为的来源Segmentation 导出有专属的预处理链。CVAT 中的椭圆Ellipse标注不能直接写成 YOLO 的多边形点序列因此先经过 EllipsesToMasks 转换用cv2.ellipse按中心、半轴和rotation属性光栅化出二值掩码并编码为 RLE再经过 datumaro 内置的masks_to_polygons把掩码轮廓提取为多边形。这条链解释了为什么文档说 Segmentation 支持 Polygons, Masks掩码经此转换为多边形输出导出统一走抽取-导出-压缩三步。_export_common 先用GetCVATDataExtractor把 CVAT 标注转成 datumaro 数据集save_mediasave_images决定是否随标注输出图像最后由make_zip_archive打包成.zip。此外源码中还注册了一个文档主页面未列入四个的Ultralytics YOLO Classificationyolo.py其独立说明见 format-yolo-ultralytics-classification.md用于图像级分类数据集。Ultralytics YOLO 导入导入 ZIP 结构与目录顺序兼容上传文件是与导出结构相同的.zip归档。为了兼容其他以 Ultralytics YOLO 格式导出数据集的工具例如 Roboflow 一类的平台CVAT 对子集目录与images/labels目录的层级顺序做了双向兼容train/images/与images/train/两种排布都是合法输入archive.zip/ ├── train/ │ ├── images/ # directory with images for train subset │ │ ├── image1.jpg │ │ ├── image2.jpg │ │ └── ... │ ├── labels/ # directory with annotations for train subset │ │ ├── image1.txt │ │ ├── image2.txt │ │ └── ...导入时的 Track 支持四个 Ultralytics YOLO 子格式的导入均支持轨迹还原任何标注行末尾的整数都会被识别为 track id。以 Detection 为例# label_id cx cy rw rh optional track_id 1 0.3 0.8 0.1 0.3 1 2 0.7 0.2 0.3 0.1即上面示例中1这行会还原为轨迹成员2这行仍是独立标注。源码级实现导入调用链与三个关键处理导入统一入口是 _import_common其流程与细节值得逐点核对def _import_common(src_file, temp_dir, instance_data, format_name, *, ...): shutil.unpack_archive(src_file.name, temp_dir, zip) detect_dataset(temp_dir, format_nameformat_name, importerdm_env.importers.get(format_name)) detected_sources dm_env.make_importer(format_name)(temp_dir) image_info {} extractor dm_env.extractors.get(format_name) frames [...] # 用 glob 找出所有 *.txt反推出图像相对路径 root_hint find_dataset_root([DatasetItem(idframe) for frame in frames], instance_data) for frame in frames: # match_dm_item 将数据集中的帧匹配到 CVAT 任务帧 # 匹配成功则记录 (height, width) ... dataset StreamDataset.import_from( temp_dir, format_name, envdm_env, image_infoimage_info, **(import_kwargs or {})) dataset dataset.transform(SetKeyframeForEveryTrackShape) if load_data_callback is not None: load_data_callback(dataset, instance_data) import_dm_annotations(dataset, instance_data)detect_dataset负责目录顺序兼容它让 datumaro 导入器探测数据集根目录因此train/images/与images/train/两种布局都能被识别与文档描述的兼容行为一一对应image_info解决归一化反推问题标签里存的是相对坐标CVAT 需要像素坐标才能还原框。导入时通过match_dm_item把归档中的图像路径与 CVAT 任务中已有的帧做匹配find_dataset_root提供根目录提示匹配成功就取任务的height/width填入image_infodatumaro 再用它把归一化坐标换算回像素SetKeyframeForEveryTrackShape 处理轨迹还原凡是带track_id属性的标注都会被包上keyframeTrue属性再导入使其在 CVAT 中成为轨迹的关键帧形状配合 CVAT 自身的插值机制重建整条轨迹。Pose 格式的导入还有额外逻辑_import_yolo_ultralytics_pose 会先从任务元数据中读出骨骼的点子标签定义point_categories构造skeleton_sub_labels映射后通过import_kwargs传给 datumaro使骨骼点的名称与 CVAT 中骨架结构的点子标签正确对齐。回归测试验证以上格式名与行为均有测试覆盖可作为行为核对依据cvat/apps/dataset_manager/tests/test_rest_api_formats.py 的格式清单断言中列出了Ultralytics YOLO Classification 1.0、Ultralytics YOLO Detection 1.0、Ultralytics YOLO Detection Track 1.0、Ultralytics YOLO Segmentation 1.0、Ultralytics YOLO Oriented Bounding Boxes 1.0、Ultralytics YOLO Pose 1.0等全部 Ultralytics 导出/导入项并对 Pose 等格式执行导出→再导入的往返校验其中Ultralytics YOLO Detection Track 1.0的再导入测试明确映射回Ultralytics YOLO Detection 1.0test_rest_api_formats.py印证了Track 与普通 Detection 共用底层格式的实现cvat/apps/dataset_manager/tests/test_formats.py 将 CVAT 显示名与 datumaro 内部名配对如Ultralytics YOLO Pose 1.0→yolo_ultralytics_pose与 yolo.py 中各导出器传入的format_name完全一致。小结从标注到训练数据集的完整映射环节行为依据选择导出格式从Ultralytics YOLO Detection / OBB / Segmentation / Pose及 Track 变体、Classification中选择yolo.py 的exporter注册生成归档data.yamltrain.txtimages/subset/labels/subset/打包为 ZIP官方文档导出章节、make_zip_archive坐标编码全部归一化x/宽、y/高越界目标会被 YOLOv8 忽略官方文档归一化说明Pose 编码kpt_shape声明点数与三元组/二元组点数不足自动补0 0 0点data.yaml注释轨迹编码行尾追加整数 track id仅 Track 变体导出write_track_idTrue导入兼容同时接受train/images/与images/train/目录顺序detect_dataset轨迹还原行尾整数识别为 track id并以关键帧形式重建轨迹SetKeyframeForEveryTrackShape在操作层面导出入口为任务页Actions → Export task datasetJob 内为Menu → Export job dataset在格式列表中选择上述 Ultralytics 项并填写 ZIP 文件名即可流程详见 导出数据集文档 与 导入数据集文档。结合本文对归档结构与标签字段的逐条说明导出的数据集可直接作为 YOLO 系列框架的训练输入而通过测试文件核对格式名也能快速确认所用部署版本支持哪些 Ultralytics 子格式。【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考