# BatchWeaver：一括出力・自動化ガイド
〜 複数アングルおよび特定フレームレンジのバッチ出力ガイド 〜

最終更新：2026/04/20

## 1. BatchWeaver の機能定義と運用メリット

BatchWeaverは、MotionWeaverによるモーション変換プロセスを、外部のパラメータ定義ファイル（CSV）に基づき連続実行するための**「バッチ・オートメーション・ツール」**です。

### 導入による最適化
個別の手動変換を自動化することで、同一のソースデータ（BVH）から異なる条件下のアセットを効率的に量産することが可能になります。
- **マルチアングル出力の効率化**: 同一の「歩行（Walking.bvh）」データから、正面・側面・背面・俯瞰など、アニメーション制作に必要な全方位のガイドデータを一括生成します。
- **ヒューマンエラーの排除**: 事前に定義されたCSVに基づき処理を行うため、手動設定によるアングルの微細なズレや命名規則の不一致を防止します。

---

## 2. 運用ワークフロー：3段階のバッチ処理

本システムは、定義・生成・実行の3フェーズにより運用されます。

### Phase 1: ソースデータ（BVH）の指定
変換の基準となる3Dモーションデータを選択します。システムが自動的に全フレーム数をスキャンし、後続のレンジ指定における基準値を算出します。

### Phase 2: パラメータ指示書（CSV）の論理構築
「投影アングル」「フレーム範囲」「出力ラベル」を記述したCSVファイルを準備します。

### Phase 3: 実行ファイル（RUN.bat）の生成とバッチ起動
UI上のボタン操作により、処理命令をカプセル化した `RUN.bat` を生成します。この実行ファイルによって、指定された全ての変換プロセスがシーケンシャルに処理され、ディレクトリ内に成果物が自動配置されます。

---

## 3. UIコンポーネントおよび操作仕様

### [1. Source BVH File]
バッチ処理のソースとなるモーションデータ（BVH形式）を指定します。ロード完了後、現在のファイルに含まれる総フレーム数がシステムログに表示されます。

### [2. Parameter CSV File]
各行に変換条件を定義したCSVファイルを選択します。
- **スキーマの生成**: 「Select / Create」ボタンにより、新規ファイルパスを指定した場合、システムが標準的なヘッダー定義（ひな形）を自動生成します。

### [3. Generate Batch File]
「GENERATE RUN.bat」コマンドにより、OSレベルでのバッチ処理指示書（batファイル）を生成します。

---

## 4. 指示書（CSV）の論理設計と構築プロトコル

CSV内の1行が、1回の独立したモーション変換プロセスに対応します。

| 項目名 | 定義 | 運用上の留意点 |
| :--- | :--- | :--- |
| **X_ROT_DEG** | X軸回転（俯仰角） | 正の値で俯瞰、負の値で仰角（アオリ）を設定。 |
| **Y_ROT_DEG** | Y軸回転（方位角） | 視点方向を定義。45.0（斜め）、90.0（真横）、180.0（背面）。 |
| **Z_ROT_DEG** | Z軸回転（傾斜） | 基本的には 0.0 固定での運用を推奨。 |
| **START_FRAME** | 開始フレーム | 抽出を開始するフレーム番号を指定。 |
| **END_FRAME_EXCL**| 終了フレーム | 抽出を終了するフレーム番号（排他的）。 |
| **MODE** | 変換モード | **重要**：原則として `mode1` を指定してください。 |
| **LABEL** | 出力ファイル識別子 | `Walk_Right_45` 等、視覚的に管理しやすいラベルを付与。 |

> [!TIP]
> **変換モード「mode1」と「mode2」の選定基準**
> - **`mode1` (標準変換)**：初期ポーズの特性を最大限に維持し、解剖学的に自然な適合を行います。通常はこのモードを全行に適用してください。
> - **`mode2` (例外補正モード)**：特定のデータにおいて関節の異常な重なりや捻じれが発生する場合の代替手段です。1フレーム目に強制的に標準Tポーズ（基準姿勢）を挿入・復元し、リギングの不整合を回避します。

---

## 5. 高度な運用スタック

### 部分抽出によるアセットの断片化（Chop-up）
長時間におよぶBVHデータから、必要な演技区間（例：歩行開始、方向転換、停止）のみを個別のフレーム範囲として定義・出力することで、ポストプロダクション工程における尺調整のコストを大幅に削減可能です。

### モーション・カタログ（アクション）の構築
本ツールで量産された `_3d.csv` 群を、Mohoの「アクション（Actions）」機能へとインポートしてください。
メイン・タイムラインとは独立した、アングル別の「動きのデータベース」が構築されます。制作のフェーズに合わせて適切なアングルデータを「スタンプ」感覚で適用できる、高度な演出環境が実現します。

---

## 6. 例外処理とテクニカルサポート

指示書の記述形式（CSVシンタックス）に不整合がある場合、バッチ処理は正常に完了しません。カンマの過不足やデータ型の不一致は、システムによるパースエラーの原因となります。

問題の特定が困難な場合は、**「作成したCSVファイル」** および **「ソースBVH」** を添えて、論理的な診断データを開発者または専門担当者に提示してください。制作のワクワクを阻害する技術的なトラブルは、データに基づく正確な修正によって速やかに解消可能です。
