scenario-blender-lighting-rendering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lighting, rendering and compositing

灯光、渲染与合成

Expert lighting controls where the eye goes. Shape comes from gradients, the subject is separated from its surroundings by value (checked desaturated), every light has a source and a purpose, and every decision is measured on the render, not on lamp values. Work from a controlled base, change one thing at a time, and compare. If a sibling skill named here is missing from your available skills, ask the user to install it (

npx skills add scenario-labs/skills --skill <name>

); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-blender-expert (execution channel, review loop, 5.2 API changes). Related: scenario-blender-texturing-shading (materials, skin SSS), scenario-blender-previs-storyboard (shot planning, cameras).

Toolkit:

scripts/bx_light.py

(tested on 5.2.1): rigs placed relative to subject and camera, EEVEE/Cycles presets, color setup and audit, 5.x compositor helpers, render analysis. Import:

sys.path.append("<this skill>/scripts"); import bx_light as BL

专业的灯光设计能够引导观众的视线。形体感来自渐变，通过明度（去饱和后检查）将主体与环境区分开，每一盏灯都有其存在的依据和作用，所有调整都要基于渲染效果判断，而非灯光的参数值。从可控的基础设置开始，每次只调整一项，然后对比效果。如果你的可用技能中缺少这里提到的关联技能，请让用户安装（

npx skills add scenario-labs/skills --skill <name>

）；如果是无人值守模式，则基于工具架构继续执行并标记缺失的技能。

必备基础技能： scenario-blender-expert（执行通道、评审循环、5.2版本API变更）。相关技能：scenario-blender-texturing-shading（材质、皮肤SSS）、scenario-blender-previs-storyboard（镜头规划、相机设置）。

工具包：

scripts/bx_light.py

（已在5.2.1版本测试）：可相对于主体和相机放置灯光rig，提供EEVEE/Cycles预设、色彩设置与检查、5.x版本合成器辅助工具、渲染分析功能。导入方式：

sys.path.append("<this skill>/scripts"); import bx_light as BL

Stance (the expert delta)

核心理念（专家级差异）

Value separation first. Andy Goralczyk separates character from background by value in almost every shot and checks it desaturated. Andrew Price: the highest-contrast area becomes the focal point whether you want it or not (the bright window beats the couch). Fix by darkening the set before brightening the subject.
Light size and distance are the controls. Andrew: a large source reads form and hides pores, a small one reads texture and grit, so a face key is a large source, never a small bulb (unless toon or deliberately harsh). Inverse square is an attention tool: move a light closer instead of adding helpers. No key:fill ratio is a rule (Andrew: "half the key is bogus"): dim the shadow side until it reads as shadow with detail, and measure on the subject.
Motivate, then cheat plausibly. Every light needs a source and a color from the world (Gleb Alexandrov, Lino Thomas). Andy puts the rim on the key side, because on the shadow side it reads as a bounce from nowhere. When the source is behind the subject he fakes a key into the face. Shadow casters and light linking keep cheats off the set. Gleb stops before the image "looks lit".
EEVEE is a trench coat (Andrew). Ray tracing is off in a factory scene. World light passes through walls unless the volume probe's outer samples sit at the inner walls (Andrew; measured 0.26 leak to 0.002; 5.2.1 puts samples one spacing inside the box, so size the box from the points). Soft lights need per-light jitter (Gleb) and custom distance (measured: automatic distance loses 8 %).
Cycles economy (Andy, Sprite Fright): 3 bounces, no caustics, no clamping, Fast GI, and bounces faked with lights. Keep sharp speculars for the eyes and hero metal only.
Linear and wide until the end (Jacob Holiday). EXR stays linear while PNG bakes the view transform. AgX hides clipping (linear 4 displays 0.91), so read the EXR. Global brightness is
```
exposure
```
in the view transform, not scaled lights (keeps every ratio, including world and emissives). AgX for scenes, Khronos PBR Neutral for product color. Set the working space once (Nathan Vegdahl).
Rebalance in comp, not by re-rendering (Wyatt, Robin). In Cycles, light groups per role (key, fill, rim, window): one render, then gains in the compositor (
```
BL.light_groups
```
,
```
BL.lightgroup_mix
```
). EEVEE has no light-group outputs: use light linking and view layers.
Always comp, lightly (Pau Homs): bloom, vignette, then a correction, stopping before it reads as a filter. In 5.x the compositor is a node group.
Color has three contrasts (Lino): value, saturation and hue. Keep one saturated focus hue and desaturate its complement over large areas.

