diff --git a/docs/scene-language.md b/docs/scene-language.md index de76a772..f69fcba1 100644 --- a/docs/scene-language.md +++ b/docs/scene-language.md @@ -88,7 +88,7 @@ When the thing to explain is a process, a sequence of events, a how-to or a tren ### Surfaces -`material` is one of `plastic` (default), `metal`, `rubber`, `pcb`, `glass`, `glow`, `paper`, `tissue` (living tissue: soft, a little wet). They are physically based surfaces lit by a room environment; `color` tints them, and an object with no colour takes the natural colour of its surface (a `pcb` is green, `rubber` near black). Where a solid has creases or open boundaries, dark edge lines emphasize them unless `edges` is false. Smooth spheres/ellipsoids, rounded cylinders and full tori have no crease lines, even when `edges` is true: their tessellation is not an authored feature. This does not add silhouette outlines or change cut faces. See `samples/scenes/continuous-surfaces.json` for default/edges-off pairs at compact and stretched proportions. +`material` is one of `plastic` (default), `metal`, `rubber`, `pcb`, `glass`, `glow`, `paper`, `tissue` (living tissue: soft, a little wet), and the named library `bone`, `muscle`, `tendon`, `skin`, `steel`, `iron`, `brass`, `copper`, `wood`, `rope`, `water` (one table, `src/scene/material-library.ts`). They are physically based surfaces lit by a room environment; `color` tints them, and an object with no colour takes the natural colour of its surface (a `pcb` is green, `rubber` a dark grey). A library material keeps a tint within its own range of lightness: a hue is given, but bone tinted white is the palest bone and muscle tinted black the darkest muscle, so each reads on a light page and a dark one (the range was set from rendered frames on both). `plastic` and `rubber` take a colour as written, but with none they are a mid-tone, not near-white or near-black. `muscle`, `tendon` and `rope` tubes and connectors wear the fibre layer below without asking. Where a solid has creases or open boundaries, dark edge lines emphasize them unless `edges` is false. Smooth spheres/ellipsoids, rounded cylinders and full tori have no crease lines, even when `edges` is true: their tessellation is not an authored feature. This does not add silhouette outlines or change cut faces. See `samples/scenes/continuous-surfaces.json` for default/edges-off pairs at compact and stretched proportions. Each object that accepts `material` also accepts four optional finish numbers, independently overriding that material's recipe: @@ -103,6 +103,10 @@ Omitted or null fields keep the named defaults, including when no `material` is See [surface finish review](surface-finish.md) and `samples/scenes/surface-finishes.json` for an authored comparison and native acceptance checklist. +`tube` and `connector` also accept `treatment: "fibres"`: a fixed, subtle longitudinal colour/roughness effect layered over the named material. For example, `material: "tissue", treatment: "fibres"` adds directional surface detail without modelling any strands; the same treatment works on a rubber cord. Omit/null keeps the plain material. This is one optional add field, not a style animation or a configurable shader. Other shapes do not support it yet. + +The renderer supplies coordinates on the existing swept rings, so the detail follows bends and rebuilt endpoint motion instead of projecting through the world. Rounded tips and directions where the initial sweep frame becomes ambiguous fade to a plain material; periodic tubes keep the circumferential seam aligned. Unresolved frequencies fade away using screen-space derivatives at every quality tier. No vertices, triangles, draw calls, textures or network requests are added. Only treated geometries allocate three coordinate floats per vertex. Alpha/depth, clipping, silhouette, highlights and section hatching retain their existing behavior. This is illustrative material appearance, not an anatomical fibre model, displacement, anisotropic scattering or tissue mechanics. See `samples/scenes/path-surface-treatments.json` for paired plain/treated paths and view changes; an authored demonstration alone does not establish native visual acceptance or live-model latency. + For `loft` and `sweep`, optional `smooth: true` blends lighting across shallow section corners and removes their longitudinal edge lines. Flat caps, end perimeters and sharp corners stay distinct. Omitted, null or false keeps the original faceted appearance. This changes shading, not the polygon silhouette, roundover or wall thickness. See [smooth profile surfaces](smooth-profiles.md). ### Adding objects @@ -120,9 +124,9 @@ For `loft` and `sweep`, optional `smooth: true` blends lighting across shallow s | `loft` | `outline` `endOutline` `depth` `smooth`? `pos`? `rot`? `color`? `material`? | two convex XY outlines at z = -depth/2 and +depth/2, joined by matching indices; 3–24 corners per ring, equal counts and winding, every intermediate section strictly convex. No closing repeat, collinear corners, holes or bevel. See [profile lofts](profile-lofts.md) | | `shell` | `size` `inner`? `latitude`? `sweep`? `pos`? `rot`? `color`? `material`? `edges`? `opacity`? | closed hollow ellipsoid section: full outer diameters `size`, concentric cavity ratio `inner` .01–.99 (default .85), latitude `[south,north]` −90–90 spanning at least 1 degree (default full), angular `sweep` 1–360 from +x toward +z (default full). Radial rims close the material, not the cavity; `inner` is not constant wall thickness. Origin stays at the full ellipsoid centre; rotate to aim the opening. Invalid/unsafe geometry rejects. See [hollow ellipsoid sections](ellipsoid-shells.md) | | `blob` | `pts` `sizes` `soft`? `pos`? `rot`? `color`? `material`? `opacity`? | a soft organic form blended from 1 to 12 ellipsoid lumps: `pts` are the lump centres and `sizes` their boxes `[x,y,z]` (one for each point; a short list repeats its last). Lumps that overlap melt into one smooth skin with necks between them, so a heart chamber, an animal's body or head, a leaf, a fruit is one blob. `soft` (0.05 to 1, default 0.5) is how far they blend: low is nearly a hard union, 1 joins lumps a little apart. A lone lump is exactly its ellipsoid. For several forms (the chambers of an organ) write one blob each. No edge lines; cut tiers use a coarser skin | -| `tube` | `pts` `radius` `flat`? `swell`? `closed`? `draw`? `color`? `material`? | a smooth tube through 2 to 24 points: cables, pipes, vessels. `flat` (0.05 to 1) squashes it to a ribbon whose wide side faces across the path. `draw` below 1 starts it part drawn. `swell` `[[along 0 to 1, factor],...]` (2 to 8 points, smooth between them) changes the radius along the tube: a vessel that tapers, a stem that thickens toward the ground, a tail. `closed: true` joins the path into a smooth loop with no caps (at least three distinct points; repeating the first point at the end is optional). The loop carries its cross-section around the curve and distributes any remaining twist around it. `swell` returns to its start factor at the join, overriding the factor at 1. A closed loop has no endpoints to auto-attach, and its stream markers keep their size across the join when fully revealed. Tight bends and overlapping paths can still intersect. A tube thick for its length (radius at least 4 per cent of its length: a stem, a vessel, a limb, a pipe) counts as part of the model when the camera frames it; a thin cable does not | +| `tube` | `pts` `radius` `flat`? `swell`? `closed`? `draw`? `color`? `material`? `treatment`? | a smooth tube through 2 to 24 points: cables, pipes, vessels. `flat` (0.05 to 1) squashes it to a ribbon whose wide side faces across the path. `draw` below 1 starts it part drawn. `swell` `[[along 0 to 1, factor],...]` (2 to 8 points, smooth between them) changes the radius along the tube: a vessel that tapers, a stem that thickens toward the ground, a tail. `closed: true` joins the path into a smooth loop with no caps (at least three distinct points; repeating the first point at the end is optional). The loop carries its cross-section around the curve and distributes any remaining twist around it. `swell` returns to its start factor at the join, overriding the factor at 1. A closed loop has no endpoints to auto-attach, and its stream markers keep their size across the join when fully revealed. Tight bends and overlapping paths can still intersect. A tube thick for its length (radius at least 4 per cent of its length: a stem, a vessel, a limb, a pipe) counts as part of the model when the camera frames it; a thin cable does not | | `line` `arrow` | `pts` `color`? `draw`? `opacity`? | a thin line through the points; an arrow ends in a head at the last point | -| `connector` | `from` `to` `kind`? `fromSide`? `toSide`? `fromAnchor`? `toAnchor`? `fromPoint`? `toPoint`? `swell`? `restLength`? `sag`? `radius`? `color`? `material`? `draw`? `opacity`? | a physical rope, belt, wire, chain or pipe between two parts of one 3D model, with its ends on them, drawn as a tube that follows them as they move; it never links panels, cards, marks or diagram nodes (flat diagram arrows are `edge`), and is not drawn until both ends are there (worked out afresh on every frame from where the two are, so it needs no pose of its own). `kind` `straight` (default) is taut, the line between its ends: a rope from a wheel's rim to a weight shortens as the weight rises. `slack` hangs in a sag (`sag`, 0 to 1, a fraction of its length, default 0.2) below the line between the ends: a wire, a tube. `wrapped` is a flat belt round two wheels (a cylinder, a sphere or a wheel, gear or bearing part) whose axes run the same way; it stands off the rims and is `radius` thick. `fromSide` and `toSide` (`left` `right` `top` `bottom` `front` `back`, as seen from the front) pick where an end meets its object: on a round object that is the rim in that direction, on any other the middle of that face of its box; left out, its middle. `fromAnchor` and `toAnchor` name a point of a ready-made part instead. For straight/slack connectors, `fromPoint`/`toPoint` are explicit local `[x,y,z]` points carried by each endpoint object's rotation and scale, taking precedence over its anchor and side. `swell` gives the same smooth radius profile as a tube. `restLength` (0.01–400) is the path length in the connector's own space at its authored radius: radius scales by `sqrt(restLength/currentLength)`, bounded to 0.25–4. This is an approximate volume-preserving visual, not a force or tissue simulation. These four fields are refused on wrapped belts. A connector to itself is refused. `radius` is its thickness (default 0.05). It is a path: a `stream` can run along it | +| `connector` | `from` `to` `kind`? `fromSide`? `toSide`? `fromAnchor`? `toAnchor`? `fromPoint`? `toPoint`? `swell`? `restLength`? `sag`? `radius`? `color`? `material`? `treatment`? `draw`? `opacity`? | a physical rope, belt, wire, chain or pipe between two parts of one 3D model, with its ends on them, drawn as a tube that follows them as they move; it never links panels, cards, marks or diagram nodes (flat diagram arrows are `edge`), and is not drawn until both ends are there (worked out afresh on every frame from where the two are, so it needs no pose of its own). `kind` `straight` (default) is taut, the line between its ends: a rope from a wheel's rim to a weight shortens as the weight rises. `slack` hangs in a sag (`sag`, 0 to 1, a fraction of its length, default 0.2) below the line between the ends: a wire, a tube. `wrapped` is a flat belt round two wheels (a cylinder, a sphere or a wheel, gear or bearing part) whose axes run the same way; it stands off the rims and is `radius` thick. `fromSide` and `toSide` (`left` `right` `top` `bottom` `front` `back`, as seen from the front) pick where an end meets its object: on a round object that is the rim in that direction, on any other the middle of that face of its box; left out, its middle. `fromAnchor` and `toAnchor` name a point of a ready-made part instead. For straight/slack connectors, `fromPoint`/`toPoint` are explicit local `[x,y,z]` points carried by each endpoint object's rotation and scale, taking precedence over its anchor and side. `swell` gives the same smooth radius profile as a tube. `restLength` (0.01–400) is the path length in the connector's own space at its authored radius: radius scales by `sqrt(restLength/currentLength)`, bounded to 0.25–4. This is an approximate volume-preserving visual, not a force or tissue simulation. These four fields are refused on wrapped belts. A connector to itself is refused. `radius` is its thickness (default 0.05). It is a path: a `stream` can run along it | | `stream` | `along` `mark`? `count`? `size`? `color`? `toColor`? `shiftAt`? `period`? `by`? `ratio`? `opacity`? | markers (`mark` `dot` default, `dash` or `arrow`; `count` 1 to 40, default 6) that run along a `tube`, `line`, `arrow` or `connector`, or along an arrow (`edge`) of a flow diagram: blood through vessels, current in a wire, water in a pipe, cars on a road, data between computers, money in an economy. They go on running by themselves, from step to step. `period` is the seconds a marker takes for the whole way (default 4; negative runs it backwards); or give `by`, a spinning part, with `ratio` laps for each turn of it. `color` changes to `toColor` along the way (`shiftAt`, 0 to 1, is where, default the middle; blood blue to red through the lungs). `size` (3D only) is never less than a bead a little wider than the pipe, since a marker inside an opaque pipe could not be seen. It hangs from its path and goes with it; markers shrink away at the ends. A stream is not part of the model for the camera | | `part` | `part` `size` `variant`? `n`? `pos`? `rot`? `color`? `parentAnchor`? `selfAnchor`? | a ready-made part fitted to the box `size`: `chip` (variant `black` or `metal`), `header` (`n` pins per row, two rows), `port` (variant `usb`, `usb3`, `ethernet`, `hdmi`, `usbc`; its opening faces `+z`), `lens` (axis `z`), `screen`, `button`, `fan` (`n` blades, axis `y`), `wheel` (`n` spokes, axis `z`). Anchor placement is described below | | `array` | `of` `count` `step`? `turn`? | `count` copies in all of the object `of` (with everything attached to it); the original is the first. Each copy is moved `step` and turned `turn` more than the last, about the origin of the group the original sits in: a row of pins, blades round a hub. The original joins the new group `id` | diff --git a/docs/scene.schema.json b/docs/scene.schema.json index a4004354..74f446b7 100644 --- a/docs/scene.schema.json +++ b/docs/scene.schema.json @@ -1148,9 +1148,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -1349,9 +1360,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -1561,9 +1583,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -1745,9 +1778,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -1931,9 +1975,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2105,9 +2160,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2304,9 +2370,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2500,9 +2577,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2692,9 +2780,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2855,9 +2954,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -2887,6 +2997,13 @@ ], "description": "coating: 0 polished, 1 matte; only visible with clearcoat; omitted keeps the material recipe; 0 to 1" }, + "treatment": { + "enum": [ + "fibres", + null + ], + "description": "optional longitudinal material detail on a tube/connector; follows the path without extra strands or physics" + }, "draw": { "type": [ "number", @@ -2926,6 +3043,7 @@ "metalness", "clearcoat", "clearcoatRoughness", + "treatment", "draw", "opacity", "at" @@ -3167,9 +3285,20 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ], - "description": "surface, default plastic" + "description": "named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic" }, "roughness": { "type": [ @@ -3199,6 +3328,13 @@ ], "description": "coating: 0 polished, 1 matte; only visible with clearcoat; omitted keeps the material recipe; 0 to 1" }, + "treatment": { + "enum": [ + "fibres", + null + ], + "description": "optional longitudinal material detail on a tube/connector; follows the path without extra strands or physics" + }, "draw": { "type": [ "number", @@ -3245,6 +3381,7 @@ "metalness", "clearcoat", "clearcoatRoughness", + "treatment", "draw", "opacity", "at" diff --git a/docs/scene.schema.lean.json b/docs/scene.schema.lean.json index 40a3d709..bea36c66 100644 --- a/docs/scene.schema.lean.json +++ b/docs/scene.schema.lean.json @@ -66,6 +66,17 @@ "glow", "paper", "tissue", + "bone", + "muscle", + "tendon", + "skin", + "steel", + "iron", + "brass", + "copper", + "wood", + "rope", + "water", null ] }, @@ -226,6 +237,12 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, + "treatment": { + "enum": [ + "fibres", + null + ] + }, "draw": { "$ref": "#/$defs/0" }, @@ -260,6 +277,7 @@ "metalness", "clearcoat", "clearcoatRoughness", + "treatment", "draw", "opacity", "at" @@ -2287,6 +2305,12 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, + "treatment": { + "enum": [ + "fibres", + null + ] + }, "draw": { "$ref": "#/$defs/0" }, @@ -2313,6 +2337,7 @@ "metalness", "clearcoat", "clearcoatRoughness", + "treatment", "draw", "opacity", "at" diff --git a/docs/superpowers/plans/2026-11-08-path-surface-treatments.md b/docs/superpowers/plans/2026-11-08-path-surface-treatments.md new file mode 100644 index 00000000..4174aab6 --- /dev/null +++ b/docs/superpowers/plans/2026-11-08-path-surface-treatments.md @@ -0,0 +1,31 @@ +# Path Surface Treatments Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this cohesive task. Steps use checkbox syntax for tracking. + +**Goal:** Add one optional fibre treatment to path surfaces with bounded renderer work. +**Architecture:** Add a tube/connector-only enum to the scene spec; attach renderer-owned coordinates to existing ring geometry and a fixed antialiased shader to its physical surface. Rebuilt paths carry the same treatment without material churn. +**Tech Stack:** TypeScript, Three.js, Node test runner; no new dependencies. +**Spec:** docs/superpowers/specs/2026-11-08-path-surface-treatments-design.md + +## Global Constraints +- No extra geometry, model shader/remote asset inputs, physics claims, or merge. +- Keep main c89033f2 as the base; test elastic compatibility separately. +- Preserve transparency, cuts, materials, low tier behavior and schema budget. + +## Review Focus +- Small surfaces and grazing views must fade unresolved stripes rather than flicker. +- Caps and closed seams must not show discontinuities or stripe pinching. +- Rebuilt/attached connectors and reverse seeks must keep coordinates and material ownership. +- Glass and section surfaces must preserve alpha, depth and clipping semantics. +- Absent/null and unsupported inputs must not silently mutate an ID or existing output. + +## Task 1: Add and verify path treatment +**Files:** src/scene/{types,spec,guide}.ts; src/overlay/{surface-treatment,scene3d,scene3d-flow}.ts; test/overlay-surface-treatment.test.ts; schemas, scene-language and paired sample. +**Interfaces:** `PathTreatment = 'fibres'`; `setPathSurfaceCoordinates(geometry, treatment)` adds an attribute only when requested; `applyPathTreatment(material, treatment)` installs a fixed shader without changing material state. +- [ ] Write schema/validation, real PanelScene, coordinate/rebuild, cap/seam, shader, filtering, glass/clipping and array regressions first. +- [ ] Run `node --test test/overlay-surface-treatment.test.ts` and verify feature-missing failures. +- [ ] Implement minimal bounded behavior, sample and docs; rebuild schemas. +- [ ] Run focused regression, full `npm test`, `npm run typecheck`, `npm run build`, `git diff --check`; report baseline failures without hiding them. +- [ ] Measure prompt/schema overhead and CPU sync cost; separately test integration with elastic connector work and send exact fixture/source for native QA. +- [ ] Commit; request independent whole-branch review; resolve important findings with failing regressions. +- [ ] Prepare reviewed draft publication with exact source hashes and explicit native/live-model limits; no merge. diff --git a/docs/superpowers/specs/2026-11-08-path-surface-treatments-design.md b/docs/superpowers/specs/2026-11-08-path-surface-treatments-design.md new file mode 100644 index 00000000..4cb6d736 --- /dev/null +++ b/docs/superpowers/specs/2026-11-08-path-surface-treatments-design.md @@ -0,0 +1,19 @@ +# Path surface treatments + +## Intent and scope +Add optional longitudinal fibre detail to existing tubes and connectors, without asking the scene-authoring model to describe each strand. A treatment supplements the named material and finish; it is not a new solid, tissue simulation, or arbitrary shader interface. + +## Chosen approach +Under the user's instruction to choose the best approach and continue improvements, use one optional enum field, `treatment: "fibres"`, on tube and connector adds. Omit/null preserves today's rendering. Other shapes and animated style actions do not accept it. The initial implementation fixes density/strength rather than adding more model controls. + +Alternatives considered: explicit strand geometry adds topology and draw overhead; remote textures add assets/latency and UV authoring; world-space stripes slide across bending shapes. Renderer-owned path coordinates on existing vertices avoid these costs. This is an implementation choice, not a user-specified API spelling. + +## Rendering +Generate a small surface coordinate attribute only for treated geometry from its existing ring topology: circumferential fraction, normalized path station, and cap fade. Each ring carries the same circumferential coordinate through bends and radius changes. Rounded tips fade the detail to avoid a pinched stripe singularity. Near an ambiguous initial sweep direction, fade the treatment smoothly rather than exposing rapid frame rotation; leave positions and normals unchanged. Closed tubes retain matching periodic seams. Rebuild paths regenerate the attribute; surface materials remain reusable. + +A bounded deterministic shader applies subtle longitudinal color and roughness variation. Derivative filtering removes unresolved frequencies at small projected sizes, on all tiers. Keep existing geometry, normals, silhouette, alpha/depth state, clipping, named material recipes, highlights and separate section hatching unchanged. No extra meshes, textures, network calls, shader inputs from the model, or new dependencies. + +## Constraints and evidence +Base this draft on merged main c89033f2, not the unmerged elastic connector branch. Test compatibility separately with that branch's rest-length/profile behavior and do not duplicate its commits. Preserve schema command-line budgets and the three-second response goal; report measured local overhead separately from unmeasured live-model/native performance. + +Automated checks cover validation/schema, topology/coordinate seams and cap fade, rebuilds/reverse seeks, glass and clipping, arrays, no-treatment compatibility, and resource ownership. Native QA must compile and inspect low/mid/high tier fixtures, small-size filtering, bends and contraction. A demonstration is not physical or visual validation; mark anything not actually checked as pending. No merge; publish only a reviewed draft through the authorized identity. diff --git a/samples/scenes/path-surface-treatments.json b/samples/scenes/path-surface-treatments.json new file mode 100644 index 00000000..abc9e95a --- /dev/null +++ b/samples/scenes/path-surface-treatments.json @@ -0,0 +1,411 @@ +{ + "v": 1, + "steps": [ + { + "say": "These pairs share the same shapes. The right adds a subtle longitudinal material effect, with no individual strands: tissue above, rubber cord in the middle, and glass below. This is an authored appearance demonstration, not tissue mechanics.", + "actions": [ + { + "op": "panel", + "x": 100, + "y": 90, + "w": 800, + "h": 780 + }, + { + "op": "orbit", + "az": 10, + "el": 10, + "dur": 0 + }, + { + "op": "add", + "shape": "group", + "id": "plain", + "pos": [ + -2.4, + 0, + 0 + ] + }, + { + "op": "add", + "shape": "tube", + "id": "plainTissue", + "parent": "plain", + "pts": [ + [ + -1.6, + 1.5, + 0 + ], + [ + -0.6, + 2.1, + 0.1 + ], + [ + 0.6, + 2.1, + 0.1 + ], + [ + 1.6, + 1.5, + 0 + ] + ], + "radius": 0.26, + "swell": [ + [ + 0, + 0.45 + ], + [ + 0.25, + 1 + ], + [ + 0.75, + 1 + ], + [ + 1, + 0.45 + ] + ], + "color": "#bf6166", + "material": "tissue" + }, + { + "op": "add", + "shape": "sphere", + "id": "plainA", + "parent": "plain", + "pos": [ + -1.6, + -0.2, + 0 + ], + "size": [ + 0.25, + 0.25, + 0.25 + ], + "color": "#68778b" + }, + { + "op": "add", + "shape": "sphere", + "id": "plainB", + "parent": "plain", + "pos": [ + 1.6, + -0.2, + 0 + ], + "size": [ + 0.25, + 0.25, + 0.25 + ], + "color": "#68778b" + }, + { + "op": "add", + "shape": "connector", + "id": "plainCord", + "parent": "plain", + "from": "plainA", + "to": "plainB", + "kind": "slack", + "sag": 0.25, + "radius": 0.16, + "color": "#d6b37b", + "material": "rubber" + }, + { + "op": "add", + "shape": "tube", + "id": "plainGlass", + "parent": "plain", + "pts": [ + [ + -1.6, + -2.2, + 0 + ], + [ + -0.6, + -1.8, + 0.1 + ], + [ + 0.6, + -1.8, + 0.1 + ], + [ + 1.6, + -2.2, + 0 + ] + ], + "radius": 0.28, + "color": "#54a69e", + "material": "glass" + }, + { + "op": "add", + "shape": "text", + "id": "plainLabel", + "parent": "plain", + "pos": [ + 0, + -3, + 0 + ], + "text": "Plain material", + "height": 0.24, + "color": "#334155" + }, + { + "op": "add", + "shape": "group", + "id": "treated", + "pos": [ + 2.4, + 0, + 0 + ] + }, + { + "op": "add", + "shape": "tube", + "id": "treatedTissue", + "parent": "treated", + "pts": [ + [ + -1.6, + 1.5, + 0 + ], + [ + -0.6, + 2.1, + 0.1 + ], + [ + 0.6, + 2.1, + 0.1 + ], + [ + 1.6, + 1.5, + 0 + ] + ], + "radius": 0.26, + "swell": [ + [ + 0, + 0.45 + ], + [ + 0.25, + 1 + ], + [ + 0.75, + 1 + ], + [ + 1, + 0.45 + ] + ], + "color": "#bf6166", + "material": "tissue", + "treatment": "fibres" + }, + { + "op": "add", + "shape": "sphere", + "id": "treatedA", + "parent": "treated", + "pos": [ + -1.6, + -0.2, + 0 + ], + "size": [ + 0.25, + 0.25, + 0.25 + ], + "color": "#68778b" + }, + { + "op": "add", + "shape": "sphere", + "id": "treatedB", + "parent": "treated", + "pos": [ + 1.6, + -0.2, + 0 + ], + "size": [ + 0.25, + 0.25, + 0.25 + ], + "color": "#68778b" + }, + { + "op": "add", + "shape": "connector", + "id": "treatedCord", + "parent": "treated", + "from": "treatedA", + "to": "treatedB", + "kind": "slack", + "sag": 0.25, + "radius": 0.16, + "color": "#d6b37b", + "material": "rubber", + "treatment": "fibres" + }, + { + "op": "add", + "shape": "tube", + "id": "treatedGlass", + "parent": "treated", + "pts": [ + [ + -1.6, + -2.2, + 0 + ], + [ + -0.6, + -1.8, + 0.1 + ], + [ + 0.6, + -1.8, + 0.1 + ], + [ + 1.6, + -2.2, + 0 + ] + ], + "radius": 0.28, + "color": "#54a69e", + "material": "glass", + "treatment": "fibres" + }, + { + "op": "add", + "shape": "text", + "id": "treatedLabel", + "parent": "treated", + "pos": [ + 0, + -3, + 0 + ], + "text": "Material + effect", + "height": 0.24, + "color": "#334155" + } + ] + }, + { + "say": "The cord bends with its endpoints. The pattern follows the existing surface. Glass still uses its ordinary transparent material.", + "actions": [ + { + "op": "move", + "id": "plainB", + "to": [ + 0.4, + 0.1, + 0.3 + ], + "dur": 1 + }, + { + "op": "move", + "id": "treatedB", + "to": [ + 0.4, + 0.1, + 0.3 + ], + "dur": 1 + }, + { + "op": "orbit", + "az": -25, + "el": 22, + "dur": 1 + } + ] + }, + { + "say": "At a smaller size and grazing view, fine detail fades instead of becoming a dense stripe pattern.", + "actions": [ + { + "op": "zoom", + "dur": 0.5, + "to": 0.55 + }, + { + "op": "orbit", + "az": 65, + "el": 12, + "dur": 0.5 + } + ] + }, + { + "say": "Returning restores the same surface. The treatment changes only the material appearance.", + "actions": [ + { + "op": "zoom", + "dur": 0.5, + "to": 1 + }, + { + "op": "orbit", + "az": 10, + "el": 10, + "dur": 0.5 + }, + { + "op": "move", + "id": "plainB", + "to": [ + 1.6, + -0.2, + 0 + ], + "dur": 0.5 + }, + { + "op": "move", + "id": "treatedB", + "to": [ + 1.6, + -0.2, + 0 + ], + "dur": 0.5 + } + ] + } + ] +} diff --git a/src/overlay/geometry.ts b/src/overlay/geometry.ts index b3817503..82eec6d3 100644 --- a/src/overlay/geometry.ts +++ b/src/overlay/geometry.ts @@ -243,6 +243,7 @@ export function tubeGeometry(path: readonly Vec3[], baseRadius: number, flat: nu const a = new Vector3(); const b = new Vector3(); const centre = new Vector3(); + let surfaceFrameStability = 1; const frames: Array<{ centre: Vector3; wide: Vector3; thin: Vector3; tangent: Vector3; radius: number }> = []; for (let i = 0; i < rings; i++) { const p = path[i] as Vec3; @@ -259,6 +260,14 @@ export function tubeGeometry(path: readonly Vec3[], baseRadius: number, flat: nu const k = Math.max(0, Math.min(1, (lean - 0.3) / 0.68)); const mix = k * k * (3 - 2 * k); const ref = new Vector3().addScaledVector(UP, 1 - mix).addScaledVector(FORWARD, mix).normalize(); + if (i === 0 && !across) { + // Near a tangent parallel to the initial reference, the existing frame + // can rotate very quickly or flip. Geometry stays exactly as before; + // optional directional material detail fades until longitude is stable. + const conditioning = new Vector3().crossVectors(tangent, ref).length(); + const resolved = Math.max(0, Math.min(1, (conditioning - 0.05) / 0.1)); + surfaceFrameStability = resolved * resolved * (3 - 2 * resolved); + } if (flat === 1 && i > 0) { wide.addScaledVector(tangent, -wide.dot(tangent)); if (wide.lengthSq() < 1e-12) wide.crossVectors(tangent, ref); @@ -379,6 +388,7 @@ export function tubeGeometry(path: readonly Vec3[], baseRadius: number, flat: nu geo.setAttribute('position', new BufferAttribute(new Float32Array(pos), 3)); geo.setAttribute('normal', new BufferAttribute(new Float32Array(nor), 3)); geo.setIndex(idx); + geo.userData.surfaceFrameStability = surfaceFrameStability; geo.userData.rings = rings; geo.userData.indicesPerRing = radial * 6; geo.userData.startCap = startCap; diff --git a/src/overlay/materials.ts b/src/overlay/materials.ts index 80465559..e610602b 100644 --- a/src/overlay/materials.ts +++ b/src/overlay/materials.ts @@ -5,6 +5,8 @@ import { Color, DoubleSide, MeshPhysicalMaterial } from 'three'; import type { Material } from 'three'; import type { SurfaceFinish } from '../scene/types.ts'; +import { fitTint } from '../scene/material-library.ts'; +import type { MaterialName } from '../scene/material-library.ts'; import type { Rgb } from './timeline.ts'; export type Tier = 'low' | 'mid' | 'high'; @@ -30,7 +32,7 @@ export const TIERS: Record = { }; /** The surfaces a scene can name, and two the parts kit uses inside itself: painted metal and rough cast metal. */ -export type SurfaceName = 'plastic' | 'metal' | 'rubber' | 'pcb' | 'glass' | 'glow' | 'bead' | 'paper' | 'tissue' | 'enamel' | 'cast' | 'section'; +export type SurfaceName = MaterialName | 'bead' | 'enamel' | 'cast' | 'section'; type Recipe = { roughness: number; metalness: number; clearcoat?: number; clearcoatRoughness?: number; @@ -52,6 +54,19 @@ const RECIPES: Record = { paper: { roughness: 0.96, metalness: 0, doubleSided: true }, // Living tissue: soft and a little wet, a gentle sheen over a matte body. tissue: { roughness: 0.62, metalness: 0, clearcoat: 0.45, clearcoatRoughness: 0.55, sheen: 0.8 }, + // Living and organic: matte to softly wet, in the colours their names ask for, none of them shiny plastic. + bone: { roughness: 0.58, metalness: 0, clearcoat: 0.12, clearcoatRoughness: 0.55 }, + muscle: { roughness: 0.55, metalness: 0, clearcoat: 0.35, clearcoatRoughness: 0.45, sheen: 0.5 }, + tendon: { roughness: 0.38, metalness: 0, clearcoat: 0.5, clearcoatRoughness: 0.3, sheen: 0.4 }, + skin: { roughness: 0.6, metalness: 0, clearcoat: 0.18, clearcoatRoughness: 0.6, sheen: 0.7 }, + // Metals and their kin: the plain metal's recipe, tuned. + steel: { roughness: 0.28, metalness: 1, envMapIntensity: 1.1 }, + iron: { roughness: 0.55, metalness: 0.9, envMapIntensity: 0.95 }, + brass: { roughness: 0.26, metalness: 1, envMapIntensity: 1.1 }, + copper: { roughness: 0.3, metalness: 1, envMapIntensity: 1.1 }, + wood: { roughness: 0.8, metalness: 0, clearcoat: 0.12, clearcoatRoughness: 0.7 }, + rope: { roughness: 0.95, metalness: 0, sheen: 0.4 }, + water: { roughness: 0.05, metalness: 0, clearcoat: 1, clearcoatRoughness: 0.05, opacity: 0.58, envMapIntensity: 1.3, doubleSided: true }, // Painted metal: a little of the metal under the paint shows in the shine, and the lacquer over it is glassy. enamel: { roughness: 0.34, metalness: 0.55, clearcoat: 1, clearcoatRoughness: 0.12, envMapIntensity: 1.1 }, // Sand-cast metal: rough and even, with no mirror in it. @@ -60,7 +75,7 @@ const RECIPES: Record = { section: { roughness: 0.7, metalness: 0.1 }, }; -export type Surface = MeshPhysicalMaterial & { userData: { base: number; glow: number } }; +export type Surface = MeshPhysicalMaterial & { userData: { base: number; glow: number; name?: string } }; export function makeSurface(name: string | undefined, tier: TierSettings, finish: SurfaceFinish = {}): Surface { const r = RECIPES[(name as SurfaceName) in RECIPES ? (name as SurfaceName) : 'plastic']; @@ -75,7 +90,7 @@ export function makeSurface(name: string | undefined, tier: TierSettings, finish m.sheenRoughness = 0.5; m.sheenColor.setRGB(1, 0.9, 0.88); } - m.userData = { base: r.opacity ?? 1, glow: r.emissive ?? 0 }; + m.userData = { base: r.opacity ?? 1, glow: r.emissive ?? 0, name }; m.opacity = m.userData.base; m.depthWrite = !m.transparent; if (name === 'section') hatched(m); @@ -102,7 +117,9 @@ export function setSurfaceOpacity(m: Surface, opacity: number): void { /** Sets a surface's tint, strength and glow for the moment. `alpha` is the object's own opacity. * Endpoint-held paths defer classification until their flow update supplies the final opacity. */ export function applySurface(m: Surface, rgb: Rgb, alpha: number, pulse: number, pulseRgb: Rgb | undefined, deferOpacity = false): void { - m.color.setRGB(rgb[0] / 255, rgb[1] / 255, rgb[2] / 255, 'srgb'); + // A tint gives the material a hue but stays within the material's own range of lightness (bone does not go white), so it reads on a light page and a dark one. + const tint = fitTint(m.userData.name, rgb); + m.color.setRGB(tint[0] / 255, tint[1] / 255, tint[2] / 255, 'srgb'); if (deferOpacity) m.opacity = alpha * m.userData.base; else setSurfaceOpacity(m, alpha * m.userData.base); if (m.userData.glow > 0 || pulse > 0) { diff --git a/src/overlay/scene3d-flow.ts b/src/overlay/scene3d-flow.ts index 2aee475f..87559e6d 100644 --- a/src/overlay/scene3d-flow.ts +++ b/src/overlay/scene3d-flow.ts @@ -1,3 +1,4 @@ +import { setPathSurfaceCoordinates, treatmentOf } from './surface-treatment.ts'; // Connectors and streams on the 3D stage. A connector is a tube whose points are worked out from where its two objects are in the scene // (connector.ts), rebuilt only when they have moved; a stream is a few markers placed along a path from the stream's lap count (stream.ts). // Both are redone on every frame after the scene's matrices are up to date, so they follow the parts they hang on, however those were moved. @@ -148,6 +149,7 @@ export function updateConnectors(nodes: ReadonlyMap, frame: Fr const signature = [radius, flat, ...(along ? [along.x, along.y, along.z] : []), ...local.flat()].map((x) => Math.round(x * 1e5)).join(','); if (signature !== node.connector.signature) { const geo = tubeGeometry(local, radius, flat, radial, def.kind === 'wrapped' ? undefined : def.swell, along ? [along.x, along.y, along.z] : undefined, capDepth); + setPathSurfaceCoordinates(geo, treatmentOf(def)); const old = node.path.geo; node.connector.mesh.geometry = geo; const at = node.geometries.indexOf(old); @@ -230,6 +232,7 @@ export function updateAttached(nodes: ReadonlyMap, frame: Fram const tube = o.shape === 'tube'; const geo = tubeGeometry(moved, tube ? (def as AddTube).radius : pathRadius, tube ? (def as AddTube).flat ?? 1 : 1, radial, tube ? (def as AddTube).swell : undefined); const mesh = node.obj.children[0] as Mesh; + setPathSurfaceCoordinates(geo, treatmentOf(def)); const old = node.path.geo; mesh.geometry = geo; const at = node.geometries.indexOf(old); diff --git a/src/overlay/scene3d.ts b/src/overlay/scene3d.ts index 6a1fdbfb..2a874ccf 100644 --- a/src/overlay/scene3d.ts +++ b/src/overlay/scene3d.ts @@ -1,3 +1,4 @@ +import { applyPathTreatment, setPathSurfaceCoordinates, treatmentOf } from './surface-treatment.ts'; import { taperedExtrudeEdges, taperedExtrudeGeometry } from './tapered-extrusion.ts'; // The 3D scene: builds objects from a Frame, moves them as the frame changes, lights them, puts a soft // shadow under them on the page, and places the camera. It never touches the DOM itself (text sprites @@ -235,6 +236,10 @@ export class PanelScene { }; const addMesh: AddMesh = (geo, surfaceName, edges) => { const surface = makeSurface(surfaceName, settings, finish); + if (def.shape === 'tube' || def.shape === 'connector') { + setPathSurfaceCoordinates(geo, treatmentOf(def)); + applyPathTreatment(surface, treatmentOf(def)); + } if (def.shape === 'patch') { surface.side = DoubleSide; surface.forceSinglePass = true; } if (geo.getAttribute('color')) surface.vertexColors = true; const mesh = new Mesh(geo, surface); diff --git a/src/overlay/surface-treatment.ts b/src/overlay/surface-treatment.ts new file mode 100644 index 00000000..ecf77e66 --- /dev/null +++ b/src/overlay/surface-treatment.ts @@ -0,0 +1,66 @@ +// Optional appearance layered over the named physical material. The scene can +// select a fixed preset, never supply shader code, texture URLs or extra strands. +import { BufferAttribute } from 'three'; +import type { BufferGeometry, Material } from 'three'; +import type { PathTreatment } from '../scene/types.ts'; +import { materialRow } from '../scene/material-library.ts'; + +/** + * The surface layer an object wears: the one the scene asks for with `treatment`, else the one its material carries (the library: muscle, tendon and rope + * have fibres). This is where a layer plugs in: a new name in PathTreatment, its row in the library, its coordinates and its shader below. + */ +export function treatmentOf(def: object): PathTreatment | undefined { + const d = def as { treatment?: PathTreatment; material?: string }; + return d.treatment ?? materialRow(d.material)?.treatment; +} + +/** Coordinates on the existing swept rings, not a projection through world space. + * This topology is shared by open/closed tubes and rebuilt connectors. Untreated + * geometry allocates nothing; position, normal, index and draw range stay intact. */ +export function setPathSurfaceCoordinates(geometry: BufferGeometry, treatment: PathTreatment | undefined): void { + if (treatment !== 'fibres' || geometry.hasAttribute('surfaceCoord')) return; + const rings = geometry.userData.rings as number; + const radial = geometry.userData.indicesPerRing / 6; + const row = radial + 1; + const count = geometry.getAttribute('position').count; + const capRings = geometry.userData.startCap / (radial * 6); + const stability = (geometry.userData.surfaceFrameStability as number | undefined) ?? 1; + const coordinates = new Float32Array(count * 3); + for (let i = 0; i < count; i++) { + const ring = Math.floor(i / row); + const cap = ring >= rings; + const capRing = cap ? (ring - rings) % capRings + 1 : 0; + coordinates[i * 3] = (i % row) / radial; + coordinates[i * 3 + 1] = cap ? (ring < rings + capRings ? 0 : 1) : ring / Math.max(1, rings - 1); + // Fade smoothly to zero at the cap poles, where longitude is undefined. + coordinates[i * 3 + 2] = stability * (cap ? Math.cos(capRing / capRings * Math.PI / 2) ** 2 : 1); + } + geometry.setAttribute('surfaceCoord', new BufferAttribute(coordinates, 3)); +} + +// Even harmonics also make the effect invariant to a 180-degree frame sign. +// Only two fixed harmonics: no texture lookup, loops, time or random state. A +// conservative derivative low-pass fades unresolved fibres to the base material +// rather than letting narrow stripes alias. Take derivatives before any discard. +const FIBRE_FILTER = ` +float filteredFibreWave(float phase, float footprint) { + float resolved = 1.0 - smoothstep(0.25, 0.75, footprint); + return cos(6.28318530718 * fract(phase)) * resolved; +} +`; + +export function applyPathTreatment(material: Material, treatment: PathTreatment | undefined): void { + if (treatment !== 'fibres') return; + const previous = material.onBeforeCompile; + const previousKey = material.customProgramCacheKey(); + material.onBeforeCompile = function (shader, renderer) { + previous.call(this, shader, renderer); + shader.vertexShader = shader.vertexShader + .replace('void main() {', 'attribute vec3 surfaceCoord;\nvarying vec3 vSurfaceCoord;\nvoid main() {\n vSurfaceCoord = surfaceCoord;'); + shader.fragmentShader = shader.fragmentShader + .replace('void main() {', `varying vec3 vSurfaceCoord;\n${FIBRE_FILTER}\nvoid main() {\n float fibrePhase = vSurfaceCoord.x * 28.0;\n float fibreFinePhase = vSurfaceCoord.x * 44.0;\n float fibreWave = vSurfaceCoord.z * (0.7 * filteredFibreWave(fibrePhase, fwidth(fibrePhase))\n + 0.3 * filteredFibreWave(fibreFinePhase, fwidth(fibreFinePhase)));`) + .replace('#include ', '#include \n diffuseColor.rgb *= 1.0 + 0.12 * fibreWave;') + .replace('#include ', '#include \n roughnessFactor = clamp(roughnessFactor - 0.07 * fibreWave, 0.0, 1.0);'); + }; + material.customProgramCacheKey = () => `${previousKey}|path-fibres-v1`; +} diff --git a/src/overlay/timeline.ts b/src/overlay/timeline.ts index 521c6f59..e16f0dc3 100644 --- a/src/overlay/timeline.ts +++ b/src/overlay/timeline.ts @@ -10,6 +10,7 @@ import { heldShift, mountPosition } from '../scene/attach.ts'; import { anchorsOf } from '../scene/anchors.ts'; import { resolvePartGeometry } from '../scene/part-geometry.ts'; import { PALETTE_RGB } from '../scene/colors.ts'; +import { MATERIAL_LIBRARY } from '../scene/material-library.ts'; import { advanceMotion, crankPinKey, crankPinSize, drawsOwnPin, emptyMotion, loopDriver, loopStart, poses, setLock, setRate, spinPlanFrom, spinsAt, stopSpin } from './motion.ts'; import type { CamDef, CoupleDef, CrankDef, FlashDef, JointDef, LoopDef, Motion, Pose, SpinPlan } from './motion.ts'; import { applyDiagramAction, clearDiagrams, diagramPlanFrom, diagramTimes, emptyDiagramPlan, evaluateDiagrams, pulseDiagramThing, styleDiagramThing } from './diagram-plan.ts'; @@ -31,11 +32,8 @@ export const DEFAULT_CAMERA = { az: 0, el: 15, zoom: 1 } as const; export const WORDS_PER_SECOND = 2.5; -/** The colour a 3D object has when the scene does not give one, by its surface. */ -export const MATERIAL_COLOR: Record = { - plastic: [214, 218, 226], metal: [196, 202, 212], rubber: [44, 46, 54], pcb: [22, 122, 70], - glass: [168, 200, 232], glow: [255, 214, 10], paper: [246, 241, 229], -}; +/** The colour a 3D object has when the scene does not give one, by its surface (the library's). */ +export const MATERIAL_COLOR: Record = Object.fromEntries(MATERIAL_LIBRARY.map((m) => [m.name, [...m.color] as Rgb])); /** The colour a new 3D object has when the scene does not give one. */ export function defaultColor(def: AddAction): Rgb { @@ -54,8 +52,9 @@ export function defaultColor(def: AddAction): Rgb { } } if (def.shape === 'stream') return [240, 244, 250]; - if (def.shape === 'connector') return [104, 108, 118]; const material = 'material' in def ? def.material : undefined; + // A connector with no material is a plain grey cord; one that names a material (a muscle, a rope) has that material's colour. + if (def.shape === 'connector' && material === undefined) return [104, 108, 118]; return [...(MATERIAL_COLOR[material ?? 'plastic'] ?? (MATERIAL_COLOR.plastic as Rgb))] as Rgb; } diff --git a/src/scene/guide.ts b/src/scene/guide.ts index 6f7459e7..5ffad66d 100644 --- a/src/scene/guide.ts +++ b/src/scene/guide.ts @@ -5,6 +5,7 @@ import { leanOmits } from './schema.ts'; import { resolvePartGeometry } from './part-geometry.ts'; import { BUILT_IN_ANCHORS } from './anchors.ts'; +import { MATERIAL_NAMES } from './material-library.ts'; import { LIMITS, PALETTE, PARTS, RESERVED_IDS, VARIANTS } from './spec.ts'; import type { Field, Variant } from './spec.ts'; @@ -68,17 +69,18 @@ const lines: string[] = [ `- Screen coordinates run 0 to 1000 across the screenshot (x right, y down). Each size is along its own axis, so a round shape on a 16:9 screen has w about 9/16 of h.`, '- Mark shapes: rot tilts a box or circle; poly takes a point on each corner; point marks one exact spot (a crossing, a tip, a place on a map); trace follows a curve or path through points set along it (head true ends it in an arrowhead); an arrow ends with its tip on what it points at. Put each mark exactly on the thing: the overlay may nudge it a few percent onto the lines and corners of the page itself, so do not count on that.', '- 3D: units x right, y up, z toward the viewer. Size-based solids are centred on their pos; hull points stay in their authored local coordinates. The panel is the rectangle the model is fitted to; the model floats over the page with a shadow. The camera frames the whole model to the panel, so only proportions matter, not the units you draw in: zoom 1 shows all of it, a higher zoom comes in closer on the focused part. Angles are degrees. Never zoom past about 1.6 on one part if the rest should stay legible.', - '- Build models from parts, not primitives alone: box with a bevel for housings, material (plastic metal rubber pcb glass glow paper tissue) for the surface, part for ready-made electronics and machine parts (the part action below lists them, with sizes, axes and anchors), array for repeats (one blade, count 9, turn 40; add the object an array copies before the array), extrude for wings and plates, hull for irregular convex solids from 4 to 64 3D corners, lathe for round bodies, tube for cables, patch for shaped open sheets (16 Bézier controls in four rows; use a regular net, not sixteen points to interpolate).', + '- Build models from parts, not primitives alone: box with a bevel for housings, material for the surface (' + MATERIAL_NAMES.join(' ') + '; name what it is made of: bone, muscle, tendon, skin for a body, steel, iron, brass, copper for machines, wood, rope, water; leave color out unless it should differ, since a tint gives the material a hue but keeps it within its own lightness, so bone stays bone on a white page, never write white for bone), part for ready-made electronics and machine parts (the part action below lists them, with sizes, axes and anchors), array for repeats (one blade, count 9, turn 40; add the object an array copies before the array), extrude for wings and plates, hull for irregular convex solids from 4 to 64 3D corners, lathe for round bodies, tube for cables, patch for shaped open sheets (16 Bézier controls in four rows; use a regular net, not sixteen points to interpolate).', '- Extrude holes are through-openings in the outline local XY plane: use up to 8 separate rings strictly inside the outline, no touching, crossing or nesting. Each ring has 3 to 24 points; all rings and the outline total at most 128 points. Either winding and one repeated closing point are accepted. Openings use flat edges (bevel 0).', '- For a closed cutaway of a round body, use lathe with sweep 1..359 degrees and a simple closed profile of 3..40 [radius,y] points (radius 0..100, y -100..100). It starts at +z towards +x around +y; rotate to choose the opening. Axis contact is allowed; avoid thin, touching or crossing boundaries. Omit sweep for the original full lathe.', '- Tune the finish on shapes with material: roughness 0 polished to 1 matte, metalness 0 nonmetal to 1 metal, clearcoat 0 to 1, clearcoatRoughness 0 polished to 1 matte. Omit/null keeps each named-material value; zero overrides it. For a fully matte finish also set clearcoat 0. Low quality disables clearcoat. These are add fields, not style animation; parts keep their mixed surfaces. Glass stays see-through, not refractive.', + '- Optional treatment fibres on tube/connector adds longitudinal material detail over any material; muscle, tendon and rope tubes and connectors have it already, so write treatment only to add it elsewhere (a rubber cord). No extra strands, geometry or physics. Omit/null for plain. The renderer follows bends, fades tiny detail and keeps glass transparency. Do not model individual fibres.', '- For a curved rail or angular band use sweep: a simple outline cross-section and a smooth open pts path, with optional up for its initial +y direction. The section follows with minimum rotation; keep it narrow relative to bends. It is a capped solid, without holes, bevel, stream or reveal.', '- A loft joins different convex end outlines with equal corner counts: outline at -depth/2, endOutline at +depth/2, corresponding indices and the same winding. Keep every intermediate section convex; no closing repeat, holes or bevel. Use for solid asymmetric transitions, not hollow ducts. On loft or sweep, smooth:true blends rounded section lighting while keeping sharp corners and flat caps; it does not round the silhouette.', '- shell makes hollow ellipsoid sections with closed radial rims: size is the full outer diameters, inner is a concentric scale (not constant thickness), latitude [0,90] an upper dome, [-90,0] a lower bowl, sweep below 360 an angular opening from +x toward +z. Use rot to aim the opening; its origin stays at the full ellipsoid centre.', '- Living or soft subjects (a heart or other organ, a plant, an animal, a fruit) are never boxes and cylinders. A blob is one smooth skin: give it a lump (pts the centre, sizes the box) for each rounded mass, overlapping the next by about a third, so the chambers of an organ or a body and its head melt into one form; use a separate blob only for another colour or a part that moves, and place it touching. Join with tube and swell (a vessel, stem, limb or tail that tapers or bulges), use lathe for bulbs and fruit, material tissue on all of it.', '- Build in the order a person would assemble it, because each part appears as you write it: the base or frame first, then the main parts that rest on it, then the moving parts, then small details; one sub-assembly per step. Write an object before anything that refers to it: the group before its parts, a part before its array, its move or its pin, and pins last, once their part exists. A parent is a group or a part made first, and carries what is attached to it. Schedule a new parent at or before its child. A pin, mark or text cannot be a parent, and a pin or mark cannot be moved or pinned. The parts appearing one after another is the animation, so there is no need to explode and reassemble.', `- Local part anchors (all parts also have origin): ${PARTS.map((part) => { const names = Object.keys(resolvePartGeometry({ part, size: [1, 1, 1] }).anchors).filter((name) => name !== 'origin'); return names.length ? `${part}: ${names.join(',')}` : ''; }).filter(Boolean).join('; ')}. A crankshaft with n>1 has pin1 through pinN (N=min(n,8)) instead of pin. Anchors use the renderer's normalized part sizes, not the raw box axes.`, - `- Attach parts to each other. Never build a pivot group, or work out an offset, to turn a part about an end or an edge: add the part with parent, parentAnchor (a point of the parent) and selfAnchor (a point of itself, default origin). The two points coincide, pos is the offset from that point, and the part stays attached whatever moves, turns, spins, swings, is dragged or exploded (explode draws a faint line back to the point); a turn or swing loop swings it about its point. Patterns: a door is box id door with parent frame, parentAnchor left, selfAnchor left, then loop id door kind swing axis y amount 60, which swings it on its hinge edge; a forearm is a cylinder with parent humerus, parentAnchor bottom, selfAnchor top, then a swing loop bends it at the elbow; a pulley wheel hangs from its beam with parentAnchor bottom, selfAnchor center, pos [0,-1,0] (a part that spins is attached by its centre, because a spin turns it about its attached point); a weight, a hand or a load hangs under a part the same way, and what joins them is a connector, never a line or tube drawn between the two parts, which would stay behind when they move: connector id rope, from wheel, to weight, fromAnchor left, toAnchor top, radius 0.06. A muscle is a connector too, from a point of the bone to a point of the forearm (fromPoint and toPoint in each part's own space, swell [[0,0.6],[0.5,1.8],[1,0.6]] for the belly: a list of [along 0 to 1, radius factor] pairs, never one number; restLength its resting length), so it follows the swing and bulges. Built-in points are in the shape's own space, so they turn with it: ${BUILT_IN_ANCHORS}. A kit part adds its own; anchor names more (an elbow, a hinge edge; write it before the part that uses it); detach lets a part go. Any 3D shape can be a parent and any with a place of its own can be attached (not a tube, line, arrow or connector, whose points are written where they go). Unknown names are refused with the available ones; write the parent first, no later than the child.`, + `- Attach parts to each other. Never build a pivot group, or work out an offset, to turn a part about an end or an edge: add the part with parent, parentAnchor (a point of the parent) and selfAnchor (a point of itself, default origin). The two points coincide, pos is the offset from that point, and the part stays attached whatever moves, turns, spins, swings, is dragged or exploded (explode draws a faint line back to the point); a turn or swing loop swings it about its point. Patterns: a door is box id door with parent frame, parentAnchor left, selfAnchor left, then loop id door kind swing axis y amount 60, which swings it on its hinge edge; a forearm is a cylinder with parent humerus, parentAnchor bottom, selfAnchor top, then a swing loop bends it at the elbow; a pulley wheel hangs from its beam with parentAnchor bottom, selfAnchor center, pos [0,-1,0] (a part that spins is attached by its centre, because a spin turns it about its attached point); a weight, a hand or a load hangs under a part the same way, and what joins them is a connector, never a line or tube drawn between the two parts, which would stay behind when they move: connector id rope, from wheel, to weight, fromAnchor left, toAnchor top, radius 0.06. A muscle is a connector too, from a point of the bone to a point of the forearm (fromPoint and toPoint in each part's own space, swell [[0,0.6],[0.5,1.8],[1,0.6]] for the belly: a list of [along 0 to 1, radius factor] pairs, never one number; restLength its resting length), so it follows the swing and bulges. Built-in points are in the shape's own space, so they turn with it: ${BUILT_IN_ANCHORS}. A kit part adds its own; anchor names more (an elbow, a hinge edge; write it before the part that uses it); detach lets a part go. A group has only its origin and the points you name with anchor (no top or bottom of its own): attach to a shape inside it, or name the point first. Any 3D shape can be a parent and any with a place of its own can be attached (not a tube, line, arrow or connector, whose points are written where they go). Unknown names are refused with the available ones; write the parent first, no later than the child.`, '- Machines move: spin keeps a shaft turning (rpm, or locked to another part by a ratio), crank ties a piston to a spinning crankshaft through its rod, cam opens a valve as a camshaft turns, flash lights a spark or burn at an angle of the cycle, and cut slices a model open to show the inside. These act on parts already added, by id, and add nothing; only the piston, rod and valve move with them, never the cylinder block or a group. Any shape moves as a simple machine: joint (hinge, slide), driven by spin or loop (slide, swing, pulse), or coupled to another joint (gear, belt, lever, screw, pulley). Motion carries on from step to step: set it up once, then narrate over it.', '- What runs between parts or along a path is a connector or a stream, not hand-placed shapes: connector for a physical rope, cord, belt, wire, chain, pipe or muscle between two parts of one 3D model (never a tube or line drawn between them, which would not follow them: from, to, and fromAnchor, toAnchor from the built-in points, such as left, right, top, bottom); stream for dots, dashes or arrows travelling along a path (blood through vessels, current in a wire, water in a pipe, cars on a road, data between computers, money in an economy). Straight/slack connectors can use local fromPoint/toPoint, tube-style swell and restLength for a muscle or soft cord that bulges as its moving ends approach; this visual follows authored motion, never applies forces. Create the tube, line, arrow, connector or flow-diagram edge first; stream along names that path, not a surface or unrelated object.', '- Flat diagrams: diagram kind flow is for an abstract process or cause and effect (node, edge), timeline for events in time (node with when), steps for a how-to (node, then tick), chart for how two quantities relate (series, dot). They are laid out for you and drawn on as you write them: the diagram first, then its pieces in the order the voice reaches them, timed to the words with at.', diff --git a/src/scene/material-library.ts b/src/scene/material-library.ts new file mode 100644 index 00000000..ddf98fff --- /dev/null +++ b/src/scene/material-library.ts @@ -0,0 +1,77 @@ +// The named materials a 3D object can be made of: one row per name, data only (no renderer), so the schema's enum, the colour an object has when none is +// written, the guide's list and the renderer's recipes are all made from the same names. The recipes (the physically based numbers) are in the overlay's +// materials.ts, typed over these names. +// +// The model picks a material by name and may tint it with `color`. A tint gives the material a hue; it never takes it out of its own `band`, the range of +// lightness (relative luminance, 0 to 1) in which the material still reads on a light page and a dark one: a bone tinted white is the palest bone, not a +// white shape on a white page. A material with no band is drawn exactly as the colour says (plastic, metal, rubber and the rest that scenes already use). + +export type Rgb3 = readonly [number, number, number]; + +export type MaterialRow = { + name: string; + /** The colour an object of this material has when the scene gives none, sRGB 0..255. */ + color: Rgb3; + /** The lightness range (relative luminance) a tint is held to; absent: no limit. */ + band?: readonly [number, number]; + /** The surface layer a path-shaped object (tube, connector) of this material wears when the scene names none: fibres along a muscle, a tendon, a rope. */ + treatment?: 'fibres'; +}; + +export const MATERIAL_LIBRARY = [ + { name: 'plastic', color: [140, 150, 172] }, + { name: 'metal', color: [196, 202, 212] }, + { name: 'rubber', color: [96, 100, 112] }, + { name: 'pcb', color: [22, 122, 70] }, + { name: 'glass', color: [168, 200, 232] }, + { name: 'glow', color: [255, 214, 10] }, + { name: 'paper', color: [246, 241, 229] }, + { name: 'tissue', color: [226, 140, 138] }, + { name: 'bone', color: [172, 148, 108], band: [0.07, 0.35] }, + { name: 'muscle', color: [168, 52, 56], band: [0.05, 0.25], treatment: 'fibres' }, + { name: 'tendon', color: [160, 154, 134], band: [0.07, 0.33], treatment: 'fibres' }, + { name: 'skin', color: [206, 142, 112], band: [0.06, 0.37] }, + { name: 'steel', color: [150, 160, 174], band: [0.14, 0.66] }, + { name: 'iron', color: [104, 108, 116], band: [0.135, 0.3] }, + { name: 'brass', color: [196, 156, 62], band: [0.15, 0.6] }, + { name: 'copper', color: [196, 112, 70], band: [0.14, 0.55] }, + { name: 'wood', color: [158, 108, 62], band: [0.075, 0.35] }, + { name: 'rope', color: [176, 148, 100], band: [0.08, 0.38], treatment: 'fibres' }, + { name: 'water', color: [72, 150, 220], band: [0.12, 0.34] }, +] as const satisfies readonly MaterialRow[]; + +export type MaterialName = (typeof MATERIAL_LIBRARY)[number]['name']; + +export const MATERIAL_NAMES = MATERIAL_LIBRARY.map((m) => m.name) as readonly MaterialName[]; + +const BY_NAME: ReadonlyMap = new Map(MATERIAL_LIBRARY.map((m) => [m.name, m])); + +export const materialRow = (name: string | undefined): MaterialRow | undefined => (name === undefined ? undefined : BY_NAME.get(name)); + + +const toLinear = (v: number): number => { const c = v / 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); }; +const toSrgb = (v: number): number => 255 * (v <= 0.0031308 ? v * 12.92 : 1.055 * Math.pow(v, 1 / 2.4) - 0.055); + +/** Relative luminance (0 black to 1 white) of an sRGB colour. */ +export function luminance(c: Rgb3): number { + return 0.2126 * toLinear(c[0]) + 0.7152 * toLinear(c[1]) + 0.0722 * toLinear(c[2]); +} + +/** + * The colour a tint gives a material: the tint itself while its lightness is inside the material's band, otherwise the tint drawn toward the material's own + * colour (in linear light, so the lightness moves in a straight line) just far enough to stand at the nearest edge of the band. A tint can give the + * material a hue; it cannot make bone white or muscle black. A material with no band, or an unknown one, takes the tint as written. + */ +export function fitTint(name: string | undefined, tint: Rgb3): Rgb3 { + const row = materialRow(name); + if (!row?.band) return tint; + const [lo, hi] = row.band; + const y = luminance(tint); + const target = y > hi ? hi : y < lo ? lo : undefined; + if (target === undefined) return tint; + const home = luminance(row.color); + // Where the material's own colour stands against the edge decides which way to draw; the default is always inside the band. + const t = Math.min(1, Math.max(0, (target - y) / (home - y))); + const mix = (i: 0 | 1 | 2): number => Math.max(0, Math.min(255, toSrgb(toLinear(tint[i]) + t * (toLinear(row.color[i]) - toLinear(tint[i]))))); + return [mix(0), mix(1), mix(2)]; +} diff --git a/src/scene/spec.ts b/src/scene/spec.ts index 6a28ba03..f5aa656b 100644 --- a/src/scene/spec.ts +++ b/src/scene/spec.ts @@ -1,6 +1,8 @@ // Scene language v0: the single table the validator and the JSON Schema are both built from. // Change a field here and both follow; docs/scene-language.md describes the same table. +import { MATERIAL_NAMES } from './material-library.ts'; + export const PALETTE = [ 'red', 'orange', 'yellow', 'green', 'teal', 'blue', 'purple', 'pink', 'white', 'gray', 'black', ] as const; @@ -127,9 +129,9 @@ const ROT: Field = { k: 'vec3', min: -3600, max: 3600, opt: true, doc: 'degrees const EXPLODE: Field = { k: 'vec3', ...WORLD, opt: true, doc: 'where it moves when the model is exploded, [x,y,z] in the units of the group it is in (spread 1); without it, it moves outward from the middle of the parts around it' }; /** The surfaces a 3D object can be made of; the colour tints them. */ -export const MATERIALS = ['plastic', 'metal', 'rubber', 'pcb', 'glass', 'glow', 'paper', 'tissue'] as const; +export const MATERIALS = MATERIAL_NAMES; const SIDE: Field = { k: 'enum', values: ['left', 'right', 'top', 'bottom', 'front', 'back'], opt: true }; -const MATERIAL: Field = { k: 'enum', values: MATERIALS, opt: true, doc: 'surface, default plastic' }; +const MATERIAL: Field = { k: 'enum', values: MATERIALS, opt: true, doc: 'named surface (the tint in color keeps within that material own range of lightness, so bone stays bone), default plastic' }; /** Optional physical finish controls. Keeping these separate from opacity preserves each recipe's transparency. */ const FINISH: Record = { roughness: { k: 'num', min: 0, max: 1, opt: true, doc: 'base surface: 0 polished, 1 matte; omitted keeps the material recipe' }, @@ -137,6 +139,7 @@ const FINISH: Record = { clearcoat: { k: 'num', min: 0, max: 1, opt: true, doc: 'clear coating strength; omitted keeps the material recipe; disabled at low quality' }, clearcoatRoughness: { k: 'num', min: 0, max: 1, opt: true, doc: 'coating: 0 polished, 1 matte; only visible with clearcoat; omitted keeps the material recipe' }, }; +const PATH_TREATMENT: Field = { k: 'enum', values: ['fibres'], opt: true, doc: 'optional longitudinal material detail on a tube/connector; follows the path without extra strands or physics' }; const BEVEL: Field = { k: 'num', min: 0, max: 20, opt: true, doc: 'rounding of the edges in units (default small)' }; const EDGES: Field = { k: 'bool', opt: true, doc: 'dark edge lines (default true)' }; const DRAW: Field = { k: 'num', min: 0, max: 1, opt: true, doc: 'how much is drawn at first, 0 to 1 (default 1); grow it with reveal' }; @@ -373,7 +376,7 @@ export const VARIANTS: readonly Variant[] = [ radius: { k: 'num', min: 0.01, max: 20 }, flat: { k: 'num', min: 0.05, max: 1, opt: true }, swell: { k: 'pts2', min: 2, max: LIMITS.maxSwell, lo: 0, hi: 10, opt: true }, closed: { k: 'bool', opt: true, doc: 'Join into a smooth loop with no caps; needs three distinct points. The radius at the join uses the start of swell.' }, - color: COLOR_OPT, material: MATERIAL, ...FINISH, draw: DRAW, opacity: OPACITY, at: AT, + color: COLOR_OPT, material: MATERIAL, ...FINISH, treatment: PATH_TREATMENT, draw: DRAW, opacity: OPACITY, at: AT, }, }, { @@ -398,7 +401,7 @@ export const VARIANTS: readonly Variant[] = [ swell: { k: 'pts2', min: 2, max: LIMITS.maxSwell, lo: 0, hi: 10, opt: true, doc: 'straight/slack: smooth [along 0 to 1, radius factor] profile, as for tube; tapered cords or muscle bellies' }, restLength: { k: 'num', min: 0.01, max: 400, opt: true, doc: 'straight/slack: local path length at authored radius. Radius scales by sqrt(restLength/currentLength), bounded to 0.25–4; illustrative volume preservation, not forces or tissue simulation' }, sag: { k: 'num', min: 0, max: 1, opt: true, doc: 'slack: how far it hangs, as a fraction of its length (default 0.2)' }, - radius: { k: 'num', min: 0.01, max: 2, opt: true }, color: COLOR_OPT, material: MATERIAL, ...FINISH, draw: DRAW, opacity: OPACITY, at: AT, + radius: { k: 'num', min: 0.01, max: 2, opt: true }, color: COLOR_OPT, material: MATERIAL, ...FINISH, treatment: PATH_TREATMENT, draw: DRAW, opacity: OPACITY, at: AT, }, }, { diff --git a/src/scene/types.ts b/src/scene/types.ts index be37fbbf..dc9be201 100644 --- a/src/scene/types.ts +++ b/src/scene/types.ts @@ -2,6 +2,7 @@ // A validated action never carries null: absent optional fields are simply missing. import type { DiagramKind } from './spec.ts'; +import type { MaterialName } from './material-library.ts'; export type { DiagramKind } from './spec.ts'; export type Vec3 = [number, number, number]; @@ -62,7 +63,7 @@ export type DiagramThing = DiagramAction | DiagramPiece; export type PanelAction = { op: 'panel'; x: number; y: number; w: number; h: number; frame?: boolean } & Timing; // 3D objects, added to the stage. Units: y up, x right, z toward the viewer. -export type Material = 'plastic' | 'metal' | 'rubber' | 'pcb' | 'glass' | 'glow' | 'paper' | 'tissue'; +export type Material = MaterialName; /** Optional 0..1 overrides of a named surface. Missing values keep that recipe; low quality disables clearcoat. */ export type SurfaceFinish = { roughness?: number; metalness?: number; clearcoat?: number; clearcoatRoughness?: number }; type Surface = { color?: Color; material?: Material; edges?: boolean; opacity?: number } & SurfaceFinish; @@ -101,8 +102,10 @@ export type AddBlob = { } & Surface & At; /** An end of a tube or line that lies on a 3D part: the part and the point on it (in the part's own space), which the end keeps wherever the part goes. Set by the validator, never written. */ export type AttachEnd = { to: string; at: Vec3 }; +/** Fixed material detail on swept paths; no additional strands or displacement. */ +export type PathTreatment = 'fibres'; export type AddTube = { - op: 'add'; shape: 'tube'; id: string; parent?: string; explode?: Vec3; pts: Vec3[]; radius: number; flat?: number; swell?: Vec2[]; closed?: boolean; draw?: number; + op: 'add'; shape: 'tube'; id: string; treatment?: PathTreatment; parent?: string; explode?: Vec3; pts: Vec3[]; radius: number; flat?: number; swell?: Vec2[]; closed?: boolean; draw?: number; attach?: [AttachEnd | null, AttachEnd | null]; } & Surface & At; export type AddPath = { @@ -126,7 +129,7 @@ export type AddGroup = { op: 'add'; shape: 'group'; id: string; parent?: string; export type Side = 'left' | 'right' | 'top' | 'bottom' | 'front' | 'back'; /** A rope, belt, wire, chain or pipe between two objects, drawn as a tube that follows them as they move. */ export type AddConnector = { - op: 'add'; shape: 'connector'; id: string; parent?: string; from: string; to: string; kind?: 'straight' | 'slack' | 'wrapped'; + op: 'add'; shape: 'connector'; id: string; treatment?: PathTreatment; parent?: string; from: string; to: string; kind?: 'straight' | 'slack' | 'wrapped'; fromSide?: Side; toSide?: Side; fromAnchor?: string; toAnchor?: string; sag?: number; radius?: number; draw?: number; fromPoint?: Vec3; toPoint?: Vec3; swell?: Vec2[]; restLength?: number; } & Surface & At; diff --git a/test/catalogue-relevance.test.ts b/test/catalogue-relevance.test.ts index a173aae1..73813649 100644 --- a/test/catalogue-relevance.test.ts +++ b/test/catalogue-relevance.test.ts @@ -170,7 +170,7 @@ import { dirname, join } from 'node:path'; test('the corpus-selection assertion works in isolated LF and CRLF checkouts', () => { const directory = mkdtempSync(join(tmpdir(), 'tt-catalogue-newlines-')); const files = [ - 'test/catalogue-relevance.test.ts', 'src/scene/spec.ts', + 'test/catalogue-relevance.test.ts', 'src/scene/spec.ts', 'src/scene/material-library.ts', 'scripts/prototypes/catalogue-evaluation.ts', 'scripts/prototypes/catalogue-retrieval.ts', 'scripts/prototypes/catalogue-parts.ts', 'scripts/prototypes/evaluate-catalogue.ts', 'scripts/prototypes/catalogue-validation-v3.json', diff --git a/test/main-path-surface-treatment.test.ts b/test/main-path-surface-treatment.test.ts new file mode 100644 index 00000000..b76f1cd3 --- /dev/null +++ b/test/main-path-surface-treatment.test.ts @@ -0,0 +1,38 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; +import { tmpdir } from 'node:os'; +import { join, resolve } from 'node:path'; +import { MeshPhysicalMaterial } from 'three'; +import type { WebGLProgramParametersWithUniforms, WebGLRenderer } from 'three'; +import { applyPathTreatment } from '../src/overlay/surface-treatment.ts'; +import { electronRuntime } from './support/electron-runtime.ts'; + +// Compile and exercise the actual material patch, separately from lighting. +// The full physical material and sample still require native scene inspection. +test('native fibre shader keeps close detail and removes unresolved frequencies and cap pinching', { timeout: 60_000 }, t => { + const runtime = electronRuntime(); + if (runtime.reason) return t.skip(runtime.reason); + const out = mkdtempSync(join(tmpdir(), 'tt-path-treatment-')); + const material = new MeshPhysicalMaterial(); + try { + applyPathTreatment(material, 'fibres'); + const shader = { + vertexShader: 'void main() { }', + fragmentShader: '#version 300 es\nprecision highp float;\nout vec4 outColor;\nvoid main() {\nvec4 diffuseColor = vec4(0.5);\nfloat roughnessFactor = 0.5;\n#include \n#include \noutColor = vec4(diffuseColor.r, roughnessFactor, 0.0, 1.0);\n}', + uniforms: {}, + }; + material.onBeforeCompile(shader as WebGLProgramParametersWithUniforms, {} as WebGLRenderer); + writeFileSync(join(out, 'fragment.glsl'), shader.fragmentShader.replace('varying vec3', 'in vec3').replace('#include ', '').replace('#include ', '')); + const env = { ...process.env }; delete env.ELECTRON_RUN_AS_NODE; + const run = spawnSync(runtime.executable!, [resolve('test/support/path-surface-treatment.cjs'), out], { env, encoding: 'utf8', timeout: 50_000 }); + assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`); + const result = JSON.parse(readFileSync(join(out, 'result.json'), 'utf8')); + assert.deepEqual(result.failures, [], JSON.stringify(result)); + assert.ok(result.denseCases >= 30); + assert.ok(result.resolvedContrast > 0.07 && result.resolvedContrast < 0.13); + assert.ok(result.maxNeutralError <= 1/255); + t.diagnostic(JSON.stringify(result)); + } finally { material.dispose(); rmSync(out, { recursive: true, force: true }); } +}); diff --git a/test/overlay-surface-treatment.test.ts b/test/overlay-surface-treatment.test.ts new file mode 100644 index 00000000..ca396685 --- /dev/null +++ b/test/overlay-surface-treatment.test.ts @@ -0,0 +1,282 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { readFileSync } from 'node:fs'; +import { Mesh, MeshPhysicalMaterial, Raycaster, ShaderLib, Triangle, Vector3 } from 'three'; +import type { Object3D, WebGLProgramParametersWithUniforms, WebGLRenderer } from 'three'; +import { PanelScene } from '../src/overlay/scene3d.ts'; +import { frameAt, evaluate, planStep } from '../src/overlay/timeline.ts'; +import { createSceneState, validateScene, sceneSchema, sceneSchemaLean } from '../src/scene/index.ts'; +import { check, variantDefinitions } from './support/json-schema.ts'; + +const tube = { op: 'add', shape: 'tube', id: 'path', pts: [[-2,0,0],[0,1,0],[2,0,0]], radius: 0.23, material: 'tissue' }; +const ends = [ + { op: 'add', shape: 'sphere', id: 'a', size: [0.3,0.3,0.3], pos: [-2,0,0] }, + { op: 'add', shape: 'sphere', id: 'b', size: [0.3,0.3,0.3], pos: [2,0,0] }, +]; +const connector = { op: 'add', shape: 'connector', id: 'path', from: 'a', to: 'b', kind: 'slack', sag: 0.3, radius: 0.18, material: 'rubber' }; +function scene(...actions: unknown[]) { + const result = validateScene({ steps: [{ say: 'Inspect the surface.', actions }] }, createSceneState()); + assert.ok(result.scene); + return { ...result, scene: result.scene }; +} +function meshOf(object: Object3D | undefined): Mesh { + let mesh: Mesh | undefined; + object?.traverse(o => { if (!mesh && o instanceof Mesh) mesh = o; }); + assert.ok(mesh); + return mesh; +} +function patch(material: MeshPhysicalMaterial) { + const shader = { vertexShader: ShaderLib.physical.vertexShader, fragmentShader: ShaderLib.physical.fragmentShader, uniforms: {} }; + material.onBeforeCompile(shader as WebGLProgramParametersWithUniforms, {} as WebGLRenderer); + return shader; +} +function setup(actions: unknown[], tier: 'low' | 'mid' | 'high' = 'mid', attached = false) { + const result = scene(...actions); + assert.deepEqual(result.issues.filter(i => !attached || !i.message.includes('it is joined to it')), []); + const frame = frameAt(result.scene.steps, 0, 99); + const panel = new PanelScene({ tier }); + panel.sync(frame, 1); + const key = frame.objects.find(o => o.id === 'path')!.key; + return { panel, frame, key, mesh: meshOf(panel.nodeOf(key)) }; +} + +test('the single fibre preset survives tube and connector validation; null is absent', () => { + for (const action of [tube, connector]) { + const before = action.shape === 'connector' ? ends : []; + const withTreatment = { ...action, treatment: 'fibres' }; + const result = scene(...before, withTreatment); + assert.deepEqual(result.issues, []); + assert.deepEqual(result.scene.steps[0]!.actions.at(-1), withTreatment); + const without = scene(...before, { ...action, treatment: null }); + assert.deepEqual(without.issues, []); + assert.deepEqual(without.scene.steps[0]!.actions.at(-1), action); + for (const value of ['arbitrary-glsl', 1, true, {}, ['fibres']]) { + const invalid = scene(...before, { ...action, treatment: value }, action); + assert.equal(invalid.issues.filter(i => i.kind === 'dropped').length, 1); + assert.deepEqual(invalid.scene.steps[0]!.actions.at(-1), action, 'an invalid treatment must not consume the ID'); + } + } +}); + +test('full and lean strict schemas admit only the path treatment enum on supported shapes', () => { + for (const schema of [sceneSchema, sceneSchemaLean]) { + const defs = variantDefinitions(schema); + for (const name of ['addTube','addConnector']) { + const properties = defs[name]!.properties!; + assert.deepEqual((properties.treatment as { enum: unknown })?.enum, ['fibres', null]); + assert.ok(defs[name]!.required!.includes('treatment')); + assert.deepEqual(check(schema, defs[name]!, { ...(name === 'addTube' ? tube : connector), treatment: 'fibres' }, '$', true), []); + } + for (const name of ['addSolid','addPart','addGroup','addPath','addText','addStream','style']) { + assert.equal(defs[name]!.properties!.treatment, undefined); + } + } +}); + +test('treatment preserves all geometry and base material state on every tier, adding coordinates only when used', () => { + for (const tier of ['low','mid','high'] as const) { + const plain = setup([tube], tier); + const fibres = setup([{ ...tube, treatment: 'fibres' }], tier); + try { + for (const name of ['position','normal']) assert.deepEqual(fibres.mesh.geometry.getAttribute(name).array, plain.mesh.geometry.getAttribute(name).array); + assert.deepEqual(fibres.mesh.geometry.index!.array, plain.mesh.geometry.index!.array); + const coords = fibres.mesh.geometry.getAttribute('surfaceCoord'); + assert.ok(coords, 'path coordinates are renderer-owned'); + assert.equal(coords.count, fibres.mesh.geometry.getAttribute('position').count); + assert.equal(plain.mesh.geometry.getAttribute('surfaceCoord'), undefined, 'untreated geometry keeps its memory budget'); + const a = fibres.mesh.material as MeshPhysicalMaterial, b = plain.mesh.material as MeshPhysicalMaterial; + for (const field of ['roughness','metalness','clearcoat','clearcoatRoughness','opacity','transparent','depthWrite','side','sheen','emissiveIntensity'] as const) assert.equal(a[field], b[field], field); + assert.notEqual(patch(a).fragmentShader, patch(b).fragmentShader); + assert.notEqual(a.customProgramCacheKey(), b.customProgramCacheKey(), 'shader cache must distinguish the treatment'); + assert.equal(fibres.panel.scene.children.length, plain.panel.scene.children.length); + } finally { plain.panel.destroy(); fibres.panel.destroy(); } + } +}); + +test('fibre coordinates remain longitudinal round the circumference and fade at cap poles', () => { + const { panel, mesh } = setup([{ ...tube, treatment: 'fibres' }]); + try { + const g = mesh.geometry, coord = g.getAttribute('surfaceCoord'); + assert.ok(coord); + const rings = g.userData.rings as number, radial = g.userData.indicesPerRing / 6, row = radial + 1; + for (let ring = 0; ring < rings; ring++) for (let j = 0; j <= radial; j++) { + const i = ring * row + j; + assert.ok(Math.abs(coord.getX(i) - j / radial) < 1e-6); + assert.ok(Math.abs(coord.getY(i) - ring / (rings - 1)) < 1e-6); + assert.equal(coord.getZ(i), 1); + } + const capRings = (coord.count / row - rings) / 2; + for (const start of [rings * row, (rings + capRings) * row]) { + for (let ring = 0; ring < capRings; ring++) for (let j = 0; j <= radial; j++) { + assert.ok(coord.getZ(start + ring * row + j) >= 0 && coord.getZ(start + ring * row + j) < 1); + } + for (let j = 0; j <= radial; j++) assert.ok(coord.getZ(start + (capRings - 1) * row + j) < 1e-6); + } + } finally { panel.destroy(); } +}); + +test('closed and flattened tubes carry seam-safe coordinates without adding caps', () => { + for (const flat of [1, 0.2]) { + const { panel, mesh } = setup([{ ...tube, closed: true, flat, treatment: 'fibres' }]); + try { + const g = mesh.geometry, coord = g.getAttribute('surfaceCoord'); + assert.ok(coord); + assert.equal(g.userData.startCap, 0); + const radial = g.userData.indicesPerRing / 6, row = radial + 1; + const last = (g.userData.rings - 1) * row; + for (let j = 0; j <= radial; j++) { + assert.equal(coord.getX(j), coord.getX(last + j)); + assert.equal(coord.getZ(j), 1); assert.equal(coord.getZ(last + j), 1); + } + assert.equal(coord.getX(0), 0); assert.equal(coord.getX(radial), 1); + } finally { panel.destroy(); } + } +}); + +test('moving connectors regenerate coordinates with no material churn and deterministic reverse seeks', () => { + const { panel, frame, key, mesh } = setup([...ends, { ...connector, treatment: 'fibres' }]); + try { + const material = mesh.material, geo = mesh.geometry; + const old = mesh.geometry.getAttribute('surfaceCoord'); + assert.ok(old); + let disposed = 0; geo.addEventListener('dispose', () => disposed++); + const moved = evaluate(planStep(frame, { say: 'Bend.', actions: [{ op: 'move', id: 'b', to: [0.5,1,0.4], dur: 0 }] }), 99); + panel.sync(moved, 1); + assert.notEqual(mesh.geometry, geo); + assert.equal(mesh.material, material); + assert.equal(disposed, 1); + assert.deepEqual(mesh.geometry.getAttribute('surfaceCoord').array, old.array); + panel.sync(frame, 1); + assert.deepEqual(mesh.geometry.getAttribute('position').array, geo.getAttribute('position').array); + assert.deepEqual(mesh.geometry.getAttribute('surfaceCoord').array, old.array); + const stable = mesh.geometry; panel.sync(frame, 1); assert.equal(mesh.geometry, stable); + assert.equal(meshOf(panel.nodeOf(key)).material, material); + } finally { panel.destroy(); } +}); + +test('attached tubes regenerate their treatment when an endpoint moves', () => { + const { panel, frame, mesh } = setup([...ends, { ...tube, pts: [[-2,0,0],[0,0.6,0],[2,0,0]], treatment: 'fibres' }], 'mid', true); + try { + const geo = mesh.geometry; + assert.ok(frame.objects.find(o => o.id === 'path')!.def && 'attach' in frame.objects.find(o => o.id === 'path')!.def); + const moved = evaluate(planStep(frame, { say: 'Move.', actions: [{ op: 'move', id: 'b', to: [2,1,0], dur: 0 }] }), 99); + panel.sync(moved, 1); + assert.notEqual(mesh.geometry, geo); + assert.ok(mesh.geometry.getAttribute('surfaceCoord')); + assert.deepEqual(mesh.geometry.getAttribute('surfaceCoord').array, geo.getAttribute('surfaceCoord').array); + } finally { panel.destroy(); } +}); + +test('glass, clipping, reveals and opacity changes retain treatment without changing alpha rules', () => { + const { panel, frame, mesh } = setup([{ ...tube, material: 'glass', draw: 0.4, treatment: 'fibres' }, { op: 'cut', id: 'path', to: 0, dur: 0 }]); + try { + const material = mesh.material as MeshPhysicalMaterial; + assert.equal(material.opacity, 0.34); assert.equal(material.transparent, true); assert.equal(material.depthWrite, false); + assert.ok(material.clippingPlanes?.length); + assert.ok(mesh.geometry.drawRange.count < mesh.geometry.index!.count); + const shader = patch(material); + assert.match(shader.fragmentShader, /vSurfaceCoord/); + assert.match(shader.fragmentShader, /#include /); + const faded = evaluate(planStep(frame, { say: 'Fade.', actions: [{ op: 'style', id: 'path', opacity: 0.5, dur: 0 }] }), 99); + panel.sync(faded, 1); + assert.equal(material.opacity, 0.17); assert.equal(mesh.material, material); + assert.equal(patch(material).fragmentShader, shader.fragmentShader); + } finally { panel.destroy(); } +}); + +test('arrays inherit treatment while untargeted materials remain unpatched and disposal stays owned once', () => { + const { panel } = setup([{ ...tube, treatment: 'fibres' }, { op: 'add', shape: 'array', id: 'copies', of: 'path', count: 3, step: [0,2,0] }]); + const materials: MeshPhysicalMaterial[] = []; + panel.scene.traverse(o => { if (o instanceof Mesh && o.material instanceof MeshPhysicalMaterial) materials.push(o.material); }); + assert.equal(materials.length, 3); + let disposed = 0; + for (const material of materials) { + assert.match(patch(material).fragmentShader, /vSurfaceCoord/); + material.addEventListener('dispose', () => disposed++); + } + panel.destroy(); + assert.equal(disposed, 3); +}); + +test('the emitted fibre filter fades unresolved detail to neutral and keeps resolved contrast bounded', () => { + const { panel, mesh } = setup([{ ...tube, treatment: 'fibres' }]); + try { + const shader = patch(mesh.material as MeshPhysicalMaterial); + // Evaluate the actual small scalar GLSL filter, not a duplicate production JS helper. + const body = shader.fragmentShader.match(/float filteredFibreWave\(float phase, float footprint\) \{([^}]+)\}/)?.[1]; + assert.ok(body); + const smoothstep = (a: number, b: number, x: number) => { const t = Math.max(0, Math.min(1, (x-a)/(b-a))); return t*t*(3-2*t); }; + const filter = new Function('phase','footprint','smoothstep','cos','fract', body.replace(/float /g,'let ')) as (...args: unknown[]) => number; + const sample = (phase: number, width: number) => filter(phase, width, smoothstep, Math.cos, (x: number) => x-Math.floor(x)); + assert.equal(sample(0, 0), 1); + assert.ok(Math.abs(sample(0.5, 0) + 1) < 1e-12); + for (const width of [0.75,1,4,100]) for (const phase of [-10,-0.3,0,0.2,0.5,3.8]) assert.equal(Math.abs(sample(phase,width)),0); + let previous = 1; + for (let i=0;i<=100;i++) { const value=sample(0,i/100); assert.ok(value>=0 && value<=previous); previous=value; } + for (let i=-200;i<=200;i++) assert.ok(Math.abs(sample(i/31,0.1))<=1); + assert.ok(shader.fragmentShader.indexOf('fwidth(fibrePhase)') < shader.fragmentShader.indexOf('#include ')); + assert.match(shader.fragmentShader, /roughnessFactor = clamp/); + assert.match(shader.fragmentShader, /diffuseColor\.rgb \*=/); + assert.doesNotMatch(shader.fragmentShader, /diffuseColor\.a\s*=/); + } finally { panel.destroy(); } +}); + + +test('the paired demonstration validates unchanged and renders every authored state on each tier', () => { + const input = JSON.parse(readFileSync(new URL('../samples/scenes/path-surface-treatments.json', import.meta.url), 'utf8')); + const result = validateScene(input); + assert.deepEqual(result.issues, []); assert.deepEqual(result.scene, input); assert.ok(result.scene); + for (const tier of ['low','mid','high'] as const) { + const panel = new PanelScene({ tier }); + try { + for (const step of [0,1,2,3,1,0]) { + const frame = frameAt(result.scene.steps,step,99); panel.sync(frame,1); + for (const kind of ['Tissue','Cord','Glass']) { + const get = (prefix: string) => meshOf(panel.nodeOf(frame.objects.find(o => o.id===prefix+kind)!.key)); + const a=get('plain'), b=get('treated'); + assert.deepEqual(a.geometry.getAttribute('position').array,b.geometry.getAttribute('position').array); + assert.ok(b.geometry.getAttribute('surfaceCoord')); + assert.equal(a.geometry.getAttribute('surfaceCoord'),undefined); + } + } + } finally { panel.destroy(); } + } +}); + + +test('tiny endpoint motion across an ambiguous initial frame does not jump the material pattern', async t => { + const cases: Array<[[number,number,number],[number,number,number]]> = [ + [[0,2.62358973342153,3.0194000911911534], [0,2.6236697334215298,3.01933057645694]], + [[0.00004,2.62360973342153,3.0193827125914012], [0.00004,2.62362973342153,3.0193653340241013]], + ]; + for (const [before,after] of cases) await t.test(before[0] === 0 ? 'discrete sign flip' : 'rapid frame rotation', () => { + const { panel, frame, mesh } = setup([ + { ...ends[0], pos: [0,0,0] }, { ...ends[1], pos: before }, + { ...connector, kind: 'straight', radius: 0.2, treatment: 'fibres' }, + ], 'high'); + const waveAtRight = (end: [number,number,number]): number => { + panel.scene.updateMatrixWorld(true); + const origin=new Vector3(2,end[1]/2,end[2]/2); + const hit=new Raycaster(origin,new Vector3(-1,0,0)).intersectObject(mesh,false)[0]; assert.ok(hit?.face); + const positions=mesh.geometry.getAttribute('position'), coordinates=mesh.geometry.getAttribute('surfaceCoord'); + const face=hit.face; + const bary=new Triangle(new Vector3().fromBufferAttribute(positions,face.a),new Vector3().fromBufferAttribute(positions,face.b),new Vector3().fromBufferAttribute(positions,face.c)).getBarycoord(mesh.worldToLocal(hit.point.clone()),new Vector3()); assert.ok(bary); + const u=coordinates.getX(face.a)*bary.x+coordinates.getX(face.b)*bary.y+coordinates.getX(face.c)*bary.z; + const fade=coordinates.getZ(face.a)*bary.x+coordinates.getZ(face.b)*bary.y+coordinates.getZ(face.c)*bary.z; + const code=patch(mesh.material as MeshPhysicalMaterial).fragmentShader; + const body=code.match(/float filteredFibreWave\(float phase, float footprint\) \{([^}]+)\}/)![1]!; + const smoothstep=(a:number,b:number,x:number)=>{const t=Math.max(0,Math.min(1,(x-a)/(b-a)));return t*t*(3-2*t);}; + const filter=new Function('phase','footprint','smoothstep','cos','fract',body.replace(/float /g,'let ')); + const sample=(phase:number,width:number)=>filter(phase,width,smoothstep,Math.cos,(x:number)=>x-Math.floor(x)); + const main=code.match(/float fibrePhase =[^]*?float fibreWave =[^]*?;/)![0]; + return new Function('vSurfaceCoord','fwidth','filteredFibreWave',main.replace(/float /g,'let ')+'return fibreWave;')({x:u,y:0.5,z:fade},()=>0,sample); + }; + try { + const a=waveAtRight(before); + panel.sync(evaluate(planStep(frame,{say:'Tiny movement.',actions:[{op:'move',id:'b',to:after,dur:0}]}),99),1); + const b=waveAtRight(after); + assert.ok(Math.abs(a-b)<1e-5, `material wave jumps from ${a} to ${b}`); + panel.sync(frame,1);assert.ok(Math.abs(waveAtRight(before)-a)<1e-5); + } finally { panel.destroy(); } + }); +}); diff --git a/test/overlay-timeline.test.ts b/test/overlay-timeline.test.ts index ee5be67d..ad793090 100644 --- a/test/overlay-timeline.test.ts +++ b/test/overlay-timeline.test.ts @@ -314,7 +314,8 @@ test('an object with no colour takes the colour of its surface or part', () => { { op: 'add', shape: 'part', id: 'c', part: 'chip', variant: 'metal', size: [1, 1, 1] }, { op: 'add', shape: 'part', id: 'd', part: 'chip', size: [1, 1, 1] }, )], 0, 99); assert.ok((obj(f, 'a')?.color[1] ?? 0) > (obj(f, 'a')?.color[0] ?? 255) * 2, 'a circuit board is green'); - assert.ok((obj(f, 'b')?.color[0] ?? 0) > 180, 'plastic is light'); + // A mid-tone, not near-white: an untinted plastic part has to read on a white page as well as a dark one (the material library measures this). + assert.ok((obj(f, 'b')?.color[0] ?? 0) > 110 && (obj(f, 'b')?.color[0] ?? 0) < 190, 'plastic is a mid-tone'); assert.ok((obj(f, 'c')?.color[0] ?? 0) > 150 && (obj(f, 'd')?.color[0] ?? 255) < 80, 'a metal-lidded chip is light, a plain one dark'); }); diff --git a/test/scene-materials.test.ts b/test/scene-materials.test.ts new file mode 100644 index 00000000..29ba5e6b --- /dev/null +++ b/test/scene-materials.test.ts @@ -0,0 +1,85 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { MATERIAL_LIBRARY, MATERIAL_NAMES, fitTint, luminance, materialRow } from '../src/scene/material-library.ts'; +import { MATERIALS, sceneGuide, sceneSchemaLean, createSceneState, validateStep } from '../src/scene/index.ts'; +import { makeSurface, applySurface, TIERS } from '../src/overlay/materials.ts'; +import { treatmentOf } from '../src/overlay/surface-treatment.ts'; +import { MATERIAL_COLOR, defaultColor } from '../src/overlay/timeline.ts'; +import type { AddAction } from '../src/scene/index.ts'; + +const banded = MATERIAL_LIBRARY.filter((m) => 'band' in m); + +test('the library is one list: the schema enum, the default colours and the guide all carry every name', () => { + assert.deepEqual([...MATERIALS], [...MATERIAL_NAMES]); + for (const name of ['bone', 'muscle', 'tendon', 'skin', 'steel', 'iron', 'brass', 'copper', 'wood', 'rope', 'water', 'plastic', 'rubber', 'glass']) assert.ok(MATERIAL_NAMES.includes(name as never), name); + const schema = JSON.stringify(sceneSchemaLean); + for (const m of MATERIAL_LIBRARY) { + assert.ok(schema.includes(`"${m.name}"`), `${m.name} is in the schema`); + assert.ok(sceneGuide.includes(m.name), `${m.name} is in the guide`); + assert.deepEqual(MATERIAL_COLOR[m.name], [...m.color], `${m.name} has its default colour`); + } + assert.deepEqual(defaultColor({ op: 'add', shape: 'sphere', id: 'a', size: [1, 1, 1], material: 'bone' } as AddAction), [...(materialRow('bone')!.color)]); +}); + +test('every material has a recipe the renderer can make, and a banded one holds its own default', () => { + for (const m of MATERIAL_LIBRARY) { + const surface = makeSurface(m.name, TIERS.mid); + assert.equal(surface.userData.name, m.name); + if ('band' in m) { + const y = luminance(m.color); + assert.ok(y >= m.band[0] && y <= m.band[1], `${m.name}: its own colour (${y.toFixed(3)}) is inside its band ${m.band}`); + } + } +}); + +test('a tint gives a banded material a hue but never takes it out of its band: bone tinted white or black is still bone-toned', () => { + for (const m of banded) { + const [lo, hi] = m.band; + for (const tint of [[255, 255, 255], [0, 0, 0], [255, 0, 0], [0, 0, 255], [255, 255, 0]] as const) { + const y = luminance(fitTint(m.name, tint)); + assert.ok(y >= lo - 1e-6 && y <= hi + 1e-6, `${m.name} tinted ${tint}: ${y.toFixed(3)} is inside ${lo} to ${hi}`); + } + // A tint already inside the band is taken as written, and the colour a scene wrote for an unbanded material is never touched. + assert.deepEqual(fitTint(m.name, m.color), m.color); + } + assert.deepEqual(fitTint('plastic', [255, 255, 255]), [255, 255, 255]); + assert.deepEqual(fitTint('metal', [0, 0, 0]), [0, 0, 0]); + assert.deepEqual(fitTint(undefined, [255, 255, 255]), [255, 255, 255]); + // The hue survives: a red tint on bone is redder than bone, not grey. + const [r, g, b] = fitTint('bone', [200, 60, 60]); + assert.ok(r > g && r > b, 'a red tint stays red'); +}); + +test('the renderer draws a white bone at its palest bone, and an unbanded plastic exactly white', () => { + const bone = makeSurface('bone', TIERS.mid); + applySurface(bone, [255, 255, 255], 1, 0, undefined); + // The colour is held in linear light, where relative luminance is the weighted sum of the channels. + const y = 0.2126 * bone.color.r + 0.7152 * bone.color.g + 0.0722 * bone.color.b; + assert.ok(y <= materialRow('bone')!.band![1] + 1e-6, `white bone is held down to ${y.toFixed(3)}`); + const plastic = makeSurface('plastic', TIERS.mid); + applySurface(plastic, [255, 255, 255], 1, 0, undefined); + assert.equal(plastic.color.r, 1); +}); + +test('the fibre layer is under the named materials: a muscle, tendon or rope path has it without asking, the scene can ask for it on any, and bone has none', () => { + for (const material of ['muscle', 'tendon', 'rope']) assert.equal(treatmentOf({ material }), 'fibres', material); + for (const material of ['bone', 'steel', 'plastic', undefined]) assert.equal(treatmentOf({ material }), undefined, String(material)); + assert.equal(treatmentOf({ material: 'steel', treatment: 'fibres' }), 'fibres', 'asked for by the scene'); + assert.equal(treatmentOf({ treatment: 'fibres' }), 'fibres'); +}); + +test('a scene that names a new material is kept, and one that names a material that does not exist is refused', () => { + const step = (material: string) => ({ say: 'x', actions: [{ op: 'add', shape: 'cylinder', id: 'humerus', size: [0.3, 2, 0.3], material, color: 'white' }] }); + const kept = validateStep(step('bone'), createSceneState()); + assert.deepEqual(kept.issues, []); + assert.ok(kept.step!.actions.some((a) => 'id' in a && a.id === 'humerus')); + const refused = validateStep(step('unobtainium'), createSceneState()); + assert.ok(!refused.step || !refused.step.actions.some((a) => 'id' in a && a.id === 'humerus')); +}); + +test('a connector that names a material has that material colour, and one that names none is the plain grey cord', () => { + const connector = (extra: object) => ({ op: 'add', shape: 'connector', id: 'c', from: 'a', to: 'b', ...extra }) as AddAction; + assert.deepEqual(defaultColor(connector({ material: 'muscle' })), [...materialRow('muscle')!.color]); + assert.deepEqual(defaultColor(connector({ material: 'rope' })), [...materialRow('rope')!.color]); + assert.deepEqual(defaultColor(connector({})), [104, 108, 118]); +}); diff --git a/test/support/path-surface-treatment.cjs b/test/support/path-surface-treatment.cjs new file mode 100644 index 00000000..ac894957 --- /dev/null +++ b/test/support/path-surface-treatment.cjs @@ -0,0 +1,69 @@ +// Isolated material probe: no app state, network, user files or security flags. +const { app, BrowserWindow } = require('electron'); +const { join } = require('node:path'); +const { readFileSync, writeFileSync } = require('node:fs'); +const out = process.argv[2]; +app.setPath('userData', join(out, 'profile')); +app.setPath('sessionData', join(out, 'profile')); +let window; +app.whenReady().then(async () => { + window = new BrowserWindow({ show: false, width: 160, height: 100, webPreferences: { sandbox: true, contextIsolation: true, nodeIntegration: false } }); + await window.loadURL('data:text/html,'); + const fragment = readFileSync(join(out, 'fragment.glsl'), 'utf8'); + const result = await window.webContents.executeJavaScript(`(${probe.toString()})(${JSON.stringify(fragment)})`); + writeFileSync(join(out, 'result.json'), JSON.stringify(result, null, 2)); + window.destroy(); app.exit(0); +}).catch(error => { console.error(error); if (window) window.destroy(); app.exit(1); }); + +function probe(fragment) { + const canvas = document.createElement('canvas'); + const width = 128, height = 4; + canvas.width = width; canvas.height = height; + const gl = canvas.getContext('webgl2', { antialias: false, alpha: false }); + if (!gl) throw new Error('WebGL2 unavailable'); + const compile = (type, source) => { + const shader = gl.createShader(type); gl.shaderSource(shader, source); gl.compileShader(shader); + if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) throw new Error(gl.getShaderInfoLog(shader)); + return shader; + }; + const vertex = compile(gl.VERTEX_SHADER, `#version 300 es + precision highp float; + in vec2 position; + uniform vec3 phase; + uniform float fade; + out vec3 vSurfaceCoord; + void main() { + vec2 pixel = (position + 1.0) * vec2(64.0, 2.0); + vSurfaceCoord = vec3((phase.x + phase.y * pixel.x + phase.z * pixel.y) / 28.0, 0.0, fade); + gl_Position = vec4(position, 0.0, 1.0); + }`); + const pixel = compile(gl.FRAGMENT_SHADER, fragment); + const program = gl.createProgram(); gl.attachShader(program, vertex); gl.attachShader(program, pixel); gl.linkProgram(program); + if (!gl.getProgramParameter(program, gl.LINK_STATUS)) throw new Error(gl.getProgramInfoLog(program)); + gl.useProgram(program); + const buffer = gl.createBuffer(); gl.bindBuffer(gl.ARRAY_BUFFER, buffer); + gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1,-1,1,-1,-1,1,-1,1,1,-1,1,1]), gl.STATIC_DRAW); + const location = gl.getAttribLocation(program, 'position'); gl.enableVertexAttribArray(location); gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0); + const uniform = gl.getUniformLocation(program, 'phase'), fade = gl.getUniformLocation(program, 'fade'); + const pixels = new Uint8Array(width * height * 4); + gl.disable(gl.DITHER); + let denseCases = 0, resolvedContrast = 0, maxNeutralError = 0; + const failures = []; + for (const span of [0.03,0.75,1,2,16]) for (const offset of [-0.3,0,0.2,1.7]) for (const [x,y] of [[1,0],[-1,0],[0.4,0.6]]) for (const cap of [0,1]) { + gl.uniform3f(uniform,offset,span*x,span*y); gl.uniform1f(fade,cap); + gl.drawArrays(gl.TRIANGLES,0,6); gl.readPixels(0,0,width,height,gl.RGBA,gl.UNSIGNED_BYTE,pixels); + let min=1,max=0; + for(let i=0;i0.565 || roughness<0.425 || roughness>0.575) failures.push({span,offset,x,y,cap,i,color,roughness}); + if(span>=0.75 || cap===0) maxNeutralError=Math.max(maxNeutralError,Math.abs(color-0.5),Math.abs(roughness-0.5)); + } + if(span>=0.75) denseCases++; + if(span===0.03 && cap===1) resolvedContrast=Math.max(resolvedContrast,max-min); + } + const extension=gl.getExtension('WEBGL_debug_renderer_info'); + const renderer=extension?gl.getParameter(extension.UNMASKED_RENDERER_WEBGL):gl.getParameter(gl.RENDERER); + gl.deleteProgram(program);gl.deleteShader(vertex);gl.deleteShader(pixel);gl.deleteBuffer(buffer); + return {denseCases,resolvedContrast,maxNeutralError,failures:failures.slice(0,10),renderer}; +}