README.md

---
library_name: ultralytics
tags:
  - mahjong
  - object-detection
  - image-segmentation
  - image-classification
  - yolo
  - resnet
---

# Mahjong models

麻雀卓の領域分割、各領域内の牌検出、牌種分類を行うための学習済みモデルです。

## ファイル

| ファイル | 役割 | 出力 |
| --- | --- | --- |
| `regions-yolo-26n.pt` | 卓上画像から手牌・河・副露などの領域を抽出 | 14クラスのセグメンテーション |
| `tile-yolo-26n.pt` | 領域画像から個々の牌面を抽出 | `tile` 1クラスのセグメンテーション |
| `classifier-resnet50.pt` | 正規化した牌面画像の牌種・裏向きを分類 | 39クラス |

## Git submoduleとして使用する

Git Xetをインストールしてから、親リポジトリの`models/`へsubmoduleとして追加します。

```bash
git xet install
git xet --version

git submodule add \
  https://huggingface.co/HaseLab/mahjong-models \
  models

git add .gitmodules models
git commit -m "Add model artifacts as submodule"
```

submoduleはモデルリポジトリの特定コミットを参照します。Hugging Face側のモデルを更新しても、親リポジトリ側でsubmoduleの参照を更新してcommitするまでは、既存の利用者が取得するモデルは変わりません。

## 推奨パイプライン

### 推論の流れ

```text
入力画像
  │
  ▼
Region YOLO
  regions-yolo-26n.pt
  手牌・河・副露などの領域をセグメンテーション
  │
  ▼
Tile YOLO
  tile-yolo-26n.pt
  Region YOLOの検出領域をそのまま入力し、
  領域内にある個々の牌面をセグメンテーション
  │
  ▼
牌面を正方形化
  検出ポリゴンの四隅から透視変換
  出力: 224 × 224 RGB
  │
  ▼
ResNet-50
  classifier-resnet50.pt
  正規化した牌面から38牌種または裏向きを分類
  │
  ▼
予測結果
  例: 5m(5萬)
```

## クラス

### Region YOLO

`regions-yolo-26n.pt`のクラスは次の14種類です。

```text
 0  self_hand  自分の手牌
 1  discard_0  自分の河
 2  discard_1  右家の河
 3  discard_2  対面の河
 4  discard_3  左家の河
 5  meld_0     自分の副露
 6  meld_1     右家の副露
 7  meld_2     対面の副露
 8  meld_3     左家の副露
 9  dora       ドラ表示牌
10  riichi_0   自分のリーチ棒
11  riichi_1   右家のリーチ棒
12  riichi_2   対面のリーチ棒
13  riichi_3   左家のリーチ棒
```

家番号は、カメラ側の自分を`0`、右家を`1`、対面を`2`、左家を`3`とします。

### Tile YOLO

`tile-yolo-26n.pt`は牌種を区別せず、すべての牌面を1クラスとして検出します。

```text
0  tile  牌面
```

牌種は後段のResNet-50で分類します。

### ResNet-50

再学習した`classifier-resnet50.pt`は、38牌種と`back`を合わせた次の39クラスを出力します。
indexはImageFolderのクラス名を`sorted()`した辞書順です。必ず次の順序を使用してください。

```text
 0  0m  赤5萬
 1  0p  赤5筒
 2  0s  赤5索
 3  0z  赤白
 4  1m  1萬
 5  1p  1筒
 6  1s  1索
 7  1z  東
 8  2m  2萬
 9  2p  2筒
10  2s  2索
11  2z  南
12  3m  3萬
13  3p  3筒
14  3s  3索
15  3z  西
16  4m  4萬
17  4p  4筒
18  4s  4索
19  4z  北
20  5m  5萬
21  5p  5筒
22  5s  5索
23  5z  白
24  6m  6萬
25  6p  6筒
26  6s  6索
27  6z  發
28  7m  7萬
29  7p  7筒
30  7s  7索
31  7z  中
32  8m  8萬
33  8p  8筒
34  8s  8索
35  9m  9萬
36  9p  9筒
37  9s  9索
38  back  裏向き
```