README.md

# MaskRCNN（Mask Region-based Convolutional Neural Network）
## 模型介绍
MaskRCNN是一种基于Faster R-CNN的物体检测和实例分割模型，由Facebook AI Research团队在2017年提出。MaskRCNN不仅可以对图像中的物体进行检测，还可以对每个物体进行像素级别的分割，即得到每个物体的精确轮廓。

## 模型结构
MaskRCNN是一种基于Faster R-CNN的物体检测和实例分割模型，它通过使用RoI Align算法和Mask Head网络来实现像素级别的物体分割，并使用多任务损失函数来训练模型。该模型由以下几个组件组成：

1. Backbone网络
   Mask R-CNN的第一步是使用一个预训练的卷积神经网络（如ResNet）提取图像的特征。这些特征被称为“特征图”，可以用来检测图像中的物体和分割物体的像素。
2. Region Proposal Network (RPN)
   接下来，Mask R-CNN使用一个Region Proposal Network (RPN)来生成可能包含物体的区域。RPN是一个用于生成候选物体区域的神经网络，它在特征图上滑动一个小窗口，对每个窗口位置预测物体边界框的位置和该边界框包含物体的概率。
3. RoI Align
   在得到候选区域之后，Mask R-CNN使用RoI Align算法将每个候选区域映射到特征图上，并将映射后的特征图送入后续的全连接层中。RoI Align是一种可以保留特征图中精细位置信息的算法，可以提高物体检测和分割的精度。
4. Mask Head
   在RoI Align之后，Mask R-CNN使用一个称为“Mask Head”的神经网络来生成每个物体的精确分割掩码。Mask Head接收RoI Align层的输出，然后生成一个二进制掩码，表示每个像素是否属于该物体。
5. 损失函数
   最后，Mask R-CNN使用一个多任务损失函数来训练模型。该损失函数包括物体检测损失（用于预测物体的类别和边界框）、物体分割损失（用于生成物体的精确分割掩码）和RPN损失（用于生成候选物体区域）。这些损失函数同时优化，以提高模型的物体检测和分割性能。

## 目标精度

0.377 Box min AP and 0.339 Mask min AP

## MLPerf代码参考版本

版本：v0.7 

原始代码位置：https://github.com/mlcommons/training_results_v0.7/tree/master/NVIDIA/benchmarks/maskrcnn/implementations/pytorch

## 数据集

模型训练的数据集来自训练数据：Open Images，该数据一个大规模的图像数据集，由Google在2016年发布。该数据集包含了超过900万张标注图像，其中每张图像都包含了多个物体的边界框和类别标签，可用于各种计算机视觉任务，例如物体检测、物体识别、场景理解等。

下载+预处理数据可按照下述进行：

    #To download and verify the dataset use following scripts:
        cd dataset_scripts
        ./download_dataset.sh
        ./verify_dataset.sh
    
    #This should return `PASSED`.
    #To extract the dataset use:
        DATASET_DIR=<path/to/data/dir> ./extract_dataset.sh
    
    #Mask R-CNN uses pre-trained ResNet50 as a backbone.
    #To download and verify the RN50 weights use:
        DATASET_DIR=<path/to/data/dir> ./download_weights.sh
    #Make sure <path/to/data/dir> exists and is writable.
    
    #To speed up loading of coco annotations during training, the annotations can be pickled since #unpickling is faster than loading a json.
        python3 pickle_coco_annotations.py --root <path/to/detectron2/dataset/dir> --ann_file <path/to/coco/annotation/file> --pickle_output_file <path/to/pickled/output/file>
## 训练

### 环境配置
提供[光源](https://www.sourcefind.cn/#/service-details)拉取的训练的docker镜像：
* 训练镜像：

python依赖安装：

    pip3 install -r requirement.txt
    python3 setup.py install
    cd ./cocoapi-0.7.0/PythonAPI; python3 setup.py install

### 训练
训练命令（此处以单机8卡规模为例说明）：

    bash sbatch.sh #输出结果见log.txt
    注：可通过修改./maskrcnn_benchmark.bak/config/paths_catalog_dbcluster.py文件按需更改数据读取位置

## 性能和准确率数据
测试采用上述输入数据，加速卡采用Z100L，下面为单机8卡测试结果：

| 测试平台 | Accuacy |    Speed    |
| :------: | :-----: | :---------: |
|  Z100L   | 34% mAP | 0.9349 s/it |

## 历史版本
* https://developer.hpccube.com/codes/modelzoo/mlperf_maskrcnn
## 参考
* https://mlcommons.org/en/
* https://github.com/mlcommons