scenario-video-color-grade

Scenario 動画カラーグレーディング

概要

ここで紹介するグレーディングはすべて、エージェントが数式を記述し、測定して調整するもので、生成モデルがピクセルに触れることはありません。ピクセル単位のカラー処理は 33³ の .cube LUT に焼き込まれ、ffmpeg が適用します。リライト、キーイングまたはマスクによる選択的カラー処理など、空間的な処理は LUT の前に numpy を使ってフレームごとに実行します。結果は正確で、すべてのフレームで同一になり、編集可能です。LUT は Premiere、After Effects、Resolve で読み込めます。フレーミング、動き、フレーム数は維持されるため、シームレスなループはシームレスなままです。

Scenario には、2 つのプリセット LUT ツールモデルと、選択的カラー処理を正確に行うためのセグメンテーションマスクがあります。新しい映像素材は対象外です。接続方法と基本的なループについては、scenario スキルを参照してください。長いクリップで LUT ツールモデルを実行する場合（コストはクリップの長さに応じて増加します。wait=false）：scenario-video-editing。リール用の音楽については、scenario-audio を参照してください。ここに記載された関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人実行の場合は、ツールスキーマに基づいて処理を進め、不足しているスキルを明記してください。

スクリプトはローカルで python3 を使って実行し、ffmpeg、numpy、scipy、Pillow が必要です。引数なしで実行すると、それぞれ使い方を表示します。--force を指定しない限り出力を上書きせず、Scenario を呼び出すこともありません。以下のパスは、このスキルのフォルダーからの相対パスです。

2 つの方法：Scenario のプリセット、または独自のレシピ

Scenario の 3D Color LUT ツールモデルは、1 つのプリセット（作成時点で約 150 種類）を不透明度（lutIntensity）で適用します。プリセットには、フィルムストックのエミュレーション、一般的なカメラのログ形式から Rec.709 への変換、プリントフィルム変換、クリエイティブなルックがあります。model_scenario-postprocessing-lut は画像を、model_scenario-postprocessing-lut-video は動画をグレーディングします。どちらの ID も固定です。それぞれの処理に対する Scenario の決定論的な専用ツールであるため、探索しても導き出せるのは同じものだけです。動画ツールはフレーム数とタイミングを維持します。

次の場合は、まずプリセットを使ってください。

• 映像素材がログ形式の場合。 カメラのログ形式に合ったプリセットを選んでください。ローカルの decode_log オペレーションは S-Log3 のみを読み取るため、このプリセットならより多くのカメラに対応できます。
• プリセットのルックが求められている場合（フィルムストック、プリントのエミュレーションなど）、またはグレーディングを Scenario 内で完結させる必要がある場合：ローカルの ffmpeg や Python を使えない場合、Scenario ワークフローのノードとして使う場合、多数の画像を処理する場合などです。

ルックを調整または新たに作る必要がある場合、位置に応じた処理（マスク、リライト、ビネット、グレイン、ハレーション）が必要な場合、参照画像に合わせる場合、.cube ファイルとして納品する場合、またはリールに使う場合は、レシピを作成してください。ツールモデルで使えるのは各モデル独自のプリセットのみで、カスタムの .cube は使えません。2 つの方法は組み合わせられます。Scenario でログ形式を変換し、その Rec.709 出力を decode_log を除いたレシピでグレーディングします。

プリセットを実行する手順：

1. 両方の ID で model_schema_get を実行し、lutStyle の許可値を確認してください。推測で選ばないでください。動画ツールにも記載されている値だけを候補に絞ってください。
2. 画像ツールを使って、1 枚の静止画に 2〜3 種類のプリセットを試してください。名前からプリセットが想定する入力はわからないため、同じフィルムストックのプリントエミュレーションを 2 種類試すなど、似たものを並べて比較してください。
3. クリップを upload_asset でアップロードし、model_run と dry_run=true で料金を確認してから、選んだプリセットを実行し、jobs_wait、続けて asset_download を実行してください。
4. 結果を ffprobe で確認してください。作成時点では、動画ツールが MPEG-4 Part 2 を返す場合がありました。ウェブ用に再エンコードするには、次を実行してください。 ffmpeg -i in.mp4 -c:v libx264 -crf 18 -pix_fmt yuv420p -movflags +faststart -c:a copy out.mp4

クイックリファレンス

