PolygonRNN++

这是Polygon-RNN++（CVPR 2018）的官方 PyTorch 重实现。该仓库允许您训练新的 Polygon-RNN++ 模型，并在本地机器上运行我们的演示工具。有关技术细节，请参阅：

使用 Polygon-RNN++ 高效交互式标注分割数据集
David Acuna*, Huan Ling*, Amlan Kar*, Sanja Fidler (* 表示共同第一作者)
CVPR 2018
[论文] [视频] [项目页面] [演示]

代码在哪里？

要获取代码，请在此处 注册。我们将使用 GitHub 来跟踪代码中的问题，并更新新版本的可用性（也可在网站上查看，并通过电子邮件通知已注册用户）。

如果您使用此代码，请引用：

@inproceedings{AcunaCVPR18,
title={Efficient Interactive Annotation of Segmentation Datasets with Polygon-RNN++},
author={David Acuna and Huan Ling and Amlan Kar and Sanja Fidler},
booktitle={CVPR},
year={2018}
}

@inproceedings{CastrejonCVPR17,
title = {Annotating Object Instances with a Polygon-RNN},
author = {Lluis Castrejon and Kaustav Kundu and Raquel Urtasun and Sanja Fidler},
booktitle = {CVPR},
year = {2017}
}

目录

1. 复现结果
2. 环境设置
3. 工具
   1. 后端
   2. 前端
4. 测试模型
5. 训练模型
   1. 数据
   2. 训练 MLE 模型
   3. 训练 RL 模型
   4. 训练评估器
   5. 训练 GGNN

结果

以下是本仓库与论文中结果的复现对比

训练类型	初始点数	LSTM 束宽	之前	现在
MLE + Att	1	1	65.43	66.35
MLE + Att + RL	1	1	67.17	67.45
MLE + Att + 评估器	5	1	69.72	71.05
MLE + Att + 评估器	5	8	70.21	70.91
MLE + Att + 评估器 + GGNN	5	8	71.38	72.05
MLE + Att + 评估器 + GGNN	5	1	-	72.08
MLE + Att + 评估器 + GGNN（共享编码器）	5	8	-	72.22
MLE + Att + 评估器 + GGNN（共享编码器）	5	1	-	72.33

注： 工具的前向传播速度基准测试（初始5个点，束宽为1）在 TitanXp 上为每次交互0.3秒。

注： 共享编码器是指在图网络和 convLSTM 网络之间共享 Resnet。而在原始论文中，这两个网络是分开的。

环境设置

所有代码均已在 Ubuntu 16.04、Python 2.7.12、Pytorch 0.4.0、CUDA 9.0、TITAN X/Xp 和 GTX 1080Ti GPU 上运行并测试过。

• 在 注册 后获取代码
• 进入下载的代码目录

cd <path_to_downloaded_directory>

• 设置 Python 环境

virtualenv env
source env/bin/activate
pip install -r requirements.txt

• 将项目添加到 PYTHONPATH

export PYTHONPATH=$PWD

工具

• 按照 环境设置 准备好您的环境
• 在 注册 获得访问权限后，下载 MLE+RL+评估器+GGNN 模型

后端

• 使用以下命令启动后端（flask 服务器）：

python Tool/tool.py --exp Experiments/tool.json --reload <path_to_model> --port <port> --image_dir Tool/frontend/static/img/

前端

• 编辑 Tool/frontend/static/js/polygon.js，将 globalFolder 改为与您克隆仓库位置相对应的目录。
• 使用 python2.7，运行

cd Tool/frontend/
python -m SimpleHTTPServer

• 在浏览器中访问 localhost:8000。您应该会看到如下页面：

注： 如果您使用的是 Python 3 作为服务器，则需将 SimpleHTTPServer 替换为 http.server。

注： 您可以通过编辑 Tool/frontend/static/js/polygon.js 并将路径传递给 Tool/tool.py 来设置您自己的图像目录。该图像目录必须包含 Tool/frontend/index.html 中定义的预设图像。

测试模型

• 按照 环境设置 准备好您的环境
• 在 注册 获得访问权限后，下载预训练模型。

python Scripts/prediction/generate_annotation.py --exp <path_to_corresponding_experiment> --reload <path_to_checkpoint> --output_dir <path_to_store_predictions>

• 如果您正在测试 RL 检查点，则实验文件应对应 RL 实验文件，其他阶段的模型也是如此。
• 您可以在 output_dir 中检查每个实例的预测掩码和真实标签掩码。
• 要获取分数，运行

python Scripts/get_scores.py --pred <path_to_preds> --output <path_to_file_to_save_results>

训练模型

数据

Cityscapes

• 从官方网站 下载 Cityscapes 数据集（leftImg8bit_trainvaltest.zip）[11 GB]
• 我们的处理后的标注文件包含在您注册后获得的下载文件中。
• 从根目录运行以下命令，使用适当的路径准备标注文件以供您的机器使用：

