scenario-blender-blockout

レンダーから実写映像への変換用ブロックアウトをBlenderで作成する

ブロックアウトはガイドクリップです。動画モデルはカメラの動き、フレーミング、レンズの印象、イージング、カット位置、ショットの長さ、すべての形状の位置とスケール、人物の向きとすべての軌道を模倣し、残りの要素（マテリアル、光、天候、各プロキシの実体、顔、衣装、エキストラ、音）はテキストと画像から生成します。そのため、ブロックアウトが全面的に決定するのは動きとレイアウトであり、見た目には一切関与しません。曖昧さは変換を台無しにしますが、粗雑さは問題ありません。曲がった街灯はヘビとして生成され、ばらばらの手足のブロックは人が増えたように見え、車には逆走させてしまいます。まずジオメトリで何を表すかを明確にし、次にプロンプトのテキストで補い、プレイブラストと動画を同期させて並べた状態で結果を評価してください。ビューポートだけで判断してはいけません。ここで名前が挙がっている関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で進める場合は、ツールのスキーマに基づいて作業し、不足しているスキルを明記してください。

必須の事前知識： scenario-blender-expert（実行チャネル、レビューループ、5.2 API の変更点）。 動画生成：scenario-blender（プラグインの見積もり、生成、配置のフロー）、scenario スキル（接続、アップロード、ジョブ）、scenario-seedance（参照動画のフィールド）。

ツールキット：scripts/bx_blockout.py： import sys; sys.path.insert(0, "<this skill>/scripts"); [sys.modules.pop(m, None) for m in ("bx_blockout", "bx_kits")]; import bx_blockout as B。 <this skill> はインストール先フォルダーの絶対パスです。pop により、前回の実行で Blender の単一 Python 環境に残されたコピーが削除されます。ビルダーは名前で取得または作成されるため、同じ呼び出しを再度実行できます。また、ユーザー自身の作品ですでに使われている名前は拒否します（名前はファイル全体で一意です）。監査の結果が空であれば合格です。呼び出しの順序はモジュールの docstring に記載されています。 scripts/bx_kits.py（import bx_kits as K、同じルール）では、建物、屋台、木、街灯、岩、車両を3段階の精度で、人物を4種類のキャストスタイルで追加できるほか、群衆、交通、配色、K.audit_budget も利用できます。簡単なものから専門的なものまで、レンダーパスの結果を含む4つの作例シーン：例（ハーネス、1、2、3、4）。

どのスキルを使うか。 このスキルは動画モデル向けのガイドを扱います。監督と編集者が評価するストーリープレビズやアニマティックには、scenario-blender-previs-storyboard を使います。承認済みのアニマティックを動画モデルのガイドとして使う場合は、ここで作り直します。

1. 要件をビルド計画として整理する

呼び出しを行う前に、次の内容を書き出します。

• 要素とその基本形状：「バス＝前面が示された長い箱」、「人物＝色付きのカプセル」。要件に記載されている範囲を超えてモデル化しないでください。
• 寸法：すべてメートル単位で記載します。要件に指定がない場合は、契約表から引用したことを明記します。
• フォーマット：整数の fps、アスペクト比、秒数を記載します。範囲は 1 から fps × 秒数までです（24 fps で 8 秒の場合は 1..192）。
• ショット：数、動き、レンズ、フレーミングの不変条件（「主役は常にフレーム内に収め、全身を映す」）、カットスタイルを記載します。ビートは秒単位で指定し、すぐにフレームへ換算します。
• レベル：密度（シンプル、ミディアム、アドバンスド、エキスパート：設置面積、要素、主役、エキストラ、ショット）、忠実度（ラフ、シェイプ済み、詳細）、配色を要件から読み取り、レベルとは分けて設定します。要件に指定がない場合（主役やショットの名前だけが示されている場合も指定なしに該当します）は、アドバンスド、シェイプ済み、カテゴリ別カラーとし、その旨を明記します。シンプルまたはミディアムに下げるのは、1 か所に登場人物が 1 人だけの場合に限ります。エキスパートは、多くの要素、動く要素、カットを意味し、ブロックをより細かくすることではありません。
• 動画モデル：ここで決めます。キャストスタイルとプロンプトの文法は使用するモデルによって異なります（プラグイン経由では list_models、ホスト型ルートでは recommend を使用します）。
• キャストスタイル：キャラクターごとに選びます（キャスト）。手足のある代役は、モデルに模倣する歩き方を示します。手足のない代役では、モデルが体と動きを自由に作り出します。主役には色付きのカプセルをデフォルトとします。キャラクターを見分けやすくする必要がある場合や、ストーリー上の小道具を持たせる場合は、特徴的な要素を 2〜3 個加えます（ゴーグル、フード、手持ちランタンなど）。ブロックアウトに手足の動きを明確に反映させる必要がある場合に限り、リグ付きのグレーのマネキンを使います。選んだスタイルと、それによって制御性がどう変わるか、他のスタイルも短い区間で A/B テストできることをユーザーに伝えます。
• 識別色：主役は赤、続いて青、緑、黄、紫、シアンです。
• 動画モデルに補完させる意図的な空白と、要件に記載された受け入れテストを確認します。これらは必須の監査項目になります。