明度分离优先。 Andy Goralczyk几乎在每个镜头中都通过明度来区分角色与背景，并会去饱和检查效果。Andrew Price：对比度最高的区域会自动成为视觉焦点，无论你是否愿意（明亮的窗户比沙发更吸睛）。解决方法是先调暗场景，再提亮主体。
灯光的大小与距离是核心控制参数。 Andrew：大光源能体现形体感并弱化毛孔细节，小光源会突出纹理和颗粒感，因此面部主光必须用大光源，绝不能用小灯泡（除非是卡通风格或刻意营造硬光效果）。平方反比定律是调整注意力的工具：将灯光移近即可，无需添加辅助光。不存在固定的主光:辅光比例（Andrew："主光一半的亮度是瞎扯"）：调暗阴影面，直到它呈现出有细节的阴影即可，以主体上的效果为准进行判断。
先找动机，再合理"作弊"。 每盏灯都要有场景中的光源依据和对应的颜色（Gleb Alexandrov、Lino Thomas）。Andy会把轮廓光放在主光一侧，因为放在阴影侧的话，会看起来像是无中生有的反弹光。当光源在主体后方时，他会在面部补一盏假主光。阴影投射物和灯光链接可以让这些"作弊"灯光不影响场景其他部分。Gleb会在画面"看起来像打了光"之前就停手。
EEVEE是件"风衣"（Andrew）。 在工厂场景中要关闭光线追踪。环境光会穿透墙壁，除非将体积探针的外采样点设置在内墙位置（Andrew；实测漏光从0.26降至0.002；5.2.1版本中采样点位于盒子内部一个间距的位置，因此要根据点位调整盒子大小）。软光需要为每盏灯单独设置抖动（Gleb）和自定义距离（实测：自动距离会损失8%的亮度）。
Cycles精简设置（Andy，《Sprite Fright》项目）： 3次反弹，关闭焦散，无钳制，开启Fast GI，用灯光模拟反弹光。仅在眼睛和主打金属材质上保留锐利的高光。
全程保持线性宽色域，最后再做转换（Jacob Holiday）。 EXR文件保持线性色彩空间，而PNG会烘焙视图转换。AgX会掩盖裁切问题（线性值4显示为0.91），因此要查看EXR文件。全局亮度通过视图转换中的
```
exposure
```
（曝光）调整，而非缩放灯光亮度（这样可以保持所有比例，包括环境光和自发光的比例）。场景用AgX色彩空间，产品色彩用Khronos PBR Neutral。工作空间只需设置一次（Nathan Vegdahl）。
在合成中重新平衡，而非重新渲染（Wyatt、Robin）。在Cycles中，按角色设置灯光组（主光、辅光、轮廓光、窗户光）：渲染一次，然后在合成器中调整增益（
```
BL.light_groups
```
、
```
BL.lightgroup_mix
```
）。EEVEE没有灯光组输出：使用灯光链接和视图层代替。
永远做轻度合成（Pau Homs）： 添加bloom、vignette，然后做校正，在效果看起来像加了滤镜之前就停手。在5.x版本中，合成器是一个节点组。
色彩有三种对比（Lino）： 明度、饱和度和色相。保留一个高饱和的焦点色相，在大面积区域降低其互补色的饱和度。

Establish first

前期确认项

