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 为什么需要InfoDict

InfoDict是本工具包中承载预测结果、样本信息等数据的基础容器，也是整个工具包最重要的数据结构——它在 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(keys=None, return_dict=False)：按主键列表批量取值，可返回列表或OrderedDict，便于把一组字段整体取出送入网络或评估器；
• prune()：剔除值为None的键，用于在数据流转后清理未填充的占位字段。

2.2 四种内置InfoDict类型

工具包内置四种InfoDict子类，分别对应数据处理管线中不同阶段的产物：

后三个子类的行为可以在源码中找到印证：

• 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与最大实例数n，pan_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_id=0): return (cat_id + _CAT_ID_OFFSET) * label_divisor + ins_id def is_crowd(pan_id, label_divisor): return pan_id % label_divisor == 0

• encode_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等信息生成语义图、实例中心热图（高斯核，sigma=8）与偏移图，并据此构造中心/偏移分支的逐像素权重。这些转换器的完整参数（如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的新数据集接口。通常包含以下步骤：

1. 将数据集的元信息存为一个 dict 列表（示例见 cityscapes.py 中的CITYSCAPES_CATEGORIES）；
2. 定义继承COCOStylePanopticDataset的 Python 类，把类属性CATEGORY_META_INFO设为第一步定义的 dict 列表，把类属性NUM_CLASSES设为类别数；
3. 重写静态方法_get_image_id()，它接收图像路径并返回该图像的唯一标识符；
4. 用装饰器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为数据集原始类别 ID，trainId为训练用类别 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_ids（thing 类 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/Cityscapes）；
• dataset_root、file_list：数据集根目录与样本清单（每行图像路径<空格>标签路径）；
• json_path：COCO 风格全景标注 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：全景、语义、实例三路评估器实现。

• 人工智能
• 计算机视觉
• 预训练