改訂モデルスタック報告 — YOLOX-Nano + mahjong_huge + ONNX Runtime Web

1. エグゼクティブサマリ

1.1 1 行サマリ (帰属表示用)

検出モデル: YOLOX-Nano (Copyright (c) 2021-2022 Megvii Inc., Apache License 2.0)
学習データ: mahjong_huge / Riichi Mahjong Detection by riichimahjongdetection (CC BY 4.0)
改変: 2 つのデータセットを統合、アノテーション形式を YOLO から COCO に変換、
      クラス体系を日本リーチ麻雀標準 37 クラスに統一。本データセットを用いて検出モデルを学習。
牌画像: riichi-mahjong-tiles by Martin Persson (CC BY 4.0)
改変: SVG を 120×160 PNG にエクスポートして使用。
推論ランタイム: ONNX Runtime Web (Microsoft, MIT License)

2. 新スタック構成 (4 レイヤー)

3. YOLOX-Nano 詳細

3.1 仕様

3.2 YOLOv8 (Ultralytics, AGPL-3.0) との比較

3.3 訓練コマンド (実行例)

# 1. リポジトリ取得
git clone https://github.com/Megvii-BaseDetection/YOLOX.git
cd YOLOX
pip install -r requirements.txt
pip install -v -e .

# 2. データセットを COCO 形式に配置 (詳細は次セクション)
# datasets/mahjong/
# ├── annotations/
# │   ├── train.json
# │   └── val.json
# ├── train/  # 画像ファイル
# └── val/

# 3. exp ファイルを用意 (exps/example/mahjong_nano.py)
# 内容: depth=0.33, width=0.25, num_classes=37, data_dir="datasets/mahjong"

# 4. 訓練
python tools/train.py -f exps/example/mahjong_nano.py -d 1 -b 64 --fp16

# 5. ONNX エクスポート
python tools/export_onnx.py \
    --output-name yolox_nano_mahjong.onnx \
    -f exps/example/mahjong_nano.py \
    -c YOLOX_outputs/mahjong_nano/best_ckpt.pth

4. mahjong_huge / Riichi Mahjong Detection データセット

4.1 データセット情報

4.2 改変方針 (本プロジェクト用)

• 2 つのデータセット (Japanese Riichi + Chinese Mahjong から日本牌を抽出) を統合
• アノテーション形式を YOLO 形式から COCO JSON 形式に変換 (YOLOX 標準が COCO)
• クラス体系を日本リーチ麻雀標準 37 クラスに統一
• 本プロジェクトで抽出した M-League フレーム (実物 201 枚) を追加
• 合成データ 5,000 枚を追加 (Section 5 参照)

4.3 想定データ規模

5. FluffyStuff/riichi-mahjong-tiles SVG 素材

5.1 素材情報

5.2 合成データ生成への組込

現状の scripts/generate-synthetic-mahjong.py は procedural モード (白枠 + 中央文字) で動作中。 FluffyStuff SVG を 120×160 PNG にエクスポートして synth/tiles/ に配置すると、 本物相当のタイル絵柄で訓練データを生成できる。

5.3 SVG → PNG エクスポートコマンド

# Inkscape CLI で一括エクスポート (Windows)
$tiles = Get-ChildItem "riichi-mahjong-tiles/Regular/*.svg"
foreach ($svg in $tiles) {
    $png = "synth/tiles/$($svg.BaseName).png"
    inkscape --export-type=png --export-width=120 --export-height=160 --export-filename=$png $svg.FullName
}

# または Python (cairosvg)
import cairosvg
import os
for svg in os.listdir("riichi-mahjong-tiles/Regular/"):
    cairosvg.svg2png(
        url=f"riichi-mahjong-tiles/Regular/{svg}",
        write_to=f"synth/tiles/{svg.replace('.svg', '.png')}",
        output_width=120, output_height=160,
    )

5.4 既存 procedural 素材との比較

6. ONNX Runtime Web ランタイム

6.1 仕様

6.2 ブラウザ内推論の利点

• サーバーレス: 推論コストゼロ (ユーザーの CPU/GPU で動作)
• プライバシー: 画像がサーバーに送られない (麻雀対局の私的データ保護)
• オフライン動作: ネット切断時も継続
• 低遅延: ネットワーク往復ゼロ (50-100ms 削減)
• スケール無制限: 100 ユーザー / 10,000 ユーザーでもサーバー費ゼロ

6.3 統合コード例 (TypeScript)

// docs-site/live-demo.html で動作させるコード骨格
import * as ort from "onnxruntime-web";

async function loadModel() {
    const session = await ort.InferenceSession.create(
        "/models/yolox_nano_mahjong.onnx",
        { executionProviders: ["wasm"] }
    );
    return session;
}

async function detect(session: ort.InferenceSession, imageData: ImageData) {
    // 1. 前処理 (416x416 リサイズ + 正規化)
    const tensor = preprocess(imageData);
    // 2. 推論
    const results = await session.run({ images: tensor });
    // 3. 後処理 (NMS, デコード)
    return postprocess(results.output);
}

6.4 Cloudflare Pages との相性

本プロジェクトはすでに mahjong-scorekeeping-docs.pages.dev を Cloudflare Pages で公開中。 ONNX Runtime Web は 静的ファイル (.onnx) として配信できる ので、 Pages にモデルをアップロードするだけで 無料でブラウザデモが公開可能:

docs-site/
├── index.html
├── live-demo.html          # 新規: ブラウザ推論デモ
└── models/
    └── yolox_nano_mahjong.onnx  # 約 3-5 MB

7. 旧スタック (YOLOv8 + Roboflow) との比較

7.1 全レイヤー比較表

7.2 ライセンス互換性マトリクス

8. 移行ステップ + 想定工数

8.1 移行 Phase 計画

8.2 移行リスク

9. クレジット表記 (CC BY 4.0 帰属表示)

本スタックを商用製品に組み込む際の必須クレジット表記:

9.1 表記場所

• 製品の About 画面 / Settings 画面
• クラウドファンディング Makuake 本ページ「使用 OSS 一覧」セクション
• Web デモ (live-demo.html) のフッター
• リポジトリ Root の LICENSE.txt または NOTICE.txt