Input	Why it changes the plan	Default when silent
Still or animation	Continuity, flicker and temporal denoise	Still
Engine	EEVEE: stylized, fast iteration, volumes, NPR, viewport comp with passes. Cycles: glass close-ups, bounce realism, reference	EEVEE to iterate, plus a Cycles reference render
Style	Toon terminators need a small, unjittered key	Stylized-realistic
Subject and focus point	Rig target (the face), mask for the analysis	Character head, else bbox center
Time and motivation	Color scheme: warm practicals, cool sky, sun	Night/dusk interior: warm key (2,700 K [added]), cool fill
Delivery	PNG display plus EXR master; external grade?	PNG + 32-bit multilayer EXR
Color fidelity	Brand RGB: Khronos PBR Neutral; skin: ACES 2.0 or AgX High Contrast	AgX
Late balance changes, comp hand-off	Cycles light groups per role, multilayer EXR	groups when rendering in Cycles

输入项	为何会影响方案	未明确时的默认值
静态图或动画	连续性、闪烁和时域降噪	静态图
渲染引擎	EEVEE：风格化、快速迭代、体积效果、NPR、带通道的视口合成。Cycles：玻璃特写、真实反弹光、参考渲染	用EEVEE迭代，同时输出Cycles参考渲染
风格	卡通风格的明暗交界线需要小尺寸、无抖动的主光	风格化写实
主体与对焦点	灯光rig的目标（面部）、分析用遮罩	角色头部，否则为边界盒中心
时间与布光动机	色彩方案：暖色调实用光源、冷色调天空、太阳光	夜晚/黄昏室内：暖主光（2700K [补充]），冷辅光
交付格式	PNG预览图加EXR母版；是否需要外部调色？	PNG + 32位多层EXR
色彩保真度	品牌RGB：Khronos PBR Neutral；皮肤：ACES 2.0或AgX High Contrast	AgX
后期平衡调整、合成交接	按角色设置Cycles灯光组，多层EXR	使用Cycles渲染时启用灯光组

Workflow

工作流

Compose, then lock the camera. Lighting is view dependent (Andrew). Use
```
BL.screen_xy
```
and
```
BL.aim_camera_at_frame_point(head, 1/3 or 2/3, 0.62)
```
for look room, and 80 mm for boxy products. GATE: one focal element; subject near a thirds point or a deliberate symmetry, pyramid or full frame.
Controlled base. For a studio: world strength 0 and a near-black rough ground (Andrew). For an EEVEE interior:
```
pb = BL.volume_probe_for_room(inner_lo, inner_hi, cell=0.5, wall=0.2)
```
(outer samples on the inner walls),
```
BL.probe_report(pb, inner_lo, inner_hi)
```
, then
```
BL.bake_probes()
```
. For an exterior:
```
BL.outdoor_sun_sky(..., azimuth_space="world")
```
. GATE:
```
probe_report
```
flags nothing and a world-only render of a sealed interior is near black.
Key. Use
```
BL.three_point
```
,
```
BL.motivated_interior
```
(window + practical, cheated linked key, spot practical, rims, bounce) or
```
BL.outdoor_sun_sky
```
. Lights stay out of walls automatically. GATE:
```
BL.light_report(target=head, face=head)
```
has no flags (frontal key, key below the eye line, key smaller than the head), and a clay render (
```
BL.clay(True)
```
) gives
```
internal_ratio >= 2.5
```
.
Supporting lights. Add fill, rim, bounce and
```
BL.eye_light
```
, plus
```
BL.shadow_caster
```
,
```
BL.fake_sun
```
,
```
BL.split_world
```
or
```
BL.haze
```
as needed. Linking lives on the light OBJECT (
```
obj.light_linking
```
, via
```
BL.link_light
```
), not the Light datablock. Adjust one lamp at a time:
```
BL.light_contributions(lights, mask, dir)
```
, or in Cycles
```
BL.lightgroup_check(exr, mask)
```
from one render. GATE: the key has the largest share on the subject, the world is under 10 % indoors, and each rim is motivated.
Measure and look.
```
r = BL.render(base)
```
gives PNG + EXR. Then
```
mask = BL.mask_cryptomatte(r["exr"], names)
```
(or
```
BL.mask_workbench
```
),
```
rep = BL.analyse(r["png"], mask, exr=r["exr"])
```
,
```
BL.verdict(rep)
```
and
```
BL.value_study(...)
```
, and open the images. GATE: the verdict is empty and in the value study the subject owns a value group; otherwise darken the set, carve with spots or blockers, and link the key.
Color.
```
BL.color_setup(view, look, exposure)
```
(brightness here, never by scaling lamps) and
```
BL.color_audit()
```
. GATE: the audit is empty, no complementary clash is flagged, clip is at most 0.5 % outside emitters, and the linear max is intended.
Render settings.
```
BL.preset_eevee(quality="final", interior=...)
```
or
```
BL.preset_cycles(quality="final", budget="film")
```
. For EEVEE finals, render a Cycles preview reference (Andrew). GATE: the subject is within about 30 % of Cycles and there are no engine artifacts (critique section 7).
Comp. Cycles:
```
mix = BL.lightgroup_mix(gains, exr=r["exr"])
```
re-grades key/fill/rim/window from the EXR in about 0.2 s (
```
BL.set_gain
```
, RGB gains recolor). Then
```
BL.comp_finish(bloom=0.25, vignette=0.3, contrast=0.05, source=mix["socket"])
```
; masks with
```
BL.matte(tree, names)
```
; pixel sizes through
```
BL.relative_px
```
; passes, back to beauty and view layers are in procedures P13. GATE: re-run the verdict on the finished frame; the vignette ratio should fall.
Deliver with evidence: final PNG, EXR, value study, the light table, the verdict, and what was not verified.

