CLI ツール

FCS CLI ツールは、フェイシャルキャプチャとアニメーション処理のワークフローを自動化するためのスクリプトベースのインターフェースを提供します。YAML スクリプト形式で、セッションの読み込み、セッション設定の変更、動画の処理、Maya へのアニメーションのアップロードを実行できます。

目次

• インストール

• クイックスタート

• スクリプト形式

  • 検証の厳格さ

  • プロファイル

• 実行モデル

• コマンド

• ステップタイプ

• 例

• ログ

• エラー処理

• Maya 連携

• トラブルシューティング

インストール

CLI ツールは FCS（Facial Capture System）パッケージに含まれています。FCS 環境のセットアップと依存関係のインストールが完了していることを確認してください。

クイックスタート

YAML スクリプトファイル（例：my_script.yaml）を作成します：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  wait_seconds_after_scene_open: 2.0  # Optional: wait 2 seconds after scene opens
  fisheye: true  # Optional: enable fisheye correction
  pipeline: "Rich"  # Optional: use Rich pipeline
  denoising: "my_profile"  # Optional: load denoising profile from presets
  initial_scene_open: true  # Optional: open scene after validation (default: true)
  command_port: 42069  # Optional: Maya commandPort for all operations
  rename_controllers:  # Optional: modify controller name prefixes
    prefix: "char_face_"
    action: "prepend"  # or "remove"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
      overrides:
        command_port: 42070  # Optional: use different port for this step

スクリプトを実行します：

FCS_CLI.exe --file my_script.yaml

スクリプト形式

トップレベル構造

すべてのスクリプトには、次の3つの必須セクションが必要です：

version: 1                    # Required: Must be exactly 1
context:                     # Required: Script context
  session: <string>          # Required: Path to fcs_session.yaml
steps:                       # Required: List of steps to execute
  - <step>                   # One or more steps

バージョン

現在サポートされているのはバージョン 1 のみです。このフィールドは、スクリプト形式の進化に伴う前方互換性を確保します。

コンテキスト

context セクションでは、スクリプト実行開始時に読み込むセッションファイルを定義します。

• session（必須、文字列）：FCS セッション YAML ファイルへのパス。ファイル名は fcs_session.yaml でなければならず、他のファイル名では検証が失敗します。

• wait_seconds_after_scene_open（任意、float）：Maya シーンを開いた後に待機するグローバルな秒数。スクリプト内のすべてのシーンオープン操作（process ステップの reopen_maya_scene や Maya 起動時のシーンを含む）に適用されます。デフォルト：0.0（待機なし）

• fisheye（任意、bool）：動画処理の魚眼補正の有効/無効。指定した場合は UI 設定を上書き。デフォルト：true。

• pipeline（任意、文字列）：動画処理に使用するパイプライン。次のいずれか："Rich"、"Robust"、"RP"、"RP++"、"Robust++"、"Rich++"。指定した場合は UI 設定を上書き。デフォルト："RP++"。

• denoising（任意、文字列）：ノイズ除去/スムージングプロファイルファイルへのパス、またはスムージングプリセットディレクトリから読み込むファイル名。フルパスの場合は存在する必要があります。ファイル名のみ（フルパスでない）の場合は FCS_TMP_DIR/smoothing_presets/filename.yaml から読み込まれます。指定した場合は処理前にプロファイルを読み込み。デフォルト：スムージングなし。

• command_port（任意、整数）：スクリプト内の全 Maya 操作で使用する Maya commandPort 番号。1 ～ 65535 の整数である必要があります。指定した場合は指定ポートで接続を再作成し、すべての Maya プリフライトチェックとアップロードに使用します。デフォルト：42069。

• initial_scene_open（任意、bool）：true（デフォルト）の場合、データ検証後、全ステップ実行前に Maya シーンを1回自動的に開きます。シーンはスクリプト実行開始時（プリフライトチェック後）に1回だけ開かれ、各ステップの前には開かれません。false の場合は初期シーンオープンをスキップします。デフォルト：true（セッションに maya_scene と maya_base が設定されている場合に自動でシーンを開く）

