Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/scene-language.md
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ When the thing to explain is a process, a sequence of events, a how-to or a tren

### Surfaces

`material` is one of `plastic` (default), `metal`, `rubber`, `pcb`, `glass`, `glow`, `paper`, `tissue` (living tissue: soft, a little wet). They are physically based surfaces lit by a room environment; `color` tints them, and an object with no colour takes the natural colour of its surface (a `pcb` is green, `rubber` near black). Where a solid has creases or open boundaries, dark edge lines emphasize them unless `edges` is false. Smooth spheres/ellipsoids, rounded cylinders and full tori have no crease lines, even when `edges` is true: their tessellation is not an authored feature. This does not add silhouette outlines or change cut faces. See `samples/scenes/continuous-surfaces.json` for default/edges-off pairs at compact and stretched proportions.
`material` is one of `plastic` (default), `metal`, `rubber`, `pcb`, `glass`, `glow`, `paper`, `tissue` (living tissue: soft, a little wet), and the named library `bone`, `muscle`, `tendon`, `skin`, `steel`, `iron`, `brass`, `copper`, `wood`, `rope`, `water` (one table, `src/scene/material-library.ts`). They are physically based surfaces lit by a room environment; `color` tints them, and an object with no colour takes the natural colour of its surface (a `pcb` is green, `rubber` a dark grey). A library material keeps a tint within its own range of lightness: a hue is given, but bone tinted white is the palest bone and muscle tinted black the darkest muscle, so each reads on a light page and a dark one (the range was set from rendered frames on both). `plastic` and `rubber` take a colour as written, but with none they are a mid-tone, not near-white or near-black. `muscle`, `tendon` and `rope` tubes and connectors wear the fibre layer below without asking. Where a solid has creases or open boundaries, dark edge lines emphasize them unless `edges` is false. Smooth spheres/ellipsoids, rounded cylinders and full tori have no crease lines, even when `edges` is true: their tessellation is not an authored feature. This does not add silhouette outlines or change cut faces. See `samples/scenes/continuous-surfaces.json` for default/edges-off pairs at compact and stretched proportions.

Each object that accepts `material` also accepts four optional finish numbers, independently overriding that material's recipe:

Expand All @@ -103,6 +103,10 @@ Omitted or null fields keep the named defaults, including when no `material` is

See [surface finish review](surface-finish.md) and `samples/scenes/surface-finishes.json` for an authored comparison and native acceptance checklist.

`tube` and `connector` also accept `treatment: "fibres"`: a fixed, subtle longitudinal colour/roughness effect layered over the named material. For example, `material: "tissue", treatment: "fibres"` adds directional surface detail without modelling any strands; the same treatment works on a rubber cord. Omit/null keeps the plain material. This is one optional add field, not a style animation or a configurable shader. Other shapes do not support it yet.

The renderer supplies coordinates on the existing swept rings, so the detail follows bends and rebuilt endpoint motion instead of projecting through the world. Rounded tips and directions where the initial sweep frame becomes ambiguous fade to a plain material; periodic tubes keep the circumferential seam aligned. Unresolved frequencies fade away using screen-space derivatives at every quality tier. No vertices, triangles, draw calls, textures or network requests are added. Only treated geometries allocate three coordinate floats per vertex. Alpha/depth, clipping, silhouette, highlights and section hatching retain their existing behavior. This is illustrative material appearance, not an anatomical fibre model, displacement, anisotropic scattering or tissue mechanics. See `samples/scenes/path-surface-treatments.json` for paired plain/treated paths and view changes; an authored demonstration alone does not establish native visual acceptance or live-model latency.

For `loft` and `sweep`, optional `smooth: true` blends lighting across shallow section corners and removes their longitudinal edge lines. Flat caps, end perimeters and sharp corners stay distinct. Omitted, null or false keeps the original faceted appearance. This changes shading, not the polygon silhouette, roundover or wall thickness. See [smooth profile surfaces](smooth-profiles.md).

