Detectron2 内置数据集完全指南：目录结构、环境变量与准备脚本详解

Detectron2 内置数据集完全指南：目录结构、环境变量与准备脚本详解

【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2

导读

Detectron2 为对象检测、实例分割、全景分割（Panoptic Segmentation）、人体关键点检测与语义分割等任务内置了一批常用数据集的接入支持。本指南以仓库 datasets/README.md 为核心，结合源码与配置文件，完整讲解内置数据集根目录的环境变量配置、各数据集期望的文件摆放结构、配套的准备/转换脚本及其底层实现原理。读完本文，你将能在自己的机器上正确摆放 COCO、LVIS、Cityscapes、Pascal VOC、ADE20K 等数据集，让仓库中所有预置模型配置与官方 Model Zoo 的预训练权重"开箱即用"，并理解这些名字背后DatasetCatalog与MetadataCatalog的注册机制。

一、内置数据集的两大接入入口：DatasetCatalog 与 MetadataCatalog

在动手摆放文件之前，先理解数据是如何被"找到"的。Detectron2 的数据层抽象为两个全局目录对象，均定义在 detectron2/data/catalog.py：

• DatasetCatalog：全局字典，保存"数据集名字 → 无参加载函数"的映射。调用DatasetCatalog.get("coco_2017_train")时，它会执行注册的函数并返回list[dict]形式的样本列表；如果名字未注册，会抛出带可用数据集清单的KeyError（见 catalog.py）。
• MetadataCatalog：保存数据集的元数据（类别名、类别 id 到连续 id 的映射、评估器类型等），例如MetadataCatalog.get("mydataset").thing_classes = ["person", "dog"]。它本质上是一个支持属性读写的全局存储（见 catalog.py）。

内置数据集的全部注册逻辑集中在 detectron2/data/datasets/builtin.py。该文件以硬编码的方式为常见数据集预先注册了名字、路径与元数据，并在 detectron2/data/datasets/init.py 中通过from . import builtin as _builtin保证导入即完成注册。因此你无需手写任何加载代码，只要目录结构摆放正确，就可以直接在配置文件中用数据集名字引用它们。

二、数据集根目录：DETECTRON2_DATASETS 环境变量

Detectron2 假定所有内置数据集都位于环境变量DETECTRON2_DATASETS指向的目录下，其下按如下结构寻找数据集（只需要与任务相关的部分）：

$DETECTRON2_DATASETS/ coco/ lvis/ cityscapes/ VOC20{07,12}/

设置方式：

export DETECTRON2_DATASETS=/path/to/datasets

如果该变量未设置，默认值是当前工作目录（CWD）下的./datasets。这一默认行为在源码中有明确对应：builtin.py 中的_root = os.path.expanduser(os.getenv("DETECTRON2_DATASETS", "datasets"))，即未设置时回退为相对路径datasets。

注册函数随后把这个根目录与每个数据集名字拼接出最终路径并完成注册，例如 COCO 注册的核心代码：