• rename_controllers（任意、マッピング）：プレフィックスを付加または削除してコントローラ名を変更。セッション読み込み後、いずれのステップが実行される前に1回適用されます。Maya シーンの命名規則に合わせてコントローラ名を調整する際に便利です。

  • prefix（必須、文字列）：すべてのコントローラ名に付加または削除するプレフィックス

  • action（任意、文字列）：実行する操作 — "prepend"（デフォルト）または "remove"

• playblast（任意、マッピング）：プレイブラストをエクスポートする process ステップで、プレイブラスト設定をアプリ設定の上書きとして適用します。指定しない場合はアプリ設定を使用します。

  • camera（任意、文字列）：Maya カメラ名（例："persp"）。

  • width（任意、整数）：出力幅（ピクセル）。

  • height（任意、整数）：出力高さ（ピクセル）。

  • percent（任意、整数）：解像度パーセント（例：100、1～100）。

  • quality（任意、整数）：プレイブラスト品質（例：100、1～100）。

• profiles（任意、リスト）：ステップ実行前に、読み込んだセッションの ROM プロファイルの有効/無効を設定するルール。詳細はプロファイルを参照。

ステップ

ステップは記述順に順次実行されます。各ステップは次のいずれかのキーを持つ単一キーのマッピングである必要があります：

• process — 動画を処理し、必要に応じて Maya にアップロード

• sleep — 指定時間だけスクリプト実行を一時停止

検証の厳格さ

スクリプト検証は厳格なスキーマ契約に従います。定義されたスキーマからの逸脱はすべて検証で拒否されます：

1. 未知のトップレベルフィールド → エラー：トップレベルで許可されるのは version、context、steps のみ。他のフィールドがあると検証が失敗します。

2. 未知の context フィールド → エラー：文書化された context フィールドのみが許可されます。context セクションの未知のフィールドがあると検証が失敗します。

3. 未知のステップタイプ → エラー：有効なステップタイプは process と sleep のみ。他のステップタイプがあると検証が失敗します。

4. 未知のステップフィールド → エラー：各ステップタイプには許可されるフィールドの定義セットがあります。そのステップタイプで文書化されていないフィールドがあると検証が失敗します。

5. ネスト構造の余分なキー → エラー：ネスト構造（process ステップの upload や overrides など）は文書化されたフィールドのみを受け付けます。未知のキーがあると検証が失敗します。

6. 順序が重要：ステップは steps リストに出現する正確な順序で順次実行されます。実行順序は意味を持ち、変更できません。

検証失敗の例：

# ❌ Invalid: Unknown top-level field
version: 1
context:
  session: "path/to/session.yaml"
steps: []
unknown_field: "value"  # Error: unknown top-level field

# ❌ Invalid: Unknown context field
version: 1
context:
  session: "path/to/session.yaml"
  unknown_context_field: "value"  # Error: unknown context field
steps: []

# ❌ Invalid: Unknown step type
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - unknown_step: {}  # Error: unknown step type

# ❌ Invalid: Unknown step field
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - process:
      video: "path/to/video.mp4"
      unknown_field: "value"  # Error: unknown field in process step

# ❌ Invalid: Unknown nested field
version: 1
context:
  session: "path/to/session.yaml"
steps:
  - process:
      video: "path/to/video.mp4"
      upload:
        animation: true
        unknown_upload_field: true  # Error: unknown field in upload

プロファイル

profiles コンテキストフィールドを使用すると、ステップ実行前にセッション内の プロファイルの有効/無効を設定できます。ルールは順次適用され、後のルールがマッチしたプロファイルについて先のルールを上書きします。

各ルールには3つのフィールドがあります：