要件で未確定の事項を判断し、その決定を記録します。質問して作業を止めないでください。例外は費用です。Scenario の料金は提示し、ユーザーの承認を得ます（セクション 3）。参照画像がある場合は、そこにある大きな形状を列挙し、妥当なスケールでブロック化し、カメラの高さとレンズを合わせます。カメラから render_still を実行し、構図を比較して一致するまで調整してから、アニメーションを付けます。

2. 出力仕様

成果物は4つです：シーン、ロック済みのカメラタイムライン、プレイブラスト、引き継ぎシート。

• シーンの整理。 ロールプレフィックス（ENV_、FIG_、PRP_、CAM_、CRV_、RIG_、NULL_target_、仕様書に記載されている全項目）、1つのルートコレクションとロール別のサブコレクションを使用します。デフォルトの Cube、Light、Camera は B.park で退避させ、削除しないでください。ファイルに別の作業が含まれている場合は、新しいシーン（B.make_scene）で作成し、既存のものには一切触れないでください。すべてのオブジェクトが、いずれかの工程に由来している必要があります。
• スケール。 メートル単位、Z 軸が上、地面は z = 0、フィギュアのルートは足元に配置します。モデルは、誤りも含め、各マスを現在の大きさのまま維持します。スケールの目安として既知の物を置かず、REF_ フィギュアを追加してください。
• 色でマスを区別し、アイデンティティを示します。 主役ごとに彩度の高い色を1色（B.PALETTE、ヒーローは赤）、セットには1つの K.scheme（デフォルトではカテゴリ別の色相、アイデンティティ用グレー、またはマテリアルカラー）、脇役には中間グレー、ライトは1つ、ワールドは暗色にします。B.paint とキットはオブジェクトカラーとマテリアルを設定します。キットには複数の色があるため、ソリッド表示ではカラータイプに Material を指定する必要があります（B.solid_view() のデフォルト、およびプレイブラストの設定）。プレイブラストがすべてグレーなら、アイデンティティが失われています。キットの色を変える場合は引数を使ってください。マテリアルは色ごとに共有されます。カメラが移動し、奥行きを読み取る必要がある場所に限り、グリッドまたはチェッカーテクスチャを使い、シートに「置き換え、継承しない」と明記してください。
• タイムライン。 ジオメトリを作成する前に B.lock_format を実行します。整数 fps、フレームは1から fps x 秒数まで、解像度は1920x1080（21:9の場合は2520x1080）、スケールは100 %です。ショットごとにカメラを1台使い、最初のフレームにある CUT_ マーカーへ紐付けます（B.bind_cuts）。カットはハードカットとし、トランジションのフレーム数は0にします。
• カメラリグ。 レールの場合は B.rail_camera を使います（カーブ、Follow Path 上のドリー、Track To による照準、カメラ）。手持ち追従撮影、直線的なプッシュイン、複数ショットのマスターについては、仕様書のレシピを使います。構図を調整するときは、カメラを回転させず、照準ターゲットを動かしてください。
• レンズ。 ショットサイズに応じて、ショットごとにレンズを1つ指定します（B.lens_for_coverage。周回撮影は28 mm、オーバー・ザ・ショルダーは42～45 mm、室内は24～30 mm、マクロは85 mm）。clip_start は0.05にします。カットでレンズを変える場合はカメラを切り替えてください。カットのフレームでレンズをステップ状に切り替えてはいけません。ショット内ではレンズを滑らかに変化させてもかまいません（意図的なズーム）。急に切り替えてはいけません。
• イージング。 自動クランプされたハンドルを持つベジェキーを使います（B.smooth_keys）。速度はレール上のキー間隔で調整します（B.key_rail）。停止させるには、ほぼ同じ値を2つ設定します。LINEAR は、フレームごとにベイクした移動（車両、車輪）に限り使用します。キーはすべてのカットを越えて動作するよう設定し、境界で停止しないようにします。
• 手持ち撮影には NOISE F カーブモディファイアーを使い、ジッターにキーを打たないでください。B.audit_handheld で仕様書の予算に照らして結果を計測します。animation_data_clear() はモディファイアーを削除するため、キーを打ち直した後に再追加してください。

