卓上マスキング前処理 統合ガイド — 既存検出スクリプトへの組み込み手順

1. 統合対象スクリプト一覧

1.1 統合対象外

• scripts/extract-roboflow-frames.py — フレーム抽出のみで検出しないため対象外
• scripts/filter-roboflow-frames.py — quality filtering のみ
• scripts/generate-image.mjs — 画像生成系で別ドメイン

2. --use-table-mask フラグの追加方法

2.1 共通パターン (argparse 拡張)

import argparse

parser = argparse.ArgumentParser()
# 既存引数...
parser.add_argument("--in-image", required=True)
parser.add_argument("--out-image", default=None)

# 新規: 卓マスキング前処理
parser.add_argument("--use-table-mask", action="store_true",
                    help="卓上領域マスキング前処理を有効化 (FP 削減)")
parser.add_argument("--mask-dilate-pct", type=float, default=5.0,
                    help="凸包の dilate 比率 (%) [default: 5.0]")
parser.add_argument("--mask-min-area-pct", type=float, default=5.0,
                    help="卓と判定する最小面積比率 (%) [default: 5.0]")
parser.add_argument("--mask-debug-out", default=None,
                    help="マスクデバッグ画像の出力パス (4 分割)")

args = parser.parse_args()

2.2 import 例

# scripts/mask-table-region.py から再利用可能関数を import
import sys
from pathlib import Path
sys.path.insert(0, str(Path(__file__).parent))

from mask_table_region import (
    table_region_mask,   # マスク生成
    apply_mask,          # マスク適用
    save_debug_grid,     # デバッグ画像 (4 分割) 保存
)

2.3 統合の最小コード (3 行差し込み)

# 既存: フレーム読み込み → YOLO 推論
frame = cv2.imread(args.in_image)
detections = model.predict(frame, confidence=0.40)

# 統合版: マスク前処理を挟む
frame = cv2.imread(args.in_image)
if args.use_table_mask:                                                # 1
    mask, info = table_region_mask(                                    # 2
        frame,
        dilate_pct=args.mask_dilate_pct,
        min_area_pct=args.mask_min_area_pct,
    )
    if not info["fallback"]:                                           # 3
        frame = apply_mask(frame, mask)
    if args.mask_debug_out:
        save_debug_grid(frame, mask, info, args.mask_debug_out)
detections = model.predict(frame, confidence=0.40)

2.4 ユースケース別 CLI 例

# 1. detect-agari-visual.py に統合後
python scripts/detect-agari-visual.py \
    --video mleague/sample01.mp4 \
    --start-frame 1800 --end-frame 2400 \
    --use-table-mask \
    --mask-debug-out mleague/output/_agari-mask-debug.png

# 2. analyze-still-frame.py に統合後
python scripts/analyze-still-frame.py \
    --in-image mleague/frames/sample01-peak.jpg \
    --use-table-mask

# 3. 評価フレームワーク
python scripts/evaluate-agari-transition-detector.py \
    --eval-dir mleague/eval/ \
    --use-table-mask \
    --report-out mleague/eval/report-with-mask.json

3. フォールバック処理 (卓検出失敗時)

3.1 フォールバック判定ロジック

def table_region_mask(frame, dilate_pct=5.0, min_area_pct=5.0):
    h, w = frame.shape[:2]
    total_area = h * w
    # ... HSV → connectedComponents ...
    if largest_area_pct < min_area_pct:
        return None, {"fallback": True, "reason": "no_table_detected",
                      "largest_area_pct": largest_area_pct}
    # ... 凸包 + dilate ...
    return mask, {"fallback": False, "table_area_pct": table_pct, ...}

3.2 フォールバック発生パターン

3.3 フォールバック発生率の監視

評価フレーム群全体に対する fallback 発生率を 5% 以下に保つことを目標とする。 それ以上なら HSV 範囲 / min_area_pct を見直す必要がある。

# 監視用ログ収集
fallback_count = 0
for frame in test_frames:
    _, info = table_region_mask(frame)
    if info["fallback"]:
        fallback_count += 1
print(f"fallback rate: {fallback_count / len(test_frames) * 100:.1f}%")

4. パイプライン順序 (マスキング → YOLO → 後処理)

[入力動画フレーム]
       │
       ▼
[1. 卓マスキング前処理]    ← 本ガイドの主題
       │   (fallback 時は素通し)
       ▼
[2. YOLO 推論 (公開モデル / MVP)]
       │   - 34 牌種 bbox + 信頼度
       │
       ▼
[3. orientation 分類]      ← 立/伏 二値判定 (Pose3D 連携)
       │
       ▼
[4. 鳴き数判定]            ← 横向き bbox を副露としてカウント
       │
       ▼