フィールド	必須	値	説明
match	はい	"all" またはクライテリアのリスト	対象とするプロファイル
select	はい	"all"、"none"、または 1 以上の整数	マッチしたプロファイルに対する操作
condition	いいえ	AND（デフォルト）または OR	複数クライテリアの結合方法

match クライテリア — リスト内の各項目は単一キーのマッピングです：

キー	マッチ条件
video: "<stem>"	プロファイルのソース動画ファイル名（拡張子なし）が値と一致
not_video: "<stem>"	プロファイルにソース動画がない、またはステムが値と異なる
user_tag: "<tag>"	プロファイルにこのユーザータグがある
no_user_tag: "<tag>"	プロファイルにこのユーザータグがない

select の値：

• "all" — マッチしたすべてのプロファイルを有効化

• "none" — マッチしたすべてのプロファイルを無効化

• 整数 N — マッチしたプロファイルからランダムに N 個を有効化（N 未満のマッチではエラー）

例：

profiles:
  # Disable everything first
  - match: all
    select: none

  # Then enable exactly 10 profiles whose source video is "ROM_walk"
  - match:
      - video: "ROM_walk"
    select: 10

  # Enable all profiles tagged "hero" OR tagged "featured"
  - match:
      - user_tag: "hero"
      - user_tag: "featured"
    condition: OR
    select: all

  # Enable profiles tagged "validated" AND whose video is NOT "ROM_bad"
  - match:
      - user_tag: "validated"
      - not_video: "ROM_bad"
    condition: AND   # default, can be omitted
    select: all

注意：match は YAML リスト（- 項目）である必要があります。プレーンなマッピングは YAML のサイレントな重複キーマージを防ぐため拒否されます（例：2つの video: キーは1つに統合されてしまう）。

実行モデル

スクリプトの実行の仕組みを理解すると、効果的な自動化ワークフローを記述できます。FCS CLI は予測可能な実行モデルに従います。

実行ライフサイクル

1. スクリプト初期化：スクリプトを読み込み、スキーマに対して検証します。スキーマエラーがあればコード 1 で即座に終了し、セッションや Maya の操作は一切行われません。

2. ライセンスチェック：ライセンスのチェックアウト/検証を行います。失敗するとコード 3 で終了します。

3. セッション読み込み：context.session で指定されたセッションファイルが1回読み込まれます。セッションは実行中メモリに保持されます。

4. コントローラリネーム：rename_controllers が指定されている場合、ステップ実行前にコントローラ名のプレフィックスの付加または削除が1回適用されます。

5. プロファイル選択：profiles が指定されている場合、ルールが順次適用され、各 ROM プロファイルの有効状態が設定されます。

6. Affogato 初期化：Maya の commandPort への接続を確立します。

7. Maya プリフライト：Maya の到達可能性を検証します。失敗するとコード 2 で終了し、ステップは実行されません。

8. 初期シーンオープン：initial_scene_open が true（デフォルト）で、セッションに maya_scene と maya_base が設定されている場合、ステップ実行前に Maya シーンが1回開かれます。失敗は非致命的（警告としてログ）です。wait_seconds_after_scene_open 秒待機します。

9. ステップ実行：ステップは出現順に順次実行されます。最初のステップ以降、各ステップの前にライセンスが再チェックされます。ロールバック、分岐、並列実行はありません。

コンテキストとオーバーライド

• コンテキストフィールド：context セクションで定義されたすべてのフィールドは、明示的にオーバーライドされない限り、すべてのステップにグローバルに適用されます。これには fisheye、pipeline、denoising、command_port、playblast などの設定が含まれます。

• ステップオーバーライド：process ステップの overrides セクションは、その特定のステップの期間中のみ適用されます。ステップ完了後、グローバルコンテキストの値が復元されます。個々の処理操作で設定（command_port、maya_scene、maya_base など）を一時的に変更できます。

実行の保証

• 順次実行：ステップは常に1つずつ、順序どおりに実行されます

• ロールバックなし：ステップが失敗した場合、実行は停止し、前のステップは元に戻されません

