PaddleSeg 全景分割工具包开发者指南：架构、数据编码与数据集定制全解析

人工智能计算机视觉预训练【免费下载链接】PaddleSegEasy-to-use image segmentation library with awesome pre-trained model zoo, supporting wide-range of practical tasks in Semantic Segmentation, Interactive Segmentation, Panoptic Segmentation, Image Matting, 3D Segmentation, etc.项目地址https://gitcode.com/gh_mirrors/pa/PaddleSeg点击查看免费下载本文面向希望向 PanopticSeg基于 PaddleSeg 的全景分割工具包位于仓库 contrib/PanopticSeg贡献代码或进行二次开发的开发者系统梳理该工具包的高级特性模块化的目录结构、贯穿训练/评估/推理全流程的核心数据结构InfoDict、统一的pan_id标签编码协议以及基于 MS COCO 格式自定义数据集的完整流程。读完本文你将掌握该工具包的组件注册机制、数据流转形态与标签编解码原理能够独立接入新数据集并理解模型输出到评估指标的完整链路。1 全景分割工具包目录结构一张模块地图与 PaddleSeg 主仓库paddleseg不同PanopticSeg 是一个相对独立的子工具包其顶层目录结构清晰地划分了配置、部署、核心实现与工具四类内容。理解这份结构图是后续二次开发的第一步PanopticSeg ├── configs: Configuration files. Organized by model. ├── deploy: Code related to model deployment. │ └── python: Python deployment code. ├── docs: Documents. ├── paddlepanseg: │ ├── core: Core APIs that supports model training, evaluation, and inference. │ ├── cvlibs: Core data structures. │ │ ├── config.py: Manage configurations. │ │ ├── info_dicts.py: Data containers for prediction results, samples, etc. │ │ └── manager.py: Register and manage components. │ ├── datasets: Interfaces for dataset IO. │ ├── deploy: Deployment APIs. │ ├── models: Implementations of models. │ │ ├── backbones: Implementations of backbone networks. │ │ ├── losses: Implementations of loss functions. │ │ ├── ops: Implementations of external operators. │ │ ├── common.py: Common classes and functions. │ │ └── param_init.py: Utility functions for weight initialization. │ ├── postprocessors: Postprocessors. │ ├── runners: Runners. │ ├── transforms: Data transformation operators. │ │ └── generate_targets: Transformation operators to generate training targets. │ └── utils: Utility functions and classes. ├── test_tipc: TIPC scripts. └── tools: Useful tools for users. ├── data: Tools for preparing public datasets. ├── analyze_model.py: Analyze the parameter count and computational complexity of a panoptic segmentation model. ├── export.py: Export model to static graph. ├── predict.py: Make inference with a pre-trained model and produce visualization results. ├── train.py: Train a model on a specific dataset. └── val.py: Evaluate the performance of a model on a specific dataset.从源码实现看各目录职责可以进一步展开paddlepanseg/cvlibs是整个工具包的地基。其中 manager.py 定义了五个组件管理器MODELS、DATASETS、POSTPROCESSORS、RUNNERS为本工具包新增语义分割与全景分割差异巨大而BACKBONES、TRANSFORMS、OPTIMIZERS、LOSSES则直接复用paddleseg.cvlibs.manager中已有的管理器——这意味着主干网络和数据增强算子可以在两个工具包之间直接复用。config.py 中的Config类继承自paddleseg.cvlibs.Config额外暴露了postprocessor_cfg、export_cfg、runner_cfg三个属性专门解析全景分割独有的postprocessor、export、runner配置段配套的PanSegBuilder则在构建后处理器时会自动从验证集数据集补齐num_classes、thing_ids、label_divisor、ignore_index等参数。paddlepanseg/postprocessors存放模型后处理逻辑目前已内置 panoptic_deeplab_pp.py 与maskformer_pp.py分别对应 Panoptic-DeepLab 和 Mask2Former 两种模型。paddlepanseg/runners存放训练/评估执行器runner同样按模型拆分。paddlepanseg/transforms/generate_targets是训练目标生成器其中GeneratePanopticDeepLabTrainTargets会从pan_id标签中解出语义、实例中心与偏移等监督信号。tools提供面向用户的五个脚本train.py、val.py、predict.py、export.py、analyze_model.py以及公开数据集准备工具tools/data。从配置目录可以看到当前工具包支持的模型族configs/mask2former 与 configs/panoptic_deeplab。2 核心数据结构InfoDict贯穿全流程的数据容器2.1 为什么需要InfoDictInfoDict是本工具包中承载预测结果、样本信息等数据的基础容器也是整个工具包最重要的数据结构——它在 PaddleSeg 主仓库中并不存在是 PanopticSeg 特有的设计。其类定义位于 paddlepanseg/cvlibs/info_dicts.py。从源码看InfoDict继承自collections.abc.MutableMapping内部用OrderedDict存储键值对因此它具备字典的全部行为取值、赋值、删除、迭代、求长度同时通过PRIMARY_KEYS类属性声明了该类型字典的主键集合构造时会用这些主键初始化占位class InfoDict(MutableMapping): PRIMARY_KEYS () _DICT_TYPE _Constant(OrderedDict) def __init__(self, *args, **kwargs): self._dict OrderedDict(zip(self.PRIMARY_KEYS, cycle([None]))) self.update(OrderedDict(*args, **kwargs))两个实用方法值得关注collect(keysNone, return_dictFalse)按主键列表批量取值可返回列表或OrderedDict便于把一组字段整体取出送入网络或评估器prune()剔除值为None的键用于在数据流转后清理未填充的占位字段。2.2 四种内置InfoDict类型工具包内置四种InfoDict子类分别对应数据处理管线中不同阶段的产物类型类名主键PRIMARY_KEYS设计用途SampleDictSampleDictimg、label、gt_fields、img_path、lab_path、ann、pan_label、sem_label、ins_label、trans_info、image_id承载数据样本及其元信息NetOutDictNetOutDictsem_out、ins_out、map_fields承载网络输出PPOutDictPPOutDictpan_pred、sem_pred、ins_pred承载后处理器输出MetricDictMetricDictpan_metrics、sem_metrics、ins_metrics承载Evaluator.evaluate()的评估结果后三个子类的行为可以在源码中找到印证SampleDict构造时会为gt_fields提供默认值[label, pan_label, sem_label, ins_label]并把trans_info初始化为空列表且它的__getitem__对gt_fields做了动态过滤——只返回当前实际存在非None的 ground-truth 字段使后续算子可以安全地遍历可用标签。NetOutDict的map_fields默认值为[sem_out]用于记录哪些输出是逐像素特征图需要在后续按空间维度处理。PPOutDict的主键pan_pred、sem_pred、ins_pred即后处理器产出的三路预测全景预测、语义预测与实例预测。2.3 工厂函数build_info_dict推荐通过工厂函数 build_info_dict 构造InfoDict对象传入_type_参数指定类型可选值为sample、net_out、pp_out、metric其余参数转发给对应构造函数def build_info_dict(_type_, *args, **kwargs): type_ _type_.lower() if type_ sample: dict_ SampleDict(*args, **kwargs) elif type_ net_out: dict_ NetOutDict(*args, **kwargs) if paddle.distributed.ParallelEnv().nranks 1: dict_ dict(dict_) elif type_ pp_out: dict_ PPOutDict(*args, **kwargs) elif type_ metric: dict_ MetricDict(*args, **kwargs) else: raise ValueError(f{_type_} is not a supported info dict type.) return dict_一个值得注意的细节当_type_为net_out且处于多卡训练环境nranks 1时工厂函数会把NetOutDict转换为普通字典再返回。从源码结构看这是为了兼容分布式训练下网络输出的收集与广播机制。一个典型的调用场景是数据集接口在读取样本时构造SampleDict后处理器在产出结果时构造PPOutDict见 base_pp.py实现数据形态在整条管线中的统一。3 全景分割标签编码协议pan_id的编解码规则全景分割标签无论是真值还是模型预测的每个像素值都是一个pan_id。编码协议的完整定义见 encoding_protocol_en.md下面给出可直接对照实现的完整规则。3.1 编码公式给定类别数c与最大实例数npan_id的取值范围为0到c * label_divisor n。具体规则分三类thing 类可数物体pan_id (cat_id 1) * label_divisor ins_id其中cat_id是类别 ID从0开始ins_id是实例 ID从1开始。stuff 类不可数背景pan_id (cat_id 1) * label_divisor即 stuff 类的pan_id恰好是该类编码基线的整数倍ins_id恒为0。未知标签pan_id等于0。label_divisor是预先定义的常量默认值为1000该默认值同时出现在 base_dataset.py 的类属性LABEL_DIVISOR 1000与 Panoptic-DeepLab 配置文件的锚点label_divisor: label_divisor 1000中。3.2 源码级实现encode.py编码协议在 paddlepanseg/utils/encode.py 中落地为三个工具函数_CAT_ID_OFFSET 1 def decode_pan_id(pan_id, label_divisor): return (pan_id // label_divisor) - _CAT_ID_OFFSET, pan_id % label_divisor def encode_pan_id(cat_id, label_divisor, ins_id0): return (cat_id _CAT_ID_OFFSET) * label_divisor ins_id def is_crowd(pan_id, label_divisor): return pan_id % label_divisor 0encode_pan_id与公式一一对应其中_CAT_ID_OFFSET 1正是公式中的1偏移用于为未知标签pan_id 0预留空间decode_pan_id返回(cat_id, ins_id)二元组is_crowd通过判断pan_id % label_divisor 0识别群体/拥挤crowd区域——即ins_id为0的 thing 类区域这类区域在实例级标注中通常被跳过。3.3 编码协议在数据管线中的实际应用以 transforms.py 中的DecodeLabels转换器为例它把 COCO 风格标注segments_info与原始pan_id标签解码为三路标签语义标签sem_label、实例标签ins_label、以及重新编码的全景标签pan_label。关键逻辑是对 thing 类实例按类别分别维护实例计数器class_id_tracker重编码时令ins_id class_id_tracker[cat_id]从而保证同一类别内实例编号连续对 stuff 类则直接encode_pan_id(cat_id, label_divisor)。解码完成后还会把segments_info中每段的id更新为新的pan_id确保后续算子使用的标注与标签图完全一致。训练阶段的目标生成器如generate_targets/panoptic_deeplab.py中的GeneratePanopticDeepLabTrainTargets同样依赖这套编码它遍历segments_info利用cat_id、iscrowd等信息生成语义图、实例中心热图高斯核sigma8与偏移图并据此构造中心/偏移分支的逐像素权重。这些转换器的完整参数如sigma、small_instance_area、small_instance_weight、ignore_stuff_in_offset都可在 Panoptic-DeepLab 配置文件的train_dataset.transforms中看到实际取值。4 数据集定制基于 COCO 格式接入新数据集4.1 推荐方案与整体步骤官方推荐的定制路径是把数据集整理成 MS COCO 格式并编写一个继承自paddlepanseg.datasets.base_dataset.COCOStylePanopticDataset的新数据集接口。通常包含以下步骤将数据集的元信息存为一个 dict 列表示例见 cityscapes.py 中的CITYSCAPES_CATEGORIES定义继承COCOStylePanopticDataset的 Python 类把类属性CATEGORY_META_INFO设为第一步定义的 dict 列表把类属性NUM_CLASSES设为类别数重写静态方法_get_image_id()它接收图像路径并返回该图像的唯一标识符用装饰器paddlepanseg.cvlibs.manager.DATASETS.add_component()注册新数据集类同样参考 cityscapes.py。4.2 元信息结构与 Cityscapes 参考实现每个类别条目是一个包含color、isthing、id、trainId、name五个字段的 dict。isthing取1表示 thing 类person、car、bicycle 等取0表示 stuff 类road、building、sky 等color为可视化 RGB 三元组id为数据集原始类别 IDtrainId为训练用类别 ID。Cityscapes 的 19 个类别中前 11 个是 stuff 类后 8 个是 thing 类CITYSCAPES_CATEGORIES中完整记录了这些元信息。作为对照base_dataset.py 中COCOStylePanopticDataset的基类实现揭示了这些元信息如何被使用_set_id_mapper()依据CATEGORY_META_INFO构建id→ 训练索引列表下标的正反双向映射convert_id_for_train/convert_id_for_eval分别用于训练与评估阶段的类别 ID 转换_get_num_classes()返回len(CATEGORY_META_INFO)即配置文件中未显式给出num_classes时会自动取类别数_get_thing_ids()收集所有isthing为真的类别索引作为后处理器的thing_idsthing 类 ID 集合用于区分可数物体与背景get_colormap()依据每类的color生成 256×3 的调色板供可视化使用。cityscapes.py中的注册写法是标准范式Cityscapes类设置CATEGORY_META_INFO CITYSCAPES_CATEGORIES与NUM_CLASSES len(CITYSCAPES_CATEGORIES)并以装饰器manager.DATASETS.add_component注册其_get_image_id取文件名中前三个下划线分段作为图像 ID对应 Cityscapes 的命名规范派生类CityscapesTrain则通过_create_cat_meta_with_train_id()把trainId提升为id供训练阶段使用。4.3 数据集配置接入以 Panoptic-DeepLab 为例新数据集注册后即可在模型配置文件的train_dataset/val_dataset段中引用。以 configs/panoptic_deeplab/panoptic_deeplab_resnet50_os32_cityscapes_1025x513_bs8_90k.yml 为参考训练数据集需给出type注册的组件名如CityscapesTrain/Cityscapesdataset_root、file_list数据集根目录与样本清单每行图像路径空格标签路径json_pathCOCO 风格全景标注 JSON含images与annotations两段每段均以image_id关联transforms数据变换链其中DecodeLabels需要label_divisor与ignore_index参数训练还需GeneratePanopticDeepLabTrainTargets生成监督目标Collect负责挑选送入网络的键顶层锚点label_divisor: label_divisor 1000、num_classes: num_classes 19、ignore_index: ignore_index 255通过 YAML 锚点贯穿数据集、后处理器与损失配置保证编码参数全局一致。从 base_dataset.py 的_read_sample_list()实现可以还原 COCO 标注的加载细节程序读取json_path将annotations按image_id建索引、images按id建索引逐行解析file_list调用_get_image_id()得到图像 ID 后查表拼接样本信息图像尺寸、segments_info并过滤掉category_id ignore_index的分段每个样本通过build_info_dict(_type_sample, ...)构造为SampleDict。此外PanopticDataset基类的collate()会把gt_fields、trans_info、image_id、ann等不参与批量拼接的键单独收集成列表其余字段走 Paddle 默认default_collate_fn——这是实现样本级标注随批次正确流转的关键机制。5 结语与延伸阅读本文覆盖了 PanopticSeg 工具包二次开发的四个核心主题以paddlepanseg/cvlibs为枢纽的模块化目录结构、以InfoDict为统一载体的数据流转形态、以pan_id编码协议为纽带的标签体系以及基于COCOStylePanopticDataset的数据集接入流程。若要进一步深入可继续阅读dev_guide_cn.md本文档的中文版encoding_protocol_cn.md编码协议中文版full_features_en.md工具包完整功能说明configs/panoptic_deeplab 与 configs/mask2former两个已支持模型的配置与说明paddlepanseg/utils/evaluation全景、语义、实例三路评估器实现。赞分享人工智能计算机视觉预训练【免费下载链接】PaddleSegEasy-to-use image segmentation library with awesome pre-trained model zoo, supporting wide-range of practical tasks in Semantic Segmentation, Interactive Segmentation, Panoptic Segmentation, Image Matting, 3D Segmentation, etc.项目地址https://gitcode.com/gh_mirrors/pa/PaddleSeg点击查看免费下载相关推荐零代码搞定图像分割数据集PaddleSeg数据生成工具全攻略零代码搞定图像分割数据集PaddleSeg数据生成工具全攻略 图像分割模型训练中高质量标注数据短缺是最棘手的问题。标注一张语义分割图像平均需要30分钟专业人工智能计算机视觉预训练FastSAM实战指南构建专属分割数据集全流程解析FastSAM实战指南构建专属分割数据集全流程解析 当你面对特定场景的图像分割需求时是否曾因缺乏合适的数据集而束手无策FastSAM为你提供了从零构建自定人工智能计算机视觉基础模型深度学习Oumi 数据集框架实战指南从预构建数据集到自定义数据集的全链路解析Oumi 数据集框架实战指南从预构建数据集到自定义数据集的全链路解析 Oumi OSS 提供了统一的 LLM 数据集框架覆盖从微小的自定义数据集到 Web人工智能大模型预训练微调强化学习模型推理服务模型评测MCP 服务分布式训练模型量化上一篇如何在5分钟内使用jquery-cropper实现图片裁剪功能下一篇Karmada karmadactl addons enable 命令详解从零启用 Karmada 可选组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考