grimoire/build/geometry_patterns.md

Procedural Three.js Object Patterns

Use this reference only when implementing a model.

Geometry Choices

• box: flat machinery, furniture, panels, blockout masses
• sphere/ellipsoid: fruit, knobs, organic joints, rounded stones
• cylinder/cone/capsule: trunks, pipes, limbs, handles, bottles, rockets
• torus: rings, tires, loops, trim, cable coils
• shape extrude: logos, flat ornamental plates, blades, keys, leaves
• lathe: vases, bottles, bowls, lamps, wheels
• tube along curve: cables, roots, branches, straps, hoses
• instanced mesh: screws, rivets, leaves, needles, scales, pebbles, repeated ornaments
• plane cards: thin leaves, feathers, labels, cloth strips, decals

Material Recipes

• wood: brown base, vertical grain normal, roughness variation, darker creases, lighter worn edges
• stone: mottled albedo, high roughness, bump/normal noise, lichen/dirt patches
• metal: lower roughness, metalness, edge scratches, anisotropic-looking streaks via texture
• plastic: controlled roughness, subtle color variation, bevels to catch highlights
• leaf/plant: alpha cards or thin shape geometry, green hue variation, central vein, translucent-ish bright rim
• water/glass: transparent material only if needed; add environment/reflection cues or it reads as a flat sheet

Material Layer Fields

For each material, prefer a layered description:

• baseColor: dominant sampled color.
• colorVariation: palette, mottling pattern, amplitude, regional masks.
• roughness: base value, variation amount, map/pattern source.
• metalness: base value and local changes.
• normal: procedural pattern, strength, scale.
• bump: amplitude and scale for small tactile relief.
• displacement: only for silhouette-visible or close-up relief.
• wear: edge wear, scratches, chips, polish, exposed underlayer.
• dirt: amount, cavity bias, color, vertical streaking, contact staining.
• localOverrides: named regions where color/roughness/bump differs from the base.

Local overrides should answer: where, what changes, how strong, and which image evidence supports it.

Local Feature Types

Use component.localFeatures for details that matter to recognizability:

• raised ridge
• recessed groove
• seam line
• screw or rivet
• chip or dent
• scratch cluster
• stain or dirt patch
• decal or label area
• hole or socket
• bevel highlight
• fabric stitch
• leaf vein or serrated edge

Each feature should include placement, approximate size, orientation, material effect, geometry effect, and confidence.

Detail Recipes

Concrete Three.js material/geometry approach per detailInventory kind. Cross-reference grimoire/intake/detail_inventory.md for the full taxonomy and the evidence/mapping rule.

• gloss: MeshPhysicalMaterial with a low-roughness localOverride (0.05-0.2) sized to the hotspot region; use clearcoat/clearcoatRoughness for a lacquer layer over a rougher base, anisotropy/anisotropyRotation for brushed/streaked highlights.
• bevel: real geometry, not a normal map - edgeTreatment.type = chamfer, bevelRadius object-relative (0.02-0.08), segments 2-4 for a soft catch-light rim, 1 for a hard edge.
• fastener: InstancedMesh for the repeated part; count + spacing pattern (linear, radial, grid) + head shape (hemisphere/flat/hex) + recess (raised vs countersunk); low-roughness metal material on the head crown.
• linework: pick engraved groove (real recessed geometry along a path, catches shadow), painted line/decal (canvas-texture localOverride, color contrast only, no relief), or panel-line (thin dark AO/roughness localOverride along a seam, no depth) - match whichever the reference evidence shows; do not default to decal for something that casts a shadow.
• stain: material.localOverrides region with dirtAmount, cavityBias (concentrate in crevices), streak (directional, usually gravity-down), patinaColor for oxidation hue shift, or a fadedMask (lighter, desaturated) for sun-bleaching - the inverse of dirt.

Character Geometry And Material Recipes

Use these when objectClass.primaryDomain is character or hybrid. Pair with grimoire/character/reconstruction.md for proportion/landmark data.