• 分岐なし：条件分岐やループはサポートされません

• 並列実行なし：複数のステップを同時に実行することはできません

• セッション永続化：セッションは実行中メモリに保持され、ディスクには保存されません

コマンド

スクリプト実行

YAML スクリプトを実行します：

FCS_CLI.exe --file <script_path>

オプション：

• --file、-f：YAML スクリプトファイルへのパス（必須）

• --dry-run：実行せずにスクリプトを検証する

例：

# Run a script
FCS_CLI.exe --file my_script.yaml

# Validate without executing
FCS_CLI.exe --file my_script.yaml --dry-run

ステップタイプ

process ステップ

単一の動画ファイルを処理し、必要に応じて結果を Maya にアップロードします。

形式：

- process:
    video: <string>                    # Required
    upload:                             # Optional
      animation: <bool>                # Default: false
      audio: <bool>                    # Default: false
      frames: <bool>                   # Default: false
      lm_frames: <bool>                # Default: false
    export:                             # Optional
      scene: <bool>                    # Default: false
      playblast: <bool>                # Default: false
    force_reprocess: <bool>            # Optional, default: true
    time_offset_frames: <int>          # Optional, default: 0
    reopen_maya_scene: <bool>          # Optional, default: auto (see below)
    overrides:                          # Optional
      command_port: <int>              # Optional, override commandPort for this step
      maya_scene: <string>             # Optional, override maya_scene for this step
      maya_base: <string>              # Optional, override maya_base for this step
      out_scene_path: <string>        # Optional, path to save Maya scene file (.ma or .mb)
      out_playblast_path: <string>    # Optional, path to save playblast video

フィールド：

• video（必須、文字列）：処理する動画ファイルへのパス

• upload（任意、マッピング）：Maya へのアップロードオプション

  • animation（bool）：アニメーションカーブをアップロード

  • audio（bool）：動画からオーディオトラックをアップロード

  • frames（bool）：動画フレームを画像シーケンスとしてアップロード

  • lm_frames（bool）：ランドマーク付きフレームをアップロード。++ パイプライン（RP++、Rich++、Robust++）では使用不可。使用すると LM_FRAMES_UNSUPPORTED_PIPELINE エラーが発生します。

• export（任意、マッピング）：処理後のエクスポートオプション

  • scene（bool）：Maya シーンファイルをエクスポート

  • playblast（bool）：プレイブラスト動画をエクスポート

• force_reprocess（任意、bool）：キャッシュがあっても強制的に再処理。デフォルト：true

• time_offset_frames（任意、整数）：アニメーションアップロードのフレームオフセット。デフォルト：0、0 以上である必要あり。

• reopen_maya_scene（任意、bool）：処理前に Maya シーンを再オープンするかを制御：

  • true — オーバーライドやアップロードフラグに関係なく、常に再オープン

  • false — 再オープンしない（明示的なオプトアウト）

  • 省略 — 自動：いずれかのオーバーライド（command_port、maya_scene、maya_base）が存在し、かつ少なくとも1つの upload.* フラグが true の場合にのみ再オープン

  • 正の値：Maya タイムラインの time_offset_frames フレーム目にアニメーションが開始する

  • ゼロ：オフセットなし

