CVAT Cityscapes 格式导入导出实战：像素级标注编码、标签色表与源码级实现解析-酒店常州论坛

CVAT Cityscapes 格式导入导出实战：像素级标注编码、标签色表与源码级实现解析

【免费下载链接】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

Cityscapes 是面向城市街景语义分割与实例分割的像素级标注事实标准，CVAT 通过 Datumaro 引擎为其提供了完整的"导出为 Cityscapes ZIP / 从 Cityscapes ZIP 导入"能力。本文以 CVAT 官方文档 format-cityscapes.md 为主线，完整梳理其导出/导入的标注支持范围、.zip包结构、gtFine三类 PNG 的像素编码规则与原始色表定义，并结合 cityscapes.py 等源码，说明形状到掩码的转换链、标签色表（label map）的生成逻辑与Convert masks to polygons选项的默认行为，帮助你把 CVAT 任务与标准 Cityscapes 数据管线可靠打通。

Cityscapes 格式概述

Cityscapes 格式在计算机视觉领域被广泛用作标准格式，尤其适用于城市街景中的语义分割（semantic segmentation）与实例分割（instance segmentation）任务。该格式通常由高分辨率的城市街景图像及其详细的像素级标注组成：每个像素都被标注为"road（道路）""pedestrian（行人）""vehicle（车辆）"等类别之一，是训练和验证城市环境理解模型的宝贵资源，也是自动驾驶、机器人、智慧城市方向研究人员和工程人员的常用选择。

Cityscapes 导出

支持的标注类型与限制

从文档定义来看，Cityscapes 导出遵循以下规则：

支持的标注：Masks（掩码）、Polygons（转换为掩码）、Bounding Boxes（转换为掩码）、Ellipses（转换为掩码）。由于 Cityscapes 是纯像素级格式，CVAT 在导出时会统一把各类形状"栅格化"为掩码；
属性（Attributes）：
- is_crowd（boolean）：必须为相应标签定义为checkbox（复选框）类型属性。它指定该标注标签是否能区分不同实例（instance）。如果is_crowd为False，导出的标注会包含实例 ID（instance id）值；
Tracks（轨迹）：不支持，轨迹会被拆导出为独立的形状（exported as separate shapes）。

导出产物：ZIP 包结构

导出结果是名为taskname.zip的归档文件，内部结构如下：

taskname.zip/ ├── label_color.txt ├── gtFine │ ├── <subset_name> │ │ └── <city_name> │ │ ├── image_0_gtFine_instanceIds.png │ │ ├── image_0_gtFine_color.png │ │ ├── image_0_gtFine_labelIds.png │ │ ├── image_1_gtFine_instanceIds.png │ │ ├── image_1_gtFine_color.png │ │ ├── image_1_gtFine_labelIds.png │ │ ├── ... └── imgsFine # if saving images was requested └── leftImg8bit ├── <subset_name> │ └── <city_name> │ ├── image_0_leftImg8bit.png │ ├── image_1_leftImg8bit.png │ ├── ...

各文件的含义：

label_color.txt：描述每个标签颜色的文件，每行为r g b label_name：
```
# label_color.txt example # r g b label_name 0 0 0 background 0 255 0 tree ...
```
*_gtFine_color.png：类别标签以颜色编码——每个像素的 RGB 值对应该类别在色表中的颜色；
*_gtFine_labelIds.png：类别标签以索引（index）编码——每个像素值为该类别的类别 ID；
*_gtFine_instanceIds.png：类别与实例联合编码的"超级像素 ID"图。像素值同时编码类别与单个实例：对 ID 做整除 1000 的整数部分得到类别 ID，余数（mod 1000）得到实例 ID。如果某条标注描述的是多个实例（crowd，即is_crowd为真），其像素只写入该类别的常规 ID（不含实例号）。

源码解析：导出流水线

CVAT 的 Cityscapes 导出器注册在 cityscapes.py 中，通过@exporter(name="Cityscapes", ext="ZIP", version="1.0")装饰器登记（显示名为Cityscapes 1.0）。其_export函数的执行链是：

