[TOC]

# 簡介
此份程式修改自 [mmpose 0.x](https://github.com/open-mmlab/mmpose/tree/0.x)，為論文 **透過選擇性特徵整合與跨層閘控增強基於 HRNet 的人體姿態估計** 所使用之程式碼，使用於單階段人體姿態辨識使用。
:::warning
:warning: 請注意，使用版本為 0.x 版本的 mmpose ，最新的 1.x 版本 mmpose 的寫法及用法與本程式不同！
:::

# mmpose 安裝
請先確保 cuda 及 cudnn 等正常安裝，在按照 [mmpose 官方安裝指南 (0.x 版本)](https://github.com/open-mmlab/mmpose/blob/0.x/docs/en/install.md) 進行安裝。

:::info
務必記得，使用 0.x 版本的 mmpose，若點進了 main branch (如下圖)

請注意以下步驟，再進行後續安裝：

git clone https://github.com/open-mmlab/mmpose.git
git checkout 0.x

:::

# 資料夾結構
在此針對幾個較重要的資料夾進行介紹：

mmpose
├── configs # 模型的定義檔，為訓練/驗證/測試模型的重要依據
├── data # 屆時用於放置資料集的區域
├── demo
├── docker
├── docs
├── mmpose # mmpose 主函式庫，針對 head/backbone 等調整都必須在此作調整。
├── mmpose.egg-info
├── model-index.yml
├── pytest.ini
├── requirements
├── requirements.txt
├── resources
├── setup.cfg
├── setup.py
├── tests
├── tools # 重要工具區，訓練/驗證/測試模型的腳本都在這裡
├── work_dirs # 訓練的記錄存放區

# 訓練
## 資料集處理
本程式所使用的資料集為 crowdpose 資料集，其簡介可參考 [mmpose 對其簡介](https://mmpose.readthedocs.io/en/latest/dataset_zoo/2d_body_keypoint.html)， mmpose 所使用的 annotation 有經 mmpose 稍微調整，故需要下載 mmpose 使用版本：

- 資料集圖片： [連結](https://github.com/Jeff-sjtu/CrowdPose)
- 資料集 annotation ：　[連結](https://download.openmmlab.com/mmpose/datasets/crowdpose_annotations.tar)

請下載後並且解壓縮到 `data` 資料夾，使其結構如下：

mmpose
├── mmpose
├── docs
├── tests
├── tools
├── configs
`── data
    │── crowdpose
        │-- annotations
        │   │-- mmpose_crowdpose_train.json
        │   │-- mmpose_crowdpose_val.json
        │   │-- mmpose_crowdpose_trainval.json
        │   │-- mmpose_crowdpose_test.json
        │   │-- det_for_crowd_test_0.1_0.5.json
        │-- images
            │-- 100000.jpg
            │-- 100001.jpg
            │-- 100002.jpg
            │-- ...

## 修改所需部分
此部分將介紹如果需要做實驗更動，需要執行的手續， 訓練所使用的 config 檔案通常放在：

### head 修改
head 相關設定會放在 `mmpose/models/heads` 中，使用習慣是建立一個新的 `head.py` ，因此會在此資料夾看到許多個 `head.py`，每當建立好新的 head ，必須要在 head 資料夾下的 `__init__.py` 引入 head 的函式，並且在最後的模型定義 config 修改來使用，以下方為例：

1. 建立新的 `head.py` 並且定義 class。
2. 修改 `__init__.py`，修改處有二，如下:

3. 修改 config 檔案
`hrnet_w32_split_crowdpose_512x512_withCLGDwasp_heatmap2branch_wahr_new_concat_clg.py` 為例，修改為對應的 class

### loss 修改
請至需要的 config 檔案中，找到以下，並且修改成想要的 loss 函式:

### 超參數及訓練設定修改
請至需要的 config 檔案中，找到以下，並且修改對應所需的超參數及訓練設定
1. optimizer
2. 學習率調整策略
3. 訓練 epoches
4. 資料集相關讀取設定
自上而下，依序講解：
1. 一張 GPU 使用多少 CPU 核心 (worker) 進行圖片讀取等處理
2. 可以理解為 batch_size ，由於我用了 4 張 GPU ，所以 batch_size 為 $8\times4=32$
3. 請務必記得修改成自己要使用的資料集的 type
4. 請修改成資料集之**訓練集** annotation 的路徑
5. 圖片的前綴，也就是資料集圖片資料夾的路徑
6. 請修改成資料集之**驗證集** annotation 的路徑
7. 請修改成資料集之**測試集** annotation 的路徑
(由於 crowdpose 沒有特別切 test，就沒有另外獨立進去)

## 訓練指令執行
這裡使用 mmpose 內附的 `dist_train.sh` 進行訓練，此腳本能夠實現多 GPU 訓練，指令參考如下:

./tools/dist_train.sh <定義 config>　<使用 GPU 數量>

請於 mmpose 資料夾下執行，操作範例為使用 4 張 GPU 進行訓練，如下：

./tools/dist_train.sh configs/joey/2d_kpt_sview_rgb_img/testing/crowdpose/hrnet_w32_split_crowdpose_512x512_withCLGDwasp_heatmap2branch_vanilla.py 4

其對應訓練結果會產出在 `work_dirs/hrnet_w32_split_crowdpose_512x512_withCLGDwasp_heatmap2branch_vanilla` 資料夾下 (對應 config 檔案名稱) 。

# 驗證與評估
這裡使用 mmpose 內附的 `dist_test.sh` 進行驗證與評估，此腳本能夠實現多 GPU 評估，指令參考如下:

./tools/dist_test.sh <定義 config> <模型 .pth> <使用 GPU 數量>

請於 mmpose 資料夾下執行，操作範例為使用 4 張 GPU 進行評估，如下：

./tools/dist_test.sh configs/body/2d_kpt_sview_rgb_img/dekr/crowdpose/hrnet_w32_crowdpose_512x512.py \
    work_dirs/hrnet_w32_crowdpose_512x512/best_AP_epoch_280.pth 4

執行成功後，產出結果畫面如下(DEKR 為範例)：

# Inference 結果圖片產出(Demo)
這裡使用 mmpose 內附的 `bottom_up_img_demo.py` 進行 inference 結果產生，藉此我們讀取訓練好的模型及其定義 config，對於 `img-path` 內的圖片進行推論，並將推論結果產到 `out-img-root`

python demo/bottom_up_img_demo.py <定義 config> <模型 .pth> \
        --img-path <輸入資料夾路徑> --out-img-root <輸出資料夾路徑>

請於 mmpose 資料夾下執行，操作範例如下：

python demo/bottom_up_img_demo.py \
    configs/body/2d_kpt_sview_rgb_img/dekr/crowdpose/hrnet_w32_crowdpose_512x512.py \
    work_dirs/hrnet_w32_crowdpose_512x512/best_AP_epoch_280.pth \
    --img-path data/crowdpose/images/ \
    --out-img-root dekr_vis_results

# 供驗證之模型及訓練 log 檔
連結為壓縮檔，內有訓練好的 .pth 檔供驗證及測試使用，也可以看當時訓練的 log 檔。
[連結](https://drive.google.com/file/d/1SlE2Mscdr6pkFdSJ9Ue0uXWEl0p4CwjP/view?usp=sharing)

最佳版本訓練指令如下:

./tools/dist_train.sh \
    configs/joey/2d_kpt_sview_rgb_img/testing/crowdpose/hrnet_w32_split_crowdpose_512x512_withCLGDwasp_heatmap2branch_wahr_new_concat_clg.py 4