• overrides（任意、マッピング）：この process ステップ専用のオーバーライド値

  • command_port（任意、整数）：このステップで使用する Maya commandPort 番号。1 ～ 65535 の整数。指定した場合、このステップのみ指定ポートで接続を再作成し、context.command_port またはアプリケーション設定のポートを上書きします。再作成後にプリフライトチェックを実行し、Maya に到達可能か確認します。

  • maya_scene（任意、文字列）：このステップで使用する Maya シーンファイルへのパス。reopen_maya_scene が true のときにセッションの maya_scene を上書きします。

  • maya_base（任意、文字列）：このステップで使用する Maya ワークスペースベースディレクトリへのパス。reopen_maya_scene が true のときにセッションの maya_base を上書きします。

  • out_scene_path（任意、文字列）：処理後に Maya シーンファイルを保存するパス（.ma または .mb 拡張子が必要）。export.scene が true の場合に指定しないと、警告がログされシーンは保存されません。

  • out_playblast_path（任意、文字列）：プレイブラスト動画を保存するパス。ファイル拡張子なしで指定する必要があります（.mp4 が自動的に付加されます）。export.playblast が true の場合に指定しないと、セッションの出力フォルダとアプリ設定からデフォルトパスが生成されます。

  重要：process ステップでは常に適切なポート（オーバーライドまたはコンテキストから）で Affogato 接続を再作成し、処理前にプリフライトチェックを実行します。reopen_maya_scene が省略されオーバーライドが存在する場合、上記の自動ルールに従いシーンが再オープンされます（reopen_maya_scene 参照）。

Maya 内部ワークフロー process ステップでいずれかの upload.* オプションが有効な場合、CLI は commandPort 経由で Maya 内で以下の操作を厳密な順序で実行します。

1. シーンタイミングの設定

• Maya シーンの FPS を入力動画に合わせて設定する。

• シーンの再生範囲を動画の総フレーム数に合わせて設定する。

2. オーディオの設定（upload.audio = true の場合）

• 入力動画からオーディオトラックをインポートする。

• オーディオを Maya タイムラインにアタッチする。

3. 参照フレームの設定（upload.frames = true または upload.lm_frames = true の場合）

• 動画フレームを画像シーケンスとして抽出する。

• 以下を使用して imagePlane を作成または更新する：

4. upload.frames = true の場合は生フレーム

• upload.lm_frames = true の場合はランドマーク付きフレーム

• アニメーションのリセット

5. セッションで定義されたすべてのコントローラの既存アニメーションキーフレームを削除する。

• これによりアップロードが決定的になり、複数回の実行でキーフレームが蓄積しないようにする。

• アニメーションのアップロード

6. 新しく計算されたアニメーションカーブをすべてのセッションコントローラに適用する。

• time_offset_frames > 0 の場合、挿入前にすべてのキーフレームが指定フレーム数だけ前方にシフトされる。

• 出力の保存

プレイブラスト動画を保存する（export.playblast = true の場合）。

Maya シーンファイルを保存する（export.scene = true の場合）。

注意

すべての操作は process ステップごとにアトミックに実行され、部分的なアップロードはサポートされません。

reopen_maya_scene = true の場合、このワークフロー開始前に Maya シーンが再オープンされます。

コントローラのマッチングは名前ベースです。解決できないコントローラにはアニメーションは適用されず、ロールバックは行われません。

- process:
    video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
    upload:
      animation: true
      audio: true
    export:
      scene: true
      playblast: true
    force_reprocess: true
    reopen_maya_scene: true
    time_offset_frames: 100
    overrides:
      command_port: 42070
      maya_scene: "D:/maya_scenes/alternate_scene.mb"
      maya_base: "D:/maya_workspace"
      out_scene_path: "D:/output/take_01.ma"
      out_playblast_path: "D:/output/take_01_playblast"

少なくとも 1 つの upload.* オプションが有効な場合にのみこのワークフローが実行されます。アップロードなしの処理では Maya シーンは変更されません。

sleep ステップ

形式：

- sleep:
    seconds: <float>    # Required: number of seconds to sleep

フィールド：

• seconds（必須、float）：実行を一時停止する秒数。0 以上の数である必要があります。

コントローラのマッチングは名前ベースです。解決できないコントローラにはアニメーションは適用されず、ロールバックは行われません。

- sleep:
    seconds: 5.0  # Wait 5 seconds

- sleep:
    seconds: 2.5  # Wait 2.5 seconds

例

例 1：基本的な処理

動画を処理して Maya にアニメーションをアップロードする：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

例 2：シーン切り替えを伴う複数動画

