scenario-blender-grease-pencil

Grease Pencil（v3、Blender 5.2）

熟練した Grease Pencil の制作では、すべてのドローイングを編集・描き直し可能な状態に保ち、構造（どのオブジェクトか、どのレイヤーか、どのキーか）に意味を持たせ、動きの中で結果を判断します。エージェントはデータ API（ドローイングは属性を持つカーブです）を通じて描画し、2D スタジオでリグを組むのと同じ方法でキャラクターを構築し、フリップして確認できないビューポートではなく、レンダリングしたフレームを確認します。ここに記載された関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください （npx skills add scenario-labs/skills --skill <name>）。無人で作業を進める場合は、ツールスキーマを参照して作業を続け、不足している点を明記してください。

必須の背景知識： scenario-blender-expert（実行チャネル、レビューループ、5.2 API の変更点）。 ショット計画、絵コンテ、アニマティクス：scenario-blender-previs-storyboard。メッシュアニメーションの原則： scenario-blender-animation。

ツールキット：scripts/bx_gp.py（5.2.1 でテスト済み）。 import sys; sys.path.append("<this skill>/scripts"); import bx_gp as G

姿勢（エキスパートとしての違い）

• Tom Viguier（Andarta、『Ewilan's Quest』）：リグは決して描き直しを妨げてはいけません。 物理的な要素ごとに GP オブジェクトを 1 つ（主役キャラクターなら約 60 個）用意し、親子付けして、主にオブジェクト変換で FK を行います。各要素内のレイヤーはグラフィック上の役割（線を塗りの上に配置）に応じて構成し、変形にはスカルプトを使います。ドローイングにアーマチュアのウェイトペイントは行いません。描き直すたびにウェイトを新たに設定する必要があるためです。
• Tom：「スカルプト済み」のペアだけを補間します。 2 つのキーをきれいに補間するには、ストロークの数、順序、色、および各ストロークの点を一致させる必要があります。そうでなければ描き直すか、歪みを受け入れるのではなく、最も近いドローイングに「クリップ」します。ネイティブの補間はオブジェクトのアニメーションを無視するため、変換は別途キー設定します。
• Falk David（GP モジュールリード）：塗りはマテリアルではなくジオメトリです。 fill_id != 0 の場合、ストロークは塗りつぶされます。同じ ID のストロークは偶奇規則で穴を含めてまとめて塗りつぶされ、hide_stroke は輪郭を非表示にします。マテリアルの塗りつぶし切り替えは非推奨で、ホールドアウトの「消しゴム塗り」（Grant Abbitt の 4.4 の手法）は廃止されています。
• Grant Abbitt：レイヤースタックが意味を持ち、マテリアルは絵の具のバケツです。 線を最上部に置き、中間に影レイヤー（乗算、低めの不透明度、塗りでマスク）を置き、最下部に塗りを置きます。マテリアルを編集すると、そのマテリアルを使うすべてのストロークの色が変わります。編集中でないものはロックします。消しゴムとスカルプトは、ロックされていないすべてのレイヤーに作用します。
• Elijah Sheffield：まず色を確実に再現できるようにします。 標準のビュー変換、フラットな無照明シェーディング、白いワールドを使います。確認済みの落とし穴：新しいレイヤーでは use_lights=True になっており、ライトの影響を受けるレイヤーはワールドノードツリーではなく World.color（デフォルトは 0.05）から環境光を取得するため、フラットなパレットは指定値のおよそ 4 分の 1 の明るさでレンダリングされます。
• Tom：マルチプレーンの規律を守り、まずレイアウトを固めます。 すべての 2D 要素をカメラと平行に配置し、カメラの軸は決して変更せず、時間を節約できる場合に限って 3D を使います。カメラ、カット、パララックスはコンポジットで見つけるのではなく、レイアウトの段階で確定します。オブジェクト間では、奥行きによってどちらが手前に描画されるかが決まります。
• Michael Weigl：動きによって表面の問題が明らかになります。 絵画的な静止画は、動かすと破綻します。2.5D はシーケンスとして評価します。個々のストロークではなく、ストロークのグループ（メッシュアイランド）をソートし、プロシージャルな出力は編集可能なストロークにベイクします。
• Pablo Fournier（Blender Studio）：影をデザインします。 ぼんやりとした 3D シェーディングを、ブロック状に描いた光と影の形（パーツごとにライト用とシャドウ用のマテリアル）に置き換えます。塗りはフラットです。曲面では、1 つの大きな塗りを前方に押し出すのではなく、小さな塗りをたくさん使います。

