scenario-labs / scenario-blender-uv-baking

UV unwrapping and baking

Expert-level UVs put seams where the texturing method can afford them, set texel density before texture size, and pack with pixel-true padding. Expert bakes measure their projection distances instead of guessing, and are judged in pixels and under a raking light, never eyeballed once. Every stage below has a measurable gate that [`scripts/bx_uvbake.py`](scripts/bx_uvbake.py) computes. 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).

Stance (the expert delta)

• Seams follow the texturing method. Kaspar (2021, 2D painting): as few as possible, hidden under hair, clothes and inner limbs. Blender Studio guide (2024, same author): more seams rather than fewer when you paint in 3D or bake, because stretch costs more. Game bakes add a hard rule: every hard edge is a seam, or the normal map cracks (Lampel, Gambrell, On Mars 3D, Polycount).
• Only closed shells and long tubes need extra cuts. Morren: anything closed on itself needs one cut. Gambrell: cut every taped-paper ring once, hidden. But an island with holes (a face with eye holes, a washer) flattens fine. cut_to_disks test-unwraps it and cuts only if it stretches [added; cutting everything folded the sheep's big islands].
• Unwrap method is a measurement, and 5.2 defaults to CONFORMAL. Always pass method=. On Suzanne, Minimum Stretch gives the most even density (spread 1.38), Angle Based the best angles, and Conformal fails by area (5.89). On flat hard-surface islands all three converge. unwrap(method="BEST") picks per island and rejects islands that fold over themselves.
• Density first, texture size second (Huge Menace). Targets: FPS 10.24 px/cm, weapon 20.48, third person 5.12, top-down 2.56. Priority follows the camera: face, hands and front up; soles, inner mouth and back down (SpeedChar, Kaspar). Match texture sets by scaling the denser set down, never the other up (Gambrell).
• Straighten, then equalize, then pack without tilting (Lampel): Follow Active Quads from a truly rectangular quad, pin, re-unwrap the rest, pack with CARDINAL. Padding is a pixel number, res/128 (16 px at 2K), passed as FRACTION margin = gap/(2*res).
• Measure the projection, never guess extrusion, and do not trust one global value. Ryan King's 0.01 then 0.02 was scene-specific. SpeedChar swept six values by hand, and the value that fixed the face broke the armpit ("when we fix something somewhere, some other problems occur", E6QMhGuhyoc [00:26:23]). Rays start on the low, and max_ray_distance counts from the extruded start. The adaptive bake keeps, per texel, the smallest extrusion that hits a front face. On the sheep it cut inverted texels from 7.5% to 1.2% [verified].
• Unique UVs wherever baked lighting differs (SpeedChar: an AO ghost means shared texels). Stacked or mirrored copies move exactly one tile out of 0-1 before the bake (Polycount), because inside 0-1 the last island baked wins.
• A bake is judged in pixels and under light. Blue < 0.5 means rays hit the far side. Exactly flat means rays missed. All-white AO means the distance is too small. Inverted pixels that do not move when extrusion changes point to a geometry problem, not a setting [verified on the sheep]. Multires bakes cast no rays: on the same surface they gave 0.09% inverted texels.

Establish first

Workflow

1. Pre-flight. Apply scale (On Mars 3D: it "fixes the vast majority" of problems). Clear non-manifold geometry, doubles and back faces (SpeedChar). Decide on Mirror and Solidify modifiers. If UVs exist, compare island_topology with uv_qa islands: seam flags in files are often leftover retopology marks, so run seams_from_uv_islands (Lampel) before re-unwrapping. GATE: scale 1, bx_audit clean, topology table read.
2. Seams. Hard surface: seams_from_sharp(obj, 30, mark_sharp=True). Organic: build part labels (head, ears, limbs, torso front and back, soles, inner mouth and eyelids per the Kaspar and Morren seam maps in [`references/expert-notes.md`](references/expert-notes.md)), then seams_from_groups(obj, labels). Specific cuts: seam_path(obj, v_a, v_b, view_dirs). Then cut_to_disks(obj, view_dirs=[camera]). GATE: must_cut empty; a checker render shows no seams across hero areas that the brief cannot afford.
3. Unwrap. unwrap(obj, method="BEST"), or the method the island type calls for. GATE: unsolved_faces 0 (the operator returns FINISHED even when it fails), folding_islands empty (else seams_from_groups(..., faces=folding_faces) and unwrap again), angle p95 at most 15 to 20 deg.
4. Straighten grid-like islands (hard surface, garments, strands): straighten(obj) before any scaling. GATE: straight stripes in the checker.
5. Texel density. normalize_texel_density(obj, target, res, weights), then texture_size_for(obj, target). GATE: island spread within 10-20%, or the intended priority ratios.
6. Pack. pack(obj, tex_res=res), with scale=False for a strict density and allow_any=True for organic islands. UDIM: pack each region, then move_to_tile. GATE: uv_qa: 0 overlaps, gap at least res/128, border at least gap/2, coverage at least 0.70 or an explained exception.
7. Look. uv_layout_image, checker_review, distortion_review(metric="angle"). Judge with [`references/critique.md`](references/critique.md).
8. Bake prep. prepare_low(low, triangulate=game, sharp_from_uv_islands=hard_surface). Check the silhouette against the high (bx_audit.audit(low, high=...)). Explode interpenetrating or moving parts (explode, one axis). Run measure_projection: miss_pct under 2 and wrong_part_pct under 1, else use a cage, explode, or bake per pair.
9. Bake. bake_high_to_low(low, highs, out, res=512) first, then the final resolution. It uses adaptive extrusion by default and hides every other object from render. Multires: bake_multires. Extras: bake_id, curvature_from_normal. GATE: sanity[...]["problems"] empty (inverted texels under 2%, notes from 0.2%), 16-bit PNG. If inverted texels remain, run map_problem_review to see where. If sweep_projection shows they do not move with extrusion, fix the geometry (fit, holes, thin parts), not the numbers.
10. Review and hook up. bake_review(low, highs, paths, out): the low with maps must read like the high under the raking light. Then hookup_maps. Report measured numbers and what was not verified.

Numbers

Quality gates

Code: q = uv_qa(obj, res), then uv_verdict(q, "game" or "film", priorities=...). unwrap()["unsolved_faces"] and ["folding_islands"]. measure_projection(). bake_high_to_low()["sanity"] (inverted, exact-flat, non-unit, AO black and white). Cross-check overlaps with bpy.ops.uv.select_overlap() when in doubt; it agreed with the raster on the tests.

Visual: layout PNG (islands, magenta overlaps), color-grid checker from front, side, three-quarter and the production camera (squares square, letters upright, seams hidden), angle and density heat maps, bake_review sheet (high, low, low + maps), map_problem_review when sanity flags pixels.

Common mistakes

Blender 5.2 notes

• uv.unwrap defaults to CONFORMAL. On failure it keeps the island's old UVs and repacks them. It has use_weights/weight_group (default group "uv_importance"): importance weights with Minimum Stretch. A weighted top half went from 31% to 74% of UV area [verified].
• Sync select is on by default (5.0). BMLoopUV only has uv and pin_uv. A me.uv_layers[...] reference goes stale after an Edit Mode toggle, so keep the name.
• pack_islands(udim_source="CLOSEST_UDIM") headless packed a region sitting in 1002 back into 1001: pack first, then move. uv.move_on_axis needs a UV editor.
• Bake: the target must be selected AND active (5.0). Operator defaults differ from scene defaults (use_clear False vs True, EXTEND vs ADJACENTFACES): pass everything. Selected to Active uses the low's render evaluation (Multires renderlevels, shape keys). Multires settings live in scene.render.bake.use_multires with object.bake_image(). A float image saved as PNG is 16-bit. Normal Map node convention OPENGL/DIRECTX (5.1). UDIM tiles need image.tile_add(fill=True).
• Auto Smooth is gone (4.1): smooth shading plus sharp edges; Triangulate "Keep Normals" is keep_custom_normals.

References

• references/expert-notes.md: judgment by expert with timestamps, disagreements and deciding conditions, my 5.2.1 measurements. Load when choosing seams, density or a bake strategy.
• [`references/procedures.md`](references/procedures.md): tested pipelines (hard-surface, character, film/UDIM, Multires, bake-fix loop) and raw bpy snippets executed by the tests. Load before writing code.
• references/critique.md: rubric for seams, stretch, density, packing, bake setup and baked maps, with proxies and severity. Load at every gate.
• [`references/sources.md`](references/sources.md): videos, credentials, URLs, best timestamps, web references.
• scripts/bx_uvbake.py: the module (docstrings list every function).