複数動画を処理し、動画ごとに Maya シーンを切り替える：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
      overrides:
        maya_scene: "D:/maya_scenes/scene_01.mb"

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/scene_02.mb"

例 3：タイムオフセット付きアニメーション

異なるタイムオフセットでアニメーションをアップロードする：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 100    # Starts at frame 100 in Maya

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 200    # Starts at frame 200 in Maya

例 4：コントローラプレフィックス管理

処理前にコンテキストでコントローラプレフィックスを追加する：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  rename_controllers:
    prefix: "char_face_"
    action: "prepend"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

例 5：フル処理パイプライン

すべての機能を使った完全なワークフロー。注意：lm_frames は非 ++ パイプライン（例：Rich、Robust、RP）が必要なため、コンテキストで pipeline: "Rich" を設定しています：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  wait_seconds_after_scene_open: 2.0
  initial_scene_open: true
  command_port: 42069
  pipeline: "Rich"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
        audio: true
        frames: true
        lm_frames: true
      export:
        scene: true
        playblast: true
      force_reprocess: true
      time_offset_frames: 0
      # reopen_maya_scene omitted — auto-reopens because overrides are present and upload is requested
      overrides:
        command_port: 42070
        maya_scene: "D:/maya_scenes/alternate_scene.mb"
        maya_base: "D:/maya_workspace"
        out_scene_path: "D:/output/take_01_processed.ma"
        out_playblast_path: "D:/output/take_01_playblast"

例 6：シーンオープンのスキップ

自動シーンオープンをスキップし、シーンを開くタイミングを手動で制御する：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  initial_scene_open: false  # Skip initial scene opening after validation

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      reopen_maya_scene: true  # Explicitly reopen before this step

例 7：プロファイル選択

すべてのプロファイルを無効化してから、特定の動画から10個をランダムに有効化する：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  profiles:
    - match: all
      select: none
    - match:
        - video: "ROM_walk"
      select: 10

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

ログ

スクリプト実行時（--dry-run モードでない場合）、CLI はスクリプトと同じディレクトリに <スクリプト名>.log というログファイルを自動的に作成します。例えば、my_script.yaml を実行すると、同じディレクトリに my_script.log が生成されます。

• ログレベル：INFO 以上（INFO、WARNING、ERROR）

• エンコーディング：UTF-8

• ライフサイクル：実行開始時にログファイルが作成され、実行完了時（成功・失敗に関わらず）にログシンクが除去されます。既存のログファイルがある場合は上書きされます。

このログファイルはコンソール出力と同じ構造化メッセージをキャプチャし、デバッグや監査のための永続的な実行記録を提供します。

エラー処理

エラーコード

CLI はプログラムによるエラー処理のため、構造化されたエラーコードを使用します：

