Blender Image To 3D

Blender image to 3D

Turn one or more reference images into a delivered game asset by moving through gated phases. Every gate is passed with rendered evidence compared to the reference from the same camera and at gameplay pixel size, never by looking at the viewport and deciding it seems fine. Most wasted work in this pipeline is detail added on top of wrong proportions, so nothing gets detail until its silhouette passes.

"Perfect" here has a definition: the acceptance checklist in references/delivery-and-acceptance.md passes, the compare sheets show no measured deviation above the phase tolerance, and every dimension or side that the reference did not show is listed as inferred. Say so when a single image forces inference; do not present a guessed back as fact.

Runtime

• Blender 4.2 or newer (used through 5.2), run headless: blender --background --python <script> -- <args>. Blender 5.x changed several APIs these builds touch; references/blender-5-notes.md lists them with runtime, baking and review lessons. Resolve the binary once: $BLENDER_BIN, then blender on PATH, then /Applications/Blender.app/Contents/MacOS/Blender. Workbench renders need no GPU on macOS or Windows; on a headless Linux box without a GPU, pass --engine cycles to review_render.py.
• A live Blender session through an MCP server (execute-Python tool) is optional and useful for inspection. Even then, build through the numbered scripts and save the same master file, so the build stays reproducible. In a live session, exec(open(path).read()) a script and call its functions instead of the command line.
• All modelling is written as bpy code in <asset>/build/NN_<phase>.py, copied from assets/build_template.py. Each script opens the master, deletes what it owns, rebuilds it, saves. Rerunning any phase is safe. Constants are measured metres with a comment naming the reference view they came from, or # inferred.
• Skill scripts (all take -- --help):

Read references/categories.md for the asset's category before Phase 0. Read references/rigging-animation.md before Phase 6 and references/delivery-and-acceptance.md before Phases 1, 5 and 9. Read references/blender-5-notes.md when a script fails on a 5.x API or before long renders and bakes.

Gate protocol (used at the end of every phase)

1. review_render.py with --ref-cam AZ EL LENS (estimated in Phase 0) plus front,side,threequarter, in the mode the phase asks for, with --gameplay-px set to the subject's on-screen height in the game (default 128).
2. compose_review.py --measure against the reference view that matches the camera. Read the sheet and the numbers. Look at the images; the numbers catch drift the eye forgives. compose_review aligns the two silhouettes by their bounding boxes, so it cannot see a model that is too short or off its axis. For orthographic sheets, also run world_gate.py on cleaned reference mattes (labels, rulers, floor lines and anything the model does not include erased) and hold that number to the phase tolerance. When the reference's own views disagree (a cape wider in the front view than in the back view), record the conflict and the per-view ceiling as a deviation instead of chasing both.
3. Write the mismatches as measurements, not adjectives: "head 12 percent too tall", "wheelbase 0.3 m short", "band 4 width +0.06". Fix the constants in the build script, rerun the phase, re-render. Repeat until every mismatch is inside the phase tolerance.
4. Show the user the compare sheet, the remaining deviations, and what was inferred. Continue on approval. If the user said not to ask, continue when the tolerance is met and keep the sheets in review/ for them. If the user reviews in a live viewport, reload the master there after each rebuild: anything hidden only for rendering (a mannequin under the costume) still shows in their view.

Tolerances: blockout IoU 0.85 and every band width within 0.05 of the reference (0.90 and 0.03 for forms); proportions within 5 percent (blockout) and 2 percent (forms) on the measurements listed in the brief; materials pass when each role reads correctly under the moving light of a material turntable and in greyscale at gameplay size.

Phase 0: read the reference, write the brief

Look at every supplied image before touching Blender. Write <asset>/asset-brief.md in this exact structure:

ASSET      prefix and name (CH_, CR_, AR_, VH_, PR_, WP_, EN_)
CATEGORY   character | creature | architecture | vehicle | prop | weapon | environment, plus subtype (biped, quadruped, winged, wheeled, tracked, modular kit, hinged prop)
VIEWS      per image: view type (front, side, back, top, three-quarter, concept), estimated camera azimuth, elevation, lens (0 = orthographic), how much of the image height the subject fills, where the ground line sits
SCALE      real size along each axis with the evidence (human height, door, wheel, brick course, weapon grip); state the number used
PROPORTIONS 8 to 15 ratios measured in the image that the blockout gate will check (head heights, shoulder width to height, wheelbase to length, storey height to width)
PARTS      every part in construction and overlap order; for each: separate object yes/no, rigid/deforming/simulated, attaches to, moves about (pivot)
SILHOUETTE the 3 to 5 features that make it read at gameplay size
MATERIALS  per part: role (skin, scales, worn leather, painted metal, carved stone, glass), colour, roughness range, wear pattern
ARTICULATION rig family, joints or pivots, sockets needed, animation needs (none / idle only / full library)
INFERRED   every side, dimension or part the images do not show and the prior used to fill it
TARGET     engine, export format, budget tier from the table, game camera (elevation, distance, lens), subject height in pixels at typical gameplay distance

