Forge Light

forge-light — Lighting Rigs & Color Management

The rendering pipeline's truthfulness depends entirely on this skill: wrong lights produce misleading material reads; wrong color management corrupts pixel values the QA loop uses to pass or fail. Get both right before dispatching a single render.

Project memory: if FORGE.md exists at the project root, read it first — it carries the established render engine (Cycles headless default on Windows), color view transform (AgX default for 4.x), output paths, and any per-project lighting notes. When ATELIER.md is also present, its world / aesthetic field sets the lighting mood (warm/cool, hard/soft, high-key/low-key) that governs parameter choices here.

Forge suite map

This skill sits in the lookdev pipeline alongside forge-material (PBR shading, Principled→glTF mapping) and forge-texture (baking, procedural maps). It is called before forge-render (headless Cycles/Workbench dispatch, turntable frames, contact sheet QA) — lighting must be configured before render dispatch. Geometry input comes from forge-model, forge-parametric, or forge-procedural. The full validation gate is forge-validate (manifold, normals, UV, glTF-Validator, render-QA escalation). For web delivery, forge-optimize handles DRACO/Meshopt/KTX2 compression and the atelier-webgl handoff.

Run any other Forge skill = call the Skill tool with its exact name. Writing "now run forge-render" in prose runs nothing — Run = call Skill("forge-render").

Decide first: rig type and color pipeline

Before touching bpy, resolve these two gates. Read FORGE.md; if absent, ask or infer from context.

Gate A — Lighting rig

Gate B — Color pipeline

Verify Blender is available before any render attempt (same preflight the other lookdev skills use):

python "$CLAUDE_CONFIG_DIR/skills/forge-render/scripts/preflight.py" --tools blender,python --json

If all_found is false (or blender is listed in missing), stop and instruct installation; blender_path gives the resolved blender.exe for the invocation below. Reference: references/blender-invocation.md.

The flow

1. Read FORGE.md (or gather scene constraints: bounding sphere, target engine, output path).

2. Decide rig + color pipeline (Gate A + B above). If ATELIER.md is present, map its aesthetic to lighting parameters using references/lighting-presets.md §1.

3. Build the bpy lighting script.

• Compute bounding sphere first — all rig distances are multiples of radius. Full helpers + three-point builder: references/three-point-rig.md.
• For HDRI/IBL: wire the world node graph with rotation control and optional packshot mode. Full HDRI node setup + PolyHaven download: references/hdri-ibl.md.
• For shadow catcher / cyclorama: references/shadow-catcher.md.
• For light linking (Cycles 4.0+): references/light-linking.md.
• For turntable catalog rig: references/turntable-catalog.md.

4. Configure color management in the same script.

• Always set view_transform, display_device, exposure, and gamma explicitly.
• Always set gamma = 1.0 — loaded .blend files may have non-default gamma.
• Tag texture color spaces on load (Non-Color for data maps; sRGB for albedo/emissive).
• Use image.save_render(), not image.save(), for display-ready PNG output.
• Full bpy color management API + OCIO details: references/color-management.md.

5. Write and invoke the Blender script headlessly (Windows PowerShell):

# Mandatory: -b BEFORE -P; user args AFTER the -- separator
& "C:\Program Files\Blender Foundation\Blender 4.5\blender.exe" `
    -b --factory-startup `
    -P "C:\forge\scripts\light_and_render.py" `
    -- "C:\assets\widget.glb" "C:\renders\widget_hero.png"

Gotcha: --factory-startup strips GPU device preferences. Re-apply GPU in script. Always use forward-slash paths in bpy.data.images.load() — use Path(...).as_posix(). Full invocation reference + GPU device flags: references/blender-invocation.md.

6. Verify render output. After render: confirm file exists and size > 1 KB, then Read the PNG to visually inspect:

• Product centred and fully in frame
• No pure-black areas outside the product (lights hitting the object)
• Shadow visible beneath product if shadow catcher is in use
• No fireflies (white single-pixel spikes → insufficient samples)

7. Optional: False Color QA pass. For exposure verification, run a False Color render before the production render. Middle gray (scene-linear 0.18) should appear as the "Gray" band (~RGB 128,128,128 in the false color output). See references/color-management.md §4 (False Color QA pass) and references/color-management-qa.md for the programmatic pixel checks.

8. Hand off to render dispatch. When lighting and color management are confirmed correct, invoke Skill("forge-render") for full turntable / contact-sheet production. Pass the configured scene path and output dir.

Key parameters at a glance

Three-point ratios (proven for product)

Key : Fill : Rim  =  1.0 : 0.35 : 0.60

• Key: 45° azimuth, 30° elevation — primary shadow definition
• Fill: opposite azimuth, 20° elevation — prevents shadow side going > 2 EV darker
• Rim: directly behind product (180° from camera), 60° elevation — edge separation

All distances are radius × 3.0; all sizes are radius × multiplier. Full Python builder with Kelvin→linear conversion: references/three-point-rig.md.

Light units (bpy)

AreaLight.normalize = True (default in 4.5): resizing keeps total Watts constant; bigger panel = softer shadows, same energy. To add both softness AND brightness, increase energy_w proportionally.

HDRI resolution guide

Color management quick-reference

View transform defaults: AgX (Blender 4.0+); Standard for game-engine exports; EXRs store raw scene-linear (no view transform applied on save).

Cycles sample budget

Critical gotchas (quick reference)

Full reproduce/fix snippets live in the per-topic references: lighting gotchas in references/shadow-catcher.md §4 (transparent-PNG black, colour cast, light-tree, is_shadow_catcher flag, factory-startup GPU) and references/light-linking.md §4 (poll error, slow convergence, EEVEE-ignored); colour gotchas in references/color-management.md §7 (+ Three.js/QA in references/color-management-qa.md).

Operating principles

• Compute the bounding sphere first. Every rig parameter (distance, size, energy) is a multiple of object radius. Never hard-code light positions in absolute world units.
• HDRI colorspace must be scene-linear, not sRGB. Use 'Linear Rec.709' (the canonical name in Blender 4.x's default OCIO config; fall back to 'Linear' if it raises ValueError, or call enumerate_colorspaces() from references/hdri-ibl.md). An HDRI loaded as sRGB is the single most common cause of blown-out or flat renders. Verify it on every HDRI load call.
• Set all color management properties explicitly in every script. Never rely on .blend file defaults for view_transform, gamma, or exposure — a saved file from an old Blender version will carry wrong values.
• Use save_render(), not save(). Only save_render() bakes the view transform into a PNG. save() writes raw scene-linear data and will look wrong in any image viewer.
• Verify with a read, not just a file-size check. After rendering, Read the PNG to visually confirm exposure, shadow presence, and absence of fireflies before reporting success.