### Adding objects
Expand All @@ -120,9 +124,9 @@ For `loft` and `sweep`, optional `smooth: true` blends lighting across shallow s
| `loft` | `outline` `endOutline` `depth` `smooth`? `pos`? `rot`? `color`? `material`? | two convex XY outlines at z = -depth/2 and +depth/2, joined by matching indices; 3–24 corners per ring, equal counts and winding, every intermediate section strictly convex. No closing repeat, collinear corners, holes or bevel. See [profile lofts](profile-lofts.md) |
| `shell` | `size` `inner`? `latitude`? `sweep`? `pos`? `rot`? `color`? `material`? `edges`? `opacity`? | closed hollow ellipsoid section: full outer diameters `size`, concentric cavity ratio `inner` .01–.99 (default .85), latitude `[south,north]` −90–90 spanning at least 1 degree (default full), angular `sweep` 1–360 from +x toward +z (default full). Radial rims close the material, not the cavity; `inner` is not constant wall thickness. Origin stays at the full ellipsoid centre; rotate to aim the opening. Invalid/unsafe geometry rejects. See [hollow ellipsoid sections](ellipsoid-shells.md) |
| `blob` | `pts` `sizes` `soft`? `pos`? `rot`? `color`? `material`? `opacity`? | a soft organic form blended from 1 to 12 ellipsoid lumps: `pts` are the lump centres and `sizes` their boxes `[x,y,z]` (one for each point; a short list repeats its last). Lumps that overlap melt into one smooth skin with necks between them, so a heart chamber, an animal's body or head, a leaf, a fruit is one blob. `soft` (0.05 to 1, default 0.5) is how far they blend: low is nearly a hard union, 1 joins lumps a little apart. A lone lump is exactly its ellipsoid. For several forms (the chambers of an organ) write one blob each. No edge lines; cut tiers use a coarser skin |
| `tube` | `pts` `radius` `flat`? `swell`? `closed`? `draw`? `color`? `material`? | a smooth tube through 2 to 24 points: cables, pipes, vessels. `flat` (0.05 to 1) squashes it to a ribbon whose wide side faces across the path. `draw` below 1 starts it part drawn. `swell` `[[along 0 to 1, factor],...]` (2 to 8 points, smooth between them) changes the radius along the tube: a vessel that tapers, a stem that thickens toward the ground, a tail. `closed: true` joins the path into a smooth loop with no caps (at least three distinct points; repeating the first point at the end is optional). The loop carries its cross-section around the curve and distributes any remaining twist around it. `swell` returns to its start factor at the join, overriding the factor at 1. A closed loop has no endpoints to auto-attach, and its stream markers keep their size across the join when fully revealed. Tight bends and overlapping paths can still intersect. A tube thick for its length (radius at least 4 per cent of its length: a stem, a vessel, a limb, a pipe) counts as part of the model when the camera frames it; a thin cable does not |
| `tube` | `pts` `radius` `flat`? `swell`? `closed`? `draw`? `color`? `material`? `treatment`? | a smooth tube through 2 to 24 points: cables, pipes, vessels. `flat` (0.05 to 1) squashes it to a ribbon whose wide side faces across the path. `draw` below 1 starts it part drawn. `swell` `[[along 0 to 1, factor],...]` (2 to 8 points, smooth between them) changes the radius along the tube: a vessel that tapers, a stem that thickens toward the ground, a tail. `closed: true` joins the path into a smooth loop with no caps (at least three distinct points; repeating the first point at the end is optional). The loop carries its cross-section around the curve and distributes any remaining twist around it. `swell` returns to its start factor at the join, overriding the factor at 1. A closed loop has no endpoints to auto-attach, and its stream markers keep their size across the join when fully revealed. Tight bends and overlapping paths can still intersect. A tube thick for its length (radius at least 4 per cent of its length: a stem, a vessel, a limb, a pipe) counts as part of the model when the camera frames it; a thin cable does not |
| `line` `arrow` | `pts` `color`? `draw`? `opacity`? | a thin line through the points; an arrow ends in a head at the last point |
| `connector` | `from` `to` `kind`? `fromSide`? `toSide`? `fromAnchor`? `toAnchor`? `fromPoint`? `toPoint`? `swell`? `restLength`? `sag`? `radius`? `color`? `material`? `draw`? `opacity`? | a physical rope, belt, wire, chain or pipe between two parts of one 3D model, with its ends on them, drawn as a tube that follows them as they move; it never links panels, cards, marks or diagram nodes (flat diagram arrows are `edge`), and is not drawn until both ends are there (worked out afresh on every frame from where the two are, so it needs no pose of its own). `kind` `straight` (default) is taut, the line between its ends: a rope from a wheel's rim to a weight shortens as the weight rises. `slack` hangs in a sag (`sag`, 0 to 1, a fraction of its length, default 0.2) below the line between the ends: a wire, a tube. `wrapped` is a flat belt round two wheels (a cylinder, a sphere or a wheel, gear or bearing part) whose axes run the same way; it stands off the rims and is `radius` thick. `fromSide` and `toSide` (`left` `right` `top` `bottom` `front` `back`, as seen from the front) pick where an end meets its object: on a round object that is the rim in that direction, on any other the middle of that face of its box; left out, its middle. `fromAnchor` and `toAnchor` name a point of a ready-made part instead. For straight/slack connectors, `fromPoint`/`toPoint` are explicit local `[x,y,z]` points carried by each endpoint object's rotation and scale, taking precedence over its anchor and side. `swell` gives the same smooth radius profile as a tube. `restLength` (0.01–400) is the path length in the connector's own space at its authored radius: radius scales by `sqrt(restLength/currentLength)`, bounded to 0.25–4. This is an approximate volume-preserving visual, not a force or tissue simulation. These four fields are refused on wrapped belts. A connector to itself is refused. `radius` is its thickness (default 0.05). It is a path: a `stream` can run along it |
| `connector` | `from` `to` `kind`? `fromSide`? `toSide`? `fromAnchor`? `toAnchor`? `fromPoint`? `toPoint`? `swell`? `restLength`? `sag`? `radius`? `color`? `material`? `treatment`? `draw`? `opacity`? | a physical rope, belt, wire, chain or pipe between two parts of one 3D model, with its ends on them, drawn as a tube that follows them as they move; it never links panels, cards, marks or diagram nodes (flat diagram arrows are `edge`), and is not drawn until both ends are there (worked out afresh on every frame from where the two are, so it needs no pose of its own). `kind` `straight` (default) is taut, the line between its ends: a rope from a wheel's rim to a weight shortens as the weight rises. `slack` hangs in a sag (`sag`, 0 to 1, a fraction of its length, default 0.2) below the line between the ends: a wire, a tube. `wrapped` is a flat belt round two wheels (a cylinder, a sphere or a wheel, gear or bearing part) whose axes run the same way; it stands off the rims and is `radius` thick. `fromSide` and `toSide` (`left` `right` `top` `bottom` `front` `back`, as seen from the front) pick where an end meets its object: on a round object that is the rim in that direction, on any other the middle of that face of its box; left out, its middle. `fromAnchor` and `toAnchor` name a point of a ready-made part instead. For straight/slack connectors, `fromPoint`/`toPoint` are explicit local `[x,y,z]` points carried by each endpoint object's rotation and scale, taking precedence over its anchor and side. `swell` gives the same smooth radius profile as a tube. `restLength` (0.01–400) is the path length in the connector's own space at its authored radius: radius scales by `sqrt(restLength/currentLength)`, bounded to 0.25–4. This is an approximate volume-preserving visual, not a force or tissue simulation. These four fields are refused on wrapped belts. A connector to itself is refused. `radius` is its thickness (default 0.05). It is a path: a `stream` can run along it |
| `stream` | `along` `mark`? `count`? `size`? `color`? `toColor`? `shiftAt`? `period`? `by`? `ratio`? `opacity`? | markers (`mark` `dot` default, `dash` or `arrow`; `count` 1 to 40, default 6) that run along a `tube`, `line`, `arrow` or `connector`, or along an arrow (`edge`) of a flow diagram: blood through vessels, current in a wire, water in a pipe, cars on a road, data between computers, money in an economy. They go on running by themselves, from step to step. `period` is the seconds a marker takes for the whole way (default 4; negative runs it backwards); or give `by`, a spinning part, with `ratio` laps for each turn of it. `color` changes to `toColor` along the way (`shiftAt`, 0 to 1, is where, default the middle; blood blue to red through the lungs). `size` (3D only) is never less than a bead a little wider than the pipe, since a marker inside an opaque pipe could not be seen. It hangs from its path and goes with it; markers shrink away at the ends. A stream is not part of the model for the camera |
| `part` | `part` `size` `variant`? `n`? `pos`? `rot`? `color`? `parentAnchor`? `selfAnchor`? | a ready-made part fitted to the box `size`: `chip` (variant `black` or `metal`), `header` (`n` pins per row, two rows), `port` (variant `usb`, `usb3`, `ethernet`, `hdmi`, `usbc`; its opening faces `+z`), `lens` (axis `z`), `screen`, `button`, `fan` (`n` blades, axis `y`), `wheel` (`n` spokes, axis `z`). Anchor placement is described below |
| `array` | `of` `count` `step`? `turn`? | `count` copies in all of the object `of` (with everything attached to it); the original is the first. Each copy is moved `step` and turned `turn` more than the last, about the origin of the group the original sits in: a row of pins, blades round a hub. The original joins the new group `id` |
Expand Down
Loading
Loading