Animation: pin the sun per location with

sun_azimuth

within about 30 deg (Andy). Light the wide shot and propagate it to coverage. Check shots with

BL.contact_sheet

and

BL.sheet_stats

(outliers more than 0.5 stop from the median). Keep temporal denoise on and never use ray-tracing resolution 1/16.

构图，然后锁定相机。 灯光是依赖视角的（Andrew）。使用
```
BL.screen_xy
```
和
```
BL.aim_camera_at_frame_point(head, 1/3 or 2/3, 0.62)
```
来预留视线空间，方正的产品用80mm焦距。门禁要求：有且仅有一个焦点元素；主体靠近三分线位置，或是刻意的对称、金字塔构图或满帧构图。
可控基础设置。 影棚场景：环境光强度设为0，地面用接近黑色的粗糙材质（Andrew）。EEVEE室内场景：
```
pb = BL.volume_probe_for_room(inner_lo, inner_hi, cell=0.5, wall=0.2)
```
（外采样点位于内墙位置），运行
```
BL.probe_report(pb, inner_lo, inner_hi)
```
，然后执行
```
BL.bake_probes()
```
。室外场景：
```
BL.outdoor_sun_sky(..., azimuth_space="world")
```
。门禁要求：
```
probe_report
```
无报错，封闭室内仅环境光的渲染结果接近纯黑。
主光设置。 使用
```
BL.three_point
```
（三点布光）、
```
BL.motivated_interior
```
（动机式室内布光：窗户光+实用光源、带链接的假主光、聚光实用灯、轮廓光、反弹光）或
```
BL.outdoor_sun_sky
```
（室外太阳光与天空）。灯光会自动避开墙壁。门禁要求：
```
BL.light_report(target=head, face=head)
```
无报错（无正面主光、主光低于视线、主光尺寸小于头部这些问题），且黏土渲染（
```
BL.clay(True)
```
）的
```
internal_ratio >= 2.5
```
。
辅助灯光。 添加辅光、轮廓光、反弹光和
```
BL.eye_light
```
（眼神光），再根据需要添加
```
BL.shadow_caster
```
（阴影投射物）、
```
BL.fake_sun
```
（假太阳光）、
```
BL.split_world
```
（分离环境光）或
```
BL.haze
```
（雾效）。灯光链接设置在灯光对象（OBJECT）上（
```
obj.light_linking
```
，通过
```
BL.link_light
```
设置），而非Light数据块上。每次只调整一盏灯：用
```
BL.light_contributions(lights, mask, dir)
```
查看，或在Cycles中用一次渲染的结果运行
```
BL.lightgroup_check(exr, mask)
```
。门禁要求：主光在主体上的占比最大，室内环境光占比低于10%，每盏轮廓光都有合理动机。
测量与目视检查。 运行
```
r = BL.render(base)
```
输出PNG和EXR。然后生成遮罩：
```
mask = BL.mask_cryptomatte(r["exr"], names)
```
（或
```
BL.mask_workbench
```
），运行
```
rep = BL.analyse(r["png"], mask, exr=r["exr"])
```
、
```
BL.verdict(rep)
```
和
```
BL.value_study(...)
```
，并打开图像查看。门禁要求：verdict（判定结果）为空，且明度研究中主体属于独立的明度组；否则需调暗场景，用聚光灯或遮光板塑造形体，并链接主光。
色彩设置。 运行
```
BL.color_setup(view, look, exposure)
```
（亮度在这里调整，绝对不要缩放灯光亮度）和
```
BL.color_audit()
```
。门禁要求：色彩检查无报错，无互补色冲突提示，除自发光外裁切占比不超过0.5%，且线性最大值符合预期。
渲染设置。 运行
```
BL.preset_eevee(quality="final", interior=...)
```
或
```
BL.preset_cycles(quality="final", budget="film")
```
。如果是EEVEE最终渲染，要输出一张Cycles预览参考图（Andrew）。门禁要求：主体效果与Cycles的差异在30%以内，且无引擎伪影（见评审第7节）。
合成。 Cycles流程：运行
```
mix = BL.lightgroup_mix(gains, exr=r["exr"])
```
，可在约0.2秒内从EXR中重新调整主光/辅光/轮廓光/窗户光的等级（
```
BL.set_gain
```
，RGB增益可改色）。然后运行
```
BL.comp_finish(bloom=0.25, vignette=0.3, contrast=0.05, source=mix["socket"])
```
；用
```
BL.matte(tree, names)
```
生成遮罩；像素尺寸通过
```
BL.relative_px
```
设置；通道、返回beauty层和视图层的操作见P13流程。门禁要求：对最终帧重新运行判定；暗角比例应符合预期。
交付时附带验证依据： 最终PNG、EXR、明度研究图、灯光参数表、判定结果，以及未验证的内容。