python Scripts/data/change_paths.py --city_dir <path_to_downloaded_leftImg8bit_folder> --json_dir <path_to_downloaded_annotation_file> --out_dir <output_dir>

自定义数据集

要在您的自定义数据集上进行训练，您有两种选择：

• 准备类似于我们标注文件的标注数据，并使用我们的默认 DataProvider
• 根据 Cityscapes 的实现方式，为您的数据实现自己的 DataProvider

训练

• 按照 环境设置 准备好您的环境
• 从 这里 下载预训练的 PyTorch Resnet-50
• 注意 - 继续训练时，务必从 epoch 结束的检查点开始恢复，以确保结果可重复！

训练 MLE 模型

• 编辑 Experiments/mle.json 中的实验文件，更改适用于您机器的路径。
• 从根目录运行

python Scripts/train/train_ce.py --exp Experiments/mle.json --resume <optional_if_resuming_training>

• 您可以在 TensorBoard 上查看训练进度（日志位于 /logs/）。

训练强化学习模型

• 编辑 Experiments/rl.json 中的实验配置文件，并根据你的机器修改路径。
• 在实验配置文件中，将 xe_initializer 设置为最佳的最大似然估计（MLE）模型。
• 从根目录运行：

python Scripts/train/train_rl.py --exp Experiments/rl.json --resume <可选，若要恢复训练>

• 注意：你可能需要调整一些超参数以实现稳定的训练，尤其是温度、学习率和学习率衰减。

训练评估器

• 编辑 Experiments/evaluator.json 中的实验配置文件，并根据你的机器修改路径。
• 在实验配置文件中，将 xe_initializer 设置为最佳的强化学习模型。
• 从根目录运行：

python Scripts/train/train_evaluator.py --exp Experiments/evaluator.json --resume <可选，若要恢复训练>

训练 GGNN

• 编辑 Experiments/ggnn.json 中的实验配置文件，并根据你的机器修改路径。
• 在实验配置文件中，将 xe_initializer 设置为最佳的评估器模型。
• 从根目录运行：

python Scripts/train/train_ggnn.py --exp Experiments/ggnn.json --resume <可选，若要恢复训练>

Polyrnn-pp-pytorch 快速上手指南

PolygonRNN++ 是一个用于高效交互式图像分割标注的深度学习模型（CVPR 2018）。本指南基于官方 PyTorch 复现版本，帮助开发者快速搭建环境并运行演示工具。

注意：源代码和预训练模型需要先在官方页面注册获取下载权限。

环境准备

本项目已在以下环境中测试通过，建议尽量匹配该配置以避免兼容性问题：

• 操作系统: Ubuntu 16.04
• Python: 2.7.12 (前端服务需注意 Python 版本差异)
• 深度学习框架: PyTorch 0.4.0
• CUDA: 9.0
• GPU: TITAN X/Xp 或 GTX 1080Ti

前置依赖：

• virtualenv (用于创建隔离环境)
• git (用于克隆代码，若已手动下载可忽略)

安装步骤

1. 获取代码与数据

注册并下载代码包后，解压并进入目录：

cd <path_to_downloaded_directory>

2. 配置 Python 环境

创建虚拟环境并安装依赖：

virtualenv env
source env/bin/activate
pip install -r requirements.txt

(注：国内用户可使用 -i https://pypi.tuna.tsinghua.edu.cn/simple 加速 pip 安装)

3. 设置环境变量

将项目路径加入 PYTHONPATH：

export PYTHONPATH=$PWD

4. 下载预训练模型

从注册后获得的链接中下载完整的 MLE+RL+Evaluator+GGNN 模型文件，并记录其路径，后续启动工具时需要用到。

基本使用

本部分介绍如何启动官方的交互式标注演示工具（包含后端服务和前端页面）。

1. 启动后端服务

运行 Flask 服务器加载模型。请替换 <path_to_model> 为你的模型文件路径，<port> 为指定端口（如 5000）：

python Tool/tool.py --exp Experiments/tool.json --reload <path_to_model> --port <port> --image_dir Tool/frontend/static/img/

2. 配置前端

编辑前端配置文件 Tool/frontend/static/js/polygon.js，将 globalFolder 变量修改为你当前代码仓库的绝对路径。

3. 启动前端服务器

进入前端目录并启动简易 HTTP 服务器：

cd Tool/frontend/
python -m SimpleHTTPServer

(注：如果你使用的是 Python 3，请将命令改为 python -m http.server)

4. 访问界面

打开浏览器访问 http://localhost:8000，即可看到交互式标注界面。你可以上传图片（需预先放置在指定的 image_dir 中）并体验模型自动勾勒多边形轮廓的功能。