• render_looks.py：動画にルックを適用します（ルックごとにMP4を1本作成し、音声をコピーします）。または1フレームに適用します（PNGの静止画とラベル付きの grid.jpg を作成します）。さらに luts/<key>.cube を書き出します。
• inspect_frame.py：grid（ピクセル座標）、sample（矩形領域の色相、彩度、明度のパーセンタイル）、key（選択キーで保持される領域を赤く重ね、ブロブのサイズを表示）を実行します。
• match.py：match オペレーション用に参照画像を測定します。CIE LabでReinhard変換を行います。
• showreel.py：すべてのルックを紹介するリールを作成します。名前を入力して表示するパネル、1本の連続したクリップ上のワイプ、グリッドのエンディング、任意のエンドカードと音楽が含まれます。
• grade.py、spatial.py、media.py：カラーオペレーションとLUTライター、リライトとキーイング、ffmpegのI/Oを提供します。上記のスクリプトからインポートされます。
• looks_library.json：デイ・フォー・ナイト、キーイングによる白黒、参照画像へのマッチング、4種類のリライトプリセットを含む、調整済みの初期ルック21種類です。
• looks.json：調整済みのルック12種類です。マスクベースの白黒、カラーのルック1種類、事前に match.py の実行が必要な参照画像へのマッチングが含まれます。
• ops.md、looks.md、keying.md、relight.md：すべてのオペレーション、各ライブラリルックの構成方法、キーとマスク、リライトについて説明します。

手順

1. ソースを確認します。 ffprobe で調べ、異なるタイミングから3〜4フレームを取り出します。ログ映像（白っぽく、フラット）、通常の映像、すでにカラーグレーディング済みの映像のどれかを確認します。ルックは、柔らかく少し彩度を抑えたソース向けに調整されています。コントラストが強いソースでは、彩度とコントラストを約3分の1下げてください。光の向きと、主なオブジェクトの色を確認します。
2. looks.json を設定します。 ライブラリまたはサンプルセットをクリップの隣にコピーし、ルックを残す、名前を変更する、追加する、削除するなどして調整します。各ルックには name と settings（リールに表示する2行のラベル）があり、relight、selective、LUT に焼き込まれる ops、および vignette、grain、halation を任意で設定できます。これらは記載順に適用されます。キーは出力の並び順を決めます。_ で始まるキーはメモです。
3. 動画の前に静止画でテストします。 python3 scripts/render_looks.py clip.mp4 --looks looks.json --out still_test --frame 40 を実行し、grid.jpg を開きます。すべてのルックがソースと異なり、白飛びや肌のオレンジ化がなく、スタイライズされたルック以外では肌が自然に見えることを確認します。ここで調整を繰り返しましょう。静止画の処理は数秒ですが、レンダリングには数分かかります。動きのあるクリップでは、2つのフレームをテストします。
4. キー付きルック：測定してからプレビューします。 フル解像度の座標を確認するには inspect_frame.py grid を使います（静止画テストの grid.jpg のタイルは縮小されています）。オブジェクトと、その色が共通するもの（肌、唇、地面）を sample で調べてから、key ... --frame 10 90 160 を実行してオーバーレイを確認します。グレーのフレーム上の赤色は、保持される部分を示します。色相ではなく、明るさや彩度が分離の決め手となることがよくあります。正確な結果を得るには、オブジェクトマスクを使います（動作する例を参照）。
5. リライトは0.3〜1ストップの範囲で、すでにハイライトがある側から行います。光の特徴は変わりますが、形状や落ち影は変わりません。その旨をユーザーに伝えてください。
6. 参照画像に合わせます。 python3 scripts/match.py clip.mp4 reference.jpg match/reference.json [--crop w:h:x:y] を実行し、続けて {"op": "match", "stats": "match/reference.json"} を使います。ソースが変わるたびに測定し直してください。同じ種類のシーンを別の時間帯に撮影した映像に合わせると、時間帯が変わったような説得力のある仕上がりになります。
7. レンダリングします。 python3 scripts/render_looks.py clip.mp4 --looks looks.json --out renders [--only k1,k2] を実行します。
   • 色のみのルックは、そのまま ffmpeg で処理されます。
   • 作成時点では、リライトとキー処理を含むルックの処理時間は1080pのフレームあたり約1〜2秒でした。そのため、長いクリップはバックグラウンドで実行してください。
   • マスクまたはマッチ用統計データがないルックは、メッセージを表示してスキップされます。
   • 各レンダリングのフレーム数がソースと一致することを確認し、キー処理とリライトを行ったレンダリングを通して確認して、ちらつき、肌、エッジをチェックします。