コード	説明
SESSION_NOT_FOUND	セッションファイルが存在しない
SESSION_INVALID	セッションファイルが無効または破損している
SESSION_LOAD_ERROR	セッション読み込みエラー（一般的な読み込み失敗）
NO_SESSION_LOADED	セッションを読み込まずに操作を試行した
MISSING_RENAME_CONTROLLERS_PREFIX	rename_controllers コンテキストフィールドに prefix がない
INVALID_RENAME_CONTROLLERS_PREFIX	rename_controllers コンテキストフィールドの prefix 値が無効
INVALID_RENAME_CONTROLLERS_ACTION	rename_controllers コンテキストフィールドの action が無効（"prepend" または "remove" である必要あり）
PROFILES_INSUFFICIENT_MATCH	select: N が指定されたが、マッチしたプロファイルが N 未満
VIDEO_NOT_FOUND	動画ファイルが存在しない
MAYA_NOT_REACHABLE	Maya commandPort に到達できない
MAYA_SCENE_NOT_SET	セッションまたはオーバーライドで Maya シーンパスが設定されていない
MAYA_SCENE_NOT_FOUND	Maya シーンファイルが存在しない
MAYA_SCENE_OPEN_ERROR	Maya シーンのオープンに失敗（reopen_maya_scene が true のとき発生）
MAYA_BASE_NOT_SET	セッションで Maya ベースパスが設定されていない
MAYA_BASE_NOT_FOUND	Maya ベースフォルダが存在しない
PIPELINE_ERROR	動画処理パイプラインが失敗した（学習/推論の失敗）
ANIMATION_NOT_FOUND	処理後にアニメーションキャッシュファイルが見つからない
LM_FRAMES_UNSUPPORTED_PIPELINE	++ パイプラインで lm_frames アップロードが要求された（非対応）
DENOISING_PROFILE_NOT_FOUND	指定パスにノイズ除去プロファイルファイルが見つからない
DENOISING_PROFILE_LOAD_ERROR	ノイズ除去プロファイルファイルの読み込みに失敗した
OUTPUT_DIR_NOT_CREATED	必要な出力ディレクトリの作成に失敗した
OUTPUT_FILE_NOT_CREATED	処理後に期待される出力ファイルが作成されなかった
PLAYBLAST_PATH_HAS_SUFFIX	out_playblast_path にファイル拡張子が含まれていた（.mp4 は自動で付加される）

実行時の動作

• 検証エラー：いずれのステップも実行される前にスクリプト検証が失敗（終了コード 1）

• Maya エラー：Maya 関連の失敗（到達不可、シーンオープン失敗など）はコード 2 で終了

• 実行エラー：最初に失敗したステップでスクリプトが停止（終了コード 3）

終了コード

• 0：成功

• 1：検証エラー（スクリプトスキーマ検証、必須フィールド欠落、無効な値）

• 2：Maya 関連エラー（Maya に到達不可、シーンオープン失敗、Maya 設定の問題）

• 3：実行失敗（ライセンスチェック失敗、セッション読み込みエラー、パイプラインエラー、ステップ実行失敗）

Maya 連携

前提条件

1. Maya が起動していること（commandPort が有効）

2. CommandPort が開いていること（通常ポート 42069、またはスクリプトの context.command_port で指定したポート）

Maya プリフライトとシーンオープン

いずれのステップを実行する前に、CLI はプリフライトチェックを実行します：

1. Maya commandPort の接続をテスト

2. Maya に到達できない場合：

   • エラーをログ：MAYA_NOT_REACHABLE

   • コード 2 で終了

   • ステップは実行されない

3. Maya に到達でき、initial_scene_open が true（デフォルト）の場合：

   • セッションで指定された Maya シーン（maya_scene と maya_base）を自動的に開く

   • 設定されていれば wait_seconds_after_scene_open 秒待機

   • 処理開始前にシーンが準備完了していることを保証

アップロードオプション

動画処理時に、次をアップロードできます：

• Animation（アニメーション）：フェイシャルアニメーションカーブ（ブレンドシェープ、コントローラ）

• Audio（オーディオ）：動画からのオーディオトラック

• Frames（フレーム）：参照用の動画フレームを画像シーケンスとして

• LM Frames：可視化用のランドマーク付きフレーム

シーン管理

• reopen_maya_scene：process ステップ前に Maya シーンを再オープンするかを制御。true = 常に、false = しない、省略 = 自動（いずれかのオーバーライドが存在し、かつ少なくとも1つのアップロードフラグが true の場合）。再オープン時はオーバーライドの maya_scene/maya_base がセッション値より優先されます。

• overrides.out_scene_path：処理後に Maya シーンを指定パスに保存

• overrides.out_playblast_path：処理後にプレイブラスト動画を指定パスに保存

• シーンパスはセッションの maya_base と maya_scene プロパティから解決されます

• Process ステップのプリフライト：各 process ステップの前に、適切なポート（オーバーライドまたはコンテキストから）で接続を再作成し、Maya に到達可能か確認するプリフライトチェックを実行します

タイムオフセット

