Detectron源码解读-roidb数据结构

柔情只为你懂 2022-05-14 16:46 191阅读 0赞

# roidb数据结构 #

roidb的类型是`list`, 其中的每个元素的数据类型都是`dict`, roidb列表的长度为数据集的数量(即图片的数量), roidb中每个元素的详细情况如下表所示:

<table> 
 <thead> 
  <tr> 
   <th><code>for entry in roidb</code></th> 
   <th>数据类型</th> 
   <th>详细说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td><code>entry['id']</code></td> 
   <td>int</td> 
   <td>代表了当前image的img_id</td> 
  </tr> 
  <tr> 
   <td><code>entry['file_name']</code></td> 
   <td>string</td> 
   <td>表示当前图片的文件名(带有.jpg后缀)</td> 
  </tr> 
  <tr> 
   <td><code>entry['dataset']</code></td> 
   <td>string</td> 
   <td>指明所属的数据集?</td> 
  </tr> 
  <tr> 
   <td><code>entry['image']</code></td> 
   <td>string</td> 
   <td>当前image的文件路径</td> 
  </tr> 
  <tr> 
   <td><code>entry['flipped']</code></td> 
   <td>bool</td> 
   <td>当前图片是否进行翻转</td> 
  </tr> 
  <tr> 
   <td><code>entry['height']</code></td> 
   <td>int</td> 
   <td>当前图片的高度</td> 
  </tr> 
  <tr> 
   <td><code>entry['width']</code></td> 
   <td>int</td> 
   <td>当前图片的宽度</td> 
  </tr> 
  <tr> 
   <td><code>entry['has_visible_keypoints']</code></td> 
   <td>bool</td> 
   <td>是否含有关键点</td> 
  </tr> 
  <tr> 
   <td><code>entry['boxes']</code></td> 
   <td>float32, numpy数组(num_objs, 4)</td> 
   <td>num_objs为当前图片中的目标物体个数, 4代表bbox的坐标</td> 
  </tr> 
  <tr> 
   <td><code>entry['segms']</code></td> 
   <td>二维列表[[],[],…]</td> 
   <td>列表中每个元素都还是一个列表, 其中存储着每个物体的ploygon实例标签</td> 
  </tr> 
  <tr> 
   <td><code>entry['gt_classes']</code></td> 
   <td>int32, numpy数组(num_objs)</td> 
   <td>指明当前图片中每一个obj的真实类别</td> 
  </tr> 
  <tr> 
   <td><code>entry['seg_areas']</code></td> 
   <td>float32, numpy数组(num_objs)</td> 
   <td>代表当前图片中每一个obj的掩膜面积</td> 
  </tr> 
  <tr> 
   <td><code>entry['gt_overlaps']</code></td> 
   <td>float32, scipy.sparse.csr_matrix数据(num_objs, 81)</td> 
   <td>代表每一个obj与81个不同类别的overlap</td> 
  </tr> 
  <tr> 
   <td><code>entry['is_crowd']</code></td> 
   <td>bool, numpy数组(num_objs)</td> 
   <td>代表当前掩膜是否为群落</td> 
  </tr> 
  <tr> 
   <td>entry[‘box_to_gt_ind_map’]</td> 
   <td>int32, numpy数组(num_objs)</td> 
   <td>该列表存储着box的顺序下标值, 同样是一维数组, 直接拼接,将每一个roi映射到一个index上, index是在entry[‘gt_classes’]&gt;0的rois列表的下标</td> 
  </tr> 
 </tbody> 
</table>

# `combined_roidb_for_training()` 方法 #

在目标检测类任务中, 有一个很重要的数据结构roidb, 它将作为基本的数据结构在数据队列中存在, Detectron 的数据载入类 `RoIDdataLoader` 也是将该数据结构作为成员变量使用的, 因此, 有必要对这个数据结构展开分析.

首先, 在运行训练脚本时, 就会调用到 `detectron/utils/train.py` 中的 `train()`函数, 而`train()`函数内部又会调用当前文件的`add_model_training_inputs()` 函数, 在这个函数内部, 就会调用到 `detectron/datasets/roidb` 文件中的 `combined_roidb_for_training()` 函数, 该函数的返回值正是`roidb`, 这是贯穿整个训练过程的训练数据, 故我们对此函数进行分析. 该函数代码解析如下:

# `get_roidb()` 方法 #