• head: sphere or ellipsoid scaled to the measured head-unit, then displaced/tapered toward the reference face shape (jaw width, chin point, cheek fullness) rather than left spherical.
• limbs: capsule or tapered cylinder per segment (upper arm, forearm, thigh, shin); taper ratio and length come from anatomy.proportions; capsules keep joints visually continuous.
• hands: simplified capsule-cluster (palm block + finger capsules) at low segment count; do not attempt per-knuckle detail unless the reference is close-up and complexity is ultra.
• hair: hair cards (alpha-mapped planes layered in clumps) for stylized/low-complexity, or a tube-along-curve per lock for wavy/flowing hair with visible strand structure; prefer cards by default - hair is the classic single-image failure mode, so favor legible clumps over many thin strands that swim or alias.
• face feature placement: position eyes, brows, nose, mouth using anatomy.faceLandmarks normalized coordinates (eyeLine, eyeSpacing, noseBase, mouthLine, hairline); never eyeball placement freehand once landmarks exist.
• eyes: glossy sphere (low roughness, slight clearcoat) plus an iris decal/texture; a correct catchlight (small bright localOverride matching the key light) sells more realism than extra geometry.
• clothing: extrude or plane panels per garment piece, with fold normals (a normal-map or displacement pattern following expected gravity/pose creases) rather than a flat shell; reuse Track A detail machinery (seam, stitch, decal, stain) for prints, buttons, wear.
• skin: approximate subsurface scattering, not true SSS - warm base albedo, soft/lower roughness variation (skin is not uniformly matte), and a rim or backlight to fake light passing through thin tissue (ears, nose edge). Avoid pure-Lambertian flat skin.

Verification Cues

A procedural object is usually failing when:

• silhouette reads wrong even before material
• every edge is perfectly sharp or perfectly smooth
• material has one flat color and no roughness variation
• lighting hides the form instead of explaining it
• repeated details are too evenly spaced
• close-up details add triangles but not recognizability

---

Hard-won patterns — real-object reconstructions (2026-07: BMX bike + M9 bayonet)

Tube-network > single sweep for framed/tubular subjects. A bike frame, knife-handle grip, fork, handlebar are networks of straight members. Model each member as a component with attachment.localStart/localEnd (+baseRadius) — the generator emits an oriented cylinder (quaternion Y→dir). A single closed curve-sweep CatmullRom-smooths into a teardrop blob. (BMX frame was a teardrop until rebuilt as a tube-network.)

Blockout must contain every silhouette-defining macro part. A bike blockout with the frame but no wheels does not read as a bike, and coarse silhouette-IoU won't catch the omission. Put wheels/blade/major masses in at level: macro.

Root/container transform.scale MUST be [1,1,1]. Children parent to the root node and inherit its transform — a 0.02 "hide" scale shrinks the whole model to a speck. Hide the container with a transparent material (opacity:0), never with scale.

Cloned components inherit actionProfile.animationRole — reset it. Cloning a seeded root carries animationRole:"root", and root ∈ ATTACHMENT_ROLES, so every part trips the structural attachment gate. Set a sensible per-part animationRole (e.g. "static-part"); keep roles like handle off non-appendage parts.

Curve the small details. Serrations/scallops/teeth as straight boxes look wrong. Use ellipsoid (or slightly canted primitives, alternating ±angle) for rounded scallop teeth. Each detail with its own small cant reads as a hand-ground edge.

Grip / friction texture = geometric ridge segments. For a knurled/wrapped/segmented grip, model raised barrel bands: a thin core cylinder + N short attachment-tube segments (radius just proud of the core, small groove gaps). Size them barely larger than the core — oversized tori read as a coil/spring, not a grip. Material texture alone (no geometry) reads as smooth/"thô".

invisibleRoot/container material is still subject to the material-pass PBR gate. Give the container a complete material (roughness map, frequency bands, textureResolution) — copy a proven one — or it fails "needs usable referencePbr / roughness map" even though it never renders.