3. チャンネル：プラグインまたはヘッドレス

実際に使うチャンネルは、プラグインのローカル Scenario MCP サーバーである scenario-blender です（blender.scenario.com のガイドでは、プラグインを Scenario for Blender と呼んでいます）。ツール一覧、呼び出し制限、タイムアウト後の復旧方法については、プラグインを参照してください。最初に注意すべき点は次の2つです。ユーザーが Allow connected agents to run Python を有効にするまで execute_python は無効です（PermissionError が出たら、ユーザーに許可を求めます）。また、呼び出しは120 sで終了するため、1回につき1ステージ分だけ送信し、各ステージの後に B.stage_backup(label) を実行します。

プラグイン独自のツール（プラグイン）：有料の Blockout は、人物、カメラ、アイデンティティカラーのない汎用的な Stage 2 のセットに適しています。camera_path では静止した中心を基準に1ショットのキーを設定できますが、追跡や複数ショットには対応していません（B.rail_camera）。動画パスには Render Video を使います。

ヘッドレスでプラグインを使わない場合は、scenario-blender-expert のヘッドレスヘルパーを使って各ステージを実行します。前の .blend を読み込み、B.guard で確認してから拡張し、次のステージ用に新しい B.stage_backup(label) を保存します。examples harness は、factory startup から一度きりのビルドを行うためのものです。start() は前のステージを含むすべてのオブジェクトを削除します。バックアップからの再開にこれを再利用しないでください。120 s の制限はプラグインのみです。

4. ビルドの順序

各ステージの後にバックアップを作成します。リセットが起きた場合は、最後のバックアップから復旧します（契約）。すべての呼び出しまたはステージスクリプトは B.guard(expected_file=..., scene=...) から開始します。キューに入れた呼び出しは、現在開いているファイルで実行されます。

0. プローブ、読み取り専用：scene_summary、datablocks_summary（ヘッドレス：bpy.data）。他の作業が存在する場合は、新しいシーンを作成します。
1. フォーマットと足場：B.make_scene、B.lock_format、B.collection のツリー、B.park、暗いワールド。
2. セット：選んだ精度のキット（K.building、K.stall、K.tree）か、実寸の厚いボックス（B.box）を配置し、繰り返しはリンク複製（K.instance）にします。または、汎用セットにはプラグインの Blockout を使います。
3. 人物：選んだキャストスタイルで各主役に K.figure(..., style=, features=) を使い、ルートを足元に置き、移動方向を向かせます（キャスト）。(frame, position) のテーブルから K.walk_path で移動させます。歩行時のストライドは身長の0.42倍、走行時は約0.7倍です。ジェスチャーには K.pose、エキストラには K.crowd(style=...) を使います。
4. 小道具と車両：実際の位置にプリミティブを配置します。車両の前部はジオメトリで示します（前部にライトブロックとグリル、後部に濃い赤）。車輪は z = 半径の位置に配置し、接写で回転が分かる場合に限り、独立した1つの回転チャンネルを使います（キットの車輪は車体メッシュです）。人物の近くに固定されていないブロックを置かないでください。
5. 照明：エリアライトを1つ使います。ブリーフで照明設計が指定されている場合に限り、キー、フィル、リムを命名して使います。
6. カメラ：ショットごとにリグとレンズを設定し、B.bind_cuts を使います。
7. モーションの仕上げ：B.key_rail と B.smooth_keys、カット後のキー、手持ち撮影風の動き、フレームごとにキーを設定した単調な曲線での車両移動を使います。
8. 監査（セクション5）：問題がなくなるまで行います。セットの装飾で主役が隠れる場合は、遮るものを移動し、カメラプランは維持します。
9. 最終化：フレーム1、ショット1のカメラ、B.audit_frames、B.state_audit、最後のバックアップを行ってから、プレイブラストと引き継ぎ用シートを作成します。