在上面的函数中我们可以发现, `combined_roidb_for_training`函数内部又定义了另一个函数`get_roidb()`, 而该函数主要是基于`detectron/datasets/json_dataset.py`中的`JsonDataset`类及该类的成员方法`get_roidb`实现的, 因此, 我们先跳到`json_dataset.py`文件中去看看这个类的内部实现是怎样的:

# detectron/datasets/json_dataset.py
    
    class JsonDataset(object):
        # 这个类的设计主要是基于COCO的json格式数据集
        # 当我们需要训练自己的数据集时, 最好的方式就是将自己的数据集的格式改为
        # COCO数据集的json格式, 这样一来, 我们就无需重写数据载入代码了.
        def __init__(self, name):
            assert dataset_catalog.contains(name), \
                "Unknown dataset name: {}".format(name)
            assert...
            #...
    
            # 准备数据集的类别信息
            category_ids = self.COCO.getCatIds() # 1~80, 对应80个类
            # coco的loadCats函数, 必须指定需要加载的cat的id, 否则返回空列表
            # 若指定后, 则返回id对应的类别信息, 每个类别信息是一个字典, 包括'name','id','supercategory'三个字段
            # 获取每个类的名字, person, bicycle,bus等等, 返回的名字在列表中的位置与id在cat_ids列表中的位置一致
            categories = [c['name'] for c in sefl.COCO.loadCats(category_ids)]
            # 建立类别的name 与 id之间的对应关系, 其中cat_name为key,cat_id为值
            self.category_to_id_map = dict(zip(categories, category_ids)) # 注意, 没有'__background__'
            self.classes = ['__background__'] + categories # 将'__background__'添加到categories类别名字列表中
            self.num_classes = len(self.classes)
            # coco下标最大值为90,但实际上只有80个类, 有的地方跳过了, 因此id不是连续的,
            self.json_category_id_to_contiguous_id = { 
                v: i + 1 # key为coco的非连续id, value为1~80的连续id, 均为整数
                for i, v in enumerate(self.COCO.getCatIds())
            }
            self.contiguous_category_id_to_json_id = { 
                v: k # key为1~80的连续id, value为coco的非连续id, 均为整数
                for k, v in self.json_category_id_to_contiguous_id.items()
            }
            self._init_keypoints() # 调用类内的keypoints初始化方法.
    
        def get_roidb(
            self,
            gt=False,
            proposal_file=None,
            min_proposal_size=2,
            proposal_limit=-1,
            crowd_filter_thresh=0
        ):
            """ 返回json dataset对应的roidb数据, 提供以下四种选项: - 在roidb中包含gt boxes - 添加位于proposal file里面的特定proposals - 基于最短边长的proposals过滤器 - 基于群落区域交集的proposals过滤器 """
    
            assert gt is True or crowd_filter_thresh == 0, \
                "Crowd filter threshold must be 0 if gt " \
                "annotations are not included."
            # 这里调用了COCO的官方API, 关于COCO数据集的结构和标注格式解析, 可以查看我的另一篇文章
            # 没有指定筛选条件, 获取数据集标签中所有的图片id
            image_ids = self.COCO.getImgIds()
            image_ids.sort() # 将id按照从小到大的顺序排列
            # roidb为列表结构, 列表中的每一项是一个字典, 代表着对应imageid的标签内容.
            # 键值包括:coco_url, license, width, filename, height, flickr_url, id, date_captured
            roidb = copy.deepcopy(self.COCO.loadImgs(image_ids))
            for entry in roidb:
                # 调用了本类的私有函数 _prep_roidb_entry(), entry为字典.
                # 主要是为entry赋初值, 占位符等等, 包含box, segms,等各种字段, 详细信息可以看下面的函数解析
                # 注意, 这里的字段值都是预测值相关的值, 因此也会局域gt_overlap等字段
                self._prep_roidb_entry(entry)
            if gt:
                # 如果参数声明是gt信息, 则会调用_add_gt_annotations
                # 访问标注文件, 以便添加相关字段信息, 具体看下面的相关函数解析
                self.debug_timer.tic()
                for entry in roidb:
                    # 注意, 是单独对每个entry调用该函数, 因此每次会载入指定imgid的相关标签
                    # 关于_add_gt_annotations函数具体解析可以看后面的部分
                    self._add_gt_annotations(entry)
                logger.debug(
                    '_add_gt_annotations took {:.3f}s'.
                    format(self.debug_timer.toc(average=False))
                )
            if proposal_file is not None:
                self.debug_timer.tic()
                # 加载proposals文件到roidb中, 关于此函数的详细解析可以看后文
                self._add_proposals_from_file(
                    roidb, proposal_file, min_proposal_size, proposal_limit,
                    crowd_filter_thresh
                )
                logger.debug(
                    '_add_proposals_from_file took {:.3f}s'.
                    format(self.debug_timer.toc(average=False))
                )
            # 类外部的函数, 用于计算与每个roidb相关的box的类别
            _add_class_assignments(roidb)
            return roidb

