scenario-blender-grease-pencil

Grease Pencil（v3，Blender 5.2）

专业的 Grease Pencil 工作流会确保每幅画都可编辑、可重新绘制，让结构承载含义 （哪个对象、哪个图层、哪个关键帧），并根据动态效果评判结果。Agent 通过数据 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 对象（主角约 60 个），建立父子关系，主要通过对象变换进行 FK；每个元素内部的图层按图形逻辑组织（线条在颜色上方）；使用雕刻作为变形器；不要对绘图进行骨架权重绘制，因为每次重绘都需要重新设置权重。
• Tom：只对“雕刻过”的关键帧对进行插值。 只有笔画数量、顺序和颜色都相同，且点也一致时，两个关键帧才能干净地插值。否则就重绘，或“裁切”到最近的绘图，而不是接受失真。原生插值会忽略对象动画：需单独设置变换关键帧。
• Falk David（GP 模块负责人）：填充属于几何，而非材质。 笔画在 fill_id != 0 时会填充；共享同一 ID 的笔画会一起填充，并以奇偶规则形成孔洞；hide_stroke 会隐藏轮廓。材质填充开关已弃用，挖空“橡皮擦填充”（Grant Abbitt 的 4.4 方法）也已过时。
• Grant Abbitt：图层堆栈承载含义，材质就是颜料桶。 线条置顶，中间放置阴影图层（正片叠底、降低不透明度，并由填充遮罩），底部放置填充。编辑材质会重新着色所有使用该材质的笔画。锁定当前未编辑的内容：橡皮擦和雕刻会作用于所有未锁定的图层。
• Elijah Sheffield：先确保颜色可预测。 使用标准视图变换、无光照平面着色和白色世界。已验证的陷阱：新图层的 use_lights=True，而受光图层的环境光取自 World.color（默认值为 0.05），而非世界节点树，因此平面调色板的渲染值大约只有预期的四分之一。
• Tom：先确立多平面纪律和布局。 所有 2D 元素都与相机平行，相机轴向始终不变，只在能节省时间时使用 3D；相机、剪辑和视差应在布局阶段确定，而不是到合成阶段才摸索。对象之间由深度决定谁画在上面。
• Michael Weigl：运动会暴露表面问题。 具有绘画感的静帧一旦动起来就可能失效；应将 2.5D 作为序列来评判。对笔画组（网格岛）排序，而不是逐条排序，并将程序化输出烘焙回可编辑笔画。
• Pablo Fournier（Blender Studio）：精心设计阴影。 用块状的绘制光影形状（每个部件分别使用光照材质和阴影材质）替代一团团的 3D 着色。填充应保持平坦：在曲面上使用许多小块填充，而不是将一整块大填充向前推。

先确定

输入	变更	未指定时的默认值
交付物	逐帧镜头、逐帧镜头、剪贴图绑定、混合动态图形、3D 上的 2.5D	逐帧镜头
格式	分辨率、帧率、时长	1920 x 1080，24 fps，按双帧计时［新增］；社交媒体动态图形：1080 x 1920，12 fps，60 帧（Elijah）
风格	平涂或光照、线条系统	平涂（不受光图层，Standard）；带压力渐细效果的墨线
线条系统	PEN 固定宽度（与 Line Art、Elijah 一致），或 INK_PEN 根据压力改变半径（卡通风格，Grant），或 PENCIL（根据压力改变半径和不透明度）	INK_PEN
调色板	材质颜色	十六进制 sRGB 值，每个填充区域使用一种材质
摄像机	正交多平面或透视	正交、正视图，绘制平面为 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)。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)，将轮廓放在线条图层上。批量处理： 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. 颜色和阴影。 阴影图层：设置 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)（修改器的半径就是线宽）。在网格上绘制线条：使用 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)	正交；透视使用深度 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 帧、正交缩放 8、形状网格细分 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
hide_stroke=True 且 fill_id=0	描边消失	为其指定填充 ID，或显示描边
在带有描边的绘图上调用 attributes.new("radius")	现有描边消失（半径为 0）	先填充默认值（G.add_strokes 会这样做）
frame_start 之后的第一个关键帧	绘图突然出现，开头是空帧	在 frame_start 处设关键帧（Elijah）
插值不同的绘图	中间帧模糊、扭曲	使用 G.match；重新绘制、重采样或裁剪（Tom）
使用骨架权重绑定绘图	每次重绘都会破坏变形	使用对象级剪纸，将雕刻用作变形器（Tom）
描边级深度排序	破坏艺术家的图层顺序	对组（对象或网格岛）排序（Weigl）
在曲面上使用一个大型填充	填充穿透网格	在表面附近使用多个小填充（Pablo）
删除多余点	描边分成两段	G.dissolve 可保持其连续（Pablo）
将 Line Art 半径设得像描边半径	轮廓粗细只有预期的一半	Line Art 半径 = 宽度 = 2 x 描边半径
只看静帧来判断 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')，线稿为 '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）需在 Edit 模式下通过 G.edit_op 运行。在实时会话中，G.gui_trim（套索修剪）、G.gui_erase_box 和 G.gui_reproject(type='SURFACE') 可在 3D 视图覆盖环境下运行。
• 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') 创建的线稿对象带有受光图层；被隐藏而不参与渲染的对象会被线稿忽略；lineart_bake_strokes 会烘焙整个场景范围。
• 启用 Instances as Layers（默认）时，GN 曲线转 Grease Pencil 会丢弃普通曲线；仅使用 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：五个源视频、各自最适合的用途及最佳时间戳。