最初に決めておくこと

入力項目	変更内容	指定がない場合のデフォルト
成果物	静止画、フレームごとのショット、カットアウトリグ、ハイブリッドモーショングラフィックス、3D上の2.5D	フレームごとのショット
フォーマット	解像度、fps、長さ	1920 x 1080、24 fpsで2コマ打ち［追加］。ソーシャル向けモーショングラフィックス：1080 x 1920、12 fps、60フレーム（Elijah）
ルック	フラットまたはライティングあり、線のシステム	フラット（ライティングなしのレイヤー、Standard）。インク線、筆圧に応じて先細り
線のシステム	PEN：一定の幅（Line Art、Elijahと同じ）、INK_PEN：半径に筆圧を反映（カートゥーン調、Grant）、またはPENCIL：半径と不透明度に筆圧を反映	INK_PEN
パレット	マテリアルの色	sRGBの16進数値、ペイントバケットごとに1つのマテリアル
カメラ	正投影マルチプレーンまたはパースペクティブ	正投影、正面ビュー、描画平面XZ
次に編集する人	手続き的な状態をどの程度維持するか	人間のアニメーター：すべてを編集可能なストロークに変換

ワークフロー

1. ステージングとレイアウト。 cam = G.scene_2d(res, fps, frame_range, ortho_scale)（-Y 方向を向く正投影カメラ、Standard、背景）。マルチプレーンの構成を計画します。どの要素を別オブジェクトにするか、奥行き順をどうするかを決めます。px = G.px_size() を計算します。ピクセル単位の線幅は 2 * radius / px です。GATE：テストレンダーでフレームが表示され、予定した線幅が 1.5 px 以上であること［追加］。
2. 構造。 要素ごとに G.new_object(name, layers=("Fills", "Shadow", "Lines")) を作成します（下から上へ、アンリット）。パーツを親子付けし、原点を関節に配置します。バケットごとに G.material(ob, name, stroke=hex, fill=hex) を 1 回実行します。GATE：[l.name for l in ob.data.layers] が意図した内容と一致し、G.draw_order(objs) が設計どおりに手前から奥の順で並ぶこと。
3. 描画。 まずキーを作成します：d = G.key(ob, "Lines", frame)。線： G.add_stroke(d, G.smooth_path(control_pts), radius, pressure=G.taper(n), brush="INK_PEN", material=i)； 端をぴったり合わせるのではなく、重ねてからトリミングします（Grant）。塗り： Fills レイヤーに G.add_shape(d, outline, holes=[...], material=i) を追加し、輪郭線は Lines に配置します。一括処理： G.add_strokes(d, specs)（0.04 秒で 3000 本のストローク）。形状は G.grab、G.dissolve、G.edit_op(ob, "stroke_smooth", ...) で修正します。GATE：G.verdict(G.report(ob)) の結果に問題がなく、フル解像度の G.render_frame で隙間、はみ出し、突き出しがないこと。
4. 色と影。 Shadow レイヤー：blend_mode='MULTIPLY'、不透明度を下げ、use_masks=True にして、mask_layers.add(fills) を設定します。影の形状を端の外側まで描き、マスクでクリップします。形状はブロック状にデザインします（Pablo）。照明表現：use_lights=True に加え、環境光として World.color とランプを使用します（検証済み：フラットな描画ではサンライトは値をスケーリングするだけですが、ポイントライトはグラデーションを作ります）。GATE：Standard の設定でサンプリングしたピクセルがパレットと一致すること。
5. アニメーション。 置き換えキーは G.key(..., mode="blank")、加算キーは mode="copy"、保持またはサイクルは mode="instance" / G.cycle(...) を使い、露出の終了には G.end_exposure を使います。表示されるレイヤーはすべて、frame_start 以前またはその時点にキーが必要です（Elijah）。カットアウトアニメーション：オブジェクトのトランスフォームをキー設定します（FK）。中割り：まず G.match(dA, dB) を確認し、次に G.interpolate(ob, layer, frame, step=2, type, easing)（ネイティブ方式。frame 周辺のセグメント）または、アニメーター独自の間隔を設定する G.inbetween(ob, layer, a, b, frames, spacing=[...] or ease=...) を使います。ペアが異なる場合は clip=True を指定します。GATE：レイヤーごとに G.exposures(ob, layer) を確認し、タイミングとポップを確認するために G.render_strip(path, frames) を左から右へ再生し、軌道と間隔は G.onion(path, frame, before, after) で確認します。
6. 2.5D（任意）。 輪郭線：G.lineart(source, radius=width_m)（モディファイアーの radius が線幅です）。メッシュ上のストローク：G.project_to_surface(pts, mesh) を使い、投影に失敗した点、またはオクルーダーに取り込まれた点を含むストロークは破棄します（Pablo の失敗パターン）。再照明： G.relight(ob, canvas, light_dir, shadow, light)。プロシージャルストローク：Geometry Nodes Curves から Grease Pencil へ、Instances as Layers をオフにし、fill_id 属性を付けてから適用し、ベイクします（手順 P7）。画像を変えずに奥行き順を変更するには：G.push_depth(ob, delta)。GATE：サーフェスが 3D に見えず（Weigl）、塗りが突き抜けない（Pablo）ことを確認できる移動レンダー（ストリップまたはプレイブラスト）。
7. 納品。 シーンカメラでフレームまたは動画をレンダリングします。.blend を編集可能な状態に保ちます（アニメーターがまだ必要とするプロシージャル段階は適用しないでください）。GATE：すべてのオブジェクトの判定に問題がなく、ストリップと最終フレームを確認し、未検証の項目を列挙すること。