[5. アガリ判定 / 点数推定] ← 視覚 + 状態遷移
       │
       ▼
[出力: 検出結果 JSON / 可視化 PNG]

4.1 順序の根拠

• マスキングは推論前に: 探索空間を絞ることで YOLO の confidence threshold を下げてもFP が抑制される
• orientation 分類は推論後に: マスクされた領域には牌がないため、ここでマスク考慮は不要
• 鳴き数判定は最後: 副露の bbox が「卓端の枠外」にも存在することがあり、マスクで切らない方が安全

4.2 鳴き対応との相互作用

4.3 動画 (時系列) パイプラインでの最適化

動画では卓位置がほぼ固定 (カメラ切替時のみ変動)。マスクを 1 秒間隔でキャッシュすることで 計算コストを削減できる:

cached_mask = None
cached_fnum = -10000

for fnum, frame in enumerate(video_frames):
    if fnum - cached_fnum >= 30:  # 30 fps 動画で 1 秒
        cached_mask, info = table_region_mask(frame)
        cached_fnum = fnum
    if cached_mask is not None:
        frame = apply_mask(frame, cached_mask)
    detections = model.predict(frame)

5. 訓練データへの適用 (Roboflow Auto-Label 精度向上)

5.1 Roboflow へのアップロード前処理

# 一括マスキング (PowerShell)
Get-ChildItem mleague/frames-roboflow-filtered/*.jpg | ForEach-Object {
    phase0/.venv/Scripts/python.exe scripts/mask-table-region.py `
        --in-image $_.FullName `
        --out-image "mleague/frames-roboflow-masked/$($_.Name)"
}

# その後 Roboflow にアップロード (CLI)
roboflow upload \
    --project mahjong-mleague-v2 \
    --version pending \
    --workspace shimanto-ai \
    --image-dir mleague/frames-roboflow-masked/

5.2 Auto-Label 精度比較 (想定)

5.3 訓練と推論の一貫性

5.4 リスク

6. A/B 評価方法

6.1 評価フレーム群の準備

1. 同じテストフレーム 100 枚を用意 (mleague/eval/ 配下)
2. 各フレームに対して 2 通り実行: マスクあり / マスクなし
3. 同一モデル ID で公平に比較 (test-upsgd/mahjong-tiles-oc9zz 等)

6.2 評価スクリプト雛形

def evaluate_ab(test_frames, model, output_dir):
    results = {"with_mask": [], "without_mask": []}
    for frame_path in test_frames:
        frame = cv2.imread(frame_path)
        # Without mask
        dets_raw = model.predict(frame)
        results["without_mask"].append({"path": frame_path, "n": len(dets_raw), "dets": dets_raw})
        # With mask
        mask, info = table_region_mask(frame)
        frame_m = apply_mask(frame, mask) if not info["fallback"] else frame
        dets_masked = model.predict(frame_m)
        results["with_mask"].append({"path": frame_path, "n": len(dets_masked), "dets": dets_masked})
    # 集計
    summary = {
        "without_mask_total": sum(r["n"] for r in results["without_mask"]),
        "with_mask_total":    sum(r["n"] for r in results["with_mask"]),
        "reduction":          sum(r["n"] for r in results["without_mask"]) -
                              sum(r["n"] for r in results["with_mask"]),
    }
    return results, summary

6.3 比較指標 (記録項目)

6.4 結果の判定基準

• TP が 5% 以上減らない: マスクが牌を消していない (健全)
• FP が 30% 以上減る: マスクの効果が出ている (採用条件)
• fallback 発生率 5% 以下: 安定動作の指標

7. 既知の問題と対策

7.1 緑シャツのプレイヤー問題

7.2 連結回避の対策案

7.3 ハイライト / 反射の問題

7.4 卓の左右端切れ問題

7.5 倍速 / スロー再生時の動的ブレ

8. 改善方向

8.1 短期改善 (1〜2 週間)

8.2 中期改善 (1〜2 ヶ月)

8.3 長期改善 (3〜6 ヶ月)

• 3D カメラキャリブレーション: 卓平面を 3D で同定し、視点変動に頑健化
• 専用セグモデル (YOLOv8-seg): 卓・牌・手・背景を同時セグ。一括処理で高速
• 放送 API 連携: M-League 制作側からカメラメタデータを取得して直接マスク生成

8.4 推奨ロードマップ

1. Week 1: 5 スクリプトに --use-table-mask 統合 (本ガイド)
2. Week 2: A/B 評価実施 (評価テンプレート 使用)
3. Week 3: 緑シャツ対策 (connectivity=4 + 第 2 連結成分除外)
4. Week 4: マスク済画像で Roboflow 再アノテ → MVP v2 訓練データ準備
5. Month 2-3: SAM ベース置換を検討。MVP v2 で十分なら見送り