动画注意事项： 用

sun_azimuth

（太阳方位角）固定每个位置的太阳角度，偏差在30度以内（Andy）。先打全景的光，再推广到其他镜头。用

BL.contact_sheet

（联系表）和

BL.sheet_stats

检查镜头（与中位数偏差超过0.5档的为异常值）。保持时域降噪开启，绝对不要使用1/16的光线追踪分辨率。

Numbers

参数参考

Value	Relative to	Source
Level of a white card: point P/(4π²d²), area P/(π²d²), sun S/π	`BL.energy_for`	measured, both engines
Source as big as its distance delivers 75 % of the nominal level	apparent size	measured
AgX display: 0.18 to 0.463, 1.0 to 0.773, 4.0 to 0.910	linear value	measured
Key 40 deg off axis, 35 deg up, 3 subject radii, size = radius	subject, camera	[added] defaults
Frontal flag: key < 20 deg off the camera axis	camera axis	[added]
Sun angle about 2 deg; continuity ±30 deg	set	Andy
Kelvin: candle 1,500, incandescent 2,000 to 2,500, daylight 6,500 (practical default 2,700 [added])	light	Andrew
EEVEE: RT 1:1 and GI 1:2 for finals, Fast GI steps 16, shadow steps 12 to 16 (leaks), shadow rays 2 (penumbra)	render	Andrew
Volume probe: outer samples on the inner walls (samples at local (i+1)/(N+1)x2-1); leak 0.22 at 0.44 m inside, 0.054 at 0.2 m, 0.002 at the wall, 0.009 past the wall; surfel density 100	room	Andrew, measured
Brand color error (of 255): Khronos 3.8, AgX 27 to 42, Standard 33	white furnace	measured
Haze density about 0.05 for a room	volume	Andrew
Cycles film: 3 bounces, clamp 0, no caustics, 100 test / 500 to 1,500 final samples	render	Andy
EXR: multilayer, half float, DWAA for comp; 32-bit masters	output	Robin, Andy
Verdict: surround separation ≥ 0.10, edge merge ≤ 35 %, clay form ratio ≥ 2.5, value range ≥ 0.30, clip ≤ 0.5 %	display luma	[added], calibrated