time_offset_frames パラメータで、アニメーションが Maya タイムラインのどこから開始するかを制御できます：

• 正のオフセット：アニメーションが遅く開始（例：100 でフレーム 100 から開始）

• ゼロ：アニメーションがデフォルト位置（通常フレーム 0）から開始

• 注意：0 以上の値のみ許可

次のような用途に便利です：

• 複数テイクを1本のタイムラインにまとめる

• 既存のキーフレームとアニメーションを合わせる

• 間隔を空けたアニメーションシーケンスを作成する

トラブルシューティング

スクリプト検証が失敗する

問題：構造や型に関するエラーでスクリプト検証が失敗する。

対処：

• version: 1 が存在し、正確に 1 であることを確認

• context.session が空でない文字列であることを確認

• steps が空でないリストであることを確認

• 各ステップがちょうど1つのキー（process または sleep）を持つことを確認

• フィールドの型がスキーマと一致しているか確認（文字列、真偽値、整数）

Maya に到達できない

問題：MAYA_NOT_REACHABLE エラーでスクリプトが終了する。

対処：

• Maya が起動していることを確認

• commandPort が開いているか確認：Maya で cmds.commandPort(n=':42069', stp='python') を実行（または context.command_port で指定したポートを使用）

• ファイアウォール/ネットワーク設定で localhost 接続が許可されているか確認

• コンテキストでカスタム command_port を使っている場合、Maya の commandPort が指定ポート番号と一致しているか確認

動画処理が失敗する

問題：動画処理中に PIPELINE_ERROR が発生する。

対処：

• 動画ファイルが存在し読み取り可能か確認

• セッションに有効なソルバー設定があるか確認

• キャッシュ用の十分なディスク容量があるか確認

• 詳細なエラーメッセージはログを確認

アニメーションがアップロードされない

問題：アニメーションアップロードは成功するように見えるが、Maya に何も表示されない。

対処：

• Maya シーンに正しいキャラクターリグが読み込まれているか確認

• セッションと Maya シーンのコントローラ名が一致しているか確認

• Maya にアニメーションレイヤーが存在するか確認（デフォルト："BaseAnimation"）

• Maya スクリプトエディタで Python エラーを確認

ベストプラクティス

1. まず検証する：実行前に --dry-run でスクリプトを検証する

2. 明示的なパスを使う：信頼性のため絶対パスを推奨

3. 段階的にテストする：簡単なスクリプトから始め、徐々に複雑にする

4. Maya 接続を確認する：アップロード付き処理の前に Maya が起動していることを確認

5. タイムオフセットに注意する：重複を避けるためフレーム範囲を確認

6. スクリプトをバージョン管理する：再現性のためスクリプトをバージョン管理に含める

上級者向け

バッチ処理

複数動画を順番に処理する：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 0

  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_01_t00.mp4"
      upload:
        animation: true
      time_offset_frames: 1000

  - process:
      video: "D:/shots/take_03.mp4"
      upload:
        animation: true
      time_offset_frames: 2000

コントローラプレフィックス管理

処理前にコンテキストでコントローラプレフィックスを追加する：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"
  rename_controllers:
    prefix: "char_face_"
    action: "prepend"

steps:
  - process:
      video: "D:/Expo/Celllook/Facial/RecData/000_00_t00.mp4"
      upload:
        animation: true

条件付きシーン切り替え

動画に応じて Maya シーンを切り替える：

version: 1

context:
  session: "D:/Expo/Celllook2/FCS/Mao/Nike2/fcs_session.yaml"

steps:
  - process:
      video: "D:/shots/closeup_01.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/closeup_scene.mb"

  - process:
      video: "D:/shots/wide_01.mp4"
      upload:
        animation: true
      overrides:
        maya_scene: "D:/maya_scenes/wide_scene.mb"

サポート

問題、質問、機能リクエストについては、メインの FCS ドキュメントを参照するか、開発チームにお問い合わせください。