scenario-video-to-motion

シナリオ動画からモーションへ

概要

動画からモーションを生成するメンバーは、クリップ内の人物を解析し、3D アニメーションを返します。オートリグとアニメーションを適用したキャラクターメッシュ、または標準スケルトン上のモーションのみのいずれかです。これらは video23d 機能に該当しますが、共通の名称から想像するより違いがあります。入力として受け取るキャラクター、返されるスケルトン、出力するファイル形式がそれぞれ異なります。

関連スキル：scenario（接続、スコープ、アップロード、jobs_wait）、scenario-3d（メッシュの作成またはリギング）、scenario-video（映像がない場合に参照パフォーマンスを生成）、scenario-video-editing（クリップのトリミングとサイズ変更）。ここに記載した関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼します （npx skills add scenario-labs/skills --skill <name>）。無人で実行する場合は、ツールのスキーマをもとに作業を進め、不足しているスキルがあることを明記します。

クイックリファレンス

手順	呼び出し	注意点
入力をアップロード	kind: "video" を指定した upload_asset の後、メッシュには kind: "3d" を指定	すべてのメンバーでメッシュは任意です
クリップを調整	asset_get の後、scenario-video-editing に従ってトリミングまたはサイズ変更	メンバーごとの長さ、サイズ、偶数寸法の制限
メンバーを選択	ユーザー自身の言葉で capability: "video23d" を指定して recommend	scenario スキルに従って next_step を確認します
入力を確認	model_schema_get	各ファイルフィールドの kind と出力の列挙値
料金を確認して実行	dry_run: true、次に wait: false を指定して model_run	video フィールドが cost_impact を持ちます
待機して確認	jobs_wait の後、asset_display	向き、足の接地、フレーム数に注意します

メンバーを選ぶ前に出力を決める

出力は3種類あり、対応するメンバーもそれぞれ異なります。まずユーザーと相談して決めます（無人で実行する場合：プロジェクトが既存のリグに依存するキャラクターにはモーションのみを使用し、それ以外の場合はメッシュをアニメーション化します）。

• 自分のキャラクターにアニメーションを適用。 メッシュを受け取り、オートリグを適用してモーションを設定するメンバーです。リグはメンバー独自のもので、メッシュがすでに持つスケルトンにリターゲットしません。そのため、既存のリグ向けに作成されたクリップでは、ボーンのリマッピングが必要です。
• 名前付きスケルトン上のモーションのみ。 キャラクターをアップロードせずに、Mixamo 形式または MetaHuman のスケルトン上にアニメーションを返すメンバーです。キャラクターにすでにリグが設定されている場合に選びます。ファイルにテンプレートメッシュが含まれることがあります。内容を確認した後、ユーザーのリグにリターゲットする際はそのメッシュを省きます。
• メッシュ対応メンバーによるモーションのみ。 一部のメッシュ対応メンバーには、ダウンロードからメッシュを除外するアニメーションのみのフラグもあります。

recommend は測定済みのコストとレイテンシに基づいてメンバーをランク付けし、キャラクターを受け取るメンバーを示します。機能名だけを伝えるのではなく、上記の出力も含めてユーザー自身の言葉で問い合わせます。

スキーマをフィールドごとに確認する

メンバー間で同じフィールド名が異なる意味で使われているため、値を設定する前に各フィールドの kind を確認してください。

• あるメンバーの characterFile は3Dメッシュを受け取りますが、別のメンバーの characterFile はキャラクターの参照画像を受け取り、メッシュ用フィールドは characterModel です。受け取るアセットを示すのはフィールド名ではなく、フィールドの kind（3d または image）です。
• 出力形式はメンバーによって異なります。エンジン固有の FBX バリアント（fbx-blender、fbx-unreal、fbx-roblox、Maya シーンファイル）を書き出すもの、プレーンな glb または fbx（スキーマでは Unity 用に fbx と命名）を書き出すもの、形式フィールドがないものがあります。実行時にエンジンのターゲットを選択してください。asset_download の format 変換でアニメーションが維持されることは文書化されていません。
• FBX の書き出し形式は ASCII の場合があります。Blender の旧式 FBX インポーターでは読み込めないため、ASCII に対応した新しいインポーターを使ってください。ファイルを Blender 対応と判断する前に、読み込んだアニメーションを確認してください。
• 設定可能な場合に設定しておくとよい項目は、コードで駆動するゲーム内移動用の moveInPlace、サイクル用の loop、フレームレートのフィールド（frameRate、fps、または targetFps）、キーフレームの整理、動きの向きが回転していたり横倒しになっていたりする場合の forward 軸と up 軸です。
• 複数人を追跡するメンバー（numPeople）や、顔をキャプチャするメンバーもあります。どちらにも cost_impact が含まれます。