Ask the user only for what the images cannot tell: target engine and format, real size when no scale cue exists, budget tier, whether rigging and animation are needed, the game camera. Offer these defaults and proceed with them when the user says to just go: 1 unit = 1 m, Z up in Blender with the subject facing -Y, GLB export, standard tier from the budgets table, a three-quarter overhead camera at 50 mm, 128 px subject height, rig only if the category deforms, no animation unless asked.

Keep every reference as a file in <asset>/ref/ under a descriptive name before Phase 1: the scripts load references from disk, and images pasted into the conversation arrive as temporary files, so copy them there first.

Multi-image references: any number of images can come in one request. Mark which views are orthographic sheets (measure from these) and which are perspective concepts (silhouette and detail only, never proportions). Conflicting images: the orthographic sheet wins for dimensions, the concept wins for surface detail; say which was used where. One image can also hold several views (a turnaround or model sheet with front, side and back panels and detail callouts): give each panel its own VIEWS entry with its pixel box, crop the orthographic panels into separate files that share one scale and ground line (ref/front.png, ref/side.png, ref/back.png) for init_master.py and the gates, and use the callouts for surface detail. Photographs: estimate the lens from perspective convergence (long lens for telephoto product shots, 24 to 35 mm for phone photos), and match it in --ref-cam.

For a request covering several assets, run one asset per category through all phases first (one character, one creature, one kit piece, one vehicle), get those approved, then apply the proven scale, rig, material and export rules to the rest. Each role still gets its own forms and motion; a shared rig family does not mean shared proportions.

Phase 1: calibration and master file

Decide the canonical unit before any modelling and keep it: 1 unit = 1 m, Z up, -Y forward, origin at the ground contact point (ground centre for vehicles, grid corner for kit pieces). If the target game uses other logical units, choose once between converting every dependent value (movement speed, reach, cell size, colliders, camera offsets) with a documented factor, or mapping only at the render boundary. Never shrink the asset alone while gameplay metrics stay in old units.

The commands in this file use an illustrative 1.85 m knight (CH_Knight, Unity); take every asset-specific value (name, height, camera, budget, engine, inferred list) from the brief.

$BLENDER_BIN --background --python scripts/init_master.py -- \
  --out CH_Knight/CH_Knight_master.blend --name CH_Knight --height 1.85 \
  --ref-front ref/front.png --ref-right ref/side.png --ref-extra ref/concept.png \
  --subject-frac 0.88 --ground-frac 0.04 --cell 2.0 --cam-elev 50 --cam-az 30 --cam-dist 12 --cam-lens 50

This writes the collections (REF, HIGH, LOW, RIG_CTRL, RIG_DEF, COLLISION, SOCKETS, EXPORT), a ruler at the target height with metre ticks, a grid cell, door clearance, a collision capsule, the game camera, and the reference images as standing planes at real scale with their ground line on z = 0. Every asset passes through this calibration; a hero, an enemy and a doorway that were never in the same file at the same scale will not fit each other in the engine.

Naming from references/delivery-and-acceptance.md: CH_Knight_Body_LOD0, DEF-upper_arm.L, SOCKET_hand.R, COL_torso, CUT_window. No .001 names in anything that ships.

Phase 2: blockout and silhouette gate

Build build/02_blockout.py from the template. Primary masses only: torso, head, pelvis and limbs as simple volumes; body shell, wheels and cabin for a vehicle; floor, walls, roof and openings for a kit piece. Hands, feet, jaw, horns, wings, doors, turrets and other appendages are separate rough objects from the start. Joint centres and pivots are placed now, at the positions the brief measured, because everything later hangs off them.

Check weight and balance: feet and hips that can support the mass, a forward driving line for a runner, a ribcage and pelvis for a quadruped, a neck and wing root that can carry the intended action, wheels under the mass of a vehicle. Add costume, armour, cladding and panels as distinct volumes. Check weapon reach, hand clearance, door swing and the silhouette in the most extreme pose or state the asset will hit (attack, crouch, turn, full steering lock, door open).

Gate in clay and silhouette modes, LOW collection, --show-ref once to confirm scale against the ruler. The category must read from the game camera without texture, particles or labels. For multi-asset work, render the greybox lineup at relative scale and check that roles differ in shoulder width, head shape, posture and stance, not only colour.

$BLENDER_BIN --background --python scripts/review_render.py -- --blend CH_Knight/CH_Knight_master.blend \
  --out CH_Knight/review/02_blockout --collections LOW --views front,side,threequarter \
  --ref-cam 35 12 50 --mode clay --gameplay-px 128
python scripts/compose_review.py --ref ref/front.png --render CH_Knight/review/02_blockout/clay_front.png \
  --out CH_Knight/review/02_blockout/compare_front.png --measure --gameplay-px 128