﻿2D Character Body Estimator 1.3.1 Distribution
Windows配布版 使い方マニュアル
============================================================

■ この配布版について
このZIPは、別のWindows PCでも利用しやすいようにした「初回自動セットアップ型」です。
ZIPを展開し、基本的には start_windows.bat をダブルクリックするだけで起動できます。

画像処理とViTPose推論はPC内のローカルプロセスで行います。
画像そのものを外部AIサービスへアップロードする構成ではありません。


■ 対応環境
・64-bit Windows 10 / 11
・インターネット接続（初回セットアップと初回モデル取得時に必要）
・NVIDIA GPUを強く推奨
・ViTPose-Hは16GB級VRAMのGPUを推奨
・VRAMが不足する場合はViTPose-L HumanArtを選択してください
・NVIDIA GPUが無いPCでもCPU版PyTorchを導入できますが、ViTPose-H推論は非常に遅くなります
・セットアップとモデルを含め、少なくとも12GB程度の空き容量を推奨します


■ 最初の起動
1. ZIPを任意のフォルダへ展開します。
   OneDriveなどの同期フォルダより、通常のローカルフォルダを推奨します。

2. start_windows.bat をダブルクリックします。

3. 初回だけAI実行環境を自動構築します。
   この処理ではPython、PyTorch、MMPose、MMPreTrain、MMCV-lite等を準備します。

   【重要】初回インストールには時間がかかります。
   PyTorchは大きなパッケージのため、回線速度・PC性能によっては数分～数十分程度かかることがあります。
   インストール中は黒いコンソール画面を閉じないでください。

4. 対応するPythonがPCに無い場合、python.orgから64-bit Python 3.10.11を自動取得し、
   このアプリ用のローカル実行環境として準備します。
   管理者権限を前提としません。

5. セットアップと環境確認が完了すると、ローカルサーバーが起動し、ブラウザが自動で開きます。


■ ViTPoseモデルの初回読込について
初回セットアップが終わっても、ViTPose-H / ViTPose-Lの学習済みモデル本体はまだ入っていません。
アプリ内でViTPoseモデルを初めて読み込んだ時に、OpenMMLab公式サイトからチェックポイントを取得します。

ViTPose-Hは特に大きいため、初回モデル読込にも追加で時間がかかります。
コンソールにダウンロード進捗が表示されます。完了するまで閉じないでください。
2回目以降は、ダウンロード済みモデルをそのまま利用します。


■ 通常の起動
2回目以降は start_windows.bat をダブルクリックしてください。
環境確認後、そのままブラウザが開きます。

ツール利用中は start_windows.bat から開いた黒いコンソール画面を残しておいてください。
コンソールを閉じるとローカルAIサーバーも終了します。


■ 主な使い方
・画像を開く
・必要なら「人物範囲を指定」で対象キャラクターを囲む
・ViTPose-H HumanArtを選び「AI自動配置」
・姿勢フレーム、Bust / Underbust / Waist / Hipを確認
・必要な断面だけ手動補正
・既知の身長や肩幅・顔高・上腕などのアンカーを追加すると整合性を高められます
・Underbustは通常、肩幅ラインと平行に固定できます
・片乳房の横幅/縦幅/突出を指定すると、体積と重量の参考推計もできます

単一の2D画像から3D形状を完全に復元することはできないため、周長・カップ・重量は推定値です。


■ プライバシーと通信
・読み込んだ画像はViTPose用のローカルPythonプロセスへlocalhost経由で渡されます
・画像をOpenMMLabやOpenAI等の外部サービスへ送信する処理はありません
・インターネット通信が必要なのは、主に初回のPython/依存パッケージ/モデル取得です
・ブラウザ内のフォールバック姿勢モデルを利用する場合、ライブラリやモデルファイル取得のためCDNへ接続する場合があります


■ Pより上の推定カップ表記
Pまでは従来の日本式目安を使用します。
Pより上については、このツール内だけの便宜的な「独自拡張」として、Bust−Underbust差を2.5cm刻みで外挿します。

Q ≈ 50.0cm差
R ≈ 52.5cm差
S ≈ 55.0cm差
…
Z ≈ 72.5cm差
Z+1 ≈ 75.0cm差
Z+2 ≈ 77.5cm差
…

例として、差74.6cmはZ+1付近、差85.0cmはZ+5付近です。
Q以降、特にZ+Nは正式なJIS/メーカー規格名称ではありません。巨大な二次元キャラクターの比較用に、同じ2.5cm刻みを機械的に延長した本ツール独自の表示です。


■ トラブルシュート
【起動しない / インストールに失敗した】
diagnose_windows.bat を実行してください。
diagnostic_latest.txt が作成されます。サポート時はこのファイルを確認してください。

【途中で回線が切れた】
start_windows.bat をもう一度実行してください。
多くの場合は不足分を再取得して自動修復します。

【CUDA out of memory / GPUメモリ不足】
・ViTPose-L HumanArtへ切り替える
・ゲーム、画像生成AI、動画処理などGPUを使うアプリを閉じる
・ブラウザのGPU負荷が大きいタブを閉じる

【NVIDIA GPUがあるのにCPUで動く】
・NVIDIAドライバを更新してください
・diagnose_windows.bat の CUDA available とGPU名を確認してください
・この配布版は検証済みのPyTorch 2.11.0 + CUDA 12.8ビルドを使用します

【DLL load failed 等が出る】
WindowsのMicrosoft Visual C++ 2015-2022 x64 Runtimeが不足している可能性があります。
Microsoft公式のVisual C++再頒布可能パッケージを導入した後、再度起動してください。

【AI環境だけ作り直したい】
reset_ai_environment.bat を実行してください。
.venvだけを削除し、次回起動時に再構築します。
ダウンロード済みViTPoseモデルは残ります。

【モデルファイルの破損が疑われる】
modelsフォルダ内の該当.pthファイルを削除してから再度モデルを読み込むと、公式サイトから再取得します。


■ 別PCへ渡す場合
配布する時は、このZIPそのものを渡すのが最も安全です。
一度セットアップしたフォルダを丸ごとコピーすると、.venvに元PCの絶対パスが残る場合があります。
この配布版はコピーされた無効な.venvを検出した場合、再構築するようにしてありますが、
原則として「未セットアップの配布ZIP」から開始することを推奨します。

配布ZIPにはPython本体、PyTorch、ViTPoseの学習済みモデルを同梱していません。
それらは利用PC側で公式配布元から取得されます。


■ 終了方法
start_windows.batで開いたコンソール画面を閉じてください。
ブラウザタブだけ閉じてもローカルサーバーが残る場合があります。


■ 再配布について
本ZIP内のアプリ本体と起動スクリプトは配布用にまとめています。
初回取得されるPython、PyTorch、OpenMMLab関連ライブラリ、ViTPoseチェックポイント等は
それぞれの配布元・ライセンス条件に従ってください。
モデル配布元は MODEL_SOURCES.txt を参照してください。


■ バージョン
2D Character Body Estimator 1.3.1 Distribution
機能ベース: v1.2.3（複数アンカー、Bust/Cup補正、Underbust平行固定、片乳房重量推計を含む）