うまく撮影できる映像

• 1人だけを撮影し、クリップ全体を通して全身がフレーム内に収まっていること。足が見え、カメラが固定され、前を横切る人がいないこと。ゆったりした服や小道具は関節を隠してしまいます。
• 納品する動きだけにトリミングしてください。料金はクリップの長さに応じて決まり、メンバーごとに入力上限があります。作成時点では、あるメンバーは30秒かつ約30 MBに制限され、別のメンバーは幅と高さが偶数であることを求めていました。スキーマに max_duration と max_size があれば確認してください。上限の記載がないからといって、無制限に入力できるとは限りません。上限を超えるクリップは、料金を見積もる前に動画編集ツールで調整してください。
• 映像がない場合は、scenario-video に従って動画モデルで動きを生成します。無地の背景に全身のキャラクターを1人だけ配置し、カメラを固定して、動作をビートごとに説明してください。生成したクリップは、ほかの動画と同様に入力として使います。
• 動きの抽出は人間の動きを対象とします。クリーチャーや二足歩行ではないメッシュの場合は、フレームごとの確認が必要で、多くの場合 DCC での調整も必要です。

具体例：ゲームキャラクターにダンスの動きを適用する

ユーザーがダンスを撮影したスマートフォンのクリップとキャラクターの GLB を持っており、Unreal 対応のループを希望しています。

1. scenario スキルに従い、クリップ（kind: "video"）と GLB（kind: "3d"）を upload_asset します。
2. クリップに対して asset_get を実行し、長さとサイズを確認します。動画カットツールでループさせる8秒間にトリミングし、候補となるメンバーが求める場合は幅と高さが偶数になるようにサイズを変更します。
3. capability: "video23d" と、たとえば「この動画のダンスをアップロードしたキャラクターメッシュに適用し、ループさせて Unreal 用に書き出す」といったプロンプトを指定して recommend を実行します。scenario スキルに従って next_step に対応し、ask_user の選択肢を提示します。proceed の場合は、確認せずに選択内容を使ってください。
4. 選択したメンバーに対して model_schema_get を実行します。kind が 3d のフィールドに GLB を指定します。形式の列挙値に Unreal の出力先があれば設定し、loop: true を指定します。ゲーム側でキャラクターを動かす場合は moveInPlace: true も指定します。
5. dry_run: true を指定して model_run を実行し、料金を提示します。その後、wait: false で実行します。これらのジョブには数分かかります。完了したら jobs_wait で終了させ、タイムアウトした場合は pending_job_ids を指定して再度呼び出します。
6. 結果に対して asset_display を実行するか、DCC で開きます。向き、足が地面に接地しているか、ループ箇所で動きが途切れないかを確認してください。向きが違う場合は、撮影が原因だと判断する前に、スキーマで公開されていれば forward 軸と up 軸を確認します。プレビューリンクだけでは、見た目の確認にはなりません。
7. format を指定せずに asset_download を実行し、使用するスケルトンとともにファイルを引き渡します。

よくある間違い

• キャラクターの既存のリグにモーションを適用できると考える：メッシュメンバーは一から自動でリギングされます。リグを維持する必要がある場合は、モーションのみのメンバーを使い、リターゲットしてください。
• フィールド名だけで値を入力する：characterFileは、あるメンバーではメッシュ、別のメンバーでは画像です。
• ソース動画を全編送信する：クリップが長くなるほど料金が上がり、上限を超えるクリップは失敗します。
• 実行時にエクスポート先を設定せず、ダウンロードしたファイルを別の3D形式に変換する。
• 軸のフィールドを試す前に、横向きや上下逆さまの結果をキャプチャ失敗と判断する。
• jobs_waitではなくjob_getでポーリングする、またはタイムアウトしただけのジョブを再実行する。