Add model usage documentation

README.md

@@ -0,0 +1,184 @@
+---
+library_name: ultralytics
+tags:
+  - mahjong
+  - object-detection
+  - image-segmentation
+  - image-classification
+  - yolo
+  - resnet
+---
+
+# Mahjong models
+
+麻雀卓の領域分割、各領域内の牌検出、牌種分類を行うための学習済みモデルです。
+
+## ファイル
+
+| ファイル | 役割 | 出力 |
+| --- | --- | --- |
+| `regions-yolo-26n.pt` | 卓上画像から手牌・河・副露などの領域を抽出 | 15クラスのセグメンテーション |
+| `tile-yolo-26n.pt` | 領域画像から個々の牌面を抽出 | `tile` 1クラスのセグメンテーション |
+| `classifier-resnet50.pt` | 正規化した牌面画像の牌種を分類 | 38クラス |
+
+## ダウンロード
+
+Hugging Face CLIを使用する場合:
+
+```bash
+hf download HaseLab/mahjong-models --local-dir models
+```
+
+Pythonから取得する場合:
+
+```python
+from huggingface_hub import snapshot_download
+
+snapshot_download(
+    repo_id="HaseLab/mahjong-models",
+    local_dir="models",
+)
+```
+
+## 推奨パイプライン
+
+1. 元画像を`regions-yolo-26n.pt`へ入力し、卓上の各領域をセグメンテーションする。
+2. 領域の四隅を使って透視変換し、`1024 x 1024`の正方形画像にする。
+3. 正方形の領域画像を`tile-yolo-26n.pt`へ入力する。
+4. 検出された牌面ポリゴンを透視変換し、`224 x 224`の正方形画像にする。
+5. 正規化した牌面画像を`classifier-resnet50.pt`へ入力して牌種を分類する。
+
+牌分類器には、bboxで単純に切り出した画像ではなく、セグメンテーション結果から牌面を正方形へ透視補正した画像を入力することを推奨します。
+
+このリポジトリ内の評価パイプラインは次のように実行できます。
+
+```bash
+uv run python src/evaluation/grouping_yolo_pipeline.py \
+  --config configs/eval/grouping-yolo-26n-real-val-tiles-oof.toml
+```
+
+## YOLOモデルの読み込み
+
+```python
+from ultralytics import YOLO
+
+regions = YOLO("models/regions-yolo-26n.pt", task="segment")
+tiles = YOLO("models/tile-yolo-26n.pt", task="segment")
+
+region_results = regions.predict(
+    "input.jpg",
+    imgsz=(1152, 1536),
+    conf=0.25,
+    iou=0.50,
+)
+
+# tile-yoloには、region結果から作った1024 x 1024の領域画像を入力する
+tile_results = tiles.predict(
+    "region_crop.png",
+    imgsz=1024,
+    conf=0.25,
+    iou=0.50,
+)
+```
+
+領域モデルのクラスは次の15種類です。
+
+```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
+14 table_roi
+```
+
+## ResNet-50分類器の読み込み
+
+`classifier-resnet50.pt`は、38クラスのResNet-50の`state_dict`です。
+
+```python
+import torch
+from PIL import Image
+from torchvision.models import resnet50
+from torchvision.transforms import Compose, Normalize, Resize, ToTensor
+
+tile_codes = (
+    [f"{i}m" for i in range(10)]
+    + [f"{i}p" for i in range(10)]
+    + [f"{i}s" for i in range(10)]
+    + [f"{i}z" for i in range(8)]
+)
+
+# ImageFolderでの学習時と同じ辞書順。必ずこの順序を使用する。
+classes = sorted(tile_codes)
+
+model = resnet50(weights=None)
+model.fc = torch.nn.Linear(model.fc.in_features, len(classes))
+state_dict = torch.load(
+    "models/classifier-resnet50.pt",
+    map_location="cpu",
+    weights_only=True,
+)
+model.load_state_dict(state_dict)
+model.eval()
+
+preprocess = Compose(
+    [
+        Resize((224, 224)),
+        ToTensor(),
+        Normalize(
+            mean=[0.485, 0.456, 0.406],
+            std=[0.229, 0.224, 0.225],
+        ),
+    ]
+)
+
+image = Image.open("tile_crop.png").convert("RGB")
+x = preprocess(image).unsqueeze(0)
+
+with torch.inference_mode():
+    class_index = int(model(x).argmax(dim=1))
+
+print(classes[class_index])
+```
+
+### クラスindexの対応
+
+この分類器のindexは、牌コードを数牌・字牌の意味順に並べた順序ではなく、Pythonの`sorted()`による辞書順です。
+
+```text
+0m, 0p, 0s, 0z,
+1m, 1p, 1s, 1z,
+2m, 2p, 2s, 2z,
+3m, 3p, 3s, 3z,
+4m, 4p, 4s, 4z,
+5m, 5p, 5s, 5z,
+6m, 6p, 6s, 6z,
+7m, 7p, 7s, 7z,
+8m, 8p, 8s,
+9m, 9p, 9s
+```
+
+順序を変えると、同じ画像でも異なる牌コードへ対応付けられるため注意してください。また、この38クラス分類器には`back`クラスは含まれていません。
+
+## 推奨入力
+
+- 横長で、着座したプレイヤー側から麻雀卓を斜めに見下ろした画像
+- 領域モデル: 元画像
+- 牌検出モデル: 領域モデルから透視補正した正方形画像
+- 分類器: 牌検出モデルのポリゴンから透視補正したRGBの牌面画像
+
+## 関連リポジトリ
+
+実行コードと設定ファイル:
+
+https://github.com/HaseLab/mahjong-cg