train different datasets in a single main.py. Add TRAINING recipes.

Author: bearpaw

.gitignore

@@ -3,7 +3,6 @@ checkpoint
 dev
 *.pth.tar
 data/mpii/images
-!data/mpii/mean.pth.tar
 *.json
 *debug*
 *.idea/*
@@ -17,6 +16,7 @@ data/mscoco/images
 miscs/posetrack
 miscs/h36m
 data/h36m
+!mean.pth.tar
 
 __pycache__/
 *.py[cod]

README.md

@@ -1,5 +1,7 @@
 # PyTorch-Pose
 
+![screenshot](./docs/screenshot.png)
+
 PyTorch-Pose is a PyTorch implementation of the general pipeline for 2D single human pose estimation. The aim is to provide the interface of the training/inference/evaluation, and the dataloader with various data augmentation options for the most popular human pose databases (e.g., [the MPII human pose](http://human-pose.mpi-inf.mpg.de), [LSP](http://www.comp.leeds.ac.uk/mat4saj/lsp.html) and [FLIC](http://bensapp.github.io/flic-dataset.html)).
 
 Some codes for data preparation and augmentation are brought from the [Stacked hourglass network](https://github.com/anewell/pose-hg-train). Thanks to the original author.
@@ -37,12 +39,14 @@ Some codes for data preparation and augmentation are brought from the [Stacked h
 
 ## Usage
 
+**Please refer to [TRAINING.md](TRAINING.md) for detailed training recipes!**
+
 ### Testing
 You may download our pretrained models (e.g., [2-stack hourglass model](https://drive.google.com/drive/folders/0B63t5HSgY4SQQ2FBRE5rQ2EzbjQ?usp=sharing)) for a quick start.
 
 Run the following command in terminal to evaluate the model on MPII validation split (The train/val split is from [Tompson et al. CVPR 2015](http://www.cims.nyu.edu/~tompson/data/mpii_valid_pred.zip)).
 ```
-CUDA_VISIBLE_DEVICES=0 python example/mpii.py -a hg --stacks 2 --blocks 1 --checkpoint checkpoint/mpii/hg_s2_b1 --resume checkpoint/mpii/hg_s2_b1/model_best.pth.tar -e -d
+CUDA_VISIBLE_DEVICES=0 python example/main.py --dataset mpii -a hg --stacks 2 --blocks 1 --checkpoint checkpoint/mpii/hg_s2_b1 --resume checkpoint/mpii/hg_s2_b1/model_best.pth.tar -e -d
 ```
 * `-a` specifies a network architecture
 * `--resume` will load the weight from a specific model
@@ -77,21 +81,18 @@ You may also evaluate the result by running `python evaluation/eval_PCKh.py` to
 ### Training
 Run the following command in terminal to train an 8-stack of hourglass network on the MPII human pose dataset.
 ```
-CUDA_VISIBLE_DEVICES=0 python example/mpii.py -a hg --stacks 8 --blocks 1 --checkpoint checkpoint/mpii/hg8 -j 4
+CUDA_VISIBLE_DEVICES=0 python example/main.py --dataset mpii -a hg --stacks 8 --blocks 1 --checkpoint checkpoint/mpii/hg8 -j 4
 ```
 Here,
 * `CUDA_VISIBLE_DEVICES=0` identifies the GPU devices you want to use. For example, use `CUDA_VISIBLE_DEVICES=0,1` if you want to use two GPUs with ID `0` and `1`.
 * `-j` specifies how many workers you want to use for data loading.
 * `--checkpoint` specifies where you want to save the models, the log and the predictions to.
 
-Please refer to the `example/mpii.py` for the supported options/arguments.
-
-## To Do List
+## Miscs
 Supported dataset
 - [x] [MPII human pose](http://human-pose.mpi-inf.mpg.de)
 - [x] [Leeds Sports Pose (LSP)](http://sam.johnson.io/research/lsp.html)
 - [x] [MSCOCO (single person)](http://cocodataset.org/#keypoints-challenge2017)
-- [ ] FLIC
 
 Supported models
 - [x] [Stacked Hourglass networks](https://arxiv.org/abs/1603.06937)

TRAINING.md

@@ -0,0 +1,125 @@
+# Training Recipe
+
+## Get datasets
+
+### MPII Human Pose Dataset
+
+- Download the [dataset](https://datasets.d2.mpi-inf.mpg.de/andriluka14cvpr/mpii_human_pose_v1.tar.gz) and create a link to the `images` directory at `./data/mpii/
+images`
+  ```
+  ln -s ${MPII_PATH}/images ./data/mpii/images
+  ```
+
+- Download the [annotation file](https://drive.google.com/open?id=1mQrH_yVHeB93rzCfyq5kC9ZYTwZeMsMm) in our JSON format, and save it to `./data/mpii/mpii_annotations.json`
+
+- You are good to go!
+
+
+### COCO Keypoints 2014/2017
+
+- Download datasets:
+  ```
+  cd ./data/mscoco
+  wget http://images.cocodataset.org/zips/train2014.zip
+  wget http://images.cocodataset.org/zips/val2014.zip
+  wget http://images.cocodataset.org/zips/train2017.zip
+  wget http://images.cocodataset.org/zips/val2017.zip
+  unzip train2014.zip -d images
+  unzip train2014.zip -d images
+  unzip train2014.zip -d images
+  unzip train2014.zip -d images
+  rm -rf *.zip
+  ```
+
+- You are good to go!
+
+### Leeds Sports Pose (LSP)
+- Download datasets:
+  ```
+  mkdir -p ./data/lsp/images
+  cd ./data/lsp/images
+  wget http://sam.johnson.io/research/lsp_dataset.zip
+  wget http://sam.johnson.io/research/lspet_dataset.zip
+  unzip lsp_dataset.zip -d lsp_dataset
+  unzip lspet_dataset.zip -d lspet_dataset
+  ```
+- You are good to go!
+
+## Training
+- Example 1: Train from scratch - ECCV'16 8-stack hourglass network
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mpii \
+--arch hg \
+--stack 8 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mpii/hg-s8-b1
+```
+
+- Example 2: Train a much faster version of HG (e.g., 1-stack)
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mpii \
+--arch hg \
+--stack 1 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mpii/hg-s1-b1
+```
+
+- Example 3: Train on COCO 2014/2017 (set `--year` argument )
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mscoco \
+--year 2017 \
+--arch hg \
+--stack 1 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mscoco/hg-s1-b1
+```
+
+- Example 4: resume training from a checkpoint
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mpii \
+--arch hg \
+--stack 8 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mpii/hg-s8-b1 \
+--resume ./checkpoint/mpii/hg-s8-b1/checkpoint.pth.tar
+```
+
+
+- **Evaluation** from an existing model: use `-e`
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mpii \
+--arch hg \
+--stack 8 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mpii/hg-s8-b1 \
+--resume ./checkpoint/mpii/hg-s8-b1/checkpoint.pth.tar \
+-e
+```
+
+- **Debug**: Use `-d` if you want to visualize the keypoints with images
+```
+CUDA_VISIBLE_DEVICES=0 python ./example/main.py \
+--dataset mpii \
+--arch hg \
+--stack 1 \
+--block 1 \
+--features 256 \
+--checkpoint ./checkpoint/mpii/hg-s1-b1 \
+--resume ./checkpoint/mpii/hg-s1-b1/checkpoint.pth.tar \
+-e \
+-d
+```
+
+The visualized images should be like
+
+![screenshot](./docs/screenshot.png)