数値

値	意味	出典
radius = 線幅の半分（m）	幅 px = 2 x radius / px_size	検証済み
px_size = ortho_scale / max(res_x, res_y)	ortho。パースでは depth x 2 tan(fov/2) / res を使用	検証済み
0.01 m	radius 属性がない場合のポイント半径	検証済み
Line Art の radius のデフォルト値は 0.0025 m	線の幅です。ポイントの半径はその半分になります	検証済み
Elijah の Line Art の太さ 60（4.x）	5.2 では幅が約 0.006 m	[推定]
use_lights True、World.color 0.05	新しいレイヤーは約 25 % の値でフラットカラーを描画します	検証済み
set_uniform_thickness(thickness=t)	半径を t/2 に設定します	検証済み
約 60 パーツ、約 100 種類のリグ、リード用リグに 2 週間	Ewilan's Quest の切り抜きアニメーション規模	Tom
12 fps、60 フレーム、ortho scale 8、シェイプメッシュに Subdivision 2～3	ハイブリッドモーショングラフィックス	Elijah
スタビライザー 40 px / 0.9（標準設定）、Elijah は必要に応じて約 60 を使用	長いカーブにのみ使用	Elijah、検証済みのデフォルト値
1 回の光のバウンス	スタイライズされたリライティングには十分です	Weigl
GP アンチエイリアス aa_samples 8	scene.grease_pencil_settings	検証済み

品質ゲート

測定可能（オブジェクトごと、各ステージで）：

for ob in gp_objects:
    print(ob.name, G.verdict(G.report(ob)))   # first key vs frame_start, lit-without-light,
                                             # invisible strokes, stray micro-strokes, sub-pixel lines,
                                             # fill/stroke alpha 0, empty masks; info: instances, unused materials
print(G.draw_order(gp_objects))               # front -> back vs the staging plan
print(G.match(dA, dB))                        # before any interpolation

視覚的な確認（すべての画像を開く）：線の品質、トリム、塗りつぶしの隙間、パレットを確認するには、フル解像度で G.render_frame(path, f) を使用します。タイミング、ホールド、ポップを確認するには G.render_strip(path, range(a, b, 2)) を使用します。間隔と弧を確認するには G.onion(path, f, before, after) を使用します（ビューポートのオニオンスキンでは無視されるオブジェクトの動きとモディファイアも含まれます。Falk と Rik）。2.5D では静止画ではなく、シーケンスを確認します。references/critique.md に照らして評価します。

よくある間違い

