chore(setup): add model pre-download utility and CLI flag; update README usage

README.md

@@ -40,6 +40,20 @@ python app.py
 
 ブラウザで表示されるGradio UIからポーズ編集を行えます。
 
+### 初回セットアップ（モデルの事前ダウンロード）
+
+初回起動時に DWPose の ONNX モデルを自動ダウンロードしますが、起動前に取得しておきたい場合は次のどちらかを実行してください。
+
+```bash
+# 1) app.pyのオプションでダウンロードだけ実施
+python app.py --setup-models
+
+# 2) ユーティリティを直接実行（同等の動作）
+python -m utils.model_setup
+```
+
+デフォルトでは `./models` にキャッシュします。企業ネットワーク等でトークンが必要な場合は、先に `huggingface-cli login` を実施してください。
+
 ## 使い方（Hugging Face Spaces）
 
 スペース版の基本フローは「入力 → 編集 → 出力」です。

app.py

@@ -6,6 +6,7 @@ from utils.notifications import notify_success, notify_error, NotificationMessag
 from utils.coordinate_system import update_coordinate_system
 from utils.image_processing import process_uploaded_image
 from utils.export_utils import export_pose_as_image, export_pose_as_json, get_timestamp_filename
+from utils.model_setup import download_models as _download_models_setup
 import json
 import tempfile
 import base64
@@ -959,5 +960,15 @@ def main():
     return demo
 
 if __name__ == "__main__":
-    demo = main()
-    demo.launch()
+    import argparse, sys
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--setup-models", action="store_true", help="Download required models into ./models and exit")
+    args, _ = parser.parse_known_args()
+
+    if args.setup_models:
+        code = _download_models_setup()
+        # exit with code so CI/automation can check
+        sys.exit(code)
+    else:
+        demo = main()
+        demo.launch()

utils/model_setup.py

@@ -0,0 +1,65 @@
+"""
+Lightweight model setup utility for dwpose-editor.
+
+Provides a CLI to pre-download required ONNX models into the local cache
+directory used by the app (./models), without initializing ONNX sessions.
+"""
+
+from typing import List
+import os
+import sys
+
+try:
+    from huggingface_hub import hf_hub_download
+except Exception as e:  # pragma: no cover
+    hf_hub_download = None
+
+
+DEFAULT_REPO_ID = "yzd-v/DWPose"
+DEFAULT_CACHE_DIR = "./models"
+REQUIRED_FILES: List[str] = [
+    "yolox_l.onnx",
+    "dw-ll_ucoco_384.onnx",
+]
+
+
+def ensure_dir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
+
+
+def download_models(repo_id: str = DEFAULT_REPO_ID, cache_dir: str = DEFAULT_CACHE_DIR) -> int:
+    """Download required model files into cache_dir. Returns 0 on success, non-zero on failure."""
+    if hf_hub_download is None:
+        print("[ERROR] huggingface-hub is not installed. Run: pip install huggingface-hub")
+        return 2
+
+    ensure_dir(cache_dir)
+
+    ok = True
+    for filename in REQUIRED_FILES:
+        try:
+            print(f"[SETUP] Downloading {filename} from {repo_id} → {cache_dir} ...")
+            local_path = hf_hub_download(repo_id=repo_id, filename=filename, cache_dir=cache_dir)
+            print(f"[SETUP] OK: {local_path}")
+        except Exception as e:
+            ok = False
+            print(f"[SETUP] ERROR: failed to download {filename}: {e}")
+
+    return 0 if ok else 1
+
+
+def main(argv: List[str] | None = None) -> int:
+    """CLI entry point: python -m utils.model_setup [--repo REPO] [--cache-dir DIR]"""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Pre-download DWPose models into ./models")
+    parser.add_argument("--repo", default=DEFAULT_REPO_ID, help="Hugging Face repo id")
+    parser.add_argument("--cache-dir", default=DEFAULT_CACHE_DIR, help="Local cache directory")
+    args = parser.parse_args(argv)
+
+    return download_models(repo_id=args.repo, cache_dir=args.cache_dir)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())
+