register_coco_instances( key, # 数据集名字，如 "coco_2017_train" _get_builtin_metadata(dataset_name), # 元数据 os.path.join(root, json_file), # 标注 json 路径 os.path.join(root, image_root), # 图片根路径 )

（见 builtin.py）。register_all_coco、register_all_lvis、register_all_cityscapes、register_all_pascal_voc、register_all_ade20k会依次在 import 时被调用（见 builtin.py）。

仓库中的 MODEL_ZOO.md 与 configs/ 目录下全部模型配置所依赖的正是这些内置数据集，因此目录摆放正确与否直接决定预置配置能否运行。

三、COCO 实例/关键点检测数据集的目录结构

COCO 实例分割与人体关键点检测期望如下结构：

coco/ annotations/ instances_{train,val}2017.json person_keypoints_{train,val}2017.json {train,val}2017/ # 上述 json 中引用的图片文件

说明：

• instances_train2017.json/instances_val2017.json服务于实例分割与检测；
• person_keypoints_train2017.json/person_keypoints_val2017.json服务于人体关键点检测（Keypoint R-CNN）；
• {train,val}2017/目录存放与 json 内images字段对应的图片文件；
• 2014 版数据集（train2014/val2014）同样受支持。

3.1 源码中预注册的 COCO splits

builtin.py 中的_PREDEFINED_SPLITS_COCO["coco"]定义了coco_2017_train、coco_2017_val、coco_2017_test、coco_2017_test-dev、coco_2014_train、coco_2014_minival、coco_2014_valminusminival等标准 split 名，以及供快速测试用的coco_2017_val_100；同文件的coco_person分支（builtin.py）定义了keypoints_coco_2017_train、keypoints_coco_2017_val等关键点 split。这就是 configs/Base-RCNN-FPN.yaml 中：

DATASETS: TRAIN: ("coco_2017_train",) TEST: ("coco_2017_val",)

能够直接起效的根本原因——训练与测试阶段通过coco_2017_*这些字符串查表得到 json 路径与图片根目录。

3.2 快速测试用的 mini COCO 数据集

仓库内置的部分集成测试脚本（dev/run_*_tests.sh，如 run_inference_tests.sh、run_instant_tests.sh）需要一个小型 COCO 数据集，可用仓库自带的脚本下载：

./datasets/prepare_for_tests.sh

查看脚本源码 datasets/prepare_for_tests.sh 可知其行为：

• 下载两个只含 100 张图的标注：instances_val2017_100.json与person_keypoints_val2017_100.json；
• 下载并解压val2017_100.tgz（val2017 中仅 100 张图片的子集）；
• 下载根目录取自DETECTRON2_DATASETS环境变量，未设置时默认存到当前目录的./coco/下，同时兼容~展开。

这正对应 configs/quick_schedules/ 下众多 instant/inference_acc_test 配置的测试数据。

四、PanopticFPN 所需的全景分割目录结构

Panoptic FPN 训练除了常规实例标注外，还要求全景标注（panoptic annotations）与从全景标注派生出的语义标注。请从 COCO 官网下载全景标注后解压为如下结构：

coco/ annotations/ panoptic_{train,val}2017.json panoptic_{train,val}2017/ # png 格式的全景标注 panoptic_stuff_{train,val}2017/ # 由下文脚本生成

首先安装 panopticapi 依赖：

pip install git+https://github.com/cocodataset/panopticapi.git

然后执行仓库自带脚本，从全景标注中提取语义分割标注：

python datasets/prepare_panoptic_fpn.py

4.1 脚本底层做了什么

分析 datasets/prepare_panoptic_fpn.py 的实现，其核心是separate_coco_semantic_from_panoptic函数：

• 使用panopticapi.utils.rgb2id把 PNG 的 RGB 编码还原为全景 segment id；
• 建立一张 id 映射表（见 prepare_panoptic_fpn.py）：所有thing（可数物体）类别统一映射到类别 0，所有stuff（背景/材质）类别映射到从 1 开始的连续 id，未标注像素（id 0）映射到 255；
• 通过multiprocessing.Pool并行把每张全景 PNG 转写为语义 PNG，输出到panoptic_stuff_{s}/目录。

主流程依次处理val2017与train2017（见 prepare_panoptic_fpn.py）。这也解释了为什么 configs/COCO-PanopticSegmentation/Base-Panoptic-FPN.yaml 里的 PanopticFPN 需要三个并行目录（原始全景、全景 json、panoptic_stuff_*语义目录）——它们在 builtin.py 的_PREDEFINED_SPLITS_COCO_PANOPTIC中被逐一硬编码，注册时区分了"separated"版本（供 PanopticFPN 使用）与"standard"版本（供 Panoptic-DeepLab 使用）。

五、LVIS 实例分割数据集的目录结构

LVIS（Large Vocabulary Instance Segmentation）要求的结构比较特殊——图片直接复用 COCO 图片目录，标注放在独立lvis/目录：

coco/ {train,val,test}2017/ lvis/ lvis_v0.5_{train,val}.json lvis_v0.5_image_info_test.json lvis_v1_{train,val}.json lvis_v1_image_info_test{,_challenge}.json

5.1 依赖安装

评估 LVIS 结果需要 lvis-api：

pip install git+https://github.com/lvis-dataset/lvis-api.git

5.2 用 COCO 类别评估 LVIS 模型：COCOfied 标注

若想用 LVIS 标注来评估在 COCO 数据集上训练的模型，需要把 LVIS 标注"COCO 化"（只保留与 COCO 共有的类别，并把类别 id 映射为 COCO id）：

python datasets/prepare_cocofied_lvis.py

源码 datasets/prepare_cocofied_lvis.py 中的cocofy_lvis函数展示了映射逻辑：借助一份硬编码的 COCO synset→cat_id 表（COCO_SYNSET_CATEGORIES，prepare_cocofied_lvis.py），先建立 LVIS 类别 → synset → COCO 类别的两级映射，然后过滤掉 COCO 中不存在的类别（prepare_cocofied_lvis.py），并同步重写每张图片的not_exhaustive_category_ids/neg_category_ids与 categories 表。脚本默认生成lvis_v0.5_train_cocofied.json与lvis_v0.5_val_cocofied.json。

注册端则体现在 builtin.py 的_PREDEFINED_SPLITS_LVIS：lvis_v1_train/lvis_v1_val、lvis_v0.5_train/lvis_v0.5_val，以及lvis_v0.5_train_cocofied/lvis_v0.5_val_cocofied都被预注册，且图片根目录一律指向coco/。例如 configs/LVISv1-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.yaml 中DATASETS.TRAIN: ("lvis_v1_train",)直接可用。

六、Cityscapes 数据集的目录结构

Cityscapes 同时支撑实例分割、语义分割与全景分割三类任务，期望的原始结构如下：

cityscapes/ gtFine/ train/ aachen/ color.png, instanceIds.png, labelIds.png, polygons.json, labelTrainIds.png ... val/ test/ # 以下为生成的 Cityscapes 全景标注 cityscapes_panoptic_train.json cityscapes_panoptic_train/ cityscapes_panoptic_val.json cityscapes_panoptic_val/ cityscapes_panoptic_test.json cityscapes_panoptic_test/ leftImg8bit/ train/ val/ test/

6.1 依赖安装

pip install git+https://github.com/mcordts/cityscapesScripts.git

6.2 生成 labelTrainIds.png（语义分割可选）

语义分割训练通常使用labelTrainIds.png（trainId 编码）而非原始labelIds.png。先按上述结构准备数据，然后执行：

CITYSCAPES_DATASET=/path/to/abovementioned/cityscapes python cityscapesscripts/preparation/createTrainIdLabelImgs.py

注意：这些文件对实例分割不是必需的。

6.3 生成 Cityscapes 全景标注（全景分割可选）

如需全景分割能力，再执行 cityscapesScripts 生成全景标注：

CITYSCAPES_DATASET=/path/to/abovementioned/cityscapes python cityscapesscripts/preparation/createPanopticImgs.py

这些文件对语义分割与实例分割不是必需的。cityscapes 的原始图像/GT 目录与全景注册逻辑可在 cityscapes.py、cityscapes_panoptic.py 及 builtin.py 中查看。

6.4 配置中的 split 命名

从 configs/Cityscapes/mask_rcnn_R_50_FPN.yaml 可见，Cityscapes 实例分割任务使用的 split 名为cityscapes_fine_instance_seg_train/cityscapes_fine_instance_seg_val，语义分割对应cityscapes_fine_sem_seg_{train,val,test}，它们由_RAW_CITYSCAPES_SPLITS的模板串格式化得到（见 builtin.py）。

七、Pascal VOC 数据集的目录结构

Pascal VOC（2007/2012）用于目标检测训练，期望结构为：

VOC20{07,12}/ Annotations/ ImageSets/ Main/ trainval.txt test.txt # 若使用这些 split，还需 train.txt 或 val.txt JPEGImages/

其中Annotations/为 XML 标注，JPEGImages/为图片，ImageSets/Main/存放各 split 的文件清单。仓库默认假设目录名为VOC2007与VOC2012（见 builtin.py 中的register_all_pascal_voc，split 列表覆盖voc_2007_trainval、voc_2007_train、voc_2007_val、voc_2007_test、voc_2012_trainval等，注册函数实现位于 pascal_voc.py）。

典型用法见 configs/PascalVOC-Detection/faster_rcnn_R_50_FPN.yaml：

DATASETS: TRAIN: ('voc_2007_trainval', 'voc_2012_trainval') TEST: ('voc_2007_test',)

八、ADE20K 场景解析数据集的目录结构

ADE20K Scene Parsing 服务于语义分割任务，期望结构：

ADEChallengeData2016/ annotations/ annotations_detectron2/ images/ objectInfo150.txt

8.1 转换脚本 prepare_ade20k_sem_seg.py

annotations_detectron2/目录需由仓库脚本生成：

python datasets/prepare_ade20k_sem_seg.py

该脚本的核心实现非常简洁（见 datasets/prepare_ade20k_sem_seg.py）：对annotations/{training,validation}中的每张标注图执行img = img - 1转换，使原始类别 id 0（忽略区域）变为 255，其余类别整体平移 1，然后写入annotations_detectron2/。这是因为 Detectron2 的语义分割约定以 255 表示 ignore 区域。生成的ade20k_sem_seg_train/ade20k_sem_seg_val在 builtin.py 中被注册，其图片扩展名为jpg、GT 扩展名为png、ignore 标签为 255。

九、验证与排查建议

根据源码行为，可按以下思路排查"数据集找不到/为空"类问题：

1. 确认注册成功：import detectron2.data.datasets后调用DatasetCatalog.list()，应能看到coco_2017_train、lvis_v1_train、cityscapes_fine_instance_seg_train、voc_2007_trainval、ade20k_sem_seg_train等全部内置名字；若某名字缺失，检查 builtin.py 中if __name__.endswith(".builtin")的条件是否满足（正常情况下通过包导入会满足）。
2. 确认根目录生效：echo $DETECTRON2_DATASETS；未设置时程序以运行目录下的datasets/为根。建议统一显式设置。
3. 确认 json 路径匹配：所有内置 split 都是"json 绝对/相对路径 + 图片根目录"的组合（如coco/annotations/instances_train2017.json配coco/train2017），json 中images的file_name需能相对图片根目录解析到真实文件。
4. 分清任务所需目录：实例分割只需 images + instances json；PanopticFPN 额外需要panoptic_*与panoptic_stuff_*；语义分割类（ADE20K）需要完成 -1 平移的转换目录；labelTrainIds.png与 cityscapes 全景标注仅对相应任务必需。

结语

Detectron2 把"数据集可用性"设计成了纯粹的目录约定：只要按 datasets/README.md 把各类数据集摆放到DETECTRON2_DATASETS之下，builtin.py 里的硬编码注册即可在 import 阶段自动完成全部接入，配合仓库 datasets/ 目录下的prepare_for_tests.sh、prepare_panoptic_fpn.py、prepare_cocofied_lvis.py、prepare_ade20k_sem_seg.py四个脚本完成 mini 数据集下载、语义标注派生、类别映射与格式平移等全部预处理工作。理解这套结构，你就能在 configs/ 与 MODEL_ZOO.md 提供的数百个模型配置间自由切换数据与任务，是熟练使用 Detectron2 的第一步，也是接入自定义数据集（详见仓库内数据注册教程）的必备基础。

【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2