5. 監査：まず数値で判定し、その後に目視します

チェック項目	ヘルパー
フレーム計算と解像度	B.audit_frames(seconds, fps)
マーカーの範囲、切り替わり、レンズ、ジャンプ	B.audit_cuts()（ブリーフでレンズを統一する場合は same_lens_across_cuts=True）
ショットごとの被写体のフレーム内表示	全身像の場合は B.audit_framing({"CAM_s1": ["FIG_red"]}, whole=True)
頭部が隠れていないこと	B.audit_occlusion("FIG_red")
近すぎる、または許容範囲外	B.audit_distance(subject, volume=...)（全身ショットのみ）
相互貫通	B.audit_intersections(names)
足と車輪が地面に接していること	B.audit_ground(names)
手持ち撮影の振幅	B.audit_handheld("CAM_s1")
引き渡し前の総数確認	B.state_audit()

各ショットの対象物そのものを監査します（マクロ撮影なら車輪、インサートなら手です）。その後、目視で確認します。 各ショットの最初、中間、最後のフレームで set_frame と render_still を実行し、数値では見落とす点をチェックします。車両の前部、接続された人物、曲線的な形状のない剛体の小道具、フレーム端に余計なものがないこと、そしてオープニングと同じように最後の画がしっかり固定されていることです。しきい値と判定結果については、監査を参照してください。監査は step フレームごとにサンプリングします。長いショットでは、呼び出し制限を超えないよう step を大きくします。

6. プレイブラスト、引き継ぎシート、動画生成

プレイブラスト。 最新の B.stage_backup コピーを使い、ヘッドレスで、scenario-blender-expert の bx_review.playblast(out_path, res_pct=100) を実行します。WorkBench でシーンカメラを使い、バインドされたマーカーに従ってカットを切り替えながら、フレーム範囲を H.264 MP4 にします。セッションのバイナリ（bpy.app.binary_path）を使ってください。PATH 上の古い blender ではファイルを開けません。シェルが使えない場合、同じ処理を execute_python 経由で呼び出すと、レンダリング中は Blender がブロックされます。短いクリップにとどめ、タイムアウト後は再実行する前にファイルがないか確認してください。各ショットの開始、中間、終了時のカメラ静止画を追加します。

引き継ぎシートはシーンから作成します（テンプレート）。参照画像に対応する色の凡例、K.cast() の行、正確な時刻を含む B.cut_list() のカットリスト、ブロックされているエンティティと言葉だけで存在するエンティティ、タイムコード付きのすべての成果物、各モーション状態の言葉による説明（「ゆっくり進む」「静止している」）、および優先規則（「テキストと動画でモーションが食い違う場合は、動画を優先する」）を記載します。

動画生成は、ユーザーが正確な料金を承認した後に限り、必ず Scenario 経由で行います。無人で実行する場合は見積もり（estimate_cost または dry_run）の時点で停止し、料金を報告します。また、ユーザーによるファイル選択が必要なローカルアップロードはスキップします。

• プラグインの Render Video レーン：キャプチャに識別色を表示するため B.solid_view() を使い、force_solid は false にします（すべてが単色のグレーになります）。モデルが受け付ける長さにタイムラインを設定してから、handoff の Route 1 に従い、list_models、model_schema、render_form（parameters を {"duration": <clip seconds>} にして configure、続いて prepare、inspect）、estimate_cost、generate、wait_for_job、結果の適用を順に実行します。キャプチャは無音の 1280x720 クリップです。
• ホスト型 Scenario MCP。フル解像度のプレイブラストに使用します。scenario スキルの手順に従ってプレイブラストをアップロードし、参照動画を受け付けるモデルを探し、まず dry_run を付けて model_schema_get、model_run を実行し、続いて jobs_wait、asset_download を実行します。

