grimoire/build/threejs_texture_reference.md

# Three.js texture & PBR reference (notebooklm research, 2026-07-22)

Doc-grounded (threejs.org MeshPhysicalMaterial / MeshStandardMaterial / Texture / CanvasTexture /
DataTexture / manual §Textures). Drives `analyze_texture.py` (finish classification + recipe) and
the emitted `makeProceduralTextureSet` / material presets in `generate_threejs_factory.py`.

## Colour space — get this right or everything looks wrong
- **Albedo / `map` / `emissiveMap` / `sheenColorMap` → `THREE.SRGBColorSpace`.**
- **Data maps (`roughnessMap`, `metalnessMap`, `normalMap`, `aoMap`, `bumpMap`, `displacementMap`,
  `thicknessMap`, `anisotropyMap`) → `THREE.NoColorSpace`** (linear data, never sRGB).
- `CanvasTexture`: `flipY = true` (default), auto `needsUpdate` on construct.
- `DataTexture`: `flipY = false` (default) — memory (0,0) is bottom-left. Set `needsUpdate = true`.
- After changing `wrapS/wrapT` on an already-used texture you MUST set `needsUpdate = true`.
- `aoMap`/`lightMap` read UV channel 1 — geometry needs a 2nd UV set, or set `texture.channel = 1`.
- Tiling: `wrapS = wrapT = THREE.RepeatWrapping` + `repeat.set(u,v)`; set `anisotropy =
  renderer.capabilities.getMaxAnisotropy()` so oblique angles stay sharp.

## Per-finish material recipe (MeshPhysicalMaterial scalars)
| finishClass | metalness | roughness | clearcoat | ccRoughness | transmission | ior | envMapIntensity | anisotropy | author maps |
|---|---|---|---|---|---|---|---|---|---|
| `gemstone` (translucent quartz/glass) | 0.0 | 0.05 | 1.0 | 0.0 | 1.0 | 1.54 | 1.0 | 0.0 | map(gradient), thicknessMap |
| `gem-metal` (chromed doppler blade — our blend) | 0.75 | 0.14 | 0.6 | 0.06 | 0.0 | 1.5 | 1.3 | 0.0 | map(gradient+smoke), roughnessMap |
| `painted-metal` (glossy paint) | 0.0 | 0.5 | 1.0 | 0.05 | 0.0 | 1.5 | 1.0 | 0.0 | map, roughnessMap, clearcoatRoughnessMap |
| `worn-composite` (aged rubber/grip) | 0.0 | 0.9 | 0.0 | 0.0 | 0.0 | 1.5 | 0.5 | 0.0 | map(mottled), roughnessMap, bumpMap |
| `brushed-steel` | 1.0 | 0.35 | 0.0 | 0.0 | 0.0 | 1.5 | 1.0 | 1.0 | anisotropyMap, roughnessMap, normalMap |

> Note: pure `gemstone` (transmission 1.0) is see-through glass. A painted/anodised metallic blade
> (CS Doppler) is opaque — use `gem-metal` (metalness + gradient map + clearcoat, no transmission).

## Procedural map generation (in code)
- **CanvasTexture** — draw to an `HTMLCanvasElement`: linear/radial gradients across palette stops
  (gemstone/doppler), layered low-alpha blobs for smoke, per-pixel mottle noise for worn finishes,
  thin horizontal streaks for brushed metal. `new THREE.CanvasTexture(canvas)` then set `colorSpace`.
- **DataTexture** — push computed noise/height into a `Uint8Array`, `new THREE.DataTexture(arr,w,h,
  THREE.RGBAFormat, THREE.UnsignedByteType)`, `colorSpace = NoColorSpace`, `needsUpdate = true`.
- **Height → Normal (no native helper — compute it):** Sobel/neighbour-difference the height field →
  `R = (dx*strength + 1)*0.5*255`, `G = (dy*strength + 1)*0.5*255`, `B = 255` (up +Z), A = 255.
- **Independent channels** (skill rule, confirmed): never alias one map into another — albedo,
  roughness, normal/height, AO are separate signals with separate frequency content.

## Analysis → which finishClass?
`analyze_texture.py` classifies a reference crop by pure-stdlib stats:
- saturation + hue spread → chromatic gemstone vs neutral metal/grey.
- luminance gradient across the crop → `gradient` finish (doppler) vs flat.
- local variance / mottle → `worn-composite`.
- directional (horizontal) high-freq streaks → `brushed-steel`.
- specular-highlight fraction (very bright pixels) → metalness proxy.
Output: `{finishClass, palette:[stops], mottle, gradientAxis, metalnessHint}` → material recipe.