# `_prep_roidb_entry()` 方法 #

数据准备函数 `_prep_roidb_entry()` 的实现解析

# detectron/datasets/json_dataset.py
    
    class JsonDataset(object):
        def __init__(...):
            #...
        def get_roidb(...):
            #...
        # 该函数主要将空的元数据添加到roidb entry中
        def _prep_roidb_entry(self, entry):
            # entry的'dataset'关键字, 值为self.
            entry['dataset'] = self
            im_path = os.path.join(self.image_directory, self.image_prefix+entry['file_name'])
            assert os.path.exists(im_path), "Image \"{} \" not found".format(im_path)
            # entry的'image'关键字, 值为当前imageid对应的image路径
            entry['image'] = im_path
            entry['flipped'] = False # 禁止反转
            entry['has_visible_keypoints'] = False
    
            # 下面entry键的对应值均为空, 暂为占位键
    
            # entry的'boxes'关键字,值为n×4的numpy数组, n代表box的数量,这里暂时为0
            entry['boxes'] = np.empty((0,4), dtype=np.float32)
            entry['segms'] = [] # entry的'segms'关键字, 值为一个列表,暂时为空
            # entry的'gt_classes'关键字, 是个一维数组, 维度与box的数量n对应,暂时为0
            entry['gt_classes'] = np.empty((0), dtype=np.int32)
            # 代表掩膜的面积, 供n项, 与boxes数目相对
            entry['seg_areas'] = np.empty((0), dtype=np.float32)
            # TODO, 这里是一个矩阵压缩, 矩阵大小为n×c, c为类别数量, 没太搞懂要压缩成什么?
            entry['gt_overlaps'] = scipy.sparse.csr_matrix(
                np.empty((0, self.num_classes), dtype=np.float32)
            )
            # 同样是n行1列, n与boxes数目对应, 表示是否为`一群物体`
            entry['is_crowd'] = np.empty((0), dtype=np.bool)
            # shape大小与roi相关, 将每一个roi映射到一个index上
            # index是在entry['gt_classes']>0的rois列表的下标 TODO还是不太清楚映射关系
            entry['box_to_gt_ind_map'] = np.empty((0), dtype=np.int32)
            # 关键点信息, 默认情况下不设置
            if self.keypoints is not None:
                entry['gt_keypoints'] = np.empty(
                    (0, 3, self.num_keypoints), dtype=np.int32
                )
            # 删除那些从json file中获取到的不需要的字段
            for k in ['date_captured', 'url', 'license', 'file_name']:
                if k in entry:
                    del entry[k]

# `_add_gt_annotations()` 方法 #

加载标注文件的函数 `_add_gt_annotations()`的实现解析

