From 5cf1513d7746bf3c57e86b6acbbd7c588c277672 Mon Sep 17 00:00:00 2001 From: ProjectIdris <227970220+ProjectIdris@users.noreply.github.com> Date: Sun, 8 Nov 2026 22:06:46 +1300 Subject: [PATCH 1/5] A clear written with id, or another op written with target, is read as the field it wants clear names its subject target while every other op says id; a model wrote clear id seven times in one answer and every one was dropped as missing target, so the old parts stayed. The validator now reads id as target on clear, and target as id on the ops that take an id, with a note; a field in its own name wins and an unknown id is still refused. Co-Authored-By: Claude Sonnet 5.5 --- docs/scene.schema.json | 2 +- src/scene/spec.ts | 2 +- src/scene/validate.ts | 21 +++++++++++++++++- test/scene-field-aliases.test.ts | 37 ++++++++++++++++++++++++++++++++ 4 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 test/scene-field-aliases.test.ts diff --git a/docs/scene.schema.json b/docs/scene.schema.json index 06d14d0..5eace19 100644 --- a/docs/scene.schema.json +++ b/docs/scene.schema.json @@ -6371,7 +6371,7 @@ "at" ], "additionalProperties": false, - "description": "Remove an object or mark (and what is attached to it), or everything with \"all\", every mark, card, diagram and pin with \"marks\", the 3D stage and its objects with \"panel\"." + "description": "Remove an object or mark (and what is attached to it): target is its id; or everything with \"all\", every mark, card, diagram and pin with \"marks\", the 3D stage and its objects with \"panel\"." }, "action": { "anyOf": [ diff --git a/src/scene/spec.ts b/src/scene/spec.ts index 988fad0..b6d4065 100644 --- a/src/scene/spec.ts +++ b/src/scene/spec.ts @@ -726,7 +726,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'clear', op: 'clear', - doc: 'Remove an object or mark (and what is attached to it), or everything with "all", every mark, card, diagram and pin with "marks", the 3D stage and its objects with "panel".', + doc: 'Remove an object or mark (and what is attached to it): target is its id; or everything with "all", every mark, card, diagram and pin with "marks", the 3D stage and its objects with "panel".', fields: { target: { k: 'target' }, at: AT }, }, ]; diff --git a/src/scene/validate.ts b/src/scene/validate.ts index e1cfcf7..c88b285 100644 --- a/src/scene/validate.ts +++ b/src/scene/validate.ts @@ -514,12 +514,31 @@ function shapeAsOp(raw: object, path: string, notes: Notes): object { return { ...raw, op: 'add', shape: op }; } +/** + * The name of the thing an op acts on: every op calls it `id` except clear, which says `target` (it also takes all, marks and panel). A model writes the + * one for the other (clear id "eth" seven times in one answer, every one dropped as "missing target"): read it as the field the op wants, with a note. + * A field that is given in its own name wins, and the id is checked as usual, so a clear of an id that does not exist is still refused. + */ +function subjectName(raw: object, path: string, notes: Notes): object { + const op = own(raw, 'op'); + if (typeof op !== 'string') return raw; + const variant = VARIANTS.find((v) => v.op === op && !v.shapes); + if (!variant) return raw; + const [want, given] = op === 'clear' ? ['target', 'id'] : variant.fields.id?.k === 'ref' ? ['id', 'target'] : [undefined, undefined]; + if (!want || !given) return raw; + const value = own(raw, given); + if (typeof value !== 'string' || (own(raw, want) !== undefined && own(raw, want) !== null)) return raw; + note(notes, 'trimmed', path, `repaired: ${op} takes ${want}; ${given} "${value.slice(0, 40)}" read as ${want}`); + const { [given]: _moved, ...rest } = raw as Record; + return { ...rest, [want]: value }; +} + function validateAction(rawIn: unknown, state: SceneState, path: string, notes: Notes, parentFirstAt: ReadonlyMap, mountedChildrenAt: ReadonlyMap, bodies: BodyVersions): Action | null { if (!isObject(rawIn)) { note(notes, 'dropped', path, 'action is not an object'); return null; } - const raw = shapeAsOp(rawIn, path, notes); + const raw = subjectName(shapeAsOp(rawIn, path, notes), path, notes); const variant = pickVariant(raw); if (typeof variant === 'string') { note(notes, 'dropped', path, variant); diff --git a/test/scene-field-aliases.test.ts b/test/scene-field-aliases.test.ts new file mode 100644 index 0000000..5d9dc66 --- /dev/null +++ b/test/scene-field-aliases.test.ts @@ -0,0 +1,37 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createSceneState, sceneGuide, validateStep } from '../src/scene/index.ts'; + +// Every other op names the thing it acts on `id`; clear alone says `target`. A model that writes the id as `id` (seven times in one answer) meant the same. +const run = (...actions: unknown[]) => validateStep({ say: 'x', actions: [{ op: 'panel', x: 500, y: 100, w: 400, h: 600 }, { op: 'add', shape: 'box', id: 'eth', size: [1, 1, 1] }, ...actions] }, createSceneState()); +const ops = (r: ReturnType) => (r.step?.actions ?? []).map((a) => a.op).join(','); + +test('clear written with id is read as clear with target, with a note', () => { + const r = run({ op: 'clear', id: 'eth' }); + assert.equal(ops(r), 'panel,add,clear', JSON.stringify(r.issues)); + assert.equal((r.step!.actions[2] as { target?: string }).target, 'eth'); + assert.ok(r.issues.some((i) => /clear takes target; id "eth" read as target/.test(i.message)), JSON.stringify(r.issues)); + assert.ok(!r.issues.some((i) => /missing target/.test(i.message))); +}); + +test('an explicit target wins over an id, and an unknown id is still refused', () => { + const both = run({ op: 'clear', target: 'eth', id: 'other' }); + assert.equal((both.step!.actions[2] as { target?: string }).target, 'eth'); + const unknown = run({ op: 'clear', id: 'nothing' }); + assert.equal(ops(unknown), 'panel,add', 'a clear of an id that does not exist is dropped as before'); + assert.ok(unknown.issues.some((i) => /unknown id "nothing"/.test(i.message)), JSON.stringify(unknown.issues)); + const everything = run({ op: 'clear', id: 'all' }); + assert.equal((everything.step!.actions[2] as { target?: string }).target, 'all'); +}); + +test('target written where the op wants id is read as id (highlight, move, spin)', () => { + const r = run({ op: 'highlight', target: 'eth' }, { op: 'move', target: 'eth', to: [1, 0, 0] }, { op: 'spin', target: 'eth', rpm: 10 }); + assert.equal(ops(r), 'panel,add,highlight,move,spin', JSON.stringify(r.issues)); + assert.equal((r.step!.actions[2] as { id?: string }).id, 'eth'); + assert.ok(r.issues.some((i) => /highlight takes id; target "eth" read as id/.test(i.message)), JSON.stringify(r.issues)); +}); + +test('the guide says clear takes target, and that it is the id', () => { + assert.match(sceneGuide, /clear \{target at\?\}/); + assert.match(sceneGuide, /clear \{target at\?\}: [^\n]*target is its id/); +}); From 0eeccf608b2d91332006373640a7da901cb208a6 Mon Sep 17 00:00:00 2001 From: ProjectIdris <227970220+ProjectIdris@users.noreply.github.com> Date: Sun, 8 Nov 2026 22:21:12 +1300 Subject: [PATCH 2/5] A kit part attached by a face of its parent turns to face out of it, and an id written again in a follow-up replaces the part A port, lens, screen, chip, header, button or fan declares which way it faces; attached by right, left, top, bottom, front or back of its parent with no rot, the validator turns it so its facing points out of that face and says so in a note. A rot the model wrote, even [0,0,0], stands, as does a part attached by the very side it faces, a part with no facing (a wheel, a gear) and a parent anchor that is not on that side. The guide gives the rule and the facings in place of the port-only sentence. A new answer may write any id left on screen by the last one again: it replaces the part (children stay attached), with a note; an id the answer wrote itself is still unique, and clear then add still works. A detail pass replaces by design and says nothing. The guide says so in one sentence. Co-Authored-By: Claude Sonnet 5.5 --- docs/scene.schema.json | 2 +- src/main/session.ts | 5 ++- src/scene/attach.ts | 18 +++++++++ src/scene/guide.ts | 2 +- src/scene/index.ts | 2 +- src/scene/part-geometry.ts | 12 ++++++ src/scene/spec.ts | 2 +- src/scene/validate.ts | 48 ++++++++++++++++++++-- test/scene-facing.test.ts | 83 ++++++++++++++++++++++++++++++++++++++ test/scene-replace.test.ts | 68 +++++++++++++++++++++++++++++++ 10 files changed, 233 insertions(+), 9 deletions(-) create mode 100644 test/scene-facing.test.ts create mode 100644 test/scene-replace.test.ts diff --git a/docs/scene.schema.json b/docs/scene.schema.json index 5eace19..81a0d15 100644 --- a/docs/scene.schema.json +++ b/docs/scene.schema.json @@ -4012,7 +4012,7 @@ "at" ], "additionalProperties": false, - "description": "A ready-made part fitted to the box size [x,y,z]. Electronics: chip (variant black or metal), header (n pins per row, two rows), port (variant usb, usb3, ethernet, hdmi, usbc; its opening faces +z), lens, screen, button, fan (n blades, axis y), wheel (n spokes, axis z). Mechanism, axis y: cylinder-block (variant cutaway or finned; the bore is round in x,z), piston, connecting-rod (small end up), valve (head down), spark-plug (tip down), spring (n coils), pipe, elbow, housing (variant cutaway); axis z: crankshaft (n throws), camshaft (n lobes), gear (n teeth), bearing (n balls). Their anchors and origin work for pins, connectors and parentAnchor/selfAnchor." + "description": "A ready-made part fitted to the box size [x,y,z]. Electronics: chip (variant black or metal), header (n pins per row, two rows), port (variant usb, usb3, ethernet, hdmi, usbc), lens, screen, button, fan (n blades, axis y), wheel (n spokes, axis z). Mechanism, axis y: cylinder-block (variant cutaway or finned; the bore is round in x,z), piston, connecting-rod (small end up), valve (head down), spark-plug (tip down), spring (n coils), pipe, elbow, housing (variant cutaway); axis z: crankshaft (n throws), camshaft (n lobes), gear (n teeth), bearing (n balls). Their anchors and origin work for pins, connectors and parentAnchor/selfAnchor. Attached by a face of its parent (right, top, front...), a part turns to face out of it unless you give rot; faces: port, lens, screen +z, chip, header, button, fan +y." }, "addArray": { "type": "object", diff --git a/src/main/session.ts b/src/main/session.ts index d921eed..5d3fc17 100644 --- a/src/main/session.ts +++ b/src/main/session.ts @@ -5,7 +5,7 @@ import type { FocusCrop, Model, ModelOutput, ModelRequest, ThreadTurn, Usage } f import { SpeechToTextError } from '../adapters/speech-to-text.ts'; import type { SpeechToText } from '../adapters/speech-to-text.ts'; import type { Screenshot } from '../adapters/types.ts'; -import { applyClear, beginLiveStep, createDetailState, createSceneState, orderScore, sceneSchemaLean, startTurn, validateEscalate, validateStep } from '../scene/index.ts'; +import { applyClear, beginLiveStep, createDetailState, createSceneState, orderScore, sceneSchemaLean, startAnswer, startTurn, validateEscalate, validateStep } from '../scene/index.ts'; import type { Action, Issue, LiveStep, SceneState, Step } from '../scene/index.ts'; import { FADE_AFTER_MS, PEN_FLUSH_GRACE_MS } from '../shared/ipc.ts'; import type { MicResult, Milestone, SceneMessage, Stroke } from '../shared/ipc.ts'; @@ -544,7 +544,8 @@ export function createSession(deps: SessionDeps) { const turn = detail ? Math.max(1, thread.length) : thread.length + 1; const picture = lastAsk?.clean; const known = [...state.ids.keys()]; - startTurn(checking); + // A detail pass replaces what it was shown by design; any other answer may write an id on screen again and replace it, with a note. + if (detail) startTurn(checking); else startAnswer(checking); deps.log(`question heard (turn ${turn}, ${source.label}${deps.logText ? `): ${JSON.stringify(question)}` : ')'}`); const shown: Step[] = []; diff --git a/src/scene/attach.ts b/src/scene/attach.ts index 9f42c7e..5ad3977 100644 --- a/src/scene/attach.ts +++ b/src/scene/attach.ts @@ -39,6 +39,24 @@ const apply = (m: Affine, p: Vec3): Vec3 => [ m.r[3]! * p[0] + m.r[4]! * p[1] + m.r[5]! * p[2] + m.t[1], m.r[6]! * p[0] + m.r[7]! * p[1] + m.r[8]! * p[2] + m.t[2], ]; +/** The way out of each face of a box, in the box's own space: the names a model gives a point on a face. */ +export const FACE_NORMALS: Readonly> = { + right: [1, 0, 0], left: [-1, 0, 0], top: [0, 1, 0], bottom: [0, -1, 0], front: [0, 0, 1], back: [0, 0, -1], +}; + +/** + * The rot (Euler degrees) that turns a part's own facing, one of the six axes, to point along a face's normal by the shortest way; undefined when it + * already does. A quarter turn about the axis both are square to, or half a turn about one square to the facing when they are opposite. + */ +export function turnToFace(facing: Vec3, normal: Vec3): Vec3 | undefined { + const cross: Vec3 = [facing[1] * normal[2] - facing[2] * normal[1], facing[2] * normal[0] - facing[0] * normal[2], facing[0] * normal[1] - facing[1] * normal[0]]; + if (cross.every((v) => v === 0)) { + if (facing[0] * normal[0] + facing[1] * normal[1] + facing[2] * normal[2] > 0) return undefined; + return facing[1] !== 0 ? [180, 0, 0] : [0, 180, 0]; + } + return cross.map((v) => v * 90 + 0) as Vec3; +} + /** Initial socket placement: rotation is explicit, and the offset is in the parent's frame. No runtime constraint is created. */ export function mountPosition(parentAnchor: Vec3, selfAnchor: Vec3, rot: Vec3, offset: Vec3, scale: Vec3 = [1, 1, 1]): Vec3 { const scaled: Vec3 = [selfAnchor[0] * scale[0], selfAnchor[1] * scale[1], selfAnchor[2] * scale[2]]; diff --git a/src/scene/guide.ts b/src/scene/guide.ts index 7e48280..7fa123c 100644 --- a/src/scene/guide.ts +++ b/src/scene/guide.ts @@ -81,7 +81,7 @@ const lines: string[] = [ '- 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). 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.', '- Name the parts of a 3D model with pin (on the object id, text; leave off out, the tag is placed for you clear of the model): it follows the part when the model turns, and a pin goes on a 3D object only. Name the parts and places of a picture on the page with label (a short name, x,y its top-left corner) beside a point. Use card for a short list or timeline, and image to crop part of the screenshot.', - `- Every mark and object has a unique id (a letter, then up to 31 letters, digits, - or _; not ${RESERVED_IDS.join(', ')}). Use the id later to change or clear it. Ids from earlier answers stay valid until cleared.`, + `- Every mark and object has a unique id (a letter, then up to 31 letters, digits, - or _; not ${RESERVED_IDS.join(', ')}). Use the id later to change or clear it; write an id again to replace it. Ids from earlier answers stay valid until cleared.`, '- at = seconds after the step starts, dur = seconds a change takes. Time the actions to the words.', `- Colours: ${PALETTE.join(', ')}. Opacity 0 to 1. Text up to ${LIMITS.maxText} characters; say up to ${LIMITS.maxSay}. At most ${LIMITS.maxActionsPerStep} actions a step.`, '- A ? after a field name means optional (null).', diff --git a/src/scene/index.ts b/src/scene/index.ts index d5ae604..0018f22 100644 --- a/src/scene/index.ts +++ b/src/scene/index.ts @@ -1,6 +1,6 @@ export * from './types.ts'; export * from './spec.ts'; -export { applyClear, beginLiveStep, createDetailState, createSceneState, startTurn, validateStep, validateScene, validateEscalate } from './validate.ts'; +export { applyClear, beginLiveStep, createDetailState, createSceneState, startAnswer, startTurn, validateStep, validateScene, validateEscalate } from './validate.ts'; export type { LiveStep, LiveStepEvents, SceneState, StepResult, SceneResult } from './validate.ts'; export { createStepStream } from './stream.ts'; export type { StepPiece, StepStream, StepStreamOptions } from './stream.ts'; diff --git a/src/scene/part-geometry.ts b/src/scene/part-geometry.ts index b9bbca7..399748b 100644 --- a/src/scene/part-geometry.ts +++ b/src/scene/part-geometry.ts @@ -60,6 +60,18 @@ export function normalSize(part: string, size: Vec3): Vec3 { } } +/** + * Which way a kit part faces in its own space (where its opening, glass or pins are), for the parts that have a front; the rest have none (a gear or a + * piston is round about an axis, a wheel hangs by its centre) and are never turned for a face. + */ +export function partFacing(part: string): Vec3 | undefined { + switch (part) { + case 'port': case 'lens': case 'screen': return [0, 0, 1]; + case 'chip': case 'header': case 'button': case 'fan': return [0, 1, 0]; + default: return undefined; + } +} + /** Radius of the circle the crank pin travels, for a crankshaft of this size box. */ export function crankThrow(size: Vec3): number { return Math.min(size[0], size[1]) * 0.3; diff --git a/src/scene/spec.ts b/src/scene/spec.ts index b6d4065..9646977 100644 --- a/src/scene/spec.ts +++ b/src/scene/spec.ts @@ -449,7 +449,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addPart', op: 'add', shapes: ['part'], creates: 'group', - doc: 'A ready-made part fitted to the box size [x,y,z]. Electronics: chip (variant black or metal), header (n pins per row, two rows), port (variant usb, usb3, ethernet, hdmi, usbc; its opening faces +z), lens, screen, button, fan (n blades, axis y), wheel (n spokes, axis z). Mechanism, axis y: cylinder-block (variant cutaway or finned; the bore is round in x,z), piston, connecting-rod (small end up), valve (head down), spark-plug (tip down), spring (n coils), pipe, elbow, housing (variant cutaway); axis z: crankshaft (n throws), camshaft (n lobes), gear (n teeth), bearing (n balls). Their anchors and origin work for pins, connectors and parentAnchor/selfAnchor.', + doc: 'A ready-made part fitted to the box size [x,y,z]. Electronics: chip (variant black or metal), header (n pins per row, two rows), port (variant usb, usb3, ethernet, hdmi, usbc), lens, screen, button, fan (n blades, axis y), wheel (n spokes, axis z). Mechanism, axis y: cylinder-block (variant cutaway or finned; the bore is round in x,z), piston, connecting-rod (small end up), valve (head down), spark-plug (tip down), spring (n coils), pipe, elbow, housing (variant cutaway); axis z: crankshaft (n throws), camshaft (n lobes), gear (n teeth), bearing (n balls). Their anchors and origin work for pins, connectors and parentAnchor/selfAnchor. Attached by a face of its parent (right, top, front...), a part turns to face out of it unless you give rot; faces: port, lens, screen +z, chip, header, button, fan +y.', fields: { shape: { k: 'enum', values: ['part'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, part: { k: 'enum', values: PARTS }, variant: { k: 'enum', values: PART_VARIANTS, opt: true }, diff --git a/src/scene/validate.ts b/src/scene/validate.ts index c88b285..4bd71c2 100644 --- a/src/scene/validate.ts +++ b/src/scene/validate.ts @@ -12,9 +12,9 @@ import { LOFT_STRIPS, prepareLoft } from './loft.ts'; import { prepareShell, SHELL_DETAIL } from './shell.ts'; import type { ShellTier } from './shell.ts'; import { nearestPaletteColor } from './colors.ts'; -import { attachTolerance, landOn, mountPosition } from './attach.ts'; +import { attachTolerance, FACE_NORMALS, landOn, mountPosition, turnToFace } from './attach.ts'; import { anchorsOf } from './anchors.ts'; -import { resolvePartGeometry } from './part-geometry.ts'; +import { partFacing, resolvePartGeometry } from './part-geometry.ts'; import { resolveHullPoints } from './hull-points.ts'; import type { Body } from './attach.ts'; import { bindParts, bindUnknownId, BINDINGS } from './bind.ts'; @@ -61,6 +61,8 @@ export type SceneState = { * any other and cannot be written a third time. Ids named but never written again stay valid to refer to. */ replaceable?: Set; + /** Set when the ids on screen may be replaced by an ordinary answer (not a detail pass, which does it by design): each replacement is then said in a note. */ + replaceNote?: boolean; /** The size of the 3D stage as last written (a stage written with no size takes it). */ stage?: { w: number; h: number }; /** Set only while an action that named an id the scene does not have is tried once more, after the rest had their chance to make it. */ @@ -100,6 +102,16 @@ export function startTurn(state: SceneState): void { state.turnActions = 0; } +/** + * A new answer begins on a scene that may already have things on screen from the last: it may write any of their ids again, and that replaces the thing + * (a follow-up that says "move this" or "make this bigger" writes the part again). What the answer itself writes is then in use like any id. + */ +export function startAnswer(state: SceneState): void { + startTurn(state); + state.replaceable = new Set(state.ids.keys()); + state.replaceNote = true; +} + type Notes = Issue[]; function note(notes: Notes, kind: IssueKind, path: string, message: string): void { @@ -366,6 +378,34 @@ function bodyAt(versions: BodyVersions, id: string, at: number): Body | undefine return found?.body; } +/** The self anchor that names the side a facing part faces by (the one a part put "face to the surface" would be attached by). */ +const FACING_SIDE = new Map([['0,0,1', 'front'], ['0,1,0', 'top']]); + +/** + * A kit part with a front (a port's opening, a lens, a chip's top) attached by a face of its parent (right, top, front...) is meant to face out of that + * face; written with no rot it would keep its default turn, which only suits one face in six. Its rot is set to turn it out, with a note. A rot the model + * wrote, even [0,0,0], is its own call and stands, and so does a part attached by the very side it faces (it was asked to put that side on the surface). + */ +function faceTurn(out: Record, state: SceneState, path: string, notes: Notes, bodies: BodyVersions): void { + if (out.shape !== 'part' || typeof out.part !== 'string' || out.rot !== undefined || typeof out.parent !== 'string') return; + const facing = partFacing(out.part); + const face = typeof out.parentAnchor === 'string' ? out.parentAnchor : undefined; + const normal = face === undefined ? undefined : FACE_NORMALS[face]; + if (!facing || !face || !normal) return; + if (out.selfAnchor === FACING_SIDE.get(facing.join(','))) return; + if (out.parent === out.id || isUnder(state, out.parent, out.id as string)) return; + const anchors = bodyAt(bodies, out.parent, (out.at as number | undefined) ?? 0)?.anchors; + const at = anchors?.[face]; + if (!at) return; + // A point the model named "right" that is not on the right of the parent's middle is not a face. + const middle = anchors.center ?? anchors.origin ?? ZERO; + if ((at[0] - middle[0]) * normal[0] + (at[1] - middle[1]) * normal[1] + (at[2] - middle[2]) * normal[2] <= 0) return; + const rot = turnToFace(facing, normal); + if (!rot) return; + out.rot = rot; + note(notes, 'trimmed', `${path}.rot`, `repaired: "${out.id as string}" is attached by ${face}, so its ${out.part} is turned to face out of it (rot [${rot.join(',')}]); write rot to turn it another way`); +} + /** Check declarative socket placement and preview its authored position for surface attachment. Playback resolves the creation-time base transforms. */ function checkMount(out: Record, state: SceneState, path: string, notes: Notes, bodies: BodyVersions): Vec3 | null | undefined { if (out.parentAnchor === undefined && out.selfAnchor === undefined) return undefined; @@ -702,6 +742,7 @@ function validateAction(rawIn: unknown, state: SceneState, path: string, notes: note(notes, 'dropped', path, 'define or replace the parent before its mounted children; a later-written replacement cannot precede an accepted mount'); return null; } + faceTurn(out, state, path, notes, bodies); const mountedPos = checkMount(out, state, path, notes, bodies); if (mountedPos === null) return null; if (variant.op === 'panel' && typeof out.w === 'number' && typeof out.h === 'number') state.stage = { w: out.w, h: out.h }; @@ -822,7 +863,7 @@ function validateAction(rawIn: unknown, state: SceneState, path: string, notes: if (variant.creates) { const id = out.id as string; // An id from the scene already on screen, written again, replaces the old one: any 3D object for any other (a box for a kit part, a cylinder for a tube), a mark, pin or text only for its own kind. - const replacing = state.replaceable?.has(id) === true; + const replacing = state.replaceable?.has(id) === true && state.ids.has(id); // A stream on an arrow of a flow diagram belongs to the diagram (a clear of the marks takes it); on a path it is a 3D object. const kind: ObjectKind = variant.name === 'addStream' && state.ids.get(out.along as string) === 'edge' ? 'dot' : variant.creates; if (replacing && !swappable(state.ids.get(id), kind)) { @@ -833,6 +874,7 @@ function validateAction(rawIn: unknown, state: SceneState, path: string, notes: note(notes, 'dropped', path, `scene already holds ${LIMITS.maxObjects} objects`); return null; } + if (replacing && state.replaceNote) note(notes, 'trimmed', path, `repaired: "${id}" was already on screen; this replaces it (clear it first to start it over)`); state.replaceable?.delete(id); const parent = (variant.attach ? out[variant.attach] : out.parent) as string | undefined; state.ids.set(id, kind); diff --git a/test/scene-facing.test.ts b/test/scene-facing.test.ts new file mode 100644 index 0000000..641fcc9 --- /dev/null +++ b/test/scene-facing.test.ts @@ -0,0 +1,83 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createSceneState, sceneGuide, validateStep } from '../src/scene/index.ts'; +import { mountPosition } from '../src/scene/attach.ts'; + +type Act = { op: string; id?: string; rot?: [number, number, number]; pos?: [number, number, number]; [k: string]: unknown }; +const board = (size = [6, 0.2, 4], extra: object = {}) => ({ op: 'add', shape: 'box', id: 'pcb', size, ...extra }); +const part = (id: string, kind: string, parentAnchor: string, extra: object = {}) => + ({ op: 'add', shape: 'part', part: kind, id, parent: 'pcb', parentAnchor, size: [1.2, 0.8, 1], ...extra }); +const run = (...actions: unknown[]) => { + const r = validateStep({ say: 'x', actions: [{ op: 'panel', x: 500, y: 100, w: 400, h: 600 }, board(), ...actions] }, createSceneState()); + return { r, by: (id: string) => (r.step?.actions ?? []).find((a) => (a as Act).id === id) as Act | undefined }; +}; +const noted = (r: ReturnType['r'], re: RegExp) => r.issues.some((i) => re.test(i.message)); +/** Where a part's facing points once turned by rot: the mount arithmetic is rot applied to a point, so the point's turned place is minus the shift. */ +const turned = (rot: number[] | undefined, f: number[]) => mountPosition([0, 0, 0], f as never, (rot ?? [0, 0, 0]) as never, [0, 0, 0]).map((v) => Math.round(-v) + 0); + +test('a port attached by the right face with no rot is turned so its opening points out of that face', () => { + const { r, by } = run(part('usb', 'port', 'right', { selfAnchor: 'center' })); + assert.deepEqual(by('usb')?.rot, [0, 90, 0]); + assert.deepEqual(turned(by('usb')?.rot, [0, 0, 1]), [1, 0, 0]); + assert.ok(noted(r, /usb.*turned to face/), JSON.stringify(r.issues)); +}); + +test('every face turns a port, a header and a chip to point out of it', () => { + const normals: Record = { right: [1, 0, 0], left: [-1, 0, 0], top: [0, 1, 0], bottom: [0, -1, 0], front: [0, 0, 1], back: [0, 0, -1] }; + const facings: Record = { port: [0, 0, 1], lens: [0, 0, 1], screen: [0, 0, 1], chip: [0, 1, 0], header: [0, 1, 0], button: [0, 1, 0], fan: [0, 1, 0] }; + for (const [kind, f] of Object.entries(facings)) for (const [face, n] of Object.entries(normals)) { + const { by } = run(part('p', kind, face, { selfAnchor: 'center' })); + assert.deepEqual(turned(by('p')?.rot, f), n, `${kind} on ${face}: rot ${JSON.stringify(by('p')?.rot)}`); + } +}); + +test('an explicit rot wins, even [0,0,0]; a part already facing out is left as it is', () => { + const zero = run(part('usb', 'port', 'right', { rot: [0, 0, 0] })); + assert.deepEqual(zero.by('usb')?.rot, [0, 0, 0]); + assert.ok(!noted(zero.r, /turned to face/)); + const given = run(part('usb', 'port', 'right', { rot: [0, 90, 0], selfAnchor: 'right' })); + assert.deepEqual(given.by('usb')?.rot, [0, 90, 0]); + const out = run(part('hdmi', 'port', 'front'), part('soc', 'chip', 'top', { selfAnchor: 'bottom' })); + assert.equal(out.by('hdmi')?.rot, undefined); + assert.equal(out.by('soc')?.rot, undefined); + assert.ok(!noted(out.r, /turned to face/)); +}); + +test('a part whose own facing side is the anchor it is attached by is left alone, as is a part with no facing', () => { + // A chip hung under the board by its top: it was asked to put its top against the board. + const under = run(part('soc', 'chip', 'bottom', { selfAnchor: 'top' })); + assert.equal(under.by('soc')?.rot, undefined); + const wheel = run(part('w', 'wheel', 'bottom', { selfAnchor: 'center', size: [1, 1, 0.2] })); + assert.equal(wheel.by('w')?.rot, undefined); + const plain = run({ op: 'add', shape: 'box', id: 'b', parent: 'pcb', parentAnchor: 'right', size: [1, 1, 1] }); + assert.equal(plain.by('b')?.rot, undefined); + const noFace = run(part('usb', 'port', 'center')); + assert.equal(noFace.by('usb')?.rot, undefined); +}); + +test('the turn is made before the placement is worked out, and the parent turning does not change it', () => { + const plain = run(part('usb', 'port', 'right', { selfAnchor: 'back', pos: [0, 0.5, 0] })); + const spun = (() => { + const r = validateStep({ say: 'x', actions: [{ op: 'panel', x: 500, y: 100, w: 400, h: 600 }, board([6, 0.2, 4], { rot: [0, 40, 0] }), part('usb', 'port', 'right', { selfAnchor: 'back', pos: [0, 0.5, 0] })] }, createSceneState()); + return (r.step?.actions ?? []).find((a) => (a as Act).id === 'usb') as Act; + })(); + assert.deepEqual(plain.by('usb')?.rot, [0, 90, 0]); + assert.deepEqual(spun.rot, [0, 90, 0]); + // Its back (at -z in its own space) is on the edge: after the turn the port stands outside the board, mouth out. + assert.ok(!plain.r.issues.some((i) => /dropped/.test(i.kind)), JSON.stringify(plain.r.issues)); +}); + +test('an anchor of the parent called right that is not on its right is not read as a face', () => { + const r = validateStep({ say: 'x', actions: [ + { op: 'panel', x: 500, y: 100, w: 400, h: 600 }, board(), { op: 'anchor', id: 'pcb', name: 'right', pos: [-3, 0, 0] }, part('usb', 'port', 'right'), + ] }, createSceneState()); + const usb = (r.step?.actions ?? []).find((a) => (a as Act).id === 'usb') as Act; + assert.equal(usb.rot, undefined); +}); + +test('the guide gives the rule and the facings, and no longer only the port', () => { + assert.match(sceneGuide, /turns to face out of it unless you give rot/); + assert.match(sceneGuide, /port, lens, screen \+z/); + assert.match(sceneGuide, /chip, header, button, fan \+y/); + assert.ok(!/opening faces \+z/.test(sceneGuide), 'the old port-only sentence is gone'); +}); diff --git a/test/scene-replace.test.ts b/test/scene-replace.test.ts new file mode 100644 index 0000000..a79f736 --- /dev/null +++ b/test/scene-replace.test.ts @@ -0,0 +1,68 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createSceneState, sceneGuide, startAnswer, validateStep } from '../src/scene/index.ts'; + +type Act = { op: string; id?: string; size?: number[]; target?: string }; +const first = () => { + const state = createSceneState(); + const r = validateStep({ say: 'x', actions: [ + { op: 'panel', x: 500, y: 100, w: 400, h: 600 }, + { op: 'add', shape: 'box', id: 'pcb', size: [6, 0.2, 4] }, + { op: 'add', shape: 'box', id: 'eth', parent: 'pcb', size: [1, 1, 1] }, + { op: 'pin', id: 'peth', on: 'eth', text: 'Ethernet' }, + ] }, state); + assert.deepEqual(r.issues.map((i) => i.message), []); + return state; +}; +const ids = (r: ReturnType) => (r.step?.actions ?? []).map((a) => `${a.op}:${(a as Act).id ?? (a as Act).target ?? ''}`); + +test('in a follow-up, writing an id that is on screen replaces it, with a note', () => { + const state = first(); + startAnswer(state); // the next answer + const r = validateStep({ say: 'y', actions: [{ op: 'add', shape: 'box', id: 'eth', parent: 'pcb', size: [2, 1, 1] }] }, state); + assert.deepEqual(ids(r), ['add:eth']); + assert.ok(r.issues.some((i) => /"eth".*replaces/.test(i.message)), JSON.stringify(r.issues)); + assert.ok(!r.issues.some((i) => i.kind === 'dropped')); +}); + +test('a part written in this answer is not replaceable: a second write of it is refused', () => { + const state = first(); + startAnswer(state); + const r = validateStep({ say: 'y', actions: [ + { op: 'add', shape: 'box', id: 'eth', parent: 'pcb', size: [2, 1, 1] }, + { op: 'add', shape: 'box', id: 'eth', parent: 'pcb', size: [3, 1, 1] }, + { op: 'add', shape: 'box', id: 'usb', parent: 'pcb', size: [1, 1, 1] }, + { op: 'add', shape: 'box', id: 'usb', parent: 'pcb', size: [1, 2, 1] }, + ] }, state); + assert.deepEqual(ids(r), ['add:eth', 'add:usb']); + assert.equal(r.issues.filter((i) => /already in use/.test(i.message)).length, 2, JSON.stringify(r.issues)); +}); + +test('within the answer that built it, an id is still unique (no turn has started since)', () => { + const state = createSceneState(); + const r = validateStep({ say: 'x', actions: [ + { op: 'panel', x: 500, y: 100, w: 400, h: 600 }, + { op: 'add', shape: 'box', id: 'a', size: [1, 1, 1] }, + { op: 'add', shape: 'box', id: 'a', size: [2, 1, 1] }, + ] }, state); + assert.deepEqual(ids(r), ['panel:', 'add:a']); +}); + +test('a 3D object may be swapped for another 3D kind, a mark only for a mark, and clear then add still works', () => { + const state = first(); + startAnswer(state); + const swapped = validateStep({ say: 'y', actions: [{ op: 'add', shape: 'sphere', id: 'eth', parent: 'pcb', size: [1, 1, 1] }] }, state); + assert.deepEqual(ids(swapped), ['add:eth']); + const mark = validateStep({ say: 'y', actions: [{ op: 'box', id: 'pcb', x: 10, y: 10, w: 100, h: 100, color: 'red' }] }, state); + assert.deepEqual(ids(mark), []); + assert.ok(mark.issues.some((i) => /cannot be swapped/.test(i.message))); + const again = first(); + startAnswer(again); + const cleared = validateStep({ say: 'y', actions: [{ op: 'clear', target: 'eth' }, { op: 'add', shape: 'box', id: 'eth', parent: 'pcb', size: [2, 1, 1] }] }, again); + assert.deepEqual(ids(cleared), ['clear:eth', 'add:eth']); + assert.ok(!cleared.issues.some((i) => /replaces/.test(i.message)), 'a cleared id is a new one, not a replacement'); +}); + +test('the guide says an id written again replaces it', () => { + assert.match(sceneGuide, /write an id again to replace it/); +}); From 399d853b87765b9aca62f8d2fdbee4b659b79f50 Mon Sep 17 00:00:00 2001 From: ProjectIdris <227970220+ProjectIdris@users.noreply.github.com> Date: Sun, 8 Nov 2026 22:51:51 +1300 Subject: [PATCH 3/5] Renderer realism: studio environment, physical material recipes, fine surface and procedural board, light occlusion on mid, rounded hull and tapered edges Co-Authored-By: Claude Sonnet 5.5 --- src/overlay/edge-soften.ts | 121 ++++++++++++++++++++++++++++ src/overlay/materials.ts | 48 ++++++----- src/overlay/overlay.ts | 16 ++-- src/overlay/post.ts | 29 +++++-- src/overlay/scene3d.ts | 9 ++- src/overlay/studio.ts | 75 +++++++++++++++++ src/overlay/surface-micro.ts | 152 +++++++++++++++++++++++++++++++++++ test/overlay-realism.test.ts | 98 ++++++++++++++++++++++ 8 files changed, 515 insertions(+), 33 deletions(-) create mode 100644 src/overlay/edge-soften.ts create mode 100644 src/overlay/studio.ts create mode 100644 src/overlay/surface-micro.ts create mode 100644 test/overlay-realism.test.ts diff --git a/src/overlay/edge-soften.ts b/src/overlay/edge-soften.ts new file mode 100644 index 0000000..5032e99 --- /dev/null +++ b/src/overlay/edge-soften.ts @@ -0,0 +1,121 @@ +// Rounded edges for flat-faced shapes that have none (a convex hull, a tapered extrusion): where two faces meet at a sharp angle the shading +// turns from the face's normal toward the normal of the face beyond, over a narrow band beside the edge, so the edge catches a thin highlight the way a +// small fillet does. Nothing is added to the geometry but five small attributes (the same on a triangle's three corners), and the shader does a few steps +// per pixel. Boxes, extrusions and cylinders are rounded in their geometry already and do not use this. + +import { BufferAttribute, Vector3 } from 'three'; +import type { BufferGeometry, MeshPhysicalMaterial } from 'three'; + +/** Edges meeting at less than this angle stay as they are (a gentle bend is already smooth). */ +const MIN_ANGLE = 28; +/** The width of the rounded band, as a fraction of the shape's size. */ +const BAND = 0.045; + +export const EDGE_ATTRIBUTES = ['edgeBary', 'edgeAlt', 'edgeNb0', 'edgeNb1', 'edgeNb2'] as const; + +/** Makes the geometry's faces known to their neighbours. Returns the same geometry (made non-indexed), or undefined when it has no faces to work on. */ +export function softenEdges(source: BufferGeometry): BufferGeometry | undefined { + const geo = source.index ? source.toNonIndexed() : source; + if (geo !== source) { Object.assign(geo.userData, source.userData); source.dispose(); } + const pos = geo.getAttribute('position'); + if (!pos || pos.count < 3) return undefined; + const tris = Math.floor(pos.count / 3); + geo.computeBoundingBox(); + const size = geo.boundingBox ? geo.boundingBox.getSize(new Vector3()) : new Vector3(1, 1, 1); + const band = BAND * Math.max(size.x, size.y, size.z, 1e-6); + + const p = (i: number): [number, number, number] => [pos.getX(i), pos.getY(i), pos.getZ(i)]; + const normals = new Float32Array(tris * 3); + const area = new Float32Array(tris); + for (let t = 0; t < tris; t++) { + const a = p(t * 3), b = p(t * 3 + 1), c = p(t * 3 + 2); + const ux = b[0] - a[0], uy = b[1] - a[1], uz = b[2] - a[2], vx = c[0] - a[0], vy = c[1] - a[1], vz = c[2] - a[2]; + const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx; + const l = Math.hypot(nx, ny, nz) || 1; + normals[t * 3] = nx / l; normals[t * 3 + 1] = ny / l; normals[t * 3 + 2] = nz / l; + area[t] = l / 2; + } + // Which triangle lies across each edge: edges keyed by their two end points (to a fine grid), the same key from either side. + const q = (v: [number, number, number]): string => `${Math.round(v[0] * 1e4)},${Math.round(v[1] * 1e4)},${Math.round(v[2] * 1e4)}`; + const across = new Map(); + const edgeKey = (a: [number, number, number], b: [number, number, number]): string => { const ka = q(a), kb = q(b); return ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`; }; + for (let t = 0; t < tris; t++) { + const v = [p(t * 3), p(t * 3 + 1), p(t * 3 + 2)] as const; + for (let e = 0; e < 3; e++) { + const k = edgeKey(v[(e + 1) % 3]!, v[(e + 2) % 3]!); + const list = across.get(k); + if (list) list.push(t); else across.set(k, [t]); + } + } + const cos = Math.cos((MIN_ANGLE * Math.PI) / 180); + const bary = new Float32Array(pos.count * 3), alt = new Float32Array(pos.count * 4); + const nb: Float32Array[] = [new Float32Array(pos.count * 3), new Float32Array(pos.count * 3), new Float32Array(pos.count * 3)]; + let any = false; + for (let t = 0; t < tris; t++) { + const v = [p(t * 3), p(t * 3 + 1), p(t * 3 + 2)] as const; + const own = [normals[t * 3]!, normals[t * 3 + 1]!, normals[t * 3 + 2]!]; + for (let e = 0; e < 3; e++) { + // The edge opposite corner e, and the altitude of that corner over it. + const a = v[(e + 1) % 3]!, b = v[(e + 2) % 3]!; + const len = Math.hypot(b[0] - a[0], b[1] - a[1], b[2] - a[2]) || 1; + const height = (2 * area[t]!) / len; + const others = (across.get(edgeKey(a, b)) ?? []).filter((o) => o !== t); + let n: number[] | undefined; + // Only an edge shared with one other face is a crease of the surface; where several meet, or none, the shading is left alone. + if (others.length === 1) { + const o = others[0]!; + const m = [normals[o * 3]!, normals[o * 3 + 1]!, normals[o * 3 + 2]!]; + if (own[0]! * m[0]! + own[1]! * m[1]! + own[2]! * m[2]! < cos) { n = m; any = true; } + } + for (let k = 0; k < 3; k++) { + const i = t * 3 + k; + alt[i * 4 + e] = height; + nb[e]![i * 3] = n ? n[0]! : 0; nb[e]![i * 3 + 1] = n ? n[1]! : 0; nb[e]![i * 3 + 2] = n ? n[2]! : 0; + } + } + for (let k = 0; k < 3; k++) { + const i = t * 3 + k; + bary[i * 3 + k] = 1; + alt[i * 4 + 3] = band; + } + } + if (!any) return undefined; + geo.setAttribute('edgeBary', new BufferAttribute(bary, 3)); + geo.setAttribute('edgeAlt', new BufferAttribute(alt, 4)); + geo.setAttribute('edgeNb0', new BufferAttribute(nb[0]!, 3)); + geo.setAttribute('edgeNb1', new BufferAttribute(nb[1]!, 3)); + geo.setAttribute('edgeNb2', new BufferAttribute(nb[2]!, 3)); + return geo; +} + +/** Makes a surface read the attributes above (a surface on a geometry without them must not be given this). */ +export function applyEdgeSoften(material: MeshPhysicalMaterial): void { + 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 edgeBary;\nattribute vec4 edgeAlt;\nattribute vec3 edgeNb0;\nattribute vec3 edgeNb1;\nattribute vec3 edgeNb2; +varying vec3 vEdgeBary;\nvarying vec4 vEdgeAlt;\nvarying vec3 vEdgeN0;\nvarying vec3 vEdgeN1;\nvarying vec3 vEdgeN2;\nvoid main() { + vEdgeBary = edgeBary; vEdgeAlt = edgeAlt; + // (a zero neighbour means no crease on that side; normalising a zero vector would be NaN, so it stays zero) + vEdgeN0 = normalMatrix * edgeNb0; vEdgeN1 = normalMatrix * edgeNb1; vEdgeN2 = normalMatrix * edgeNb2;`); + shader.fragmentShader = shader.fragmentShader + .replace('void main() {', 'varying vec3 vEdgeBary;\nvarying vec4 vEdgeAlt;\nvarying vec3 vEdgeN0;\nvarying vec3 vEdgeN1;\nvarying vec3 vEdgeN2;\nvoid main() {') + .replace('#include ', `#include + { + float edgeW = max(vEdgeAlt.w, 1e-6); + vec3 edgeAdd = vec3(0.0); + float t0 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.x * vEdgeAlt.x); + float t1 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.y * vEdgeAlt.y); + float t2 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.z * vEdgeAlt.z); + edgeAdd += (t0 * t0 * vEdgeN0 + t1 * t1 * vEdgeN1 + t2 * t2 * vEdgeN2) * 1.2; + if (dot(edgeAdd, edgeAdd) > 0.0) normal = normalize(normal + edgeAdd); + // the thin light line a small fillet shows along its length + float rim = max(t0 * t0, max(t1 * t1, t2 * t2)) * step(0.0001, dot(edgeAdd, edgeAdd)); + diffuseColor.rgb *= 1.0 + 0.22 * rim; + roughnessFactor = max(0.05, roughnessFactor - 0.12 * rim); + }`); + }; + material.customProgramCacheKey = () => `${previousKey}|edge-soften-v3`; +} diff --git a/src/overlay/materials.ts b/src/overlay/materials.ts index e610602..a406571 100644 --- a/src/overlay/materials.ts +++ b/src/overlay/materials.ts @@ -5,6 +5,7 @@ import { Color, DoubleSide, MeshPhysicalMaterial } from 'three'; import type { Material } from 'three'; import type { SurfaceFinish } from '../scene/types.ts'; +import { applyMicroSurface } from './surface-micro.ts'; import { fitTint } from '../scene/material-library.ts'; import type { MaterialName } from '../scene/material-library.ts'; import type { Rgb } from './timeline.ts'; @@ -23,12 +24,16 @@ export type TierSettings = { maxPixelRatio: number; /** Clear coat on glossy surfaces. */ clearcoat: boolean; + /** The finest surface (surface-micro.ts): 0 none, 1 a variation of roughness, 2 that and a fine bump. */ + micro: 0 | 1 | 2; + /** A circuit board's own surface: 0 plain, 1 traces and pads, 2 with silkscreen. */ + board: 0 | 1 | 2; }; export const TIERS: Record = { - low: { msaa: false, shadows: false, shadowMapSize: 512, edges: false, maxPixelRatio: 1, clearcoat: false }, - mid: { msaa: true, shadows: true, shadowMapSize: 1024, edges: true, maxPixelRatio: 1.5, clearcoat: true }, - high: { msaa: true, shadows: true, shadowMapSize: 2048, edges: true, maxPixelRatio: 2, clearcoat: true }, + low: { msaa: false, shadows: false, shadowMapSize: 512, edges: false, maxPixelRatio: 1, clearcoat: false, micro: 0, board: 1 }, + mid: { msaa: true, shadows: true, shadowMapSize: 1024, edges: true, maxPixelRatio: 1.5, clearcoat: true, micro: 1, board: 2 }, + high: { msaa: true, shadows: true, shadowMapSize: 2048, edges: true, maxPixelRatio: 2, clearcoat: true, micro: 2, board: 2 }, }; /** The surfaces a scene can name, and two the parts kit uses inside itself: painted metal and rough cast metal. */ @@ -40,37 +45,41 @@ type Recipe = { opacity?: number; envMapIntensity?: number; emissive?: number; doubleSided?: boolean; /** A soft light along the edges that turn from the viewer (cloth, skin, tissue). */ sheen?: number; + /** The finest surface: how far roughness swings, how many cycles to a unit, and the strength of the fine bump. */ + micro?: { rough: number; grain: number; bump: number }; + /** The surface is a circuit board's (solder mask, traces, pads, silkscreen). */ + board?: boolean; }; const RECIPES: Record = { - plastic: { roughness: 0.46, metalness: 0, clearcoat: 0.3, clearcoatRoughness: 0.4 }, - metal: { roughness: 0.3, metalness: 1, envMapIntensity: 1.1 }, - rubber: { roughness: 0.92, metalness: 0 }, - pcb: { roughness: 0.52, metalness: 0, clearcoat: 0.55, clearcoatRoughness: 0.3 }, + plastic: { roughness: 0.4, metalness: 0, clearcoat: 0.12, clearcoatRoughness: 0.35, micro: { rough: 0.14, grain: 26, bump: 0.5 } }, + metal: { roughness: 0.32, metalness: 1, envMapIntensity: 1.1, micro: { rough: 0.1, grain: 70, bump: 0.3 } }, + rubber: { roughness: 0.88, metalness: 0, micro: { rough: 0.1, grain: 34, bump: 0.9 } }, + pcb: { roughness: 0.38, metalness: 0, clearcoat: 0.25, clearcoatRoughness: 0.3, micro: { rough: 0.1, grain: 30, bump: 0.3 }, board: true }, glass: { roughness: 0.04, metalness: 0, clearcoat: 1, clearcoatRoughness: 0.04, opacity: 0.34, envMapIntensity: 1.5, doubleSided: true }, glow: { roughness: 0.6, metalness: 0, emissive: 1.25 }, // A marker that travels along a pipe: a little self-light so it stays bright, but shaded and glossy so it reads as a bead on a pale or see-through tube. bead: { roughness: 0.3, metalness: 0, clearcoat: 0.8, clearcoatRoughness: 0.1, emissive: 0.4 }, 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 }, + tissue: { roughness: 0.62, metalness: 0, clearcoat: 0.45, clearcoatRoughness: 0.55, sheen: 0.8, micro: { rough: 0.07, grain: 12, bump: 0.15 } }, // 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 }, + bone: { roughness: 0.58, metalness: 0, clearcoat: 0.12, clearcoatRoughness: 0.55, micro: { rough: 0.07, grain: 12, bump: 0.15 } }, + muscle: { roughness: 0.55, metalness: 0, clearcoat: 0.35, clearcoatRoughness: 0.45, sheen: 0.5, micro: { rough: 0.07, grain: 12, bump: 0.15 } }, 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 }, + skin: { roughness: 0.6, metalness: 0, clearcoat: 0.18, clearcoatRoughness: 0.6, sheen: 0.7, micro: { rough: 0.07, grain: 12, bump: 0.15 } }, // 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 }, + steel: { roughness: 0.3, metalness: 1, envMapIntensity: 1.1, micro: { rough: 0.1, grain: 70, bump: 0.3 } }, + iron: { roughness: 0.5, metalness: 0.92, envMapIntensity: 0.95, micro: { rough: 0.16, grain: 36, bump: 0.8 } }, + brass: { roughness: 0.28, metalness: 1, envMapIntensity: 1.1, micro: { rough: 0.1, grain: 66, bump: 0.25 } }, + copper: { roughness: 0.3, metalness: 1, envMapIntensity: 1.1, micro: { rough: 0.1, grain: 66, bump: 0.25 } }, + wood: { roughness: 0.75, metalness: 0, clearcoat: 0.12, clearcoatRoughness: 0.7, micro: { rough: 0.14, grain: 22, bump: 0.6 } }, 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 }, + enamel: { roughness: 0.34, metalness: 0.55, clearcoat: 1, clearcoatRoughness: 0.12, envMapIntensity: 1.1, micro: { rough: 0.06, grain: 30, bump: 0.2 } }, // Sand-cast metal: rough and even, with no mirror in it. - cast: { roughness: 0.42, metalness: 1, envMapIntensity: 1.05 }, + cast: { roughness: 0.46, metalness: 1, envMapIntensity: 1.05, micro: { rough: 0.18, grain: 30, bump: 0.9 } }, // The flat cut face of a part drawn already cut open (hatched, see `hatched`). section: { roughness: 0.7, metalness: 0.1 }, }; @@ -94,6 +103,9 @@ export function makeSurface(name: string | undefined, tier: TierSettings, finish m.opacity = m.userData.base; m.depthWrite = !m.transparent; if (name === 'section') hatched(m); + else if ((tier.micro > 0 && r.micro) || (tier.board > 0 && r.board)) { + if ((r.opacity ?? 1) >= 1 && !r.emissive) applyMicroSurface(m, { rough: tier.micro > 0 && r.micro ? r.micro.rough : 0, grain: r.micro?.grain ?? 30, bump: tier.micro > 1 && r.micro ? r.micro.bump : 0, board: r.board ? tier.board : 0 }); + } return m; } diff --git a/src/overlay/overlay.ts b/src/overlay/overlay.ts index 98fa26a..e169981 100644 --- a/src/overlay/overlay.ts +++ b/src/overlay/overlay.ts @@ -4,7 +4,7 @@ // Everything is data-driven by validated scenes (see src/scene). import { NeutralToneMapping, PMREMGenerator, SRGBColorSpace, VSMShadowMap, WebGLRenderer } from 'three'; -import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js'; +import { StudioEnvironment } from './studio.ts'; import { FADE_AFTER_MS } from '../shared/ipc.ts'; import type { DisplayInfo, SceneMessage } from '../shared/ipc.ts'; import type { Action, Mark, Scene } from '../scene/types.ts'; @@ -147,9 +147,9 @@ function createRenderer(): WebGLRenderer | undefined { candidate.shadowMap.enabled = settings.shadows; candidate.shadowMap.type = VSMShadowMap; const pmrem = new PMREMGenerator(candidate); - const room = new RoomEnvironment(); + const room = new StudioEnvironment(); try { - panelScene.setEnvironment(pmrem.fromScene(room, 0.04).texture, 0.8); + panelScene.setEnvironment(pmrem.fromScene(room, 0.04).texture, 1.0); } finally { room.dispose(); pmrem.dispose(); @@ -165,15 +165,15 @@ function createRenderer(): WebGLRenderer | undefined { } const renderer = createRenderer(); -/** The high tier's occlusion and smoothing; absent on the others, and if the graphics stack will not run it. */ +/** The occlusion (and, on the high tier, the smoothing): full on high, lighter on mid, absent on low, and if the graphics stack will not run it. */ let finishing: Finishing | undefined; -if (renderer && tier === 'high') { +if (renderer && tier !== 'low') { try { - finishing = new Finishing(renderer, panelScene.scene, panelScene.camera); - console.info('talkthrough: high tier finishing pass on'); + finishing = new Finishing(renderer, panelScene.scene, panelScene.camera, tier === 'high' ? 'full' : 'light'); + console.info(`talkthrough: ${tier} tier finishing pass on`); } catch { finishing = undefined; // the plain render is the fallback - console.info('talkthrough: high tier finishing pass unavailable, drawing plainly'); + console.info(`talkthrough: ${tier} tier finishing pass unavailable, drawing plainly`); } } diff --git a/src/overlay/post.ts b/src/overlay/post.ts index 4f76d02..933bd1d 100644 --- a/src/overlay/post.ts +++ b/src/overlay/post.ts @@ -15,6 +15,9 @@ import { GTAOPass } from 'three/examples/jsm/postprocessing/GTAOPass.js'; import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js'; import { SMAAPass } from 'three/examples/jsm/postprocessing/SMAAPass.js'; +/** How much the finishing does: the high tier does all of it, the mid tier a lighter occlusion (half resolution, fewer samples, two-sample target) with no smoothing pass. */ +export type FinishingLevel = 'light' | 'full'; + /** A rectangle in CSS pixels, from the top left of the display. */ export type PixelRect = { x: number; y: number; w: number; h: number }; @@ -33,6 +36,7 @@ export class Finishing { private height = 0; private renderer: WebGLRenderer; private depth: DepthTexture; + private level: FinishingLevel; /** Whether this graphics stack can render to half-float targets (without that the first draw would fail). */ static supported(renderer: WebGLRenderer): boolean { @@ -40,18 +44,19 @@ export class Finishing { return ext.has('EXT_color_buffer_float') || ext.has('EXT_color_buffer_half_float'); } - constructor(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera) { + constructor(renderer: WebGLRenderer, scene: Scene, camera: PerspectiveCamera, level: FinishingLevel = 'full') { if (!Finishing.supported(renderer)) throw new Error('no half-float render targets'); this.renderer = renderer; + this.level = level; this.depth = new DepthTexture(1, 1); this.depth.format = DepthStencilFormat; this.depth.type = UnsignedInt248Type; // The stencil is kept: a cut model's caps (cutaway.ts) are drawn with it. - this.beauty = new WebGLRenderTarget(1, 1, { type: HalfFloatType, samples: 4, depthBuffer: true, stencilBuffer: true, depthTexture: this.depth }); + this.beauty = new WebGLRenderTarget(1, 1, { type: HalfFloatType, samples: level === 'full' ? 4 : 2, depthBuffer: true, stencilBuffer: true, depthTexture: this.depth }); this.occluded = new WebGLRenderTarget(1, 1, { type: HalfFloatType, depthBuffer: false }); this.toned = new WebGLRenderTarget(1, 1, { type: UnsignedByteType, depthBuffer: false }); this.gtao = new GTAOPass(scene, camera, 1, 1, { depthTexture: this.depth }); - this.gtao.updateGtaoMaterial({ radius: 1.2, distanceExponent: 1.2, thickness: 2, scale: 1.4, samples: 16, distanceFallOff: 1, screenSpaceRadius: false }); + this.gtao.updateGtaoMaterial({ radius: level === 'full' ? 1.3 : 1.1, distanceExponent: 1.2, thickness: 2, scale: level === 'full' ? 2.4 : 2.0, samples: level === 'full' ? 16 : 8, distanceFallOff: 1, screenSpaceRadius: false }); this.gtao.blendIntensity = 0.9; // The colour in the target is premultiplied by its alpha: take that out before toning and put it back after. const material = this.output.material; @@ -61,7 +66,8 @@ export class Finishing { material.fragmentShader = material.fragmentShader .replace('gl_FragColor = texture2D( tDiffuse, vUv );', 'gl_FragColor = texture2D( tDiffuse, vUv );\n\t\t\tfloat coverage = gl_FragColor.a;\n\t\t\tgl_FragColor.rgb /= max(coverage, 0.0001);') .replace(/}\s*$/, '\tgl_FragColor.rgb *= coverage;\n\t\t}'); - this.smaa.renderToScreen = true; + this.smaa.renderToScreen = level === 'full'; + this.output.renderToScreen = level !== 'full'; } /** Whether a model drawn in this rectangle is finished here (it is not when the targets would be very large). */ @@ -79,7 +85,9 @@ export class Finishing { this.beauty.setSize(dw, dh); this.occluded.setSize(dw, dh); this.toned.setSize(dw, dh); - this.gtao.setSize(dw, dh); + // The light level works the occlusion out at half the resolution: it is soft by nature, and the depth it reads stays full size. + if (this.level === 'full') this.gtao.setSize(dw, dh); + else this.gtao.setSize(Math.max(1, dw >> 1), Math.max(1, dh >> 1)); this.smaa.setSize(dw, dh); } @@ -103,6 +111,17 @@ export class Finishing { r.clear(); r.render(scene, camera); this.gtao.render(r, this.occluded, this.beauty, 0, false); + if (this.level !== 'full') { + // Back to the canvas first: the output pass draws straight to it, with no smoothing pass after. + if (view) camera.setViewOffset(view.fullWidth, view.fullHeight, view.offsetX, view.offsetY, view.width, view.height); + else camera.clearViewOffset(); + r.setRenderTarget(null); + r.setViewport(rect.x, display.height - rect.y - h, w, h); + r.setScissorTest(scissor); + this.output.render(r, null as unknown as WebGLRenderTarget, this.occluded, 0, false); + r.setViewport(viewport); + return; + } this.output.render(r, this.toned, this.occluded, 0, false); // Back to the canvas, where the window of the display this stands for is. if (view) camera.setViewOffset(view.fullWidth, view.fullHeight, view.offsetX, view.offsetY, view.width, view.height); diff --git a/src/overlay/scene3d.ts b/src/overlay/scene3d.ts index 984bca3..919bf9a 100644 --- a/src/overlay/scene3d.ts +++ b/src/overlay/scene3d.ts @@ -20,6 +20,7 @@ import { sweepGeometry, sweepEdges } from './sweep.ts'; import { shellGeometry, shellEdges } from './shell.ts'; import { BLOB_MIN_TRIANGLES, blobGeometry } from './blob.ts'; import { buildHullGeometry } from './hull.ts'; +import { applyEdgeSoften, softenEdges } from './edge-soften.ts'; import { loftEdges, loftGeometry } from './loft.ts'; import { DETAIL, boxGeometry, defaultBevel, drawFraction, extrudeGeometry, latheGeometry, pointAlong, roundedCylinderGeometry, samplePath, shadeByHeight, tubeGeometry } from './geometry.ts'; import type { Detail } from './geometry.ts'; @@ -250,6 +251,7 @@ export class PanelScene { } if (def.shape === 'patch') { surface.side = DoubleSide; surface.forceSinglePass = true; } if (geo.getAttribute('color')) surface.vertexColors = true; + if (geo.getAttribute('edgeBary')) applyEdgeSoften(surface); const mesh = new Mesh(geo, surface); mesh.castShadow = settings.shadows; mesh.receiveShadow = settings.shadows; @@ -267,7 +269,7 @@ export class PanelScene { case 'group': case 'array': case 'field': break; case 'hull': { const result = buildHullGeometry(def.pts); - if (result.ok) node.obj = addMesh(result.geometry, material, def.edges !== false); + if (result.ok) node.obj = addMesh(softenEdges(result.geometry) ?? result.geometry, material, def.edges !== false); else console.warn(`talkthrough: hull ${o.id} could not be built: ${result.message}`); break; } @@ -399,7 +401,10 @@ export class PanelScene { case 'patch': return patchGeometry(def.pts, PATCH_SEGMENTS[this.tier]); case 'extrude': { const e = def as { outline: Array<[number, number]>; depth: number; bevel?: number; holes?: Array>; taper?: number; shift?: [number, number] }; - if (e.taper != null || e.shift != null) return taperedExtrudeGeometry(e.outline, e.depth, e.taper ?? 1, e.shift ?? [0, 0]); + if (e.taper != null || e.shift != null) { + const tapered = taperedExtrudeGeometry(e.outline, e.depth, e.taper ?? 1, e.shift ?? [0, 0]); + return softenEdges(tapered) ?? tapered; + } return extrudeGeometry(e.outline, e.depth, e.bevel ?? Math.min(0.1, e.depth * 0.2), d, e.holes); } case 'blob': { diff --git a/src/overlay/studio.ts b/src/overlay/studio.ts new file mode 100644 index 0000000..c6088fb --- /dev/null +++ b/src/overlay/studio.ts @@ -0,0 +1,75 @@ +// The lighting every surface is reflected in and lit by: a small photographic studio built in code (no image file, no licence, nothing to +// fetch). A soft gradient dome stands for the room, and rectangles brighter than anything on screen stand for softboxes, a strip light and an +// overhead panel. Pre-filtered once (PMREMGenerator.fromScene), it gives a metal curve a soft bright band with a darker gap beside it and a +// glossy plastic a clean window highlight, which a plain room of evenly lit walls cannot: the reflections are what make a surface read as made of +// something. Brightness is in linear values above one (the target is half-float); the renderer's tone mapping brings them back. + +import { BackSide, Color, DoubleSide, Float32BufferAttribute, Mesh, MeshBasicMaterial, PlaneGeometry, Scene, SphereGeometry, Vector3 } from 'three'; + +type Light = { + /** Where its middle is, in the studio's own units (the model sits at the origin, the camera looks along -z). */ + at: [number, number, number]; + /** Width and height of the lit rectangle. */ + size: [number, number]; + /** Linear colour; its brightest channel is the light's strength. */ + color: [number, number, number]; + /** Turn about its own long axis, in degrees (a strip light stands up or lies down). */ + roll?: number; +}; + +/** The studio's lamps: one large key to the upper left, a cooler fill on the right, a strip behind for a rim along an edge, a panel overhead, a low warm bounce. */ +export const STUDIO_LIGHTS: readonly Light[] = [ + { at: [-9, 8, 9], size: [9, 7], color: [7, 6.6, 6] }, + { at: [12, 3.5, 7], size: [8, 9], color: [1.6, 1.9, 2.3] }, + { at: [-3, 7, -13], size: [18, 1.6], color: [5, 5, 5] }, + { at: [-13, 2, -3], size: [1.4, 11], color: [3.2, 3.2, 3.4] }, + { at: [0, 17, 0], size: [14, 14], color: [1.2, 1.2, 1.25] }, + { at: [0, -9, 5], size: [18, 8], color: [0.5, 0.45, 0.4] }, +]; + +/** The dome's colours by height: a light cool sky above, a mid grey at the horizon, a dark warm floor below. */ +const DOME = { zenith: [0.85, 0.87, 0.9], horizon: [0.5, 0.5, 0.5], nadir: [0.14, 0.13, 0.12] } as const; + +export class StudioEnvironment extends Scene { + constructor() { + super(); + this.name = 'StudioEnvironment'; + + const dome = new SphereGeometry(40, 48, 24); + const pos = dome.getAttribute('position'); + const colours: number[] = []; + const c = new Color(); + for (let i = 0; i < pos.count; i++) { + const up = pos.getY(i) / 40; + const a = up >= 0 ? DOME.horizon : DOME.nadir; + const b = up >= 0 ? DOME.zenith : DOME.horizon; + const t = up >= 0 ? Math.pow(up, 0.7) : 1 - Math.pow(-up, 0.7); + c.setRGB(a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t); + colours.push(c.r, c.g, c.b); + } + dome.setAttribute('color', new Float32BufferAttribute(colours, 3)); + this.add(new Mesh(dome, new MeshBasicMaterial({ vertexColors: true, side: BackSide, toneMapped: false }))); + + const panel = new PlaneGeometry(1, 1); + for (const light of STUDIO_LIGHTS) { + const material = new MeshBasicMaterial({ color: new Color(light.color[0], light.color[1], light.color[2]), side: DoubleSide, toneMapped: false }); + const mesh = new Mesh(panel, material); + mesh.scale.set(light.size[0], light.size[1], 1); + mesh.position.set(...light.at); + mesh.lookAt(new Vector3(0, 0, 0)); + if (light.roll) mesh.rotateZ((light.roll * Math.PI) / 180); + this.add(mesh); + } + } + + /** Releases the geometry and materials once the environment has been filtered. */ + dispose(): void { + const seen = new Set(); + this.traverse((o) => { + const mesh = o as Mesh; + if (!mesh.isMesh) return; + if (!seen.has(mesh.geometry)) { seen.add(mesh.geometry); mesh.geometry.dispose(); } + (mesh.material as MeshBasicMaterial).dispose(); + }); + } +} diff --git a/src/overlay/surface-micro.ts b/src/overlay/surface-micro.ts new file mode 100644 index 0000000..25193dc --- /dev/null +++ b/src/overlay/surface-micro.ts @@ -0,0 +1,152 @@ +// The finest surface of a material, made in the shader from the object's own coordinates (no image, no UV, so it does not stretch with a part's size +// and costs no memory): a faint variation of roughness and a fine bump, which is what keeps a surface from looking computer-perfect (a machined +// metal catches the light unevenly, a moulded plastic has a grain), and, for a circuit board, the board itself: solder mask over copper traces, pads +// and silkscreen, drawn on the faces that look up and down. Each layer is a few arithmetic steps per pixel; a tier that does not ask for a layer +// compiles without it. + +import type { MeshPhysicalMaterial } from 'three'; + +export type MicroSurface = { + /** How far roughness swings about its recipe value (0 none, 0.3 a lot): the rest of the layer is one more number each. */ + rough: number; + /** Cycles of the variation to a unit of the object. */ + grain: number; + /** Strength of the fine bump (0 none). */ + bump: number; + /** 0 nothing, 1 traces and pads, 2 traces, pads and silkscreen. */ + board: 0 | 1 | 2; +}; + +const COMMON = ` +float microHash(vec3 p) { p = fract(p * 0.1031); p += dot(p, p.zyx + 31.32); return fract((p.x + p.y) * p.z); } +float microNoise(vec3 p) { + vec3 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f); + return mix(mix(mix(microHash(i), microHash(i + vec3(1,0,0)), f.x), mix(microHash(i + vec3(0,1,0)), microHash(i + vec3(1,1,0)), f.x), f.y), + mix(mix(microHash(i + vec3(0,0,1)), microHash(i + vec3(1,0,1)), f.x), mix(microHash(i + vec3(0,1,1)), microHash(i + vec3(1,1,1)), f.x), f.y), f.z); +} +float microHash2(vec2 p) { p = fract(p * vec2(123.34, 456.21)); p += dot(p, p + 45.32); return fract(p.x * p.y); } +`; + +/** + * A board seen from above: traces (runs of parallel lines in both directions with gaps, as routing leaves them), round pads with a hole, and + * silkscreen outlines and bars. The result: a covering amount for each of three layers, and the height used for the bump. + */ +const BOARD = ` +float boardLine(float across, float pitch, float width, float aa) { + float f = (fract(across / pitch) - 0.5) * pitch; + return 1.0 - smoothstep(width * 0.5 - aa, width * 0.5 + aa, abs(f)); +} +// One direction of routing: rows of pitch p, each cut into runs of random length, some missing. +float boardRuns(vec2 q, float pitch, float width, float run, float seed, float aa) { + float row = floor(q.y / pitch); + float len = run * (0.7 + 0.9 * microHash2(vec2(row, seed))); + float id = floor((q.x + len * microHash2(vec2(row, seed + 7.0))) / len); + float on = step(0.62, microHash2(vec2(row * 1.7 + seed, id))); + return on * boardLine(q.y, pitch, width, aa); +} +void boardLayers(vec2 q, float aa, out float trace, out float pad, out float hole, out float silk) { + trace = max(boardRuns(q, 0.1, 0.03, 1.1, 1.0, aa), boardRuns(q.yx + 0.31, 0.1, 0.03, 1.1, 5.0, aa)); + // pads on a coarse grid, one in four present + vec2 cell = q / 0.3; vec2 id = floor(cell); vec2 f = (fract(cell) - 0.5) * 0.3; + float has = step(0.86, microHash2(id + 3.1)); + float d = length(f); + pad = has * (1.0 - smoothstep(0.062 - aa, 0.062 + aa, d)); + hole = has * (1.0 - smoothstep(0.026 - aa, 0.026 + aa, d)); + // silkscreen: a thin outline of a part's footprint and a short bar, in cells where one lands + vec2 sc = q / 0.52; vec2 sid = floor(sc); vec2 sf = (fract(sc) - 0.5) * 0.52; + float r = microHash2(sid + 9.7); + float box = step(0.9, r) * (1.0 - smoothstep(0.006 - aa, 0.006 + aa, abs(max(abs(sf.x) - 0.17, abs(sf.y) - 0.09)))); + box *= step(max(abs(sf.x) - 0.17, abs(sf.y) - 0.09), 0.012); + float bar = step(0.95, r) * step(abs(sf.y + 0.2), 0.012) * step(abs(sf.x), 0.14 * (0.4 + microHash2(sid + 2.3))); + silk = max(box, bar); +} +`; + +export function applyMicroSurface(material: MeshPhysicalMaterial, o: MicroSurface): void { + if (o.rough <= 0 && o.bump <= 0 && o.board === 0) return; + const previous = material.onBeforeCompile; + const previousKey = material.customProgramCacheKey(); + const defines = [o.rough > 0 ? '#define MICRO_ROUGH' : '', o.bump > 0 ? '#define MICRO_BUMP' : '', o.board > 0 ? '#define MICRO_BOARD' : '', o.board > 1 ? '#define MICRO_SILK' : ''].join('\n'); + const grain = o.grain.toFixed(2), rough = o.rough.toFixed(3), bump = o.bump.toFixed(3); + material.onBeforeCompile = function (shader, renderer) { + previous.call(this, shader, renderer); + shader.vertexShader = shader.vertexShader + .replace('void main() {', 'varying vec3 vMicroP;\nvarying vec3 vMicroN;\nvoid main() {') + .replace('#include ', '#include \n vMicroP = position;\n vMicroN = normal;'); + shader.fragmentShader = shader.fragmentShader + .replace('void main() {', `${defines}\nvarying vec3 vMicroP;\nvarying vec3 vMicroN;\n${COMMON}\n#ifdef MICRO_BOARD\n${BOARD}\n#endif\nvoid main() { + float microRough = 1.0; + float microHeight = 0.0; + float boardMetal = 0.0; + float boardRough = -1.0; + float boardHeight = 0.0; +#ifdef MICRO_ROUGH + float mn = microNoise(vMicroP * ${grain}) * 0.65 + microNoise(vMicroP * ${grain} * 2.7) * 0.35; + // Out of reach of the pixels the variation fades to nothing (a surface seen from far has no grain, and aliasing would only crawl). + float microFoot = max(length(dFdx(vMicroP)), length(dFdy(vMicroP))); + microRough = 1.0 + ${rough} * (mn * 2.0 - 1.0) * (1.0 - smoothstep(0.2, 0.5, microFoot * ${grain} * 2.7)); +#endif +#ifdef MICRO_BUMP + { + float g2 = ${grain} * 2.2; + float fp = max(length(dFdx(vMicroP)), length(dFdy(vMicroP))); + microHeight = (microNoise(vMicroP * g2) - 0.5) * ${bump} * 0.03 / g2 * (1.0 - smoothstep(0.2, 0.5, fp * g2)); + } +#endif`) + .replace('#include ', `#include +#ifdef MICRO_BOARD + { + float up = abs(vMicroN.y); + if (up > 0.9) { + vec2 q = vMicroP.xz; + float aa = max(fwidth(q.x), fwidth(q.y)) * 0.7; + float trace, pad, hole, silk; + boardLayers(q, aa, trace, pad, hole, silk); + // copper under the mask shows as a lighter, glossier green; a pad is bare gold; the hole is dark; silkscreen is white paint + vec3 mask = diffuseColor.rgb; + mask *= mix(1.0, 1.28, trace); + boardHeight = trace * 0.5; + vec3 gold = vec3(0.78, 0.55, 0.18); + mask = mix(mask, gold, pad); + boardMetal = pad; + boardRough = mix(-1.0, 0.28, pad); + boardHeight = max(boardHeight, pad * 0.8); + mask = mix(mask, vec3(0.02), hole); + boardHeight *= 1.0 - hole; +#ifdef MICRO_SILK + mask = mix(mask, vec3(0.86, 0.88, 0.84), silk * (1.0 - pad)); + boardRough = mix(boardRough, 0.7, silk * (1.0 - pad)); + boardHeight = max(boardHeight, silk * 0.25 * (1.0 - pad)); +#endif + diffuseColor.rgb = mask; + float fade = 1.0 - smoothstep(0.5, 1.2, aa / 0.03); + boardMetal *= fade; + } + } +#endif`) + .replace('#include ', `#include + roughnessFactor = clamp(roughnessFactor * microRough, 0.03, 1.0); +#ifdef MICRO_BOARD + if (boardRough >= 0.0) roughnessFactor = boardRough; +#endif`) + .replace('#include ', `#include +#ifdef MICRO_BOARD + metalnessFactor = max(metalnessFactor, boardMetal); +#endif`) + .replace('#include ', `#include +#if defined(MICRO_BUMP) || defined(MICRO_BOARD) + { + float hgt = microHeight + boardHeight * 0.004; + vec2 dHdxy = vec2(dFdx(hgt), dFdy(hgt)); + vec3 q0 = dFdx(-vViewPosition.xyz); + vec3 q1 = dFdy(-vViewPosition.xyz); + vec3 R1 = cross(q1, normal); + vec3 R2 = cross(normal, q0); + float fDet = dot(q0, R1); + vec3 vGrad = sign(fDet) * (dHdxy.x * R1 + dHdxy.y * R2); + normal = normalize(abs(fDet) * normal - vGrad); + } +#endif`); + }; + material.customProgramCacheKey = () => `${previousKey}|micro-v1|${defines.replace(/\s+/g, '')}|${grain}|${rough}|${bump}`; +} diff --git a/test/overlay-realism.test.ts b/test/overlay-realism.test.ts new file mode 100644 index 0000000..2c69b64 --- /dev/null +++ b/test/overlay-realism.test.ts @@ -0,0 +1,98 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { BoxGeometry, BufferGeometry, Float32BufferAttribute, MeshPhysicalMaterial, PerspectiveCamera, Scene, SphereGeometry } from 'three'; +import type { WebGLRenderer } from 'three'; +import { TIERS, makeSurface } from '../src/overlay/materials.ts'; +import { StudioEnvironment, STUDIO_LIGHTS } from '../src/overlay/studio.ts'; +import { applyEdgeSoften, softenEdges, EDGE_ATTRIBUTES } from '../src/overlay/edge-soften.ts'; +import { Finishing } from '../src/overlay/post.ts'; +import { MATERIAL_NAMES } from '../src/scene/material-library.ts'; + +(globalThis as { Image?: unknown }).Image ??= class { set src(_v: string) {} addEventListener(): void {} }; + +const METALS = ['metal', 'steel', 'iron', 'brass', 'copper', 'cast']; +const fakeShader = () => ({ + vertexShader: 'void main() {\n#include \n}', + fragmentShader: 'void main() {\n#include \n#include \n#include \n#include \n}', +} as never); +const compiled = (m: MeshPhysicalMaterial): { vertexShader: string; fragmentShader: string } => { + const shader = fakeShader() as { vertexShader: string; fragmentShader: string }; + m.onBeforeCompile(shader as never, undefined as never); + return shader; +}; + +test('every material the library names has a real finish: metals are metal, everything else is not, roughness is never a mirror or chalk by accident', () => { + for (const name of MATERIAL_NAMES) { + const m = makeSurface(name, TIERS.high); + if (METALS.includes(name)) assert.ok(m.metalness >= 0.9, `${name} reads as metal`); + else assert.equal(m.metalness, 0, `${name} is not metal`); + assert.ok(m.roughness > 0 && m.roughness <= 1, `${name} roughness`); + } + assert.ok(makeSurface('steel', TIERS.high).roughness < makeSurface('iron', TIERS.high).roughness, 'polished steel is smoother than iron'); + assert.ok(makeSurface('rubber', TIERS.high).roughness > 0.8); +}); + +test('the fine surface is a tier choice: low keeps its shaders plain (but for the board), mid adds the grain, high adds the bump', () => { + assert.equal(makeSurface('steel', TIERS.low).customProgramCacheKey(), makeSurface('plastic', TIERS.low).customProgramCacheKey(), 'low compiles the stock shader'); + const mid = makeSurface('steel', TIERS.mid).customProgramCacheKey(); + const high = makeSurface('steel', TIERS.high).customProgramCacheKey(); + assert.match(mid, /MICRO_ROUGH/); + assert.doesNotMatch(mid, /MICRO_BUMP/); + assert.match(high, /MICRO_BUMP/); + const board = (t: typeof TIERS.low) => makeSurface('pcb', t).customProgramCacheKey(); + assert.match(board(TIERS.low), /MICRO_BOARD/); + assert.doesNotMatch(board(TIERS.low), /MICRO_SILK/); + assert.match(board(TIERS.mid), /MICRO_SILK/); + assert.doesNotMatch(makeSurface('glass', TIERS.high).customProgramCacheKey(), /MICRO/, 'see-through surfaces get no grain'); +}); + +test('the micro surface patches every stage it needs, and the board layers only the pcb gets', () => { + const s = compiled(makeSurface('pcb', TIERS.high)); + assert.match(s.vertexShader, /vMicroP = position/); + for (const part of ['boardLayers(q', 'metalnessFactor = max', 'roughnessFactor = clamp', 'normal = normalize(abs(fDet)']) assert.ok(s.fragmentShader.includes(part), part); + const plain = compiled(makeSurface('steel', TIERS.high)); + assert.ok(plain.fragmentShader.includes('void main()')); + assert.doesNotMatch(plain.fragmentShader.replace(/#ifdef MICRO_BOARD[\s\S]*?#endif/g, ''), /boardLayers\(q/); +}); + +test('the studio is built in code: lights brighter than the screen, a dome, nothing to fetch, and it can be freed', () => { + const room = new StudioEnvironment(); + assert.ok(room.children.length >= STUDIO_LIGHTS.length + 1); + assert.ok(STUDIO_LIGHTS.some((l) => Math.max(...l.color) > 4), 'a key light well above white'); + assert.ok(STUDIO_LIGHTS.every((l) => l.size[0] > 0 && l.size[1] > 0)); + room.dispose(); +}); + +test('softening edges: a crease gets its neighbour, a smooth ball gets nothing, and a side with no crease stays a zero vector (a zero would turn NaN if normalised)', () => { + const cube = softenEdges(new BoxGeometry(1, 1, 1)); + assert.ok(cube, 'a cube has creases'); + for (const name of EDGE_ATTRIBUTES) assert.ok(cube.getAttribute(name), name); + assert.equal(softenEdges(new SphereGeometry(1, 24, 16)), undefined, 'gentle bends are left to the normals'); + // A triangle fan whose only crease is one edge: the other two sides carry zeros. + const g = new BufferGeometry(); + g.setAttribute('position', new Float32BufferAttribute([0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1], 3)); + const hinged = softenEdges(g); + assert.ok(hinged); + const nb = ['edgeNb0', 'edgeNb1', 'edgeNb2'].map((n) => hinged.getAttribute(n)); + const zeros = nb.filter((a) => a.getX(0) === 0 && a.getY(0) === 0 && a.getZ(0) === 0).length; + assert.equal(zeros, 2); + const m = new MeshPhysicalMaterial(); + applyEdgeSoften(m); + const s = compiled(m); + assert.doesNotMatch(s.vertexShader, /normalize\(normalMatrix \* edgeNb/, 'a zero neighbour must not be normalised'); + assert.match(s.fragmentShader, /roughnessFactor = max\(0\.05/); +}); + +const stub = (): WebGLRenderer => ({ extensions: { has: (n: string) => n === 'EXT_color_buffer_half_float' }, getPixelRatio: () => 1 }) as unknown as WebGLRenderer; + +test('the mid tier finishes at half resolution and with fewer samples than the high tier', () => { + const light = new Finishing(stub(), new Scene(), new PerspectiveCamera(), 'light'); + const full = new Finishing(stub(), new Scene(), new PerspectiveCamera(), 'full'); + const size = (f: Finishing) => (f as unknown as { gtao: { width: number; height: number; samples?: number } }).gtao; + (light as unknown as { size(w: number, h: number): void }).size(800, 400); + (full as unknown as { size(w: number, h: number): void }).size(800, 400); + assert.equal(size(light).width, 400); + assert.equal(size(full).width, 800); + light.dispose(); + full.dispose(); +}); From 5e63d22b4bb38572be3ab416b1e21a80c6170efc Mon Sep 17 00:00:00 2001 From: ProjectIdris <227970220+ProjectIdris@users.noreply.github.com> Date: Sun, 8 Nov 2026 23:45:38 +1300 Subject: [PATCH 4/5] Realism review fixes: 16-sample mid occlusion at the original strength, one shared program per tier for the fine surface, a prewarm of the surfaces and finishing pass, board pattern scaled by board size, lighter crease rounding on polished metal Co-Authored-By: Claude Sonnet 5.5 --- scripts/overlay-frames.cjs | 5 +++- src/overlay/edge-soften.ts | 8 ++++--- src/overlay/materials.ts | 3 +++ src/overlay/overlay.ts | 41 +++++++++++++++++++++++++++++++++ src/overlay/post.ts | 4 ++-- src/overlay/scene3d.ts | 26 ++++++++++++++++++++- src/overlay/surface-micro.ts | 36 +++++++++++++++++++++-------- test/overlay-realism.test.ts | 44 +++++++++++++++++++++++++++++++++--- 8 files changed, 147 insertions(+), 20 deletions(-) diff --git a/scripts/overlay-frames.cjs b/scripts/overlay-frames.cjs index da54557..9e6b9c1 100644 --- a/scripts/overlay-frames.cjs +++ b/scripts/overlay-frames.cjs @@ -4,7 +4,7 @@ // npm run build // (run it as `env -u ELECTRON_RUN_AS_NODE` if your shell sets that) // npx electron scripts/overlay-frames.cjs --out --steps 0:0.5,1:2 \ -// [--size 1920x1080] [--dpr 1] [--hidden] [--backdrop ] [--controls ] [--after ] \n// [--tier low|mid|high] [--gpu yes] [--clean yes] [--metrics yes] [--hold ] +// [--size 1920x1080] [--dpr 1] [--hidden] [--backdrop ] [--controls ] [--after ] \n// [--tier low|mid|high] [--gpu yes] [--clean yes] [--metrics yes] [--hold ] [--idle ] // // --steps is a list of step:seconds pairs (seconds into that step; earlier steps are complete). // --dpr sets the display scale; offscreen windows always render at 1, so use --hidden (a hidden, non-offscreen window) for dpr other than 1. @@ -110,8 +110,10 @@ app.whenReady().then(async () => { const seek = async (scene, step, t, name) => { const mine = ++token; const done = new Promise((r) => pending.set(mine, r)); + const sentAt = Date.now(); win.webContents.send(CHANNEL.scene, { kind: 'seek', scene, step, t, token: mine, cameraFit: 'instant' }); await Promise.race([done, sleep(10000).then(() => { throw new Error('no frame painted for ' + name); })]); + console.log('paint', name, Date.now() - sentAt, 'ms'); // the first of a run is the cold one: shaders compile on it await sleep(120 + Number(args.hold || 0)); // --hold : wait longer so tags that glide or fade in real time have arrived const image = await capture(); const file = path.join(args.out, name + '.png'); @@ -280,6 +282,7 @@ app.whenReady().then(async () => { scene.steps = base.steps.concat(scene.steps); } const offset = base ? base.steps.length : 0; + if (args.idle) await sleep(Number(args.idle)); // --idle : leave the page alone this long before the first step (what the app has: the overlay is up well before anyone asks) for (const pair of args.steps.split(',')) { const [s, t] = pair.split(':').map(Number); await seek(scene, s + offset, t, `${label}-s${s}-t${String(t).replace('.', '_')}`); diff --git a/src/overlay/edge-soften.ts b/src/overlay/edge-soften.ts index 5032e99..aa51cdf 100644 --- a/src/overlay/edge-soften.ts +++ b/src/overlay/edge-soften.ts @@ -109,13 +109,15 @@ varying vec3 vEdgeBary;\nvarying vec4 vEdgeAlt;\nvarying vec3 vEdgeN0;\nvarying float t0 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.x * vEdgeAlt.x); float t1 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.y * vEdgeAlt.y); float t2 = 1.0 - smoothstep(0.0, edgeW, vEdgeBary.z * vEdgeAlt.z); - edgeAdd += (t0 * t0 * vEdgeN0 + t1 * t1 * vEdgeN1 + t2 * t2 * vEdgeN2) * 1.2; + // A bent normal on a mirror finish picks up whatever dark part of the room is there and draws a grey band: polished metal takes much less of it. + float soft = mix(1.0, 0.25, clamp(metalnessFactor, 0.0, 1.0)); + edgeAdd += (t0 * t0 * vEdgeN0 + t1 * t1 * vEdgeN1 + t2 * t2 * vEdgeN2) * 1.2 * soft; if (dot(edgeAdd, edgeAdd) > 0.0) normal = normalize(normal + edgeAdd); // the thin light line a small fillet shows along its length float rim = max(t0 * t0, max(t1 * t1, t2 * t2)) * step(0.0001, dot(edgeAdd, edgeAdd)); - diffuseColor.rgb *= 1.0 + 0.22 * rim; + diffuseColor.rgb *= 1.0 + 0.22 * rim * soft; roughnessFactor = max(0.05, roughnessFactor - 0.12 * rim); }`); }; - material.customProgramCacheKey = () => `${previousKey}|edge-soften-v3`; + material.customProgramCacheKey = () => `${previousKey}|edge-soften-v4`; } diff --git a/src/overlay/materials.ts b/src/overlay/materials.ts index a406571..8e08668 100644 --- a/src/overlay/materials.ts +++ b/src/overlay/materials.ts @@ -84,6 +84,9 @@ const RECIPES: Record = { section: { roughness: 0.7, metalness: 0.1 }, }; +/** Every surface the renderer has a recipe for (the library's materials and the kit's own). */ +export const SURFACE_NAMES = Object.keys(RECIPES) as SurfaceName[]; + export type Surface = MeshPhysicalMaterial & { userData: { base: number; glow: number; name?: string } }; export function makeSurface(name: string | undefined, tier: TierSettings, finish: SurfaceFinish = {}): Surface { diff --git a/src/overlay/overlay.ts b/src/overlay/overlay.ts index e169981..e14b5c8 100644 --- a/src/overlay/overlay.ts +++ b/src/overlay/overlay.ts @@ -363,6 +363,7 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { renderer.setViewport(0, 0, view.width, view.height); renderer.setScissor(r.x, view.height - r.y - r.h, r.w, r.h); renderer.setScissorTest(true); + modelFramesDrawn++; if (finishing?.fits(r)) { try { finishing.render(panelScene.scene, panelScene.camera, r, view); @@ -1733,5 +1734,45 @@ window.talkthrough.onScene((message) => { console.error('overlay: could not play the scene', error); } }); +/** + * The graphics card builds a shader program the first time something is drawn with it, which put most of a second on the first model of a run (the + * finishing pass's programs, and one per kind of surface). The overlay is up long before anyone asks, so they are built once now, out of sight: the + * surfaces' programs are started together and waited for without blocking the page, then a small window is drawn through the same path a model takes + * (which builds the finishing pass's own) and cleared; if an answer's model has been drawn by then there is nothing left to build and nothing is drawn. The solids are in the scene only while that is being started or drawn, never across a pause. + */ +let modelFramesDrawn = 0; +async function prewarm(): Promise { + if (!renderer) return; + const started = performance.now(); + const drawnBefore = modelFramesDrawn; + const group = panelScene.prewarmGroup(); + try { + panelScene.scene.add(group); + const built = renderer.compileAsync(panelScene.scene, panelScene.camera); + panelScene.scene.remove(group); + await built; + const programs = performance.now() - started; + // A model drawn in the meantime has built the finishing pass's programs itself, and the clearing below would wipe it off the canvas. + if (modelFramesDrawn !== drawnBefore) return; + const rect = { x: 0, y: 0, w: 64, h: 64 }; + panelScene.scene.add(group); + renderer.setViewport(0, 0, view.width, view.height); + renderer.setScissor(0, Math.max(0, view.height - rect.h), rect.w, rect.h); + renderer.setScissorTest(true); + if (finishing?.fits(rect)) finishing.render(panelScene.scene, panelScene.camera, rect, view); + else renderer.render(panelScene.scene, panelScene.camera); + console.info(`talkthrough: prewarm built the surfaces in ${Math.round(programs)} ms and the finishing in ${Math.round(performance.now() - started - programs)} ms`); + } catch (error) { + console.info('talkthrough: prewarm skipped', error); + } finally { + panelScene.scene.remove(group); + if (modelFramesDrawn === drawnBefore) { + renderer.setRenderTarget(null); + renderer.setScissorTest(false); + renderer.clear(); + } + } +} resize(); +void prewarm(); window.talkthrough.ready(); diff --git a/src/overlay/post.ts b/src/overlay/post.ts index 933bd1d..4612021 100644 --- a/src/overlay/post.ts +++ b/src/overlay/post.ts @@ -56,8 +56,8 @@ export class Finishing { this.occluded = new WebGLRenderTarget(1, 1, { type: HalfFloatType, depthBuffer: false }); this.toned = new WebGLRenderTarget(1, 1, { type: UnsignedByteType, depthBuffer: false }); this.gtao = new GTAOPass(scene, camera, 1, 1, { depthTexture: this.depth }); - this.gtao.updateGtaoMaterial({ radius: level === 'full' ? 1.3 : 1.1, distanceExponent: 1.2, thickness: 2, scale: level === 'full' ? 2.4 : 2.0, samples: level === 'full' ? 16 : 8, distanceFallOff: 1, screenSpaceRadius: false }); - this.gtao.blendIntensity = 0.9; + this.gtao.updateGtaoMaterial({ radius: level === 'full' ? 1.2 : 1.1, distanceExponent: 1.2, thickness: 2, scale: 1.4, samples: 16, distanceFallOff: 1, screenSpaceRadius: false }); + this.gtao.blendIntensity = 0.7; // The colour in the target is premultiplied by its alpha: take that out before toning and put it back after. const material = this.output.material; const start = 'gl_FragColor = texture2D( tDiffuse, vUv );'; diff --git a/src/overlay/scene3d.ts b/src/overlay/scene3d.ts index 919bf9a..503e587 100644 --- a/src/overlay/scene3d.ts +++ b/src/overlay/scene3d.ts @@ -21,11 +21,12 @@ import { shellGeometry, shellEdges } from './shell.ts'; import { BLOB_MIN_TRIANGLES, blobGeometry } from './blob.ts'; import { buildHullGeometry } from './hull.ts'; import { applyEdgeSoften, softenEdges } from './edge-soften.ts'; +import { fitBoardPattern } from './surface-micro.ts'; import { loftEdges, loftGeometry } from './loft.ts'; import { DETAIL, boxGeometry, defaultBevel, drawFraction, extrudeGeometry, latheGeometry, pointAlong, roundedCylinderGeometry, samplePath, shadeByHeight, tubeGeometry } from './geometry.ts'; import type { Detail } from './geometry.ts'; import { closedTubeGeometry } from './closed-tube.ts'; -import { TIERS, applySurface, makeSurface } from './materials.ts'; +import { SURFACE_NAMES, TIERS, applySurface, makeSurface } from './materials.ts'; import type { Surface, Tier } from './materials.ts'; import { buildPart } from './parts.ts'; import { TAG_HEIGHT_FACTOR, tagTextPx } from './theme.ts'; @@ -221,6 +222,28 @@ export class PanelScene { this.scene.add(this.camera); } + private warmSurfaces: Surface[] = []; + + /** + * One small solid in every surface this tier has, to be drawn once before any answer so the graphics card has built the programs the first model will + * use (a program is built on first use, which cost the first model most of a second). The surfaces are kept for good: a program is freed when the + * last surface using it is, and the first real model would then build it again. Not part of the model: the caller adds it, draws, and takes it out. + */ + prewarmGroup(): Group { + const settings = TIERS[this.tier]; + const group = new Group(); + if (this.warmSurfaces.length === 0) this.warmSurfaces = SURFACE_NAMES.map((name) => makeSurface(name, settings)); + const geometry = new SphereGeometry(0.5, 8, 6); + for (const surface of this.warmSurfaces) { + const mesh = new Mesh(geometry, surface); + mesh.castShadow = settings.shadows; + mesh.receiveShadow = settings.shadows; + mesh.frustumCulled = false; + group.add(mesh); + } + return group; + } + /** The environment the surfaces reflect and are lit by (from the renderer's pre-filtering). */ setEnvironment(texture: Texture | null, intensity = 1): void { this.scene.environment = texture; @@ -252,6 +275,7 @@ export class PanelScene { if (def.shape === 'patch') { surface.side = DoubleSide; surface.forceSinglePass = true; } if (geo.getAttribute('color')) surface.vertexColors = true; if (geo.getAttribute('edgeBary')) applyEdgeSoften(surface); + fitBoardPattern(surface, geo); const mesh = new Mesh(geo, surface); mesh.castShadow = settings.shadows; mesh.receiveShadow = settings.shadows; diff --git a/src/overlay/surface-micro.ts b/src/overlay/surface-micro.ts index 25193dc..9859c6f 100644 --- a/src/overlay/surface-micro.ts +++ b/src/overlay/surface-micro.ts @@ -4,7 +4,7 @@ // and silkscreen, drawn on the faces that look up and down. Each layer is a few arithmetic steps per pixel; a tier that does not ask for a layer // compiles without it. -import type { MeshPhysicalMaterial } from 'three'; +import type { BufferGeometry, MeshPhysicalMaterial } from 'three'; export type MicroSurface = { /** How far roughness swings about its recipe value (0 none, 0.3 a lot): the rest of the layer is one more number each. */ @@ -64,33 +64,37 @@ void boardLayers(vec2 q, float aa, out float trace, out float pad, out float hol export function applyMicroSurface(material: MeshPhysicalMaterial, o: MicroSurface): void { if (o.rough <= 0 && o.bump <= 0 && o.board === 0) return; + const unit = { value: 1 }; + material.userData.boardUnit = unit; const previous = material.onBeforeCompile; const previousKey = material.customProgramCacheKey(); const defines = [o.rough > 0 ? '#define MICRO_ROUGH' : '', o.bump > 0 ? '#define MICRO_BUMP' : '', o.board > 0 ? '#define MICRO_BOARD' : '', o.board > 1 ? '#define MICRO_SILK' : ''].join('\n'); - const grain = o.grain.toFixed(2), rough = o.rough.toFixed(3), bump = o.bump.toFixed(3); + // The numbers go in as uniforms, not into the program: every material of a tier then shares one program (steel, iron, brass and cast differ only in three floats). + const own = { microGrain: { value: o.grain }, microRoughAmt: { value: o.rough }, microBumpAmt: { value: o.bump }, boardUnit: unit }; material.onBeforeCompile = function (shader, renderer) { previous.call(this, shader, renderer); + Object.assign(shader.uniforms, own); shader.vertexShader = shader.vertexShader .replace('void main() {', 'varying vec3 vMicroP;\nvarying vec3 vMicroN;\nvoid main() {') .replace('#include ', '#include \n vMicroP = position;\n vMicroN = normal;'); shader.fragmentShader = shader.fragmentShader - .replace('void main() {', `${defines}\nvarying vec3 vMicroP;\nvarying vec3 vMicroN;\n${COMMON}\n#ifdef MICRO_BOARD\n${BOARD}\n#endif\nvoid main() { + .replace('void main() {', `${defines}\nuniform float microGrain;\nuniform float microRoughAmt;\nuniform float microBumpAmt;\nuniform float boardUnit;\nvarying vec3 vMicroP;\nvarying vec3 vMicroN;\n${COMMON}\n#ifdef MICRO_BOARD\n${BOARD}\n#endif\nvoid main() { float microRough = 1.0; float microHeight = 0.0; float boardMetal = 0.0; float boardRough = -1.0; float boardHeight = 0.0; #ifdef MICRO_ROUGH - float mn = microNoise(vMicroP * ${grain}) * 0.65 + microNoise(vMicroP * ${grain} * 2.7) * 0.35; + float mn = microNoise(vMicroP * microGrain) * 0.65 + microNoise(vMicroP * microGrain * 2.7) * 0.35; // Out of reach of the pixels the variation fades to nothing (a surface seen from far has no grain, and aliasing would only crawl). float microFoot = max(length(dFdx(vMicroP)), length(dFdy(vMicroP))); - microRough = 1.0 + ${rough} * (mn * 2.0 - 1.0) * (1.0 - smoothstep(0.2, 0.5, microFoot * ${grain} * 2.7)); + microRough = 1.0 + microRoughAmt * (mn * 2.0 - 1.0) * (1.0 - smoothstep(0.2, 0.5, microFoot * microGrain * 2.7)); #endif #ifdef MICRO_BUMP { - float g2 = ${grain} * 2.2; + float g2 = microGrain * 2.2; float fp = max(length(dFdx(vMicroP)), length(dFdy(vMicroP))); - microHeight = (microNoise(vMicroP * g2) - 0.5) * ${bump} * 0.03 / g2 * (1.0 - smoothstep(0.2, 0.5, fp * g2)); + microHeight = (microNoise(vMicroP * g2) - 0.5) * microBumpAmt * 0.03 / g2 * (1.0 - smoothstep(0.2, 0.5, fp * g2)); } #endif`) .replace('#include ', `#include @@ -98,7 +102,7 @@ export function applyMicroSurface(material: MeshPhysicalMaterial, o: MicroSurfac { float up = abs(vMicroN.y); if (up > 0.9) { - vec2 q = vMicroP.xz; + vec2 q = vMicroP.xz / boardUnit; float aa = max(fwidth(q.x), fwidth(q.y)) * 0.7; float trace, pad, hole, silk; boardLayers(q, aa, trace, pad, hole, silk); @@ -136,7 +140,7 @@ export function applyMicroSurface(material: MeshPhysicalMaterial, o: MicroSurfac .replace('#include ', `#include #if defined(MICRO_BUMP) || defined(MICRO_BOARD) { - float hgt = microHeight + boardHeight * 0.004; + float hgt = microHeight + boardHeight * 0.004 * boardUnit; vec2 dHdxy = vec2(dFdx(hgt), dFdy(hgt)); vec3 q0 = dFdx(-vViewPosition.xyz); vec3 q1 = dFdy(-vViewPosition.xyz); @@ -148,5 +152,17 @@ export function applyMicroSurface(material: MeshPhysicalMaterial, o: MicroSurfac } #endif`); }; - material.customProgramCacheKey = () => `${previousKey}|micro-v1|${defines.replace(/\s+/g, '')}|${grain}|${rough}|${bump}`; + material.customProgramCacheKey = () => `${previousKey}|micro-v2|${defines.replace(/\s+/g, '')}`; +} + +/** The pattern of a board is drawn for a board about 6 by 4; this sets its scale from the geometry so a board written at any size carries the same detail. */ +export function fitBoardPattern(material: MeshPhysicalMaterial, geometry: BufferGeometry): void { + const unit = material.userData.boardUnit as { value: number } | undefined; + if (!unit) return; + geometry.computeBoundingBox(); + const box = geometry.boundingBox; + if (!box) return; + const w = box.max.x - box.min.x, d = box.max.z - box.min.z; + if (!(w > 0 && d > 0)) return; + unit.value = Math.min(100, Math.max(0.01, Math.sqrt(w * d) / Math.sqrt(24))); } diff --git a/test/overlay-realism.test.ts b/test/overlay-realism.test.ts index 2c69b64..9be511e 100644 --- a/test/overlay-realism.test.ts +++ b/test/overlay-realism.test.ts @@ -2,8 +2,10 @@ import test from 'node:test'; import assert from 'node:assert/strict'; import { BoxGeometry, BufferGeometry, Float32BufferAttribute, MeshPhysicalMaterial, PerspectiveCamera, Scene, SphereGeometry } from 'three'; import type { WebGLRenderer } from 'three'; -import { TIERS, makeSurface } from '../src/overlay/materials.ts'; +import { SURFACE_NAMES, TIERS, makeSurface } from '../src/overlay/materials.ts'; +import { PanelScene } from '../src/overlay/scene3d.ts'; import { StudioEnvironment, STUDIO_LIGHTS } from '../src/overlay/studio.ts'; +import { fitBoardPattern } from '../src/overlay/surface-micro.ts'; import { applyEdgeSoften, softenEdges, EDGE_ATTRIBUTES } from '../src/overlay/edge-soften.ts'; import { Finishing } from '../src/overlay/post.ts'; import { MATERIAL_NAMES } from '../src/scene/material-library.ts'; @@ -12,11 +14,12 @@ import { MATERIAL_NAMES } from '../src/scene/material-library.ts'; const METALS = ['metal', 'steel', 'iron', 'brass', 'copper', 'cast']; const fakeShader = () => ({ + uniforms: {}, vertexShader: 'void main() {\n#include \n}', fragmentShader: 'void main() {\n#include \n#include \n#include \n#include \n}', } as never); -const compiled = (m: MeshPhysicalMaterial): { vertexShader: string; fragmentShader: string } => { - const shader = fakeShader() as { vertexShader: string; fragmentShader: string }; +const compiled = (m: MeshPhysicalMaterial): { vertexShader: string; fragmentShader: string; uniforms: Record } => { + const shader = fakeShader() as { vertexShader: string; fragmentShader: string; uniforms: Record }; m.onBeforeCompile(shader as never, undefined as never); return shader; }; @@ -96,3 +99,38 @@ test('the mid tier finishes at half resolution and with fewer samples than the h light.dispose(); full.dispose(); }); + +test('the fine surface of every metal shares one program and differs only in its uniforms, so a tier compiles it once', () => { + const keys = new Set(['steel', 'metal', 'iron', 'brass', 'copper', 'cast'].map((n) => makeSurface(n, TIERS.high).customProgramCacheKey())); + assert.equal(keys.size, 1, [...keys].join(' / ')); + const steel = compiled(makeSurface('steel', TIERS.high)).uniforms, iron = compiled(makeSurface('iron', TIERS.high)).uniforms; + assert.notEqual(steel.microGrain!.value, iron.microGrain!.value); + assert.notEqual(steel.microBumpAmt!.value, iron.microBumpAmt!.value); +}); + +test('a board pattern is drawn for the size of the board: the same detail on a board written ten times larger or smaller', () => { + const unitOf = (w: number, d: number) => { + const m = makeSurface('pcb', TIERS.high); + fitBoardPattern(m, new BoxGeometry(w, 0.2, d)); + return compiled(m).uniforms.boardUnit!.value; + }; + assert.ok(Math.abs(unitOf(6, 4) - 1) < 0.01, 'the reference board is unchanged'); + assert.ok(Math.abs(unitOf(60, 40) / unitOf(6, 4) - 10) < 0.01); + assert.ok(Math.abs(unitOf(0.6, 0.4) / unitOf(6, 4) - 0.1) < 0.001); +}); + +test('the prewarm group has a solid in every surface, the same surfaces every time (their programs stay alive), and is built as a model is', () => { + for (const tier of ['low', 'mid', 'high'] as const) { + const panel = new PanelScene({ tier }); + const first = panel.prewarmGroup(); + assert.equal(first.children.length, SURFACE_NAMES.length); + const second = panel.prewarmGroup(); + const surfaces = (g: typeof first) => g.children.map((m) => (m as unknown as { material: unknown }).material); + assert.deepEqual(surfaces(second), surfaces(first), 'one set of surfaces for good'); + for (const m of first.children) { + assert.equal(m.castShadow, TIERS[tier].shadows); + assert.equal(m.frustumCulled, false); + } + assert.ok(!panel.scene.children.includes(first), 'it is not part of the scene until the caller adds it'); + } +}); From 6a1cab46dc80a7fedbd93e2c7da3a7e85496eee8 Mon Sep 17 00:00:00 2001 From: ProjectIdris <227970220+ProjectIdris@users.noreply.github.com> Date: Sun, 8 Nov 2026 23:50:20 +1300 Subject: [PATCH 5/5] Version 0.7.0 Co-Authored-By: Claude Opus 5.5 --- package-lock.json | 4 ++-- package.json | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/package-lock.json b/package-lock.json index 99269b6..4bfb572 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "talkthrough", - "version": "0.6.0", + "version": "0.7.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "talkthrough", - "version": "0.6.0", + "version": "0.7.0", "license": "MIT", "dependencies": { "get-windows": "10.0.0", diff --git a/package.json b/package.json index 15a3349..18ea622 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "talkthrough", - "version": "0.6.0", + "version": "0.7.0", "description": "An AI that talks you through anything on your screen, and draws as it talks.", "keywords": [ "screen assistant",