参数值	参照对象	来源
白卡亮度：点光源 P/(4π²d²)，面光源 P/(π²d²)，太阳光 S/π	`BL.energy_for`	实测，双引擎通用
光源尺寸等于其距离时，亮度为标称值的75%	表观尺寸	实测
AgX显示值：0.18对应0.463，1.0对应0.773，4.0对应0.910	线性值	实测
主光偏离轴线40度，向上35度，距离为3倍主体半径，尺寸=主体半径	主体、相机	[补充]默认值
正面光标记：主光偏离相机轴线小于20度	相机轴线	[补充]
太阳角度约2度；连续性偏差±30度	场景	Andy
开尔文色温：蜡烛1500K，白炽灯2000-2500K，日光6500K（实用默认值2700K [补充]）	灯光	Andrew
EEVEE：最终渲染用RT 1:1、GI 1:2，Fast GI步数16，阴影步数12-16（漏光问题），阴影光线2（半影）	渲染	Andrew
体积探针：外采样点位于内墙位置（采样点坐标为局部 (i+1)/(N+1)x2-1）；内墙内0.44米处漏光0.22，0.2米处0.054，墙位置0.002，墙外0.009；面元密度100	房间	Andrew、实测
品牌色彩误差（255级）：Khronos 3.8，AgX 27-42，标准33	白炉测试	实测
室内雾效密度约0.05	体积	Andrew
Cycles电影级设置：3次反弹，钳制0，无焦散，测试100采样/最终500-1500采样	渲染	Andy
EXR：多层、半精度浮点，合作用DWAA压缩；母版用32位	输出	Robin、Andy
判定标准：环境分离度≥0.10，边缘融合度≤35%，黏土形体比≥2.5，明度范围≥0.30，裁切≤0.5%	显示亮度	[补充]、已校准

Quality gates

质量门禁

Measurable:

python

rep = BL.analyse(png, mask, exr=exr); problems = BL.verdict(rep)          # [] = pass
flags = BL.light_report(target=head, face=head)["flags"]; audit = BL.color_audit()
probe = BL.probe_report(pb, inner_lo, inner_hi)["flags"]                  # EEVEE interiors: []
groups = BL.lightgroup_check(exr, mask)                                   # Cycles: rel_error ~0, shares
shares = BL.light_contributions(lights, mask, out_dir)                   # per-light share on subject

Visual: open the render, the

value_study

panel (desaturated | value groups | squint) and, for sequences, the contact sheet. Judge them with

references/critique.md

: first read, value structure, form, motivation, color, composition, artifacts, finish.

可量化指标：

python

rep = BL.analyse(png, mask, exr=exr); problems = BL.verdict(rep)          # [] = pass
flags = BL.light_report(target=head, face=head)["flags"]; audit = BL.color_audit()
probe = BL.probe_report(pb, inner_lo, inner_hi)["flags"]                  # EEVEE interiors: []
groups = BL.lightgroup_check(exr, mask)                                   # Cycles: rel_error ~0, shares
shares = BL.light_contributions(lights, mask, out_dir)                   # per-light share on subject

目视检查： 打开渲染图、

value_study

面板（去饱和 | 明度分组 | 眯眼检查），如果是序列帧，还要查看联系表。按照

references/critique.md

中的标准评判：第一观感、明度结构、形体感、布光动机、色彩、构图、伪影、完成度。

Common mistakes

常见错误