# detectron/datasets/json_dataset.py
    
    class JsonDataset(object):
        def __init__(...):
            #...
        def get_roidb(...):
            #...
        def _prep_roidb_entry(self, entry):
            #...
        # 该函数将标注文件的元数据添加到roidb entry中
        def _add_gt_annotations(self, entry):
            # 获取指定imgid的annid列表 (对应多个box)
            ann_ids = self.COCO.getAnnIds(imgIds=entry['id'], iscrowd=None)
            # 根据annids的id列表, 获取这些id对应的标注信息, objs是一个列表
            # 列表中的每一个元素都是一个字典,字典的内容是标注文件中的内容,包含bbox,segmentation等字段
            objs = self.COCO.loadAnns(ann_ids)
            # 下面的代码会对bboxes进行清洗, 因为有些是无效的数据
            valid_objs=[] # 存储有效的objs
            valid_segms=[] # 存储有效的segms
            width = entry['width'] # 获取entry中的width字段, 代表图片的宽度
            height = entry['height'] # 获取entry中的height字段, 代表图片的高度
            for obj in objs:
                # crowd区域采用RLE编码
                # import detectron.utils.segms as segm_utils
                # 用于判断当前的segmentation是polygon编码还是rle编码, 前者是列表类型, 后者是字典类型
                # 返回True为polygon编码, 返回Fasle为rle编码
                if segm_utils.is_poly(obj['segmentation']):
                    # poly编码必须含有>=3个点才能组成一个多边形, 因此需要>=6个坐标点
                    # 类似于这样的检查操作只在PLOYGON中存在, 在面对RLE时无需检查, 可以直接接受后面的检查
                    obj['segmentation'] = [
                        p for p in obj['segmentation'] if len(p) >=6
                    ]
                if obj['area'] < cfg.TRAIN.GT_MIN_AREA:
                    continue # 如果面积不达标, 则认为该标注无效, 不将其加入valid列表
                if 'ignore' in obj and obj['ignore'] == 1:
                    continue
                # import detectron.utils.boxes as box_utils
                # 将[x1,y1,w,h]的边框格式转换成[x1,y1,x2,y2]的格式
                x1, y1, x2, y2 = box_utils.xywh_to_xyxy(obj['bbox'])
                # 将[x1,y1,x2,y2]的边框坐标限制在图片的[width,height]范围内, 防止越界
                x1, y1, x2, y2 = box_utils.clip_xyxy_to_image(
                    x1, y1, x2, y2, height, width
                )
    
                if obj['area'] > 0 and x2 > x1 and y2 > y1: # 若数据有效, 则加入到列表当中
                    obj['clean_bbox'] = [x1, y1, x2, y2]
                    valid_objs.append(obj)
                    valid_segms.append(obj['segmentation']) # 将数据的segms存在列表中(RLE/PLOYGON)
            num_valid_objs = len(valid_objs) # num_valid_objs持有objs的有效个数
    
            # 注意, 下面的数据内容都被初始化为0
            # boxes为 有效objs数×4 的numpy数组, 用来表示每个objs的边框坐标
            boxes = np.zeros((num_valid_objs,4), dtype=entry['seg_areas'].dtype)
            # 每个objs的真实类别
            gt_classes = np.zeros((num_valid_objs), dtype=entry['gt_classes'].dtype)
            gt_overlaps = np.zeros( # 形状为 有效objs数×num_class数 的numpy数组, 表示与每个类的IoU大小
                (num_valid_objs, self.num_classes),
                dtype=entry['gt_overlaps'].dtype
            )
            # 掩膜面积
            seg_areas = np.zeros((num_valid_objs), dtype=entry['seg_areas'].dtype)
            # 是否crowd
            is_crowd = np.zeros((num_valid_objs), dtype=entry['is_crowd'].dtype)
            # 这个是???
            box_to_gt_ind_map = np.zeros(
                (num_valid_objs), dtype=entry['box_to_gt_ind_map'].dtype
            )
            if self.keypoints is not None:
                gt_keypoints = np.zeros(
                    (num_valid_objs, 3, self.num_keypoints),
                    dtype=entry['gt_keypoints'].dtype
                )
    
            # 图片是否有可视的关键点?
            im_has_visible_keypoints = False
            for ix, obj in enumerate(valid_objs):# ix为下标, obj为下标对应元素
                # category_id为coco类别id,json_category_id_to_contiguous_id 为字典类型
                # 其中, key为coco的非连续id, value为1~80的连续id, 均为整数, 所以这里是将coco的非连续id转换成对应的连续id
                cls = self.json_category_id_to_contiguous_id[obj['category_id']]
                boxes[ix, :] = obj['clean_box'] # 将当前obj的box填入boxes列表
                gt_classes[ix] = cls # 将连续id填入gt_classes列表
                seg_areas[ix] = obj['area'] # 将area填入seg_areas列表
                is_crowd[ix] = obj['iscrowd']
                box_to_gt_ind_map[ix] = ix # 该列表存储着box的顺序下标值
                if self.keypoints is not None:
                    # ...
                if obj['iscrowd']:
                    # 如果当前物体是crowd的话, 则将所有类别的overlap都设置为-1,
                    # 这样一来在训练的时候, 这些物体都会被排除在外!!
                    gt_overlaps[ix, :] = -1.0
                else:
                    gt_overlaps[ix, cls] = 1.0  # 仅仅将对应类的overlap设置为1, 其他为0
            # 将gt的boxes添加到entry中, 注意axis为0, 则会按照第0维拼接, 即最后是一个n×4的数组
            # 注意, entry['boxes']初始时候是空的, 因此这就相当于是只添加了真实的框
            entry['boxes'] = np.append(entry['boxes'], boxes, axis=0)
            # 由于segms是以列表形式存储, 所以利用列表的extend方法来将valid_segms添加到其中
            entry['segms'].extend(valid_segms)  
            # gt_classes的类型内一维numpy数组(维度为有效obj的数量), 因此这里不用指定axis的值, 直接按照一维数组拼接即可
            entry['gt_classes'] = np.append(entry['gt_classes'], gt_classes)
            # 同理, 一维numpy数组(维度为有效obj的数量), 无须指定axis的值
            entry['seg_areas'] = np.append(entry['seg_areas'], seg_areas)
            # gt_overlaps为 num_objs × num_classes的numpy数组, 表示每个obj与任意一个类的重叠度
            # 因为entry['gt_overlaps']的类型为scipy.sparse.csr.csr_matrix, 因此这里需要调用toarray方法将其转换成numpy数组, 然后再与gt_overlaps拼接,
            #由于entry['gt_overlaps']的维度为 0 × 81 , 因此拼接后的维度为num_objs × num_classes的numpy数组
            entry['gt_overlaps'] = np.append(
                entry['gt_overlaps'].toarray(), gt_overlaps, axis=0
            )
            # 再将其包装成scipy.sparse.csr.csr_matrix类型
            entry['gt_overlaps'] = scipy.sparse.csr_matrix(entry['gt_overlaps'])
            # 一维numpy数组, 可直接拼接
            entry['is_crowd'] = np.append(entry['is_crowd'], is_crowd)
            # 该列表存储着box的顺序下标值, 同样是一维数组, 直接拼接
            entry['box_to_gt_ind_map'] = np.append(
                entry['box_to_gt_ind_map'], box_to_gt_ind_map
            )
            if self.keypoints is not None:
                entry['gt_keypoints'] = np.append(
                    entry['gt_keypoints'], gt_keypoints, axis=0
                )
                entry['has_visible_keypoints'] = im_has_visible_keypoints

