# 数据模块 ## 介绍 本模块是一个Python模块，用于加载数据并将其转换成适用于检测模型的训练、验证、测试所需要的格式——由多个np.ndarray组成的tuple数组，例如用于Faster R-CNN模型的训练数据格式为：`[(im, im_info, im_id, gt_bbox, gt_class, is_crowd), (...)]`。 ### 实现 该模块内部可分为4个子功能：数据解析、图片预处理、数据转换和数据获取接口。 我们采用`data.Dataset`表示一份数据，比如`COCO`数据包含3份数据，分别用于训练、验证和测试。原始数据存储与文件中，通过`data.source`加载到内存，然后使用`data.transform`对数据进行处理转换，最终通过`data.Reader`的接口可以获得用于训练、验证和测试的batch数据。 子功能介绍： 1. 数据解析 数据解析得到的是`data.Dataset`,实现逻辑位于`data.source`中。通过它可以实现解析不同格式的数据集，已支持的数据源包括： - COCO数据源 该数据集目前分为COCO2014和COCO2017，主要由json文件和image文件组成，其组织结构如下所示： ``` dataset/coco/ ├── annotations │ ├── instances_train2014.json │ ├── instances_train2017.json │ ├── instances_val2014.json │ ├── instances_val2017.json │ | ... ├── train2017 │ ├── 000000000009.jpg │ ├── 000000580008.jpg │ | ... ├── val2017 │ ├── 000000000139.jpg │ ├── 000000000285.jpg │ | ... | ... ``` - Pascal VOC数据源 该数据集目前分为VOC2007和VOC2012，主要由xml文件和image文件组成，其组织结构如下所示： ``` dataset/voc/ ├── train.txt ├── val.txt ├── test.txt ├── label_list.txt (optional) ├── VOCdevkit/VOC2007 │ ├── Annotations │ ├── 001789.xml │ | ... │ ├── JPEGImages │ ├── 001789.xml │ | ... │ ├── ImageSets │ | ... ├── VOCdevkit/VOC2012 │ ├── Annotations │ ├── 003876.xml │ | ... │ ├── JPEGImages │ ├── 003876.xml │ | ... │ ├── ImageSets │ | ... | ... ``` **说明：** 如果你在yaml配置文件中设置`use_default_label=False`, 将从`label_list.txt` 中读取类别列表，反之则可以没有`label_list.txt`文件，检测库会使用Pascal VOC数据集的默 认类别列表，默认类别列表定义在[voc\_loader.py](../ppdet/data/source/voc_loader.py) - Roidb数据源 该数据集主要由COCO数据集和Pascal VOC数据集转换而成的pickle文件，包含一个dict，而dict中只包含一个命名为‘records’的list（可能还有一个命名为‘cname2cid’的字典），其内容如下所示： ```python (records, catname2clsid) 'records'是一个list并且它的结构如下: { 'im_file': im_fname, # 图像文件名 'im_id': im_id, # 图像id 'h': im_h, # 图像高度 'w': im_w, # 图像宽度 'is_crowd': is_crowd, # 是否重叠 'gt_class': gt_class, # 真实框类别 'gt_bbox': gt_bbox, # 真实框坐标 'gt_poly': gt_poly, # 多边形坐标 } 'cname2id'是一个dict，保存了类别名到id的映射 ``` 我们在`./tools/`中提供了一个生成roidb数据集的代码，可以通过下面命令实现该功能。 ``` # --type: 原始数据集的类别（只能是xml或者json） # --annotation: 一个包含所需标注文件名的文件的路径 # --save-dir: 保存路径 # --samples: sample的个数（默认是-1，代表使用所有sample） python ./ppdet/data/tools/generate_data_for_training.py --type=json \ --annotation=./annotations/instances_val2017.json \ --save-dir=./roidb \ --samples=-1 ``` 2. 图片预处理 图片预处理通过包括图片解码、缩放、裁剪等操作，我们采用`data.transform.operator`算子的方式来统一实现，这样能方便扩展。此外，多个算子还可以组合形成复杂的处理流程, 并被`data.transformer`中的转换器使用，比如多线程完成一个复杂的预处理流程。 3. 数据转换器 数据转换器的功能是完成对某个`data.Dataset`进行转换处理，从而得到一个新的`data.Dataset`。我们采用装饰器模式实现各种不同的`data.transform.transformer`。比如用于多进程预处理的`dataset.transform.paralle_map`转换器。 4. 数据获取接口 为方便训练时的数据获取，我们将多个`data.Dataset`组合在一起构成一个`data.Reader`为用户提供数据，用户只需要调用`Reader.[train|eval|infer]`即可获得对应的数据流。`Reader`支持yaml文件配置数据地址、预处理过程、加速方式等。 ### APIs 主要的APIs如下： 1. 数据解析 - `source/coco_loader.py`：用于解析COCO数据集。[详见代码](../ppdet/data/source/coco_loader.py) - `source/voc_loader.py`：用于解析Pascal VOC数据集。[详见代码](../ppdet/data/source/voc_loader.py) [注意]在使用VOC数据集时，若不使用默认的label列表，则需要先使用`tools/generate_data_for_training.py`生成`label_list.txt`（使用方式与数据解析中的roidb数据集获取过程一致），或提供`label_list.txt`放置于`data/pascalvoc/ImageSets/Main`中；同时在配置文件中设置参数`use_default_label`为`true`。 - `source/loader.py`：用于解析Roidb数据集。[详见代码](../ppdet/data/source/loader.py) 2. 算子 `transform/operators.py`：包含多种数据增强方式，主要包括： ``` python RandomFlipImage：水平翻转。 RandomDistort：随机扰动图片亮度、对比度、饱和度和色相。 ResizeImage：根据特定的插值方式调整图像大小。 RandomInterpImage：使用随机的插值方式调整图像大小。 CropImage：根据缩放比例、长宽比例两个参数生成若干候选框，再依据这些候选框和标注框的面积交并比(IoU)挑选出符合要求的裁剪结果。 ExpandImage：将原始图片放进一张使用像素均值填充(随后会在减均值操作中减掉)的扩张图中，再对此图进行裁剪、缩放和翻转。 DecodeImage：以RGB格式读取图像。 Permute：对图像的通道进行排列并转为BGR格式。 NormalizeImage：对图像像素值进行归一化。 NormalizeBox：对bounding box进行归一化。 MixupImage：按比例叠加两张图像。 ``` [注意]：Mixup的操作可参考[论文](https://arxiv.org/pdf/1710.09412.pdf)。 `transform/arrange_sample.py`：实现对输入网络数据的排序。 3. 转换 `transform/post_map.py`：用于完成批数据的预处理操作，其主要包括： ``` python 随机调整批数据的图像大小 多尺度调整图像大小 padding操作 ``` `transform/transformer.py`：用于过滤无用的数据，并返回批数据。 `transform/parallel_map.py`：用于实现加速。 4. 读取 `reader.py`：用于组合source和transformer操作，根据`max_iter`返回batch数据。 `data_feed.py`: 用于配置 `reader.py`中所需的默认参数. ### 使用 #### 常规使用 结合yaml文件中的配置信息，完成本模块的功能。yaml文件的使用可以参见配置文件部分。 - 读取用于训练的数据 ``` python ccfg = load_cfg('./config.yml') coco = Reader(ccfg.DATA, ccfg.TRANSFORM, maxiter=-1) ``` #### 如何使用自定义数据集？ - 选择1：将数据集转换为COCO格式。 ``` # 在./tools/中提供了x2coco.py用于将labelme标注的数据集或cityscape数据集转换为COCO数据集 python ./ppdet/data/tools/x2coco.py --dataset_type labelme --json_input_dir ./labelme_annos/ --image_input_dir ./labelme_imgs/ --output_dir ./cocome/ --train_proportion 0.8 --val_proportion 0.2 --test_proportion 0.0 # --dataset_type：需要转换的数据格式，目前支持：’labelme‘和’cityscape‘ # --json_input_dir：使用labelme标注的json文件所在文件夹 # --image_input_dir：图像文件所在文件夹 # --output_dir：转换后的COCO格式数据集存放位置 # --train_proportion：标注数据中用于train的比例 # --val_proportion：标注数据中用于validation的比例 # --test_proportion: 标注数据中用于infer的比例 ``` - 选择2： 1. 仿照`./source/coco_loader.py`和`./source/voc_loader.py`，添加`./source/XX_loader.py`并实现`load`函数。 2. 在`./source/loader.py`的`load`函数中添加使用`./source/XX_loader.py`的入口。 3. 修改`./source/__init__.py`： ```python if data_cf['type'] in ['VOCSource', 'COCOSource', 'RoiDbSource']: source_type = 'RoiDbSource' # 将上述代码替换为如下代码： if data_cf['type'] in ['VOCSource', 'COCOSource', 'RoiDbSource', 'XXSource']: source_type = 'RoiDbSource' ``` 4. 在配置文件中修改`dataset`下的`type`为`XXSource`。 #### 如何增加数据预处理？ - 若增加单张图像的增强预处理，可在`transform/operators.py`中参考每个类的代码，新建一个类来实现新的数据增强；同时在配置文件中增加该预处理。 - 若增加单个batch的图像预处理，可在`transform/post_map.py`中参考`build_post_map`中每个函数的代码，新建一个内部函数来实现新的批数据预处理；同时在配置文件中增加该预处理。