間違い	症状	対処
ランプがないのにレイヤーの use_lights=True のままにする	フラットなパレットが暗い茶色やグレーで描画される	layer.use_lights=False にするか、World.color を上げてランプを追加する
マテリアルから塗りつぶされると期待する	形状の輪郭だけが表示される	stroke.fill_id=1 と cyclic=True を設定する。穴には同じ ID を使う
fill_id=0 で hide_stroke=True にする	ストロークが消える	塗りつぶし ID を設定するか、ストロークを表示する
ストロークのある描画で attributes.new("radius") を使う	既存のストロークが消える（半径 0）	先にデフォルト値を設定する（G.add_strokes が設定します）
frame_start の後に最初のキーを設定する	描画が突然表示され、冒頭に空のフレームがある	frame_start にキーを設定する（Elijah）
異なる描画を補間する	中割りがにじんだり、ねじれたりする	G.match を使う。描き直す、再サンプリングする、またはクリップする（Tom）
アーマチュアのウェイトで描画をリギングする	描き直すたびに変形が崩れる	オブジェクトレベルの切り抜きを使い、デフォーマーとしてスカルプトする（Tom）
ストロークレベルで奥行きを並べ替える	アーティストが設定したレイヤー順が失われる	グループ（オブジェクトまたはメッシュアイランド）を並べ替える（Weigl）
曲面に大きな塗りつぶしを 1 つ配置する	塗りつぶしがメッシュから突き出る	曲面の近くに小さな塗りつぶしを多数配置する（Pablo）
余分な点を削除する	ストロークが 2 つに分かれる	G.dissolve を使うと連続した状態を維持できる（Pablo）
Line Art の半径をストロークの半径と同じように設定する	輪郭線が意図した太さの半分になる	Line Art の半径 ＝ 幅 ＝ ストロークの半径 × 2
静止画で 2.5D を判断する	絵画のように見えるが、動かすと 3D として認識される	シーケンスをレンダリングする（Weigl）
スクリプトから描画ブラシを呼び出す	Invalid operator call が発生し、何も描画されない	データとしてストロークを書き込む。5.2 の注記を参照

Blender 5.2 に関するメモ

• 型：オブジェクトは GREASEPENCIL、データは bpy.data.grease_pencils です； layer.frames.new(n).drawing.add_strokes([...]) を使います。従来の frame.strokes、point.co、pressure、 strength、GPENCIL、object.grease_pencil_modifiers はなくなりました。モディファイアーは通常どおりです： ob.modifiers.new(n, 'GREASE_PENCIL_NOISE')、Line Art は 'LINEART' です。
• ストロークとポイントのヘルパーは Python ラッパーです。ストロークを追加または削除した後は、必ず再取得してください。キャッシュしないでください。
• grease_pencil.brush_stroke と sculpt_paint には exec がありません。ライブセッションでストロークのリストを渡して呼び出すと、「Invalid operator call」と記録され、何も描画されません（GUI で確認済み）。event_simulate でマウスイベントを再生しても何も描画されませんでした。ドローとスカルプトのストロークはデータです。ヘッドレス編集オペレーター（stroke_smooth、stroke_simplify、set_uniform_thickness、stroke_subdivide、outline、join_fills、set_curve_type）は、G.edit_op を通じて編集モードで実行します。ライブセッションでは、3D ビューのオーバーライドを使うと G.gui_trim（投げ縄トリム）、G.gui_erase_box、G.gui_reproject(type='SURFACE') が動作します。
• interpolate_sequence はアクティブなオブジェクトとレイヤーに対してヘッドレスで実行され、現在のフレーム周辺の区間のみを埋めて、BREAKDOWN キーを挿入します。type と easing でイージングを設定します。
• 既存のフレームに対して frames.new または frames.copy を実行すると、「Frame already exists」エラーが発生します；get_frame_at(n) は n の位置で公開されているキーを返します（最初のキーより前では None）。
• layer.mask_layers.add(layer) が 5.2 のマスク API です。レイヤーグループには gp.layer_groups.new と gp.layers.move_to_layer_group を使います。レイヤーはオブジェクトまたはボーンを親にでき（layer.parent、parent_bone）、独自の変換を保持できます。
• object.grease_pencil_add(type='LINEART_OBJECT') で作成した Line Art オブジェクトには、点灯したレイヤーがあります。レンダーで非表示のオブジェクトは Line Art で無視されます。lineart_bake_strokes はシーン全体の範囲をベイクします。
• GN の Curves to Grease Pencil は、Instances as Layers がオン（デフォルト）の場合、通常のカーブを破棄します。Set Material だけでは、もはや塗りつぶされません（5.1）：カーブドメインに INT の fill_id を保存してください。

参考資料

• references/expert-notes.md：各エキスパートの原則、判断、意見の相違をタイムスタンプ付きで記載しています。スタイルやパイプラインを決める際に読み込んでください。
• references/procedures.md：テスト済みの raw-bpy 手順（P1 から P8）と bx_gp のレシピ（切り抜きキャラクター、フレームごとの作成、補間、2.5D）を記載しています。GP コードを書く前に読み込んでください。
• references/critique.md：線、塗り、画面構成、タイミング、2.5D レンダリングを評価するための基準です。各レビューゲートで読み込んでください。
• references/sources.md：5 本のソース動画、それぞれに適した内容、最適なタイムスタンプを記載しています。