# `_add_proposals_from_file()` #

# detectron/datasets/json_dataset.py
    
    class JsonDataset(object):
        def __init__(...):
            #...
        def get_roidb(...):
            #...
        def _prep_roidb_entry(self, entry):
            #...
        def _add_gt_annotations(self, entry):
            #...
        #
        def _add_proposals_from_file(
            self, roidb, proposal_file, min_proposal_size, top_k, crowd_thresh
        ):

# 续解`combined_roidb_for_training()` 方法 #

接下来, 重新回到刚才`detectron/datasets/roidb.py` 文件 的 `combined_roidb_for_training` 函数中, 继续往下看:

# detectron/datasets/roidb.py
    
    # 加载并连接一个或多个数据集的roidbs, along with optional object proposals
    # 每个roidb entry都带有特定的元数据类型, 对其进行准备工作后进行训练
    def combined_roidb_for_training(dataset_names, proposal_files):
        def get_roidb(dataset_name, proposal_file): # 注意没有 's'
            # from detectron.datasets.json_dataset import JsonDataset
            # 可以看到, roidb 是利用JsonDataset类对象的get_roidb()方法获取的
            # 注意gt参数是True, 所以表明加载的是训练集的真实数据及其标签
            ds = JsonDataset(dataset_name)
            roidb = ds.get_roidb(
                gt=True,
                proposal_file=proposal_file,
                crowd_filter_thresh=cfg.TRAIN.CROWD_FILTER_THRESH
            )
            # 如果图片翻转属性为真, 则对加载好以后的数据集进行翻转操作
            if cfg.TRAIN.USE_FLIPPED:
                logger.info("Appending horizontally-flipped training examples...")
                extend_with_flipped_entries(roidb, ds)
            logger.info("Loaded dataset: {:s}".format(ds.name))
            # 以上, 数据集加载操作完成, 将roidb数据结构返回
            return roidb
        if isinstance(dataset_names, basestring):
            dataset_names=(dataset_names, )
        if isinstance(proposal_files, basestring):
            proposal_files = (proposal_files, )
        if len(proposal_files) == 0:
            proposal_files = (None, ) * len(dataset_names)
        assert len(dataset_names) == len(proposal_files)
        roidbs = [get_roidb(*args) for args in zip(dataset_names, proposal_files)]
        roidb = roidbs[0]
        for r in roidbs[1:]:
            roidb.extend(r)
        roidb = filter_for_training(roidb)
    
        logger.info("Computing bounding-box regression targets...")
        # 为训练bounding-box 回归其添加必要的information
        add_bbox_regression_targets(roidb)
        logger.info("done")
        _compute_and_log_stats(roidb)
    
        return roidb