Mistake	What it looks like	Fix
Frontal key	Flat, "flash photo", clay form ratio about 1.3	Key 30 to 60 deg off axis, above the eye line
Practical behind the subject used as the key	Dull face, bright wall steals focus	Cheated key on the source's side, linked to the subject
Bare point practical near a wall	Blown wall, shelf becomes the focal point	Spot with the shade's cone; blocker
EEVEE interior without probe, or a probe box drawn to the walls	Shadows lifted blue/gray everywhere, muddy	Outer samples at the inner walls ( `probe_report` ), bake, sealed-room test
Small bulb as a face key	Pores and texture, harsh face	Large source (head-sized or more); flag in `light_report(face=)`
Brightening by scaling lamps	World and emissives left behind, ratios drift	`exposure` in the view transform
`light.data.light_linking`	AttributeError	Linking and light groups are Object properties
Re-rendering to rebalance lights	Hours per tweak	Cycles light groups + `lightgroup_mix`
Rig lights inside walls	A rim that contributes nothing	`avoid=subject` (default in rigs)
Unlinked faked key	Set brightens with the subject, no separation	`link_key=True` ; key share high, background share near 0
Judging clipping on AgX PNG	Highlights look fine, EXR at 20+	Read `linear_max` , use exposure
Big soft jittered key on a toon material	Dithered, noisy terminator	Small unjittered key for NPR (Wyatt: crisp shadows for toon)
Inverted hull outline	Character goes dark or flat	Outline material transparent to shadow rays ( `outline_hull` )
AOV named in shader only	Pass silently missing	`BL.register_aovs()`
Pixel-sized comp effects	Look changes between preview and final	`BL.relative_px`
Exclude instead of indirect-only in layers	Missing shadows in the comp	`indirect_only` (0.0004 vs 0.016 diff)

错误	表现	解决方法
正面主光	画面平、像"闪光灯拍的"，黏土形体比约1.3	主光偏离轴线30-60度，高于视线
主体后方的实用光源当主光	面部暗淡，明亮的墙壁抢了焦点	在光源一侧补一盏假主光，链接到主体
靠近墙壁的裸点实用光源	墙壁过曝，架子成为焦点	用带灯罩锥角的聚光灯；加遮光板
EEVEE室内场景无探针，或探针盒贴墙	阴影整体偏蓝/灰，画面发灰	将外采样点设在内墙位置（ `probe_report` 检查），烘焙，做封闭房间测试
小灯泡当面部主光	毛孔和纹理突出，面部生硬	用大光源（头部大小或更大）；用 `light_report(face=)` 检查标记
通过缩放灯光亮度来提亮	环境光和自发光跟不上，比例失衡	用视图转换中的 `exposure` 调整
`light.data.light_linking`	属性错误	灯光链接和灯光组是Object（对象）的属性
为了重新平衡灯光而重新渲染	每次调整要花几小时	Cycles灯光组 + `lightgroup_mix`
灯光rig穿模到墙里	轮廓光完全不起作用	设置 `avoid=subject` （rig中默认开启）
假主光没开链接	场景和主体一起变亮，没有分离感	开启 `link_key=True` ；主光占比高，背景占比接近0
通过AgX的PNG判断裁切	高光看起来没问题，EXR里已经到20+	查看 `linear_max` ，用曝光调整
卡通材质用大尺寸带抖动的软主光	明暗交界线有抖动、噪点	NPR用小尺寸无抖动的主光（Wyatt：卡通风格要阴影锐利）
反转外壳轮廓	角色变暗或变平	轮廓材质对阴影光线透明（ `outline_hull` ）
仅在着色器中命名AOV	通道悄无声息地丢失	运行 `BL.register_aovs()`
像素大小的合成效果	预览和最终渲染效果不一样	用 `BL.relative_px`
图层中用排除而非仅间接光	合成中缺少阴影	用 `indirect_only` （差异为0.0004 vs 0.016）

Blender 5.2 notes

Blender 5.2版本注意事项