GetCVATDataExtractor(instance_data, include_images=save_images)从数据库构建 Datumaro 数据抽取器，save_images参数即对应 UI 上"保存图像"选项，决定最终包中是否包含imgsFine目录；
依次施加一串形状到掩码的变换：RotatedBoxesToPolygons（旋转框转多边形）→"polygons_to_masks"→"boxes_to_masks"→EllipsesToMasks（椭圆光栅化为 RLE 掩码，实现见 transformations.py 中基于cv2.ellipse的编码）→"merge_instance_segments"（合并同一实例的分段）；
dataset.export(temp_dir, "cityscapes", save_media=save_images, apply_colormap=True, label_map=...)调用 Datumaro 的 cityscapes 导出器，其中label_map由make_colormap(instance_data)构造，即"任务标签名 → 标签颜色 RGB"的映射；
make_zip_archive把中间目录打包成最终 ZIP。

其中label_map的构造函数 make_colormap 有一个与文档强相关的行为：如果任务标签中没有background，会自动在首位插入一个黑色背景标签{"name": "background", "color": "#000000"}。这正是文档强调"必须有一个黑色背景的标签"这一要求的底层依据——导出逻辑本身就会保证背景存在，但若你的业务背景类别命名/颜色与原始 Cityscapes 不一致，导入回标准管线时可能产生歧义，因此建议任务中显式保留黑色background标签。

Cityscapes 导入

支持范围

支持的标注：Masks；Polygons（当启用Convert masks to polygons选项时，掩码会被转换为多边形导入）；
属性：is_crowd（boolean），须定义为checkbox类型；
Tracks：不支持。

上传文件结构

上传的.zip归档结构为：

archive.zip/ ├── label_color.txt # optional └── gtFine └── <city_name> ├── image_0_gtFine_instanceIds.png ├── image_1_gtFine_instanceIds.png ├── ...

源码解析：导入流水线与颜色表文件

导入器_import的实现见 cityscapes.py：

shutil.unpack_archive解压 ZIP 到临时目录；
检查目录下的标签颜色表文件。从源码看，导入器实际检查与写入的文件名是label_colors.txt：若压缩包中未提供该文件，则用任务自身标签颜色经write_label_map生成一份，作为gtFine像素解码的依据。因此上传包若自带颜色表，建议使用导入器处理的label_colors.txt文件名，避免被按任务默认颜色重新生成；
detect_dataset以format_name="cityscapes"探测目录结构，随后StreamDataset.import_from(temp_dir, "cityscapes", env=dm_env)完成像素图到掩码的反向解码；
MaskToPolygonTransformation.convert_dataset(dataset, **kwargs)控制"掩码转多边形"。该变换的选项名为conv_mask_to_poly（见 transformations.py），默认值为True，即默认把导入的掩码转为多边形形状（与文档中"Polygons (if Convert masks to polygons is enabled)"一致）。该参数沿调用链从 REST 层传入：task.py 中import_task_annotations(src_file, task_id, format_name, conv_mask_to_poly, ...)将其透传给 importer，project.py 的import_dataset_as_project同样以conv_mask_to_poly参数支持项目级导入；
最后import_dm_annotations把解析出的标注写回任务/作业数据库。

创建 Cityscapes 任务：标签与颜色配置

文档给出的任务创建流程分为三步，并特别强调标签配置的约束：

创建带所需标签的任务——你可以自定义标签，也可以直接复用原始 Cityscapes 数据集的标签与颜色。但要处理 Cityscapes 格式，必须有一个黑色（#000000）的background标签；

上传图像，打包结构如：

images.zip/ ├── image_0.jpg ├── image_1.jpg ├── ...

创建任务后，按上一节描述的 ZIP 结构上传 Cityscapes 标注。

此外，若需要导出/导入实例 ID，对应标签须定义is_crowd布尔复选框属性。CVAT 格式测试资产 tasks.json 中的Cityscapes 1.0任务正是一个标准示例：car标签带有is_crowd属性（input_type为checkbox、mutable为false、取值["false", "true"]），person标签无属性，并始终包含黑色background标签——与文档要求一一对应。

原始 Cityscapes 色表（34 类）

如果你要与官方数据集保持标签/颜色对齐，文档提供了完整的原始色表（JSON），可原样用于任务标签定义：