プロンプトはモーションを最優先にして書きます。クリップはリハーサル映像として扱い、キャストはプロキシの形状ではなく役割とモーションで説明します。スタイルは、再スタイル化した 1 フレームではなく、4 パネルのスタイルボードから指定します。カプセル状のキャストには、スタンドインに関する条項（カプセルは位置、高さ、速度、向きのみを示す）と歩行に関する条項を追加します（cast）。プラグインのレーンでは、プラグインがクリップと画像の役割を自ら指定するため、look にはキャストとスタイルだけを記載します。文法、条項、テスト済みの制限については、handoff を参照してください。

実例

概要：「10 秒、24 fps：倉庫で赤いランナーが木箱の列の間をカメラに向かって疾走する。6 秒時点で青い警備員が姿を現す。35 mm で手持ち撮影しながら後退する。」

1. scene_summary {"fields": ["type"], "limit": 100}：ファイルには別の作業が含まれているため、その隣に作成します。
2. execute_python：B.make_scene("BLK_warehouse") を実行します。次の呼び出しで B.guard(scene="BLK_warehouse")、B.lock_format(24, 10)（1..240）、コレクション、バックアップを作成します。
3. 床を 34 x 20 m、壁を 7 m にし、B.box で高さ 1.2 m の木箱を 2 列配置してから、バックアップします。
4. K.figure("red", 1.8, (0, 15, 0), style="featured", features=("hood",)) を実行し、続いて K.walk_path でフレーム 200 までに (0, 1) へ移動させます。疾走に合わせた歩幅は 1.3 m とします。青い警備員はカプセルとして、フレーム 144 から 156 にかけて通路に入ります。バックアップします。
5. B.rail_camera("s1", [(0, 3, 1.5), (0, -1, 1.5), (0, -4, 1.5)], follow="FIG_red", target_offset=(0, 0, 1.2), lens=35)、B.key_rail("RIG_dolly_s1", [(1, 0), (260, 1)])、B.bind_cuts([(1, "CAM_s1")]) を実行し、予算内で手持ち撮影のノイズを加えます。
6. B.audit_frames(10, 24)、B.audit_cuts()、 B.audit_framing({"CAM_s1": ["FIG_red", "FIG_blue"]}, whole=True)、 B.audit_occlusion("FIG_red")、B.audit_handheld("CAM_s1") を実行し、問題がなくなるまで木箱を移動します。
7. set_frame を 1、120、240 に設定し、それぞれ render_still を実行して確認します。バックアップを取り、ヘッドレスでプレイブラストを作成し、B.cut_list() をシートに反映します。

よくある間違いと後続工程での誤読

• 形状だけでは識別できない：浮いた頭部や板状の腕、人物の近くにある無造作なブロックは追加の人物に見えます。前面が示されていない車は後退しているように見えます。不透明な車内の乗員は見えなくなるため、車内にアルファ値を設定します。
• カメラの文法：カットフレームでキーを設定すると、その位置で動きが止まります。頭上からのオービットはカットに見えます。反対側のカメラでは座席が反転して見えます。会話中に存在しない逆方向のショットが作られます。最後の数秒でカメラがドリフトします。
• 曖昧な動き：ゆっくりしたプロキシの動きは、回転しているようにも静止しているようにも見えます。シートで判断します。
• 手足の複製：参照動画モデルでは、段階的またはループする脚の動きが、硬直したり、足並みをそろえたり、滑ったりして再現されます。そのキャラクターをカプセルに切り替えます（cast）。
• 壊れやすいディテール：ピクセル未満のパーツは、スタイル変更のたびに識別性が変わります。文字を連想させるスタイルでは、意味不明な文字が生成されます。
• 開始フレームの虚構：「ドアから始まる」には、フレーム1の背後に出入り口が必要です。平坦な地面を見下ろす高いカメラ位置では、地面も平坦に見えます。
• 状態のドリフト：レンダリングの確認後に解像度やファイルパスが変更されたままになります。既存のオブジェクトが自分のものとして扱われます。Blender 5では、スロットに割り当てられたアクションによってFカーブが隠れるため、B.fcurvesを使用します。