EEVEE id is
```
BLENDER_EEVEE
```
;
```
use_raytracing
```
is False by default;
```
use_bloom/ssr/gtao/soft_shadows
```
are gone (Glare node, ray tracing, Fast GI, per-light jitter).
Probes are
```
SPHERE/PLANE/VOLUME
```
;
```
lightprobe_cache_bake
```
runs synchronously headless; the sphere-probe default is 512. Volume samples sit one spacing inside the box faces, never on them.
EEVEE writes Cryptomatte but no Object Index pass; light groups are Cycles only (EEVEE Render Layers has no
```
Combined_<group>
```
); light linking works in both engines.
```
light_linking
```
and
```
lightgroup
```
are Object properties;
```
bpy.types.Light
```
has neither.
Compositor:
```
scene.compositing_node_group
```
, Group Output,
```
ShaderNodeMix
```
(color sockets 6/7, result 2), menu inputs take display names ('Bloom'). GPU is the default device. Assets live in
```
datafiles/assets/nodes/compositing_nodes_essentials.blend
```
.
Color: the working space is read-only (use
```
bpy.ops.wm.set_working_color_space
```
); looks are prefixed ('AgX - Punchy'); 'Linear'/'Raw' are rejected; camera log spaces exist; Principled Thin Wall exists for window glass.
```
matrix_world
```
is stale after setting a transform; call
```
view_layer.update()
```
. OIIO
```
read_image(subimage, ...)
```
: the first argument selects the part.

EEVEE的ID是
```
BLENDER_EEVEE
```
；
```
use_raytracing
```
默认关闭；
```
use_bloom/ssr/gtao/soft_shadows
```
已移除（替换为Glare节点、光线追踪、Fast GI、单灯抖动）。
探针类型为
```
SPHERE/PLANE/VOLUME
```
；
```
lightprobe_cache_bake
```
在无头模式下同步运行；球形探针默认分辨率512。体积采样点位于盒面内部一个间距的位置，绝不会在盒面上。
EEVEE会输出Cryptomatte但没有对象索引通道；灯光组仅Cycles支持（EEVEE渲染层没有
```
Combined_<group>
```
）；灯光链接在两个引擎中都可用。
```
light_linking
```
和
```
lightgroup
```
是Object的属性；
```
bpy.types.Light
```
没有这两个属性。
合成器：
```
scene.compositing_node_group
```
、Group Output、
```
ShaderNodeMix
```
（颜色插槽为6/7，结果为2），菜单输入使用显示名称（'Bloom'）。默认使用GPU设备。资产位于
```
datafiles/assets/nodes/compositing_nodes_essentials.blend
```
。
色彩：工作空间是只读的（用
```
bpy.ops.wm.set_working_color_space
```
设置）；look（外观）有前缀（'AgX - Punchy'）；不支持'Linear'/'Raw'；支持相机对数空间；窗户玻璃可用Principled Thin Wall材质。
设置变换后
```
matrix_world
```
会过期；需调用
```
view_layer.update()
```
。OIIO的
```
read_image(subimage, ...)
```
：第一个参数用于选择子图像。

References

参考资料

```
references/procedures.md
```
: tested code for every stage (P1 units to P17 exposure and color), with measured results and test paths. Load before writing code.
```
references/critique.md
```
: the rubric to judge a render or sequence, in expert reading order, with the code check behind each question.
```
references/expert-notes.md
```
: principles per expert with timestamps, plus the disagreements table. Load for judgment calls and attribution.
```
references/sources.md
```
: the 15 videos, credentials, best timestamps, and which to consult for which question.

```
references/procedures.md
```
：每个阶段的经过测试的代码（从P1单位转换到P17曝光与色彩），包含实测结果和测试路径。编写代码前先加载。
```
references/critique.md
```
：评判渲染图或序列帧的标准，按专家评审顺序排列，每个问题背后都有对应的代码检查。
```
references/expert-notes.md
```
：每位专家的原则及对应视频时间戳，还有意见分歧对照表。需要做判断或标注来源时加载。
```
references/sources.md
```
：15个参考视频、专家资质、最佳时间戳，以及不同问题该参考哪个视频。