diff --git a/docs/overlay.md b/docs/overlay.md index c4d480d..56afe3e 100644 --- a/docs/overlay.md +++ b/docs/overlay.md @@ -38,11 +38,11 @@ The camera's near and far clipping planes follow the current visible pieces, inc Placement first tries to keep readable surfaces apart. When no layout fits, admission uses the actual painted card bounds, including flow growth and entrance motion, and omits whole conflicting panels instead of painting text through text. The stage keeps priority, then panels added or highlighted by the current step (including their diagram items), then older retained panels. Newer panels win ties. A visible count explains omissions; omitted panels and their annotations have no pointer footprint. -Cleared panels may finish fading only where they do not block live panels. Their departure does not count as a crowded omission, and reusing an id removes the old fading instance before measurement. An annotation belongs to the last preceding containing diagram or image and follows that exact surface through placement. +A stage a clear is taking away (`panel.leaving`) holds no space against what arrives either (`stageKeepOut`), and does not push the surfaces that arrive where it stood, so a chart that replaces the model is not hidden and the cue not raised while the model fades. Cleared panels may finish fading only where they do not block live panels. Their departure does not count as a crowded omission, and reusing an id removes the old fading instance before measurement. An annotation belongs to the last preceding containing diagram or image and follows that exact surface through placement. Diagram bounds are prepared without painting, then admitted content is painted once at the same timestamp. Node easing is not reset or advanced twice. The cue measures in an aria-hidden element, caches its size by count bound and viewport width, and changes its live text only when the count changes. -Known limits: an extreme thirteen-panel layout at 480×340 can still evict the stage to make room for the cue. Omitted panels still participate in placement, and diagram-internal clipping is separate from panel overlap. This fallback does not implement stage growth or animation hysteresis; future stage growth should relocate panels through the placer before admission becomes necessary. +Known limits: an extreme thirteen-panel layout at 480×340 can still evict the stage to make room for the cue. Omitted panels still participate in placement, and diagram-internal clipping is separate from panel overlap. Stage growth goes through the placer (`taller`), so cards relocate before admission is needed; a normal answer omits nothing while the stage appears. ### Where tags go @@ -100,7 +100,7 @@ Frame grabs can show these states without a pointer: `--steps step:t:az:el:zoom: ## Where things go -A model writes coordinates without seeing the page, so the overlay moves what it would cover (`src/overlay/placement.ts`). From a small gray picture of the screenshot it finds where there is something on the page (an edge, or a tone that is not the page's own background) and, for the 3D stage (a tag beside a small stage is drawn up to 30 per cent smaller so it does not outweigh the model) and for each note card or crop, picks the nearest free rectangle. Explanation first (Alex, 5 November): a stage, card or diagram takes the size and shape it was asked for before it shrinks or narrows to keep off page text, and may sit over text where that reads best; the cost of covering text still picks the quietest place of that size, and it leaves where the model put it only when the move is clearly worth it (`MOVE_WORTH`). Only what the answer points at (boxes, circles, underlines, arrow ends, labels, crop regions) is kept clear: touching it, even by a corner, costs a good deal, and only when no place of its size is clear of it, of the stage or of the cards does a stage go smaller (down to about half) or a diagram smaller and narrower. A card or diagram keeps well off the stage (it counts eight times over), since the model in it is what is being explained. A stage the model asked for small is made larger, up to a width and height of about a third of the screen (`STAGE_BIGGEST`), into blank page first and, when that gives it less than most of what it could have, onto page text too, never over what is pointed at or the cards (`enlarge`). What is covered is weighed by kind (`bodyTextOf`, `FIXTURE_COST`): each cell of ink is body text to some degree from 0 to 1, and covering the rest counts six times as much. A stack of at least four lines that start together, repeat at a steady pitch and mostly run nearly as long as the longest is a column of text however narrow it is (a split pane, a chat, an ultrawide screen); any other ink is weighed by the width of its line, a fixture under 15% of the page, prose from 30%, and a ramp between so a figure does not flip at a cliff, and a run wider than 85% is a bar (a toolbar) and a fixture again. A sidebar or panel of labels of all lengths, an infobox and its picture, and a toolbar are fixtures, so a place of the asked size that avoids a page's controls or figures is preferred to one that covers them, and body text is covered first. A place that is already free stays where the model put it, a move has to be clearly worth it, and a page with nowhere free is left as written. A card's place is free again when it is cleared. The scene's messages wait, up to a second and a half, for the screenshot to be decoded so the first stage is placed on the real page; without a picture of the page nothing moves. The optional `frame` behind the stage is light over a light page and dark over a dark one. +A model writes coordinates without seeing the page, so the overlay moves what it would cover (`src/overlay/placement.ts`). From a small gray picture of the screenshot it finds where there is something on the page (an edge, or a tone that is not the page's own background) and, for the 3D stage (a tag beside a small stage is drawn up to 30 per cent smaller so it does not outweigh the model) and for each note card or crop, picks the nearest free rectangle. Explanation first (Alex, 5 November): a stage, card or diagram takes the size and shape it was asked for before it shrinks or narrows to keep off page text, and may sit over text where that reads best; the cost of covering text still picks the quietest place of that size, and it leaves where the model put it only when the move is clearly worth it (`MOVE_WORTH`). Only what the answer points at (boxes, circles, underlines, arrow ends, labels, crop regions) is kept clear: touching it, even by a corner, costs a good deal, and only when no place of its size is clear of it, of the stage or of the cards does a stage go smaller (down to about half) or a diagram smaller and narrower. A card or diagram keeps well off the stage (it counts eight times over), since the model in it is what is being explained. A stage the model asked for small is made larger, up to a width and height of about a third of the screen (`STAGE_BIGGEST`), into blank page first and, when that gives it less than most of what it could have, onto page text too, never over what is pointed at or the cards (`enlarge`). A stage shorter than a fair share of the screen's height (620 units, about 62 per cent) is then made taller, keeping its width and everything it covered (`taller`): the screen is wider than tall, so a stage as wide as it is tall is a wide slab and a tall or compact model is limited by its height. The added height must lie on page with little on it (at most 15% of its cells inked, at most 10% controls or figures), so a page of text keeps the stage as asked; cards and the page's controls are hard keep-outs, and what the answer points at is a preference (a place that would cover another pointed-at spot is passed over; a spot the stage already covers is left out of the reckoning). It stops short of taking the last quiet place a note-sized card could have (a card about 380 by 150 units must find a place as quiet as it had before, clear of the grown stage, the strip of its buttons below it, the controls and the cards already placed), so on a page with one blank column the stage grows less rather than push the next note onto the page's content. It is done in the placement, so cards written after it keep off the taller stage, and the rectangle the page eases to always holds the one it eased from, so admission does not flip while it eases. What is covered is weighed by kind (`bodyTextOf`, `FIXTURE_COST`): each cell of ink is body text to some degree from 0 to 1, and covering the rest counts six times as much. A stack of at least four lines that start together, repeat at a steady pitch and mostly run nearly as long as the longest is a column of text however narrow it is (a split pane, a chat, an ultrawide screen); any other ink is weighed by the width of its line, a fixture under 15% of the page, prose from 30%, and a ramp between so a figure does not flip at a cliff, and a run wider than 85% is a bar (a toolbar) and a fixture again. A sidebar or panel of labels of all lengths, an infobox and its picture, and a toolbar are fixtures, so a place of the asked size that avoids a page's controls or figures is preferred to one that covers them, and body text is covered first. A place that is already free stays where the model put it, a move has to be clearly worth it, and a page with nowhere free is left as written. A card's place is free again when it is cleared. The scene's messages wait, up to a second and a half, for the screenshot to be decoded so the first stage is placed on the real page; without a picture of the page nothing moves. The optional `frame` behind the stage is light over a light page and dark over a dark one. A model also points at things inside a picture from a downsized view, so a mark can be a few pixels off what it means (an arrow stopping short of its curve, a ring beside the crossing, a box with an edge through a line of text). `src/overlay/snap.ts` looks at the page's own pixels, at about a thousand cells across: the long edges (lines and curves, found by thinning the edges and keeping those that run a few percent of the screen; letters are shorter), the corners and crossings (where the gradient changes two ways, then placed exactly where the two lines through them meet) and the ink (anything that is not the page's own background). Then an arrow's tip goes to the nearest line, a point goes to the nearest crossing or line, a small ring is centred on the crossing next to it, a polygon's corners go to the page's corners, a trace is laid on the curve it follows, a box takes in an edge that cuts through a line of text or a figure and takes in a loose empty margin (keeping a little air), and an underline drops to just under its line of letters. It never moves a mark far (seven percent of the shorter side at most, and less for most) and it leaves a mark alone wherever it cannot tell what was meant: nothing long enough to land on near it, two lines about equally near, a mark over blank page, a box on a border, a tilted box, a large ring round a figure. It runs before the placement above, once for each action, and says each move in the app log (`talkthrough: snapped arrow demandarrow by 14 units`). What it works out from a page (the busy map, the placement grid, the snapper) is kept for that capture only and dropped when the next screenshot arrives, since one image element holds every capture; it is built as soon as the screenshot has decoded, not at the first mark. diff --git a/docs/scene.schema.json b/docs/scene.schema.json index 8c8a01f..06d14d0 100644 --- a/docs/scene.schema.json +++ b/docs/scene.schema.json @@ -1450,7 +1450,7 @@ "at" ], "additionalProperties": false, - "description": "A closed hollow ellipsoid section: domes, bowls, curved enclosures and opened layers. size is the full outer ellipsoid diameters [x,y,z], not the cropped bounds. inner (default .85) scales its concentric cavity, not a uniform wall thickness. latitude [south,north] degrees -90..90 (default [-90,90], span at least 1); sweep 1..360 (default 360) runs from +x toward +z around y. Radial rims close the material volume. Rotate to aim the opening. Invalid or unsafe geometry rejects." + "description": "A closed hollow ellipsoid section: domes, bowls, curved enclosures, opened layers. size is the full outer diameters [x,y,z]; inner (default .85) scales the cavity concentrically, so the wall is not a constant thickness; latitude [south,north] degrees -90..90 (default [-90,90], span at least 1) cuts a dome or bowl; sweep 1..360 (default 360) runs from +x toward +z around y and leaves an angular opening: rot aims it. Radial rims close the volume; unsafe geometry rejects." }, "addExtrude": { "type": "object", @@ -1682,7 +1682,7 @@ "at" ], "additionalProperties": false, - "description": "A flat outline [[x,y],...] in the x,y plane, pushed out depth along z and centred on it: wings, fins, plates, brackets. Ordinary extrusions support disjoint through-hole rings strictly inside the outline, with flat edges only. Optional taper or shift makes a sharp closed transition: the negative-z end is the outline, the positive-z end is outline*taper+shift, scaling about the local origin. Defaults in this mode: taper 1, shift [0,0]. taper 0.05..20; both end coordinates -100..100; depth 0.01..100. Requires a simple polygon, 3..40 points, either winding. Invalid or Float32-unsafe geometry rejects, not repairs. Bevel must be omitted/null/0; through-holes are not supported in this mode." + "description": "A flat outline [[x,y],...] in the x,y plane, pushed out depth (0.01..100) along z and centred on it: wings, fins, plates, brackets. A simple polygon of 3..40 points, either winding. holes: up to 8 separate rings of 3 to 24 points, strictly inside the outline and clear of each other (no touching, crossing or nesting), 128 points in all with the outline, flat edges only (bevel 0). taper or shift makes a sharp closed transition: the negative-z end is the outline, the positive-z end is outline*taper+shift about the local origin (taper 0.05..20, defaults 1 and [0,0], ends within -100..100); it takes no bevel or holes. Unsafe geometry rejects, not repairs." }, "addHull": { "type": "object", @@ -2064,7 +2064,7 @@ "at" ], "additionalProperties": false, - "description": "A profile [[radius,y],...] spun round the y axis: bodies, nozzles, rings, bottles. sides makes it faceted (default quality tiers: 20/36/64). Optional sweep 1..359 degrees makes a closed sector from +z towards +x about +y; rotate to choose its start. Sector profile: simple closed polygon, 3..40 points (one repeated closing point allowed), radius 0..100, y -100..100. Invalid, touching, intersecting or Float32-unsafe profiles and invalid sweeps are rejected, not repaired. Either winding; exact redundant collinear boundary points are removed. sides is segments per full revolution (sector segments scale proportionally, at most 90 degrees each)." + "description": "A profile [[radius,y],...] spun round the y axis: bodies, nozzles, rings, bottles. sides is the segments per full revolution (default by quality: 20/36/64). sweep 1..359 degrees makes a cutaway: a closed sector from +z towards +x about +y (rot chooses where it starts); the profile is then a simple closed polygon of 3..40 points, radius 0..100, y -100..100, not touching or crossing itself, either winding. Omit sweep for the full lathe. Bad profiles reject, not repair." }, "addPatch": { "type": "object", @@ -2247,7 +2247,7 @@ "at" ], "additionalProperties": false, - "description": "An open bicubic Bézier sheet: exactly 16 controls [x,y,z], four rows of four in row-major order. Each row runs across u; rows advance v. Corners lie on the sheet; other controls pull its curvature, not interpolation points. Curved panels, canopies, membranes. Two-sided, no thickness or solid cut cap. Use a regular net without folds or collapsed rows." + "description": "An open bicubic Bézier sheet: exactly 16 controls [x,y,z], four rows of four in row-major order (rows run across u and advance v). Corners lie on the sheet; the other controls pull its curve, they are not points to interpolate, so use a regular net without folds or collapsed rows. Two-sided, no thickness: curved panels, canopies, membranes." }, "addSweep": { "type": "object", @@ -2460,7 +2460,7 @@ "at" ], "additionalProperties": false, - "description": "A closed polygon outline carried along a smooth open 3D path: curved rails, shaped cables and solid bands. Outline x,y are local section offsets; up sets initial +y, projected perpendicular to the path (default +y, or +x for a vertical start). The section follows with minimum rotation. Flat caps and sharp section corners by default; smooth:true blends shallow wall joins without changing geometry. No bevel or holes. Keep the profile narrow relative to bends; folded or collapsed sampled meshes are rejected." + "description": "A closed polygon outline carried along a smooth open 3D path pts: curved rails, shaped cables, solid bands. Outline x,y are section offsets; up sets the initial +y (default +y, or +x for a vertical start). The section follows with minimum rotation, so keep it narrow relative to bends. Flat caps and sharp corners; smooth:true blends shallow wall joins without changing geometry. No bevel, holes, stream or reveal." }, "addLoft": { "type": "object", @@ -2667,7 +2667,7 @@ "at" ], "additionalProperties": false, - "description": "A closed solid joining independently shaped convex end outlines by matching point indices, at z=-depth/2 and +depth/2. Both rings need 3–24 corners, equal counts and the same winding; every interpolated section must stay strictly convex. No closing duplicate, collinear corners, holes or bevel. Use for asymmetric shape-changing transitions; no automatic recentering or point rematching. Optional smooth:true blends shallow wall joins while retaining flat caps and sharp corners." + "description": "A closed solid joining two convex end outlines by matching point indices: outline at z=-depth/2, endOutline at +depth/2. Both rings need 3-24 corners, equal counts and the same winding, and every section between must stay strictly convex (no closing repeat, collinear corners, holes or bevel). For solid asymmetric transitions, not hollow ducts; smooth:true blends shallow wall joins and keeps flat caps and sharp corners." }, "addBlob": { "type": "object", @@ -2861,7 +2861,7 @@ "at" ], "additionalProperties": false, - "description": "A soft organic form blended from up to 12 ellipsoid lumps, each at a point of pts with its own box size [x,y,z] in sizes (the same count, or the last is repeated): a heart or other organ, a fruit, an animal body or head, a leaf. Lumps that overlap melt into one skin with smooth necks; soft (0.05 to 1, default 0.5) is how far they blend. Build one form per blob and join forms with tube." + "description": "A soft organic form blended from up to 12 ellipsoid lumps, each at a point of pts with its own box size [x,y,z] in sizes (the same count, or the last is repeated). Overlapping lumps melt into one skin with smooth necks; soft (0.05 to 1, default 0.5) is how far they blend. One form per blob; join forms with tube." }, "addTube": { "type": "object", @@ -3049,7 +3049,7 @@ "at" ], "additionalProperties": false, - "description": "A smooth tube through the points: cables, pipes, vessels, stems, limbs. closed true joins it into a continuous loop (three distinct points minimum, no caps or endpoint attachment). flat (0.05 to 1) squashes it to a ribbon; draw below 1 starts it partly drawn. swell [[along 0 to 1, radius factor],...] (2 to 8 points) makes the radius change along it: a vessel that tapers, a stem that thickens, a tail." + "description": "A smooth tube through the points: cables, pipes, vessels, stems, limbs. closed true joins it into a continuous loop (three distinct points minimum, no caps or endpoint attachment, no wave). flat (0.05 to 1) squashes it to a ribbon; draw below 1 starts it partly drawn. swell [[along 0 to 1, radius factor],...] (2 to 8 points) makes the radius change along it: a vessel that tapers, a stem that thickens, a tail. An end that lies on a part is joined to it and goes with it: keep a part that travels along the tube (along, a mouthful) off the ends, or the tube is pulled into a stub." }, "addPath": { "type": "object", @@ -3387,7 +3387,7 @@ "at" ], "additionalProperties": false, - "description": "A physical rope, belt, wire, chain or pipe between two parts of one 3D model, its ends on them, following them as they move (it never links panels, cards or marks: flat diagram arrows are edge). kind straight (default) is taut and shortens as a weight rises; slack hangs in a sag; wrapped is a flat belt round two wheels. fromSide and toSide say where an end meets its object, as seen from the front (left, right, top, bottom, front, back; the rim of a wheel), else its middle; fromAnchor and toAnchor name a point of a ready-made part." + "description": "A physical rope, belt, wire, chain or pipe between two parts of one 3D model, its ends on them, following them as they move (never panels, cards or marks: flat diagram arrows are edge). kind straight (default) is taut and shortens as a weight rises; slack hangs in a sag; wrapped is a flat belt round two wheels. fromSide and toSide say where an end meets its object, as seen from the front (left, right, top, bottom, front, back; the rim of a wheel), else its middle; fromAnchor and toAnchor name a point of a ready-made part; fromPoint and toPoint are points in each part's own space. swell and restLength make a muscle or soft cord bulge as its ends approach." }, "addStream": { "type": "object", @@ -3486,6 +3486,20 @@ "null" ], "description": "seconds after the step starts; 0 to 60" + }, + "surge": { + "type": [ + "number", + "null" + ], + "description": "flow in beats: the markers speed up and slow down once a beat by this fraction of their speed (0.8 is strong surges, as blood in a pulse); not with by; 0.05 to 0.95" + }, + "beat": { + "type": [ + "number", + "null" + ], + "description": "seconds a beat takes (default 1); 0.2 to 10" } }, "required": [ @@ -3503,12 +3517,14 @@ "by", "ratio", "opacity", - "at" + "at", + "surge", + "beat" ], "additionalProperties": false, "description": "Dots, dashes or arrows travelling along a tube, line, arrow, connector or an edge of a flow diagram, running on by themselves. period is the seconds a marker takes for the whole way (negative runs backwards, default 4); or by a spinning part, ratio laps for each turn. color changes to toColor along the way (shiftAt, 0 to 1, is where)." }, - "addPart": { + "addParticles": { "type": "object", "properties": { "op": { @@ -3518,7 +3534,7 @@ }, "shape": { "enum": [ - "part" + "particles" ] }, "id": { @@ -3531,41 +3547,38 @@ ], "description": "id of a group, part or shape to attach to; create a new parent no later than this child (it carries this along)" }, - "parentAnchor": { + "pos": { "type": [ - "string", + "array", "null" ], - "description": "attach at this named point of the parent (requires parent): a built-in name, a kit part's own, or one named with the anchor action; origin when only selfAnchor is set. The part then stays at that point whatever moves, spins or is dragged, and pos and move are its offset from the point; up to 24 characters" + "items": { + "type": "number" + }, + "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" }, - "selfAnchor": { + "count": { "type": [ - "string", + "number", "null" ], - "description": "the point of this object placed at parentAnchor, default origin; requires parent. Unknown names drop the action with the available ones; up to 24 characters" + "description": "4 to 80" }, - "explode": { - "type": [ - "array", - "null" - ], + "from": { + "type": "array", "items": { "type": "number" }, - "description": "where it moves when the model is exploded, [x,y,z] in the units of the group it is in (spread 1); without it, it moves outward from the middle of the parts around it; [x,y,z], each -100 to 100" + "description": "[x,y,z], each 0.05 to 100" }, - "pos": { - "type": [ - "array", - "null" - ], + "to": { + "type": "array", "items": { "type": "number" }, - "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" + "description": "[x,y,z], each 0.05 to 100" }, - "rot": { + "shift": { "type": [ "array", "null" @@ -3573,61 +3586,28 @@ "items": { "type": "number" }, - "description": "degrees [x,y,z]; [x,y,z], each -3600 to 3600" - }, - "part": { - "enum": [ - "chip", - "header", - "port", - "lens", - "screen", - "button", - "fan", - "wheel", - "cylinder-block", - "piston", - "connecting-rod", - "crankshaft", - "valve", - "camshaft", - "spark-plug", - "gear", - "spring", - "bearing", - "pipe", - "elbow", - "housing" - ] - }, - "variant": { - "enum": [ - "black", - "metal", - "usb", - "usb3", - "ethernet", - "hdmi", - "usbc", - "gold", - "cutaway", - "finned", - null - ] + "description": "where the middle of the box they fill is, from the middle of the box they start in; [x,y,z], each -100 to 100" }, "size": { - "type": "array", - "items": { - "type": "number" - }, - "description": "[x,y,z], each 0.01 to 100" + "type": [ + "number", + "null" + ], + "description": "0.01 to 2" }, - "n": { + "jitter": { "type": [ "number", "null" ], - "description": "1 to 64" + "description": "how far each jostles (default 0.12); 0 to 2" + }, + "period": { + "type": [ + "number", + "null" + ], + "description": "seconds a jostle takes (default 1.5); 0.2 to 20" }, "color": { "type": [ @@ -3636,6 +3616,13 @@ ], "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" }, + "draw": { + "type": [ + "number", + "null" + ], + "description": "how spread out they are at first, 0 crowded in the start box to 1 filling the other (default 0); grow it with reveal; 0 to 1" + }, "opacity": { "type": [ "number", @@ -3656,23 +3643,23 @@ "shape", "id", "parent", - "parentAnchor", - "selfAnchor", - "explode", "pos", - "rot", - "part", - "variant", + "count", + "from", + "to", + "shift", "size", - "n", + "jitter", + "period", "color", + "draw", "opacity", "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). Each has good proportions; mechanism anchors and the origin of every part can be used by pins, connectors and parentAnchor/selfAnchor placement." + "description": "A cloud of count small particles (default 30) that spread out: they begin in a box of size from at pos and, as reveal takes the cloud from 0 to 1 (it begins at 0, so they start crowded), drift apart to fill a box of size to, centred shift further on, jostling all the while. Diffusion, a gas filling a room, dye in water; a membrane is a plane or box between." }, - "addArray": { + "addForce": { "type": "object", "properties": { "op": { @@ -3682,38 +3669,47 @@ }, "shape": { "enum": [ - "array" + "force" ] }, "id": { "type": "string" }, - "of": { - "type": "string" - }, - "count": { - "type": "number", - "description": "2 to 64" + "on": { + "type": "string", + "description": "the part the force acts on" }, - "step": { + "point": { "type": [ - "array", + "string", "null" ], + "description": "up to 24 characters" + }, + "dir": { + "type": "array", "items": { "type": "number" }, - "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" + "description": "the direction it points, [x,y,z] in the scene: [0,-1,0] is down; [x,y,z], each -100 to 100" }, - "turn": { + "strength": { + "type": "number", + "description": "0.05 to 30" + }, + "color": { "type": [ - "array", + "string", "null" ], - "items": { - "type": "number" - }, - "description": "degrees [x,y,z]; [x,y,z], each -3600 to 3600" + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "opacity": { + "type": [ + "number", + "null" + ], + "description": "0 to 1" }, "at": { "type": [ @@ -3727,16 +3723,18 @@ "op", "shape", "id", - "of", - "count", - "step", - "turn", + "on", + "point", + "dir", + "strength", + "color", + "opacity", "at" ], "additionalProperties": false, - "description": "Copies of an existing object, count in all (the original is the first). step moves each copy [x,y,z] from the last; turn rotates each copy about the origin of the group the original sits in, which is how to put blades round a hub." + "description": "An arrow for a force on a part: from a point of it (point, default center) the way dir points in the scene (not the part: gravity stays down as the part turns), strength units long and thicker the stronger, following the part wherever it goes. Colour it and name it with a pin; scale it to change its strength, loop pulse it to make it come and go." }, - "addText": { + "addField": { "type": "object", "properties": { "op": { @@ -3746,7 +3744,7 @@ }, "shape": { "enum": [ - "text" + "field" ] }, "id": { @@ -3759,52 +3757,72 @@ ], "description": "id of a group, part or shape to attach to; create a new parent no later than this child (it carries this along)" }, - "parentAnchor": { + "pos": { "type": [ - "string", + "array", "null" ], - "description": "attach at this named point of the parent (requires parent): a built-in name, a kit part's own, or one named with the anchor action; origin when only selfAnchor is set. The part then stays at that point whatever moves, spins or is dragged, and pos and move are its offset from the point; up to 24 characters" + "items": { + "type": "number" + }, + "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" }, - "selfAnchor": { + "kind": { + "enum": [ + "dipole", + "radial", + "uniform" + ] + }, + "axis": { + "enum": [ + "x", + "y", + null + ] + }, + "size": { "type": [ - "string", + "number", "null" ], - "description": "the point of this object placed at parentAnchor, default origin; requires parent. Unknown names drop the action with the available ones; up to 24 characters" + "description": "0.5 to 40" }, - "explode": { + "count": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "where it moves when the model is exploded, [x,y,z] in the units of the group it is in (spread 1); without it, it moves outward from the middle of the parts around it; [x,y,z], each -100 to 100" + "description": "2 to 16" }, - "pos": { + "gap": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" - }, - "text": { - "type": "string", - "description": "up to 80 characters" + "description": "0 to 40" }, - "height": { - "type": "number", - "description": "0.05 to 50" + "flip": { + "type": [ + "boolean", + "null" + ], + "description": "reverse the way the lines point" }, "color": { - "type": "string", + "type": [ + "string", + "null" + ], "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" }, + "opacity": { + "type": [ + "number", + "null" + ], + "description": "0 to 1" + }, "at": { "type": [ "number", @@ -3818,19 +3836,21 @@ "shape", "id", "parent", - "parentAnchor", - "selfAnchor", - "explode", "pos", - "text", - "height", + "kind", + "axis", + "size", + "count", + "gap", + "flip", "color", + "opacity", "at" ], "additionalProperties": false, - "description": "Text in the 3D scene that always faces the camera; height is in 3D units." + "description": "Field lines as arrows in the front plane round pos: dipole (a bar magnet or pair of charges: lines leave the end on the positive axis side and curve round to the other), radial (spokes out from a point charge, in to a mass: flip reverses them), uniform (parallel lines along axis, between plates or near the ground). size is how far they reach (default 5), count how many (default 8), gap the room between poles or plates. One group: clear its id to take them all away." }, - "addGroup": { + "addPart": { "type": "object", "properties": { "op": { @@ -3840,7 +3860,7 @@ }, "shape": { "enum": [ - "group" + "part" ] }, "id": { @@ -3897,11 +3917,79 @@ }, "description": "degrees [x,y,z]; [x,y,z], each -3600 to 3600" }, - "at": { - "type": [ - "number", - "null" - ], + "part": { + "enum": [ + "chip", + "header", + "port", + "lens", + "screen", + "button", + "fan", + "wheel", + "cylinder-block", + "piston", + "connecting-rod", + "crankshaft", + "valve", + "camshaft", + "spark-plug", + "gear", + "spring", + "bearing", + "pipe", + "elbow", + "housing" + ] + }, + "variant": { + "enum": [ + "black", + "metal", + "usb", + "usb3", + "ethernet", + "hdmi", + "usbc", + "gold", + "cutaway", + "finned", + null + ] + }, + "size": { + "type": "array", + "items": { + "type": "number" + }, + "description": "[x,y,z], each 0.01 to 100" + }, + "n": { + "type": [ + "number", + "null" + ], + "description": "1 to 64" + }, + "color": { + "type": [ + "string", + "null" + ], + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "opacity": { + "type": [ + "number", + "null" + ], + "description": "0 to 1" + }, + "at": { + "type": [ + "number", + "null" + ], "description": "seconds after the step starts; 0 to 60" } }, @@ -3915,26 +4003,41 @@ "explode", "pos", "rot", + "part", + "variant", + "size", + "n", + "color", + "opacity", "at" ], "additionalProperties": false, - "description": "An empty node to move, turn and scale other objects together (attach them with parent)." + "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." }, - "pin": { + "addArray": { "type": "object", "properties": { "op": { "enum": [ - "pin" + "add" + ] + }, + "shape": { + "enum": [ + "array" ] }, "id": { "type": "string" }, - "on": { + "of": { "type": "string" }, - "point": { + "count": { + "type": "number", + "description": "2 to 64" + }, + "step": { "type": [ "array", "null" @@ -3944,18 +4047,75 @@ }, "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" }, - "anchor": { + "turn": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "degrees [x,y,z]; [x,y,z], each -3600 to 3600" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "shape", + "id", + "of", + "count", + "step", + "turn", + "at" + ], + "additionalProperties": false, + "description": "Copies of an existing object, count in all (the original is the first). step moves each copy [x,y,z] from the last; turn rotates each copy about the origin of the group the original sits in, which is how to put blades round a hub." + }, + "addText": { + "type": "object", + "properties": { + "op": { + "enum": [ + "add" + ] + }, + "shape": { + "enum": [ + "text" + ] + }, + "id": { + "type": "string" + }, + "parent": { "type": [ "string", "null" ], - "description": "a named point of a ready-made part, instead of point; up to 24 characters" + "description": "id of a group, part or shape to attach to; create a new parent no later than this child (it carries this along)" }, - "text": { - "type": "string", - "description": "up to 40 characters" + "parentAnchor": { + "type": [ + "string", + "null" + ], + "description": "attach at this named point of the parent (requires parent): a built-in name, a kit part's own, or one named with the anchor action; origin when only selfAnchor is set. The part then stays at that point whatever moves, spins or is dragged, and pos and move are its offset from the point; up to 24 characters" }, - "off": { + "selfAnchor": { + "type": [ + "string", + "null" + ], + "description": "the point of this object placed at parentAnchor, default origin; requires parent. Unknown names drop the action with the available ones; up to 24 characters" + }, + "explode": { "type": [ "array", "null" @@ -3963,54 +4123,679 @@ "items": { "type": "number" }, - "description": "[x,y], each -500 to 500" + "description": "where it moves when the model is exploded, [x,y,z] in the units of the group it is in (spread 1); without it, it moves outward from the middle of the parts around it; [x,y,z], each -100 to 100" + }, + "pos": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" + }, + "text": { + "type": "string", + "description": "up to 80 characters" + }, + "height": { + "type": "number", + "description": "0.05 to 50" }, "color": { + "type": "string", + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "shape", + "id", + "parent", + "parentAnchor", + "selfAnchor", + "explode", + "pos", + "text", + "height", + "color", + "at" + ], + "additionalProperties": false, + "description": "Text in the 3D scene that always faces the camera; height is in 3D units." + }, + "addGroup": { + "type": "object", + "properties": { + "op": { + "enum": [ + "add" + ] + }, + "shape": { + "enum": [ + "group" + ] + }, + "id": { + "type": "string" + }, + "parent": { "type": [ "string", "null" ], - "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + "description": "id of a group, part or shape to attach to; create a new parent no later than this child (it carries this along)" + }, + "parentAnchor": { + "type": [ + "string", + "null" + ], + "description": "attach at this named point of the parent (requires parent): a built-in name, a kit part's own, or one named with the anchor action; origin when only selfAnchor is set. The part then stays at that point whatever moves, spins or is dragged, and pos and move are its offset from the point; up to 24 characters" + }, + "selfAnchor": { + "type": [ + "string", + "null" + ], + "description": "the point of this object placed at parentAnchor, default origin; requires parent. Unknown names drop the action with the available ones; up to 24 characters" + }, + "explode": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "where it moves when the model is exploded, [x,y,z] in the units of the group it is in (spread 1); without it, it moves outward from the middle of the parts around it; [x,y,z], each -100 to 100" + }, + "pos": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" + }, + "rot": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "degrees [x,y,z]; [x,y,z], each -3600 to 3600" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "shape", + "id", + "parent", + "parentAnchor", + "selfAnchor", + "explode", + "pos", + "rot", + "at" + ], + "additionalProperties": false, + "description": "An empty node to move, turn and scale other objects together (attach them with parent)." + }, + "pin": { + "type": "object", + "properties": { + "op": { + "enum": [ + "pin" + ] + }, + "id": { + "type": "string" + }, + "on": { + "type": "string" + }, + "point": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "[x,y,z], default [0,0,0]; [x,y,z], each -100 to 100" + }, + "anchor": { + "type": [ + "string", + "null" + ], + "description": "a named point of a ready-made part, instead of point; up to 24 characters" + }, + "text": { + "type": "string", + "description": "up to 40 characters" + }, + "off": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "[x,y], each -500 to 500" + }, + "color": { + "type": [ + "string", + "null" + ], + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "id", + "on", + "point", + "anchor", + "text", + "off", + "color", + "at" + ], + "additionalProperties": false, + "description": "A label pinned to a 3D object: a dot at point (in the object's own space, default its middle), a line and a tag that follow it as it moves. off is where the tag sits from the dot in screen units (default [0,-90])." + }, + "move": { + "type": "object", + "properties": { + "op": { + "enum": [ + "move" + ] + }, + "id": { + "type": "string" + }, + "to": { + "type": "array", + "items": { + "type": "number" + }, + "description": "[x,y,z], each -100 to 100" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "to", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Move a 3D object to an absolute position." + }, + "along": { + "type": "object", + "properties": { + "op": { + "enum": [ + "along" + ] + }, + "id": { + "type": "string" + }, + "pts": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number" + } + }, + "description": "1 to 24 points [x,y,z]" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "pts", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Move a 3D object along a smooth path through the points, ending on the last." + }, + "turn": { + "type": "object", + "properties": { + "op": { + "enum": [ + "turn" + ] + }, + "id": { + "type": "string" + }, + "to": { + "type": "array", + "items": { + "type": "number" + }, + "description": "[x,y,z], each -3600 to 3600" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "to", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Turn a 3D object to absolute angles in degrees; from [0,0,0], [0,360,0] is one full spin." + }, + "scale": { + "type": "object", + "properties": { + "op": { + "enum": [ + "scale" + ] + }, + "id": { + "type": "string" + }, + "to": { + "type": "array", + "items": { + "type": "number" + }, + "description": "[x,y,z], each 0.01 to 100" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "to", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Scale a 3D object to absolute factors [x,y,z] (1 is the size it was added at)." + }, + "explode": { + "type": "object", + "properties": { + "op": { + "enum": [ + "explode" + ] + }, + "id": { + "type": "string" + }, + "to": { + "type": "number", + "description": "0 to 3" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "to", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Spread the parts of a group outward from its origin: 0 assembled, 1 apart (up to 3). A part that has its own explode offset moves by that offset times the spread instead. Back to 0 to assemble." + }, + "reveal": { + "type": "object", + "properties": { + "op": { + "enum": [ + "reveal" + ] + }, + "id": { + "type": "string" + }, + "to": { + "type": "number", + "description": "0 to 1" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "to", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Draw a tube, line or arrow on, from its start: to 1 is all of it." + }, + "anchor": { + "type": "object", + "properties": { + "op": { + "enum": [ + "anchor" + ] + }, + "id": { + "type": "string" + }, + "name": { + "type": "string", + "description": "up to 24 characters" + }, + "pos": { + "type": "array", + "items": { + "type": "number" + }, + "description": "[x,y,z], each -100 to 100" + } + }, + "required": [ + "op", + "id", + "name", + "pos" + ], + "additionalProperties": false, + "description": "Name a point on a 3D object, in its own space, for parentAnchor or selfAnchor: write it right after the object." + }, + "detach": { + "type": "object", + "properties": { + "op": { + "enum": [ + "detach" + ] + }, + "id": { + "type": "string" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "id", + "at" + ], + "additionalProperties": false, + "description": "Let an attached part go: it stays where it is and is placed on its own from then (no join line). To lift a part out and still show where it goes, move it instead." + }, + "style": { + "type": "object", + "properties": { + "op": { + "enum": [ + "style" + ] + }, + "id": { + "type": "string" + }, + "color": { + "type": [ + "string", + "null" + ], + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "opacity": { + "type": [ + "number", + "null" + ], + "description": "0 to 1" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" + }, + "dur": { + "type": [ + "number", + "null" + ], + "description": "seconds the change takes (default 0.6); 0 to 30" + } + }, + "required": [ + "op", + "id", + "color", + "opacity", + "at", + "dur" + ], + "additionalProperties": false, + "description": "Change the colour and/or opacity of any object or mark; at least one of them." + }, + "highlight": { + "type": "object", + "properties": { + "op": { + "enum": [ + "highlight" + ] + }, + "id": { + "type": "string" + }, + "color": { + "type": [ + "string", + "null" + ], + "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" }, - "at": { + "dur": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "seconds the change takes (default 0.6); 0 to 30" } }, "required": [ "op", "id", - "on", - "point", - "anchor", - "text", - "off", "color", - "at" + "at", + "dur" ], "additionalProperties": false, - "description": "A label pinned to a 3D object: a dot at point (in the object's own space, default its middle), a line and a tag that follow it as it moves. off is where the tag sits from the dot in screen units (default [0,-90])." + "description": "Pulse an object or mark to draw the eye, optionally in a colour." }, - "move": { + "spin": { "type": "object", "properties": { "op": { "enum": [ - "move" + "spin" ] }, "id": { "type": "string" }, - "to": { - "type": "array", - "items": { - "type": "number" - }, - "description": "[x,y,z], each -100 to 100" + "rpm": { + "type": [ + "number", + "null" + ], + "description": "-600 to 600" + }, + "by": { + "type": [ + "string", + "null" + ] + }, + "ratio": { + "type": [ + "number", + "null" + ], + "description": "-20 to 20" + }, + "phase": { + "type": [ + "number", + "null" + ], + "description": "-3600 to 3600" + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null + ] + }, + "onlyAxis": { + "type": [ + "boolean", + "null" + ], + "description": "with rpm 0: stop only a spin about axis, and leave any other as it is" }, "at": { "type": [ @@ -4030,267 +4815,278 @@ "required": [ "op", "id", - "to", + "rpm", + "by", + "ratio", + "phase", + "axis", + "onlyAxis", "at", "dur" ], "additionalProperties": false, - "description": "Move a 3D object to an absolute position." + "description": "Make a part turn round its own axis and keep turning, until another spin on it says otherwise. rpm is turns a minute (negative the other way; 0 stops; dur is the time to get up to speed). Or give by, another part that drives it: it then turns ratio times as far as that part (0.5 half as fast, -1 a meshed gear) and phase degrees ahead. axis is x, y or z, default z (use y for a fan)." }, - "along": { + "crank": { "type": "object", "properties": { "op": { "enum": [ - "along" + "crank" + ] + }, + "piston": { + "type": [ + "string", + "null" ] }, "id": { + "type": [ + "string", + "null" + ], + "description": "the same as piston" + }, + "shaft": { "type": "string" }, - "pts": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "number" - } - }, - "description": "1 to 24 points [x,y,z]" + "rod": { + "type": [ + "string", + "null" + ] }, - "at": { + "pin": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "1 to 8" }, - "dur": { + "at": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" + "description": "seconds after the step starts; 0 to 60" } }, "required": [ "op", + "piston", "id", - "pts", - "at", - "dur" + "shaft", + "rod", + "pin", + "at" ], "additionalProperties": false, - "description": "Move a 3D object along a smooth path through the points, ending on the last." + "description": "Tie a piston to a spinning crankshaft through a connecting rod: the piston slides up and down its cylinder (along y, in the x,y plane) as the crank pin goes round, and the rod swings to join them. piston, shaft and rod are the ids of the piston (never the cylinder block), the crankshaft and the connecting rod, in one group, the crankshaft turning with spin. On a plain cylinder laid on its side as the crankshaft, the crank draws the pin and runs the rod on it in front of the disc: add no pin of your own. pin is which throw (1 is the first)." }, - "turn": { + "cam": { "type": "object", "properties": { "op": { "enum": [ - "turn" + "cam" + ] + }, + "valve": { + "type": [ + "string", + "null" ] }, "id": { + "type": [ + "string", + "null" + ], + "description": "the same as valve" + }, + "by": { "type": "string" }, - "to": { - "type": "array", - "items": { - "type": "number" - }, - "description": "[x,y,z], each -3600 to 3600" + "lift": { + "type": [ + "number", + "null" + ], + "description": "how far it moves down in units (default a fifth of its length); 0.01 to 50" }, - "at": { + "open": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "10 to 350" }, - "dur": { + "phase": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" + "description": "-3600 to 3600" + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" } }, "required": [ "op", + "valve", "id", - "to", - "at", - "dur" + "by", + "lift", + "open", + "phase", + "at" ], "additionalProperties": false, - "description": "Turn a 3D object to absolute angles in degrees; from [0,0,0], [0,360,0] is one full spin." + "description": "A valve (or any follower) that a spinning camshaft pushes down along y: it is down by lift while the cam nose points down at it, and back up otherwise. open is how many degrees of the turn of the cam it stays open (default 110), phase the cam angle where it is most open (default 180: the nose pointing down). valve is the id of the valve, by of the camshaft." }, - "scale": { + "flash": { "type": "object", "properties": { "op": { "enum": [ - "scale" + "flash" ] }, "id": { "type": "string" }, - "to": { - "type": "array", - "items": { - "type": "number" - }, - "description": "[x,y,z], each 0.01 to 100" + "by": { + "type": "string", + "description": "the part whose turning times it" }, - "at": { + "angle": { + "type": "number", + "description": "0 to 3600" + }, + "span": { + "type": "number", + "description": "1 to 720" + }, + "cycle": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "90 to 3600" }, - "dur": { + "at": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" + "description": "seconds after the step starts; 0 to 60" } }, "required": [ "op", "id", - "to", - "at", - "dur" + "by", + "angle", + "span", + "cycle", + "at" ], "additionalProperties": false, - "description": "Scale a 3D object to absolute factors [x,y,z] (1 is the size it was added at)." + "description": "A glow at one point of the cycle of a turning part: the object (a small sphere for a spark, a larger one for the burn) is invisible, flares to its opacity at the given angle and dies away over span degrees. by is the crankshaft; angle is degrees into a cycle of cycle degrees (default 720, a four-stroke engine: 0 is the piston at the top starting the intake, 360 the top of the compression)." }, - "explode": { + "loop": { "type": "object", "properties": { "op": { "enum": [ - "explode" + "loop" ] }, "id": { "type": "string" }, - "to": { - "type": "number", - "description": "0 to 3" + "kind": { + "enum": [ + "slide", + "swing", + "pulse", + "gate", + "float", + "stop", + null + ] }, - "at": { + "amount": { + "type": [ + "number", + "null" + ], + "description": "slide: positive total travel in units; swing: signed degrees each side (negative reverses the swing, zero holds still); pulse: positive size factor (1.3 is 30% bigger, 0.8 smaller); gate: degrees the hinge opens on half of each cycle; float: units it bobs up and down; -360 to 360" + }, + "damp": { + "type": [ + "number", + "null" + ], + "description": "cycles for the motion to fall to a third of its size, so it settles (a pendulum running down); left out, it never settles; 0.2 to 50" + }, + "tilt": { + "type": [ + "number", + "null" + ], + "description": "float: degrees it rocks from side to side about z (default 4); 0 to 30" + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null + ] + }, + "period": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "0.1 to 60" }, - "dur": { + "by": { "type": [ - "number", + "string", "null" - ], - "description": "seconds the change takes (default 0.6); 0 to 30" - } - }, - "required": [ - "op", - "id", - "to", - "at", - "dur" - ], - "additionalProperties": false, - "description": "Spread the parts of a group outward from its origin: 0 assembled, 1 apart (up to 3). A part that has its own explode offset moves by that offset times the spread instead. Back to 0 to assemble." - }, - "reveal": { - "type": "object", - "properties": { - "op": { - "enum": [ - "reveal" ] }, - "id": { - "type": "string" - }, - "to": { - "type": "number", - "description": "0 to 1" - }, - "at": { + "ratio": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "with by: cycles per turn (default 1); -20 to 20" }, - "dur": { + "phase": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" - } - }, - "required": [ - "op", - "id", - "to", - "at", - "dur" - ], - "additionalProperties": false, - "description": "Draw a tube, line or arrow on, from its start: to 1 is all of it." - }, - "anchor": { - "type": "object", - "properties": { - "op": { - "enum": [ - "anchor" - ] - }, - "id": { - "type": "string" - }, - "name": { - "type": "string", - "description": "up to 24 characters" + "description": "degrees ahead (180 is half a cycle behind another loop at 0); -3600 to 3600" }, - "pos": { - "type": "array", + "pivot": { + "type": [ + "array", + "null" + ], "items": { "type": "number" }, - "description": "[x,y,z], each -100 to 100" - } - }, - "required": [ - "op", - "id", - "name", - "pos" - ], - "additionalProperties": false, - "description": "Name a point on a 3D object, in its own space, for parentAnchor or selfAnchor: write it right after the object." - }, - "detach": { - "type": "object", - "properties": { - "op": { - "enum": [ - "detach" - ] - }, - "id": { - "type": "string" + "description": "swing: from the object to the point it turns about; [x,y,z], each -100 to 100" }, "at": { "type": [ @@ -4303,135 +5099,228 @@ "required": [ "op", "id", + "kind", + "amount", + "damp", + "tilt", + "axis", + "period", + "by", + "ratio", + "phase", + "pivot", "at" ], "additionalProperties": false, - "description": "Let an attached part go: it stays where it is and is placed on its own from then (no join line). To lift a part out and still show where it goes, move it instead." + "description": "Repeat a motion on any object: slide (back and forth along axis, positive amount units in all), swing (rock about axis by signed amount degrees each side, -180 to 180, about the hinge pivot; negative reverses it, zero holds still) or pulse (swell to positive amount times its size), every period seconds (default 2) or by a spinning part. Left out, kind is the joint's. Another loop replaces it; stop ends it. id is an object already in the scene, never a name for the loop." }, - "style": { + "joint": { "type": "object", "properties": { "op": { "enum": [ - "style" + "joint" ] }, "id": { "type": "string" }, - "color": { + "kind": { + "enum": [ + "hinge", + "slide", + "fixed", + "pivot", + "ball" + ] + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null + ] + }, + "dir": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "slide: the direction, [x,y,z]; [x,y,z], each -100 to 100" + }, + "pivot": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "hinge or ball: from the object to the point it turns about; [x,y,z], each -100 to 100" + }, + "about": { "type": [ "string", "null" ], - "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + "description": "hinge or ball: a point of the object by name (built in, a kit part own or one named with anchor) to turn about, instead of pivot; up to 24 characters" }, - "opacity": { + "limit": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "ball: how far each axis may turn each way, degrees [x,y,z]; [x,y,z], each 0 to 360" + }, + "min": { "type": [ "number", "null" ], - "description": "0 to 1" + "description": "-3600 to 3600" }, - "at": { + "max": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "-3600 to 3600" }, - "dur": { + "to": { + "type": [ + "string", + "null" + ], + "description": "fixed: the object it rides with" + }, + "at": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" + "description": "seconds after the step starts; 0 to 60" } }, "required": [ "op", "id", - "color", - "opacity", - "at", - "dur" + "kind", + "axis", + "dir", + "pivot", + "about", + "limit", + "min", + "max", + "to", + "at" ], "additionalProperties": false, - "description": "Change the colour and/or opacity of any object or mark; at least one of them." + "description": "Give any object a freedom: hinge (turns about axis through pivot, the point from the object), slide (along axis or a tilted dir: an inclined plane, a wedge), pivot (turns about its own long axis, axis y by default, through its own middle: a forearm, a screw, a tap), ball (turns about all three axes about its pivot point, held to limit [x,y,z] degrees each way: a shoulder, a hip; one swing loop or spin per axis drives it), fixed (rides with to). about names the point to turn about (any point of the part: left, top, a named one) instead of pivot. min and max hold its value. It moves when spin, loop or couple drives it." }, - "highlight": { + "couple": { "type": "object", "properties": { "op": { "enum": [ - "highlight" + "couple" ] }, "id": { "type": "string" }, - "color": { + "by": { "type": [ "string", "null" + ] + }, + "ratio": { + "type": [ + "number", + "null" ], - "description": "a colour name (red, orange, yellow, green, teal, blue, purple, pink, white, gray, black) or hex \"#rrggbb\"" + "description": "-100 to 100" }, - "at": { + "pitch": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "-100 to 100" }, - "dur": { + "phase": { "type": [ "number", "null" ], - "description": "seconds the change takes (default 0.6); 0 to 30" + "description": "-3600 to 3600" + }, + "stop": { + "type": [ + "boolean", + "null" + ] + }, + "at": { + "type": [ + "number", + "null" + ], + "description": "seconds after the step starts; 0 to 60" } }, "required": [ "op", "id", - "color", - "at", - "dur" + "by", + "ratio", + "pitch", + "phase", + "stop", + "at" ], "additionalProperties": false, - "description": "Pulse an object or mark to draw the eye, optionally in a colour." + "description": "One joint follows another: its value is ratio times that of by, plus phase. Use ratio between two of a kind (gear, belt, lever) and pitch between a hinge and a slide (units of travel for one turn: a screw, a rack, a rope on a wheel is 2 x pi x radius). stop ends it." }, - "spin": { + "lever": { "type": "object", "properties": { "op": { "enum": [ - "spin" + "lever" ] }, "id": { "type": "string" }, - "rpm": { + "fulcrum": { "type": [ - "number", + "string", "null" ], - "description": "-600 to 600" + "description": "up to 24 characters" }, - "by": { + "swing": { "type": [ - "string", + "number", "null" - ] + ], + "description": "1 to 90" }, - "ratio": { + "period": { "type": [ "number", "null" ], - "description": "-20 to 20" + "description": "0.1 to 60" }, "phase": { "type": [ @@ -4448,79 +5337,62 @@ null ] }, - "onlyAxis": { - "type": [ - "boolean", - "null" - ], - "description": "with rpm 0: stop only a spin about axis, and leave any other as it is" - }, "at": { "type": [ "number", "null" ], "description": "seconds after the step starts; 0 to 60" - }, - "dur": { - "type": [ - "number", - "null" - ], - "description": "seconds the change takes (default 0.6); 0 to 30" } }, "required": [ "op", "id", - "rpm", - "by", - "ratio", + "fulcrum", + "swing", + "period", "phase", "axis", - "onlyAxis", - "at", - "dur" + "at" ], "additionalProperties": false, - "description": "Make a part turn round its own axis and keep turning, until another spin on it says otherwise. rpm is turns a minute (negative the other way; 0 stops; dur is the time to get up to speed). Or give by, another part that drives it: it then turns ratio times as far as that part (0.5 half as fast, -1 a meshed gear) and phase degrees ahead. axis is x, y or z, default z (use y for a fan)." + "description": "A beam that rocks about a fulcrum: a hinge at fulcrum, a point of the beam (center, the default, is a seesaw, the first class; left or right, an end, with the load or the effort between it and the other end, the second and third class; or a point named with anchor), swinging swing degrees each side every period seconds. Attach the load and the effort at points of the beam (parentAnchor) and they rise and fall with it." }, - "crank": { + "muscle": { "type": "object", "properties": { "op": { "enum": [ - "crank" - ] - }, - "piston": { - "type": [ - "string", - "null" + "muscle" ] }, "id": { + "type": "string" + }, + "pulls": { + "type": "string", + "description": "the id of the part it pulls (an end of the connector), or from or to for that end; up to 40 characters" + }, + "contract": { "type": [ - "string", + "number", "null" ], - "description": "the same as piston" - }, - "shaft": { - "type": "string" + "description": "0.02 to 0.9" }, - "rod": { + "period": { "type": [ - "string", + "number", "null" - ] + ], + "description": "0.1 to 60" }, - "pin": { + "phase": { "type": [ "number", "null" ], - "description": "1 to 8" + "description": "-3600 to 3600" }, "at": { "type": [ @@ -4532,55 +5404,61 @@ }, "required": [ "op", - "piston", "id", - "shaft", - "rod", - "pin", + "pulls", + "contract", + "period", + "phase", "at" ], "additionalProperties": false, - "description": "Tie a piston to a spinning crankshaft through a connecting rod: the piston slides up and down its cylinder (along y, in the x,y plane) as the crank pin goes round, and the rod swings to join them. piston, shaft and rod are the ids of the piston (never the cylinder block), the crankshaft and the connecting rod. Put the three in one group, the crankshaft turning with spin. On a plain cylinder laid on its side as the crankshaft, the crank draws the pin and runs the rod on it in front of the disc: add no pin of your own. pin is which throw (1 is the first)." + "description": "A connector that is a muscle: it shortens by contract (a fraction of its relaxed length, 0.02 to 0.9; 0.1 to 0.25 for a limb) and lengthens again every period seconds, turning the part it pulls (pulls, the id of one of its two ends, or from or to; that part needs a hinge or pivot joint with min and max). Join the ends with fromPoint and toPoint or fromAnchor and toAnchor; its belly swells as it shortens (swell). id is the connector." }, - "cam": { + "pulley": { "type": "object", "properties": { "op": { "enum": [ - "cam" - ] - }, - "valve": { - "type": [ - "string", - "null" + "pulley" ] }, "id": { + "type": "string" + }, + "wheel": { + "type": "string" + }, + "radius": { "type": [ - "string", + "number", "null" ], - "description": "the same as valve" - }, - "by": { - "type": "string" + "description": "0.01 to 100" }, - "lift": { + "rpm": { "type": [ "number", "null" ], - "description": "how far it moves down in units (default a fifth of its length); 0.01 to 50" + "description": "-600 to 600" }, - "open": { + "axis": { + "enum": [ + "x", + "y", + "z", + null + ], + "description": "the axis the wheel turns about: left out, a cylinder turns about its own long axis as it lies and anything else about z" + }, + "min": { "type": [ "number", "null" ], - "description": "10 to 350" + "description": "-3600 to 3600" }, - "phase": { + "max": { "type": [ "number", "null" @@ -4597,46 +5475,62 @@ }, "required": [ "op", - "valve", "id", - "by", - "lift", - "open", - "phase", + "wheel", + "radius", + "rpm", + "axis", + "min", + "max", "at" ], "additionalProperties": false, - "description": "A valve (or any follower) that a spinning camshaft pushes down along y: it is down by lift while the cam nose points down at it, and back up otherwise. open is how many degrees of the turn of the cam it stays open (default 110), phase the cam angle where it is most open (default 180: the nose pointing down). valve is the id of the valve, by of the camshaft." + "description": "A rope over a wheel: the wheel (wheel) turns rpm turns a minute (negative the other way) and the load (id) rises by the rope laid on it, 2 x pi x radius for each turn, without end unless max stops it (the most it may rise, in units; min the least). radius is the rope's radius on the wheel, read from the wheel's size when left out. A winch, a crane drum and a wheel and axle (give the axle's radius) are the same." }, - "flash": { + "wave": { "type": "object", "properties": { "op": { "enum": [ - "flash" + "wave" ] }, "id": { "type": "string" }, - "by": { - "type": "string", - "description": "the part whose turning times it" + "amount": { + "type": [ + "number", + "null" + ], + "description": "0.2 to 4" }, - "angle": { - "type": "number", - "description": "0 to 3600" + "width": { + "type": [ + "number", + "null" + ], + "description": "0.03 to 0.6" }, - "span": { - "type": "number", - "description": "1 to 720" + "count": { + "type": [ + "number", + "null" + ], + "description": "1 to 6" }, - "cycle": { + "period": { "type": [ "number", "null" ], - "description": "90 to 3600" + "description": "-60 to 60" + }, + "stop": { + "type": [ + "boolean", + "null" + ] }, "at": { "type": [ @@ -4649,41 +5543,63 @@ "required": [ "op", "id", - "by", - "angle", - "span", - "cycle", + "amount", + "width", + "count", + "period", + "stop", "at" ], "additionalProperties": false, - "description": "A glow that comes on at one point of the cycle of a turning part: the object (a small sphere for a spark, a larger one for the burn) is invisible, flares to its opacity at the crank angle given and dies away over span degrees. by is the crankshaft; angle is degrees into a cycle of cycle degrees (default 720, a four-stroke engine: 0 is the piston at the top starting the intake, 360 the top of the compression)." + "description": "A wave running along an open tube: peristalsis, a pulse down a vessel. amount is the radius at its crest as a factor (above 1 a swell, below 1 a squeeze), width the fraction of the tube it spans, count how many run at once, period the seconds a crest takes for the whole tube (negative runs backwards). A one-marker stream along the same tube with the same period rides the crest (a mouthful going down). stop true ends it." }, - "loop": { + "pendulum": { "type": "object", "properties": { "op": { "enum": [ - "loop" + "pendulum" ] }, "id": { "type": "string" }, - "kind": { - "enum": [ - "slide", - "swing", - "pulse", - "stop", - null + "from": { + "type": [ + "string", + "null" ] }, - "amount": { + "pivot": { + "type": [ + "array", + "null" + ], + "items": { + "type": "number" + }, + "description": "[x,y,z], each -100 to 100" + }, + "swing": { + "type": [ + "number", + "null" + ], + "description": "1 to 90" + }, + "period": { + "type": [ + "number", + "null" + ], + "description": "0.1 to 60" + }, + "damp": { "type": [ "number", "null" ], - "description": "slide: positive total travel in units; swing: signed degrees each side (negative reverses the swing, zero holds still); pulse: positive size factor (1.3 is 30% bigger, 0.8 smaller); -360 to 360" + "description": "0.2 to 50" }, "axis": { "enum": [ @@ -4693,42 +5609,67 @@ null ] }, - "period": { + "at": { "type": [ "number", "null" ], - "description": "0.1 to 60" - }, - "by": { - "type": [ - "string", - "null" + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "id", + "from", + "pivot", + "swing", + "period", + "damp", + "axis", + "at" + ], + "additionalProperties": false, + "description": "A weight hanging from a point and swinging: id is the weight, from the part it hangs from (the swing is about its middle) or pivot, the point from the weight to the hang point. swing is degrees each side, period seconds (left out, longer for a longer string), damp cycles for it to settle. It starts let go at the far end. Draw the string as a connector between the two; hang it from a part that does not slide, and write the pendulum after any loop on its parts." + }, + "oscillate": { + "type": "object", + "properties": { + "op": { + "enum": [ + "oscillate" ] }, - "ratio": { + "id": { + "type": "string" + }, + "amount": { "type": [ "number", "null" ], - "description": "with by: cycles per turn (default 1); -20 to 20" + "description": "0.01 to 50" }, - "phase": { + "period": { "type": [ "number", "null" ], - "description": "degrees ahead (180 is half a cycle behind another loop at 0); -3600 to 3600" + "description": "0.1 to 60" }, - "pivot": { + "damp": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "swing: from the object to the point it turns about; [x,y,z], each -100 to 100" + "description": "0.2 to 50" + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null + ] }, "at": { "type": [ @@ -4741,172 +5682,179 @@ "required": [ "op", "id", - "kind", "amount", - "axis", "period", - "by", - "ratio", - "phase", - "pivot", + "damp", + "axis", "at" ], "additionalProperties": false, - "description": "Repeat a motion on any object: slide (back and forth along axis, positive amount units in all), swing (rock about axis by signed amount degrees each side, -180 to 180, about the hinge pivot; negative reverses it, zero holds still) or pulse (swell to positive amount times its size), every period seconds (default 2) or by a spinning part. Left out, kind is the joint's. Another loop replaces it; stop ends it. id is an object already in the scene, never a name for the loop." + "description": "A weight bobbing on a spring or elastic: it moves amount units each way along axis (default y) every period seconds, starting pulled to the low end and let go, and settles if damp (cycles to fall to a third) is given. Draw the spring or elastic as a connector from its fixed end to the weight." }, - "joint": { + "float": { "type": "object", "properties": { "op": { "enum": [ - "joint" + "float" ] }, "id": { "type": "string" }, - "kind": { - "enum": [ - "hinge", - "slide", - "fixed", - "pivot", - "ball" - ] - }, - "axis": { - "enum": [ - "x", - "y", - "z", - null - ] - }, - "dir": { + "bob": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "slide: the direction, [x,y,z]; [x,y,z], each -100 to 100" + "description": "0.01 to 20" }, - "pivot": { + "tilt": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "hinge or ball: from the object to the point it turns about; [x,y,z], each -100 to 100" + "description": "0 to 30" }, - "about": { + "period": { "type": [ - "string", + "number", "null" ], - "description": "hinge or ball: a point of the object by name (built in, a kit part own or one named with anchor) to turn about, instead of pivot; up to 24 characters" + "description": "0.1 to 60" }, - "limit": { + "damp": { "type": [ - "array", + "number", "null" ], - "items": { - "type": "number" - }, - "description": "ball: how far each axis may turn each way, degrees [x,y,z]; [x,y,z], each 0 to 360" + "description": "0.2 to 50" }, - "min": { + "at": { "type": [ "number", "null" ], - "description": "-3600 to 3600" + "description": "seconds after the step starts; 0 to 60" + } + }, + "required": [ + "op", + "id", + "bob", + "tilt", + "period", + "damp", + "at" + ], + "additionalProperties": false, + "description": "Buoyancy, illustrated: the part rides on water, bobbing bob units and rocking tilt degrees every period seconds. Put it at the water line first (drop does that); damp settles it." + }, + "drop": { + "type": "object", + "properties": { + "op": { + "enum": [ + "drop" + ] }, - "max": { + "id": { + "type": "string" + }, + "to": { + "type": "number", + "description": "-100 to 100" + }, + "bounce": { "type": [ "number", "null" ], - "description": "-3600 to 3600" + "description": "0 to 0.8" }, - "to": { + "at": { "type": [ - "string", + "number", "null" ], - "description": "fixed: the object it rides with" + "description": "seconds after the step starts; 0 to 60" }, - "at": { + "dur": { "type": [ "number", "null" ], - "description": "seconds after the step starts; 0 to 60" + "description": "seconds the change takes (default 0.6); 0 to 30" } }, "required": [ "op", "id", - "kind", - "axis", - "dir", - "pivot", - "about", - "limit", - "min", - "max", "to", - "at" + "bounce", + "at", + "dur" ], "additionalProperties": false, - "description": "Give any object a freedom: hinge (turns about axis through pivot, the point from the object), slide (along axis or a tilted dir: an inclined plane, a wedge), pivot (turns about its own long axis, axis y by default, through its own middle: a forearm, a screw, a tap), ball (turns about all three axes about its pivot point, held to limit [x,y,z] degrees each way: a shoulder, a hip; one swing loop or spin per axis drives it), fixed (rides with to). about names the point to turn about (any point of the part: left, top, a named one) instead of pivot. min and max hold its value. It moves when spin, loop or couple drives it." + "description": "Gravity, illustrated: the part falls to height to (y, in the units of the group it is in) with an ever faster pull, and bounces bounce (0 lands dead, 0.8 very springy) times lower each time until it settles. dur left out, it takes as long as the fall." }, - "couple": { + "pump": { "type": "object", "properties": { "op": { "enum": [ - "couple" + "pump" ] }, "id": { "type": "string" }, - "by": { + "inlet": { "type": [ "string", "null" ] }, - "ratio": { + "outlet": { + "type": [ + "string", + "null" + ] + }, + "squeeze": { "type": [ "number", "null" ], - "description": "-100 to 100" + "description": "0.3 to 0.95" }, - "pitch": { + "open": { "type": [ "number", "null" ], - "description": "-100 to 100" + "description": "-170 to 170" }, - "phase": { + "period": { "type": [ "number", "null" ], - "description": "-3600 to 3600" + "description": "0.2 to 20" }, - "stop": { + "hinge": { "type": [ - "boolean", + "string", "null" + ], + "description": "up to 24 characters" + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null ] }, "at": { @@ -4920,62 +5868,55 @@ "required": [ "op", "id", - "by", - "ratio", - "pitch", - "phase", - "stop", + "inlet", + "outlet", + "squeeze", + "open", + "period", + "hinge", + "axis", "at" ], "additionalProperties": false, - "description": "One joint follows another: its value is ratio times that of by, plus phase. Use ratio between two of a kind (gear, belt, lever) and pitch between a hinge and a slide (units of travel for one turn: a screw, a rack, a rope on a wheel is 2 x pi x radius). stop ends it." + "description": "A chamber that squeezes and refills behind one-way valves, for a heart or a bellows: id is the chamber (it shrinks to squeeze of its size, then refills, every period seconds), inlet the flap that opens while it refills and outlet the flap that opens while it squeezes. Each valve turns about its hinge point (a named point of the valve, default left) by open degrees (negative the other way)." }, - "lever": { + "incline": { "type": "object", "properties": { "op": { "enum": [ - "lever" + "incline" ] }, "id": { "type": "string" }, - "fulcrum": { + "ramp": { "type": [ "string", "null" - ], - "description": "up to 24 characters" + ] }, - "swing": { + "angle": { "type": [ "number", "null" ], - "description": "1 to 90" + "description": "-80 to 80" }, - "period": { + "travel": { "type": [ "number", "null" ], - "description": "0.1 to 60" + "description": "0.1 to 100" }, - "phase": { + "period": { "type": [ "number", "null" ], - "description": "-3600 to 3600" - }, - "axis": { - "enum": [ - "x", - "y", - "z", - null - ] + "description": "0.1 to 60" }, "at": { "type": [ @@ -4988,51 +5929,57 @@ "required": [ "op", "id", - "fulcrum", - "swing", + "ramp", + "angle", + "travel", "period", - "phase", - "axis", "at" ], "additionalProperties": false, - "description": "A beam that rocks about a fulcrum: a hinge at fulcrum, a point of the beam (center, the default, is a seesaw and the first class; left or right, an end, with the load or the effort between it and the other end, is the second and third class; or a point named with anchor), swinging swing degrees each side every period seconds. Attach the load and the effort at points of the beam (parentAnchor) and they rise and fall with it." + "description": "An inclined plane: the load (id) slides up and down the slope, travel units in all, every period seconds. The slope is the turn of the ramp (a box turned about z; its length runs along x), or angle degrees." }, - "muscle": { + "wedge": { "type": "object", "properties": { "op": { "enum": [ - "muscle" + "wedge" ] }, "id": { "type": "string" }, - "pulls": { - "type": "string", - "description": "the id of the part it pulls (an end of the connector), or from or to for that end; up to 40 characters" + "drives": { + "type": "string" }, - "contract": { + "angle": { "type": [ "number", "null" ], - "description": "0.02 to 0.9" + "description": "3 to 70" }, - "period": { + "travel": { "type": [ "number", "null" ], - "description": "0.1 to 60" + "description": "0.1 to 100" }, - "phase": { + "period": { "type": [ "number", "null" ], - "description": "-3600 to 3600" + "description": "0.1 to 60" + }, + "axis": { + "enum": [ + "x", + "y", + "z", + null + ] }, "at": { "type": [ @@ -5045,35 +5992,36 @@ "required": [ "op", "id", - "pulls", - "contract", + "drives", + "angle", + "travel", "period", - "phase", + "axis", "at" ], "additionalProperties": false, - "description": "A connector that is a muscle: it shortens by contract (a fraction of its relaxed length, 0.02 to 0.9, default 0.2) and lengthens again every period seconds (default 2), and the part it pulls (pulls, the id of one of its two ends, or from or to, with a hinge or pivot joint with min and max to hold it) is turned by it, not beside it. Join the ends with fromPoint and toPoint or fromAnchor and toAnchor; its belly swells as it shortens (swell). id is the connector." + "description": "A wedge driven in along axis (default y), travel units in all every period seconds, pushing the part it drives (drives) aside across axis by tan(angle) of its own travel, angle being the wedge's half angle in degrees (default 20): an axe in a log, a door stop. Put the driven part on the side of the wedge it is to be pushed to; write it again for the other side." }, - "pulley": { + "screw": { "type": "object", "properties": { "op": { "enum": [ - "pulley" + "screw" ] }, "id": { "type": "string" }, - "wheel": { + "screw": { "type": "string" }, - "radius": { + "pitch": { "type": [ "number", "null" ], - "description": "0.01 to 100" + "description": "-20 to 20" }, "rpm": { "type": [ @@ -5088,8 +6036,21 @@ "y", "z", null + ] + }, + "min": { + "type": [ + "number", + "null" ], - "description": "the axis the wheel turns about: left out, a cylinder turns about its own long axis as it lies and anything else about z" + "description": "-3600 to 3600" + }, + "max": { + "type": [ + "number", + "null" + ], + "description": "-3600 to 3600" }, "at": { "type": [ @@ -5102,14 +6063,16 @@ "required": [ "op", "id", - "wheel", - "radius", + "screw", + "pitch", "rpm", "axis", + "min", + "max", "at" ], "additionalProperties": false, - "description": "A rope over a wheel: the wheel (wheel) turns rpm turns a minute (default 20, negative the other way) and the load (id) rises by the rope laid on it, 2 x pi x radius for each turn. radius is the rope's radius on the wheel, read from the wheel's size when left out. A winch, a crane drum and a wheel and axle (give the axle's radius) are the same." + "description": "A screw and its nut: the screw (screw) turns rpm turns a minute and the nut (id) travels along its length pitch units for each turn (negative the other way), without end unless max stops it (the most it may travel, in units; min the least). A cylinder turns about its own long axis as it lies; axis says otherwise." }, "cut": { "type": "object", @@ -5169,7 +6132,7 @@ "dur" ], "additionalProperties": false, - "description": "Cut a 3D object and its children open. Choose axis x/y/z or normal [x,y,z], never both. normal is a nonzero local direction with finite components from -100 to 100; magnitude is ignored. to is signed distance along that unit direction from the local origin (not necessarily the center of a hull point cloud); the positive side is removed. Omit direction to keep the active cut direction (initially +z). Direction changes at the action start; only to animates. Closed opaque pieces are capped; open surfaces are not. to 100 removes the cut." + "description": "Cut a 3D object and its children open. Choose axis x/y/z or normal [x,y,z] (a nonzero local direction, components -100 to 100, magnitude ignored), never both. to is the signed distance along that unit direction from the local origin (not necessarily the centre of a hull); the positive side is removed, and to 100 removes the cut. Omit the direction to keep the active one (initially +z); it changes at the action's start, only to animates. Closed opaque pieces are capped; open surfaces are not." }, "orbit": { "type": "object", @@ -5380,7 +6343,7 @@ "dir" ], "additionalProperties": false, - "description": "Guide mode, optional: let the app make one navigation move for the person, in a step that points at it (the wait stays: if the app does not do it, they click). kind is tab (a tab), open (a menu item that opens a submenu) or scroll (a window or area; dir down by default). x,y is the middle of that control on the screenshot (anywhere in the area for scroll). The app does it only in a native window, only if the person has allowed it, says so aloud first, and refuses everything that is not exactly this (a button, a link, a checkbox, a field, anything that saves, sends, deletes or buys). At most one a step." + "description": "Guide mode, optional: let the app make one navigation move for the person, in a step that points at it (the wait stays: if the app does not do it, they click). kind is tab, open (a menu item that opens a submenu) or scroll (dir down by default); x,y is the middle of that control on the screenshot (anywhere in the area for scroll). Only in a native window and only if the person has allowed it; the app says so aloud first and refuses anything else (a button, link, checkbox, field, anything that saves, sends, deletes or buys). At most one a step." }, "clear": { "type": "object", @@ -5502,6 +6465,15 @@ { "$ref": "#/$defs/addStream" }, + { + "$ref": "#/$defs/addParticles" + }, + { + "$ref": "#/$defs/addForce" + }, + { + "$ref": "#/$defs/addField" + }, { "$ref": "#/$defs/addPart" }, @@ -5577,6 +6549,33 @@ { "$ref": "#/$defs/pulley" }, + { + "$ref": "#/$defs/wave" + }, + { + "$ref": "#/$defs/pendulum" + }, + { + "$ref": "#/$defs/oscillate" + }, + { + "$ref": "#/$defs/float" + }, + { + "$ref": "#/$defs/drop" + }, + { + "$ref": "#/$defs/pump" + }, + { + "$ref": "#/$defs/incline" + }, + { + "$ref": "#/$defs/wedge" + }, + { + "$ref": "#/$defs/screw" + }, { "$ref": "#/$defs/cut" }, diff --git a/docs/scene.schema.lean.json b/docs/scene.schema.lean.json index c2bf784..eab928b 100644 --- a/docs/scene.schema.lean.json +++ b/docs/scene.schema.lean.json @@ -4,7 +4,7 @@ "steps": { "type": "array", "items": { - "$ref": "#/$defs/1x" + "$ref": "#/$defs/29" } }, "escalate": { @@ -42,6 +42,12 @@ } }, "3": { + "type": [ + "boolean", + "null" + ] + }, + "4": { "type": "array", "items": { "type": "array", @@ -50,12 +56,6 @@ } } }, - "4": { - "type": [ - "boolean", - "null" - ] - }, "5": { "enum": [ "plastic", @@ -138,7 +138,7 @@ "$ref": "#/$defs/1" }, "pts": { - "$ref": "#/$defs/3" + "$ref": "#/$defs/4" }, "color": { "$ref": "#/$defs/1" @@ -350,6 +350,12 @@ }, "at": { "$ref": "#/$defs/0" + }, + "surge": { + "$ref": "#/$defs/0" + }, + "beat": { + "$ref": "#/$defs/0" } }, "required": [ @@ -367,11 +373,217 @@ "by", "ratio", "opacity", - "at" + "at", + "surge", + "beat" ], "additionalProperties": false }, "13": { + "type": "object", + "properties": { + "op": { + "enum": [ + "add" + ] + }, + "shape": { + "enum": [ + "particles" + ] + }, + "id": { + "type": "string" + }, + "parent": { + "$ref": "#/$defs/1" + }, + "pos": { + "$ref": "#/$defs/2" + }, + "count": { + "$ref": "#/$defs/0" + }, + "from": { + "$ref": "#/$defs/7" + }, + "to": { + "$ref": "#/$defs/7" + }, + "shift": { + "$ref": "#/$defs/2" + }, + "size": { + "$ref": "#/$defs/0" + }, + "jitter": { + "$ref": "#/$defs/0" + }, + "period": { + "$ref": "#/$defs/0" + }, + "color": { + "$ref": "#/$defs/1" + }, + "draw": { + "$ref": "#/$defs/0" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "shape", + "id", + "parent", + "pos", + "count", + "from", + "to", + "shift", + "size", + "jitter", + "period", + "color", + "draw", + "opacity", + "at" + ], + "additionalProperties": false + }, + "14": { + "type": "object", + "properties": { + "op": { + "enum": [ + "add" + ] + }, + "shape": { + "enum": [ + "force" + ] + }, + "id": { + "type": "string" + }, + "on": { + "type": "string" + }, + "point": { + "$ref": "#/$defs/1" + }, + "dir": { + "$ref": "#/$defs/7" + }, + "strength": { + "type": "number" + }, + "color": { + "$ref": "#/$defs/1" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "shape", + "id", + "on", + "point", + "dir", + "strength", + "color", + "opacity", + "at" + ], + "additionalProperties": false + }, + "15": { + "type": "object", + "properties": { + "op": { + "enum": [ + "add" + ] + }, + "shape": { + "enum": [ + "field" + ] + }, + "id": { + "type": "string" + }, + "parent": { + "$ref": "#/$defs/1" + }, + "pos": { + "$ref": "#/$defs/2" + }, + "kind": { + "enum": [ + "dipole", + "radial", + "uniform" + ] + }, + "axis": { + "enum": [ + "x", + "y", + null + ] + }, + "size": { + "$ref": "#/$defs/0" + }, + "count": { + "$ref": "#/$defs/0" + }, + "gap": { + "$ref": "#/$defs/0" + }, + "flip": { + "$ref": "#/$defs/3" + }, + "color": { + "$ref": "#/$defs/1" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "shape", + "id", + "parent", + "pos", + "kind", + "axis", + "size", + "count", + "gap", + "flip", + "color", + "opacity", + "at" + ], + "additionalProperties": false + }, + "16": { "type": "object", "properties": { "op": { @@ -477,7 +689,7 @@ ], "additionalProperties": false }, - "14": { + "17": { "type": "object", "properties": { "op": { @@ -521,7 +733,7 @@ ], "additionalProperties": false }, - "15": { + "18": { "type": "object", "properties": { "op": { @@ -577,7 +789,7 @@ ], "additionalProperties": false }, - "16": { + "19": { "type": "object", "properties": { "op": { @@ -625,34 +837,34 @@ ], "additionalProperties": false }, - "17": { + "20": { "type": "object", "properties": { "op": { "enum": [ - "pin" + "screw" ] }, "id": { "type": "string" }, - "on": { + "screw": { "type": "string" }, - "point": { - "$ref": "#/$defs/2" + "pitch": { + "$ref": "#/$defs/0" }, - "anchor": { - "$ref": "#/$defs/1" + "rpm": { + "$ref": "#/$defs/0" }, - "text": { - "type": "string" + "axis": { + "$ref": "#/$defs/6" }, - "off": { - "$ref": "#/$defs/2" + "min": { + "$ref": "#/$defs/0" }, - "color": { - "$ref": "#/$defs/1" + "max": { + "$ref": "#/$defs/0" }, "at": { "$ref": "#/$defs/0" @@ -661,32 +873,36 @@ "required": [ "op", "id", - "on", - "point", - "anchor", - "text", - "off", - "color", + "screw", + "pitch", + "rpm", + "axis", + "min", + "max", "at" ], "additionalProperties": false }, - "18": { + "21": { "type": "object", "properties": { "op": { "enum": [ - "move", - "turn", - "scale" + "cut" ] }, "id": { "type": "string" }, - "to": { - "$ref": "#/$defs/7" - }, + "axis": { + "$ref": "#/$defs/6" + }, + "normal": { + "$ref": "#/$defs/2" + }, + "to": { + "type": "number" + }, "at": { "$ref": "#/$defs/0" }, @@ -697,25 +913,27 @@ "required": [ "op", "id", + "axis", + "normal", "to", "at", "dur" ], "additionalProperties": false }, - "19": { + "22": { "type": "object", "properties": { "op": { "enum": [ - "along" + "orbit" ] }, - "id": { - "type": "string" + "az": { + "type": "number" }, - "pts": { - "$ref": "#/$defs/3" + "el": { + "type": "number" }, "at": { "$ref": "#/$defs/0" @@ -726,180 +944,115 @@ }, "required": [ "op", - "id", - "pts", + "az", + "el", "at", "dur" ], "additionalProperties": false }, - "a": { + "23": { "type": "object", "properties": { "op": { "enum": [ - "box", - "circle" + "zoom" ] }, - "id": { - "type": "string" - }, - "x": { - "type": "number" - }, - "y": { - "type": "number" - }, - "w": { - "type": "number" - }, - "h": { + "to": { "type": "number" }, - "rot": { + "at": { "$ref": "#/$defs/0" }, - "color": { - "type": "string" - }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", - "id", - "x", - "y", - "w", - "h", - "rot", - "color", - "at" + "to", + "at", + "dur" ], "additionalProperties": false }, - "b": { + "24": { "type": "object", "properties": { "op": { "enum": [ - "underline" + "focus" ] }, "id": { - "type": "string" - }, - "x": { - "type": "number" - }, - "y": { - "type": "number" - }, - "w": { - "type": "number" - }, - "color": { - "type": "string" + "$ref": "#/$defs/1" }, "at": { "$ref": "#/$defs/0" + }, + "dur": { + "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "x", - "y", - "w", - "color", - "at" + "at", + "dur" ], "additionalProperties": false }, - "c": { + "25": { "type": "object", "properties": { "op": { "enum": [ - "arrow" + "wait" ] }, - "id": { - "type": "string" - }, - "x1": { - "type": "number" - }, - "y1": { - "type": "number" - }, - "x2": { - "type": "number" - }, - "y2": { - "type": "number" - }, - "color": { - "type": "string" - }, - "at": { - "$ref": "#/$defs/0" - } - }, - "required": [ - "op", - "id", - "x1", - "y1", - "x2", - "y2", - "color", - "at" - ], - "additionalProperties": false - }, - "d": { - "type": "object", - "properties": { - "op": { + "for": { "enum": [ - "poly" + "click" ] }, - "id": { - "type": "string" + "x": { + "$ref": "#/$defs/0" }, - "pts": { - "$ref": "#/$defs/3" + "y": { + "$ref": "#/$defs/0" }, - "color": { - "type": "string" + "w": { + "$ref": "#/$defs/0" }, - "at": { + "h": { "$ref": "#/$defs/0" } }, "required": [ "op", - "id", - "pts", - "color", - "at" + "for", + "x", + "y", + "w", + "h" ], "additionalProperties": false }, - "e": { + "26": { "type": "object", "properties": { "op": { "enum": [ - "point" + "go" ] }, - "id": { - "type": "string" + "kind": { + "enum": [ + "tab", + "open", + "scroll" + ] }, "x": { "type": "number" @@ -907,45 +1060,34 @@ "y": { "type": "number" }, - "color": { - "type": "string" - }, - "cell": { - "$ref": "#/$defs/1" - }, - "at": { - "$ref": "#/$defs/0" + "dir": { + "enum": [ + "down", + "up", + "left", + "right", + null + ] } }, "required": [ "op", - "id", + "kind", "x", "y", - "color", - "cell", - "at" + "dir" ], "additionalProperties": false }, - "f": { + "27": { "type": "object", "properties": { "op": { "enum": [ - "trace" + "clear" ] }, - "id": { - "type": "string" - }, - "pts": { - "$ref": "#/$defs/3" - }, - "head": { - "$ref": "#/$defs/4" - }, - "color": { + "target": { "type": "string" }, "at": { @@ -954,62 +1096,251 @@ }, "required": [ "op", - "id", - "pts", - "head", - "color", + "target", "at" ], "additionalProperties": false }, - "g": { - "type": "object", - "properties": { - "op": { - "enum": [ - "label" - ] + "28": { + "anyOf": [ + { + "$ref": "#/$defs/a" }, - "id": { - "type": "string" + { + "$ref": "#/$defs/b" }, - "x": { - "type": "number" + { + "$ref": "#/$defs/c" }, - "y": { - "type": "number" + { + "$ref": "#/$defs/d" }, - "text": { - "type": "string" + { + "$ref": "#/$defs/e" }, - "color": { - "type": "string" + { + "$ref": "#/$defs/f" }, - "size": { - "$ref": "#/$defs/0" + { + "$ref": "#/$defs/g" }, - "at": { - "$ref": "#/$defs/0" - } - }, - "required": [ - "op", - "id", - "x", - "y", - "text", - "color", - "size", - "at" - ], + { + "$ref": "#/$defs/h" + }, + { + "$ref": "#/$defs/i" + }, + { + "$ref": "#/$defs/j" + }, + { + "$ref": "#/$defs/k" + }, + { + "$ref": "#/$defs/l" + }, + { + "$ref": "#/$defs/m" + }, + { + "$ref": "#/$defs/n" + }, + { + "$ref": "#/$defs/o" + }, + { + "$ref": "#/$defs/p" + }, + { + "$ref": "#/$defs/q" + }, + { + "$ref": "#/$defs/r" + }, + { + "$ref": "#/$defs/s" + }, + { + "$ref": "#/$defs/t" + }, + { + "$ref": "#/$defs/u" + }, + { + "$ref": "#/$defs/v" + }, + { + "$ref": "#/$defs/w" + }, + { + "$ref": "#/$defs/x" + }, + { + "$ref": "#/$defs/y" + }, + { + "$ref": "#/$defs/z" + }, + { + "$ref": "#/$defs/10" + }, + { + "$ref": "#/$defs/11" + }, + { + "$ref": "#/$defs/12" + }, + { + "$ref": "#/$defs/13" + }, + { + "$ref": "#/$defs/14" + }, + { + "$ref": "#/$defs/15" + }, + { + "$ref": "#/$defs/16" + }, + { + "$ref": "#/$defs/17" + }, + { + "$ref": "#/$defs/18" + }, + { + "$ref": "#/$defs/19" + }, + { + "$ref": "#/$defs/1a" + }, + { + "$ref": "#/$defs/1b" + }, + { + "$ref": "#/$defs/1c" + }, + { + "$ref": "#/$defs/1d" + }, + { + "$ref": "#/$defs/1e" + }, + { + "$ref": "#/$defs/1f" + }, + { + "$ref": "#/$defs/1g" + }, + { + "$ref": "#/$defs/1h" + }, + { + "$ref": "#/$defs/1i" + }, + { + "$ref": "#/$defs/1j" + }, + { + "$ref": "#/$defs/1k" + }, + { + "$ref": "#/$defs/1l" + }, + { + "$ref": "#/$defs/1m" + }, + { + "$ref": "#/$defs/1n" + }, + { + "$ref": "#/$defs/1o" + }, + { + "$ref": "#/$defs/1p" + }, + { + "$ref": "#/$defs/1q" + }, + { + "$ref": "#/$defs/1r" + }, + { + "$ref": "#/$defs/1s" + }, + { + "$ref": "#/$defs/1t" + }, + { + "$ref": "#/$defs/1u" + }, + { + "$ref": "#/$defs/1v" + }, + { + "$ref": "#/$defs/1w" + }, + { + "$ref": "#/$defs/1x" + }, + { + "$ref": "#/$defs/1y" + }, + { + "$ref": "#/$defs/1z" + }, + { + "$ref": "#/$defs/20" + }, + { + "$ref": "#/$defs/21" + }, + { + "$ref": "#/$defs/22" + }, + { + "$ref": "#/$defs/23" + }, + { + "$ref": "#/$defs/24" + }, + { + "$ref": "#/$defs/25" + }, + { + "$ref": "#/$defs/26" + }, + { + "$ref": "#/$defs/27" + } + ] + }, + "29": { + "type": "object", + "properties": { + "say": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/$defs/28" + } + } + }, + "required": [ + "say", + "actions" + ], "additionalProperties": false }, - "h": { + "a": { "type": "object", "properties": { "op": { "enum": [ - "card" + "box", + "circle" ] }, "id": { @@ -1022,33 +1353,16 @@ "type": "number" }, "w": { - "$ref": "#/$defs/0" - }, - "title": { - "$ref": "#/$defs/1" - }, - "rows": { - "type": [ - "array", - "null" - ], - "items": { - "type": "string" - } + "type": "number" }, - "layout": { - "enum": [ - "list", - "timeline", - "stat", - null - ] + "h": { + "type": "number" }, - "to": { - "$ref": "#/$defs/2" + "rot": { + "$ref": "#/$defs/0" }, "color": { - "$ref": "#/$defs/1" + "type": "string" }, "at": { "$ref": "#/$defs/0" @@ -1060,52 +1374,35 @@ "x", "y", "w", - "title", - "rows", - "layout", - "to", + "h", + "rot", "color", "at" ], "additionalProperties": false }, - "i": { + "b": { "type": "object", "properties": { "op": { "enum": [ - "image" + "underline" ] }, "id": { "type": "string" }, - "sx": { - "type": "number" - }, - "sy": { - "type": "number" - }, - "sw": { + "x": { "type": "number" }, - "sh": { + "y": { "type": "number" }, - "dx": { + "w": { "type": "number" }, - "dy": { - "type": "number" - }, - "dw": { - "type": "number" - }, - "caption": { - "$ref": "#/$defs/1" - }, - "color": { - "$ref": "#/$defs/1" + "color": { + "type": "string" }, "at": { "$ref": "#/$defs/0" @@ -1114,67 +1411,39 @@ "required": [ "op", "id", - "sx", - "sy", - "sw", - "sh", - "dx", - "dy", - "dw", - "caption", + "x", + "y", + "w", "color", "at" ], "additionalProperties": false }, - "j": { + "c": { "type": "object", "properties": { "op": { "enum": [ - "diagram" + "arrow" ] }, "id": { "type": "string" }, - "kind": { - "enum": [ - "flow", - "timeline", - "steps", - "chart" - ] - }, - "x": { + "x1": { "type": "number" }, - "y": { + "y1": { "type": "number" }, - "w": { + "x2": { "type": "number" }, - "h": { + "y2": { "type": "number" }, - "title": { - "$ref": "#/$defs/1" - }, - "xlabel": { - "$ref": "#/$defs/1" - }, - "ylabel": { - "$ref": "#/$defs/1" - }, - "xrange": { - "$ref": "#/$defs/2" - }, - "yrange": { - "$ref": "#/$defs/2" - }, "color": { - "$ref": "#/$defs/1" + "type": "string" }, "at": { "$ref": "#/$defs/0" @@ -1183,49 +1452,31 @@ "required": [ "op", "id", - "kind", - "x", - "y", - "w", - "h", - "title", - "xlabel", - "ylabel", - "xrange", - "yrange", + "x1", + "y1", + "x2", + "y2", "color", "at" ], "additionalProperties": false }, - "k": { + "d": { "type": "object", "properties": { "op": { "enum": [ - "node" + "poly" ] }, "id": { "type": "string" }, - "of": { - "type": "string" - }, - "text": { - "type": "string" - }, - "note": { - "$ref": "#/$defs/1" - }, - "when": { - "$ref": "#/$defs/1" - }, - "pos": { - "$ref": "#/$defs/0" + "pts": { + "$ref": "#/$defs/4" }, "color": { - "$ref": "#/$defs/1" + "type": "string" }, "at": { "$ref": "#/$defs/0" @@ -1234,37 +1485,33 @@ "required": [ "op", "id", - "of", - "text", - "note", - "when", - "pos", + "pts", "color", "at" ], "additionalProperties": false }, - "l": { + "e": { "type": "object", "properties": { "op": { "enum": [ - "edge" + "point" ] }, "id": { "type": "string" }, - "from": { - "type": "string" - }, - "to": { - "type": "string" + "x": { + "type": "number" }, - "text": { - "$ref": "#/$defs/1" + "y": { + "type": "number" }, "color": { + "type": "string" + }, + "cell": { "$ref": "#/$defs/1" }, "at": { @@ -1274,39 +1521,33 @@ "required": [ "op", "id", - "from", - "to", - "text", + "x", + "y", "color", + "cell", "at" ], "additionalProperties": false }, - "m": { + "f": { "type": "object", "properties": { "op": { "enum": [ - "series" + "trace" ] }, "id": { "type": "string" }, - "of": { - "type": "string" - }, "pts": { - "$ref": "#/$defs/3" - }, - "label": { - "$ref": "#/$defs/1" - }, - "curve": { "$ref": "#/$defs/4" }, + "head": { + "$ref": "#/$defs/3" + }, "color": { - "$ref": "#/$defs/1" + "type": "string" }, "at": { "$ref": "#/$defs/0" @@ -1315,29 +1556,24 @@ "required": [ "op", "id", - "of", "pts", - "label", - "curve", + "head", "color", "at" ], "additionalProperties": false }, - "n": { + "g": { "type": "object", "properties": { "op": { "enum": [ - "dot" + "label" ] }, "id": { "type": "string" }, - "of": { - "type": "string" - }, "x": { "type": "number" }, @@ -1345,10 +1581,13 @@ "type": "number" }, "text": { - "$ref": "#/$defs/1" + "type": "string" }, "color": { - "$ref": "#/$defs/1" + "type": "string" + }, + "size": { + "$ref": "#/$defs/0" }, "at": { "$ref": "#/$defs/0" @@ -1357,49 +1596,26 @@ "required": [ "op", "id", - "of", "x", "y", "text", "color", + "size", "at" ], "additionalProperties": false }, - "o": { + "h": { "type": "object", "properties": { "op": { "enum": [ - "tick" + "card" ] }, "id": { "type": "string" }, - "done": { - "$ref": "#/$defs/4" - }, - "at": { - "$ref": "#/$defs/0" - } - }, - "required": [ - "op", - "id", - "done", - "at" - ], - "additionalProperties": false - }, - "p": { - "type": "object", - "properties": { - "op": { - "enum": [ - "panel" - ] - }, "x": { "type": "number" }, @@ -1407,98 +1623,90 @@ "type": "number" }, "w": { - "type": "number" + "$ref": "#/$defs/0" }, - "h": { - "type": "number" + "title": { + "$ref": "#/$defs/1" }, - "frame": { - "$ref": "#/$defs/4" + "rows": { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } }, - "at": { - "$ref": "#/$defs/0" + "layout": { + "enum": [ + "list", + "timeline", + "stat", + null + ] }, - "dur": { + "to": { + "$ref": "#/$defs/2" + }, + "color": { + "$ref": "#/$defs/1" + }, + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", + "id", "x", "y", "w", - "h", - "frame", - "at", - "dur" + "title", + "rows", + "layout", + "to", + "color", + "at" ], "additionalProperties": false }, - "q": { + "i": { "type": "object", "properties": { "op": { "enum": [ - "add" - ] - }, - "shape": { - "enum": [ - "box", - "sphere", - "cylinder", - "cone", - "torus", - "plane" + "image" ] }, "id": { "type": "string" }, - "parent": { - "$ref": "#/$defs/1" + "sx": { + "type": "number" }, - "parentAnchor": { - "$ref": "#/$defs/1" + "sy": { + "type": "number" }, - "selfAnchor": { - "$ref": "#/$defs/1" + "sw": { + "type": "number" }, - "pos": { - "$ref": "#/$defs/2" - }, - "size": { - "$ref": "#/$defs/7" - }, - "rot": { - "$ref": "#/$defs/2" - }, - "color": { - "$ref": "#/$defs/1" - }, - "material": { - "$ref": "#/$defs/5" - }, - "roughness": { - "$ref": "#/$defs/0" - }, - "metalness": { - "$ref": "#/$defs/0" + "sh": { + "type": "number" }, - "clearcoat": { - "$ref": "#/$defs/0" + "dx": { + "type": "number" }, - "clearcoatRoughness": { - "$ref": "#/$defs/0" + "dy": { + "type": "number" }, - "bevel": { - "$ref": "#/$defs/0" + "dw": { + "type": "number" }, - "edges": { - "$ref": "#/$defs/4" + "caption": { + "$ref": "#/$defs/1" }, - "opacity": { - "$ref": "#/$defs/0" + "color": { + "$ref": "#/$defs/1" }, "at": { "$ref": "#/$defs/0" @@ -1506,296 +1714,242 @@ }, "required": [ "op", - "shape", "id", - "parent", - "parentAnchor", - "selfAnchor", - "pos", - "size", - "rot", + "sx", + "sy", + "sw", + "sh", + "dx", + "dy", + "dw", + "caption", "color", - "material", - "roughness", - "metalness", - "clearcoat", - "clearcoatRoughness", - "bevel", - "edges", - "opacity", "at" ], "additionalProperties": false }, - "r": { + "j": { "type": "object", "properties": { "op": { "enum": [ - "add" + "diagram" ] }, - "shape": { + "id": { + "type": "string" + }, + "kind": { "enum": [ - "shell" + "flow", + "timeline", + "steps", + "chart" ] }, - "id": { - "type": "string" + "x": { + "type": "number" }, - "parent": { - "$ref": "#/$defs/1" + "y": { + "type": "number" }, - "parentAnchor": { + "w": { + "type": "number" + }, + "h": { + "type": "number" + }, + "title": { "$ref": "#/$defs/1" }, - "selfAnchor": { + "xlabel": { "$ref": "#/$defs/1" }, - "pos": { - "$ref": "#/$defs/2" + "ylabel": { + "$ref": "#/$defs/1" }, - "rot": { + "xrange": { "$ref": "#/$defs/2" }, - "size": { - "$ref": "#/$defs/7" - }, - "inner": { - "$ref": "#/$defs/0" - }, - "latitude": { + "yrange": { "$ref": "#/$defs/2" }, - "sweep": { - "$ref": "#/$defs/0" - }, "color": { "$ref": "#/$defs/1" }, - "material": { - "$ref": "#/$defs/5" - }, - "roughness": { - "$ref": "#/$defs/0" - }, - "metalness": { - "$ref": "#/$defs/0" - }, - "clearcoat": { - "$ref": "#/$defs/0" - }, - "clearcoatRoughness": { - "$ref": "#/$defs/0" - }, - "edges": { - "$ref": "#/$defs/4" - }, - "opacity": { - "$ref": "#/$defs/0" - }, "at": { "$ref": "#/$defs/0" } }, "required": [ "op", - "shape", "id", - "parent", - "parentAnchor", - "selfAnchor", - "pos", - "rot", - "size", - "inner", - "latitude", - "sweep", + "kind", + "x", + "y", + "w", + "h", + "title", + "xlabel", + "ylabel", + "xrange", + "yrange", "color", - "material", - "roughness", - "metalness", - "clearcoat", - "clearcoatRoughness", - "edges", - "opacity", "at" ], "additionalProperties": false }, - "s": { + "k": { "type": "object", "properties": { "op": { "enum": [ - "add" - ] - }, - "shape": { - "enum": [ - "extrude" + "node" ] }, "id": { "type": "string" }, - "parent": { - "$ref": "#/$defs/1" + "of": { + "type": "string" }, - "parentAnchor": { + "text": { + "type": "string" + }, + "note": { "$ref": "#/$defs/1" }, - "selfAnchor": { + "when": { "$ref": "#/$defs/1" }, "pos": { - "$ref": "#/$defs/2" - }, - "rot": { - "$ref": "#/$defs/2" - }, - "outline": { - "$ref": "#/$defs/3" - }, - "taper": { "$ref": "#/$defs/0" }, - "shift": { - "$ref": "#/$defs/2" - }, - "holes": { - "type": [ - "array", - "null" - ], - "items": { - "type": "array", - "items": { - "type": "array", - "items": { - "type": "number" - } - } - } - }, - "depth": { - "type": "number" - }, "color": { "$ref": "#/$defs/1" }, - "material": { - "$ref": "#/$defs/5" - }, - "roughness": { - "$ref": "#/$defs/0" - }, - "metalness": { - "$ref": "#/$defs/0" - }, - "clearcoat": { - "$ref": "#/$defs/0" - }, - "clearcoatRoughness": { - "$ref": "#/$defs/0" - }, - "bevel": { - "$ref": "#/$defs/0" - }, - "edges": { - "$ref": "#/$defs/4" - }, - "opacity": { - "$ref": "#/$defs/0" - }, "at": { "$ref": "#/$defs/0" } }, "required": [ "op", - "shape", "id", - "parent", - "parentAnchor", - "selfAnchor", + "of", + "text", + "note", + "when", "pos", - "rot", - "outline", - "taper", - "shift", - "holes", - "depth", "color", - "material", - "roughness", - "metalness", - "clearcoat", - "clearcoatRoughness", - "bevel", - "edges", - "opacity", "at" ], "additionalProperties": false }, - "t": { + "l": { "type": "object", "properties": { "op": { "enum": [ - "add" - ] - }, - "shape": { - "enum": [ - "hull" + "edge" ] }, "id": { "type": "string" }, - "parent": { - "$ref": "#/$defs/1" + "from": { + "type": "string" }, - "parentAnchor": { + "to": { + "type": "string" + }, + "text": { "$ref": "#/$defs/1" }, - "selfAnchor": { + "color": { "$ref": "#/$defs/1" }, - "pos": { - "$ref": "#/$defs/2" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "from", + "to", + "text", + "color", + "at" + ], + "additionalProperties": false + }, + "m": { + "type": "object", + "properties": { + "op": { + "enum": [ + "series" + ] }, - "rot": { - "$ref": "#/$defs/2" + "id": { + "type": "string" + }, + "of": { + "type": "string" }, "pts": { + "$ref": "#/$defs/4" + }, + "label": { + "$ref": "#/$defs/1" + }, + "curve": { "$ref": "#/$defs/3" }, "color": { "$ref": "#/$defs/1" }, - "material": { - "$ref": "#/$defs/5" - }, - "roughness": { + "at": { "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "of", + "pts", + "label", + "curve", + "color", + "at" + ], + "additionalProperties": false + }, + "n": { + "type": "object", + "properties": { + "op": { + "enum": [ + "dot" + ] }, - "metalness": { - "$ref": "#/$defs/0" + "id": { + "type": "string" }, - "clearcoat": { - "$ref": "#/$defs/0" + "of": { + "type": "string" }, - "clearcoatRoughness": { - "$ref": "#/$defs/0" + "x": { + "type": "number" }, - "edges": { - "$ref": "#/$defs/4" + "y": { + "type": "number" }, - "opacity": { - "$ref": "#/$defs/0" + "text": { + "$ref": "#/$defs/1" + }, + "color": { + "$ref": "#/$defs/1" }, "at": { "$ref": "#/$defs/0" @@ -1803,27 +1957,85 @@ }, "required": [ "op", - "shape", "id", - "parent", - "parentAnchor", - "selfAnchor", - "pos", - "rot", - "pts", + "of", + "x", + "y", + "text", "color", - "material", - "roughness", - "metalness", - "clearcoat", - "clearcoatRoughness", - "edges", - "opacity", "at" ], "additionalProperties": false }, - "u": { + "o": { + "type": "object", + "properties": { + "op": { + "enum": [ + "tick" + ] + }, + "id": { + "type": "string" + }, + "done": { + "$ref": "#/$defs/3" + }, + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "done", + "at" + ], + "additionalProperties": false + }, + "p": { + "type": "object", + "properties": { + "op": { + "enum": [ + "panel" + ] + }, + "x": { + "type": "number" + }, + "y": { + "type": "number" + }, + "w": { + "type": "number" + }, + "h": { + "type": "number" + }, + "frame": { + "$ref": "#/$defs/3" + }, + "at": { + "$ref": "#/$defs/0" + }, + "dur": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "x", + "y", + "w", + "h", + "frame", + "at", + "dur" + ], + "additionalProperties": false + }, + "q": { "type": "object", "properties": { "op": { @@ -1833,7 +2045,12 @@ }, "shape": { "enum": [ - "lathe" + "box", + "sphere", + "cylinder", + "cone", + "torus", + "plane" ] }, "id": { @@ -1851,18 +2068,12 @@ "pos": { "$ref": "#/$defs/2" }, + "size": { + "$ref": "#/$defs/7" + }, "rot": { "$ref": "#/$defs/2" }, - "profile": { - "$ref": "#/$defs/3" - }, - "sweep": { - "$ref": "#/$defs/0" - }, - "sides": { - "$ref": "#/$defs/0" - }, "color": { "$ref": "#/$defs/1" }, @@ -1881,8 +2092,11 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, + "bevel": { + "$ref": "#/$defs/0" + }, "edges": { - "$ref": "#/$defs/4" + "$ref": "#/$defs/3" }, "opacity": { "$ref": "#/$defs/0" @@ -1899,23 +2113,22 @@ "parentAnchor", "selfAnchor", "pos", + "size", "rot", - "profile", - "sweep", - "sides", "color", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", + "bevel", "edges", "opacity", "at" ], "additionalProperties": false }, - "v": { + "r": { "type": "object", "properties": { "op": { @@ -1925,7 +2138,7 @@ }, "shape": { "enum": [ - "patch" + "shell" ] }, "id": { @@ -1946,8 +2159,17 @@ "rot": { "$ref": "#/$defs/2" }, - "pts": { - "$ref": "#/$defs/3" + "size": { + "$ref": "#/$defs/7" + }, + "inner": { + "$ref": "#/$defs/0" + }, + "latitude": { + "$ref": "#/$defs/2" + }, + "sweep": { + "$ref": "#/$defs/0" }, "color": { "$ref": "#/$defs/1" @@ -1968,7 +2190,7 @@ "$ref": "#/$defs/0" }, "edges": { - "$ref": "#/$defs/4" + "$ref": "#/$defs/3" }, "opacity": { "$ref": "#/$defs/0" @@ -1986,7 +2208,10 @@ "selfAnchor", "pos", "rot", - "pts", + "size", + "inner", + "latitude", + "sweep", "color", "material", "roughness", @@ -1999,7 +2224,7 @@ ], "additionalProperties": false }, - "w": { + "s": { "type": "object", "properties": { "op": { @@ -2009,7 +2234,7 @@ }, "shape": { "enum": [ - "sweep" + "extrude" ] }, "id": { @@ -2031,16 +2256,31 @@ "$ref": "#/$defs/2" }, "outline": { - "$ref": "#/$defs/3" + "$ref": "#/$defs/4" }, - "pts": { - "$ref": "#/$defs/3" + "taper": { + "$ref": "#/$defs/0" }, - "up": { + "shift": { "$ref": "#/$defs/2" }, - "smooth": { - "$ref": "#/$defs/4" + "holes": { + "type": [ + "array", + "null" + ], + "items": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "number" + } + } + } + }, + "depth": { + "type": "number" }, "color": { "$ref": "#/$defs/1" @@ -2060,8 +2300,11 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, + "bevel": { + "$ref": "#/$defs/0" + }, "edges": { - "$ref": "#/$defs/4" + "$ref": "#/$defs/3" }, "opacity": { "$ref": "#/$defs/0" @@ -2080,22 +2323,24 @@ "pos", "rot", "outline", - "pts", - "up", - "smooth", + "taper", + "shift", + "holes", + "depth", "color", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", + "bevel", "edges", "opacity", "at" ], "additionalProperties": false }, - "x": { + "t": { "type": "object", "properties": { "op": { @@ -2105,7 +2350,7 @@ }, "shape": { "enum": [ - "loft" + "hull" ] }, "id": { @@ -2126,18 +2371,9 @@ "rot": { "$ref": "#/$defs/2" }, - "outline": { - "$ref": "#/$defs/3" - }, - "endOutline": { - "$ref": "#/$defs/3" - }, - "smooth": { + "pts": { "$ref": "#/$defs/4" }, - "depth": { - "type": "number" - }, "color": { "$ref": "#/$defs/1" }, @@ -2157,7 +2393,7 @@ "$ref": "#/$defs/0" }, "edges": { - "$ref": "#/$defs/4" + "$ref": "#/$defs/3" }, "opacity": { "$ref": "#/$defs/0" @@ -2175,10 +2411,7 @@ "selfAnchor", "pos", "rot", - "outline", - "endOutline", - "smooth", - "depth", + "pts", "color", "material", "roughness", @@ -2191,7 +2424,7 @@ ], "additionalProperties": false }, - "y": { + "u": { "type": "object", "properties": { "op": { @@ -2201,7 +2434,7 @@ }, "shape": { "enum": [ - "blob" + "lathe" ] }, "id": { @@ -2222,13 +2455,13 @@ "rot": { "$ref": "#/$defs/2" }, - "pts": { - "$ref": "#/$defs/3" + "profile": { + "$ref": "#/$defs/4" }, - "sizes": { - "$ref": "#/$defs/3" + "sweep": { + "$ref": "#/$defs/0" }, - "soft": { + "sides": { "$ref": "#/$defs/0" }, "color": { @@ -2249,6 +2482,9 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, + "edges": { + "$ref": "#/$defs/3" + }, "opacity": { "$ref": "#/$defs/0" }, @@ -2265,21 +2501,22 @@ "selfAnchor", "pos", "rot", - "pts", - "sizes", - "soft", + "profile", + "sweep", + "sides", "color", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", + "edges", "opacity", "at" ], "additionalProperties": false }, - "z": { + "v": { "type": "object", "properties": { "op": { @@ -2289,7 +2526,7 @@ }, "shape": { "enum": [ - "tube" + "patch" ] }, "id": { @@ -2298,19 +2535,19 @@ "parent": { "$ref": "#/$defs/1" }, - "pts": { - "$ref": "#/$defs/3" + "parentAnchor": { + "$ref": "#/$defs/1" }, - "radius": { - "type": "number" + "selfAnchor": { + "$ref": "#/$defs/1" }, - "flat": { - "$ref": "#/$defs/0" + "pos": { + "$ref": "#/$defs/2" }, - "swell": { - "$ref": "#/$defs/8" + "rot": { + "$ref": "#/$defs/2" }, - "closed": { + "pts": { "$ref": "#/$defs/4" }, "color": { @@ -2331,14 +2568,8 @@ "clearcoatRoughness": { "$ref": "#/$defs/0" }, - "treatment": { - "enum": [ - "fibres", - null - ] - }, - "draw": { - "$ref": "#/$defs/0" + "edges": { + "$ref": "#/$defs/3" }, "opacity": { "$ref": "#/$defs/0" @@ -2352,91 +2583,89 @@ "shape", "id", "parent", + "parentAnchor", + "selfAnchor", + "pos", + "rot", "pts", - "radius", - "flat", - "swell", - "closed", "color", "material", "roughness", "metalness", "clearcoat", "clearcoatRoughness", - "treatment", - "draw", + "edges", "opacity", "at" ], "additionalProperties": false }, - "1a": { + "w": { "type": "object", "properties": { "op": { "enum": [ - "explode", - "reveal" + "add" + ] + }, + "shape": { + "enum": [ + "sweep" ] }, "id": { "type": "string" }, - "to": { - "type": "number" + "parent": { + "$ref": "#/$defs/1" }, - "at": { + "parentAnchor": { + "$ref": "#/$defs/1" + }, + "selfAnchor": { + "$ref": "#/$defs/1" + }, + "pos": { + "$ref": "#/$defs/2" + }, + "rot": { + "$ref": "#/$defs/2" + }, + "outline": { + "$ref": "#/$defs/4" + }, + "pts": { + "$ref": "#/$defs/4" + }, + "up": { + "$ref": "#/$defs/2" + }, + "smooth": { + "$ref": "#/$defs/3" + }, + "color": { + "$ref": "#/$defs/1" + }, + "material": { + "$ref": "#/$defs/5" + }, + "roughness": { "$ref": "#/$defs/0" }, - "dur": { + "metalness": { "$ref": "#/$defs/0" - } - }, - "required": [ - "op", - "id", - "to", - "at", - "dur" - ], - "additionalProperties": false - }, - "1b": { - "type": "object", - "properties": { - "op": { - "enum": [ - "anchor" - ] }, - "id": { - "type": "string" + "clearcoat": { + "$ref": "#/$defs/0" }, - "name": { - "type": "string" + "clearcoatRoughness": { + "$ref": "#/$defs/0" }, - "pos": { - "$ref": "#/$defs/7" - } - }, - "required": [ - "op", - "id", - "name", - "pos" - ], - "additionalProperties": false - }, - "1c": { - "type": "object", - "properties": { - "op": { - "enum": [ - "detach" - ] + "edges": { + "$ref": "#/$defs/3" }, - "id": { - "type": "string" + "opacity": { + "$ref": "#/$defs/0" }, "at": { "$ref": "#/$defs/0" @@ -2444,143 +2673,332 @@ }, "required": [ "op", + "shape", "id", + "parent", + "parentAnchor", + "selfAnchor", + "pos", + "rot", + "outline", + "pts", + "up", + "smooth", + "color", + "material", + "roughness", + "metalness", + "clearcoat", + "clearcoatRoughness", + "edges", + "opacity", "at" ], "additionalProperties": false }, - "1d": { + "x": { "type": "object", "properties": { "op": { "enum": [ - "style" + "add" + ] + }, + "shape": { + "enum": [ + "loft" ] }, "id": { "type": "string" }, - "color": { + "parent": { "$ref": "#/$defs/1" }, - "opacity": { - "$ref": "#/$defs/0" + "parentAnchor": { + "$ref": "#/$defs/1" }, - "at": { + "selfAnchor": { + "$ref": "#/$defs/1" + }, + "pos": { + "$ref": "#/$defs/2" + }, + "rot": { + "$ref": "#/$defs/2" + }, + "outline": { + "$ref": "#/$defs/4" + }, + "endOutline": { + "$ref": "#/$defs/4" + }, + "smooth": { + "$ref": "#/$defs/3" + }, + "depth": { + "type": "number" + }, + "color": { + "$ref": "#/$defs/1" + }, + "material": { + "$ref": "#/$defs/5" + }, + "roughness": { "$ref": "#/$defs/0" }, - "dur": { + "metalness": { + "$ref": "#/$defs/0" + }, + "clearcoat": { + "$ref": "#/$defs/0" + }, + "clearcoatRoughness": { + "$ref": "#/$defs/0" + }, + "edges": { + "$ref": "#/$defs/3" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", + "shape", "id", + "parent", + "parentAnchor", + "selfAnchor", + "pos", + "rot", + "outline", + "endOutline", + "smooth", + "depth", "color", + "material", + "roughness", + "metalness", + "clearcoat", + "clearcoatRoughness", + "edges", "opacity", - "at", - "dur" + "at" ], "additionalProperties": false }, - "1e": { + "y": { "type": "object", "properties": { "op": { "enum": [ - "highlight" + "add" + ] + }, + "shape": { + "enum": [ + "blob" ] }, "id": { "type": "string" }, + "parent": { + "$ref": "#/$defs/1" + }, + "parentAnchor": { + "$ref": "#/$defs/1" + }, + "selfAnchor": { + "$ref": "#/$defs/1" + }, + "pos": { + "$ref": "#/$defs/2" + }, + "rot": { + "$ref": "#/$defs/2" + }, + "pts": { + "$ref": "#/$defs/4" + }, + "sizes": { + "$ref": "#/$defs/4" + }, + "soft": { + "$ref": "#/$defs/0" + }, "color": { "$ref": "#/$defs/1" }, - "at": { + "material": { + "$ref": "#/$defs/5" + }, + "roughness": { "$ref": "#/$defs/0" }, - "dur": { + "metalness": { + "$ref": "#/$defs/0" + }, + "clearcoat": { + "$ref": "#/$defs/0" + }, + "clearcoatRoughness": { + "$ref": "#/$defs/0" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", + "shape", "id", + "parent", + "parentAnchor", + "selfAnchor", + "pos", + "rot", + "pts", + "sizes", + "soft", "color", - "at", - "dur" + "material", + "roughness", + "metalness", + "clearcoat", + "clearcoatRoughness", + "opacity", + "at" ], "additionalProperties": false }, - "1f": { + "z": { "type": "object", "properties": { "op": { "enum": [ - "spin" + "add" + ] + }, + "shape": { + "enum": [ + "tube" ] }, "id": { "type": "string" }, - "rpm": { + "parent": { + "$ref": "#/$defs/1" + }, + "pts": { + "$ref": "#/$defs/4" + }, + "radius": { + "type": "number" + }, + "flat": { "$ref": "#/$defs/0" }, - "by": { + "swell": { + "$ref": "#/$defs/8" + }, + "closed": { + "$ref": "#/$defs/3" + }, + "color": { "$ref": "#/$defs/1" }, - "ratio": { + "material": { + "$ref": "#/$defs/5" + }, + "roughness": { "$ref": "#/$defs/0" }, - "phase": { + "metalness": { "$ref": "#/$defs/0" }, - "axis": { - "$ref": "#/$defs/6" + "clearcoat": { + "$ref": "#/$defs/0" }, - "at": { + "clearcoatRoughness": { "$ref": "#/$defs/0" }, - "dur": { + "treatment": { + "enum": [ + "fibres", + null + ] + }, + "draw": { + "$ref": "#/$defs/0" + }, + "opacity": { + "$ref": "#/$defs/0" + }, + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", + "shape", "id", - "rpm", - "by", - "ratio", - "phase", - "axis", - "at", - "dur" + "parent", + "pts", + "radius", + "flat", + "swell", + "closed", + "color", + "material", + "roughness", + "metalness", + "clearcoat", + "clearcoatRoughness", + "treatment", + "draw", + "opacity", + "at" ], "additionalProperties": false }, - "1g": { + "1a": { "type": "object", "properties": { "op": { "enum": [ - "crank" + "pin" ] }, - "piston": { - "$ref": "#/$defs/1" - }, "id": { - "$ref": "#/$defs/1" + "type": "string" }, - "shaft": { + "on": { "type": "string" }, - "rod": { + "point": { + "$ref": "#/$defs/2" + }, + "anchor": { "$ref": "#/$defs/1" }, - "pin": { - "$ref": "#/$defs/0" + "text": { + "type": "string" + }, + "off": { + "$ref": "#/$defs/2" + }, + "color": { + "$ref": "#/$defs/1" }, "at": { "$ref": "#/$defs/0" @@ -2588,241 +3006,147 @@ }, "required": [ "op", - "piston", "id", - "shaft", - "rod", - "pin", + "on", + "point", + "anchor", + "text", + "off", + "color", "at" ], "additionalProperties": false }, - "1h": { + "1b": { "type": "object", "properties": { "op": { "enum": [ - "cam" - ] - }, - "valve": { - "$ref": "#/$defs/1" + "move", + "turn", + "scale" + ] }, "id": { - "$ref": "#/$defs/1" - }, - "by": { "type": "string" }, - "lift": { - "$ref": "#/$defs/0" - }, - "open": { - "$ref": "#/$defs/0" + "to": { + "$ref": "#/$defs/7" }, - "phase": { + "at": { "$ref": "#/$defs/0" }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", - "valve", "id", - "by", - "lift", - "open", - "phase", - "at" + "to", + "at", + "dur" ], "additionalProperties": false }, - "1i": { + "1c": { "type": "object", "properties": { "op": { "enum": [ - "flash" + "along" ] }, "id": { "type": "string" }, - "by": { - "type": "string" - }, - "angle": { - "type": "number" - }, - "span": { - "type": "number" + "pts": { + "$ref": "#/$defs/4" }, - "cycle": { + "at": { "$ref": "#/$defs/0" }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "by", - "angle", - "span", - "cycle", - "at" + "pts", + "at", + "dur" ], "additionalProperties": false }, - "1j": { + "1d": { "type": "object", "properties": { "op": { "enum": [ - "loop" + "explode", + "reveal" ] }, "id": { "type": "string" }, - "kind": { - "enum": [ - "slide", - "swing", - "pulse", - "stop", - null - ] - }, - "amount": { - "$ref": "#/$defs/0" - }, - "axis": { - "$ref": "#/$defs/6" - }, - "period": { - "$ref": "#/$defs/0" - }, - "by": { - "$ref": "#/$defs/1" - }, - "ratio": { - "$ref": "#/$defs/0" + "to": { + "type": "number" }, - "phase": { + "at": { "$ref": "#/$defs/0" }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "kind", - "amount", - "axis", - "period", - "by", - "ratio", - "phase", - "at" + "to", + "at", + "dur" ], "additionalProperties": false }, - "1k": { + "1e": { "type": "object", "properties": { "op": { "enum": [ - "joint" + "anchor" ] }, "id": { "type": "string" }, - "kind": { - "enum": [ - "hinge", - "slide", - "fixed", - "pivot", - "ball" - ] - }, - "axis": { - "$ref": "#/$defs/6" - }, - "dir": { - "$ref": "#/$defs/2" - }, - "pivot": { - "$ref": "#/$defs/2" - }, - "about": { - "$ref": "#/$defs/1" - }, - "limit": { - "$ref": "#/$defs/2" - }, - "min": { - "$ref": "#/$defs/0" - }, - "max": { - "$ref": "#/$defs/0" - }, - "to": { - "$ref": "#/$defs/1" + "name": { + "type": "string" }, - "at": { - "$ref": "#/$defs/0" + "pos": { + "$ref": "#/$defs/7" } }, "required": [ "op", "id", - "kind", - "axis", - "dir", - "pivot", - "about", - "limit", - "min", - "max", - "to", - "at" + "name", + "pos" ], "additionalProperties": false }, - "1l": { + "1f": { "type": "object", "properties": { "op": { "enum": [ - "couple" + "detach" ] }, "id": { "type": "string" }, - "by": { - "$ref": "#/$defs/1" - }, - "ratio": { - "$ref": "#/$defs/0" - }, - "pitch": { - "$ref": "#/$defs/0" - }, - "phase": { - "$ref": "#/$defs/0" - }, - "stop": { - "$ref": "#/$defs/4" - }, "at": { "$ref": "#/$defs/0" } @@ -2830,113 +3154,95 @@ "required": [ "op", "id", - "by", - "ratio", - "pitch", - "phase", - "stop", "at" ], "additionalProperties": false }, - "1m": { + "1g": { "type": "object", "properties": { "op": { "enum": [ - "lever" + "style" ] }, "id": { "type": "string" }, - "fulcrum": { + "color": { "$ref": "#/$defs/1" }, - "swing": { - "$ref": "#/$defs/0" - }, - "period": { + "opacity": { "$ref": "#/$defs/0" }, - "phase": { + "at": { "$ref": "#/$defs/0" }, - "axis": { - "$ref": "#/$defs/6" - }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "fulcrum", - "swing", - "period", - "phase", - "axis", - "at" + "color", + "opacity", + "at", + "dur" ], "additionalProperties": false }, - "1n": { + "1h": { "type": "object", "properties": { "op": { "enum": [ - "muscle" + "highlight" ] }, "id": { "type": "string" }, - "pulls": { - "type": "string" - }, - "contract": { - "$ref": "#/$defs/0" - }, - "period": { - "$ref": "#/$defs/0" + "color": { + "$ref": "#/$defs/1" }, - "phase": { + "at": { "$ref": "#/$defs/0" }, - "at": { + "dur": { "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "pulls", - "contract", - "period", - "phase", - "at" + "color", + "at", + "dur" ], "additionalProperties": false }, - "1o": { + "1i": { "type": "object", "properties": { "op": { "enum": [ - "pulley" + "spin" ] }, "id": { "type": "string" }, - "wheel": { - "type": "string" + "rpm": { + "$ref": "#/$defs/0" }, - "radius": { + "by": { + "$ref": "#/$defs/1" + }, + "ratio": { "$ref": "#/$defs/0" }, - "rpm": { + "phase": { "$ref": "#/$defs/0" }, "axis": { @@ -2944,431 +3250,765 @@ }, "at": { "$ref": "#/$defs/0" + }, + "dur": { + "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "wheel", - "radius", "rpm", + "by", + "ratio", + "phase", "axis", - "at" + "at", + "dur" ], "additionalProperties": false }, - "1p": { + "1j": { "type": "object", "properties": { "op": { "enum": [ - "cut" + "crank" ] }, - "id": { - "type": "string" + "piston": { + "$ref": "#/$defs/1" }, - "axis": { - "$ref": "#/$defs/6" + "id": { + "$ref": "#/$defs/1" }, - "normal": { - "$ref": "#/$defs/2" + "shaft": { + "type": "string" }, - "to": { - "type": "number" + "rod": { + "$ref": "#/$defs/1" }, - "at": { + "pin": { "$ref": "#/$defs/0" }, - "dur": { + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", + "piston", "id", - "axis", - "normal", - "to", - "at", - "dur" + "shaft", + "rod", + "pin", + "at" ], "additionalProperties": false }, - "1q": { + "1k": { "type": "object", "properties": { "op": { "enum": [ - "orbit" + "cam" ] }, - "az": { - "type": "number" + "valve": { + "$ref": "#/$defs/1" }, - "el": { - "type": "number" + "id": { + "$ref": "#/$defs/1" }, - "at": { - "$ref": "#/$defs/0" + "by": { + "type": "string" }, - "dur": { + "lift": { "$ref": "#/$defs/0" - } - }, - "required": [ - "op", - "az", - "el", - "at", - "dur" - ], - "additionalProperties": false - }, - "1r": { - "type": "object", - "properties": { - "op": { - "enum": [ - "zoom" - ] }, - "to": { - "type": "number" + "open": { + "$ref": "#/$defs/0" }, - "at": { + "phase": { "$ref": "#/$defs/0" }, - "dur": { + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", - "to", - "at", - "dur" + "valve", + "id", + "by", + "lift", + "open", + "phase", + "at" ], "additionalProperties": false }, - "1s": { + "1l": { "type": "object", "properties": { "op": { "enum": [ - "focus" + "flash" ] }, "id": { - "$ref": "#/$defs/1" + "type": "string" }, - "at": { + "by": { + "type": "string" + }, + "angle": { + "type": "number" + }, + "span": { + "type": "number" + }, + "cycle": { "$ref": "#/$defs/0" }, - "dur": { + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", "id", - "at", - "dur" + "by", + "angle", + "span", + "cycle", + "at" ], "additionalProperties": false }, - "1t": { + "1m": { "type": "object", "properties": { "op": { "enum": [ - "wait" + "loop" ] }, - "for": { + "id": { + "type": "string" + }, + "kind": { "enum": [ - "click" + "slide", + "swing", + "pulse", + "gate", + "float", + "stop", + null ] }, - "x": { + "amount": { "$ref": "#/$defs/0" }, - "y": { + "damp": { "$ref": "#/$defs/0" }, - "w": { + "tilt": { "$ref": "#/$defs/0" }, - "h": { + "axis": { + "$ref": "#/$defs/6" + }, + "period": { + "$ref": "#/$defs/0" + }, + "by": { + "$ref": "#/$defs/1" + }, + "ratio": { + "$ref": "#/$defs/0" + }, + "phase": { + "$ref": "#/$defs/0" + }, + "at": { "$ref": "#/$defs/0" } }, "required": [ "op", - "for", - "x", - "y", - "w", - "h" + "id", + "kind", + "amount", + "damp", + "tilt", + "axis", + "period", + "by", + "ratio", + "phase", + "at" ], "additionalProperties": false }, - "1u": { + "1n": { "type": "object", "properties": { "op": { "enum": [ - "go" + "joint" ] }, + "id": { + "type": "string" + }, "kind": { "enum": [ - "tab", - "open", - "scroll" + "hinge", + "slide", + "fixed", + "pivot", + "ball" ] }, - "x": { - "type": "number" - }, - "y": { - "type": "number" + "axis": { + "$ref": "#/$defs/6" }, "dir": { - "enum": [ - "down", - "up", - "left", - "right", - null - ] + "$ref": "#/$defs/2" + }, + "pivot": { + "$ref": "#/$defs/2" + }, + "about": { + "$ref": "#/$defs/1" + }, + "limit": { + "$ref": "#/$defs/2" + }, + "min": { + "$ref": "#/$defs/0" + }, + "max": { + "$ref": "#/$defs/0" + }, + "to": { + "$ref": "#/$defs/1" + }, + "at": { + "$ref": "#/$defs/0" } }, "required": [ "op", + "id", "kind", - "x", - "y", - "dir" + "axis", + "dir", + "pivot", + "about", + "limit", + "min", + "max", + "to", + "at" ], "additionalProperties": false }, - "1v": { + "1o": { "type": "object", "properties": { "op": { "enum": [ - "clear" + "couple" ] }, - "target": { + "id": { "type": "string" }, + "by": { + "$ref": "#/$defs/1" + }, + "ratio": { + "$ref": "#/$defs/0" + }, + "pitch": { + "$ref": "#/$defs/0" + }, + "phase": { + "$ref": "#/$defs/0" + }, + "stop": { + "$ref": "#/$defs/3" + }, "at": { "$ref": "#/$defs/0" } }, "required": [ "op", - "target", - "at" - ], - "additionalProperties": false + "id", + "by", + "ratio", + "pitch", + "phase", + "stop", + "at" + ], + "additionalProperties": false }, - "1w": { - "anyOf": [ - { - "$ref": "#/$defs/a" + "1p": { + "type": "object", + "properties": { + "op": { + "enum": [ + "lever" + ] }, - { - "$ref": "#/$defs/b" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/c" + "fulcrum": { + "$ref": "#/$defs/1" }, - { - "$ref": "#/$defs/d" + "swing": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/e" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/f" + "phase": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/g" + "axis": { + "$ref": "#/$defs/6" }, - { - "$ref": "#/$defs/h" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "fulcrum", + "swing", + "period", + "phase", + "axis", + "at" + ], + "additionalProperties": false + }, + "1q": { + "type": "object", + "properties": { + "op": { + "enum": [ + "muscle" + ] }, - { - "$ref": "#/$defs/i" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/j" + "pulls": { + "type": "string" }, - { - "$ref": "#/$defs/k" + "contract": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/l" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/m" + "phase": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/n" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "pulls", + "contract", + "period", + "phase", + "at" + ], + "additionalProperties": false + }, + "1r": { + "type": "object", + "properties": { + "op": { + "enum": [ + "pulley" + ] }, - { - "$ref": "#/$defs/o" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/p" + "wheel": { + "type": "string" }, - { - "$ref": "#/$defs/q" + "radius": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/r" + "rpm": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/s" + "axis": { + "$ref": "#/$defs/6" }, - { - "$ref": "#/$defs/t" + "min": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/u" + "max": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/v" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "wheel", + "radius", + "rpm", + "axis", + "min", + "max", + "at" + ], + "additionalProperties": false + }, + "1s": { + "type": "object", + "properties": { + "op": { + "enum": [ + "wave" + ] }, - { - "$ref": "#/$defs/w" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/x" + "amount": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/y" + "width": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/z" + "count": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/10" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/11" + "stop": { + "$ref": "#/$defs/3" }, - { - "$ref": "#/$defs/12" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "amount", + "width", + "count", + "period", + "stop", + "at" + ], + "additionalProperties": false + }, + "1t": { + "type": "object", + "properties": { + "op": { + "enum": [ + "pendulum" + ] }, - { - "$ref": "#/$defs/13" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/14" + "from": { + "$ref": "#/$defs/1" }, - { - "$ref": "#/$defs/15" + "pivot": { + "$ref": "#/$defs/2" }, - { - "$ref": "#/$defs/16" + "swing": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/17" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/18" + "damp": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/19" + "axis": { + "$ref": "#/$defs/6" }, - { - "$ref": "#/$defs/1a" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "from", + "pivot", + "swing", + "period", + "damp", + "axis", + "at" + ], + "additionalProperties": false + }, + "1u": { + "type": "object", + "properties": { + "op": { + "enum": [ + "oscillate" + ] }, - { - "$ref": "#/$defs/1b" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/1c" + "amount": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1d" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1e" + "damp": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1f" + "axis": { + "$ref": "#/$defs/6" }, - { - "$ref": "#/$defs/1g" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "amount", + "period", + "damp", + "axis", + "at" + ], + "additionalProperties": false + }, + "1v": { + "type": "object", + "properties": { + "op": { + "enum": [ + "float" + ] }, - { - "$ref": "#/$defs/1h" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/1i" + "bob": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1j" + "tilt": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1k" + "period": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1l" + "damp": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1m" + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "bob", + "tilt", + "period", + "damp", + "at" + ], + "additionalProperties": false + }, + "1w": { + "type": "object", + "properties": { + "op": { + "enum": [ + "drop" + ] }, - { - "$ref": "#/$defs/1n" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/1o" + "to": { + "type": "number" }, - { - "$ref": "#/$defs/1p" + "bounce": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1q" + "at": { + "$ref": "#/$defs/0" }, - { - "$ref": "#/$defs/1r" + "dur": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "to", + "bounce", + "at", + "dur" + ], + "additionalProperties": false + }, + "1x": { + "type": "object", + "properties": { + "op": { + "enum": [ + "pump" + ] }, - { - "$ref": "#/$defs/1s" + "id": { + "type": "string" }, - { - "$ref": "#/$defs/1t" + "inlet": { + "$ref": "#/$defs/1" }, - { - "$ref": "#/$defs/1u" + "outlet": { + "$ref": "#/$defs/1" }, - { - "$ref": "#/$defs/1v" + "squeeze": { + "$ref": "#/$defs/0" + }, + "open": { + "$ref": "#/$defs/0" + }, + "period": { + "$ref": "#/$defs/0" + }, + "hinge": { + "$ref": "#/$defs/1" + }, + "axis": { + "$ref": "#/$defs/6" + }, + "at": { + "$ref": "#/$defs/0" } - ] + }, + "required": [ + "op", + "id", + "inlet", + "outlet", + "squeeze", + "open", + "period", + "hinge", + "axis", + "at" + ], + "additionalProperties": false }, - "1x": { + "1y": { "type": "object", "properties": { - "say": { + "op": { + "enum": [ + "incline" + ] + }, + "id": { "type": "string" }, - "actions": { - "type": "array", - "items": { - "$ref": "#/$defs/1w" - } + "ramp": { + "$ref": "#/$defs/1" + }, + "angle": { + "$ref": "#/$defs/0" + }, + "travel": { + "$ref": "#/$defs/0" + }, + "period": { + "$ref": "#/$defs/0" + }, + "at": { + "$ref": "#/$defs/0" } }, "required": [ - "say", - "actions" + "op", + "id", + "ramp", + "angle", + "travel", + "period", + "at" + ], + "additionalProperties": false + }, + "1z": { + "type": "object", + "properties": { + "op": { + "enum": [ + "wedge" + ] + }, + "id": { + "type": "string" + }, + "drives": { + "type": "string" + }, + "angle": { + "$ref": "#/$defs/0" + }, + "travel": { + "$ref": "#/$defs/0" + }, + "period": { + "$ref": "#/$defs/0" + }, + "axis": { + "$ref": "#/$defs/6" + }, + "at": { + "$ref": "#/$defs/0" + } + }, + "required": [ + "op", + "id", + "drives", + "angle", + "travel", + "period", + "axis", + "at" ], "additionalProperties": false } diff --git a/package-lock.json b/package-lock.json index 1597445..99269b6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "talkthrough", - "version": "0.5.0", + "version": "0.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "talkthrough", - "version": "0.5.0", + "version": "0.6.0", "license": "MIT", "dependencies": { "get-windows": "10.0.0", diff --git a/package.json b/package.json index 27fca81..15a3349 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "talkthrough", - "version": "0.5.0", + "version": "0.6.0", "description": "An AI that talks you through anything on your screen, and draws as it talks.", "keywords": [ "screen assistant", diff --git a/src/overlay/fall.ts b/src/overlay/fall.ts new file mode 100644 index 0000000..55e0ce1 --- /dev/null +++ b/src/overlay/fall.ts @@ -0,0 +1,44 @@ +// Gravity, illustrated: how far a dropped part has gone toward the floor, and how long a drop takes. +// A constant pull makes the fall a square of the time; each bounce goes up and comes down again in the time a smaller fall takes, +// `bounce` (0 to 0.8) being the speed it keeps, so the height it reaches is that squared. A pure function of the time, as every motion is. + +const MAX_BOUNCES = 5; + +/** The times of one fall, in units of the first fall's: the first fall is 1, bounce k takes 2 x bounce^k. */ +function schedule(bounce: number): number[] { + const out = [1]; + for (let k = 1; k <= MAX_BOUNCES; k++) { + const t = 2 * Math.pow(bounce, k); + if (t < 0.04) break; + out.push(t); + } + return out; +} + +/** How far toward the floor it is (0 at the start, 1 on the floor) after `u` (0 to 1) of the whole drop, bounces and all. */ +export function fallCurve(u: number, bounce: number): number { + if (u <= 0) return 0; + if (u >= 1) return 1; + const e = Math.max(0, Math.min(0.8, bounce)); + const times = schedule(e); + const total = times.reduce((a, b) => a + b, 0); + let t = u * total; + if (t < 1) return t * t; + t -= 1; + for (let k = 1; k < times.length; k++) { + const span = times[k] as number; + if (t <= span) { + const x = (2 * t) / span - 1; + return 1 - Math.pow(e, 2 * k) * (1 - x * x); + } + t -= span; + } + return 1; +} + +/** Seconds a drop of `height` units takes, bounces included: longer for a greater fall, with a pull that makes a 4 unit fall take about 0.8 s. */ +export function fallSeconds(height: number, bounce: number): number { + const first = 0.4 * Math.sqrt(Math.max(0.1, Math.abs(height))); + const e = Math.max(0, Math.min(0.8, bounce)); + return first * schedule(e).reduce((a, b) => a + b, 0); +} diff --git a/src/overlay/motion.ts b/src/overlay/motion.ts index 0ddce83..c4a0a9e 100644 --- a/src/overlay/motion.ts +++ b/src/overlay/motion.ts @@ -28,8 +28,15 @@ export type FlashDef = { key: number; byKey: number; angle: number; span: number * `loopDriver(key)` (below zero, so it never meets an object): free, it turns once a period; locked, it follows another part. The pose is a function * of that angle (the cosine of it: 1 at the far end, so a part locked to a crank is at the top when the crank pin is). */ -export type LoopKind = 'slide' | 'swing' | 'pulse'; -export type LoopDef = { key: number; kind: LoopKind; axis: Axis; amount: number; pivot: Vec3 }; +export type LoopKind = 'slide' | 'swing' | 'pulse' | 'gate' | 'float'; +/** + * `gate` swings a hinge open on one half of the cycle and shuts it on the other (a one-way valve); `float` bobs the object up and down by `amount` + * units and rocks it `tilt` degrees about z (a boat on water). `damp` is the number of cycles for the motion to fall to a third (it settles); `start` is the + * angle the loop began at, which the fall is counted from. + */ +export type LoopDef = { key: number; kind: LoopKind; axis: Axis; amount: number; pivot: Vec3; damp?: number; start?: number; tilt?: number; /** A swing about the middle of this object, wherever it stands (a pendulum hung from a part): the pivot is worked out each frame. */ pivotKey?: number }; +/** How much of its swing a damped free loop still has when its angle is `a`: one for a loop that does not settle. */ +export const loopFade = (l: LoopDef, a: number): number => (l.damp !== undefined && l.start !== undefined ? Math.exp(-Math.max(0, (a - l.start) / 360) / l.damp) : 1); /** The key of the angle that drives the loop on object `key`; the same call gives the object back from the driver's key. */ export const loopDriver = (key: number): number => -1 - key; /** @@ -38,7 +45,10 @@ export const loopDriver = (key: number): number => -1 - key; */ const BALL_BASE = -10_000_000; export const ballDriver = (key: number, axis: Axis): number => BALL_BASE - key * 3 - axis; -export const driverOwner = (driver: number): number => (driver <= BALL_BASE ? Math.floor((BALL_BASE - driver) / 3) : -1 - driver); +/** The angle that drives the wave on a tube: its own key range, below the rest. */ +const WAVE_BASE = -1_000_000_000; +export const waveDriver = (key: number): number => WAVE_BASE - key; +export const driverOwner = (driver: number): number => (driver <= WAVE_BASE ? WAVE_BASE - driver : driver <= BALL_BASE ? Math.floor((BALL_BASE - driver) / 3) : -1 - driver); /** Where a free loop's angle starts, so it begins at rest: the cosine is 0 for slide and swing, and the pulse is at its smallest. */ export const loopStart = (kind: LoopKind): number => (kind === 'pulse' ? 180 : 270); @@ -58,10 +68,15 @@ export type CoupleDef = { key: number; byKey: number; ratio: number; pitch: numb * turns the part's hinge or pivot to make it so. The cycle (0 relaxed to 1 most contracted) is the cosine of the angle kept under `loopDriver(key)`. */ export type MuscleDef = { key: number; holderKey: number; connectorKey: number; from: Vec3; to: Vec3; contract: number }; -export type Motion = { spins: SpinState[]; cranks: CrankDef[]; cams: CamDef[]; flashes: FlashDef[]; loops: LoopDef[]; joints: JointDef[]; couples: CoupleDef[]; muscles?: MuscleDef[] }; +/** + * A wave travelling along a tube: a swell (amount above 1) or a squeeze (below 1) of its radius, width (a fraction of the length) across, `count` of them spaced + * evenly. Where it is is the angle kept under `waveDriver(key)`, in laps, the same as a stream's markers: a crest and a marker of the same period are together. + */ +export type WaveDef = { key: number; amount: number; width: number; count: number }; +export type Motion = { spins: SpinState[]; cranks: CrankDef[]; cams: CamDef[]; flashes: FlashDef[]; loops: LoopDef[]; joints: JointDef[]; couples: CoupleDef[]; muscles?: MuscleDef[]; waves?: WaveDef[] }; export type Pose = { pos?: Vec3; rot?: Vec3; opacity?: number; /** A multiplier on the object's own scale. */ scale?: Vec3 }; -export const emptyMotion = (): Motion => ({ spins: [], cranks: [], cams: [], flashes: [], loops: [], joints: [], couples: [], muscles: [] }); +export const emptyMotion = (): Motion => ({ spins: [], cranks: [], cams: [], flashes: [], loops: [], joints: [], couples: [], muscles: [], waves: [] }); // ---- Spins over time ------------------------------------------------------------------------------ @@ -364,7 +379,7 @@ export function poses(objects: readonly PoseObject[], motion: Motion): Map([...jointOf.keys(), ...coupleOf.keys(), ...muscleOf.keys(), ...[...loopOf.values()].filter((l) => l.kind !== 'pulse').map((l) => l.key)]); + const driven = new Set([...jointOf.keys(), ...coupleOf.keys(), ...muscleOf.keys(), ...[...loopOf.values()].filter((l) => l.kind !== 'pulse' && l.kind !== 'float').map((l) => l.key)]); for (const key of driven) { const o = byKey.get(key); const joint = jointOf.get(key); @@ -423,7 +438,16 @@ export function poses(objects: readonly PoseObject[], motion: Motion): Map { @@ -425,7 +427,9 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { board.beginFrame({ width: view.width, height: view.height, model: modelRect, dragging, now: labelClock(), ...(cardRect ? { within: cardRect } : {}) }); board.keep(new Set(frame.marks.filter((m) => m.mark.op === 'pin').map((m) => m.key))); pinGeometry = []; - let admission = new SurfaceAdmission(modelRect ? [modelRect] : []); + // A stage that a clear is taking away does not hold space against what arrives (it is still drawn, fading). + const stageHeld = stageKeepOut(frame.panel, modelRect); + let admission = new SurfaceAdmission(stageHeld); const paintTime = labelClock(); const admitSurface = (id: string) => admission.shown.has(id); const annotator = { @@ -451,14 +455,14 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { overflowEl.style.display = admission.omitted.size ? 'block' : 'none'; if (admission.omitted.size) { const size = omissionCue.size(frame.marks.length + frame.diagrams.length + 1, view.width); - const obstacles = [...admission.shown.values(), ...(modelRect ? [modelRect] : []), ...overlayControlRects()]; + const obstacles = [...admission.shown.values(), ...stageHeld, ...overlayControlRects()]; const at = followupSpot(view, size, obstacles); const cue = { ...at, w: size.w, h: size.h }; let hiddenStage = 0; if (obstacles.some(r => surfacesOverlap(cue, r))) { // No gap even for the cue: give it a dedicated slot, omitting intersecting panels too. // The stage is normally first priority, but cannot obscure this last-resort explanation. - if (modelRect && surfacesOverlap(cue, modelRect)) { + if (modelRect && stageHeld.length > 0 && surfacesOverlap(cue, modelRect)) { hiddenStage = 1; renderer?.setScissorTest(false); renderer?.clear(); frameEl.style.display = 'none'; @@ -466,7 +470,7 @@ function draw(frame: Frame, seekView = false, cameraFit?: 'instant'): Frame { frame = omitStageForCue(frame, board); placeExplode(frame); } - admission = admission.prioritize(frame, [cue, ...(modelRect ? [modelRect] : [])]); + admission = admission.prioritize(frame, [cue, ...stageKeepOut(frame.panel, modelRect)]); } const count = admission.omitted.size + hiddenStage; omissionCue.show(count); diff --git a/src/overlay/placement.ts b/src/overlay/placement.ts index 8fc3c63..4a412bf 100644 --- a/src/overlay/placement.ts +++ b/src/overlay/placement.ts @@ -237,6 +237,25 @@ const STAGE_GROW = 2; const STAGE_BIGGEST = { w: 320, h: 560 }; /** Growth under this factor is not worth moving the stage for. */ const STAGE_GROW_LEAST = 1.12; +/** + * A stage shorter than a fair share of the screen's height is made taller, keeping its width, where the page under the added height has little on it + * (the screen is wider than tall, so a stage as wide as it is tall is a wide slab, and a tall or compact model is limited by its height). A fair share is + * this many units of height; growth under STAGE_TALLER_LEAST is not worth a move; the page under what is added may have at most this share of its cells + * inked at all (little text: a margin, a gutter, a blank column) and at most this share of controls and figures. + */ +const STAGE_FAIR_HEIGHT = 620; +const STAGE_TALLER_LEAST = 30; +const STAGE_TALLER_INK = 0.15; +const STAGE_TALLER_FIXTURES = 0.1; +/** + * The stage's growth must leave the cards after it their room: a note-sized card (about this size) has to find a place as quiet as it would have had before + * the stage grew (within this much of the cost of covering the page), anywhere clear of the grown stage, the strip of its buttons below it, the page's + * controls and the cards already placed. A card a later step writes cannot be known when the stage is placed, so this stops short of taking the last + * quiet place, rather than forbidding any growth that could move a card. + */ +const NOTE_ROOM = { w: 380, h: 150 }; +const NOTE_ROOM_SLACK = 0.3; +const STAGE_BUTTONS_STRIP = 90; /** A place has to be this much cheaper (a few percent of the page's text under it) before a card, diagram or stage leaves where it was asked for: text may be covered when that reads better. */ const MOVE_WORTH = 8; @@ -466,12 +485,58 @@ export class Placer { // is where it reads best); it is made smaller only when no place of its size is clear of what the answer points at. const keep = [...this.reserved, ...this.reserved, ...this.reserved, ...this.controls, ...this.cards.values()]; const full = this.search(want, [1], keep, [1], 0, false, 0, { w: 0, h: 0 }, false); - const placed = this.enlarge(keep.some((r) => overlap(full, r) > 0) ? this.search(want, [1, 0.88, 0.76, 0.64, 0.52], keep) : full); + const placed = this.taller(this.enlarge(keep.some((r) => overlap(full, r) > 0) ? this.search(want, [1, 0.88, 0.76, 0.64, 0.52], keep) : full)); this.stage = placed; this.stageControls = []; return placed; } + /** + * A stage shorter than a fair share of the screen is made taller, keeping its width and everything it already covered: the tallest height (to + * STAGE_FAIR_HEIGHT) that, grown up, down or both ways, adds only page with little on it and stays clear of the cards and the page's controls (hard) and + * of what the answer points at (a preference: a place that would cover another pointed-at spot is passed over, and a spot the stage already covers is + * left out of the reckoning). When nothing qualifies it stays as it is. The growth is made here, in the placement, so cards written after it keep + * off the taller stage and the rectangle the page eases to always holds the one it eased from. + */ + private taller(box: Box): Box { + const lo = this.margin, top = lo, bottom = 1000 - lo; + const target = Math.min(STAGE_FAIR_HEIGHT, bottom - top); + if (box.h > target - STAGE_TALLER_LEAST) return box; + const hard = [...this.controls, ...this.cards.values()]; + const spots = this.reserved.filter((r) => overlap(box, r) <= 0); + const quiet = (strip: Box): boolean => { + if (strip.h <= 0) return true; + const padded = { x: strip.x - 6, y: strip.y - 6, w: strip.w + 12, h: strip.h + 12 }; + return this.ink.mean(padded) <= STAGE_TALLER_INK && this.fixtures.mean(padded) <= STAGE_TALLER_FIXTURES; + }; + // The least a note-sized card would cost the page, anywhere that is not under the stage (and its button strip), the controls or the cards. + const noteCost = (stage: Box): number => { + const taken = [{ x: stage.x - 10, y: stage.y - 10, w: stage.w + 20, h: stage.h + 10 + STAGE_BUTTONS_STRIP }, ...hard]; + let least = Infinity; + for (let y = lo; y + NOTE_ROOM.h <= bottom + 0.01; y += 20) for (let x = lo; x + NOTE_ROOM.w <= 1000 - lo + 0.01; x += 20) { + const spot = { x, y, w: NOTE_ROOM.w, h: NOTE_ROOM.h }; + if (taken.some((r) => overlap(spot, r) > 0)) continue; + least = Math.min(least, this.coverage(spot, [])); + } + return least; + }; + const roomBefore = noteCost(box); + for (let h = target; h >= box.h + STAGE_TALLER_LEAST; h -= 20) { + let best: { box: Box; cost: number } | undefined; + for (const y0 of [box.y, box.y + box.h - h, box.y + (box.h - h) / 2]) { + const y = clamp(y0, top, bottom - h); + const grown = { x: box.x, y, w: box.w, h }; + if (hard.some((r) => overlap(grown, r) > 0) || spots.some((r) => overlap(grown, r) > 0)) continue; + const above = { x: box.x, y, w: box.w, h: box.y - y }, below = { x: box.x, y: box.y + box.h, w: box.w, h: y + h - box.y - box.h }; + if (!quiet(above) || !quiet(below)) continue; + const cost = (above.h > 0 ? this.coverage(above, []) : 0) + (below.h > 0 ? this.coverage(below, []) : 0); + if (!best || cost < best.cost - 1e-9) best = { box: { x: box.x, y: Math.round(y), w: box.w, h: Math.round(h) }, cost }; + } + if (best && noteCost(best.box) <= roomBefore + NOTE_ROOM_SLACK) return best.box; + } + return box; + } + /** * A small stage made larger when the blank page beside it has room: the biggest growth (about its own centre, or from one of its corners, * so it can spread toward the free side) that is still blank, clear of what the answer points at and of the cards, and inside the screen. diff --git a/src/overlay/scene3d-flow.ts b/src/overlay/scene3d-flow.ts index 87559e6..edcfa72 100644 --- a/src/overlay/scene3d-flow.ts +++ b/src/overlay/scene3d-flow.ts @@ -3,10 +3,10 @@ import { setPathSurfaceCoordinates, treatmentOf } from './surface-treatment.ts'; // (connector.ts), rebuilt only when they have moved; a stream is a few markers placed along a path from the stream's lap count (stream.ts). // Both are redone on every frame after the scene's matrices are up to date, so they follow the parts they hang on, however those were moved. -import { Box3, BufferGeometry, ConeGeometry, CylinderGeometry, Group, Matrix4, Mesh, Quaternion, SphereGeometry, Vector3 } from 'three'; +import { Box3, BufferGeometry, ConeGeometry, CylinderGeometry, Group, Matrix4, Mesh, Quaternion, Sphere, SphereGeometry, Vector3 } from 'three'; import type { Object3D } from 'three'; import type { Rgb } from '../scene/colors.ts'; -import type { AddConnector, AddPath, AddStream, AddTube, Vec3 } from '../scene/types.ts'; +import type { AddConnector, AddForce, AddParticles, AddPath, AddStream, AddTube, Vec2, Vec3 } from '../scene/types.ts'; import { arcPoint, beltPoints, endPoint, ropePoints, roundOf } from './connector.ts'; import { drawFraction, swellAt, tubeGeometry } from './geometry.ts'; import { applySurface, setSurfaceOpacity } from './materials.ts'; @@ -26,6 +26,12 @@ export type FlowNode = { connector?: { mesh: Mesh; signature: string }; stream?: { markers: Mesh[]; kind: 'dot' | 'dash' | 'arrow' }; attached?: { base: Vec3[]; along: number[]; signature: string }; + /** A tube a wave runs along: what it was last drawn with, and its bounds at rest (so the camera does not breathe with the swell). */ + wave?: { signature: string; sphere: Sphere; box: Box3 }; + /** A cloud of particles: where each starts, where it ends up and how it jostles. */ + particles?: { beads: Mesh[]; start: Vec3[]; end: Vec3[]; shake: Array<{ freq: Vec3; phase: Vec3 }> }; + /** A force arrow: its shaft and head. */ + force?: { shaft: Mesh; head: Mesh }; }; export type AddMesh = (geo: BufferGeometry, surface: string | undefined, edges: boolean) => Mesh; @@ -327,3 +333,181 @@ export function updateStreams(nodes: ReadonlyMap, frame: Frame }); } } + +// ---- Waves along a tube ---------------------------------------------------------------------------------------------------------- + +/** The factor a wave puts on the radius at `u` (0 to 1 along the tube), crests `count` apiece, each `width` of the length across, `phase` laps along. */ +export function waveFactor(u: number, phase: number, count: number, width: number, amount: number): number { + let bump = 0; + const half = Math.max(0.01, width / 2); + for (let j = 0; j < count; j++) { + const c = (((phase + j / count) % 1) + 1) % 1; + const d = Math.abs(u - c) / half; + if (d < 1) bump = Math.max(bump, 0.5 * (1 + Math.cos(Math.PI * d))); + } + return 1 + (amount - 1) * bump; +} + +/** + * A tube with a wave on it is drawn again with its radius swelled (or squeezed) along its length, the crest where the laps say. The same laps run a stream's + * markers, so a marker and a crest of the same period are together. A tube that has lost its wave is drawn as it was authored. A closed loop takes no wave. + */ +export function updateWaves(nodes: ReadonlyMap, frame: Frame, radial: number): void { + for (const o of frame.objects) { + if (o.shape !== 'tube') continue; + const node = nodes.get(o.key); + const def = o.def as AddTube; + if (!node?.path || def.closed === true || (!o.wave && !node.wave)) continue; + const sampled = node.path.sampled; + const n = sampled.length; + if (n < 2) continue; + const swell: Vec2[] = []; + const w = o.wave; + for (let i = 0; i < n; i++) { + const u = i / (n - 1); + const base = def.swell ? swellAt(def.swell, u) : 1; + swell.push([u, base * (w ? waveFactor(u, w.phase, w.count, w.width, w.amount) : 1)]); + } + const signature = w ? swell.map((p) => Math.round(p[1] * 400)).join(',') + ':' + n : ''; + if (!node.wave) { + const rest = node.path.geo; + if (!rest.boundingSphere) rest.computeBoundingSphere(); + if (!rest.boundingBox) rest.computeBoundingBox(); + node.wave = { signature: '\u0000', sphere: (rest.boundingSphere as Sphere).clone(), box: (rest.boundingBox as Box3).clone() }; + } + if (signature !== node.wave.signature) { + const geo = tubeGeometry(sampled, def.radius, def.flat ?? 1, radial, w ? swell : def.swell); + setPathSurfaceCoordinates(geo, treatmentOf(def)); + geo.boundingSphere = node.wave.sphere.clone(); + geo.boundingBox = node.wave.box.clone(); + const mesh = node.obj.children[0] as Mesh; + const old = node.path.geo; + mesh.geometry = geo; + const at = node.geometries.indexOf(old); + if (at >= 0) node.geometries[at] = geo; + else node.geometries.push(geo); + old.dispose(); + node.path.geo = geo; + node.wave.signature = signature; + } + drawFraction(node.path.geo, o.draw); + if (!w) delete node.wave; + } +} + +// ---- Particles that spread ---------------------------------------------------------------------------------------------------------- + +const MAX_PARTICLES = 80; +const unit = (s: number): number => { + // A fixed pseudo-random number from 0 to 1 for a seed (the same every time, so a frame grab and the live page agree). + const x = Math.sin(s * 127.1 + 311.7) * 43758.5453; + return x - Math.floor(x); +}; +const smooth = (k: number): number => { + const x = Math.max(0, Math.min(1, k)); + return x * x * (3 - 2 * x); +}; + +export function buildParticles(node: FlowNode, o: ObjectFrame, addMesh: AddMesh): void { + const def = o.def as AddParticles; + const count = Math.max(1, Math.min(MAX_PARTICLES, def.count ?? 30)); + const shift = def.shift ?? [0, 0, 0]; + const geo = new SphereGeometry(0.5, 12, 9); + const group = new Group(); + const beads: Mesh[] = []; + const start: Vec3[] = [], end: Vec3[] = []; + const shake: Array<{ freq: Vec3; phase: Vec3 }> = []; + for (let i = 0; i < count; i++) { + const m = addMesh(geo, 'bead', false); + group.add(m); + beads.push(m); + const r = (k: number): number => unit(i * 7.31 + k * 13.17) - 0.5; + start.push([r(1) * def.from[0], r(2) * def.from[1], r(3) * def.from[2]]); + end.push([shift[0] + r(4) * def.to[0], shift[1] + r(5) * def.to[1], shift[2] + r(6) * def.to[2]]); + shake.push({ freq: [1 + unit(i + 0.1) * 2, 1 + unit(i + 0.2) * 2, 1 + unit(i + 0.3) * 2], phase: [unit(i + 0.4) * 6.283, unit(i + 0.5) * 6.283, unit(i + 0.6) * 6.283] }); + } + node.obj = group; + node.particles = { beads, start, end, shake }; +} + +/** Puts the particles where the spread (the object's draw) and the jostle (its laps) say. */ +export function updateParticles(nodes: ReadonlyMap, frame: Frame): void { + for (const o of frame.objects) { + if (o.shape !== 'particles') continue; + const node = nodes.get(o.key); + const cloud = node?.particles; + if (!node || !cloud) continue; + const def = o.def as AddParticles; + const k = smooth(o.draw); + const jostle = def.jitter ?? 0.12; + const laps = o.phase ?? 0; + const size = def.size ?? 0.14; + cloud.beads.forEach((m, i) => { + const a = cloud.start[i] as Vec3, b = cloud.end[i] as Vec3, s = cloud.shake[i] as { freq: Vec3; phase: Vec3 }; + m.position.set( + a[0] + (b[0] - a[0]) * k + jostle * Math.sin(2 * Math.PI * (laps * s.freq[0] + s.phase[0] / 6.283)), + a[1] + (b[1] - a[1]) * k + jostle * Math.sin(2 * Math.PI * (laps * s.freq[1] + s.phase[1] / 6.283)), + a[2] + (b[2] - a[2]) * k + jostle * Math.sin(2 * Math.PI * (laps * s.freq[2] + s.phase[2] / 6.283)), + ); + m.scale.setScalar(size); + }); + } +} + +// ---- Force arrows ----------------------------------------------------------------------------------------------------------------- + +export function buildForce(node: FlowNode, o: ObjectFrame, addMesh: AddMesh): void { + void o; + const group = new Group(); + const shaft = addMesh(new CylinderGeometry(0.5, 0.5, 1, 14), 'plastic', false); + const head = addMesh(new ConeGeometry(0.5, 1, 18), 'plastic', false); + group.add(shaft, head); + node.obj = group; + node.force = { shaft, head }; +} + +const dirV = new Vector3(), startV = new Vector3(), mid = new Vector3(); + +/** + * Puts each force arrow on the part it acts on: it starts at a point of the part and points the way the scene says, whatever the part does (gravity stays + * down as the part turns), strength units long (the object's scale and pulse make it more or less) and thicker the stronger. + */ +export function updateForces(nodes: ReadonlyMap, frame: Frame): void { + const byId = new Map(); + for (const o of frame.objects) byId.set(o.id, o); + for (const o of frame.objects) { + if (o.shape !== 'force') continue; + const node = nodes.get(o.key); + const arrow = node?.force; + if (!node || !arrow) continue; + const def = o.def as AddForce; + const host = byId.get(def.on); + const hostNode = host && nodes.get(host.key); + if (!host || !hostNode || !hostNode.obj.visible) { + node.obj.visible = false; + continue; + } + // It is placed in the scene's own space: its own place and turn are not used. + node.obj.position.set(0, 0, 0); + node.obj.rotation.set(0, 0, 0); + node.obj.scale.set(1, 1, 1); + node.obj.updateWorldMatrix(true, false); + const inverse = new Matrix4().copy(node.obj.matrixWorld).invert(); + endPoint(hostNode.obj, host.def, undefined, def.point, hostNode.anchors, startV); + startV.applyMatrix4(inverse); + dirV.set(def.dir[0], def.dir[1], def.dir[2]).transformDirection(inverse); + const grown = o.pose?.scale ?? [1, 1, 1]; + const strength = Math.max(0.02, def.strength * ((o.scale[0] + o.scale[1] + o.scale[2]) / 3) * ((grown[0] + grown[1] + grown[2]) / 3)); + const length = strength; + const r = 0.05 + 0.025 * Math.min(strength, 8); + const headLen = Math.min(length * 0.45, 0.35 + 3 * r); + const shaftLen = Math.max(0.001, length - headLen); + quat.setFromUnitVectors(UP, dirV); + arrow.shaft.quaternion.copy(quat); + arrow.head.quaternion.copy(quat); + arrow.shaft.scale.set(2 * r, shaftLen, 2 * r); + arrow.head.scale.set(4.4 * r, headLen, 4.4 * r); + arrow.shaft.position.copy(mid.copy(startV).addScaledVector(dirV, shaftLen / 2)); + arrow.head.position.copy(mid.copy(startV).addScaledVector(dirV, shaftLen + headLen / 2)); + } +} diff --git a/src/overlay/scene3d.ts b/src/overlay/scene3d.ts index 2a874cc..984bca3 100644 --- a/src/overlay/scene3d.ts +++ b/src/overlay/scene3d.ts @@ -31,7 +31,9 @@ import { TAG_HEIGHT_FACTOR, tagTextPx } from './theme.ts'; import { convexHull } from './labels.ts'; import type { Pt } from './labels.ts'; import type { Piece } from './parts.ts'; +import { sweptPoses } from './timeline.ts'; import type { FocusFrame, Frame, ObjectFrame, Rgb } from './timeline.ts'; +import type { Pose } from './motion.ts'; import { spreadPosition, userOffsets } from './explode.ts'; import type { Part } from './explode.ts'; import { PATCH_SEGMENTS } from '../scene/patch.ts'; @@ -39,7 +41,7 @@ import { patchGeometry, patchEdges } from './patch.ts'; import { Cutaway } from './cutaway.ts'; import { anchorsOf } from '../scene/anchors.ts'; import { latheSectorEdges, latheSectorGeometry } from './lathe-sector.ts'; -import { buildConnector, buildStream, updateAttached, updateConnectors, updateStreams } from './scene3d-flow.ts'; +import { buildConnector, buildForce, buildParticles, buildStream, updateAttached, updateConnectors, updateForces, updateParticles, updateStreams, updateWaves } from './scene3d-flow.ts'; import type { FlowNode } from './scene3d-flow.ts'; /** The longer side of the stage sees this many degrees; the shorter side follows from its shape, so a wide stage does not skew what sits at its edges. */ @@ -115,6 +117,9 @@ type Node = { /** A connector's tube and what it was last built from; a stream's markers (see scene3d-flow.ts). */ connector?: FlowNode['connector']; stream?: FlowNode['stream']; + wave?: FlowNode['wave']; + particles?: FlowNode['particles']; + force?: FlowNode['force']; /** A tube or line with an end on a part: its points as drawn at rest (see scene3d-flow.ts). */ attached?: FlowNode['attached']; }; @@ -155,6 +160,9 @@ export class PanelScene { private fitClock: number | undefined; /** The visible parts' bounding spheres and box corners at rest (no machine pose, no pulse), worked out in `sync` for the camera's fit. */ private restSpheres: PartHull[] = []; + /** The parts' spheres and boxes at the poses a running machine takes over its cycle (see `sweptPoses`), kept while the machine and its parts are as they were. */ + private sweepHulls: PartHull[] = []; + private sweepKey = ''; /** Where the text sprites were put on screen by the last `tidyTexts` (window pixels): what is drawn includes them. */ private textRects: ScreenRect[] = []; private settling = false; @@ -256,7 +264,7 @@ export class PanelScene { return mesh; }; switch (def.shape) { - case 'group': case 'array': break; + 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); @@ -296,6 +304,8 @@ export class PanelScene { case 'tube': case 'line': case 'arrow': this.buildPath(node, o, addMesh); break; case 'connector': buildConnector(node, o, addMesh, this.detail.radial); break; case 'stream': buildStream(node, o, addMesh); break; + case 'particles': buildParticles(node, o, addMesh); break; + case 'force': buildForce(node, o, addMesh); break; default: { const geo = this.solidGeometry(def); if (def.shape === 'blob') shadeByHeight(geo); @@ -413,7 +423,9 @@ export class PanelScene { private buildPath(node: Node, o: ObjectFrame, addMesh: AddMesh): void { const def = o.def as { shape: string; pts: Vec3[]; radius?: number; flat?: number; swell?: Array<[number, number]>; closed?: boolean; material?: string }; const tube = def.shape === 'tube'; - const radius = tube ? def.radius ?? PATH_RADIUS : PATH_RADIUS; + // A field line (made by the timeline) is finer than an arrow the model draws, and counts in the fit of the camera: the lines are the picture. + const fine = (def as { fine?: boolean }).fine === true; + const radius = tube ? def.radius ?? PATH_RADIUS : fine ? PATH_RADIUS * 0.8 : PATH_RADIUS; const loop = tube && def.closed ? closedTubeGeometry(def.pts, radius, def.flat ?? 1, this.detail.radial, this.detail.tube, def.swell) : undefined; const sampled = loop?.sampled ?? samplePath(def.pts, tube, this.detail.tube); const geo = loop?.geo ?? tubeGeometry(sampled, radius, tube ? def.flat ?? 1 : 1, this.detail.radial, tube ? def.swell : undefined); @@ -423,6 +435,7 @@ export class PanelScene { let head: Mesh | undefined; if (def.shape === 'arrow') { head = addMesh(new ConeGeometry(PATH_RADIUS * 3.4, 0.55, 20), 'plastic', false); + if (fine) head.scale.setScalar(0.85); group.add(head); } node.obj = group; @@ -430,7 +443,7 @@ export class PanelScene { for (let i = 1; i < sampled.length; i++) length += Math.hypot(sampled[i]![0] - sampled[i - 1]![0], sampled[i]![1] - sampled[i - 1]![1], sampled[i]![2] - sampled[i - 1]![2]); // Closed loops are model geometry, even when thin; only open trailing cables // may stay outside the camera fit and the bounds that enable rendering. - node.path = { geo, sampled, head, body: tube && (def.closed === true || radius >= 0.04 * length) }; + node.path = { geo, sampled, head, body: fine || (tube && (def.closed === true || radius >= 0.04 * length)) }; } private buildText(node: Node, o: ObjectFrame): void { @@ -567,14 +580,27 @@ export class PanelScene { layout(offsets, true); this.scene.updateMatrixWorld(true); this.restSpheres = this.partSpheres(); + this.sweepHulls = this.sweptHulls(frame, offsets, spreads); layout(offsets); } this.scene.updateMatrixWorld(true); - if (!frame.objects.some((o) => o.pose || o.pulse !== 0)) this.restSpheres = this.partSpheres(); + if (!frame.objects.some((o) => o.pose || o.pulse !== 0)) { + this.restSpheres = this.partSpheres(); + // Nothing is moving yet but something will be, later in this step: the camera is already fitted to it. + this.sweepHulls = frame.ahead ? this.sweptHulls(frame, offsets, spreads) : []; + if (!frame.ahead) this.sweepKey = ''; + else { + layout(offsets); + this.scene.updateMatrixWorld(true); + } + } // Connectors and streams are placed from where their parts now are; what hangs on a connector then needs its matrices again. updateAttached(this.nodes, frame, this.detail.radial, PATH_RADIUS); if (updateConnectors(this.nodes, frame, this.detail.radial)) this.scene.updateMatrixWorld(true); + updateWaves(this.nodes, frame, this.detail.radial); updateStreams(this.nodes, frame); + updateParticles(this.nodes, frame); + updateForces(this.nodes, frame); this.scene.updateMatrixWorld(true); this.aim(frame, aspect, view, standBack); if (view) this.tidyTexts(view); @@ -666,17 +692,23 @@ export class PanelScene { line.visible = node.obj.visible; } + /** Where a part stands and how big it is: its own values, or a machine's pose in their place; swell is what a pulse loop multiplies its scale by. */ + private place(node: Node, o: ObjectFrame, parentSpread: number, offset: Vec3 | undefined, pose: Pose | undefined, swell: Vec3 | undefined, grow: number): void { + const at = spreadPosition(pose?.pos ?? o.pos, (o.def as { explode?: Vec3 }).explode, parentSpread); + const rot = pose?.rot ?? o.rot; + node.obj.position.set(at[0] + (offset?.[0] ?? 0), at[1] + (offset?.[1] ?? 0), at[2] + (offset?.[2] ?? 0)); + node.obj.rotation.copy(new Euler(rot[0] * DEG, rot[1] * DEG, rot[2] * DEG, 'XYZ')); + const loop = swell ?? [1, 1, 1]; + node.obj.scale.set(node.baseScale.x * o.scale[0] * loop[0] * grow, node.baseScale.y * o.scale[1] * loop[1] * grow, node.baseScale.z * o.scale[2] * loop[2] * grow); + } + private apply(node: Node, o: ObjectFrame, parentSpread: number, offset?: Vec3, rest = false): void { const pulse = rest ? 0 : o.pulse; const pose = rest ? undefined : o.pose; const grow = 1 + 0.07 * pulse; // Spread by the model's own explode, then by the person's control; a machine's pose stands in for the rest values. - const at = spreadPosition(pose?.pos ?? o.pos, (o.def as { explode?: Vec3 }).explode, parentSpread); const rot = pose?.rot ?? o.rot; - node.obj.position.set(at[0] + (offset?.[0] ?? 0), at[1] + (offset?.[1] ?? 0), at[2] + (offset?.[2] ?? 0)); - node.obj.rotation.copy(new Euler(rot[0] * DEG, rot[1] * DEG, rot[2] * DEG, 'XYZ')); - const loop = o.pose?.scale ?? [1, 1, 1]; // a pulse loop swells it on top of its own scale - node.obj.scale.set(node.baseScale.x * o.scale[0] * loop[0] * grow, node.baseScale.y * o.scale[1] * loop[1] * grow, node.baseScale.z * o.scale[2] * loop[2] * grow); + this.place(node, o, parentSpread, offset, pose, o.pose?.scale, grow); // a pulse loop swells it on top of its own scale if (!node.anchorsFrom || node.anchorsFrom.def !== o.def || node.anchorsFrom.points !== o.points) { node.anchors = anchorsOf(o.points ? { ...o.def, points: o.points } : o.def); node.anchorsFrom = { def: o.def, points: o.points }; @@ -707,7 +739,7 @@ export class PanelScene { if (head) { const { p, dir } = pointAlong(node.path.sampled, o.draw); const d = new Vector3(dir[0], dir[1], dir[2]); - head.position.set(p[0], p[1], p[2]).addScaledVector(d, -0.2); + head.position.set(p[0], p[1], p[2]).addScaledVector(d, -0.2 * head.scale.y); head.quaternion.setFromUnitVectors(new Vector3(0, 1, 0), d); head.visible = o.draw > 0.02; } @@ -731,7 +763,14 @@ export class PanelScene { // The distance comes from a sphere round the visible parts; it also takes in an opened (exploded) model, which is // laid out by now, so the camera stands back for it without being told. const az = cam.az * DEG, el = Math.max(-89, Math.min(89, cam.el)) * DEG; - const fit = this.eased(this.fitTarget(az, el, tan, aspect), view?.now); + // A sweep may reach the screen's edge, not only the stage's: how much wider than the stage that is, each way, from the stage's middle. + const room = { x: 1, y: 1 }; + if (view) { + const cx = view.rect.x + view.rect.w / 2, cy = view.rect.y + view.rect.h / 2; + room.x = Math.max(1, (0.96 * Math.min(cx, view.width - cx)) / (view.rect.w / 2)); + room.y = Math.max(1, (0.96 * Math.min(cy, view.height - cy)) / (view.rect.h / 2)); + } + const fit = this.eased(this.fitTarget(az, el, tan, aspect, room), view?.now); let base = (FRAMING_UNITS / 2 / (aspect >= 1 ? 1 : aspect)) / tan; if (fit) base = Math.max(MIN_FIT_DISTANCE, fit.radius); void standBack; @@ -831,7 +870,7 @@ export class PanelScene { private partSpheres(): PartHull[] { const spheres: PartHull[] = []; for (const node of this.nodes.values()) { - if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream) continue; + if (!node.obj.visible || node.obj instanceof Sprite || node.pieces.length === 0 || (node.path && !node.path.body) || node.stream || node.particles || node.force) continue; for (const p of node.pieces) { const mesh = p.object as Mesh; const geo = mesh.geometry; @@ -851,6 +890,32 @@ export class PanelScene { return spheres; } + /** + * The parts' spheres and boxes at each of the poses a running machine takes over its cycle: the camera fits the stage to all of them with the rest ones, so + * a part that swings out of its rest shape does not leave the stage. Taken again only when the parts or the machine change (a part appears, moves, or + * a loop or joint is written), never as the machine runs, so the camera stands still over the cycle. + */ + private sweptHulls(frame: Frame, offsets: Map | undefined, spreads: ReadonlyMap): PartHull[] { + const q = (v: readonly number[], k: number): string => v.map((x) => Math.round(x * k)).join(','); + const m = frame.ahead ?? frame.motion; + const key = frame.objects.map((o) => `${o.key}:${o.parentKey}:${q(o.pos, 4)}:${q(o.rot, 1)}:${q(o.scale, 4)}:${o.opacity * o.appear * o.fade > 0.003 ? 1 : 0}`).join('|') + + '#' + JSON.stringify([m.cranks, m.cams, m.loops, m.joints, m.couples, m.muscles, m.spins.map((s) => [s.key, s.axis, s.rate !== 0, s.lock ?? null])]); + if (key === this.sweepKey) return this.sweepHulls; + this.sweepKey = key; + const hulls: PartHull[] = []; + for (const set of sweptPoses(frame)) { + for (const o of frame.objects) { + const node = this.nodes.get(o.key); + if (!node) continue; + const pose = set.get(o.key); + this.place(node, o, o.parentKey !== null ? spreads.get(o.parentKey) ?? 0 : 0, offsets?.get(o.key), pose, pose?.scale, 1); + } + this.scene.updateMatrixWorld(true); + hulls.push(...this.partSpheres()); + } + return hulls; + } + /** * Where the model is on screen, tightly: for each part the overlap of its box's projection and its bounding sphere's, joined. A box alone * reaches past a round part by a corner's worth, which made a ball look bigger than it was (and its buttons and tags keep away from nothing). @@ -927,22 +992,22 @@ export class PanelScene { * margin. A tall or long model fills its stage instead of leaving it mostly empty, and, being made from the rest pose, it does not breathe * when a part pulses or a machine moves. Never further than the all-round sphere would put it. */ - private fitTarget(az: number, el: number, tan: number, aspect: number): { center: Vector3; radius: number } | undefined { - const parts = this.restSpheres; - if (parts.length === 0) return undefined; + private fitTarget(az: number, el: number, tan: number, aspect: number, room = { x: 1, y: 1 }): { center: Vector3; radius: number } | undefined { + const groups: Array<[PartHull[], number, number]> = [[this.restSpheres, 1, 1], [this.sweepHulls, room.x, room.y]]; + if (this.restSpheres.length === 0) return undefined; const lo = new Vector3(Infinity, Infinity, Infinity), hi = new Vector3(-Infinity, -Infinity, -Infinity); - for (const p of parts) for (const c of p.corners) { lo.min(c); hi.max(c); } + for (const [parts] of groups) for (const p of parts) for (const c of p.corners) { lo.min(c); hi.max(c); } const center = lo.add(hi).multiplyScalar(0.5); const toCam = new Vector3(Math.sin(az) * Math.cos(el), Math.sin(el), Math.cos(az) * Math.cos(el)); const right = new Vector3().crossVectors(new Vector3(0, 1, 0), toCam); if (right.lengthSq() < 1e-9) right.set(1, 0, 0); right.normalize(); const up = new Vector3().crossVectors(toCam, right).normalize(); - const tanY = tan, tanX = tan * aspect; - const kx = Math.sqrt(1 + tanX * tanX), ky = Math.sqrt(1 + tanY * tanY); const rel = new Vector3(); let dist = 0; - for (const { sphere: s, corners } of parts) { + for (const [parts, sx, sy] of groups) for (const { sphere: s, corners } of parts) { + const tanY = tan * sy, tanX = tan * aspect * sx; + const kx = Math.sqrt(1 + tanX * tanX), ky = Math.sqrt(1 + tanY * tanY); // Each part needs the nearer of what its box asks and what its bounding sphere asks: a long thin part is held by its box, a round one by its sphere. let byBox = 0; for (const c of corners) { @@ -1149,6 +1214,9 @@ export class PanelScene { let beyond = false; try { beyond = reverse.intersectObjects(target, false).some(allowed); } finally { for (const [m, side] of sides) m.side = side; } + // A point inside a solid made of overlapping closed pieces (the middle of a kit wheel: a barrel with a cap set into each end) has a closed piece's + // near face between it and the camera, yet it is not behind anything: going on away from the camera the ray leaves more solids than it enters. + if (beyond && this.insideSolid(world, away, target)) beyond = false; if (beyond) continue; } this.pinWarnings.delete(key); @@ -1157,6 +1225,23 @@ export class PanelScene { return hidden(); } + /** Whether a point lies inside a closed solid among these meshes: going on from it in `away`, the ray leaves more of their closed surfaces than it enters. */ + private insideSolid(world: Vector3, away: Vector3, meshes: readonly Mesh[]): boolean { + const sides = new Map(); + for (const mesh of meshes) for (const m of (Array.isArray(mesh.material) ? mesh.material : [mesh.material])) { + if (!sides.has(m)) { sides.set(m, m.side); m.side = DoubleSide; } + } + try { + let net = 0; + for (const hit of new Raycaster(world.clone(), away.clone()).intersectObjects(meshes as Mesh[], false)) { + if (!hit.face) continue; + const normal = hit.face.normal.clone().transformDirection((hit.object as Mesh).matrixWorld); + net += normal.dot(away) > 0 ? 1 : -1; // leaving a solid (its normal points on along the ray) or entering one + } + return net > 0; + } finally { for (const [m, side] of sides) m.side = side; } + } + /** The window rectangle the model fills, and the part of the page its shadow touches too; undefined when there is no model. */ screenBounds(width: number, height: number): { model: ScreenRect; drawn: ScreenRect } | undefined { if (!this.hasBox || this.box.isEmpty()) return undefined; diff --git a/src/overlay/surface-admission.ts b/src/overlay/surface-admission.ts index cb64b6d..d157490 100644 --- a/src/overlay/surface-admission.ts +++ b/src/overlay/surface-admission.ts @@ -106,3 +106,11 @@ export class OmissionCue { if (this.live.textContent !== text) this.live.textContent = text; } } + +/** + * What the stage holds against the surfaces being admitted: its rectangle, while it is there to stay. A stage a clear has taken (`leaving`) is fading out + * and, like a leaving panel, yields to what arrives, so a chart that replaces the model is neither hidden nor counted in the omission cue while the model fades. + */ +export function stageKeepOut(panel: Frame['panel'], rect: Box | undefined): Box[] { + return rect && !panel?.leaving ? [rect] : []; +} diff --git a/src/overlay/timeline.ts b/src/overlay/timeline.ts index f3f652b..b299065 100644 --- a/src/overlay/timeline.ts +++ b/src/overlay/timeline.ts @@ -11,12 +11,14 @@ import { anchorsOf } from '../scene/anchors.ts'; import { resolvePartGeometry } from '../scene/part-geometry.ts'; import { PALETTE_RGB } from '../scene/colors.ts'; import { MATERIAL_LIBRARY } from '../scene/material-library.ts'; -import { advanceMotion, ballDriver, muscleRest, crankPinKey, crankPinSize, driverOwner, drawsOwnPin, emptyMotion, loopDriver, loopStart, poses, restPoint, setLock, setRate, spinPlanFrom, spinsAt, stopSpin } from './motion.ts'; -import type { CamDef, CoupleDef, CrankDef, FlashDef, JointDef, LoopDef, Motion, MuscleDef, Pose, SpinPlan } from './motion.ts'; +import { advanceMotion, ballDriver, muscleRest, crankPinKey, crankPinSize, driverOwner, drawsOwnPin, emptyMotion, loopDriver, loopStart, poses, restPoint, waveDriver, setLock, setRate, spinPlanFrom, spinsAt, stopSpin } from './motion.ts'; +import type { CamDef, CoupleDef, CrankDef, FlashDef, JointDef, LoopDef, Motion, MuscleDef, Pose, SpinPlan, WaveDef } from './motion.ts'; import { applyDiagramAction, clearDiagrams, diagramPlanFrom, diagramTimes, emptyDiagramPlan, evaluateDiagrams, pulseDiagramThing, styleDiagramThing } from './diagram-plan.ts'; import type { DiagramFrame, DiagramPlan } from './diagram-plan.ts'; import { mechanismColor } from './part-colors.ts'; import { pathLength, smoothPath } from './shapes.ts'; +import { fallCurve, fallSeconds } from './fall.ts'; +import { fieldLines } from '../scene/field-lines.ts'; import type { Rgb } from '../scene/colors.ts'; import type { Action, AddAction, AddConnector, Mark, Step, StreamPiece, Vec3 } from '../scene/types.ts'; @@ -52,6 +54,8 @@ export function defaultColor(def: AddAction): Rgb { } } if (def.shape === 'stream') return [240, 244, 250]; + if (def.shape === 'force') return [226, 92, 72]; + if (def.shape === 'particles') return [96, 150, 232]; const material = 'material' in def ? def.material : undefined; // A connector with no material is a plain grey cord; one that names a material (a muscle, a rope) has that material's colour. if (def.shape === 'connector' && material === undefined) return [104, 108, 118]; @@ -126,6 +130,8 @@ export type ObjectFrame = { draw: number; /** A stream: how many laps its markers have run, whole and part (their places along the path are a function of this alone). */ phase?: number; + /** A wave running along a tube: the laps it has run, how big a swell (above 1) or squeeze (below) at the crest, how wide a fraction of the tube and how many at once. */ + wave?: { phase: number; amount: number; width: number; count: number }; /** How far apart its parts are pushed: 0 assembled; its children sit at pos * (1 + spread). */ spread: number; /** Where a machine has put it just now (a turning part, a piston, a valve, a glow); drawn in place of pos, rot and opacity. */ @@ -139,7 +145,7 @@ export type ObjectFrame = { }; export type Frame = { - panel: { rect: Rect; appear: number; fade: number; frame: boolean } | null; + panel: { rect: Rect; appear: number; fade: number; frame: boolean; /** A clear has taken it: it is fading out, and holds no space against what arrives. */ leaving?: boolean } | null; marks: MarkFrame[]; /** The flat diagrams (flow, timeline, steps, chart) on the screen, and what is drawn in each. */ diagrams: DiagramFrame[]; @@ -153,6 +159,11 @@ export type Frame = { userCut?: number; /** What is turning, and how the parts are tied to it. */ motion: Motion; + /** + * The machine as it will be later in the same step, when something in it has not started turning yet (a loop written to begin a few seconds in): the camera + * fits the stage to it from the start, so the model is not drawn large and then made smaller when the machine starts. + */ + ahead?: Motion; }; export function emptyFrame(): Frame { @@ -164,7 +175,7 @@ export function emptyFrame(): Frame { // ---- Tracks: a property over time ----------------------------------------------------------- -type Seg = { start: number; dur: number; from: number[]; to: number[]; /** A smooth path from the start through these points to the end. */ curve?: number[][] }; +type Seg = { start: number; dur: number; from: number[]; to: number[]; /** A smooth path from the start through these points to the end. */ curve?: number[][]; /** Falls to the end with a constant pull and bounces this high (0 to 0.8) instead of easing. */ fall?: number }; type Track = { init: number[]; segs: Seg[] }; const track = (init: readonly number[]): Track => ({ init: [...init], segs: [] }); @@ -202,7 +213,7 @@ function valueAt(tr: Track, t: number): number[] { else break; } if (!seg) return [...tr.init]; - const p = ease(progress(t, seg.start, seg.dur)); + const p = seg.fall !== undefined ? fallCurve(progress(t, seg.start, seg.dur), seg.fall) : ease(progress(t, seg.start, seg.dur)); if (seg.curve && p < 1) return catmull(seg.curve, p); return seg.to.map((to, i) => { const from = seg.from[i] ?? to; @@ -262,6 +273,7 @@ export type StepPlan = { joints: JointDef[]; couples: CoupleDef[]; muscles: MuscleDef[]; + waves: WaveDef[]; nextKey: number; /** Authored seconds until the last action has finished. */ duration: number; @@ -375,7 +387,7 @@ function buildStep(base: Frame, step: Step, authored?: AuthoredStep, targets?: M az: track([base.camera.az]), el: track([base.camera.el]), zoom: track([base.camera.zoom]), focus: { init: base.camera.focus.key, segs: [] }, pulses: [], nextKey: base.nextKey, duration: 0, - spins: base.motion.spins.map(spinPlanFrom), cranks: [...base.motion.cranks], cams: [...base.motion.cams], flashes: [...base.motion.flashes], loops: [...base.motion.loops], joints: [...base.motion.joints], couples: [...base.motion.couples], muscles: [...(base.motion.muscles ?? [])], + spins: base.motion.spins.map(spinPlanFrom), cranks: [...base.motion.cranks], cams: [...base.motion.cams], flashes: [...base.motion.flashes], loops: [...base.motion.loops], joints: [...base.motion.joints], couples: [...base.motion.couples], muscles: [...(base.motion.muscles ?? [])], waves: [...(base.motion.waves ?? [])], }; for (const m of base.marks) { plan.marks.push({ @@ -538,6 +550,10 @@ function applyAction(plan: StepPlan, a: Action, at: number, spinRamp: (spin: Spi end(APPEAR_SECONDS); return; } + if (a.shape === 'field') { + addField(plan, a, at, end); + return; + } const parent = 'parent' in a && a.parent !== undefined ? lookup(plan.objs, a.parent, at) : undefined; // Raw scenes can bypass validation. A missing holder must not silently make a child a root. if ('parent' in a && a.parent !== undefined && !parent) return; @@ -565,7 +581,7 @@ function applyAction(plan: StepPlan, a: Action, at: number, spinRamp: (spin: Spi scale: track([1, 1, 1]), color: track(given !== undefined ? parseColor(given) : defaultColor(a)), opacity: track([('opacity' in a && a.opacity !== undefined) ? a.opacity : 1]), - draw: track([('draw' in a && a.draw !== undefined) ? a.draw : 1]), spread: track([0]), + draw: track([('draw' in a && a.draw !== undefined) ? a.draw : a.shape === 'particles' ? 0 : 1]), spread: track([0]), }; if (replaced?.points) fresh.points = { ...replaced.points }; if (replaced) replaceObject(plan, replaced, fresh, at); @@ -575,6 +591,14 @@ function applyAction(plan: StepPlan, a: Action, at: number, spinRamp: (spin: Spi fresh.rot = track(authoredMount.rot); fresh.scale = track(authoredMount.scale); } + if (a.shape === 'particles') { + // The jostle runs on its own clock, an angle kept like a stream's laps. + const driver = loopDriver(fresh.key); + plan.spins = plan.spins.filter((x) => x.key !== driver); + const sp = spinPlanFrom({ key: driver, axis: 2, angle: 0, rate: 0 }); + plan.spins.push(sp); + setRate(sp, at, 360 / (a.period ?? 1.5), 0, 2); + } end(replaced ? REPLACE_SECONDS : APPEAR_SECONDS); return; } @@ -733,14 +757,19 @@ function applyAction(plan: StepPlan, a: Action, at: number, spinRamp: (spin: Spi if (kind === undefined) return; // One loop to an object: the later one replaces the earlier (and `stop` is only that replacement left empty). A ball joint has one for each axis. const ball = joint?.kind === 'ball'; - const axis = a.axis === 'x' ? 0 : a.axis === 'z' ? 2 : a.axis === 'y' ? 1 : kind === 'swing' ? 2 : 1; + const axis = a.axis === 'x' ? 0 : a.axis === 'z' ? 2 : a.axis === 'y' ? 1 : kind === 'swing' || kind === 'gate' ? 2 : 1; const driver = ball ? ballDriver(o.key, axis) : loopDriver(o.key); plan.muscles = plan.muscles.filter((m) => m.key !== o.key); plan.loops = plan.loops.filter((l) => l.key !== o.key || (ball && l.axis !== axis)); plan.spins = plan.spins.filter((s) => s.key !== driver); if (kind !== 'stop') { - plan.loops.push({ key: o.key, kind, axis, amount: a.amount ?? 1, pivot: a.pivot ? asVec(a.pivot) : [0, 0, 0] }); - const sp = spinPlanFrom({ key: driver, axis: 2, angle: loopStart(kind) + (by ? 0 : a.phase ?? 0), rate: 0 }); + const start = loopStart(kind) + (by ? 0 : a.phase ?? 0); + plan.loops.push({ + key: o.key, kind, axis, amount: a.amount ?? 1, pivot: a.pivot ? asVec(a.pivot) : [0, 0, 0], + ...(a.pivotOn !== undefined && lookup(plan.objs, a.pivotOn, at) ? { pivotKey: (lookup(plan.objs, a.pivotOn, at) as ObjInst).key } : {}), + ...(!by && a.damp !== undefined ? { damp: a.damp } : {}), ...(!by && (a.damp !== undefined || kind === 'float') ? { start } : {}), ...(kind === 'float' ? { tilt: a.tilt ?? 4 } : {}), + }); + const sp = spinPlanFrom({ key: driver, axis: 2, angle: start, rate: 0 }); plan.spins.push(sp); if (by) setLock(sp, at, { byKey: by.key, ratio: a.ratio ?? 1, phase: a.phase ?? 0 }, 2); else setRate(sp, at, 360 / (a.period ?? 2), 0, 2); @@ -787,17 +816,117 @@ function applyAction(plan: StepPlan, a: Action, at: number, spinRamp: (spin: Spi if (!(radius > 0)) radius = 1; } // It turns about its own axis: a cylinder's is its long one, as it lies; a kit wheel or anything else turns as a disc seen from the front, about z. - let axis = a.axis; - if (axis === undefined && wheel.def.shape === 'cylinder') { - const v = restPoint(asVec(valueAt(wheel.rot, at)), [1, 1, 1], [0, 1, 0]); - const big = Math.max(Math.abs(v[0]), Math.abs(v[1]), Math.abs(v[2])); - axis = Math.abs(v[0]) === big ? 'x' : Math.abs(v[1]) === big ? 'y' : 'z'; - } + const axis = a.axis ?? (wheel.def.shape === 'cylinder' ? longAxis(wheel, at).axis : undefined); applyAction(plan, { op: 'spin', id: a.wheel, rpm: a.rpm ?? 20, axis: axis ?? 'z', at }, at, spinRamp, context); - applyAction(plan, { op: 'joint', id: a.id, kind: 'slide', axis: 'y', at }, at, spinRamp, context); + applyAction(plan, { op: 'joint', id: a.id, kind: 'slide', axis: 'y', ...(a.min !== undefined ? { min: a.min } : {}), ...(a.max !== undefined ? { max: a.max } : {}), at }, at, spinRamp, context); applyAction(plan, { op: 'couple', id: a.id, by: a.wheel, pitch: 2 * Math.PI * radius, at }, at, spinRamp, context); return; } + case 'wave': { + // A swell or squeeze that runs along a tube; its place is an angle kept like a stream's laps, so a marker of the same period rides the crest. + const tube = lookup(plan.objs, a.id, at); + if (!tube || tube.def.shape !== 'tube') return; + const driver = waveDriver(tube.key); + plan.waves = plan.waves.filter((w) => w.key !== tube.key); + plan.spins = plan.spins.filter((s) => s.key !== driver); + if (a.stop !== true) { + plan.waves.push({ key: tube.key, amount: a.amount ?? 1.6, width: a.width ?? 0.2, count: a.count ?? 1 }); + const sp = spinPlanFrom({ key: driver, axis: 2, angle: 0, rate: 0 }); + plan.spins.push(sp); + setRate(sp, at, 360 / (a.period ?? STREAM_PERIOD), 0, 2); + } + end(0.2); + return; + } + case 'pendulum': { + // A swing about the hang point, let go at the far end, with the period a longer string asks for. + const o = lookup(plan.objs, a.id, at); + if (!o) return; + // Hung from a part, the pivot is that part's middle wherever it is (worked out each frame, through any parents); the string's length, for the period, is read from where both stand now. + const holder = a.from !== undefined && !a.pivot ? lookup(plan.objs, a.from, at) : undefined; + if (!a.pivot && !holder) return; + const reach = a.pivot ? asVec(a.pivot) : (rootPos(plan, holder as ObjInst, at).map((v, i) => v - (rootPos(plan, o, at)[i] as number)) as Vec3); + const length = Math.hypot(reach[0], reach[1], reach[2]); + applyAction(plan, { op: 'loop', id: a.id, kind: 'swing', axis: a.axis ?? 'z', amount: a.swing ?? 25, period: a.period ?? Math.max(0.8, Math.min(6, 1.6 * Math.sqrt(length))), ...(a.pivot ? { pivot: asVec(a.pivot) } : { pivotOn: a.from }), phase: 90, ...(a.damp !== undefined ? { damp: a.damp } : {}), at }, at, spinRamp, context); + return; + } + case 'oscillate': { + // A slide let go at the low end; amount is the travel each way, a slide's is the whole. + applyAction(plan, { op: 'loop', id: a.id, kind: 'slide', axis: a.axis ?? 'y', amount: 2 * (a.amount ?? 0.5), period: a.period ?? 1.5, phase: 270, ...(a.damp !== undefined ? { damp: a.damp } : {}), at }, at, spinRamp, context); + return; + } + case 'float': { + applyAction(plan, { op: 'loop', id: a.id, kind: 'float', amount: a.bob ?? 0.15, tilt: a.tilt ?? 4, period: a.period ?? 3, ...(a.damp !== undefined ? { damp: a.damp } : {}), at }, at, spinRamp, context); + return; + } + case 'drop': { + const o = lookup(plan.objs, a.id, at); + if (!o || !aliveAt(o, at)) return; + context.targets?.set(a, o); + const from = valueAt(o.pos, at); + const bounce = a.bounce ?? 0.3; + const seconds = 'dur' in a && a.dur !== undefined ? a.dur : fallSeconds((from[1] ?? 0) - a.to, bounce); + o.pos.segs.push({ start: at, dur: seconds, from, to: [from[0] ?? 0, a.to, from[2] ?? 0], fall: bounce }); + end(seconds); + return; + } + case 'pump': { + // The chamber squeezes and refills; the outlet flap opens while it squeezes and the inlet while it refills, all on the one cycle (the same period from the same start). + const chamber = lookup(plan.objs, a.id, at); + if (!chamber) return; + const period = a.period ?? 1.2; + const open = a.open ?? 70; + const axis = a.axis ?? 'z'; + applyAction(plan, { op: 'loop', id: a.id, kind: 'pulse', amount: a.squeeze ?? 0.7, period, at }, at, spinRamp, context); + const flap = (id: string | undefined, phase: number): void => { + if (id === undefined || !lookup(plan.objs, id, at)) return; + applyAction(plan, { op: 'joint', id, kind: 'hinge', axis, about: a.hinge ?? 'left', at }, at, spinRamp, context); + applyAction(plan, { op: 'loop', id, kind: 'gate', axis, amount: open, period, phase, at }, at, spinRamp, context); + }; + // The chamber's cycle starts at 180 degrees (relaxed) and shrinks to 360; a flap opens on the cosine of its own angle, so the outlet's angle runs a quarter turn ahead + // of the chamber's (open while it shrinks) and the inlet's a quarter turn behind (open while it grows back). + flap(a.outlet, 0); + flap(a.inlet, -180); + return; + } + case 'incline': { + // The load slides along the slope, a tilted slide joint with a loop on it. + const load = lookup(plan.objs, a.id, at); + const ramp = a.ramp !== undefined ? lookup(plan.objs, a.ramp, at) : undefined; + if (!load || (a.ramp !== undefined && (!ramp || ramp.key === load.key))) return; + const along: Vec3 = ramp ? restPoint(asVec(valueAt(ramp.rot, at)), [1, 1, 1], [1, 0, 0]) : [Math.cos(((a.angle ?? 0) * Math.PI) / 180), Math.sin(((a.angle ?? 0) * Math.PI) / 180), 0]; + applyAction(plan, { op: 'joint', id: a.id, kind: 'slide', dir: along, at }, at, spinRamp, context); + applyAction(plan, { op: 'loop', id: a.id, kind: 'slide', amount: a.travel ?? 4, period: a.period ?? 4, at }, at, spinRamp, context); + return; + } + case 'wedge': { + // The wedge slides in and out along its axis; the part it drives slides across it by tan(angle) of that, to the side it lies on. + const wedge = lookup(plan.objs, a.id, at); + const block = lookup(plan.objs, a.drives, at); + if (!wedge || !block || wedge.key === block.key) return; + const axis = a.axis ?? 'y'; + const across = axis === 'y' ? 'x' : 'y'; + const slot = across === 'x' ? 0 : 1; + const side = (asVec(valueAt(block.pos, at))[slot] as number) >= (asVec(valueAt(wedge.pos, at))[slot] as number) ? 1 : -1; + applyAction(plan, { op: 'joint', id: a.id, kind: 'slide', axis, at }, at, spinRamp, context); + applyAction(plan, { op: 'loop', id: a.id, kind: 'slide', amount: a.travel ?? 2, period: a.period ?? 3, at }, at, spinRamp, context); + applyAction(plan, { op: 'joint', id: a.drives, kind: 'slide', axis: across, at }, at, spinRamp, context); + applyAction(plan, { op: 'couple', id: a.drives, by: a.id, ratio: Math.tan(((a.angle ?? 20) * Math.PI) / 180) * side * (axis === 'y' ? -1 : 1), at }, at, spinRamp, context); + return; + } + case 'screw': { + // The screw turns about its length; the nut slides along that, by the pitch for each turn. + const nut = lookup(plan.objs, a.id, at); + const screw = lookup(plan.objs, a.screw, at); + if (!nut || !screw || nut.key === screw.key) return; + const long = screw.def.shape === 'cylinder' ? longAxis(screw, at) : { axis: 'y' as const, dir: [0, 1, 0] as Vec3 }; + const axis = a.axis ?? long.axis; + const dir: Vec3 = a.axis === undefined ? long.dir : a.axis === 'x' ? [1, 0, 0] : a.axis === 'y' ? [0, 1, 0] : [0, 0, 1]; + applyAction(plan, { op: 'spin', id: a.screw, rpm: a.rpm ?? 30, axis, at }, at, spinRamp, context); + applyAction(plan, { op: 'joint', id: a.id, kind: 'slide', dir, ...(a.min !== undefined ? { min: a.min } : {}), ...(a.max !== undefined ? { max: a.max } : {}), at }, at, spinRamp, context); + applyAction(plan, { op: 'couple', id: a.id, by: a.screw, pitch: a.pitch ?? 0.5, at }, at, spinRamp, context); + return; + } case 'muscle': { // A connector pulls the part it is on: that part's hinge or pivot is turned until the connector is as short as the cycle says. const conn = lookup(plan.objs, a.id, at); @@ -909,6 +1038,7 @@ function replaceObject(plan: StepPlan, old: ObjInst, fresh: ObjInst, at: number) for (const sp of plan.spins) { if (sp.key === old.key) sp.key = fresh.key; if (sp.key === loopDriver(old.key)) sp.key = loopDriver(fresh.key); + if (sp.key === waveDriver(old.key)) sp.key = waveDriver(fresh.key); for (const axis of [0, 1, 2] as const) if (sp.key === ballDriver(old.key, axis)) sp.key = ballDriver(fresh.key, axis); if (sp.lock) sp.lock.byKey = to(sp.lock.byKey); } @@ -919,6 +1049,7 @@ function replaceObject(plan: StepPlan, old: ObjInst, fresh: ObjInst, at: number) plan.joints = plan.joints.map((j) => ({ ...j, key: to(j.key), toKey: j.toKey === null ? null : to(j.toKey) })); plan.couples = plan.couples.map((c) => ({ ...c, key: to(c.key), byKey: to(c.byKey) })); plan.muscles = plan.muscles.map((m) => ({ ...m, key: to(m.key), holderKey: to(m.holderKey), connectorKey: to(m.connectorKey) })); + plan.waves = plan.waves.map((w) => ({ ...w, key: to(w.key) })); // The new one sits where the old one was in the list, so parents still come before their children. plan.objs.splice(plan.objs.indexOf(old) + 1, 0, fresh); plan.duration = Math.max(plan.duration, at + REPLACE_SECONDS); @@ -927,6 +1058,32 @@ function replaceObject(plan: StepPlan, old: ObjInst, fresh: ObjInst, at: number) /** Seconds a stream's markers take for the whole way when the scene gives no period. */ export const STREAM_PERIOD = 4; +/** Where an object's origin stands in the scene, adding up its place and its parents', each as the object is mounted (turns and scales of parents are left out: this is for lengths only, such as a string's). */ +function rootPos(plan: StepPlan, o: ObjInst, at: number, depth = 0): Vec3 { + const own = asVec(valueAt(o.pos, at)); + const parent = o.parentKey !== null ? plan.objs.find((p) => p.key === o.parentKey) : undefined; + if (!parent || depth > 8) return own; + let local = own; + if (hasMount(o.def)) { + const d = o.def as { parentAnchor?: string; selfAnchor?: string }; + const from = anchorsOf({ ...parent.def, ...(parent.points ? { points: parent.points } : {}) })[d.parentAnchor ?? 'origin']; + const mine = anchorsOf({ ...o.def, ...(o.points ? { points: o.points } : {}) })[d.selfAnchor ?? 'origin']; + if (from && mine) local = mountPosition(from, mine, asVec(valueAt(o.rot, at)), own, asVec(valueAt(o.scale, at))); + } + const base = rootPos(plan, parent, at, depth + 1); + return [base[0] + local[0], base[1] + local[1], base[2] + local[2]]; +} + +/** The axis a cylinder lies along (the letter, and the unit direction it points in, in its parent's space). */ +function longAxis(o: ObjInst, at: number): { axis: 'x' | 'y' | 'z'; dir: Vec3 } { + const v = restPoint(asVec(valueAt(o.rot, at)), [1, 1, 1], [0, 1, 0]); + const big = Math.max(Math.abs(v[0]), Math.abs(v[1]), Math.abs(v[2])); + const i = Math.abs(v[0]) === big ? 0 : Math.abs(v[1]) === big ? 1 : 2; + const dir: Vec3 = [0, 0, 0]; + dir[i] = (v[i] as number) < 0 ? -1 : 1; + return { axis: i === 0 ? 'x' : i === 1 ? 'y' : 'z', dir }; +} + /** * A stream: markers running along a path on the 3D stage (it hangs from the path, so it goes with it) or along an arrow of a flat diagram. Its laps are * an angle kept like a loop's (under the key loopDriver gives), free at one lap a period or locked to a spinning part, so it runs on by itself. @@ -964,6 +1121,37 @@ function addStream(plan: StepPlan, a: Extract, a else setRate(sp, at, 360 / (a.period ?? STREAM_PERIOD), 0, 2); } +/** Field lines: a group, and an arrow for each line, drawn on together. Written again, the old lines go. */ +function addField(plan: StepPlan, a: Extract, at: number, end: (len: number) => void): void { + const parent = a.parent !== undefined ? lookup(plan.objs, a.parent, at) : undefined; + if (a.parent !== undefined && !parent) return; + const before = lookup(plan.objs, a.id, at); + if (before) { + for (const d of [before, ...descendants(plan, before.key, at)]) { + d.diedAt = at; + d.wipe = REPLACE_SECONDS; + } + } + const color = parseColor(a.color ?? 'teal'); + const group: ObjInst = { + key: plan.nextKey++, id: a.id, parentKey: parent ? parent.key : before ? before.parentKey : null, def: a, bornAt: at, diedAt: undefined, + pos: track(a.pos ?? [0, 0, 0]), rot: track([0, 0, 0]), scale: track([1, 1, 1]), color: track(color), opacity: track([a.opacity ?? 1]), + draw: track([1]), spread: track([0]), + }; + plan.objs.push(group); + fieldLines(a).forEach((pts, i) => { + const id = `${a.id}.${i + 1}`; + const line: ObjInst = { + key: plan.nextKey++, id, parentKey: group.key, def: { op: 'add', shape: 'arrow', id, pts, fine: true } as unknown as AddAction, bornAt: at, diedAt: undefined, + pos: track([0, 0, 0]), rot: track([0, 0, 0]), scale: track([1, 1, 1]), color: track(color), opacity: track([a.opacity ?? 1]), + draw: track([0]), spread: track([0]), + }; + tweenTo(line.draw, at, 0.9, [1]); + plan.objs.push(line); + }); + end(0.9); +} + /** Makes the copies of an array: the original joins a new group, and each further copy sits in a pivot that carries the step and turn. */ function addArray(plan: StepPlan, a: Extract, at: number): void { const of = lookup(plan.objs, a.of, at); @@ -1118,16 +1306,18 @@ export function evaluate(plan: StepPlan, t: number): Frame { }); } const motion = motionOf(plan, objects, spinTime, diagrams); + const coming = spinTime < plan.duration ? motionOf(plan, objects, plan.duration, diagrams) : undefined; + const ahead = coming && coming.spins.some((s) => s.rate !== 0 && !motion.spins.some((m) => m.key === s.key && m.rate !== 0)) ? coming : undefined; applyPoses(objects, motion); applyPhases(objects, motion); let panel: Frame['panel'] = null; for (const p of plan.panels) { if (!visibleAt(p, t)) continue; const r = valueAt(p.rect, t); - panel = { rect: { x: r[0] ?? 0, y: r[1] ?? 0, w: r[2] ?? 0, h: r[3] ?? 0 }, appear: appearOf(p, t), fade: fadeOf(p, t), frame: p.frame }; + panel = { rect: { x: r[0] ?? 0, y: r[1] ?? 0, w: r[2] ?? 0, h: r[3] ?? 0 }, appear: appearOf(p, t), fade: fadeOf(p, t), frame: p.frame, leaving: p.diedAt !== undefined && p.diedAt <= t }; } return { - panel, marks, diagrams: phasedDiagrams(diagrams, motion), objects, nextKey: plan.nextKey, motion, + panel, marks, diagrams: phasedDiagrams(diagrams, motion), objects, nextKey: plan.nextKey, motion, ...(ahead ? { ahead } : {}), camera: { az: valueAt(plan.az, t)[0] ?? 0, el: valueAt(plan.el, t)[0] ?? 0, zoom: valueAt(plan.zoom, t)[0] ?? 1, focus: focusAt(plan.focus, t), @@ -1180,7 +1370,7 @@ function parentsFirst(objs: readonly ObjInst[]): readonly ObjInst[] { /** What is turning at time `t`, and what is tied to it, limited to what is still on the stage. */ function motionOf(plan: StepPlan, objects: readonly ObjectFrame[], t: number, diagrams: readonly DiagramFrame[] = []): Motion { - if (plan.spins.length + plan.cranks.length + plan.cams.length + plan.flashes.length + plan.loops.length + plan.joints.length + plan.couples.length + plan.muscles.length === 0) return emptyMotion(); + if (plan.spins.length + plan.cranks.length + plan.cams.length + plan.flashes.length + plan.loops.length + plan.joints.length + plan.couples.length + plan.muscles.length + plan.waves.length === 0) return emptyMotion(); const alive = new Set(objects.map((o) => o.key)); for (const d of diagrams) for (const it of d.items) if (it.def.op === 'stream') alive.add(it.key); // A loop's angle (under a key below zero) lives as long as the object it moves. @@ -1195,6 +1385,7 @@ function motionOf(plan: StepPlan, objects: readonly ObjectFrame[], t: number, di joints: plan.joints.filter((j) => alive.has(j.key) && (j.toKey === null || alive.has(j.toKey))), couples: plan.couples.filter((c) => both(c.key, c.byKey)), muscles: plan.muscles.filter((m) => both(m.key, m.holderKey) && alive.has(m.connectorKey)), + waves: plan.waves.filter((w) => alive.has(w.key)), }; } @@ -1202,9 +1393,22 @@ function motionOf(plan: StepPlan, objects: readonly ObjectFrame[], t: number, di function applyPhases(objects: ObjectFrame[], motion: Motion): void { if (motion.spins.length === 0) return; const angles = new Map(motion.spins.map((s) => [s.key, s.angle] as const)); + const waves = new Map((motion.waves ?? []).map((w) => [w.key, w] as const)); for (const o of objects) { - const angle = o.shape === 'stream' ? angles.get(loopDriver(o.key)) : undefined; - if (angle !== undefined) o.phase = angle / 360; + const angle = o.shape === 'stream' || o.shape === 'particles' ? angles.get(loopDriver(o.key)) : undefined; + if (angle !== undefined) { + o.phase = angle / 360; + const def = o.def as { surge?: number; beat?: number; period?: number; by?: string }; + // A flow that comes in beats: the markers speed up and slow down once a beat, which is a smooth bend of the laps (the speed is 1 + surge x cosine of the beat). + if (o.shape === 'stream' && def.surge !== undefined && def.by === undefined) { + const period = def.period ?? STREAM_PERIOD; + const beat = def.beat ?? 1; + o.phase += ((def.surge * beat) / (2 * Math.PI * period)) * Math.sin((2 * Math.PI * o.phase * period) / beat); + } + } + const wave = waves.get(o.key); + const where = wave ? angles.get(waveDriver(o.key)) : undefined; + if (wave && where !== undefined) o.wave = { phase: where / 360, amount: wave.amount, width: wave.width, count: wave.count }; } } @@ -1251,7 +1455,7 @@ function holdMount(o: ObjectFrame, pose: Pose, motion: Motion): void { if (motion.joints.some((j) => j.key === o.key && (j.kind === 'fixed' || pivot(j.pivot)))) return; // A pivot turns a part about its own axis through its own middle: its attached point stays only if that point is on the axis, so it is left to the joint. if (motion.joints.some((j) => j.key === o.key && j.kind === 'pivot')) return; - if (motion.loops.some((l) => l.key === o.key && pivot(l.pivot))) return; + if (motion.loops.some((l) => l.key === o.key && (pivot(l.pivot) || l.pivotKey !== undefined))) return; const grown: Vec3 = [o.scale[0] * (pose.scale?.[0] ?? 1), o.scale[1] * (pose.scale?.[1] ?? 1), o.scale[2] * (pose.scale?.[2] ?? 1)]; const shift = heldShift(o.rot, pose.rot ?? o.rot, o.scale, grown, o.mount.self); const base = pose.pos ?? o.pos; @@ -1281,6 +1485,40 @@ export function withMotion(frame: Frame, seconds: number, from: Motion = frame.m return { ...frame, objects, diagrams: phasedDiagrams(frame.diagrams, motion), motion }; } +/** How many poses a swept fit takes of a running machine (see `sweptPoses`). */ +export const SWEEP_SAMPLES = 40; +/** The longest a cycle is sampled over, seconds: a slower one is seen in part. */ +const SWEEP_LONGEST = 60; + +/** + * The poses a running machine takes over its whole cycle, for the camera to fit the stage to everything the model does and not only to how it stands at + * rest (a wing flapped out of its rest shape, a door swung toward the viewer). A pure function of the frame's motion and not of the time it is asked at: + * every turning angle is put back to its start and run on by moments spread over the slowest cycle (one that does not meet a faster one's rhythm), so + * the same machine gives the same set at any moment and the camera does not breathe. It reads the machine the frame will have later in its step (`ahead`) + * when something has not started yet, so a loop written to begin at 3 s is fitted from 0. A frame with nothing turning, now or later in the step, gives none. + */ +export function sweptPoses(frame: Frame, count = SWEEP_SAMPLES): Array> { + const motion = frame.ahead ?? frame.motion; + const running = motion.spins.filter((s) => s.rate !== 0); + if (running.length === 0) return []; + const span = Math.min(SWEEP_LONGEST, Math.max(...running.map((s) => 360 / Math.abs(s.rate)))); + const base: Motion = { ...motion, spins: motion.spins.map((s) => (s.rate !== 0 && !s.lock ? { ...s, angle: 0 } : s)) }; + const bare = frame.objects.map((o) => { + const { pose: _gone, ...rest } = o; + return rest as ObjectFrame; + }); + const out: Array> = []; + const golden = 0.6180339887498949; + for (let j = 0; j < count; j++) { + const objects = bare.map((o) => ({ ...o })); + applyPoses(objects, advanceMotion(base, span * ((j * golden) % 1))); + const placed = new Map(); + for (const o of objects) if (o.pose) placed.set(o.key, o.pose); + out.push(placed); + } + return out; +} + /** How far in and out the person may zoom the 3D panel: the scene language's own limits, so a wheel step never moves a scene's own zoom. */ export const ZOOM_MIN = 0.2; export const ZOOM_MAX = 5; diff --git a/src/scene/field-lines.ts b/src/scene/field-lines.ts new file mode 100644 index 0000000..71a3409 --- /dev/null +++ b/src/scene/field-lines.ts @@ -0,0 +1,106 @@ +// Field lines, illustrated: where the arrows of a magnet's field, a charge's or a mass's, or the field between two plates, run. Pure geometry in the front +// plane (z = 0) about the middle of the field; the timeline turns each line into an arrow. Nothing is solved: a dipole's lines are the textbook curves +// r = L sin^2(theta), kept to the outside of the magnet; the rest are straight. + +import type { Vec3 } from './types.ts'; + +export type FieldKind = 'dipole' | 'radial' | 'uniform'; +export type FieldShape = { kind: FieldKind; axis?: 'x' | 'y'; size?: number; count?: number; gap?: number; flip?: boolean }; + +const POINTS = 24; + +/** A point from its place along the axis and across it, in the front plane. */ +function at(axis: 'x' | 'y', along: number, across: number): Vec3 { + return axis === 'x' ? [along, across, 0] : [across, along, 0]; +} + +/** The field of a positive pole at +x and a negative at -x (a unit each), at a point of the front plane. */ +function fieldAt(px: number, py: number, pole: number): [number, number] { + let ex = 0, ey = 0; + for (const [cx, sign] of [[pole, 1], [-pole, -1]] as const) { + const dx = px - cx, dy = py; + const d3 = Math.pow(dx * dx + dy * dy, 1.5) || 1e-9; + ex += (sign * dx) / d3; + ey += (sign * dy) / d3; + } + return [ex, ey]; +} + +/** + * One line of a dipole: from a ring round the positive pole at `alpha` from the axis, step by step the way the field points (a short step, a midpoint + * correction) until it comes to the negative pole, or has gone far past `size`; then `POINTS` points of it spaced by length. `side` mirrors it below the axis. + */ +function traceLine(pole: number, ring: number, alpha: number, side: number, size: number, axis: 'x' | 'y'): Vec3[] { + const path: Array<[number, number]> = [[pole + ring * Math.cos(alpha), side * ring * Math.sin(alpha)]]; + const step = Math.max(0.01, pole * 0.04); + for (let i = 0; i < 4000; i++) { + const [px, py] = path[path.length - 1] as [number, number]; + if (Math.hypot(px + pole, py) < ring || Math.hypot(px, py) > size * 1.6) break; + const dir = (x: number, y: number): [number, number] => { + const [ex, ey] = fieldAt(x, y, pole); + const n = Math.hypot(ex, ey) || 1; + return [ex / n, ey / n]; + }; + const [dx, dy] = dir(px, py); + const [mx, my] = dir(px + (dx * step) / 2, py + (dy * step) / 2); + path.push([px + mx * step, py + my * step]); + } + // Even by length. + const cum = [0]; + for (let i = 1; i < path.length; i++) cum.push((cum[i - 1] as number) + Math.hypot((path[i] as number[])[0]! - (path[i - 1] as number[])[0]!, (path[i] as number[])[1]! - (path[i - 1] as number[])[1]!)); + const total = cum[cum.length - 1] as number; + const out: Vec3[] = []; + let j = 1; + for (let i = 0; i < POINTS; i++) { + const want = (total * i) / (POINTS - 1); + while (j < path.length - 1 && (cum[j] as number) < want) j++; + const span = (cum[j] as number) - (cum[j - 1] as number); + const t = span > 1e-12 ? (want - (cum[j - 1] as number)) / span : 0; + const p0 = path[j - 1] as [number, number], p1 = path[j] as [number, number]; + out.push(at(axis, p0[0] + (p1[0] - p0[0]) * t, p0[1] + (p1[1] - p0[1]) * t)); + } + return out; +} + +/** + * The lines, each a run of points in the direction the field points (the lines of a dipole leave the end on the positive side of the axis and curve + * round to the other; `flip` reverses them all). Never more than `count` lines, and never a line with fewer than two points. + */ +export function fieldLines(shape: FieldShape): Vec3[][] { + const axis = shape.axis ?? 'x'; + const size = Math.max(0.5, shape.size ?? 5); + const count = Math.max(2, Math.min(16, Math.round(shape.count ?? 8))); + const lines: Vec3[][] = []; + if (shape.kind === 'dipole') { + // Two opposite poles near the ends of a bar `gap` long (three tenths of the reach by default). Each line is followed from a small ring round the + // positive pole, the way the field points, to the negative one. They leave at angles from the axis chosen so the widest loop just reaches `size`. + const end = Math.max(0.1, (shape.gap ?? size * 0.3) / 2); + const pole = end * 0.85; + const ring = pole * 0.3; + // A loop launched at angle alpha from the axis is widest (across the middle) at pole x tan(phi) with cos(phi) = (1 - cos(alpha)) / 2. + const keep = pole / Math.hypot(pole, size); + const widest = Math.acos(Math.max(-1, Math.min(1, 1 - 2 * keep))); + const perSide = Math.max(1, Math.floor(count / 2)); + const last = (120 * Math.PI) / 180; + for (let side = 1; side >= -1; side -= 2) { + for (let k = 0; k < perSide; k++) { + const alpha = perSide === 1 ? (widest + last) / 2 : last - ((last - widest) * k) / (perSide - 1); + lines.push(traceLine(pole, ring, alpha, side, size, axis)); + } + } + } else if (shape.kind === 'radial') { + const from = Math.max(0.05, (shape.gap ?? 1) / 2); + for (let i = 0; i < count; i++) { + const a = (2 * Math.PI * i) / count; + lines.push([[Math.cos(a) * from, Math.sin(a) * from, 0], [Math.cos(a) * size, Math.sin(a) * size, 0]]); + } + } else { + // Parallel lines along the axis, spread across the gap between the plates. + const across = shape.gap ?? size * 0.6; + for (let i = 0; i < count; i++) { + const y = count === 1 ? 0 : -across / 2 + (across * i) / (count - 1); + lines.push([at(axis, -size / 2, y), at(axis, size / 2, y)]); + } + } + return shape.flip === true ? lines.map((l) => [...l].reverse()) : lines; +} diff --git a/src/scene/guide.ts b/src/scene/guide.ts index 6b51f46..7e48280 100644 --- a/src/scene/guide.ts +++ b/src/scene/guide.ts @@ -62,27 +62,23 @@ const lines: string[] = [ 'Answer with JSON only: {"steps":[{"say":"words to speak","actions":[...]}],"escalate":null}. Each step is drawn and spoken as soon as it is written.', 'Rules:', '- Choose words alone (actions: []), a mark on the page, a flat diagram or a 3D model, whichever explains best; use no actions when words suffice, and never draw for its own sake. A diagram of a physical thing or process is a 3D scene with streams for what moves.', - '- Step 1 is short, so something appears within a second or two: one sentence that begins the answer itself (never a description of the page or of what was circled) and one or two marks if useful (actions may be empty) on what the question is about (or a panel), and nothing else. Pick the mark that fits what it points at: a box or circle for text or a region; for a part inside a picture (a figure, graph, map or photo) a poly with a point on each corner of a tilted or irregular shape (a tilted square is a poly, not a circle), a point on one exact spot, a trace along a curve or a coast; never an oval over a tilted shape or a coastline. When needed, build a 3D model or a flat diagram (below) from step 2 on, a few parts at a time, and add detail in later steps. Never put a whole model in step 1. When a model explains a machine or mechanism (an engine, a lock, a gearbox, a pump), build it from step 2 on and set it running as soon as its moving parts are in, so it plays while you explain; marks on the page support the model and do not replace it. Marks alone answer where-is-it questions (where to click, what a thing is called). When the parts or places of a picture are the point of the question (the chambers of a heart, the islands and straits of a map, the sides of a figure), name them, a few to a step from step 2 on: say each name as you reach it and put it on the picture, a point well inside the part (on the land of an island, never on its edge or out at sea) and a label of one to three words beside it, on the picture it names. When the picture is small (a fifth of the screen width or less, so its parts crowd each other) and a card at least 1.5 times as wide as it still fits (the card is dw * sh / sw tall, keep that at most 700), you never label it where it stands: enlarge it first, in the step before the names: an image of its own box (sx, sy, sw, sh) as a card of dw at least 1.5 * sw, where it reads best and large, never over what the answer points at, and put the points and labels on that card: a part at x, y on the screenshot is at dx + (x - sx) * dw / sw, dy + (y - sy) * dw / sw on it. A box round the picture is not a naming, and name only what you can see and are sure of. An explain, how-does or walk-me-through question asks how the thing works: teach its mechanism, causes and steps, and never describe the page. If a diagram helps, use a 3D scene for any physical thing, place or natural process (the water cycle, a heart, an engine, a river forming: its parts as shapes, streams for what moves), also when a diagram or drawing of it is asked for, and a flat diagram (below) only for an abstract process, the events in time, the steps or the quantities involved, or when a flowchart is asked for, drawn where it reads best and large as you speak, never over what the answer points at, with the marks on the page supporting it. A circle, underline or arrow only says which subject the question is about; the picture is at most an example to point at while you teach, and what it happens to show is not the topic. A box on the page figure is not an explanation.', + '- Step 1 is short, so something appears within a second or two: one sentence that begins the answer itself (never a description of the page or of what was circled) and one or two marks if useful (actions may be empty) on what the question is about (or a panel), and nothing else. Pick the mark that fits what it points at: a box or circle for text or a region; for a part inside a picture (a figure, graph, map or photo) a poly with a point on each corner of a tilted or irregular shape (a tilted square is a poly, not a circle), a point on one exact spot, a trace along a curve or a coast; never an oval over a tilted shape or a coastline. Marks alone answer where-is-it questions (where to click, what a thing is called). When needed, build a 3D model or a flat diagram (below) from step 2 on, a few parts at a time, and add detail in later steps; never put a whole model in step 1. When a model explains a machine or mechanism (an engine, a lock, a gearbox, a pump), set it running as soon as its moving parts are in, so it plays while you explain; marks on the page support the model and do not replace it. When the parts or places of a picture are the point of the question (the chambers of a heart, the islands and straits of a map, the sides of a figure), name them, a few to a step from step 2 on: say each name as you reach it and put it on the picture, a point well inside the part (on the land of an island, never on its edge or out at sea) and a label of one to three words beside it, on the picture it names. When the picture is small (a fifth of the screen width or less, so its parts crowd each other) and a card at least 1.5 times as wide as it still fits (the card is dw * sh / sw tall, keep that at most 700), you never label it where it stands: enlarge it first, in the step before the names: an image of its own box (sx, sy, sw, sh) as a card of dw at least 1.5 * sw, where it reads best and large, never over what the answer points at, and put the points and labels on that card: a part at x, y on the screenshot is at dx + (x - sx) * dw / sw, dy + (y - sy) * dw / sw on it. A box round the picture is not a naming, and name only what you can see and are sure of. An explain, how-does or walk-me-through question asks how the thing works: teach its mechanism, causes and steps. If a diagram helps, use a 3D scene for any physical thing, place or natural process (the water cycle, a heart, an engine, a river forming: its parts as shapes, streams for what moves), also when a diagram or drawing of it is asked for, and a flat diagram (below) only for an abstract process, the events in time, the steps or the quantities involved, or when a flowchart is asked for, drawn where it reads best and large as you speak, never over what the answer points at. A circle, underline or arrow only says which subject the question is about; what it happens to show is not the topic.', '- The say of every explanation step opens with a short first sentence, about 6 words or 30 characters at most, and then the rest: the voice starts on the first sentence as soon as it is made, so a short opener is heard sooner. The cap on the whole say stays; a walk move is that one short sentence alone.', '- The question sets the task; the page, and anything circled on it, is material to use, never a subject to report on. Never open with what the page or picture is, and never say where your knowledge comes from or what the page does or does not contain, unless asked. Do not draw again what the page already has (its graph, its table, its list of steps): point at it with marks and say what it shows. Draw only when it explains better than words alone, to show what the page only says in words or leaves unsaid (a process, a sequence in time, a cause). Where the page gives the content (the proof its figure shows, the steps and amounts it lists), use that, not another. A label starts just to the right of its point, at the height of the point, so each name clearly belongs to its point.', '- State as fact only what a picture clearly shows (a pose, a position, a word you can read); where it does not show something (a hand, a tool, a contact, an angle), teach the general point without pinning it on the photo. Never quote an angle, size or distance you cannot measure: show a direction by drawing along a real edge or line in the picture, and give a number only if the page says it.', `- Screen coordinates run 0 to 1000 across the screenshot (x right, y down). Each size is along its own axis, so a round shape on a 16:9 screen has w about 9/16 of h.`, - '- Mark shapes: rot tilts a box or circle; poly takes a point on each corner; point marks one exact spot (a crossing, a tip, a place on a map); trace follows a curve or path through points set along it (head true ends it in an arrowhead); an arrow ends with its tip on what it points at. Put each mark exactly on the thing: the overlay may nudge it a few percent onto the lines and corners of the page itself, so do not count on that.', - '- 3D: units x right, y up, z toward the viewer. Size-based solids are centred on their pos; hull points stay in their authored local coordinates. The panel is the rectangle the model is fitted to; the model floats over the page with a shadow. Give it room: about 60 percent of the screen height (h near 600), and narrower than tall for a tall or compact model, since the screen is wider than tall and a panel as wide as it is tall is a wide slab. The camera frames the whole model to the panel, so only proportions matter, not the units you draw in: zoom 1 shows all of it, a higher zoom comes in closer on the focused part. Angles are degrees. Never zoom past about 1.6 on one part if the rest should stay legible.', - '- Build models from parts, not primitives alone: box with a bevel for housings, material for the surface (' + MATERIAL_NAMES.join(' ') + '; name what it is made of: bone, muscle, tendon, skin for a body, steel, iron, brass, copper for machines, wood, rope, water; leave color out unless it should differ, since a tint gives the material a hue but keeps it within its own lightness, so bone stays bone on a white page, never write white for bone), part for ready-made electronics and machine parts (the part action below lists them, with sizes, axes and anchors), array for repeats (one blade, count 9, turn 40; add the object an array copies before the array), extrude for wings and plates, hull for irregular convex solids from 4 to 64 3D corners, lathe for round bodies, tube for cables, patch for shaped open sheets (16 Bézier controls in four rows; use a regular net, not sixteen points to interpolate).', - '- Extrude holes are through-openings in the outline local XY plane: use up to 8 separate rings strictly inside the outline, no touching, crossing or nesting. Each ring has 3 to 24 points; all rings and the outline total at most 128 points. Either winding and one repeated closing point are accepted. Openings use flat edges (bevel 0).', - '- For a closed cutaway of a round body, use lathe with sweep 1..359 degrees and a simple closed profile of 3..40 [radius,y] points (radius 0..100, y -100..100). It starts at +z towards +x around +y; rotate to choose the opening. Axis contact is allowed; avoid thin, touching or crossing boundaries. Omit sweep for the original full lathe.', - '- Tune the finish on shapes with material: roughness 0 polished to 1 matte, metalness 0 nonmetal to 1 metal, clearcoat 0 to 1, clearcoatRoughness 0 polished to 1 matte. Omit/null keeps each named-material value; zero overrides it. For a fully matte finish also set clearcoat 0. Low quality disables clearcoat. These are add fields, not style animation; parts keep their mixed surfaces. Glass stays see-through, not refractive.', - '- Optional treatment fibres on tube/connector adds longitudinal material detail over any material; muscle, tendon and rope tubes and connectors have it already, so write treatment only to add it elsewhere (a rubber cord). No extra strands, geometry or physics. Omit/null for plain. The renderer follows bends, fades tiny detail and keeps glass transparency. Do not model individual fibres.', - '- For a curved rail or angular band use sweep: a simple outline cross-section and a smooth open pts path, with optional up for its initial +y direction. The section follows with minimum rotation; keep it narrow relative to bends. It is a capped solid, without holes, bevel, stream or reveal.', - '- A loft joins different convex end outlines with equal corner counts: outline at -depth/2, endOutline at +depth/2, corresponding indices and the same winding. Keep every intermediate section convex; no closing repeat, holes or bevel. Use for solid asymmetric transitions, not hollow ducts. On loft or sweep, smooth:true blends rounded section lighting while keeping sharp corners and flat caps; it does not round the silhouette.', - '- shell makes hollow ellipsoid sections with closed radial rims: size is the full outer diameters, inner is a concentric scale (not constant thickness), latitude [0,90] an upper dome, [-90,0] a lower bowl, sweep below 360 an angular opening from +x toward +z. Use rot to aim the opening; its origin stays at the full ellipsoid centre.', + '- Put each mark exactly on the thing: the overlay may nudge it a few percent onto the lines and corners of the page itself, so do not count on that.', + '- 3D: units x right, y up, z toward the viewer; angles in degrees. Size-based solids are centred on their pos; hull points stay in their authored local coordinates. The panel is the rectangle the model is fitted to; the model floats over the page with a shadow. Give it room: about 60 percent of the screen height (h near 600), and narrower than tall for a tall or compact model, since the screen is wider than tall and a panel as wide as it is tall is a wide slab. The camera frames the whole model to the panel, so only proportions matter, not the units you draw in: zoom 1 shows all of it, a higher zoom comes in closer on the focused part (never past about 1.6 on one part if the rest should stay legible).', + '- Build models from parts, not primitives alone: box with a bevel for housings, material for the surface (' + MATERIAL_NAMES.join(' ') + '; name what it is made of: bone, muscle, tendon, skin for a body, steel, brass for machines; leave color out unless it should differ, since a tint gives the material a hue but keeps it within its own lightness, so bone stays bone on a white page, never write white for bone), part for ready-made electronics and machine parts (the part action below lists them), array for repeats (one blade, count 9, turn 40; add the object an array copies before the array), extrude for wings and plates, hull for irregular convex solids, lathe for round bodies, tube for cables, patch for shaped open sheets (16 Bézier controls in four rows; use a regular net, not sixteen points to interpolate); each is listed below.', + '- Tune the finish on shapes with material: roughness 0 polished to 1 matte, metalness 0 to 1, clearcoat 0 to 1, clearcoatRoughness 0 polished to 1 matte. Omit/null keeps each named material\'s value; zero overrides it. For a fully matte finish also set clearcoat 0. Low quality disables clearcoat. Glass stays see-through, not refractive.', + '- treatment fibres on a tube or connector adds longitudinal fibre detail; muscle, tendon and rope tubes and connectors have it already, so write it only to add it elsewhere (a rubber cord). Do not model individual fibres.', '- Living or soft subjects (a heart or other organ, a plant, an animal, a fruit) are never boxes and cylinders. A blob is one smooth skin: give it a lump (pts the centre, sizes the box) for each rounded mass, overlapping the next by about a third, so the chambers of an organ or a body and its head melt into one form; use a separate blob only for another colour or a part that moves, and place it touching. Join with tube and swell (a vessel, stem, limb or tail that tapers or bulges), use lathe for bulbs and fruit, material tissue on all of it.', - '- Build in the order a person would assemble it, because each part appears as you write it: the base or frame first, then the main parts that rest on it, then the moving parts, then small details; one sub-assembly per step. Write an object before anything that refers to it: the group before its parts, a part before its array, its move or its pin, and pins last, once their part exists. A parent is a group or a part made first, and carries what is attached to it. Schedule a new parent at or before its child. A pin, mark or text cannot be a parent, and a pin or mark cannot be moved or pinned. The parts appearing one after another is the animation, so there is no need to explode and reassemble.', + '- Build in the order a person would assemble it, because each part appears as you write it: the base or frame first, then the main parts that rest on it, then the moving parts, then small details; one sub-assembly per step. Write an object before anything that refers to it: the group before its parts, a part before its array, its move or its pin, and pins last, once their part exists. A parent is made first (at or before its child). A pin, mark or text cannot be a parent, and a pin or mark cannot be moved or pinned. The parts appearing one after another is the animation, so there is no need to explode and reassemble.', `- Local part anchors (all parts also have origin): ${PARTS.map((part) => { const names = Object.keys(resolvePartGeometry({ part, size: [1, 1, 1] }).anchors).filter((name) => name !== 'origin'); return names.length ? `${part}: ${names.join(',')}` : ''; }).filter(Boolean).join('; ')}. A crankshaft with n>1 has pin1 through pinN (N=min(n,8)) instead of pin. Anchors use the renderer's normalized part sizes, not the raw box axes.`, - `- Attach parts to each other. Never build a pivot group, or work out an offset, to turn a part about an end or an edge: add the part with parent, parentAnchor (a point of the parent) and selfAnchor (a point of itself, default origin). The two points coincide, pos is the offset from that point, and the part stays attached whatever moves, turns, spins, swings, is dragged or exploded (explode draws a faint line back to the point); a turn or swing loop swings it about its point. Patterns: a door is box id door with parent frame, parentAnchor left, selfAnchor left, then loop id door kind swing axis y amount 60, which swings it on its hinge edge; a forearm is a cylinder with parent humerus, parentAnchor bottom, selfAnchor top, then a swing loop bends it at the elbow; a pulley wheel hangs from its beam with parentAnchor bottom, selfAnchor center, pos [0,-1,0] (a part that spins is attached by its centre, because a spin turns it about its attached point); a weight, a hand or a load hangs under a part the same way, and what joins them is a connector, never a line or tube drawn between the two parts, which would stay behind when they move: connector id rope, from wheel, to weight, fromAnchor left, toAnchor top, radius 0.06. A muscle is a connector too, from a point of the bone to a point of the forearm (fromPoint and toPoint in each part's own space, swell [[0,0.6],[0.5,1.8],[1,0.6]] for the belly: a list of [along 0 to 1, radius factor] pairs, never one number; restLength its resting length), so it follows the swing and bulges. Built-in points are in the shape's own space, so they turn with it: ${BUILT_IN_ANCHORS}. A kit part adds its own; anchor names more (an elbow, a hinge edge; write it before the part that uses it); detach lets a part go. A group has only its origin and the points you name with anchor (no top or bottom of its own): attach to a shape inside it, or name the point first. Any 3D shape can be a parent and any with a place of its own can be attached (not a tube, line, arrow or connector, whose points are written where they go). Unknown names are refused with the available ones; write the parent first, no later than the child.`, - '- Machines move: spin keeps a shaft turning (rpm, or locked to another part by a ratio), crank ties a piston to a spinning crankshaft through its rod, cam opens a valve as a camshaft turns, flash lights a spark or burn at an angle of the cycle, and cut slices a model open to show the inside. These act on parts already added, by id, and add nothing; only the piston, rod and valve move with them, never the cylinder block or a group. Any shape moves as a simple machine: joint (hinge, slide, pivot to turn about its own long axis: a forearm, a tap; ball to turn about all three axes within limit [x,y,z] degrees, one swing loop per axis: a shoulder, a hip; about names the point it turns about: left, top, or one made with anchor), driven by spin or loop (slide, swing, pulse), or coupled to another joint (gear, belt, lever, screw, pulley). A part inside a spinning part (a wheel parented to its cog) already turns with it: spin only the holder, never both. lever rocks a beam about a fulcrum point (center a seesaw; left or right an end, the load or effort between it and the other end), the load and effort attached to the beam so they rise and fall with it; pulley turns a wheel and lifts a load by the rope on it (a winch, a crane, a wheel and axle). muscle makes a connector one that pulls: it shortens by contract (0.1 to 0.25 for a limb) and turns the hinge or pivot of the part it pulls (that joint with min and max wide enough for the way the muscle pulls it, like -120 to 120), so an arm bends by its muscle, not beside it. A bend or swing that is to show from the front turns about z; about x or y it swings toward the viewer and shows little. Motion carries on from step to step: set it up once, then narrate over it.', - '- What runs between parts or along a path is a connector or a stream, not hand-placed shapes: connector for a physical rope, cord, belt, wire, chain, pipe or muscle between two parts of one 3D model (never a tube or line drawn between them, which would not follow them: from, to, and fromAnchor, toAnchor from the built-in points, such as left, right, top, bottom); stream for dots, dashes or arrows travelling along a path (blood through vessels, current in a wire, water in a pipe, cars on a road, data between computers, money in an economy). Straight/slack connectors can use local fromPoint/toPoint, tube-style swell and restLength for a muscle or soft cord that bulges as its moving ends approach; this visual follows authored motion, never applies forces. Create the tube, line, arrow, connector or flow-diagram edge first; stream along names that path, not a surface or unrelated object.', + `- Attach parts to each other. Never build a pivot group, or work out an offset, to turn a part about an end or an edge: add the part with parent, parentAnchor (a point of the parent) and selfAnchor (a point of itself, default origin). The two points coincide, pos is the offset from that point, and the part stays attached whatever moves, turns, spins, swings, is dragged or exploded (explode draws a faint line back to the point); a turn or swing loop swings it about its point. Patterns: a forearm is a cylinder with parent humerus, parentAnchor bottom, selfAnchor top, then a swing loop bends it at the elbow; a pulley wheel hangs from its beam with parentAnchor bottom, selfAnchor center, pos [0,-1,0] (a part that spins is attached by its centre, because a spin turns it about its attached point); a weight, a hand or a load hangs under a part the same way, and a connector joins them (never a tube or line, which would stay behind): connector id rope, from wheel, to weight, fromAnchor left, toAnchor top, radius 0.06. A muscle is a connector too, from a point of the bone to a point of the forearm (fromPoint and toPoint in each part's own space, swell [[0,0.6],[0.5,1.8],[1,0.6]] for the belly: a list of [along 0 to 1, radius factor] pairs, never one number; restLength its resting length), so it follows the swing and bulges. Built-in points are in the shape's own space, so they turn with it: ${BUILT_IN_ANCHORS}. A kit part adds its own; anchor names more (an elbow, a hinge edge; write it before the part that uses it); detach lets a part go. A group has only its origin and the points you name with anchor: attach to a shape inside it, or name the point first. Any 3D shape can be a parent and any with a place of its own can be attached (not a tube, line, arrow or connector, whose points are written where they go).`, + '- Machines move on parts already added, by id: spin, crank, cam and flash add nothing, and only the piston, rod and valve move with a crank or cam, never the cylinder block or a group. Any shape moves as a simple machine: a joint, driven by spin or loop (slide, swing, pulse) or coupled to another joint (gear, belt, lever, screw, pulley). A part inside a spinning part (a wheel parented to its cog) already turns with it: spin only the holder, never both. A muscle turns the hinge or pivot of the part it pulls (give that joint min and max wide enough for the way the muscle pulls it, like -120 to 120), so an arm bends by its muscle, not beside it. A bend or swing that is to show from the front turns about z; about x or y it swings toward the viewer and shows little. Motion carries on from step to step: set it up once, then narrate over it.', + '- Flows, forces and change, illustrated rather than simulated. Reach for the ready-made motion: a heart or bellows is a pump: draw all its chambers (a heart is four blobs), give pump to the chamber that squeezes (a ventricle) with a flap for its inlet and one for its outlet, and make its blood a stream with surge and beat so it runs in pulses; a vessel that squeezes along its length is a wave; swallowing and peristalsis are a wave on an open tube with a one-marker stream of the same period riding its crest (the mouthful). Diffusion, a gas, dye in water: add with shape particles, grown from 0 to 1 by reveal. Gravity: drop (falls and bounces), pendulum (draw its string as a connector), oscillate (a weight on a spring or elastic), float (a boat or buoy; put it at the water line first); damp on any loop makes it settle. A force is add with shape force (never op force): an arrow strength units long pointing the way dir does in the scene ([0,-1,0] is down) whatever its part does; add with shape field draws field lines (dipole a magnet, radial a charge or a mass, uniform between plates); name either with a pin. The last simple machines: incline, wedge, screw. A load that would rise or travel without end (a well, a screw\'s nut) gets max (and min) so it stops. A change of colour, size or state over time is style or scale with dur (or highlight, or loop pulse): nothing more is needed.', + '- 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.`, diff --git a/src/scene/spec.ts b/src/scene/spec.ts index 0cb9e2a..988fad0 100644 --- a/src/scene/spec.ts +++ b/src/scene/spec.ts @@ -287,7 +287,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addShell', op: 'add', shapes: ['shell'], creates: 'solid', - doc: 'A closed hollow ellipsoid section: domes, bowls, curved enclosures and opened layers. size is the full outer ellipsoid diameters [x,y,z], not the cropped bounds. inner (default .85) scales its concentric cavity, not a uniform wall thickness. latitude [south,north] degrees -90..90 (default [-90,90], span at least 1); sweep 1..360 (default 360) runs from +x toward +z around y. Radial rims close the material volume. Rotate to aim the opening. Invalid or unsafe geometry rejects.', + doc: 'A closed hollow ellipsoid section: domes, bowls, curved enclosures, opened layers. size is the full outer diameters [x,y,z]; inner (default .85) scales the cavity concentrically, so the wall is not a constant thickness; latitude [south,north] degrees -90..90 (default [-90,90], span at least 1) cuts a dome or bowl; sweep 1..360 (default 360) runs from +x toward +z around y and leaves an angular opening: rot aims it. Radial rims close the volume; unsafe geometry rejects.', fields: { shape: { k: 'enum', values: ['shell'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, size: { k: 'vec3', min: 0.01, max: 100 }, inner: { k: 'num', min: 0.01, max: 0.99, opt: true }, @@ -297,7 +297,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addExtrude', op: 'add', shapes: ['extrude'], creates: 'solid', - doc: 'A flat outline [[x,y],...] in the x,y plane, pushed out depth along z and centred on it: wings, fins, plates, brackets. Ordinary extrusions support disjoint through-hole rings strictly inside the outline, with flat edges only. Optional taper or shift makes a sharp closed transition: the negative-z end is the outline, the positive-z end is outline*taper+shift, scaling about the local origin. Defaults in this mode: taper 1, shift [0,0]. taper 0.05..20; both end coordinates -100..100; depth 0.01..100. Requires a simple polygon, 3..40 points, either winding. Invalid or Float32-unsafe geometry rejects, not repairs. Bevel must be omitted/null/0; through-holes are not supported in this mode.', + doc: 'A flat outline [[x,y],...] in the x,y plane, pushed out depth (0.01..100) along z and centred on it: wings, fins, plates, brackets. A simple polygon of 3..40 points, either winding. holes: up to 8 separate rings of 3 to 24 points, strictly inside the outline and clear of each other (no touching, crossing or nesting), 128 points in all with the outline, flat edges only (bevel 0). taper or shift makes a sharp closed transition: the negative-z end is the outline, the positive-z end is outline*taper+shift about the local origin (taper 0.05..20, defaults 1 and [0,0], ends within -100..100); it takes no bevel or holes. Unsafe geometry rejects, not repairs.', fields: { shape: { k: 'enum', values: ['extrude'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, outline: { k: 'pts2', min: 3, max: LIMITS.maxOutline, lo: WORLD.min, hi: WORLD.max }, @@ -317,7 +317,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addLathe', op: 'add', shapes: ['lathe'], creates: 'solid', - doc: 'A profile [[radius,y],...] spun round the y axis: bodies, nozzles, rings, bottles. sides makes it faceted (default quality tiers: 20/36/64). Optional sweep 1..359 degrees makes a closed sector from +z towards +x about +y; rotate to choose its start. Sector profile: simple closed polygon, 3..40 points (one repeated closing point allowed), radius 0..100, y -100..100. Invalid, touching, intersecting or Float32-unsafe profiles and invalid sweeps are rejected, not repaired. Either winding; exact redundant collinear boundary points are removed. sides is segments per full revolution (sector segments scale proportionally, at most 90 degrees each).', + doc: 'A profile [[radius,y],...] spun round the y axis: bodies, nozzles, rings, bottles. sides is the segments per full revolution (default by quality: 20/36/64). sweep 1..359 degrees makes a cutaway: a closed sector from +z towards +x about +y (rot chooses where it starts); the profile is then a simple closed polygon of 3..40 points, radius 0..100, y -100..100, not touching or crossing itself, either winding. Omit sweep for the full lathe. Bad profiles reject, not repair.', fields: { shape: { k: 'enum', values: ['lathe'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, profile: { k: 'pts2', min: 2, max: LIMITS.maxOutline, lo: WORLD.min, hi: WORLD.max }, @@ -327,7 +327,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addPatch', op: 'add', shapes: ['patch'], creates: 'solid', - doc: 'An open bicubic Bézier sheet: exactly 16 controls [x,y,z], four rows of four in row-major order. Each row runs across u; rows advance v. Corners lie on the sheet; other controls pull its curvature, not interpolation points. Curved panels, canopies, membranes. Two-sided, no thickness or solid cut cap. Use a regular net without folds or collapsed rows.', + doc: 'An open bicubic Bézier sheet: exactly 16 controls [x,y,z], four rows of four in row-major order (rows run across u and advance v). Corners lie on the sheet; the other controls pull its curve, they are not points to interpolate, so use a regular net without folds or collapsed rows. Two-sided, no thickness: curved panels, canopies, membranes.', fields: { shape: { k: 'enum', values: ['patch'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, pts: { k: 'pts', min: 16, max: 16, lo: WORLD.min, hi: WORLD.max, doc: 'exactly 16 finite controls in -100..100; never trimmed or clamped; numerically unsafe sampled nets are rejected' }, @@ -336,7 +336,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addSweep', op: 'add', shapes: ['sweep'], creates: 'solid', - doc: 'A closed polygon outline carried along a smooth open 3D path: curved rails, shaped cables and solid bands. Outline x,y are local section offsets; up sets initial +y, projected perpendicular to the path (default +y, or +x for a vertical start). The section follows with minimum rotation. Flat caps and sharp section corners by default; smooth:true blends shallow wall joins without changing geometry. No bevel or holes. Keep the profile narrow relative to bends; folded or collapsed sampled meshes are rejected.', + doc: 'A closed polygon outline carried along a smooth open 3D path pts: curved rails, shaped cables, solid bands. Outline x,y are section offsets; up sets the initial +y (default +y, or +x for a vertical start). The section follows with minimum rotation, so keep it narrow relative to bends. Flat caps and sharp corners; smooth:true blends shallow wall joins without changing geometry. No bevel, holes, stream or reveal.', fields: { shape: { k: 'enum', values: ['sweep'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, outline: { k: 'pts2', min: 3, max: 24, lo: WORLD.min, hi: WORLD.max }, @@ -348,7 +348,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addLoft', op: 'add', shapes: ['loft'], creates: 'solid', - doc: 'A closed solid joining independently shaped convex end outlines by matching point indices, at z=-depth/2 and +depth/2. Both rings need 3–24 corners, equal counts and the same winding; every interpolated section must stay strictly convex. No closing duplicate, collinear corners, holes or bevel. Use for asymmetric shape-changing transitions; no automatic recentering or point rematching. Optional smooth:true blends shallow wall joins while retaining flat caps and sharp corners.', + doc: 'A closed solid joining two convex end outlines by matching point indices: outline at z=-depth/2, endOutline at +depth/2. Both rings need 3-24 corners, equal counts and the same winding, and every section between must stay strictly convex (no closing repeat, collinear corners, holes or bevel). For solid asymmetric transitions, not hollow ducts; smooth:true blends shallow wall joins and keeps flat caps and sharp corners.', fields: { shape: { k: 'enum', values: ['loft'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, outline: { k: 'pts2', min: 3, max: 24, lo: WORLD.min, hi: WORLD.max }, @@ -359,7 +359,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addBlob', op: 'add', shapes: ['blob'], creates: 'solid', - doc: 'A soft organic form blended from up to 12 ellipsoid lumps, each at a point of pts with its own box size [x,y,z] in sizes (the same count, or the last is repeated): a heart or other organ, a fruit, an animal body or head, a leaf. Lumps that overlap melt into one skin with smooth necks; soft (0.05 to 1, default 0.5) is how far they blend. Build one form per blob and join forms with tube.', + doc: 'A soft organic form blended from up to 12 ellipsoid lumps, each at a point of pts with its own box size [x,y,z] in sizes (the same count, or the last is repeated). Overlapping lumps melt into one skin with smooth necks; soft (0.05 to 1, default 0.5) is how far they blend. One form per blob; join forms with tube.', fields: { shape: { k: 'enum', values: ['blob'] }, id: { k: 'newId' }, parent: PARENT, parentAnchor: PARENT_ANCHOR, selfAnchor: SELF_ANCHOR, explode: EXPLODE, pos: POS, rot: ROT, pts: { k: 'pts', min: 1, max: LIMITS.maxLumps, lo: WORLD.min, hi: WORLD.max }, @@ -369,7 +369,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addTube', op: 'add', shapes: ['tube'], creates: 'path', - doc: 'A smooth tube through the points: cables, pipes, vessels, stems, limbs. closed true joins it into a continuous loop (three distinct points minimum, no caps or endpoint attachment). flat (0.05 to 1) squashes it to a ribbon; draw below 1 starts it partly drawn. swell [[along 0 to 1, radius factor],...] (2 to 8 points) makes the radius change along it: a vessel that tapers, a stem that thickens, a tail.', + doc: 'A smooth tube through the points: cables, pipes, vessels, stems, limbs. closed true joins it into a continuous loop (three distinct points minimum, no caps or endpoint attachment, no wave). flat (0.05 to 1) squashes it to a ribbon; draw below 1 starts it partly drawn. swell [[along 0 to 1, radius factor],...] (2 to 8 points) makes the radius change along it: a vessel that tapers, a stem that thickens, a tail. An end that lies on a part is joined to it and goes with it: keep a part that travels along the tube (along, a mouthful) off the ends, or the tube is pulled into a stub.', fields: { shape: { k: 'enum', values: ['tube'] }, id: { k: 'newId' }, parent: PARENT, explode: EXPLODE, pts: { k: 'pts', min: 2, max: LIMITS.maxPts, lo: WORLD.min, hi: WORLD.max }, @@ -389,7 +389,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'addConnector', op: 'add', shapes: ['connector'], creates: 'path', - doc: 'A physical rope, belt, wire, chain or pipe between two parts of one 3D model, its ends on them, following them as they move (it never links panels, cards or marks: flat diagram arrows are edge). kind straight (default) is taut and shortens as a weight rises; slack hangs in a sag; wrapped is a flat belt round two wheels. fromSide and toSide say where an end meets its object, as seen from the front (left, right, top, bottom, front, back; the rim of a wheel), else its middle; fromAnchor and toAnchor name a point of a ready-made part.', + doc: 'A physical rope, belt, wire, chain or pipe between two parts of one 3D model, its ends on them, following them as they move (never panels, cards or marks: flat diagram arrows are edge). kind straight (default) is taut and shortens as a weight rises; slack hangs in a sag; wrapped is a flat belt round two wheels. fromSide and toSide say where an end meets its object, as seen from the front (left, right, top, bottom, front, back; the rim of a wheel), else its middle; fromAnchor and toAnchor name a point of a ready-made part; fromPoint and toPoint are points in each part\'s own space. swell and restLength make a muscle or soft cord bulge as its ends approach.', fields: { shape: { k: 'enum', values: ['connector'] }, id: { k: 'newId' }, parent: PARENT, from: { k: 'ref', of: 'object3d', doc: 'the object one end is on' }, to: { k: 'ref', of: 'object3d', doc: 'the object the other end is on' }, @@ -413,11 +413,43 @@ export const VARIANTS: readonly Variant[] = [ size: { k: 'num', min: 0.01, max: 5, opt: true }, color: COLOR_OPT, toColor: COLOR_OPT, shiftAt: { k: 'num', min: 0, max: 1, opt: true }, period: { k: 'num', min: -120, max: 120, opt: true }, by: { k: 'ref', of: 'object3d', opt: true, doc: 'a spinning part to run in step with' }, ratio: { k: 'num', min: -100, max: 100, opt: true }, opacity: OPACITY, at: AT, + surge: { k: 'num', min: 0.05, max: 0.95, opt: true, doc: 'flow in beats: the markers speed up and slow down once a beat by this fraction of their speed (0.8 is strong surges, as blood in a pulse); not with by' }, + beat: { k: 'num', min: 0.2, max: 10, opt: true, doc: 'seconds a beat takes (default 1)' }, + }, + }, + { + name: 'addParticles', op: 'add', shapes: ['particles'], creates: 'solid', + doc: 'A cloud of count small particles (default 30) that spread out: they begin in a box of size from at pos and, as reveal takes the cloud from 0 to 1 (it begins at 0, so they start crowded), drift apart to fill a box of size to, centred shift further on, jostling all the while. Diffusion, a gas filling a room, dye in water; a membrane is a plane or box between.', + fields: { + shape: { k: 'enum', values: ['particles'] }, id: { k: 'newId' }, parent: PARENT, pos: POS, + count: { k: 'num', min: 4, max: 80, int: true, opt: true }, from: { k: 'vec3', min: 0.05, max: 100 }, to: { k: 'vec3', min: 0.05, max: 100 }, + shift: { ...POS, doc: 'where the middle of the box they fill is, from the middle of the box they start in' }, + size: { k: 'num', min: 0.01, max: 2, opt: true }, jitter: { k: 'num', min: 0, max: 2, opt: true, doc: 'how far each jostles (default 0.12)' }, period: { k: 'num', min: 0.2, max: 20, opt: true, doc: 'seconds a jostle takes (default 1.5)' }, + color: COLOR_OPT, draw: { ...DRAW, doc: 'how spread out they are at first, 0 crowded in the start box to 1 filling the other (default 0); grow it with reveal' }, opacity: OPACITY, at: AT, + }, + }, + { + name: 'addForce', op: 'add', shapes: ['force'], creates: 'solid', attach: 'on', + doc: 'An arrow for a force on a part: from a point of it (point, default center) the way dir points in the scene (not the part: gravity stays down as the part turns), strength units long and thicker the stronger, following the part wherever it goes. Colour it and name it with a pin; scale it to change its strength, loop pulse it to make it come and go.', + fields: { + shape: { k: 'enum', values: ['force'] }, id: { k: 'newId' }, on: { k: 'ref', of: 'object3d', doc: 'the part the force acts on' }, + point: { k: 'str', min: 1, max: 24, opt: true }, dir: { k: 'vec3', min: -100, max: 100, doc: 'the direction it points, [x,y,z] in the scene: [0,-1,0] is down' }, + strength: { k: 'num', min: 0.05, max: 30 }, color: COLOR_OPT, opacity: OPACITY, at: AT, + }, + }, + { + name: 'addField', op: 'add', shapes: ['field'], creates: 'group', + doc: 'Field lines as arrows in the front plane round pos: dipole (a bar magnet or pair of charges: lines leave the end on the positive axis side and curve round to the other), radial (spokes out from a point charge, in to a mass: flip reverses them), uniform (parallel lines along axis, between plates or near the ground). size is how far they reach (default 5), count how many (default 8), gap the room between poles or plates. One group: clear its id to take them all away.', + fields: { + shape: { k: 'enum', values: ['field'] }, id: { k: 'newId' }, parent: PARENT, pos: POS, + kind: { k: 'enum', values: ['dipole', 'radial', 'uniform'] }, axis: { k: 'enum', values: ['x', 'y'], opt: true }, + size: { k: 'num', min: 0.5, max: 40, opt: true }, count: { k: 'num', min: 2, max: 16, int: true, opt: true }, gap: { k: 'num', min: 0, max: 40, opt: true }, + flip: { k: 'bool', opt: true, doc: 'reverse the way the lines point' }, color: COLOR_OPT, opacity: OPACITY, at: AT, }, }, { 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). Each has good proportions; mechanism anchors and the origin of every part can be used by pins, connectors and parentAnchor/selfAnchor placement.', + 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.', 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 }, @@ -515,7 +547,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'crank', op: 'crank', - doc: 'Tie a piston to a spinning crankshaft through a connecting rod: the piston slides up and down its cylinder (along y, in the x,y plane) as the crank pin goes round, and the rod swings to join them. piston, shaft and rod are the ids of the piston (never the cylinder block), the crankshaft and the connecting rod. Put the three in one group, the crankshaft turning with spin. On a plain cylinder laid on its side as the crankshaft, the crank draws the pin and runs the rod on it in front of the disc: add no pin of your own. pin is which throw (1 is the first).', + doc: 'Tie a piston to a spinning crankshaft through a connecting rod: the piston slides up and down its cylinder (along y, in the x,y plane) as the crank pin goes round, and the rod swings to join them. piston, shaft and rod are the ids of the piston (never the cylinder block), the crankshaft and the connecting rod, in one group, the crankshaft turning with spin. On a plain cylinder laid on its side as the crankshaft, the crank draws the pin and runs the rod on it in front of the disc: add no pin of your own. pin is which throw (1 is the first).', fields: { piston: { k: 'ref', of: 'object3d', opt: true }, id: { k: 'ref', of: 'object3d', opt: true, doc: 'the same as piston' }, shaft: { k: 'ref', of: 'object3d' }, rod: { k: 'ref', of: 'object3d', opt: true }, @@ -533,7 +565,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'flash', op: 'flash', - doc: 'A glow that comes on at one point of the cycle of a turning part: the object (a small sphere for a spark, a larger one for the burn) is invisible, flares to its opacity at the crank angle given and dies away over span degrees. by is the crankshaft; angle is degrees into a cycle of cycle degrees (default 720, a four-stroke engine: 0 is the piston at the top starting the intake, 360 the top of the compression).', + doc: 'A glow at one point of the cycle of a turning part: the object (a small sphere for a spark, a larger one for the burn) is invisible, flares to its opacity at the given angle and dies away over span degrees. by is the crankshaft; angle is degrees into a cycle of cycle degrees (default 720, a four-stroke engine: 0 is the piston at the top starting the intake, 360 the top of the compression).', fields: { id: { k: 'ref', of: 'object3d' }, by: { k: 'ref', of: 'object3d', doc: 'the part whose turning times it' }, angle: { k: 'num', min: 0, max: 3600 }, span: { k: 'num', min: 1, max: 720 }, @@ -544,8 +576,10 @@ export const VARIANTS: readonly Variant[] = [ name: 'loop', op: 'loop', doc: 'Repeat a motion on any object: slide (back and forth along axis, positive amount units in all), swing (rock about axis by signed amount degrees each side, -180 to 180, about the hinge pivot; negative reverses it, zero holds still) or pulse (swell to positive amount times its size), every period seconds (default 2) or by a spinning part. Left out, kind is the joint\'s. Another loop replaces it; stop ends it. id is an object already in the scene, never a name for the loop.', fields: { - id: { k: 'ref', of: 'object3d' }, kind: { k: 'enum', values: ['slide', 'swing', 'pulse', 'stop'], opt: true }, - amount: { k: 'num', min: -360, max: 360, opt: true, doc: 'slide: positive total travel in units; swing: signed degrees each side (negative reverses the swing, zero holds still); pulse: positive size factor (1.3 is 30% bigger, 0.8 smaller)' }, + id: { k: 'ref', of: 'object3d' }, kind: { k: 'enum', values: ['slide', 'swing', 'pulse', 'gate', 'float', 'stop'], opt: true }, + amount: { k: 'num', min: -360, max: 360, opt: true, doc: 'slide: positive total travel in units; swing: signed degrees each side (negative reverses the swing, zero holds still); pulse: positive size factor (1.3 is 30% bigger, 0.8 smaller); gate: degrees the hinge opens on half of each cycle; float: units it bobs up and down' }, + damp: { k: 'num', min: 0.2, max: 50, opt: true, doc: 'cycles for the motion to fall to a third of its size, so it settles (a pendulum running down); left out, it never settles' }, + tilt: { k: 'num', min: 0, max: 30, opt: true, doc: 'float: degrees it rocks from side to side about z (default 4)' }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, by: { k: 'ref', of: 'object3d', opt: true }, ratio: { k: 'num', min: -20, max: 20, opt: true, doc: 'with by: cycles per turn (default 1)' }, phase: { k: 'num', min: -3600, max: 3600, opt: true, doc: 'degrees ahead (180 is half a cycle behind another loop at 0)' }, @@ -574,7 +608,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'lever', op: 'lever', - doc: 'A beam that rocks about a fulcrum: a hinge at fulcrum, a point of the beam (center, the default, is a seesaw and the first class; left or right, an end, with the load or the effort between it and the other end, is the second and third class; or a point named with anchor), swinging swing degrees each side every period seconds. Attach the load and the effort at points of the beam (parentAnchor) and they rise and fall with it.', + doc: 'A beam that rocks about a fulcrum: a hinge at fulcrum, a point of the beam (center, the default, is a seesaw, the first class; left or right, an end, with the load or the effort between it and the other end, the second and third class; or a point named with anchor), swinging swing degrees each side every period seconds. Attach the load and the effort at points of the beam (parentAnchor) and they rise and fall with it.', fields: { id: { k: 'ref', of: 'object3d' }, fulcrum: { k: 'str', min: 1, max: 24, opt: true }, swing: { k: 'num', min: 1, max: 90, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, @@ -583,7 +617,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'muscle', op: 'muscle', - doc: 'A connector that is a muscle: it shortens by contract (a fraction of its relaxed length, 0.02 to 0.9, default 0.2) and lengthens again every period seconds (default 2), and the part it pulls (pulls, the id of one of its two ends, or from or to, with a hinge or pivot joint with min and max to hold it) is turned by it, not beside it. Join the ends with fromPoint and toPoint or fromAnchor and toAnchor; its belly swells as it shortens (swell). id is the connector.', + doc: 'A connector that is a muscle: it shortens by contract (a fraction of its relaxed length, 0.02 to 0.9; 0.1 to 0.25 for a limb) and lengthens again every period seconds, turning the part it pulls (pulls, the id of one of its two ends, or from or to; that part needs a hinge or pivot joint with min and max). Join the ends with fromPoint and toPoint or fromAnchor and toAnchor; its belly swells as it shortens (swell). id is the connector.', fields: { id: { k: 'ref', of: 'object3d' }, pulls: { k: 'str', min: 1, max: 40, doc: 'the id of the part it pulls (an end of the connector), or from or to for that end' }, contract: { k: 'num', min: 0.02, max: 0.9, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, @@ -592,16 +626,69 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'pulley', op: 'pulley', - doc: 'A rope over a wheel: the wheel (wheel) turns rpm turns a minute (default 20, negative the other way) and the load (id) rises by the rope laid on it, 2 x pi x radius for each turn. radius is the rope\'s radius on the wheel, read from the wheel\'s size when left out. A winch, a crane drum and a wheel and axle (give the axle\'s radius) are the same.', + doc: 'A rope over a wheel: the wheel (wheel) turns rpm turns a minute (negative the other way) and the load (id) rises by the rope laid on it, 2 x pi x radius for each turn, without end unless max stops it (the most it may rise, in units; min the least). radius is the rope\'s radius on the wheel, read from the wheel\'s size when left out. A winch, a crane drum and a wheel and axle (give the axle\'s radius) are the same.', fields: { id: { k: 'ref', of: 'object3d' }, wheel: { k: 'ref', of: 'object3d' }, radius: { k: 'num', min: 0.01, max: 100, opt: true }, rpm: { k: 'num', min: -600, max: 600, opt: true }, - axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true, doc: 'the axis the wheel turns about: left out, a cylinder turns about its own long axis as it lies and anything else about z' }, at: AT, + axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true, doc: 'the axis the wheel turns about: left out, a cylinder turns about its own long axis as it lies and anything else about z' }, + min: { k: 'num', min: -3600, max: 3600, opt: true }, max: { k: 'num', min: -3600, max: 3600, opt: true }, at: AT, + }, + }, + { + name: 'wave', op: 'wave', + doc: 'A wave running along an open tube: peristalsis, a pulse down a vessel. amount is the radius at its crest as a factor (above 1 a swell, below 1 a squeeze), width the fraction of the tube it spans, count how many run at once, period the seconds a crest takes for the whole tube (negative runs backwards). A one-marker stream along the same tube with the same period rides the crest (a mouthful going down). stop true ends it.', + fields: { id: { k: 'ref', of: 'object3d' }, amount: { k: 'num', min: 0.2, max: 4, opt: true }, width: { k: 'num', min: 0.03, max: 0.6, opt: true }, count: { k: 'num', min: 1, max: 6, int: true, opt: true }, period: { k: 'num', min: -60, max: 60, opt: true }, stop: { k: 'bool', opt: true }, at: AT }, + }, + { + name: 'pendulum', op: 'pendulum', + doc: 'A weight hanging from a point and swinging: id is the weight, from the part it hangs from (the swing is about its middle) or pivot, the point from the weight to the hang point. swing is degrees each side, period seconds (left out, longer for a longer string), damp cycles for it to settle. It starts let go at the far end. Draw the string as a connector between the two; hang it from a part that does not slide, and write the pendulum after any loop on its parts.', + fields: { + id: { k: 'ref', of: 'object3d' }, from: { k: 'ref', of: 'object3d', opt: true }, pivot: { k: 'vec3', ...WORLD, opt: true }, + swing: { k: 'num', min: 1, max: 90, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, damp: { k: 'num', min: 0.2, max: 50, opt: true }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, at: AT, }, }, + { + name: 'oscillate', op: 'oscillate', + doc: 'A weight bobbing on a spring or elastic: it moves amount units each way along axis (default y) every period seconds, starting pulled to the low end and let go, and settles if damp (cycles to fall to a third) is given. Draw the spring or elastic as a connector from its fixed end to the weight.', + fields: { id: { k: 'ref', of: 'object3d' }, amount: { k: 'num', min: 0.01, max: 50, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, damp: { k: 'num', min: 0.2, max: 50, opt: true }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, at: AT }, + }, + { + name: 'float', op: 'float', + doc: 'Buoyancy, illustrated: the part rides on water, bobbing bob units and rocking tilt degrees every period seconds. Put it at the water line first (drop does that); damp settles it.', + fields: { id: { k: 'ref', of: 'object3d' }, bob: { k: 'num', min: 0.01, max: 20, opt: true }, tilt: { k: 'num', min: 0, max: 30, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, damp: { k: 'num', min: 0.2, max: 50, opt: true }, at: AT }, + }, + { + name: 'drop', op: 'drop', + doc: 'Gravity, illustrated: the part falls to height to (y, in the units of the group it is in) with an ever faster pull, and bounces bounce (0 lands dead, 0.8 very springy) times lower each time until it settles. dur left out, it takes as long as the fall.', + fields: { id: { k: 'ref', of: 'object3d' }, to: { k: 'num', min: -100, max: 100 }, bounce: { k: 'num', min: 0, max: 0.8, opt: true }, at: AT, dur: DUR }, + }, + { + name: 'pump', op: 'pump', + doc: 'A chamber that squeezes and refills behind one-way valves, for a heart or a bellows: id is the chamber (it shrinks to squeeze of its size, then refills, every period seconds), inlet the flap that opens while it refills and outlet the flap that opens while it squeezes. Each valve turns about its hinge point (a named point of the valve, default left) by open degrees (negative the other way).', + fields: { + id: { k: 'ref', of: 'object3d' }, inlet: { k: 'ref', of: 'object3d', opt: true }, outlet: { k: 'ref', of: 'object3d', opt: true }, + squeeze: { k: 'num', min: 0.3, max: 0.95, opt: true }, open: { k: 'num', min: -170, max: 170, opt: true }, period: { k: 'num', min: 0.2, max: 20, opt: true }, + hinge: { k: 'str', min: 1, max: 24, opt: true }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, at: AT, + }, + }, + { + name: 'incline', op: 'incline', + doc: 'An inclined plane: the load (id) slides up and down the slope, travel units in all, every period seconds. The slope is the turn of the ramp (a box turned about z; its length runs along x), or angle degrees.', + fields: { id: { k: 'ref', of: 'object3d' }, ramp: { k: 'ref', of: 'object3d', opt: true }, angle: { k: 'num', min: -80, max: 80, opt: true }, travel: { k: 'num', min: 0.1, max: 100, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, at: AT }, + }, + { + name: 'wedge', op: 'wedge', + doc: 'A wedge driven in along axis (default y), travel units in all every period seconds, pushing the part it drives (drives) aside across axis by tan(angle) of its own travel, angle being the wedge\'s half angle in degrees (default 20): an axe in a log, a door stop. Put the driven part on the side of the wedge it is to be pushed to; write it again for the other side.', + fields: { id: { k: 'ref', of: 'object3d' }, drives: { k: 'ref', of: 'object3d' }, angle: { k: 'num', min: 3, max: 70, opt: true }, travel: { k: 'num', min: 0.1, max: 100, opt: true }, period: { k: 'num', min: 0.1, max: 60, opt: true }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, at: AT }, + }, + { + name: 'screw', op: 'screw', + doc: 'A screw and its nut: the screw (screw) turns rpm turns a minute and the nut (id) travels along its length pitch units for each turn (negative the other way), without end unless max stops it (the most it may travel, in units; min the least). A cylinder turns about its own long axis as it lies; axis says otherwise.', + fields: { id: { k: 'ref', of: 'object3d' }, screw: { k: 'ref', of: 'object3d' }, pitch: { k: 'num', min: -20, max: 20, opt: true }, rpm: { k: 'num', min: -600, max: 600, opt: true }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, min: { k: 'num', min: -3600, max: 3600, opt: true }, max: { k: 'num', min: -3600, max: 3600, opt: true }, at: AT }, + }, { name: 'cut', op: 'cut', - doc: 'Cut a 3D object and its children open. Choose axis x/y/z or normal [x,y,z], never both. normal is a nonzero local direction with finite components from -100 to 100; magnitude is ignored. to is signed distance along that unit direction from the local origin (not necessarily the center of a hull point cloud); the positive side is removed. Omit direction to keep the active cut direction (initially +z). Direction changes at the action start; only to animates. Closed opaque pieces are capped; open surfaces are not. to 100 removes the cut.', + doc: 'Cut a 3D object and its children open. Choose axis x/y/z or normal [x,y,z] (a nonzero local direction, components -100 to 100, magnitude ignored), never both. to is the signed distance along that unit direction from the local origin (not necessarily the centre of a hull); the positive side is removed, and to 100 removes the cut. Omit the direction to keep the active one (initially +z); it changes at the action\'s start, only to animates. Closed opaque pieces are capped; open surfaces are not.', fields: { id: { k: 'ref', of: 'object3d' }, axis: { k: 'enum', values: ['x', 'y', 'z'], opt: true }, normal: { k: 'vec3', min: -100, max: 100, opt: true, doc: 'nonzero local cut direction; do not combine with axis' }, to: { k: 'num', min: -100, max: 100 }, at: AT, dur: DUR }, }, { @@ -630,7 +717,7 @@ export const VARIANTS: readonly Variant[] = [ }, { name: 'go', op: 'go', - doc: 'Guide mode, optional: let the app make one navigation move for the person, in a step that points at it (the wait stays: if the app does not do it, they click). kind is tab (a tab), open (a menu item that opens a submenu) or scroll (a window or area; dir down by default). x,y is the middle of that control on the screenshot (anywhere in the area for scroll). The app does it only in a native window, only if the person has allowed it, says so aloud first, and refuses everything that is not exactly this (a button, a link, a checkbox, a field, anything that saves, sends, deletes or buys). At most one a step.', + doc: 'Guide mode, optional: let the app make one navigation move for the person, in a step that points at it (the wait stays: if the app does not do it, they click). kind is tab, open (a menu item that opens a submenu) or scroll (dir down by default); x,y is the middle of that control on the screenshot (anywhere in the area for scroll). Only in a native window and only if the person has allowed it; the app says so aloud first and refuses anything else (a button, link, checkbox, field, anything that saves, sends, deletes or buys). At most one a step.', fields: { kind: { k: 'enum', values: ['tab', 'open', 'scroll'] }, x: { k: 'num', ...SCREEN }, y: { k: 'num', ...SCREEN }, diff --git a/src/scene/types.ts b/src/scene/types.ts index 2553228..97cb1d5 100644 --- a/src/scene/types.ts +++ b/src/scene/types.ts @@ -137,12 +137,18 @@ export type AddConnector = { export type StreamMark = 'dot' | 'dash' | 'arrow'; export type AddStream = { op: 'add'; shape: 'stream'; id: string; along: string; mark?: StreamMark; count?: number; size?: number; color?: Color; toColor?: Color; - shiftAt?: number; period?: number; by?: string; ratio?: number; opacity?: number; + shiftAt?: number; period?: number; by?: string; ratio?: number; opacity?: number; surge?: number; beat?: number; } & At; /** A stream on an edge of a flat diagram: what the timeline makes of an AddStream whose `along` is an edge. Never written by the model. */ export type StreamPiece = { op: 'stream'; id: string; along: string; mark?: StreamMark; count?: number; color?: Color; toColor?: Color; shiftAt?: number; period?: number; opacity?: number } & At; -export type AddAction = AddSolid | AddShell | AddExtrude | AddHull | AddLathe | AddLoft | AddSweep | AddPatch | AddBlob | AddTube | AddPath | AddConnector | AddStream | AddPart | AddArray | AddText | AddGroup; +/** A cloud of particles that spread from one box to a larger one (diffusion). The reveal op takes it from crowded (0) to spread (1). */ +export type AddParticles = { op: 'add'; shape: 'particles'; id: string; parent?: string; pos?: Vec3; count?: number; from: Vec3; to: Vec3; shift?: Vec3; size?: number; jitter?: number; period?: number; color?: Color; draw?: number; opacity?: number } & At; +/** An arrow for a force on a part: strength units long, pointing the way dir does in the scene, from a point of the part. */ +export type AddForce = { op: 'add'; shape: 'force'; id: string; parent?: string; on: string; point?: string; dir: Vec3; strength: number; color?: Color; opacity?: number } & At; +/** Field lines drawn as arrows round a point (a magnet, a charge, a mass, two plates); the timeline makes them. */ +export type AddField = { op: 'add'; shape: 'field'; id: string; parent?: string; pos?: Vec3; kind: 'dipole' | 'radial' | 'uniform'; axis?: 'x' | 'y'; size?: number; count?: number; gap?: number; flip?: boolean; color?: Color; opacity?: number } & At; +export type AddAction = AddSolid | AddShell | AddExtrude | AddHull | AddLathe | AddLoft | AddSweep | AddPatch | AddBlob | AddTube | AddPath | AddConnector | AddStream | AddParticles | AddForce | AddField | AddPart | AddArray | AddText | AddGroup; // Tweens and changes on existing ids. export type MoveAction = { op: 'move'; id: string; to: Vec3 } & Timing; @@ -164,7 +170,7 @@ export type CutAction = { op: 'cut'; id: string; axis?: 'x' | 'y' | 'z'; normal? export type CrankAction = { op: 'crank'; id: string; shaft: string; rod?: string; pin?: number } & At; export type CamAction = { op: 'cam'; id: string; by: string; lift?: number; open?: number; phase?: number } & At; /** A repeating motion that is not a full turn, for any object: slide along an axis, swing about a pivot, or pulse in size. Its own period, or locked to a spinning part with by. */ -export type LoopAction = { op: 'loop'; id: string; kind?: 'slide' | 'swing' | 'pulse' | 'stop'; axis?: 'x' | 'y' | 'z'; amount?: number; period?: number; by?: string; ratio?: number; phase?: number; pivot?: Vec3 } & At; +export type LoopAction = { op: 'loop'; id: string; kind?: 'slide' | 'swing' | 'pulse' | 'gate' | 'float' | 'stop'; axis?: 'x' | 'y' | 'z'; amount?: number; period?: number; by?: string; ratio?: number; phase?: number; pivot?: Vec3; damp?: number; tilt?: number; /** Never written by the model: the part a pendulum hangs from, which the pivot follows. */ pivotOn?: string } & At; /** A freedom of an object: a hinge about a pivot, a slide along an axis or a direction, or riding rigidly with another object. It moves nothing until a driver (spin, loop) or a coupling sets its value. */ export type JointAction = { op: 'joint'; id: string; kind: 'hinge' | 'slide' | 'fixed' | 'pivot' | 'ball'; axis?: 'x' | 'y' | 'z'; dir?: Vec3; pivot?: Vec3; about?: string; limit?: Vec3; min?: number; max?: number; to?: string } & At; /** One joint follows another's value: ratio between two of a kind (gear, belt, lever arm), or pitch between a hinge and a slide (units of travel for a turn: a screw, a rack, a rope on a wheel). stop ends it. */ @@ -174,7 +180,20 @@ export type LeverAction = { op: 'lever'; id: string; fulcrum?: string; swing?: n /** A connector that pulls the part it is on: it contracts between its two points and the part's hinge or pivot is turned to make it so. */ export type MuscleAction = { op: 'muscle'; id: string; pulls: string; contract?: number; period?: number; phase?: number } & At; /** A rope over a wheel in one op: the wheel turns and the load slides by the rope laid on it. */ -export type PulleyAction = { op: 'pulley'; id: string; wheel: string; radius?: number; rpm?: number; axis?: 'x' | 'y' | 'z' } & At; +export type PulleyAction = { op: 'pulley'; id: string; wheel: string; radius?: number; rpm?: number; axis?: 'x' | 'y' | 'z'; min?: number; max?: number } & At; +/** Gravity and its kin, illustrated, each in one op over the loops, joints and couplings: a weight hanging and swinging, bobbing on a spring, floating, falling and bouncing. */ +export type PendulumAction = { op: 'pendulum'; id: string; from?: string; pivot?: Vec3; swing?: number; period?: number; damp?: number; axis?: 'x' | 'y' | 'z' } & At; +export type OscillateAction = { op: 'oscillate'; id: string; amount?: number; period?: number; damp?: number; axis?: 'x' | 'y' | 'z' } & At; +export type FloatAction = { op: 'float'; id: string; bob?: number; tilt?: number; period?: number; damp?: number } & At; +export type DropAction = { op: 'drop'; id: string; to: number; bounce?: number } & Timing; +/** A chamber that squeezes and refills behind one-way valves. */ +export type PumpAction = { op: 'pump'; id: string; inlet?: string; outlet?: string; squeeze?: number; open?: number; period?: number; hinge?: string; axis?: 'x' | 'y' | 'z' } & At; +/** The last simple machines: a load on a slope, a wedge pushing a part aside, a screw and its nut. */ +export type InclineAction = { op: 'incline'; id: string; ramp?: string; angle?: number; travel?: number; period?: number } & At; +export type WedgeAction = { op: 'wedge'; id: string; drives: string; angle?: number; travel?: number; period?: number; axis?: 'x' | 'y' | 'z' } & At; +export type ScrewAction = { op: 'screw'; id: string; screw: string; pitch?: number; rpm?: number; axis?: 'x' | 'y' | 'z'; min?: number; max?: number } & At; +/** A wave running along a tube. */ +export type WaveAction = { op: 'wave'; id: string; amount?: number; width?: number; count?: number; period?: number; stop?: boolean } & At; export type FlashAction = { op: 'flash'; id: string; by: string; angle: number; span: number; cycle?: number } & At; // Camera, for the 3D panel. @@ -194,6 +213,7 @@ export type Action = | Mark | PanelAction | AddAction | DiagramThing | TickAction | MoveAction | AlongAction | TurnAction | ScaleAction | ExplodeAction | RevealAction | AnchorAction | DetachAction | StyleAction | HighlightAction | CutAction | SpinAction | CrankAction | CamAction | FlashAction | LoopAction | JointAction | CoupleAction | LeverAction | PulleyAction | MuscleAction + | WaveAction | PendulumAction | OscillateAction | FloatAction | DropAction | PumpAction | InclineAction | WedgeAction | ScrewAction | OrbitAction | ZoomAction | FocusAction | ClearAction | WaitAction | GoAction; export type Step = { say: string; actions: Action[] }; diff --git a/src/scene/validate.ts b/src/scene/validate.ts index 5869305..e1cfcf7 100644 --- a/src/scene/validate.ts +++ b/src/scene/validate.ts @@ -39,6 +39,8 @@ export type SceneState = { spins: Map; /** The two ends of each connector made so far: a muscle is one of them. */ connectors?: Map; + /** The tubes made so far, and whether each is a closed loop: a wave runs along an open tube. */ + tubes?: Map; /** The min and max each joint was given: a muscle on a joint with no room to turn cannot move it. */ jointRanges?: Map; /** The parts a muscle pulls: a loop or coupling written for one is dropped (the muscle drives it) until a loop stop frees it. */ @@ -86,7 +88,7 @@ export function createSceneState(): SceneState { export function createDetailState(onScreen: SceneState): SceneState { return { ids: new Map(onScreen.ids), parents: new Map(onScreen.parents), depth: new Map(onScreen.depth), diagramKinds: new Map(onScreen.diagramKinds), parts: new Map(onScreen.parts), joints: new Map(onScreen.joints), follows: new Map(onScreen.follows), rides: new Map(onScreen.rides), spins: new Map(onScreen.spins), - bodies: new Map(onScreen.bodies), loose: new Map(onScreen.loose), after: [], connectors: new Map(onScreen.connectors ?? []), muscled: new Set(onScreen.muscled ?? []), jointRanges: new Map(onScreen.jointRanges ?? []), + bodies: new Map(onScreen.bodies), loose: new Map(onScreen.loose), after: [], connectors: new Map(onScreen.connectors ?? []), tubes: new Map(onScreen.tubes ?? []), muscled: new Set(onScreen.muscled ?? []), jointRanges: new Map(onScreen.jointRanges ?? []), turnSteps: 0, turnActions: 0, copies: onScreen.copies, replaceable: new Set(onScreen.ids.keys()), ...(onScreen.stage ? { stage: { ...onScreen.stage } } : {}), }; @@ -497,11 +499,27 @@ function fitStage(raw: Record, state: SceneState, path: string, return next; } -function validateAction(raw: unknown, state: SceneState, path: string, notes: Notes, parentFirstAt: ReadonlyMap, mountedChildrenAt: ReadonlyMap, bodies: BodyVersions): Action | null { - if (!isObject(raw)) { +/** + * A shape written as the op (op "force" for add with shape force, as a model has done): read as the add it was meant to be, with a note. + * This is general: any shape name an `add` takes (sphere, tube, array, group, connector, ...) written as an op is rewritten the same way, + * each with its own note; a name that is no op and no shape stays dropped, and so does an op that also gives a different shape. + */ +function shapeAsOp(raw: object, path: string, notes: Notes): object { + const op = own(raw, 'op'); + if (typeof op !== 'string' || VARIANTS.some((v) => v.op === op)) return raw; + const shape = own(raw, 'shape'); + if (shape !== undefined && shape !== null) return raw; + if (!VARIANTS.some((v) => v.op === 'add' && (v.shapes as readonly string[] | undefined)?.includes(op))) return raw; + note(notes, 'trimmed', path, `repaired: op "${op}" read as add with shape ${op}`); + return { ...raw, op: 'add', shape: op }; +} + +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 variant = pickVariant(raw); if (typeof variant === 'string') { note(notes, 'dropped', path, variant); @@ -712,7 +730,7 @@ function validateAction(raw: unknown, state: SceneState, path: string, notes: No note(notes, 'dropped', path, 'loop needs an amount'); return null; } - const [low, high] = kind === 'slide' ? [0.01, 100] : kind === 'swing' ? [-180, 180] : [0.1, 5]; + const [low, high] = kind === 'slide' || kind === 'float' ? [0.01, 100] : kind === 'swing' ? [-180, 180] : kind === 'gate' ? [-170, 170] : [0.1, 5]; const held = Math.min(high, Math.max(low, amount)); if (held !== amount) { note(notes, 'clamped', `${path}.amount`, `${kind} amount ${amount} held to ${held}`); @@ -736,6 +754,20 @@ function validateAction(raw: unknown, state: SceneState, path: string, notes: No if (variant.name === 'lever' && !checkLever(out, state, path, notes)) return null; if (variant.name === 'pulley' && !checkPulley(out, state, path, notes)) return null; if (variant.name === 'muscle' && !checkMuscle(out, state, path, notes)) return null; + if (variant.name === 'pendulum' && out.from === undefined && out.pivot === undefined) { + note(notes, 'dropped', path, 'pendulum needs from (the part it hangs from) or pivot (the hang point, from the weight)'); + return null; + } + if (variant.name === 'pendulum' && out.from === out.id) { + note(notes, 'dropped', `${path}.from`, 'a pendulum hangs from a different part'); + return null; + } + if (variant.name === 'wave' && !checkWave(out, state, path, notes)) return null; + if (variant.name === 'addForce' && !checkForce(out, state, path, notes)) return null; + if (variant.name === 'pump' && !checkPump(out, state, path, notes)) return null; + if (variant.name === 'incline' && !checkIncline(out, state, path, notes)) return null; + if (variant.name === 'wedge' && !checkMachine(out, state, path, notes, 'drives', 'slide')) return null; + if (variant.name === 'screw' && !checkMachine(out, state, path, notes, 'screw', 'slide')) return null; if (variant.name === 'addTube' && out.closed === true && new Set((out.pts as Vec3[]).map((p) => p.join(','))).size < 3) { note(notes, 'dropped', `${path}.pts`, 'a closed tube needs at least three distinct points'); return null; @@ -791,6 +823,8 @@ function validateAction(raw: unknown, state: SceneState, path: string, notes: No else state.parts.delete(id); if (variant.name === 'addConnector') (state.connectors ??= new Map()).set(id, { from: out.from as string, to: out.to as string }); else state.connectors?.delete(id); + if (variant.name === 'addTube') (state.tubes ??= new Map()).set(id, { closed: out.closed === true }); + else state.tubes?.delete(id); state.parents.set(id, parent); state.depth.set(id, parent === undefined ? 1 : (state.depth.get(parent) ?? 0) + 1); holdBody(state, variant.name, out, path, notes, mountedPos); @@ -976,6 +1010,107 @@ function checkMuscle(out: Record, state: SceneState, path: stri return true; } +/** A wave runs along a tube that is open at its ends. */ +function checkWave(out: Record, state: SceneState, path: string, notes: Notes): boolean { + const id = out.id as string; + const tube = state.tubes?.get(id); + if (!tube) { + note(notes, 'dropped', path, `a wave runs along a tube: "${id}" is not one (add a tube first, or run a stream along a line)`); + return false; + } + if (tube.closed) { + note(notes, 'dropped', path, `"${id}" is a closed loop: a wave needs a tube open at both ends (a stream can run round a loop)`); + return false; + } + if (out.period === 0) { + delete out.period; + note(notes, 'trimmed', `${path}.period`, 'period 0 would not move; the default is used'); + } + return true; +} + +/** A force arrow starts at a point of the part it acts on and points somewhere. */ +function checkForce(out: Record, state: SceneState, path: string, notes: Notes): boolean { + const dir = out.dir as Vec3; + if (Math.hypot(dir[0], dir[1], dir[2]) < 1e-6) { + note(notes, 'dropped', `${path}.dir`, 'a force needs a direction: [0,-1,0] is down'); + return false; + } + const on = out.on as string; + const point = out.point as string | undefined; + const points = state.bodies.get(on)?.anchors; + if (point !== undefined && points && !Object.hasOwn(points, point)) { + note(notes, 'dropped', `${path}.point`, `unknown point "${point}" on "${on}"; available: ${Object.keys(points).join(', ')}`); + return false; + } + return true; +} + +/** A pump has a chamber and at least one valve, all different parts; each valve is a hinge. */ +function checkPump(out: Record, state: SceneState, path: string, notes: Notes): boolean { + const id = out.id as string; + const valves = ['inlet', 'outlet'].filter((k) => out[k] !== undefined); + if (valves.length === 0) { + note(notes, 'dropped', path, 'pump needs an inlet or an outlet valve (the parts that open and shut)'); + return false; + } + if (out.inlet !== undefined && out.inlet === out.outlet) { + note(notes, 'dropped', path, 'the inlet and the outlet of a pump are different parts'); + return false; + } + for (const k of valves) { + if (out[k] === id) { + note(notes, 'dropped', `${path}.${k}`, 'a valve is a different part from the chamber'); + return false; + } + } + const points = (key: string): Record | undefined => state.bodies.get(out[key] as string)?.anchors; + const hinge = (out.hinge as string | undefined) ?? 'left'; + for (const k of valves) { + const known = points(k); + if (known && !Object.hasOwn(known, hinge)) { + note(notes, 'dropped', `${path}.hinge`, `unknown point "${hinge}" on "${out[k] as string}"; available: ${Object.keys(known).join(', ')}`); + return false; + } + } + for (const k of valves) state.joints.set(out[k] as string, 'hinge'); + return true; +} + +/** An inclined plane needs its slope: the ramp it lies on, or an angle. */ +function checkIncline(out: Record, state: SceneState, path: string, notes: Notes): boolean { + if (out.ramp === undefined && out.angle === undefined) { + note(notes, 'dropped', path, 'incline needs ramp (the sloping part) or angle (degrees of slope)'); + return false; + } + if (out.ramp === out.id) { + note(notes, 'dropped', `${path}.ramp`, 'the load and the ramp are different parts'); + return false; + } + state.joints.set(out.id as string, 'slide'); + return true; +} + +/** A wedge and the part it drives, or a screw and its nut: two different parts, the second following the first. */ +function checkMachine(out: Record, state: SceneState, path: string, notes: Notes, other: string, kind: 'slide'): boolean { + const id = out.id as string; + const mate = out[other] as string; + if (mate === id) { + note(notes, 'dropped', path, `${id} and ${mate} are different parts`); + return false; + } + const follower = other === 'drives' ? mate : id; + const leader = other === 'drives' ? id : mate; + if (comesBack(state.follows, leader, follower)) { + note(notes, 'dropped', `${path}.${other}`, `${follower} cannot follow ${leader}: that follows ${follower} already (a coupling loop)`); + return false; + } + state.joints.set(follower, kind); + if (other === 'drives') state.joints.set(id, 'slide'); + state.follows.set(follower, leader); + return true; +} + /** A pulley's load slides and follows the wheel, which turns by its own spin: neither may be the other. */ function checkPulley(out: Record, state: SceneState, path: string, notes: Notes): boolean { const id = out.id as string; diff --git a/test/flows-fluids.test.ts b/test/flows-fluids.test.ts new file mode 100644 index 0000000..2dd40c0 --- /dev/null +++ b/test/flows-fluids.test.ts @@ -0,0 +1,220 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { Box3, Group, Mesh, MeshBasicMaterial, Vector3 } from 'three'; +import type { BufferGeometry } from 'three'; +import { createSceneState, validateStep } from '../src/scene/index.ts'; +import { emptyFrame, evaluate, planStep } from '../src/overlay/timeline.ts'; +import type { Frame } from '../src/overlay/timeline.ts'; +import { buildForce, buildParticles, updateForces, updateParticles, waveFactor } from '../src/overlay/scene3d-flow.ts'; +import type { FlowNode } from '../src/overlay/scene3d-flow.ts'; +import { fieldLines } from '../src/scene/field-lines.ts'; + +// Flows and forces: a wave along a tube, flow in beats, particles that spread, force arrows and field lines. + +const near = (a: number | undefined, b: number, eps = 1e-3) => assert.ok(a !== undefined && Math.abs(a - b) <= eps, `${a} vs ${b}`); +const run = (...actions: unknown[]) => { + const checked = validateStep({ say: 'x', actions }, createSceneState()); + assert.ok(checked.step, JSON.stringify(checked.issues)); + return { plan: planStep(emptyFrame(), checked.step), issues: checked.issues }; +}; +const obj = (f: Frame, id: string) => f.objects.find((o) => o.id === id)!; +const tube = { op: 'add', shape: 'tube', id: 'gut', pts: [[-4, 0, 0], [0, 1, 0], [4, 0, 0]], radius: 0.3 }; + +test('a wave crest is a swell where the laps put it, a squeeze below one, with count crests apart; it is one far from a crest', () => { + near(waveFactor(0.3, 0.3, 1, 0.2, 2), 2); + near(waveFactor(0.3 + 0.1, 0.3, 1, 0.2, 2), 1, 1e-9); + near(waveFactor(0.9, 0.3, 1, 0.2, 2), 1, 1e-9); + near(waveFactor(0.3, 0.3, 1, 0.2, 0.4), 0.4); + near(waveFactor(0.8, 0.3, 2, 0.2, 2), 2); + near(waveFactor(0.3, -0.7, 1, 0.2, 2), 2); + near(waveFactor(0.3, 1.3, 1, 0.2, 2), 2); +}); + +test('a wave on a tube is carried by the frame, its place a lap count a stream of the same period shares', () => { + const r = run(tube, { op: 'wave', id: 'gut', amount: 1.8, width: 0.25, period: 4 }, { op: 'add', shape: 'stream', id: 'bolus', along: 'gut', count: 1, period: 4 }); + assert.deepEqual(r.issues, []); + for (const t of [0.5, 1.7, 3]) { + const f = evaluate(r.plan, t); + const w = obj(f, 'gut').wave!; + assert.ok(w, 'the tube has a wave'); + near(w.phase, obj(f, 'bolus').phase!, 1e-9); + near(w.phase, t / 4, 1e-9); + assert.equal(w.amount, 1.8); + } + const back = run(tube, { op: 'wave', id: 'gut', period: -4 }); + near(obj(evaluate(back.plan, 2), 'gut').wave!.phase, -0.5, 1e-9); + // a wave written again replaces the one before (as a loop does), and stop leaves the tube still + const stopped = run(tube, { op: 'wave', id: 'gut' }, { op: 'wave', id: 'gut', stop: true }); + assert.equal(obj(evaluate(stopped.plan, 2), 'gut').wave, undefined); + const again = run(tube, { op: 'wave', id: 'gut', amount: 1.5 }, { op: 'wave', id: 'gut', amount: 0.5, count: 2 }); + assert.deepEqual([obj(evaluate(again.plan, 1), 'gut').wave!.amount, obj(evaluate(again.plan, 1), 'gut').wave!.count], [0.5, 2]); +}); + +test('a wave on something that is not an open tube is dropped with a note', () => { + const line = validateStep({ say: 'x', actions: [{ op: 'add', shape: 'line', id: 'l', pts: [[0, 0, 0], [3, 0, 0]] }, { op: 'wave', id: 'l' }] }, createSceneState()); + assert.ok(line.issues.some((i) => /not one|a tube/.test(i.message)), JSON.stringify(line.issues)); + const loop = validateStep({ say: 'x', actions: [{ ...tube, id: 'ring', closed: true, pts: [[0, 0, 0], [2, 0, 0], [1, 2, 0]] }, { op: 'wave', id: 'ring' }] }, createSceneState()); + assert.ok(loop.issues.some((i) => /closed loop/.test(i.message)), JSON.stringify(loop.issues)); +}); + +test('a stream with surge runs in beats: faster and slower within each, and exactly on time at the end of each beat', () => { + const r = run(tube, { op: 'add', shape: 'stream', id: 's', along: 'gut', period: 4, surge: 0.8, beat: 1 }); + const plain = run(tube, { op: 'add', shape: 'stream', id: 's', along: 'gut', period: 4 }); + const lap = (rr: typeof r, t: number) => obj(evaluate(rr.plan, t), 's').phase!; + for (const t of [1, 2, 3, 5]) near(lap(r, t), lap(plain, t), 1e-9); + assert.ok(Math.abs(lap(r, 0.25) - lap(plain, 0.25)) > 0.005, 'ahead within a beat'); + // never backwards, and the speed swings between 1 - surge and 1 + surge of the plain one + let slowest = Infinity, fastest = 0; + for (let t = 0.01; t < 4; t += 0.01) { + const v = (lap(r, t + 0.001) - lap(r, t)) / (lap(plain, t + 0.001) - lap(plain, t)); + slowest = Math.min(slowest, v); + fastest = Math.max(fastest, v); + } + assert.ok(slowest > 0.15 && slowest < 0.3, `slowest ${slowest}`); + assert.ok(fastest > 1.7 && fastest < 1.85, `fastest ${fastest}`); +}); + +// ---- the stage's side, with no WebGL: the meshes are made and placed, and read back ---- + +const meshOf = () => new Mesh(undefined, new MeshBasicMaterial()); +const blankNode = (): FlowNode => ({ obj: new Group(), pieces: [], geometries: [], alpha: 1 }); +const addMesh = (geo: BufferGeometry) => { + const m = meshOf(); + m.geometry = geo; + return m; +}; + +test('particles begin in the start box and spread to the end box as the object is revealed, jostling all the while', () => { + const r = run({ op: 'add', shape: 'particles', id: 'gas', count: 40, from: [1, 1, 1], to: [8, 4, 1], shift: [3, 0, 0], jitter: 0.1 }, { op: 'reveal', id: 'gas', to: 1, at: 1, dur: 4 }); + assert.deepEqual(r.issues, []); + const f0 = evaluate(r.plan, 0); + near(obj(f0, 'gas').draw, 0); + const node = blankNode(); + buildParticles(node, obj(f0, 'gas'), addMesh as never); + const spreadAt = (t: number) => { + const f = evaluate(r.plan, t); + updateParticles(new Map([[obj(f, 'gas').key, node]]), f); + const box = new Box3(); + for (const b of node.particles!.beads) box.expandByPoint(b.position); + return box; + }; + const start = spreadAt(0); + assert.ok(start.max.x - start.min.x <= 1 + 0.2 + 1e-9 && start.max.y - start.min.y <= 1.2 + 1e-9, 'crowded to begin with'); + const end = spreadAt(6); + assert.ok(end.max.x - end.min.x > 6 && end.max.y - end.min.y > 2.5, `spread out ${end.max.x - end.min.x}`); + assert.ok(end.min.x >= 3 - 4 - 0.2 - 1e-9 && end.max.x <= 3 + 4 + 0.2 + 1e-9, 'inside the box it fills'); + // the jostle: the same cloud at the same spread is not still from one moment to the next + const again = spreadAt(6.4); + const a = node.particles!.beads[0]!.position.clone(); + spreadAt(6); + assert.ok(a.distanceTo(node.particles!.beads[0]!.position) > 0.01, 'they jostle'); + void again; + // and the same time always gives the same places + const p1 = spreadAt(3.3).max.x, p2 = spreadAt(3.3).max.x; + near(p1, p2, 1e-12); +}); + +test('a force arrow starts on its part, points the way the scene says however the part turns, and is as long as its strength', () => { + const r = run({ op: 'add', shape: 'sphere', id: 'bob', size: [1, 1, 1], pos: [2, -1, 0] }, { op: 'add', shape: 'force', id: 'weight', on: 'bob', dir: [0, -2, 0], strength: 3 }); + assert.deepEqual(r.issues, []); + const f = evaluate(r.plan, 1); + const host = new FlowNode0(); + const arrowNode = blankNode(); + buildForce(arrowNode, obj(f, 'weight'), addMesh as never); + host.group.position.set(2, -1, 0); + host.group.rotation.set(0, 0, 0.9); // the part is turned: the arrow is not + host.group.updateMatrixWorld(true); + const nodes = new Map([[obj(f, 'bob').key, host.node], [obj(f, 'weight').key, arrowNode]]); + updateForces(nodes, f); + const arrow = arrowNode.force!; + const tail = new Vector3().copy(arrow.shaft.position).addScaledVector(new Vector3(0, 1, 0).applyQuaternion(arrow.shaft.quaternion), -arrow.shaft.scale.y / 2); + near(tail.x, 2, 1e-6); + near(tail.y, -1, 1e-6); + const tip = new Vector3().copy(arrow.head.position).addScaledVector(new Vector3(0, 1, 0).applyQuaternion(arrow.head.quaternion), arrow.head.scale.y / 2); + near(tip.x, 2, 1e-6); + near(tip.y, -1 - 3, 1e-6); + // a stronger force is thicker and longer + const strong = run({ op: 'add', shape: 'sphere', id: 'bob', size: [1, 1, 1], pos: [2, -1, 0] }, { op: 'add', shape: 'force', id: 'weight', on: 'bob', dir: [0, -1, 0], strength: 6 }); + const f2 = evaluate(strong.plan, 1); + const node2 = blankNode(); + buildForce(node2, obj(f2, 'weight'), addMesh as never); + updateForces(new Map([[obj(f2, 'bob').key, host.node], [obj(f2, 'weight').key, node2]]), f2); + assert.ok(node2.force!.shaft.scale.x > arrow.shaft.scale.x, 'thicker'); + near(node2.force!.shaft.scale.y + node2.force!.head.scale.y, 6, 1e-6); +}); + +class FlowNode0 { + group = new Group(); + node: FlowNode = { obj: this.group, pieces: [], geometries: [], alpha: 1 }; +} + +test('a force with no direction, or from a point the part does not have, is dropped with a note', () => { + const part = { op: 'add', shape: 'box', id: 'crate', size: [1, 1, 1] }; + const none = validateStep({ say: 'x', actions: [part, { op: 'add', shape: 'force', id: 'f', on: 'crate', dir: [0, 0, 0], strength: 2 }] }, createSceneState()); + assert.ok(none.issues.some((i) => /direction/.test(i.message)), JSON.stringify(none.issues)); + const bad = validateStep({ say: 'x', actions: [part, { op: 'add', shape: 'force', id: 'f', on: 'crate', point: 'handle', dir: [1, 0, 0], strength: 2 }] }, createSceneState()); + assert.ok(bad.issues.some((i) => /unknown point "handle"/.test(i.message)), JSON.stringify(bad.issues)); + const good = validateStep({ say: 'x', actions: [part, { op: 'add', shape: 'force', id: 'f', on: 'crate', point: 'right', dir: [1, 0, 0], strength: 2 }] }, createSceneState()); + assert.deepEqual(good.issues, [], JSON.stringify(good.issues)); +}); + +test('a dipole field leaves the positive end, loops round outside the magnet to the other, and mirrors above and below', () => { + const lines = fieldLines({ kind: 'dipole', size: 5, count: 8, gap: 2 }); + assert.equal(lines.length, 8); + for (const l of lines) { + assert.ok(l.length >= 2 && l.length <= 24); + assert.ok(l[0]![0] > 0.5 && l[l.length - 1]![0] < -0.5, 'from the right end to the left'); + for (const p of l) assert.ok(Math.hypot(p[0], p[1]) <= 5.2 && p[2] === 0); + // it starts on a ring round the positive pole (at 0.85 for a bar 2 long) and comes to the negative one + near(Math.hypot(l[0]![0] - 0.85, l[0]![1]), 0.85 * 0.3, 1e-9); + assert.ok(Math.hypot(l[l.length - 1]![0] + 0.85, l[l.length - 1]![1]) < 0.85 * 0.5, 'ends at the other pole'); + // and a line is a smooth curve: no step of it more than twice the average one + const steps = l.slice(1).map((p, i) => Math.hypot(p[0] - l[i]![0], p[1] - l[i]![1])); + assert.ok(Math.max(...steps) < 2 * (steps.reduce((a, b) => a + b, 0) / steps.length) + 1e-9); + } + const up = lines.filter((l) => l[Math.floor(l.length / 2)]![1] > 0); + const down = lines.filter((l) => l[Math.floor(l.length / 2)]![1] < 0); + assert.equal(up.length, 4); + assert.equal(down.length, 4); + near(up[1]![5]![0], down[1]![5]![0], 1e-9); + near(up[1]![5]![1], -down[1]![5]![1], 1e-9); + assert.ok(up[3]![7]![1] > up[0]![7]![1] + 0.5, 'the outer lines reach further'); + const widest = Math.max(...up[3]!.map((p) => p[1])); + assert.ok(widest > 3.5 && widest <= 5.2, `the widest loop reaches the size asked: ${widest}`); + const tall = fieldLines({ kind: 'dipole', axis: 'y', size: 5, count: 4, gap: 2 }); + assert.ok(tall[0]![0]![1] > 0.5 && tall[0]![tall[0]!.length - 1]![1] < -0.5, 'the same turned to lie along y'); + const flipped = fieldLines({ kind: 'dipole', size: 5, count: 8, gap: 2, flip: true }); + near(flipped[0]![0]![0], lines[0]![lines[0]!.length - 1]![0], 1e-9); +}); + +test('radial lines spoke out from a point and uniform ones run parallel across the gap', () => { + const spokes = fieldLines({ kind: 'radial', size: 4, count: 6, gap: 1 }); + assert.equal(spokes.length, 6); + for (const s of spokes) { + near(Math.hypot(s[0]![0], s[0]![1]), 0.5, 1e-9); + near(Math.hypot(s[1]![0], s[1]![1]), 4, 1e-9); + } + const inward = fieldLines({ kind: 'radial', size: 4, count: 6, gap: 1, flip: true }); + near(Math.hypot(inward[0]![0]![0], inward[0]![0]![1]), 4, 1e-9); + const plates = fieldLines({ kind: 'uniform', size: 6, count: 5, gap: 4 }); + assert.equal(plates.length, 5); + plates.forEach((l, i) => { + near(l[0]![0], -3, 1e-9); + near(l[1]![0], 3, 1e-9); + near(l[0]![1], -2 + i, 1e-9); + near(l[1]![1], l[0]![1], 1e-9); + }); +}); + +test('a field is one group of arrows that draw on together, and clearing its id takes them all', () => { + const r = run({ op: 'add', shape: 'field', id: 'mag', kind: 'dipole', pos: [1, 0, 0], size: 4, count: 6 }, { op: 'clear', target: 'mag', at: 3 }); + assert.deepEqual(r.issues, []); + const f = evaluate(r.plan, 2); + const lines = f.objects.filter((o) => o.id.startsWith('mag.')); + assert.equal(lines.length, 6); + assert.ok(lines.every((o) => o.shape === 'arrow' && o.parentKey === obj(f, 'mag').key)); + assert.ok(lines.every((o) => o.draw > 0.99), 'drawn on by two seconds'); + assert.ok(evaluate(r.plan, 0.2).objects.filter((o) => o.id.startsWith('mag.')).every((o) => o.draw < 0.9)); + const gone = evaluate(r.plan, 10); + assert.equal(gone.objects.filter((o) => o.id.startsWith('mag')).length, 0); +}); diff --git a/test/flows-gravity.test.ts b/test/flows-gravity.test.ts new file mode 100644 index 0000000..86add75 --- /dev/null +++ b/test/flows-gravity.test.ts @@ -0,0 +1,214 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createSceneState, validateStep } from '../src/scene/index.ts'; +import { emptyFrame, evaluate, planStep } from '../src/overlay/timeline.ts'; +import type { Frame } from '../src/overlay/timeline.ts'; +import { fallCurve, fallSeconds } from '../src/overlay/fall.ts'; + +// Gravity and its kin, illustrated: a pendulum, a weight on a spring, a boat on water, a drop with a bounce, a pump behind one-way valves, +// and the last simple machines (a load on a slope, a wedge, a screw). Each is a few existing movements written in one op. + +const near = (a: number | undefined, b: number, eps = 1e-3) => assert.ok(a !== undefined && Math.abs(a - b) <= eps, `${a} vs ${b}`); +const obj = (f: Frame, id: string) => f.objects.find((o) => o.id === id)!; +const posOf = (f: Frame, id: string) => (obj(f, id).pose?.pos ?? obj(f, id).pos) as [number, number, number]; +const rotOf = (f: Frame, id: string) => (obj(f, id).pose?.rot ?? obj(f, id).rot) as [number, number, number]; +const scaleOf = (f: Frame, id: string) => (obj(f, id).pose?.scale ?? [1, 1, 1]) as [number, number, number]; +const run = (...actions: unknown[]) => { + const checked = validateStep({ say: 'x', actions }, createSceneState()); + assert.ok(checked.step, JSON.stringify(checked.issues)); + return { plan: planStep(emptyFrame(), checked.step), issues: checked.issues, step: checked.step }; +}; +const at = (r: ReturnType, t: number) => evaluate(r.plan, t); + +const support = { op: 'add', shape: 'box', id: 'support', size: [4, 0.4, 1], pos: [0, 0, 0] }; +const bob = { op: 'add', shape: 'sphere', id: 'bob', size: [0.8, 0.8, 0.8], pos: [0, -4, 0] }; + +test('a pendulum swings about the part it hangs from, let go at the far end, and keeps its string length', () => { + const r = run(support, bob, { op: 'pendulum', id: 'bob', from: 'support', swing: 25 }); + const a = (25 * Math.PI) / 180; + const start = posOf(at(r, 0), 'bob'); + near(start[0], 4 * Math.sin(a)); + near(start[1], -4 * Math.cos(a)); + for (const t of [0, 0.7, 1.9, 2.6, 3.9]) { + const p = posOf(at(r, t), 'bob'); + near(Math.hypot(p[0], p[1]), 4, 1e-3); + } + // 1.6 x sqrt(4) = 3.2 seconds a swing there and back: the far end on the other side at half of it + near(posOf(at(r, 1.6), 'bob')[0], -4 * Math.sin(a)); + near(posOf(at(r, 3.2), 'bob')[0], 4 * Math.sin(a)); +}); + +test('a pendulum hangs from the part its weight is attached to (the way a model writes it), and swings about that part, not nothing', () => { + const hung = { op: 'add', shape: 'sphere', id: 'bob', parent: 'support', parentAnchor: 'bottom', selfAnchor: 'top', pos: [0, -4, 0], size: [1.2, 1.2, 1.2] }; + const r = run(support, hung, { op: 'pendulum', id: 'bob', from: 'support', swing: 30, period: 2.5 }); + assert.deepEqual(r.issues, []); + // the bob rides in the support (which stays at the origin), so its own place is its place in the scene; at rest it hangs 4.8 below the middle + // of the support (the support's bottom is 0.2 down, the bob's top is 0.6 above its middle, and it is written 4 further down) + const world = (t: number) => posOf(at(r, t), 'bob'); + const lengths = [0, 0.4, 1.1, 2, 3].map((t) => Math.hypot(world(t)[0], world(t)[1])); + assert.ok(lengths.every((l) => Math.abs(l - 4.8) < 1e-6), `lengths ${lengths}`); + const a = (30 * Math.PI) / 180; + near(Math.atan2(world(0)[0], -world(0)[1]), a, 1e-6); + near(Math.atan2(world(1.25)[0], -world(1.25)[1]), -a, 0.02); +}); + +test('a longer string swings more slowly, and damp lets it run down to hanging still', () => { + const short = run(support, { ...bob, pos: [0, -1, 0] }, { op: 'pendulum', id: 'bob', from: 'support', swing: 30 }); + const long = run(support, { ...bob, pos: [0, -9, 0] }, { op: 'pendulum', id: 'bob', from: 'support', swing: 30 }); + const crossing = (r: ReturnType) => { + let t = 0.05; + while (posOf(at(r, t), 'bob')[0] > 0 && t < 20) t += 0.05; + return t; + }; + assert.ok(crossing(long) > 2 * crossing(short), `${crossing(long)} vs ${crossing(short)}`); + const damped = run(support, bob, { op: 'pendulum', id: 'bob', from: 'support', swing: 25, damp: 1 }); + const x0 = Math.abs(posOf(at(damped, 0), 'bob')[0]); + // the far end of the fourth swing: three cycles on, a third of a third of a third as big + const x3 = Math.abs(posOf(at(damped, 3.2 * 3), 'bob')[0]); + assert.ok(x3 < x0 * 0.06 && x3 > x0 * 0.04, `${x3} of ${x0}`); + assert.ok(Math.abs(posOf(at(damped, 40), 'bob')[0]) < 0.01, 'it hangs still in the end'); +}); + +test('a pendulum with nothing to hang from is dropped with a note', () => { + const checked = validateStep({ say: 'x', actions: [bob, { op: 'pendulum', id: 'bob' }] }, createSceneState()); + assert.ok(checked.issues.some((i) => /hang/.test(i.message)), JSON.stringify(checked.issues)); +}); + +test('a weight on a spring starts pulled low, bobs the amount each way and settles when damped', () => { + const r = run({ op: 'add', shape: 'sphere', id: 'weight', size: [1, 1, 1], pos: [0, 2, 0] }, { op: 'oscillate', id: 'weight', amount: 0.8, period: 2, damp: 1.5 }); + near(posOf(at(r, 0), 'weight')[1], 2 - 0.8); + near(posOf(at(r, 1), 'weight')[1], 2 + 0.8 * Math.exp(-0.5 / 1.5)); + assert.ok(Math.abs(posOf(at(r, 60), 'weight')[1] - 2) < 0.01, 'at rest in the end'); + const free = run({ op: 'add', shape: 'sphere', id: 'weight', size: [1, 1, 1], pos: [0, 2, 0] }, { op: 'oscillate', id: 'weight', amount: 0.8, period: 2 }); + near(posOf(at(free, 61), 'weight')[1], 2 + 0.8, 1e-3); +}); + +test('a floating part begins at rest, bobs and rocks within its bounds, and settles when damped', () => { + const boat = { op: 'add', shape: 'box', id: 'boat', size: [3, 0.6, 1], pos: [0, 0, 0], rot: [0, 0, 0] }; + const r = run(boat, { op: 'float', id: 'boat', bob: 0.2, tilt: 6, period: 3 }); + near(posOf(at(r, 0), 'boat')[1], 0, 1e-6); + near(rotOf(at(r, 0), 'boat')[2], 0, 1e-6); + let peak = 0, lean = 0; + for (let t = 0; t <= 12; t += 0.1) { + peak = Math.max(peak, Math.abs(posOf(at(r, t), 'boat')[1])); + lean = Math.max(lean, Math.abs(rotOf(at(r, t), 'boat')[2])); + } + assert.ok(peak > 0.18 && peak <= 0.2 + 1e-6, `bob ${peak}`); + assert.ok(lean > 5 && lean <= 6 + 1e-6, `rock ${lean}`); + const calm = run(boat, { op: 'float', id: 'boat', bob: 0.2, tilt: 6, period: 3, damp: 1 }); + assert.ok(Math.abs(posOf(at(calm, 60), 'boat')[1]) < 0.001 && Math.abs(rotOf(at(calm, 60), 'boat')[2]) < 0.01); +}); + +test('the fall curve is a square of the time, lands at 1, and bounces back up a smaller height each time', () => { + near(fallCurve(0, 0.5), 0); + near(fallCurve(1, 0.5), 1); + // dead landing: a plain square and no rise after it + const dead = [0.1, 0.3, 0.5, 0.7, 0.9, 1].map((u) => fallCurve(u, 0)); + dead.forEach((p, i) => near(p, [0.1, 0.3, 0.5, 0.7, 0.9, 1][i]! ** 2)); + // springy: it lands, comes back off the floor and lands again, never above the start and each rise lower than the one before + const samples = Array.from({ length: 400 }, (_, i) => fallCurve(i / 399, 0.6)); + assert.ok(samples.every((p) => p >= -1e-9 && p <= 1 + 1e-9)); + // the top of each bounce is a low point of the curve: there are at least three, and each is lower than the one before + const rises: number[] = []; + for (let i = 1; i < samples.length - 1; i++) if ((samples[i] as number) < (samples[i - 1] as number) && (samples[i] as number) <= (samples[i + 1] as number)) rises.push(1 - (samples[i] as number)); + assert.ok(rises.length >= 3, `bounces ${rises.length}`); + rises.forEach((h, i) => i > 0 && assert.ok(h < (rises[i - 1] as number) + 1e-9, `${rises}`)); + near(rises[0], 0.36, 0.01); + assert.ok(fallSeconds(16, 0.3) > fallSeconds(4, 0.3), 'a greater fall takes longer'); + assert.ok(fallSeconds(4, 0.6) > fallSeconds(4, 0), 'and bouncing takes longer than landing dead'); +}); + +test('a drop falls to the height, speeding up, and ends there; it never goes below it', () => { + const r = run({ op: 'add', shape: 'sphere', id: 'ball', size: [1, 1, 1], pos: [1, 6, 0] }, { op: 'drop', id: 'ball', to: 0.5, bounce: 0.5 }); + near(posOf(at(r, 0), 'ball')[1], 6); + near(posOf(at(r, 0), 'ball')[0], 1); + const end = r.plan.duration; + near(posOf(at(r, end + 1), 'ball')[1], 0.5); + let lowest = 99; + for (let t = 0; t <= end; t += end / 200) lowest = Math.min(lowest, posOf(at(r, t), 'ball')[1]); + assert.ok(lowest >= 0.5 - 1e-9, `lowest ${lowest}`); + const first = fallSeconds(5.5, 0.5); + assert.ok(Math.abs(end - first) < 0.01, 'the drop takes as long as the fall says'); + // a constant pull: a quarter of the way down the first fall has gone a sixteenth of the way + const total = 1 / (1 + 2 * (0.5 + 0.25 + 0.125 + 0.0625 + 0.03125)); + near(posOf(at(r, end * total * 0.25), 'ball')[1], 6 - 5.5 / 16, 0.02); +}); + +test('a pump squeezes its chamber, opens the outlet while it does and the inlet while it refills', () => { + const parts = [ + { op: 'add', shape: 'sphere', id: 'chamber', size: [2, 2, 2], pos: [0, 0, 0] }, + { op: 'add', shape: 'box', id: 'inlet', size: [1, 0.1, 1], pos: [-2, 0, 0] }, + { op: 'add', shape: 'box', id: 'outlet', size: [1, 0.1, 1], pos: [2, 0, 0] }, + ]; + const r = run(...parts, { op: 'pump', id: 'chamber', inlet: 'inlet', outlet: 'outlet', squeeze: 0.6, open: 60, period: 2 }); + assert.deepEqual(r.issues, []); + const shut = (id: string, t: number) => Math.abs(rotOf(at(r, t), id)[2]); + // a 2 second cycle: 0 to 1 it squeezes (the outlet opens, fullest at 0.5), 1 to 2 it refills (the inlet opens, fullest at 1.5), smallest at 1 and relaxed at 0 and 2 + near(scaleOf(at(r, 0), 'chamber')[0], 1); + near(scaleOf(at(r, 1), 'chamber')[0], 0.6); + near(scaleOf(at(r, 3), 'chamber')[0], 0.6); + near(shut('outlet', 0), 0, 1e-6); + near(shut('outlet', 0.5), 60, 0.05); + near(shut('outlet', 0.25), 60 * Math.cos(Math.PI / 4), 0.05); + assert.ok(shut('inlet', 0.5) < 1e-6, 'the inlet is shut while it squeezes'); + assert.ok(shut('outlet', 1.5) < 1e-6, 'the outlet is shut while it refills'); + near(shut('inlet', 1.5), 60, 0.05); + assert.ok(shut('inlet', 1) < 1e-6 && shut('outlet', 1) < 1e-6, 'both are shut when it is smallest'); + // a flap is never open the other way + for (let t = 0; t < 4; t += 0.1) assert.ok(rotOf(at(r, t), 'inlet')[2] >= -1e-9 && rotOf(at(r, t), 'outlet')[2] >= -1e-9); +}); + +test('a pump without a valve, or a valve that is its own chamber, is dropped with a note', () => { + const chamber = { op: 'add', shape: 'sphere', id: 'chamber', size: [2, 2, 2] }; + const none = validateStep({ say: 'x', actions: [chamber, { op: 'pump', id: 'chamber' }] }, createSceneState()); + assert.ok(none.issues.some((i) => /inlet or an outlet/.test(i.message)), JSON.stringify(none.issues)); + const same = validateStep({ say: 'x', actions: [chamber, { op: 'pump', id: 'chamber', inlet: 'chamber' }] }, createSceneState()); + assert.ok(same.issues.some((i) => /different part/.test(i.message)), JSON.stringify(same.issues)); +}); + +test('a load on an incline slides along the slope of its ramp, or along an angle', () => { + const load = { op: 'add', shape: 'box', id: 'crate', size: [1, 1, 1], pos: [0, 0, 0] }; + const ramp = { op: 'add', shape: 'box', id: 'ramp', size: [8, 0.4, 2], pos: [0, -1, 0], rot: [0, 0, 30] }; + const r = run(ramp, load, { op: 'incline', id: 'crate', ramp: 'ramp', travel: 4, period: 4 }); + const a = at(r, 1), b = at(r, 3); + const dx = posOf(b, 'crate')[0] - posOf(a, 'crate')[0], dy = posOf(b, 'crate')[1] - posOf(a, 'crate')[1]; + assert.ok(Math.hypot(dx, dy) > 3, 'it moves along the slope'); + near(Math.abs(Math.atan2(dy, dx) * (180 / Math.PI)), 150, 0.5); + const byAngle = run(load, { op: 'incline', id: 'crate', angle: 30, travel: 4, period: 4 }); + const p = posOf(at(byAngle, 1), 'crate'), q = posOf(at(byAngle, 3), 'crate'); + near(Math.abs(Math.atan2(q[1] - p[1], q[0] - p[0]) * (180 / Math.PI)), 150, 0.5); + const none = validateStep({ say: 'x', actions: [load, { op: 'incline', id: 'crate' }] }, createSceneState()); + assert.ok(none.issues.some((i) => /slope|ramp/.test(i.message)), JSON.stringify(none.issues)); +}); + +test('a wedge driven in pushes the part beside it aside by tan of its angle, each to its own side', () => { + const wedge = { op: 'add', shape: 'cone', id: 'wedge', size: [2, 3, 2], pos: [0, 2, 0], rot: [0, 0, 180] }; + const left = { op: 'add', shape: 'box', id: 'left', size: [1, 2, 1], pos: [-1.5, 0, 0] }; + const right = { op: 'add', shape: 'box', id: 'right', size: [1, 2, 1], pos: [1.5, 0, 0] }; + const r = run(wedge, left, right, { op: 'wedge', id: 'wedge', drives: 'left', angle: 30, travel: 2, period: 4 }, { op: 'wedge', id: 'wedge', drives: 'right', angle: 30, travel: 2, period: 4 }); + assert.deepEqual(r.issues, []); + const spread = (t: number) => posOf(at(r, t), 'right')[0] - posOf(at(r, t), 'left')[0]; + const wedgeY = (t: number) => posOf(at(r, t), 'wedge')[1]; + // in: while the wedge is lower than at rest, the two are further apart than at rest by 2 tan(angle) of how far it has gone down; and it is symmetric + for (const t of [0.4, 1.3, 2.2, 3.1]) { + const down = 2 - wedgeY(t); + near(spread(t), 3 + 2 * Math.tan((30 * Math.PI) / 180) * down, 1e-6); + near(posOf(at(r, t), 'left')[0] + posOf(at(r, t), 'right')[0], 0, 1e-6); + } + assert.ok(Math.abs(wedgeY(1) - 2) > 0.5, 'the wedge really moves'); +}); + +test('a screw turns about its length and its nut travels the pitch for each turn', () => { + const screw = { op: 'add', shape: 'cylinder', id: 'screw', size: [0.6, 6, 0.6], pos: [0, 0, 0] }; + const nut = { op: 'add', shape: 'box', id: 'nut', size: [1.4, 0.5, 1.4], pos: [0, -1, 0] }; + const r = run(screw, nut, { op: 'screw', id: 'nut', screw: 'screw', pitch: 0.5, rpm: 60 }); + assert.deepEqual(r.issues, []); + // three seconds at 60 rpm is three turns once it is up to speed: the angle it has turned and the travel agree + const turned = (t: number) => rotOf(at(r, t), 'screw')[1]; + const moved = (t: number) => posOf(at(r, t), 'nut')[1] + 1; + for (const t of [1, 2.5, 4]) near(moved(t), (0.5 * turned(t)) / 360, 1e-6); + assert.ok(Math.abs(moved(4)) > 1, 'the nut really travels'); + const lying = run({ ...screw, rot: [0, 0, 90] }, { ...nut, pos: [-1, 0, 0] }, { op: 'screw', id: 'nut', screw: 'screw', pitch: 0.5, rpm: 60 }); + assert.ok(Math.abs(posOf(at(lying, 4), 'nut')[0] + 1) > 1, 'a screw lying on its side carries the nut along x'); + near(posOf(at(lying, 4), 'nut')[1], 0, 1e-6); +}); diff --git a/test/guide-pass.test.ts b/test/guide-pass.test.ts new file mode 100644 index 0000000..40dd80f --- /dev/null +++ b/test/guide-pass.test.ts @@ -0,0 +1,87 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { createSceneState, sceneGuide, sceneSchemaLean, validateStep } from '../src/scene/index.ts'; +import { emptyFrame, evaluate, planStep } from '../src/overlay/timeline.ts'; +import type { Frame } from '../src/overlay/timeline.ts'; + +// The guide pass: what a model was seen to get wrong, said once; and the size the prompt is held to. + +const check = (...actions: unknown[]) => validateStep({ say: 'x', actions }, createSceneState()); +const posOf = (f: Frame, id: string) => { + const o = f.objects.find((x) => x.id === id)!; + return (o.pose?.pos ?? o.pos) as [number, number, number]; +}; +const play = (...actions: unknown[]) => { + const checked = check(...actions); + assert.ok(checked.step, JSON.stringify(checked.issues)); + return planStep(emptyFrame(), checked.step); +}; + +test('a shape written as the op (op force, field, particles) is read as the add it was meant to be, with a note', () => { + const base = { op: 'add', shape: 'box', id: 'weight', size: [1, 1, 1] }; + const force = check(base, { op: 'force', id: 'g', on: 'weight', dir: [0, -1, 0], strength: 2 }); + assert.equal(force.step?.actions.length, 2, 'the arrow is made'); + assert.deepEqual(force.step?.actions[1] && { op: (force.step.actions[1] as { op: string }).op, shape: (force.step.actions[1] as { shape?: string }).shape }, { op: 'add', shape: 'force' }); + assert.ok(force.issues.some((i) => /op "force" read as add with shape force/.test(i.message)), JSON.stringify(force.issues)); + const field = check({ op: 'field', id: 'f', kind: 'dipole' }); + assert.equal((field.step?.actions[0] as { shape?: string } | undefined)?.shape, 'field', JSON.stringify(field.issues)); + const cloud = check({ op: 'particles', id: 'p', from: [1, 1, 1], to: [4, 4, 4] }); + assert.equal((cloud.step?.actions[0] as { shape?: string } | undefined)?.shape, 'particles', JSON.stringify(cloud.issues)); +}); + +test('any shape name written as an op is rewritten, each with a note (sphere, tube, array, group too)', () => { + const box = { op: 'add', shape: 'box', id: 'b', size: [1, 1, 1] }; + for (const written of [ + { op: 'sphere', id: 's', size: [1, 1, 1] }, + { op: 'group', id: 'g' }, + { op: 'tube', id: 't', pts: [[0, 0, 0], [0, 2, 0]], radius: 0.2 }, + { op: 'array', id: 'a', of: 'b', count: 3, step: [1, 0, 0] }, + ]) { + const r = check(box, written); + assert.equal((r.step?.actions[1] as { shape?: string } | undefined)?.shape, written.op, `${written.op}: ${JSON.stringify(r.issues)}`); + assert.ok(r.issues.some((i) => new RegExp(`op "${written.op}" read as add with shape ${written.op}`).test(i.message)), `${written.op} has its note`); + } +}); + +test('a name that is no shape stays dropped, and so does an op whose shape is given as something else', () => { + const nothing = check({ op: 'frobnicate', id: 'f' }); + assert.ok(nothing.issues.some((i) => /unknown action "frobnicate"/.test(i.message)), JSON.stringify(nothing.issues)); + const other = check({ op: 'force', shape: 'box', id: 'f', size: [1, 1, 1] }); + assert.ok(other.issues.some((i) => /unknown action "force"/.test(i.message)), JSON.stringify(other.issues)); +}); + +const wheel = { op: 'add', shape: 'cylinder', id: 'drum', size: [1, 3, 1] }; +const load = { op: 'add', shape: 'box', id: 'bucket', size: [1, 1, 1], pos: [3, -2, 0] }; + +test('a pulley load that would rise without end stops at max; without max it goes on', () => { + const free = play(wheel, load, { op: 'pulley', id: 'bucket', wheel: 'drum', radius: 0.4, rpm: 60 }); + const stopped = play(wheel, load, { op: 'pulley', id: 'bucket', wheel: 'drum', radius: 0.4, rpm: 60, max: 2 }); + const rise = (plan: ReturnType, t: number) => Math.abs(posOf(evaluate(plan, t), 'bucket')[1] - -2); + assert.ok(rise(free, 6) > 10, `free: ${rise(free, 6)}`); + assert.ok(Math.abs(rise(stopped, 6) - 2) < 1e-6, `stopped: ${rise(stopped, 6)}`); + assert.ok(rise(stopped, 0.3) < 2, 'and it was on its way before that'); +}); + +test('a screw nut stops at max the same way', () => { + const screw = { op: 'add', shape: 'cylinder', id: 'bolt', size: [0.5, 4, 0.5] }; + const nut = { op: 'add', shape: 'box', id: 'nut', size: [1, 0.4, 1] }; + const free = play(screw, nut, { op: 'screw', id: 'nut', screw: 'bolt', pitch: 0.5, rpm: 60 }); + const stopped = play(screw, nut, { op: 'screw', id: 'nut', screw: 'bolt', pitch: 0.5, rpm: 60, max: 1.5 }); + const travel = (plan: ReturnType, t: number) => Math.abs(posOf(evaluate(plan, t), 'nut')[1]); + assert.ok(travel(free, 10) > 4, `free: ${travel(free, 10)}`); + assert.ok(travel(stopped, 10) <= 1.5 + 1e-6, `stopped: ${travel(stopped, 10)}`); +}); + +test('the guide tells the model what the judge sets showed it missing', () => { + assert.match(sceneGuide, /heart or bellows is a pump/); + assert.match(sceneGuide, /surge and beat/); + assert.match(sceneGuide, /never op force/); + assert.match(sceneGuide, /A load that would rise or travel without end .* gets max/); + assert.match(sceneGuide, /keep a part that travels along the tube .* off the ends/); + assert.match(sceneGuide, /hang it from a part that does not slide, and write the pendulum after any loop/); +}); + +test('the prompt keeps to its budget: the guide and the lean schema are sent with every question', () => { + assert.ok(sceneGuide.length <= 43500, `the guide is ${sceneGuide.length} characters`); + assert.ok(JSON.stringify(sceneSchemaLean).length <= 33500, `the lean schema is ${JSON.stringify(sceneSchemaLean).length} characters`); +}); diff --git a/test/overlay-pin-interior.test.ts b/test/overlay-pin-interior.test.ts new file mode 100644 index 0000000..ea921c5 --- /dev/null +++ b/test/overlay-pin-interior.test.ts @@ -0,0 +1,29 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; + +// A pin written at a point inside a solid is on the object, not behind anything: the middle of a kit wheel (a barrel with a cap set into each end) +// has a closed piece's near face between it and the camera, and its label was never drawn. +async function pinAt(part: Record, point: [number, number, number]) { + const { PanelScene } = await import('../src/overlay/scene3d.ts'); + const { frameAt } = await import('../src/overlay/timeline.ts'); + const f = frameAt([{ say: 'x', actions: [{ op: 'panel', x: 100, y: 100, w: 600, h: 500 }, { op: 'add', id: 'p', ...part }] }] as never, 0, 99); + const scene = new PanelScene(); + scene.sync(f, 1); + const key = f.objects.find((o) => o.id === 'p')?.key ?? -1; + return scene.project(key, point, 800, 800); +} + +const wheel = { shape: 'part', part: 'wheel', n: 8, size: [2, 2, 0.4] }; + +test('a pin inside the hub of a kit wheel is drawn, and so is one on the rim', async () => { + for (const point of [[0, 0, 0], [0, 0, 0.05], [0, 0, 0.1], [0.3, 0, 0], [0.9, 0, 0]] as Array<[number, number, number]>) { + const at = await pinAt(wheel, point); + assert.ok(at?.visible, `point ${JSON.stringify(point)} is on the wheel`); + } +}); + +test('a point behind a surface of the object, in an empty cavity, is still not drawn', async () => { + const shell = { shape: 'shell', size: [4, 4, 4], inner: 0.6, latitude: [-90, 90] }; + const cavity = await pinAt(shell, [0, 0, 0]); + assert.ok(!cavity?.visible, 'the middle of a closed hollow shell is hidden by its wall'); +}); diff --git a/test/overlay-placement.test.ts b/test/overlay-placement.test.ts index 24763bc..b1d5455 100644 --- a/test/overlay-placement.test.ts +++ b/test/overlay-placement.test.ts @@ -297,7 +297,7 @@ test('a diagram that has to grow is placed again for its new size, at that size, test('a stage the model asked for small is given more room (blank page first, then page text if that is all there is), never over what is pointed at, and not past a comfortable size', () => { const small = { x: 700, y: 200, w: 130, h: 200 }; const grown = placer().panel(small); - assert.ok(grown.w >= 130 * 1.5 && grown.w <= 320 && grown.h <= 560 && inside(grown), `grown on blank page: ${JSON.stringify(grown)}`); + assert.ok(grown.w >= 130 * 1.5 && grown.w <= 320 && grown.h <= 620 && inside(grown), `grown on blank page: ${JSON.stringify(grown)}`); assert.ok(placer().busy({ x: grown.x - 6, y: grown.y - 10, w: grown.w + 12, h: grown.h + 20 }) < 0.02, 'and still on blank page'); // Narrow blank room: an explanation is the priority, so it grows onto the text beside the strip rather than stay a sliver. const tight = new Placer(textPage(0.85), { aspect: 16 / 9 }).panel({ x: 880, y: 200, w: 100, h: 200 }); @@ -308,8 +308,8 @@ test('a stage the model asked for small is given more room (blank page first, th p.reserve(pointed); const beside = p.panel(small); assert.ok(!overlaps(beside, pointed), JSON.stringify(beside)); - // A stage already of a comfortable size is left alone. - assert.deepEqual(placer().panel({ x: 600, y: 150, w: 320, h: 560 }), { x: 600, y: 150, w: 320, h: 560 }); + // A stage already of a comfortable size (a fair share of the screen's height) is left alone. + assert.deepEqual(placer().panel({ x: 600, y: 100, w: 320, h: 620 }), { x: 600, y: 100, w: 320, h: 620 }); // A page that is all text: the stage still gets its room; it does not stay small to spare the text. const crowded = new Placer(textPage(1), { aspect: 16 / 9 }).panel(small); assert.ok(crowded.w >= small.w * 1.5, JSON.stringify(crowded)); diff --git a/test/overlay-stage-height.test.ts b/test/overlay-stage-height.test.ts new file mode 100644 index 0000000..e1e2a67 --- /dev/null +++ b/test/overlay-stage-height.test.ts @@ -0,0 +1,215 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { DiagramPainter } from '../src/overlay/diagram-draw.ts'; +import { drawMarks } from '../src/overlay/marks.ts'; +import { evaluate, emptyFrame, planStep, settle } from '../src/overlay/timeline.ts'; +import type { Frame } from '../src/overlay/timeline.ts'; +import { Placer, pageGrid, placeAction } from '../src/overlay/placement.ts'; +import type { Box } from '../src/overlay/placement.ts'; +import { panelRect } from '../src/overlay/layout.ts'; +import { SurfaceAdmission, admittedFrame, stageKeepOut, withoutReplacedSurfaces } from '../src/overlay/surface-admission.ts'; +import type { Action, Step } from '../src/scene/types.ts'; + +const COLS = 192, ROWS = 108; +/** A page: text lines across the left `textEnd` of the screen, nothing on the right. */ +function page(textEnd = 0.45, from = 0) { + const gray = new Uint8Array(COLS * ROWS); + for (let r = 0; r < ROWS; r++) for (let c = 0; c < COLS; c++) { + const text = c > COLS * from + 4 && c < COLS * textEnd && r > 8 && r % 4 < 2 && (c * 7 + r * 13) % 11 !== 0; + gray[r * COLS + c] = text ? 40 : 238; + } + return pageGrid(gray, COLS, ROWS); +} +const placer = (grid = page(), aspect = 16 / 9) => new Placer(grid, { aspect, height: 1080 }); +const overlaps = (a: Box, b: Box) => Math.min(a.x + a.w, b.x + b.w) > Math.max(a.x, b.x) && Math.min(a.y + a.h, b.y + b.h) > Math.max(a.y, b.y); +const FAIR = 620; + +test('a short stage on a quiet page grows taller to about 62 percent of the screen, keeping its width and what it already covered', () => { + const asked = { x: 600, y: 150, w: 330, h: 400 }; + const got = placer().panel(asked); + assert.equal(got.w, asked.w, 'width is kept'); + assert.equal(got.x, asked.x, 'and so is its left edge'); + assert.ok(got.h >= FAIR - 40 && got.h <= FAIR + 1, `grew to about 62 percent: ${JSON.stringify(got)}`); + assert.ok(got.y <= asked.y && got.y + got.h >= asked.y + asked.h, 'the stage still covers everything it asked for'); + assert.ok(got.y >= 12 && got.y + got.h <= 1000 - 12, 'inside the screen margin'); +}); + +test('a stage already about 62 percent tall or more is left alone, and nothing is ever made smaller', () => { + for (const h of [600, 640, 800]) assert.deepEqual(placer().panel({ x: 600, y: 100, w: 330, h }), { x: 600, y: 100, w: 330, h }); +}); + +test('it grows only into a page with little on it: text under the added height stops it', () => { + const asked = { x: 300, y: 150, w: 300, h: 400 }; + const quiet = placer(page(0.2)).panel(asked); + assert.ok(quiet.h >= FAIR - 40, `quiet page: ${JSON.stringify(quiet)}`); + // Body text on both sides and across the whole screen under the stage's reach: no growth, and the stage stays where the model put it. + const busy = placer(page(1)).panel(asked); + assert.equal(busy.h, asked.h, `a full page of text is not covered further: ${JSON.stringify(busy)}`); +}); + +test('cards and page controls are hard keep-outs: it grows only as far as the gap they leave', () => { + const asked = { x: 600, y: 150, w: 330, h: 400 }; + const p = placer(); + const below: Box = { x: 560, y: 600, w: 420, h: 120 }; + p.card(below, 'note'); + const withCard = p.panel(asked); + assert.ok(!overlaps(withCard, below), `not over the card: ${JSON.stringify(withCard)}`); + assert.ok(withCard.h > asked.h, 'it still grows upward into the room there is'); + const q = placer(); + const control: Box = { x: 640, y: 570, w: 200, h: 40 }; + q.setControls([control]); + const withControl = q.panel(asked); + assert.ok(!overlaps(withControl, control), `not over the control: ${JSON.stringify(withControl)}`); + // Boxed in above and below: no growth at all. + const r = placer(); + r.card({ x: 560, y: 12, w: 420, h: 120 }, 'a'); + r.card({ x: 560, y: 560, w: 420, h: 120 }, 'b'); + const boxed = r.panel(asked); + assert.equal(boxed.h, asked.h, JSON.stringify(boxed)); +}); + +test('what the answer points at is a preference: growth goes the other way, or not at all, rather than cover it; a spot the stage already covers is left out of the reckoning', () => { + const asked = { x: 600, y: 150, w: 330, h: 400 }; + const pointedBelow: Box = { x: 650, y: 560, w: 200, h: 50 }; + const p = placer(); p.reserve(pointedBelow); + const got = p.panel(asked); + assert.ok(!overlaps(got, pointedBelow), `not over the pointed-at spot: ${JSON.stringify(got)}`); + assert.ok(got.h > asked.h, 'it grows upward instead'); + const both = placer(); both.reserve(pointedBelow); both.reserve({ x: 650, y: 60, w: 200, h: 50 }); + const none = both.panel(asked); + assert.ok(!overlaps(none, pointedBelow) && !overlaps(none, { x: 650, y: 60, w: 200, h: 50 }), `neither is covered: ${JSON.stringify(none)}`); + // Pointed-at ground the stage cannot avoid (the whole screen is boxed): it is already under the stage, so it does not stop the growth. + const everywhere = placer(); everywhere.reserve({ x: 0, y: 0, w: 1000, h: 1000 }); + const covered = everywhere.panel(asked); + assert.ok(covered.h >= FAIR - 40, `a spot already under the stage does not stop it growing: ${JSON.stringify(covered)}`); +}); + +test('later cards keep off the grown stage, and a card written before the stage is not grown over', () => { + const p = placer(); + const first = placeAction(p, { op: 'card', id: 'n1', x: 600, y: 600, w: 300, title: 'Before', rows: ['a', 'b'] } as Action, 1080) as Extract; + const stage = placeAction(p, { op: 'panel', x: 600, y: 150, w: 330, h: 400 } as Action, 1080) as Extract; + const later = placeAction(p, { op: 'card', id: 'n2', x: 600, y: 300, w: 300, title: 'After', rows: ['c', 'd'] } as Action, 1080) as Extract; + const box = (a: { x: number; y: number; w: number; h?: number }): Box => ({ x: a.x, y: a.y, w: a.w, h: a.h ?? 100 }); + assert.ok(!overlaps(box(stage as never), box({ x: first.x, y: first.y, w: first.w ?? 300, h: 90 })), 'the stage does not cover the earlier card'); + assert.ok(stage.h >= 400 && !overlaps(box(later as never), box(stage as never)), 'the later card is clear of the grown stage'); +}); + +// ---- Growth leaves the next note its room ------------------------------------------------------------------------------------------------------ + +/** Text across the whole page except one blank rectangle (units): the only quiet ground there is. */ +function pageBlankOnlyIn(blank: Box) { + const gray = new Uint8Array(COLS * ROWS); + for (let r = 0; r < ROWS; r++) for (let c = 0; c < COLS; c++) { + const x = ((c + 0.5) / COLS) * 1000, y = ((r + 0.5) / ROWS) * 1000; + const inside = x >= blank.x && x <= blank.x + blank.w && y >= blank.y && y <= blank.y + blank.h; + const text = !inside && r > 2 && r % 4 < 2 && (c * 7 + r * 13) % 11 !== 0; + gray[r * COLS + c] = text ? 40 : 238; + } + return pageGrid(gray, COLS, ROWS); +} +const NOTE_W = 380, NOTE_H = 150; + +test('growth stops short of taking the last quiet place a note-sized card could have: the card written after still lands on blank page, not on the text', () => { + // The blank column ends at 780: a stage grown to 620 from 100 (and its buttons' strip) would leave no room for a note beside it in the column. + const p = new Placer(pageBlankOnlyIn({ x: 560, y: 40, w: 420, h: 820 }), { aspect: 1920 / 804, height: 804 }); + const stage = p.panel({ x: 600, y: 100, w: 330, h: 400 }); + assert.ok(stage.h > 400, `it still grows where the room allows: ${JSON.stringify(stage)}`); + // The column is blank to 860: the note (150 tall) and the strip of the stage's buttons (90) have to fit under the stage, so it grows to about 510 and no further. + assert.ok(stage.h <= 520, `but not to the full share, which would take the note's room: ${JSON.stringify(stage)}`); + const note = p.card({ x: 560, y: 600, w: NOTE_W, h: NOTE_H }, 'note'); + assert.ok(!overlaps(note, stage), 'the note is clear of the stage'); + assert.ok(p.busy(note) < 0.05, `and it sits on blank page, not on the text: ${JSON.stringify(note)} busy ${p.busy(note)}`); +}); + +test('where the blank page has room for the stage and a note both, the stage still grows to the full share', () => { + const p = new Placer(pageBlankOnlyIn({ x: 560, y: 40, w: 420, h: 940 }), { aspect: 1920 / 804, height: 804 }); + const stage = p.panel({ x: 600, y: 100, w: 330, h: 400 }); + assert.ok(stage.h >= FAIR - 40, JSON.stringify(stage)); + const note = p.card({ x: 560, y: 740, w: NOTE_W, h: NOTE_H }, 'note'); + assert.ok(!overlaps(note, stage) && p.busy(note) < 0.05, `the note has its place under the grown stage: ${JSON.stringify(note)}`); +}); + +// ---- Admission holds steady while the stage comes in and eases ------------------------------------------------------------------------------------ + +function canvas() { + const state: Record = { font: '12px sans-serif' }; + return new Proxy(state, { + get(t, k: string) { + if (k === 'createLinearGradient') return () => ({ addColorStop() {} }); + if (k === 'measureText') return (s: string) => ({ width: s.length * 7 }); + return k in t ? t[k] : () => {}; + }, + set(t, k: string, v) { t[k] = v; return true; }, + }) as unknown as CanvasRenderingContext2D; +} +const VIEW = { width: 1920, height: 804, dpr: 1 }; +const stageRect = (f: Frame): Box | undefined => { const r = panelRect(f.panel, VIEW); return r ? { x: r.x, y: r.y, w: r.w, h: r.h } : undefined; }; +function admit(f0: Frame, keepOut: Box[], painter: DiagramPainter, now: number) { + const f = withoutReplacedSurfaces(f0); + const ctx = canvas(); + let a = new SurfaceAdmission(keepOut); + drawMarks(ctx, f.marks, VIEW, { view: VIEW, project: () => undefined, admitSurface: (id: string, b: Box) => { a.admit(id, b); return false; } } as never); + painter.prepare(ctx, f.diagrams, VIEW, now, (id, b) => { a.admit(id, b); }); + a = a.prioritize(f, keepOut); + return { a, shown: admittedFrame(f, a, new Map()) }; +} + +test('a normal answer (stage, a note, a chart) omits nothing at any moment while the grown stage appears', () => { + const p = placer(page(0.4), VIEW.width / VIEW.height); + const written: Action[] = [ + { op: 'panel', x: 640, y: 150, w: 320, h: 380 }, + { op: 'card', id: 'note', x: 60, y: 560, w: 300, title: 'Note', rows: ['one line', 'two lines'] }, + { op: 'diagram', kind: 'chart', id: 'chart', x: 400, y: 560, w: 340, h: 300, title: 'Chart' }, + ] as Action[]; + const placed = written.map((a) => placeAction(p, a, VIEW.height)); + const stage = placed[0] as Extract; + assert.ok(stage.h >= FAIR - 40, `the stage grew: ${JSON.stringify(stage)}`); + const plan = planStep(emptyFrame(), { say: '', actions: placed } as Step); + const painter = new DiagramPainter(); + for (let i = 0; i <= 90; i++) { + const f = evaluate(plan, i / 30); + const keep = stageKeepOut(f.panel, stageRect(f)); + const { a } = admit(f, keep, painter, (i * 1000) / 30); + assert.equal(a.omitted.size, 0, `nothing omitted at ${(i / 30).toFixed(2)} s: ${[...a.omitted.keys()]}`); + } +}); + +test('a stage re-asked in a later step eases over ground the earlier one held, clear of the cards in between, so no card is clipped on the way', () => { + const p = placer(page(0.4), VIEW.width / VIEW.height); + const ask = { op: 'panel', x: 640, y: 300, w: 320, h: 250 } as Action; + const first = placeAction(p, ask, VIEW.height) as Extract; + const card = placeAction(p, { op: 'card', id: 'note', x: 60, y: 560, w: 300, title: 'Note', rows: ['a', 'b'] } as Action, VIEW.height) as Extract; + const second = placeAction(p, ask, VIEW.height) as Extract; + assert.ok(second.x === first.x && second.w === first.w, 'same column'); + const noteBox = { x: card.x, y: card.y, w: card.w ?? 300, h: 90 }; + for (const [name, stage] of [['earlier', first], ['later', second]] as const) assert.ok(!overlaps(stage as never, noteBox), `the card is clear of the ${name} rectangle`); + const base = settle(planStep(emptyFrame(), { say: '', actions: [first, card] } as Step)); + const plan = planStep(base, { say: '', actions: [second] } as Step); + const painter = new DiagramPainter(); + for (let i = 0; i <= 60; i++) { + const f = evaluate(plan, i / 30); + const keep = stageKeepOut(f.panel, stageRect(f)); + const { a } = admit(f, keep, painter, (i * 1000) / 30); + assert.equal(a.omitted.size, 0, `no card clipped at ${(i / 30).toFixed(2)} s`); + } +}); + +// ---- A stage that leaves with a clear does not hold space against what arrives ----------------------------------------------------------------- + +test('a stage that is leaving is not a keep-out: a chart arriving where it stood is admitted from its first frame, with no omission cue', () => { + const stageUnits = { x: 640, y: 150, w: 320, h: 600 }; + const base = settle(planStep(emptyFrame(), { say: '', actions: [{ op: 'panel', ...stageUnits }, { op: 'add', shape: 'box', id: 'b', size: [1, 1, 1] }] } as unknown as Step)); + const plan = planStep(base, { say: '', actions: [{ op: 'clear', target: 'all', at: 0 } as Action, { op: 'diagram', kind: 'chart', id: 'new', x: 660, y: 200, w: 300, h: 300, title: 'New' } as Action] } as Step); + const painter = new DiagramPainter(); + for (const t of [0.02, 0.05, 0.1, 0.15]) { + const f = evaluate(plan, t); + assert.ok(f.panel && f.panel.fade > 0.3, `the stage is still fading at ${t}`); + const keep = stageKeepOut(f.panel, stageRect(f)); + const { a } = admit(f, keep, painter, t * 1000); + assert.equal(a.omitted.size, 0, `no cue at ${t}`); + assert.ok(a.shown.has('new'), `the chart is admitted at ${t}`); + } + const live = evaluate(planStep(base, { say: '', actions: [{ op: 'diagram', kind: 'chart', id: 'on', x: 660, y: 200, w: 300, h: 300, title: 'On' } as Action] } as Step), 1); + assert.deepEqual(stageKeepOut(live.panel, stageRect(live)), [stageRect(live)], 'a stage that stays is still a keep-out'); + assert.deepEqual(stageKeepOut(null, undefined), []); +}); diff --git a/test/overlay-swept-fit.test.ts b/test/overlay-swept-fit.test.ts new file mode 100644 index 0000000..187c9e6 --- /dev/null +++ b/test/overlay-swept-fit.test.ts @@ -0,0 +1,144 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { Mesh, Vector3 } from 'three'; +import { PanelScene } from '../src/overlay/scene3d.ts'; +import { frameAt } from '../src/overlay/timeline.ts'; +import { validateScene } from '../src/scene/index.ts'; +import type { Frame } from '../src/overlay/timeline.ts'; + +// The camera fits the stage to what the model does, not only to how it stands at rest: a model that swings out of its rest shape stays inside the screen the +// whole time (a wing built toward the viewer and flapped off the top and the foot of the screen, 4.4 times as tall as its stage). + +const ASPECT = 883 / 322; // the stage the wing answer was given on a 21:9 screen +const steps = (...stepActions: unknown[][]) => { + const checked = validateScene({ v: 1, steps: stepActions.map((actions, i) => ({ say: `Step ${i}.`, actions })) }); + assert.deepEqual(checked.issues, []); + assert.ok(checked.scene); + return checked.scene.steps; +}; +const tube = (id: string, parent: string, length: number) => ({ op: 'add', shape: 'tube', id, parent, pts: [[0, 0, 0], [0, 0, length]], radius: 0.18, at: 0 }); +const wing = [ + { op: 'panel', x: 520, y: 120, w: 460, h: 400 }, + { op: 'orbit', az: 0, el: 0, dur: 0 }, + { op: 'add', shape: 'box', id: 'torso', size: [3, 1.2, 1.2], at: 0 }, + { op: 'add', shape: 'group', id: 'upper', parent: 'torso', pos: [0, 0, 1.2], at: 0 }, + tube('humerus', 'upper', 2), + { op: 'add', shape: 'group', id: 'fore', parent: 'upper', pos: [0, 0, 2], at: 0 }, + tube('ulna', 'fore', 2), + { op: 'add', shape: 'group', id: 'hand', parent: 'fore', pos: [0, 0, 2], at: 0 }, + tube('carpus', 'hand', 1.8), +]; +const flap = [ + ...['upper', 'fore', 'hand'].map((id) => ({ op: 'joint', id, kind: 'hinge', axis: 'x', pivot: [0, 0, 0], min: -40, max: 40, at: 0 })), + { op: 'loop', id: 'upper', kind: 'swing', amount: 30, axis: 'x', period: 1.6, at: 0 }, + { op: 'loop', id: 'fore', kind: 'swing', amount: 25, axis: 'x', period: 1.6, phase: 30, at: 0 }, + { op: 'loop', id: 'hand', kind: 'swing', amount: 30, axis: 'x', period: 1.6, phase: 60, at: 0 }, +]; + +/** How far the model's vertices reach on the stage, as a share of the stage's half height and half width (1 is the stage's edge). */ +function reach(scene: PanelScene, frame: Frame): { x: number; y: number } { + const out = { x: 0, y: 0 }; + const p = new Vector3(); + for (const o of frame.objects) { + scene.nodeOf(o.key)?.traverse((m) => { + if (!(m instanceof Mesh) || !m.visible) return; + const a = m.geometry.getAttribute('position'); + for (let i = 0; i < a.count; i++) { + p.fromBufferAttribute(a, i).applyMatrix4(m.matrixWorld).project(scene.camera); + out.x = Math.max(out.x, Math.abs(p.x)); + out.y = Math.max(out.y, Math.abs(p.y)); + } + }); + } + return out; +} + +/** Plays a scene's last step for a few seconds, frame by frame as the page does, and gives each frame's reach and the camera's distance. */ +function play(all: ReturnType, from: number, to: number, every: number): Array<{ t: number; x: number; y: number; distance: number }> { + const scene = new PanelScene({ tier: 'mid' }); + try { + const rows = []; + for (let t = from; t <= to + 1e-9; t += every) { + const f = frameAt(all, all.length - 1, t); + scene.sync(f, ASPECT); + rows.push({ t, ...reach(scene, f), distance: scene.camera.position.length() }); + } + return rows; + } finally { scene.destroy(); } +} + +test('a model that swings out of its rest shape stays inside the screen the whole time it swings', () => { + const rows = play(steps(wing, flap), 0.2, 4, 0.1); + const worst = rows.reduce((a, b) => (Math.max(b.x, b.y) > Math.max(a.x, a.y) ? b : a)); + assert.ok(Math.max(worst.x, worst.y) <= 1.001, `at ${worst.t.toFixed(1)} s the model reaches ${worst.x.toFixed(2)} of the stage's half width and ${worst.y.toFixed(2)} of its half height`); + // The camera does not move over the cycle (no breathing), and the model still fills what it can of the stage. + const distances = rows.map((r) => r.distance); + assert.ok(Math.max(...distances) - Math.min(...distances) < 0.01 * Math.max(...distances), 'the camera stands still while the model swings'); + assert.ok(Math.max(...rows.map((r) => Math.max(r.x, r.y))) > 0.8, 'and the swing, at its widest, fills most of the stage'); +}); + +test('a model that only turns inside its own shape is fitted exactly as a still one is', () => { + const wheel = [ + { op: 'panel', x: 520, y: 120, w: 460, h: 400 }, { op: 'orbit', az: 0, el: 0, dur: 0 }, + { op: 'add', shape: 'cylinder', id: 'wheel', size: [4, 0.6, 4], rot: [90, 0, 0], at: 0 }, + ]; + const still = play(steps(wheel), 1, 1, 1)[0]!; + const turning = play(steps(wheel, [{ op: 'spin', id: 'wheel', rpm: 30, at: 0 }]), 0.5, 3, 0.25); + for (const r of turning) assert.ok(Math.abs(r.distance - still.distance) < 0.01 * still.distance, `at ${r.t} s the camera stands ${r.distance.toFixed(2)}, a still wheel's ${still.distance.toFixed(2)}`); +}); + +test('a still model is fitted as it always was', () => { + const rows = play(steps(wing), 1, 1, 1); + assert.ok(Math.max(rows[0]!.x, rows[0]!.y) > 0.6 && Math.max(rows[0]!.x, rows[0]!.y) <= 1.001, `the still wing reaches ${rows[0]!.x.toFixed(2)} by ${rows[0]!.y.toFixed(2)} of the stage`); +}); + +// ---- a swing may pass over the stage's rectangle, never off the screen -------------------------------------------------------------------------------- + +const WINDOW = { width: 1920, height: 804 }; +const STAGE = { x: 998, y: 96, w: 883, h: 322 }; // where the placer put the wing's stage on a 21:9 screen + +/** Plays a scene with the stage placed in a window, and gives each frame's reach of the screen and of the stage, in the window's pixels. */ +function playOnScreen(all: ReturnType, from: number, to: number, every: number): Array<{ t: number; screen: number; stage: number }> { + const scene = new PanelScene({ tier: 'mid' }); + try { + const rows = []; + for (let t = from; t <= to + 1e-9; t += every) { + const f = frameAt(all, all.length - 1, t); + scene.sync(f, STAGE.w / STAGE.h, { rect: STAGE, ...WINDOW }); + let screen = 0, stage = 0; + const p = new Vector3(); + for (const o of f.objects) { + scene.nodeOf(o.key)?.traverse((m) => { + if (!(m instanceof Mesh) || !m.visible) return; + const a = m.geometry.getAttribute('position'); + for (let i = 0; i < a.count; i++) { + p.fromBufferAttribute(a, i).applyMatrix4(m.matrixWorld).project(scene.camera); + const x = ((p.x + 1) / 2) * WINDOW.width, y = ((1 - p.y) / 2) * WINDOW.height; + screen = Math.max(screen, Math.abs(p.x), Math.abs(p.y)); + stage = Math.max(stage, Math.abs(x - (STAGE.x + STAGE.w / 2)) / (STAGE.w / 2), Math.abs(y - (STAGE.y + STAGE.h / 2)) / (STAGE.h / 2)); + } + }); + } + rows.push({ t, screen, stage }); + } + return rows; + } finally { scene.destroy(); } +} + +test('a swing may pass over its stage but stays on the screen, and the model is no smaller for it than it has to be', () => { + const rows = playOnScreen(steps(wing, flap), 0.2, 4, 0.1); + const worstScreen = Math.max(...rows.map((r) => r.screen)); + assert.ok(worstScreen <= 1.001, `the swing reaches ${worstScreen.toFixed(3)} of the screen's half size (1 is its edge)`); + const worstStage = Math.max(...rows.map((r) => r.stage)); + assert.ok(worstStage > 1.2, `and it does pass over the stage's rectangle (${worstStage.toFixed(2)} of the stage's half size), since it is allowed to`); + assert.ok(worstScreen > 0.85, `reaching the screen's edge is what the camera fits it to (${worstScreen.toFixed(2)})`); +}); + +test('a machine that starts later in the same step is fitted from the start: the camera does not move when it starts', () => { + const late = flap.map((a) => (a.op === 'loop' ? { ...a, at: 3 } : a)); + const rows = play(steps(wing, late), 0.5, 5, 0.25); + const before = rows.filter((r) => r.t < 2.9).map((r) => r.distance), after = rows.filter((r) => r.t > 3.3).map((r) => r.distance); + assert.ok(before.length > 3 && after.length > 3); + const d = after[0]!; + for (const x of [...before, ...after]) assert.ok(Math.abs(x - d) < 0.01 * d, `the camera stood ${x.toFixed(2)} before and ${d.toFixed(2)} after the swing began`); +});