partforge 0.123.0 → 0.125.0

package/src/framework/materials/contact-shadow.js

@@ -110,7 +110,12 @@ export function createContactShadow({ renderer, sizeMm = 400 }) {
   // While a part moves (lowRes) only the soft layer is redrawn and the tight
   // one is hidden: an outline left where the part WAS would be wrong, and the
   // settle render that follows brings it back.
-  function render(scene, casters, { lowRes = false } = {}) {
+  //
+  // `clippingPlanes` (world space) clip the casters the way the cutaway clips
+  // what is on screen. The depth pass draws every caster with the one override
+  // material, which carries none of the casters' own clipping planes, so
+  // without this the half the cutaway removed still cast its shadow.
+  function render(scene, casters, { lowRes = false, clippingPlanes = null } = {}) {
     const bg = scene.background;
     const overrideBefore = scene.overrideMaterial;
     const clear = renderer.getClearAlpha();
@@ -123,6 +128,7 @@ export function createContactShadow({ renderer, sizeMm = 400 }) {
       renderer.setClearAlpha(0);
       for (const l of layers) {
         if (lowRes && l.spec.name === "tight") continue;
+        setClipping(l.depthMaterial, clippingPlanes);
         scene.overrideMaterial = l.depthMaterial;
         renderer.setRenderTarget(l.rt);
         renderer.render(scene, cam);
@@ -143,6 +149,27 @@ export function createContactShadow({ renderer, sizeMm = 400 }) {
     }
   }
 
+  // A new plane count needs a new program; the same planes moved do not (three
+  // reads their values every frame).
+  //
+  // A clipped pass also draws BOTH sides, depth-tested. The pass looks UP at
+  // the casters, and a cut that removes a part's underside (a kept side facing
+  // up, e.g. a top-view cut after Flip) leaves no downward-facing faces at the
+  // cut — from below only back faces remain, which FrontSide culls, and the
+  // shadow shrinks to a faint ring of side walls. The interior back faces fill
+  // the silhouette instead, and the depth test keeps the LOWEST surface under
+  // each texel (the one the ground's darkness is measured from) rather than
+  // whichever face drew last. Unclipped, the pass is exactly as before:
+  // front faces, no depth test.
+  function setClipping(material, planes) {
+    const next = planes?.length ? planes : null;
+    const side = next ? THREE.DoubleSide : THREE.FrontSide;
+    if ((material.clippingPlanes?.length ?? 0) !== (next?.length ?? 0) || material.side !== side) material.needsUpdate = true;
+    material.clippingPlanes = next;
+    material.side = side;
+    material.depthTest = material.depthWrite = !!next;
+  }
+
   return {
     group,
     render,

package/src/framework/materials/environment.js

@@ -94,21 +94,32 @@ export async function loadEnvironmentRig(renderer, requestedId, { loadHdr, loadT
   if (env.ground.bed) {
     const material = groundMaterial(tex, rough, normal, { ...env.ground, bed: true });
     const bed = createPrintBed({ pei: material, tileMm: env.ground.tileMm ?? env.ground.sizeMm, createCanvas });
-    // An enclosure's LED bar: one hard overhead light, riding with the bed so
-    // it always falls on the part from the same place.
+    // An enclosure's LED bar: one hard overhead light, aimed at the bed's own
+    // origin. The LIGHT itself is deliberately not a child of bed.object:
+    // updateForCamera hides that whole group from below, and a hidden parent
+    // stops three from rendering its children too — the light would go dark
+    // exactly when the part needs it lit from underneath. It rides in
+    // `lights` instead and is repositioned by hand wherever the bed moves.
+    // The target CAN stay a child (matrixWorld updates regardless of
+    // visibility), which is what lets it keep tracking the bed for free.
     let keyLight = null;
     if (env.keyLight) {
       keyLight = new THREE.DirectionalLight(0xffffff, env.keyLight.intensity);
-      keyLight.position.set(...env.keyLight.direction);
-      bed.object.add(keyLight, keyLight.target);
+      bed.object.add(keyLight.target);
     }
     return {
       id, exposure: env.exposure, envMap, background, backgroundBlurriness, backgroundIntensity,
       rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
       ground: bed.object,
+      lights: keyLight ? [keyLight] : [],
       shadow,
+      updateForCamera(camera) { bed.updateForCamera(camera); },
       setGround({ y, centerX = 0, centerZ = 0, radius, footprintMm = radius }) {
         bed.place({ y, centerX, centerZ, footprintMm });
+        if (keyLight) {
+          const p = bed.object.position; // the fixed offset off the bed's origin
+          keyLight.position.set(p.x + env.keyLight.direction[0], p.y + env.keyLight.direction[1], p.z + env.keyLight.direction[2]);
+        }
         shadow.group.position.set(centerX, y, centerZ);
         // The shadow plane never hangs past the plate's edge into thin air.
         const s = Math.min(Math.max(radius * 3, 20), bed.sizeMm);
@@ -147,6 +158,7 @@ export async function loadEnvironmentRig(renderer, requestedId, { loadHdr, loadT
     backgroundIntensity,
     rotationY: ((env.rotationDeg ?? 0) * Math.PI) / 180,
     ground,
+    lights: [],
     shadow,
     setGround,
     dispose() {

package/src/framework/materials/patterns.js

@@ -45,10 +45,22 @@ uniform sampler2D pfNormalMap;
 uniform sampler2D pfRoughMap;
 uniform float pfRoughMean;
 uniform float pfNormalStrength;
+uniform vec3 pfGrainSwap;
 varying vec3 vPfNmX;
 varying vec3 vPfNmY;
 varying vec3 vPfNmZ;
 vec3 pfTriplanarWeights(vec3 n) { vec3 w = pow(abs(n), vec3(4.0)); return w / (w.x + w.y + w.z); }
+// One grain direction on every face: each projection's UV pair is transposed
+// where pfGrainSwap says so (grainSwaps below), so the texture's grain lands on
+// the sub-part's grain axis. A transpose is a mirror, not a rotation, which is
+// what keeps the normal map exact: its slopes just swap axes (t.yx), no signs.
+vec2 pfGrainUv(vec2 ab, float s) { return mix(ab, ab.yx, s); }
+vec3 pfTriplanarWood(sampler2D map, vec3 p, vec3 n) {
+  vec3 w = pfTriplanarWeights(n);
+  return texture2D(map, pfGrainUv(p.yz, pfGrainSwap.x) / pfPatternScale).rgb * w.x
+       + texture2D(map, pfGrainUv(p.xz, pfGrainSwap.y) / pfPatternScale).rgb * w.y
+       + texture2D(map, pfGrainUv(p.xy, pfGrainSwap.z) / pfPatternScale).rgb * w.z;
+}
 // Triplanar tangent-space normal map, whiteout-blended (Golus, "Normal Mapping
 // for a Triplanar Shader"). Each projection's map is read as a height field over
 // the two object axes its UVs run along, so its tangent normal (x, y) is a slope
@@ -59,10 +71,13 @@ vec3 pfTriplanarWeights(vec3 n) { vec3 w = pow(abs(n), vec3(4.0)); return w / (w
 // Poly Haven "nor_gl" convention. Returns an OBJECT-space unit normal.
 vec3 pfTriplanarNormal(vec3 p, vec3 n, float scale) {
   vec3 w = pfTriplanarWeights(n);
-  vec3 tx = texture2D(pfNormalMap, p.yz / scale).xyz * 2.0 - 1.0;
-  vec3 ty = texture2D(pfNormalMap, p.xz / scale).xyz * 2.0 - 1.0;
-  vec3 tz = texture2D(pfNormalMap, p.xy / scale).xyz * 2.0 - 1.0;
-  tx.xy *= pfNormalStrength; ty.xy *= pfNormalStrength; tz.xy *= pfNormalStrength;
+  vec3 tx = texture2D(pfNormalMap, pfGrainUv(p.yz, pfGrainSwap.x) / scale).xyz * 2.0 - 1.0;
+  vec3 ty = texture2D(pfNormalMap, pfGrainUv(p.xz, pfGrainSwap.y) / scale).xyz * 2.0 - 1.0;
+  vec3 tz = texture2D(pfNormalMap, pfGrainUv(p.xy, pfGrainSwap.z) / scale).xyz * 2.0 - 1.0;
+  // a transposed sample's slopes run along the swapped axes
+  tx.xy = pfGrainUv(tx.xy, pfGrainSwap.x) * pfNormalStrength;
+  ty.xy = pfGrainUv(ty.xy, pfGrainSwap.y) * pfNormalStrength;
+  tz.xy = pfGrainUv(tz.xy, pfGrainSwap.z) * pfNormalStrength;
   tx = vec3(tx.xy + n.yz, abs(tx.z) * n.x);   // uv = (y, z), face axis x
   ty = vec3(ty.xy + n.xz, abs(ty.z) * n.y);   // uv = (x, z), face axis y
   tz = vec3(tz.xy + n.xy, abs(tz.z) * n.z);   // uv = (x, y), face axis z
@@ -102,11 +117,12 @@ const FRAG_BODY = {
   // author tinted it, physical.js — and the roughness map varies roughnessFactor
   // around the preset's value (divided by the map's own mean, so the preset sets
   // the average). Mipmaps (and RepeatWrapping) do the far-distance filtering.
+  // All three maps follow the grain axis (pfTriplanarWood / setGrainAxis).
   wood: `
   {
     vec3 pfN = normalize(vPfObjNormal);
-    diffuseColor.rgb *= pfTriplanar(pfPatternMap, vPfObjPos, pfN, pfPatternScale);
-    float r = pfTriplanar(pfRoughMap, vPfObjPos, pfN, pfPatternScale).g;
+    diffuseColor.rgb *= pfTriplanarWood(pfPatternMap, vPfObjPos, pfN);
+    float r = pfTriplanarWood(pfRoughMap, vPfObjPos, pfN).g;
     roughnessFactor = clamp(roughnessFactor * r / pfRoughMean, 0.02, 1.0);
   }`,
   // Carbon samples a luminance MASK (raw, not sRGB-decoded: physical.js) and
@@ -164,7 +180,40 @@ const FRAG_NORMAL = {
   }`,
 };
 
-export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1 } = {}) {
+// Wood grain: real wood has ONE grain direction, the board's long axis, but a
+// triplanar projection with fixed UVs (X-faces (y, z), Y-faces (x, z), Z-faces
+// (x, y)) lands the texture's grain on a different object axis per face — on a
+// block, adjacent faces showed grain at right angles. So each sub-part gets a
+// grain axis (its longest object-space bounding-box axis, X on a tie) and every
+// projection whose face CONTAINS that axis is transposed where needed so the
+// texture's grain runs along it. Faces across the axis are end grain; there is
+// no end-grain texture, so they keep the default sample.
+//
+// `grain` is which texture axis a scan's figure runs along ("u" horizontal, "v"
+// vertical in the image), declared per texture set in presets.js.
+const PLANE_AXES = [[1, 2], [0, 2], [0, 1]]; // each projection's (u, v) object axes
+export function grainAxisFor(box) {
+  if (!box || box.isEmpty?.()) return 0;
+  const s = [box.max.x - box.min.x, box.max.y - box.min.y, box.max.z - box.min.z];
+  const eps = Math.max(...s) * 1e-6;
+  let axis = 0;
+  for (let i = 1; i < 3; i++) if (s[i] > s[axis] + eps) axis = i;
+  return axis;
+}
+export function grainSwaps(axis, grain = "u") {
+  const want = grain === "v" ? 1 : 0;
+  return PLANE_AXES.map(([u], face) => (face === axis ? 0 : (axis === u ? 0 : 1) !== want ? 1 : 0));
+}
+// Point a wood material (and every clone sharing its uniforms) at a grain axis.
+// A no-op on any other material.
+export function setGrainAxis(material, axis) {
+  const u = material?.userData?.patternUniforms?.pfGrainSwap;
+  if (!u) return;
+  material.userData.pfGrainAxis = axis;
+  u.value.fromArray(grainSwaps(axis, material.userData.pfGrain));
+}
+
+export function applyPattern(material, { kind, scale = 1, printFrame, texture, normalMap, roughnessMap, roughnessMean = 0.5, normalScale = 1, grain = "u" } = {}) {
   if (!kind || !FRAG_BODY[kind]) return material;
   const wood = kind === "wood";
   const uniforms = {
@@ -176,9 +225,11 @@ export function applyPattern(material, { kind, scale = 1, printFrame, texture, n
       pfRoughMap: { value: roughnessMap ?? null },
       pfRoughMean: { value: roughnessMean },
       pfNormalStrength: { value: normalScale },
+      pfGrainSwap: { value: new THREE.Vector3() },
     } : {}),
   };
   material.userData.patternUniforms = uniforms;
+  if (wood) { material.userData.pfGrain = grain; setGrainAxis(material, 0); }
   material.onBeforeCompile = (shader) => {
     Object.assign(shader.uniforms, uniforms);
     shader.vertexShader = shader.vertexShader

package/src/framework/materials/physical.js

@@ -72,6 +72,7 @@ function buildPhysical(display, { printFrame, loadTexture } = {}) {
       roughnessMap: load(set.roughness, THREE.NoColorSpace),
       roughnessMean: set.roughnessMean,
       normalScale: set.normalScale,
+      grain: set.grain,
     });
     return m;
   }

package/src/framework/materials/presets.js

@@ -8,15 +8,12 @@
 // converted to sRGB. Adding a preset is one record here plus a look at the
 // contact sheet (materials.html) in every environment.
 
-export const DEFAULT_PRESET_ID = "default";
-
 const P = (id, label, category, use, fields) => ({ id, label, category, use, tintable: false, ...fields });
 
 export const PRESETS = {
-  // The viewer's look before this library existed. Not documented as a choice:
-  // it is what a sub-part with no `material` renders as.
-  default: P("default", "Default", "default", "The viewer's neutral blue-grey, used when a sub-part names no material.",
-    { color: 0x9fb4cc, metalness: 0.25, roughness: 0.55 }),
+  // Every record here is a documented, nameable material. A sub-part that names
+  // none is drawn by resolve.js (the blue-grey CAD look; a PLA print in that
+  // colour in realistic mode) — there is no hidden "default" record any more.
 
   "machined-aluminum": P("machined-aluminum", "Machined aluminium", "aluminium", "Bare CNC-milled aluminium, fine tool marks, satin sheen.",
     { color: 0xf5f6f6, metalness: 1, roughness: 0.32 }),
@@ -77,13 +74,16 @@ export const PRESETS = {
   // `roughnessMean` is the roughness map's mean, so the preset `roughness` (or an
   // override) sets the AVERAGE roughness and the map only varies it. `normalScale`
   // strengthens the normal map: these scans' tangent normals barely leave +Z (a
-  // ~1% tilt), which reads as flat under an environment map.
+  // ~1% tilt), which reads as flat under an environment map. `grain` is the
+  // texture axis the scan's figure runs along — oak's runs up the image ("v"),
+  // walnut's across it ("u") — so patterns.js can lay it along each sub-part's
+  // long axis.
   oak: P("oak", "Oak", "natural", "Light oak with open grain.",
     { color: 0xa17e57, metalness: 0, roughness: 0.65, pattern: "wood", textureScale: 250,
-      textures: { color: "pattern-oak-color.jpg", normal: "pattern-oak-normal.jpg", roughness: "pattern-oak-rough.jpg", roughnessMean: 0.53, normalScale: 2.5 } }),
+      textures: { color: "pattern-oak-color.jpg", normal: "pattern-oak-normal.jpg", roughness: "pattern-oak-rough.jpg", roughnessMean: 0.53, normalScale: 2.5, grain: "v" } }),
   walnut: P("walnut", "Walnut", "natural", "Dark oiled walnut.",
     { color: 0x5d2a18, metalness: 0, roughness: 0.5, clearcoat: 0.3, clearcoatRoughness: 0.4, pattern: "wood", textureScale: 400,
-      textures: { color: "pattern-walnut-color.jpg", normal: "pattern-walnut-normal.jpg", roughness: "pattern-walnut-rough.jpg", roughnessMean: 0.628, normalScale: 3 } }),
+      textures: { color: "pattern-walnut-color.jpg", normal: "pattern-walnut-normal.jpg", roughness: "pattern-walnut-rough.jpg", roughnessMean: 0.628, normalScale: 3, grain: "u" } }),
   "carbon-fiber": P("carbon-fiber", "Carbon fibre", "natural", "2x2 twill carbon fibre under clear coat.",
     { color: 0x1b1c1e, metalness: 0.2, roughness: 0.35, clearcoat: 1, clearcoatRoughness: 0.05, pattern: "carbon", textureScale: 48 }),
 };

package/src/framework/materials/print-bed.js

@@ -154,6 +154,14 @@ export function createPrintBed({ pei, tileMm, createCanvas }) {
     ink.scale.set(size, 1, size);
   }
 
+  // Below this, the whole plate hides — like the other environments' single-
+  // sided ground discs, which cull away once the camera passes their back
+  // face. The epsilon keeps a camera sitting exactly at plate height from
+  // flickering the bed in and out as float error nudges it either side.
+  const HIDE_EPSILON_MM = 0.05;
+  const _camWorld = new THREE.Vector3();
+  const _topWorld = new THREE.Vector3();
+
   return {
     object: group,
     get sizeMm() { return size; },
@@ -161,6 +169,15 @@ export function createPrintBed({ pei, tileMm, createCanvas }) {
       setSize(bedSizeFor(footprintMm));
       group.position.set(centerX, y - 0.01, centerZ);
     },
+    // Called once per render, with the camera actually doing the rendering
+    // (the live camera, or an offscreen capture's) — never a cached "current
+    // view" — so a canonical "from below" render also sees the part rather
+    // than the plate's underside.
+    updateForCamera(camera) {
+      camera.getWorldPosition(_camWorld);
+      group.getWorldPosition(_topWorld); // local y = 0 is the plate's top surface
+      group.visible = _camWorld.y >= _topWorld.y - HIDE_EPSILON_MM;
+    },
     dispose() {
       plate.geometry.dispose(); ink.geometry.dispose();
       edge.dispose(); inkMat.dispose(); inkTex?.dispose();

package/src/framework/materials/resolve.js

@@ -1,10 +1,11 @@
 // src/framework/materials/resolve.js
 // Pure resolution of a sub-part's `display` block against the library. Never
-// throws and never rejects a value: an unknown preset falls back to the default,
+// throws and never rejects a value: an unknown preset falls back to the
+// no-material look (below),
 // an out-of-range override clamps, an unknown key is ignored — and every one of
 // those is returned as an `issue` so lint can warn about it. Appearance must
 // never be able to fail a build.
-import { PRESETS, DEFAULT_PRESET_ID } from "./presets.js";
+import { PRESETS } from "./presets.js";
 import { ENVIRONMENTS, DEFAULT_ENVIRONMENT_ID } from "./environments.js";
 
 export const OVERRIDE_RANGES = {
@@ -20,16 +21,34 @@ export const DISPLAY_KEYS = ["color", "opacity", "material", ...Object.keys(OVER
 
 const isColor = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
 
+// A sub-part with no usable material — none named, or one the library does not
+// know. The CAD view draws it in the viewer's neutral blue-grey drafting look
+// (the look every part had before the library existed; viewer.js's base
+// material and threemf.js's uncoloured-object colour are the same literal).
+// Realistic mode draws it as a PLA print — the pla-print finish, layer lines
+// and all — in that same colour, or the part's own `color`, so a part is the
+// same colour in both views, just printed. `declaresMaterials` still counts
+// only a NAMED material: this default never makes a part "declare" one.
+export const NO_MATERIAL_COLOR = 0x9fb4cc;
+export const NO_MATERIAL_PRESET_ID = "pla-print";
+const NO_MATERIAL_CAD = { color: NO_MATERIAL_COLOR, metalness: 0.25, roughness: 0.55 };
+
+const knownMaterial = (m) => typeof m === "string" && Object.hasOwn(PRESETS, m);
+
 export function resolveMaterial(display) {
   const d = display && typeof display === "object" ? display : {};
   const issues = [];
-  let preset = PRESETS[DEFAULT_PRESET_ID];
-  if (d.material != null) {
-    if (typeof d.material === "string" && Object.hasOwn(PRESETS, d.material)) preset = PRESETS[d.material];
-    else issues.push({ kind: "unknown-material", key: "material", value: d.material });
-  }
+  if (d.material != null && !knownMaterial(d.material)) issues.push({ kind: "unknown-material", key: "material", value: d.material });
+  const preset = knownMaterial(d.material) ? PRESETS[d.material] : PRESETS[NO_MATERIAL_PRESET_ID];
+  const baseColor = knownMaterial(d.material) ? preset.color : NO_MATERIAL_COLOR;
+  return { preset, ...applyDisplay(d, preset, baseColor, issues) };
+}
+
+// A preset record's numbers with the display block's colour, opacity and clamped
+// overrides applied. Pushes onto `issues`; returns them with the params.
+function applyDisplay(d, preset, baseColor, issues) {
   const params = {
-    color: preset.color,
+    color: baseColor,
     metalness: preset.metalness,
     roughness: preset.roughness,
     clearcoat: preset.clearcoat ?? 0,
@@ -63,7 +82,7 @@ export function resolveMaterial(display) {
   }
   // `tinted`: the author named a colour. A textured preset's colour map carries
   // its own colour, so only an explicit tint multiplies it (physical.js).
-  return { preset, params, issues, tinted: isColor(d.color) };
+  return { params, issues, tinted: isColor(d.color) };
 }
 
 // CAD-view appearance: the resolved colour on the CAD MeshStandardMaterial,
@@ -73,11 +92,15 @@ export function resolveMaterial(display) {
 const MIN_CAD_LUMA = 60; // 0..255, Rec. 709
 export function cadAppearance(display) {
   const d = display && typeof display === "object" ? display : {};
-  const { params } = resolveMaterial(d);
   if (d.material == null) {
-    // Byte-for-byte today's behaviour for a part without `material`.
-    return { color: params.color, metalness: 0.25, roughness: 0.55, opacity: params.opacity };
+    // The drafting look, untouched by overrides — as it always was.
+    const { params } = resolveMaterial(d);
+    return { color: params.color, metalness: NO_MATERIAL_CAD.metalness, roughness: NO_MATERIAL_CAD.roughness, opacity: params.opacity };
   }
+  // An unknown material flattens the drafting look rather than the realistic
+  // PLA default, exactly as it did when it fell back to the retired "default"
+  // preset.
+  const { params } = knownMaterial(d.material) ? resolveMaterial(d) : applyDisplay(d, NO_MATERIAL_CAD, NO_MATERIAL_COLOR, []);
   return {
     color: liftLuma(params.color, MIN_CAD_LUMA),
     metalness: Math.min(params.metalness, 0.5),
@@ -97,8 +120,9 @@ function liftLuma(color, min) {
 }
 
 // The colour a 3MF object carries: the explicit tint, else the preset's own
-// colour. Null when the sub-part says nothing about appearance, which is what
-// keeps an appearance-free export byte-for-byte unchanged.
+// colour (the blue-grey for an unknown material, never the realistic PLA
+// default's). Null when the sub-part says nothing about appearance, which is
+// what keeps an appearance-free export byte-for-byte unchanged.
 export function printColor(display) {
   if (!display || typeof display !== "object") return null;
   if (isColor(display.color)) return display.color;