8. リール（任意）： python3 scripts/showreel.py --renders renders --looks looks.json --source 00_ungraded --out reel.mp4 --order k1,k2 --music track.mp3 を実行します。 ドラマチックなルック（デュオトーン、ノワールなど）は2番目か3番目に配置し、きれいにループするクリップを選ぶことをおすすめします。リールの音楽は約-18 LUFSに正規化されます。デフォルトではリールにブランド表示は入りません。ユーザーから依頼があった場合に限り、独自の --credit テキストか --logo（白色の透過PNG）を指定してエンドカードを追加してください。
9. 納品します。 レンダリング、renders/luts/*.cube（Premiereでは Lumetri、Creative、Look）、グリッド、リールを納品します。ルックの名前には空間的な要素を含めてください。LUT単体では色しか扱わないため、編集者にはマスクも必要です。

作例：白黒に、色を残したオブジェクトを1つ

カラーグレーディングはローカルで行います。Scenario から取得するのはマスクだけで、マスクの作成処理によってピクセルが変わることはありません。

1. ユーザーの言葉でニーズを指定して recommend を実行します。たとえば、「動画のすべてのフレームで、1つのオブジェクトをセグメント化する」などです。動画セグメンテーション対応のメンバーを選び、model_schema_get でスキーマを取得して、そのスキーマに基づいてパラメーターを作成します。
2. カラーグレーディングするクリップそのものを upload_asset します。model_run を dry_run=true で実行して料金を確認した後、オブジェクトごとに短い名詞句をテキストプロンプトとして指定し、1回ずつ実行します（「赤いレザージャケット」、「赤い給油ポンプ」）。jobs_wait を実行し、各マスク動画を asset_download で masks/ にダウンロードします。
3. マスクの輪郭を、フル解像度のフレーム2～3枚に重ねて確認します。マスクのフレーム数はクリップと一致している必要があります。
4. ルックに selective ブロックを指定します。key を含むマスクエントリは、オブジェクト内の指定した色だけを残します。そのため、赤いポンプの白いパネルはグレーのままになります。

"selective": {
  "masks": [{"path": "masks/jacket.mp4"},
            {"path": "masks/pump.mp4", "key": {"center": 11, "width": 18, "min_sat": 0.28, "max_val": 0.62}}],
  "weights": [0.3, 0.55, 0.15], "sat": 1.7, "val": 1.05
}

5. まず静止画でテストし、その後レンダリングします。色を変更する（赤から金色にする）には、同じブロックに "shift": 34 を追加します。

作成時点では、8秒のループに12種類のルックを適用する場合、マスク2つとリールの音楽を合わせて112 CUかかります。カラーグレーディング自体には費用がかかりません。

よくある間違い

• プリセットですでに対応しているレシピを作る。 ログ変換やフィルムストックのエミュレーションには lutStyle プリセットがあります。まずそちらを確認してください。
• 動画LUTツールの出力を確認せずに納品する。 MPEG-4 Part 2 を H.264 に再エンコードしてからウェブで使用してください。
• 色を1色だけ残すのに、カラーキーだけを使う。 肌、唇、暖色系の背景はオブジェクトと色が似ているため、縁に色が残ることがあります。オブジェクトの近くに肌がある場合は、オブジェクト内にキーを適用する際にマスクを併用してください。
• 色相だけでキーを設定する。 暖色の空を反射する青緑色の車には青緑色のピクセルがほとんどなく、唇は赤いジャケットと色相が似ています。明るさや彩度で分離し、min_area を設定してプレビューしてください。それでも色が漏れる場合は、マスクが必要だとユーザーに伝えてください。
• ヒューリスティックな領域マスク（「空だけを変更」など）。 髪、柱、モーションブラーなどが入り込みます。代わりにグラデーションフィルターか、参照画像へのマッチングを提案してください。
• あるソースでの調整を別のソースに使い回す。 新しいソースごとに静止画テストをやり直してください。
• ルック名に商標を使う。 公開名には映画のタイトルやフィルムストックのブランド名を含めず、「Scorched Desert」や「Vintage Slide」のような説明的な名前を使ってください。
• 動画より音声がわずかに短い場合に -shortest を使う。 ffmpeg が最後のフレームを削除し、ループが途切れます。スクリプトではこの指定を避けています。カスタムコマンドでも同様にしてください。
• カラーグレーディングだけを行う。 カラーグレーディングは好みによるものです。グリッドや短いプレビューを見せ、ユーザーの指摘に沿って調整してください。