[ {"name": "unlabeled", "color": "#000000", "attributes": []}, {"name": "egovehicle", "color": "#000000", "attributes": []}, {"name": "rectificationborder", "color": "#000000", "attributes": []}, {"name": "outofroi", "color": "#000000", "attributes": []}, {"name": "static", "color": "#000000", "attributes": []}, {"name": "dynamic", "color": "#6f4a00", "attributes": []}, {"name": "ground", "color": "#510051", "attributes": []}, {"name": "road", "color": "#804080", "attributes": []}, {"name": "sidewalk", "color": "#f423e8", "attributes": []}, {"name": "parking", "color": "#faaaa0", "attributes": []}, {"name": "railtrack", "color": "#e6968c", "attributes": []}, {"name": "building", "color": "#464646", "attributes": []}, {"name": "wall", "color": "#66669c", "attributes": []}, {"name": "fence", "color": "#be9999", "attributes": []}, {"name": "guardrail", "color": "#b4a5b4", "attributes": []}, {"name": "bridge", "color": "#966464", "attributes": []}, {"name": "tunnel", "color": "#96785a", "attributes": []}, {"name": "pole", "color": "#999999", "attributes": []}, {"name": "polegroup", "color": "#999999", "attributes": []}, {"name": "trafficlight", "color": "#faaa1e", "attributes": []}, {"name": "trafficsign", "color": "#dcdc00", "attributes": []}, {"name": "vegetation", "color": "#6b8e23", "attributes": []}, {"name": "terrain", "color": "#98fb98", "attributes": []}, {"name": "sky", "color": "#4682b4", "attributes": []}, {"name": "person", "color": "#dc143c", "attributes": []}, {"name": "rider", "color": "#ff0000", "attributes": []}, {"name": "car", "color": "#00008e", "attributes": []}, {"name": "truck", "color": "#000046", "attributes": []}, {"name": "bus", "color": "#003c64", "attributes": []}, {"name": "caravan", "color": "#00005a", "attributes": []}, {"name": "trailer", "color": "#00006e", "attributes": []}, {"name": "train", "color": "#005064", "attributes": []}, {"name": "motorcycle", "color": "#0000e6", "attributes": []}, {"name": "bicycle", "color": "#770b20", "attributes": []}, {"name": "licenseplate", "color": "#00000e", "attributes": []} ]

需要注意色表中的隐含约束：unlabeled、egovehicle、rectificationborder、outofroi、static均映射为黑色#000000——与"背景必须为黑色"的要求一致，即多个不可区分/未标注语义都归并到背景。

格式注册与测试验证

Cityscapes 格式在格式注册表中以Cityscapes 1.0显示名分别注册到导出与导入两侧：

注册机制：registry.py 中exporter/importer装饰器把格式函数包装为带NAME、VERSION、EXT、DISPLAY_NAME元信息的对象，分别存入EXPORT_FORMATS与IMPORT_FORMATS字典；cityscapes模块在文件尾部随所有格式模块一起导入完成自注册（见 registry.py 的导入段）；
测试佐证：test_formats.py 断言导出/导入格式集合均包含"Cityscapes 1.0"；同时其中一行注释明确记录# ('Cityscapes 1.0', 'cityscapes'), does not support, empty annotations，说明 Cityscapes 格式的空标注（无标注）场景在通用空标注往返测试中是被排除的，属于该格式的已知限制。

实践建议与已知限制

结合文档与源码，使用 Cityscapes 格式时建议注意以下几点：

形状多样性统一为掩码：导出前 CVAT 会把旋转框、多边形、矩形框、椭圆全部转换为掩码（RotatedBoxesToPolygons、polygons_to_masks、boxes_to_masks、EllipsesToMasks），原始形状信息在导出后不可恢复；
轨迹不可用：Tracks 会被拆为独立形状导出，导入侧也不支持轨迹还原；
实例语义依赖is_crowd：只有is_crowd为False的标注才会写入 instance ID；crowd 标注在instanceIds.png中退化为纯类别 ID。标签必须正确定义checkbox类型的is_crowd属性（可参考 tasks.json 的测试任务定义）；
背景与颜色表一致性：确保存在黑色background标签；跨数据集交换时，注意导出包中的label_color.txt与导入侧实际处理的label_colors.txt文件名约定，避免因颜色表缺失而按任务默认颜色解码；
掩码转多边形默认开启：导入时conv_mask_to_poly默认为True，掩码会转换为多边形以便在 UI 中编辑；如需保留掩码形态，可在导入选项中关闭该转换。

参考

文档原文：Cityscapes 格式说明
导出/导入实现：cityscapes.py
形状转换（椭圆/旋转框/掩码转多边形）：transformations.py
标签色表构造：utils.py
格式注册表：registry.py
导入调用链：task.py、project.py
测试与测试资产：test_formats.py、tasks.json

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析