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.pyDatasetCatalog全局字典保存数据集名字 → 无参加载函数的映射。调用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 splitsbuiltin.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.tgzval2017 中仅 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 githttps://github.com/cocodataset/panopticapi.git然后执行仓库自带脚本从全景标注中提取语义分割标注python datasets/prepare_panoptic_fpn.py4.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 实例分割数据集的目录结构LVISLarge 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}.json5.1 依赖安装评估 LVIS 结果需要 lvis-apipip install githttps://github.com/lvis-dataset/lvis-api.git5.2 用 COCO 类别评估 LVIS 模型COCOfied 标注若想用 LVIS 标注来评估在 COCO 数据集上训练的模型需要把 LVIS 标注COCO 化只保留与 COCO 共有的类别并把类别 id 映射为 COCO idpython datasets/prepare_cocofied_lvis.py源码 datasets/prepare_cocofied_lvis.py 中的cocofy_lvis函数展示了映射逻辑借助一份硬编码的 COCO synset→cat_id 表COCO_SYNSET_CATEGORIESprepare_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_LVISlvis_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 githttps://github.com/mcordts/cityscapesScripts.git6.2 生成 labelTrainIds.png语义分割可选语义分割训练通常使用labelTrainIds.pngtrainId 编码而非原始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 VOC2007/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_vocsplit 列表覆盖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.yamlDATASETS: TRAIN: (voc_2007_trainval, voc_2012_trainval) TEST: (voc_2007_test,)八、ADE20K 场景解析数据集的目录结构ADE20K Scene Parsing 服务于语义分割任务期望结构ADEChallengeData2016/ annotations/ annotations_detectron2/ images/ objectInfo150.txt8.1 转换脚本 prepare_ade20k_sem_seg.pyannotations_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。九、验证与排查建议根据源码行为可按以下思路排查数据集找不到/为空类问题确认注册成功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)的条件是否满足正常情况下通过包导入会满足。确认根目录生效echo $DETECTRON2_DATASETS未设置时程序以运行目录下的datasets/为根。建议统一显式设置。确认 json 路径匹配所有内置 split 都是json 绝对/相对路径 图片根目录的组合如coco/annotations/instances_train2017.json配coco/train2017json 中images的file_name需能相对图片根目录解析到真实文件。分清任务所需目录实例分割只需 images instances jsonPanopticFPN 额外需要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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考