lk3d 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/CHANGELOG.md +59 -0
  2. package/README.md +28 -7
  3. package/bin/lk3d.mjs +24 -13
  4. package/dist/lk3d-export.min.js +1 -1
  5. package/dist/lk3d.min.js +73 -35
  6. package/dist/lk3d.mjs +72 -34
  7. package/docs/api.md +132 -51
  8. package/docs/design.md +12 -7
  9. package/docs/handles-and-lines.md +27 -0
  10. package/docs/performance.md +42 -10
  11. package/docs/scene-format.md +31 -29
  12. package/index.d.ts +53 -2
  13. package/package.json +2 -3
  14. package/scene.d.ts +200 -1
  15. package/schema/scene.schema.json +329 -1
  16. package/skill/lk3d/SKILL.md +14 -1
  17. package/src/ao.js +58 -0
  18. package/src/controls.js +21 -2
  19. package/src/element.js +111 -0
  20. package/src/figure/api.js +18 -3
  21. package/src/figure/camera.js +57 -9
  22. package/src/figure/context.d.ts +37 -2
  23. package/src/figure/dimensions.js +140 -0
  24. package/src/figure/idle.js +57 -19
  25. package/src/figure/input.js +105 -7
  26. package/src/figure/labels.js +26 -8
  27. package/src/figure/loop.js +8 -2
  28. package/src/figure/pick.js +24 -8
  29. package/src/figure/steps.js +144 -0
  30. package/src/flow.js +33 -2
  31. package/src/index.js +16 -2
  32. package/src/locales/en.js +7 -0
  33. package/src/locales/vi.js +7 -0
  34. package/src/renderer-gl.js +88 -16
  35. package/src/shaders.js +63 -17
  36. package/src/stylesheet.js +14 -4
  37. package/src/validate.js +89 -0
  38. package/docs/flow.png +0 -0
  39. package/docs/generator.png +0 -0
  40. package/docs/pen-blueprint.png +0 -0
  41. package/docs/pen-dark.png +0 -0
  42. package/docs/pen-ortho.png +0 -0
  43. package/docs/shapes/blade.png +0 -0
  44. package/docs/shapes/blob.png +0 -0
  45. package/docs/shapes/box.png +0 -0
  46. package/docs/shapes/capsule.png +0 -0
  47. package/docs/shapes/cylinder.png +0 -0
  48. package/docs/shapes/dna.png +0 -0
  49. package/docs/shapes/ellipsoid.png +0 -0
  50. package/docs/shapes/extrude.png +0 -0
  51. package/docs/shapes/helix.png +0 -0
  52. package/docs/shapes/lathe.png +0 -0
  53. package/docs/shapes/loop.png +0 -0
  54. package/docs/shapes/molecule.png +0 -0
  55. package/docs/shapes/orbit.png +0 -0
  56. package/docs/shapes/ring.png +0 -0
  57. package/docs/shapes/scatter.png +0 -0
  58. package/docs/shapes/shell.png +0 -0
  59. package/docs/shapes/sphere.png +0 -0
  60. package/docs/shapes/terrain.png +0 -0
  61. package/docs/shapes/torus.png +0 -0
  62. package/docs/shapes/tree.png +0 -0
  63. package/docs/shapes/tube.png +0 -0
@@ -7,18 +7,19 @@ it, keep the tab in front, press Run).
7
7
 
8
8
  ## Size
9
9
 
10
- The global script `dist/lk3d.min.js`, built by `npm run build`. The budget is 65 KB gzipped (57 KB until November 2026; 60 when the engine began checking scenes and models itself; 65 for room to grow): `npm run size` fails past
10
+ The global script `dist/lk3d.min.js`, built by `npm run build`. The budget is 67 KB gzipped (57 KB until November 2026; 60 when the engine began checking scenes and models itself; 65 for room to grow; 67 for guided steps, the cut the reader moves, the element, and streaks and crease shading off the main thread): `npm run size` fails past
11
11
  it, and the CI workflow runs it. The glTF exporter is a script of its own, `dist/lk3d-export.min.js` (3.8 KB, 2.0 KB
12
12
  gzipped), outside the budget: a page loads it only to export.
13
13
 
14
14
  | | Minified | Gzipped |
15
15
  | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
16
+ | lk3d 0.2.1 | 170.5 KB | 66.6 KB |
17
+ | lk3d 0.2.0 | 166.0 KB | 64.9 KB |
16
18
  | lk3d 0.1.0 | 148.0 KB | 59.2 KB |
17
19
  | three.js r187, the smallest page (renderer, camera, box, basic material) | 522 KB | 131 KB |
18
20
  | three.js r187 with what lk3d does (PBR and glass, shadows, environment, orbit controls, picking, glTF, labels, bloom, shape generators) | 708 KB | 181 KB |
19
21
 
20
- Measured with esbuild (minify, ES2020) and gzip level 9 (lk3d by `npm run size`, 8 November 2026: 60 589 bytes, 5 971
21
- under the budget; three.js, 2 November 2026).
22
+ Measured with esbuild (minify, ES2020) and gzip level 9 (lk3d by `npm run size`, 11 November 2026: 68 157 bytes, 451 under the budget; three.js, 2 November 2026).
22
23
 
23
24
  ## Frames
24
25
 
@@ -40,9 +41,9 @@ Apple M3 Pro laptop, Chrome, 120 Hz screen (8.3 ms per frame), 2 November 2026.
40
41
 
41
42
  Every scene kept the screen's rate. The pen look's edges cost no script: they are found once, in idle time after the
42
43
  first picture, and drawn by the GPU. The jet engine's rows were measured again after it was rebuilt on its test stand
43
- (twice the triangles: the stand, flanges and bolts, casings in halves). Flow streaks are the one thing whose script
44
- grows with what is drawn: each streak is placed on the CPU every frame it moves (about 0.6 ms for 2000 here), so a page that needs thousands on a
45
- phone draws fewer (`amount`). On this machine the GPU's cost hides under the 120 Hz frame, so the numbers that
44
+ (twice the triangles: the stand, flanges and bolts, casings in halves). Flow streaks were the one thing whose script
45
+ grew with what is drawn, each placed on the CPU every frame it moved (about 0.6 ms for 2000 here); on WebGL 2 the GPU
46
+ places them now (below). On this machine the GPU's cost hides under the 120 Hz frame, so the numbers that
46
47
  matter most come from phones.
47
48
 
48
49
  ## On a phone-like device
@@ -64,13 +65,44 @@ percentile, on a 60 Hz screen.
64
65
  | Solar System | 11 332 | 6× | 132 | 154 | 340 | 887 | 16.7 / 16.7 |
65
66
  | Molecules | 26 856 | 6× | 224 | 245 | 562 | 6 836 | 16.7 / 16.7 |
66
67
 
67
- The first picture comes within a third of a second even at 6×. The crease shading is the slow part (up to 7 s of
68
- CPU on the molecules at 6×), but it is done in idle time and waits while the reader turns the figure: turned from
69
- its first frame for 4 s at 6×, no frame of the cell, the molecules or the jet engine took over 50 ms (the worst 33
70
- ms), and the shading finished once the figure was still. What this cannot show is a phone's GPU: frames held the
68
+ The first picture comes within a third of a second even at 6×. The crease shading was the slow part (up to 7 s of
69
+ CPU on the molecules at 6×), done on the page in idle slices of a few milliseconds that wait while the reader turns
70
+ the figure. Since 11 November 2026 it is worked out in a Web Worker made of lk3d's own script (the file a `<script src>`
71
+ loaded, or an inline script's text: nothing more to ship), off the page's main thread, and without the slices' pauses
72
+ it finishes sooner: at 1× (the CPU slowdown does not reach a worker, so only 1× compares fairly), shading done
73
+ in ms from mounting, `node test/bench/phone.mjs` with the engine before and after:
74
+
75
+ | Scene | On the page, in idle slices | In the worker |
76
+ | ----------- | --------------------------- | ------------- |
77
+ | Animal cell | 970 | 353 |
78
+ | Jet engine | 536 | 245 |
79
+ | Molecules | 2 170 | 572 |
80
+
81
+ Where no worker can be made (lk3d imported as a module, a page whose policy forbids workers) the figure shades on the
82
+ page in idle slices, as before; `fig.stats().aoWorker` says which. What this cannot show is a phone's GPU: frames held the
71
83
  screen's rate here because the laptop's GPU did the drawing. A real low-end phone (and its browser) is still the
72
84
  measurement that matters.
73
85
 
86
+ ## Flow streaks
87
+
88
+ `node test/bench/flow.mjs`: the ducted fan of the image tests with n streaks between its two flows, moving, each frame
89
+ drawn with `drawNow()` and timed (lk3d's own work, median / 95th percentile in ms; the GPU's work is not in it).
90
+ Headless Chromium on the same laptop (Metal), 11 November 2026.
91
+
92
+ | Streaks | CPU | Placed on the CPU (before) | Placed on the GPU (WebGL 2) |
93
+ | ------- | --- | -------------------------- | --------------------------- |
94
+ | 2 000 | 1× | 0.5 / 0.7 | 0.0 / 0.1 |
95
+ | 8 000 | 1× | 2.0 / 2.3 | 0.0 / 0.2 |
96
+ | 2 000 | 6× | 3.6 / 4.9 | 0.1 / 1.3 |
97
+ | 8 000 | 6× | 13.7 / 16.6 | 0.1 / 1.3 |
98
+
99
+ Each streak used to be placed on the CPU every frame it moved, and its geometry sent to the GPU again (over 2 MB a
100
+ frame at 8 000). On WebGL 2 each flow's paths go to the GPU once, as a float texture (a row a path: each point and its
101
+ distance along), and its streaks' fixed numbers as instance attributes; the vertex shader places each corner from the
102
+ time travelled, finding its place along the path by halving, so a frame sends one number a flow. WebGL 1 and the 2D
103
+ fallback still place them on the CPU. What this moves to the GPU (three lookups of up to 16 steps a corner) is still to
104
+ be measured on a phone's GPU.
105
+
74
106
  ## Many parts
75
107
 
76
108
  How far lk3d scales with the number of parts, measured with `node lessonkit/js/bench.cjs`: n small assemblies on a
@@ -11,35 +11,37 @@ A shape, a motion, a joint, a vessel, a liquid and a gas take only the fields li
11
11
 
12
12
  A 3D figure as data: parts made of shapes, each with a name and a note, that the reader turns, takes apart, cuts open and moves. Every field is one of the format's, so a misspelt one is caught; a page's own data goes under extras.
13
13
 
14
- | Field | Type | Meaning |
15
- | ------------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16
- | `lk3d` | `1` | The version of this format the scene is written in (1). Optional; a later engine that changes the format reads older versions. |
17
- | `w` | number > 0 | The stage's width in proportion to h (16 by default). |
18
- | `h` | number > 0 | The stage's height in proportion to w (10 by default). |
19
- | `narrow` | string | The stage's proportions on a narrow screen, e.g. "1 / 0.9". |
20
- | `title` | string | What the figure shows; also the canvas's label when alt is not given. |
21
- | `author` | string | Who made the figure: credited under it (© author), and written into an exported .glb. |
22
- | `license` | string | The terms the figure is under ("CC BY-NC-ND 4.0", "all rights reserved"): credited under it, after its author, and written into an exported .glb. |
23
- | `url` | string | Where the figure comes from: a web address (http or https), which the author's name in the credit links to. |
24
- | `alt` | string | A description of the model for screen readers. |
25
- | `style` | `"ink"` \| `"studio"` \| `"pen"` | The first look: pen (near-white, thin lines; the default), studio (realistic) or ink (drawn). |
26
- | `theme` | `"light"` \| `"dark"` \| `"blueprint"` \| `"sepia"` \| `"auto"` | The colours of the page behind the model, its lines and words (auto: light or dark, as the reader's system is set). None: each look's own. |
27
- | `env` | `"studio"` \| `"warm"` \| `"night"` | The studio look's environment. |
28
- | `view` | object | The first camera. |
29
- | `edges` | boolean | Lines where a part's faces meet at an angle: drawn in the pen look unless false; true draws them in every look. |
30
- | `check` | object | What the geometry check (lk3d check, lk3d/lint) is to excuse, by name: what the scene means on purpose. |
31
- | `ground` | boolean | A shadow under the model (true by default). |
32
- | `section` | `false` or object | The cut: a plane, or false to offer none. What lies on the side its normal points to, beyond offset along it, is cut away; a page may move it (set({ section })) |
33
- | `motions` | list of object | Parts that move together as one value goes along a range: a piston's stroke as the crank turns, a sleeve sliding back, a valve opening. Set or played by the page (fig.motion(id)) and, when named, by the reader (a slider and a play button); run through its range by the geometry check. |
34
- | `joints` | list of object | Parts posed by how they are joined, not by keys for each: a crank driven by a motion, a piston held by its rod, a rod aimed at the crank pin, a cam that follows at half speed. A joint's value comes from a motion, another joint, a rod, an aim, or the page (set({ joints })). |
35
- | `scale` | object | Honest scale: a bar that keeps its true length as the view zooms, and/or a note saying what is not to scale. |
36
- | `models` | map of name → object | glTF 2.0 models (.glb) by name, for {model: name} shapes. |
37
- | `unit` | `"mm"` \| `"cm"` \| `"dm"` \| `"m"` \| `"km"` | What one scene unit is (m): the laws of liquids and gases (g, R) are worked out in it. |
38
- | `vessels` | list of object | Parts that hold liquids or a gas: the radius of their inside at each height, and an outlet they pour through. |
39
- | `liquids` | list of object | Liquids in vessels, drawn by lk3d as bodies that fill their vessel to the level their volume gives; liquids in one vessel stack by density; an open outlet pours by Torricelli's law into the liquid below. |
40
- | `gases` | list of object | Gases under a piston: the piston rests where pV = nRT puts it (n moles at T kelvin under p pascals and the piston's weight). |
41
- | `extras` | object | The page's own data about the figure (as glTF's extras): lk3d keeps it and does not read it. |
42
- | `parts` (required) | list of object | The parts of the model, each a list of shapes with a name and a note. |
14
+ | Field | Type | Meaning |
15
+ | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16
+ | `lk3d` | `1` | The version of this format the scene is written in (1). Optional; a later engine that changes the format reads older versions. |
17
+ | `w` | number > 0 | The stage's width in proportion to h (16 by default). |
18
+ | `h` | number > 0 | The stage's height in proportion to w (10 by default). |
19
+ | `narrow` | string | The stage's proportions on a narrow screen, e.g. "1 / 0.9". |
20
+ | `title` | string | What the figure shows; also the canvas's label when alt is not given. |
21
+ | `author` | string | Who made the figure: credited under it (© author), and written into an exported .glb. |
22
+ | `license` | string | The terms the figure is under ("CC BY-NC-ND 4.0", "all rights reserved"): credited under it, after its author, and written into an exported .glb. |
23
+ | `url` | string | Where the figure comes from: a web address (http or https), which the author's name in the credit links to. |
24
+ | `alt` | string | A description of the model for screen readers. |
25
+ | `style` | `"ink"` \| `"studio"` \| `"pen"` | The first look: pen (near-white, thin lines; the default), studio (realistic) or ink (drawn). |
26
+ | `theme` | `"light"` \| `"dark"` \| `"blueprint"` \| `"sepia"` \| `"auto"` | The colours of the page behind the model, its lines and words (auto: light or dark, as the reader's system is set). None: each look's own. |
27
+ | `env` | `"studio"` \| `"warm"` \| `"night"` | The studio look's environment. |
28
+ | `view` | object | The first camera. |
29
+ | `edges` | boolean | Lines where a part's faces meet at an angle: drawn in the pen look unless false; true draws them in every look. |
30
+ | `check` | object | What the geometry check (lk3d check, lk3d/lint) is to excuse, by name: what the scene means on purpose. |
31
+ | `ground` | boolean | A shadow under the model (true by default). |
32
+ | `section` | `false` or object | The cut: a plane, or false to offer none. What lies on the side its normal points to, beyond offset along it, is cut away; while the model is cut open the reader moves the plane along its normal (dragging the cut face, or the slider) unless it is fixed, and a page may move it (set({ section })) |
33
+ | `motions` | list of object | Parts that move together as one value goes along a range: a piston's stroke as the crank turns, a sleeve sliding back, a valve opening. Set or played by the page (fig.motion(id)) and, when named, by the reader (a slider and a play button); run through its range by the geometry check. |
34
+ | `joints` | list of object | Parts posed by how they are joined, not by keys for each: a crank driven by a motion, a piston held by its rod, a rod aimed at the crank pin, a cam that follows at half speed. A joint's value comes from a motion, another joint, a rod, an aim, or the page (set({ joints })). |
35
+ | `scale` | object | Honest scale: a bar that keeps its true length as the view zooms, and/or a note saying what is not to scale. |
36
+ | `dimensions` | list of object | Dimensions drawn on the figure: lengths between points and angles at vertices, with their values, as on a technical drawing; worked out from the points as shown, so a length to a moving part changes as it moves. |
37
+ | `models` | map of name → object | glTF 2.0 models (.glb) by name, for {model: name} shapes. |
38
+ | `unit` | `"mm"` \| `"cm"` \| `"dm"` \| `"m"` \| `"km"` | What one scene unit is (m): the laws of liquids and gases (g, R) are worked out in it. |
39
+ | `vessels` | list of object | Parts that hold liquids or a gas: the radius of their inside at each height, and an outlet they pour through. |
40
+ | `liquids` | list of object | Liquids in vessels, drawn by lk3d as bodies that fill their vessel to the level their volume gives; liquids in one vessel stack by density; an open outlet pours by Torricelli's law into the liquid below. |
41
+ | `gases` | list of object | Gases under a piston: the piston rests where pV = nRT puts it (n moles at T kelvin under p pascals and the piston's weight). |
42
+ | `extras` | object | The page's own data about the figure (as glTF's extras): lk3d keeps it and does not read it. |
43
+ | `parts` (required) | list of object | The parts of the model, each a list of shapes with a name and a note. |
44
+ | `steps` | list of object | Guided steps: the figure explained in order, each with its words and a state of the figure (where the camera looks, taken apart, cut open, labels, a part chosen, motions). The figure starts at the first; the reader goes through them with Back and Next under it, the page with fig.step(). |
43
45
 
44
46
  ## Part
45
47
 
package/index.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  // (Scene, Part, Shape, Handle, Motion, Joint, …) are generated from schema/scene.schema.json into scene.d.ts and
3
3
  // re-exported from here.
4
4
 
5
- import type { Scene, Look, SceneTheme, Vec3, Color, JointFields } from './scene.js';
5
+ import type { Scene, Look, SceneTheme, Vec3, Color, JointFields, Step } from './scene.js';
6
6
  export * from './scene.js';
7
7
 
8
8
  /** the themes lk3d has by name (a scene may also say 'auto') */
@@ -68,6 +68,16 @@ export interface Strings {
68
68
  home: string;
69
69
  play: string;
70
70
  pause: string;
71
+ /** the slider that moves the cut, while it is on, and what a screen reader calls it */
72
+ cutAt: string;
73
+ cutAtLabel: string;
74
+ /** what screen readers call the list of the figure's dimensions */
75
+ dimensions: string;
76
+ /** the guided steps' panel, its buttons, and where the reader is ("{n}" and "{count}" are filled in) */
77
+ steps: string;
78
+ back: string;
79
+ next: string;
80
+ stepOf: string;
71
81
  /** the decimal mark in numbers read out (handles) */
72
82
  decimal: string;
73
83
  }
@@ -76,8 +86,15 @@ export interface MountOptions {
76
86
  /** an element for the name and note of the part pointed at, and what it says when none is */
77
87
  info?: HTMLElement;
78
88
  infoIdle?: string;
79
- /** false: no built-in buttons */
89
+ /** false: no built-in buttons (nor the steps' panel, unless `steps` says otherwise) */
80
90
  controls?: boolean;
91
+ /** false: no panel for the scene's steps under the figure (the page goes through them with fig.step) */
92
+ steps?: boolean;
93
+ /** the step the figure starts at, by its place (from 0) or id (the first); -1: before the first, the figure at its
94
+ * own start (Next goes to the first) */
95
+ step?: number | string;
96
+ /** the reader went to another step with the panel's Back or Next (not the page's own fig.step) */
97
+ onStep?: (index: number, step: Step) => void;
81
98
  style?: Look;
82
99
  theme?: string;
83
100
  labels?: Labels;
@@ -89,6 +106,8 @@ export interface MountOptions {
89
106
  onHover?: (part: BuiltPart | null) => void;
90
107
  /** a handle moved by the reader (not by the page's own set()) */
91
108
  onHandle?: (id: string, value: number) => void;
109
+ /** the cut moved by the reader, by its face or its slider (not by the page's own set()) */
110
+ onSection?: (section: { normal: Vec3; offset: number }) => void;
92
111
  /** what a screen reader says for a handle's value */
93
112
  handleText?: (id: string, value: number) => string | undefined;
94
113
  /** 'en' (default), 'vi', or any key of LK3D.locales */
@@ -266,6 +285,8 @@ export interface Figure {
266
285
  motion?: Record<string, number>;
267
286
  /** joints' values, by id, over their drives (a joint held by a rod or an aim keeps to it); each call replaces the last */
268
287
  joints?: Record<string, number>;
288
+ /** the dimensions shown, by id ([]: none), or null: the scene's own (those not hidden) */
289
+ dimensions?: string[] | null;
269
290
  }): void;
270
291
  /** a motion of the scene, to set or play */
271
292
  /** the figure as glTF 2.0 binary (.glb), posed as it is now; animate: each motion as an animation. Needs the
@@ -297,11 +318,19 @@ export interface Figure {
297
318
  readonly zoomLevel: number;
298
319
  explode(v: number): void;
299
320
  focus(ids: string[], o?: { yaw?: number; pitch?: number; ms?: number }): void;
321
+ /** the scene's guided steps */
322
+ readonly steps: Step[];
323
+ /** go to a step by its place (from 0) or id: its state glided to (ms: 0, at once); onStep is not called */
324
+ step(which: number | string, o?: { ms?: number }): void;
325
+ /** the step shown, from 0 (-1: the scene has none) */
326
+ readonly currentStep: number;
300
327
  camera(): { yaw: number; pitch: number; dist: number; target: Vec3 };
301
328
  readonly selected: string | null;
302
329
  /** choose a part (or null) without calling onPick */
303
330
  select(id: string | null): void;
304
331
  readonly labels: Labels;
332
+ /** the cut's plane now: the scene's, a step's, the page's or where the reader moved it */
333
+ readonly section: { normal: Vec3; offset: number };
305
334
  readonly style: Look;
306
335
  readonly theme: string | null;
307
336
  readonly timeScale: number;
@@ -381,3 +410,25 @@ declare const LK3D: {
381
410
  toGLB?: (scene: unknown, o?: object) => Uint8Array;
382
411
  };
383
412
  export default LK3D;
413
+
414
+ /** <lk3d-figure>: a figure as an HTML element (src="scene.json", or a JSON script inside; attributes look, theme,
415
+ * labels, step, locale, controls="false", steps="false", info="false", transparent), defined when lk3d loads */
416
+ export interface Lk3dFigureElement extends HTMLElement {
417
+ /** the figure's API, once mounted (a new one each time the element mounts it again) */
418
+ readonly figure: Figure | null;
419
+ /** resolves with the first figure, once complete */
420
+ readonly ready: Promise<Figure>;
421
+ }
422
+ /** what the element's events carry (they bubble) */
423
+ export interface Lk3dFigureEvents {
424
+ 'lk3d-pick': CustomEvent<{ id: string | null }>;
425
+ 'lk3d-handle': CustomEvent<{ id: string; value: number }>;
426
+ 'lk3d-step': CustomEvent<{ index: number; step: Step }>;
427
+ 'lk3d-section': CustomEvent<{ normal: Vec3; offset: number }>;
428
+ 'lk3d-error': CustomEvent<{ message: string }>;
429
+ }
430
+ declare global {
431
+ interface HTMLElementTagNameMap {
432
+ 'lk3d-figure': Lk3dFigureElement;
433
+ }
434
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lk3d",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "A small engine for explorable, accessible 3D diagrams built from data: take apart, cut open, label, move parts by hand",
5
5
  "keywords": [
6
6
  "3d",
@@ -64,8 +64,6 @@
64
64
  "export.d.ts",
65
65
  "validate.d.ts",
66
66
  "docs/*.md",
67
- "docs/*.png",
68
- "docs/shapes/*.png",
69
67
  "README.md",
70
68
  "LICENSE",
71
69
  "CHANGELOG.md",
@@ -90,6 +88,7 @@
90
88
  "lint": "eslint . && prettier --check .",
91
89
  "format": "prettier --write .",
92
90
  "examples": "node build.mjs && node test/visual/serve.mjs",
91
+ "playground": "node build.mjs && node test/visual/serve.mjs",
93
92
  "docs": "node docs/scene-format.mjs && node docs/shapes/render.mjs",
94
93
  "prepublishOnly": "npm run lint && npm test && npm run typecheck && npm run size",
95
94
  "prepack": "node build.mjs"
package/scene.d.ts CHANGED
@@ -109,13 +109,29 @@ export interface Scene {
109
109
  ground?: boolean;
110
110
  /**
111
111
  * The cut: a plane, or false to offer none. What lies on the side its normal points to, beyond offset along
112
- * it, is cut away; a page may move it (set({ section }))
112
+ * it, is cut away; while the model is cut open the reader moves the plane along its normal (dragging the cut
113
+ * face, or the slider) unless it is fixed, and a page may move it (set({ section }))
113
114
  */
114
115
  section?:
115
116
  | false
116
117
  | {
117
118
  normal?: Vec3;
118
119
  offset?: number;
120
+ /**
121
+ * true: the reader cannot move the cut (by dragging its face or its slider); the page still can. By default,
122
+ * while the model is cut open, the reader moves the plane along its normal.
123
+ */
124
+ fixed?: boolean;
125
+ /**
126
+ * A second plane, for a quarter cut: then only what lies beyond both planes is cut away (two planes at right
127
+ * angles take out a quarter). false: none (a step's, over the scene's).
128
+ */
129
+ second?:
130
+ | false
131
+ | {
132
+ normal?: Vec3;
133
+ offset?: number;
134
+ };
119
135
  };
120
136
  /**
121
137
  * Parts that move together as one value goes along a range: a piston's stroke as the crank turns, a sleeve
@@ -133,6 +149,11 @@ export interface Scene {
133
149
  * Honest scale: a bar that keeps its true length as the view zooms, and/or a note saying what is not to scale.
134
150
  */
135
151
  scale?: SceneScale;
152
+ /**
153
+ * Dimensions drawn on the figure: lengths between points and angles at vertices, with their values, as on a
154
+ * technical drawing; worked out from the points as shown, so a length to a moving part changes as it moves.
155
+ */
156
+ dimensions?: Dimension[];
136
157
  /** glTF 2.0 models (.glb) by name, for {model: name} shapes. */
137
158
  models?: { [key: string]: Model };
138
159
  /** What one scene unit is (m): the laws of liquids and gases (g, R) are worked out in it. */
@@ -156,6 +177,12 @@ export interface Scene {
156
177
  extras?: { [key: string]: unknown };
157
178
  /** The parts of the model, each a list of shapes with a name and a note. */
158
179
  parts: Part[];
180
+ /**
181
+ * Guided steps: the figure explained in order, each with its words and a state of the figure (where the camera
182
+ * looks, taken apart, cut open, labels, a part chosen, motions). The figure starts at the first; the reader
183
+ * goes through them with Back and Next under it, the page with fig.step().
184
+ */
185
+ steps?: Step[];
159
186
  }
160
187
 
161
188
  /** The first look: pen (near-white, thin lines; the default), studio (realistic) or ink (drawn). */
@@ -281,6 +308,65 @@ export interface SceneScaleFields {
281
308
  note?: string;
282
309
  }
283
310
 
311
+ /**
312
+ * A dimension drawn on the figure, as on a technical drawing: a length between two points (extension lines, a
313
+ * dimension line with arrows, its value), or an angle at a vertex (an arc with arrows, its value in degrees).
314
+ * Its value is worked out from the points as they are shown (in the scene's unit, when it has one), unless
315
+ * text says otherwise.
316
+ */
317
+ export type Dimension = Form<DimensionFields, 'from' | 'to'> | Form<DimensionFields, 'angle'>;
318
+
319
+ /** the fields of Dimension, each optional (Dimension says which are required, together) */
320
+ export interface DimensionFields {
321
+ /**
322
+ * Unique among the dimensions: what steps and the page name it by.
323
+ * @minLength 1
324
+ */
325
+ id?: string;
326
+ /**
327
+ * What is measured, for screen readers ("the piston's stroke").
328
+ * @minLength 1
329
+ */
330
+ name?: string;
331
+ /** A length's first end. */
332
+ from?: Point;
333
+ /** A length's other end. */
334
+ to?: Point;
335
+ /**
336
+ * Where the dimension line is drawn: the two ends moved by this much (default: on the points themselves), with
337
+ * extension lines out to it.
338
+ */
339
+ offset?: Vec3;
340
+ /** An angle: a point on one arm, the vertex, a point on the other arm. */
341
+ angle?: [Point, Point, Point];
342
+ /**
343
+ * An angle's arc radius (default: a third of the shorter arm).
344
+ * @exclusiveMinimum 0
345
+ */
346
+ radius?: number;
347
+ /** Draw an angle's arms from the vertex (false by default: they are usually edges of the model). */
348
+ arms?: boolean;
349
+ /**
350
+ * The value shown, in place of the one worked out ("Ø 40", "stroke").
351
+ * @minLength 1
352
+ */
353
+ text?: string;
354
+ /**
355
+ * Decimals in the value worked out (default: three significant figures).
356
+ * @minimum 0
357
+ * @maximum 6
358
+ * @integer
359
+ */
360
+ digits?: number;
361
+ /** Not shown unless a step or the page names it. */
362
+ hidden?: boolean;
363
+ /**
364
+ * The unit a length's value is given in (the scene's unit by default); converted from the scene's unit, which
365
+ * it needs.
366
+ */
367
+ unit?: 'mm' | 'cm' | 'dm' | 'm' | 'km';
368
+ }
369
+
284
370
  /** a model needs its .glb: data (base64) or file (a path) */
285
371
  export type Model = Form<ModelFields, 'data'> | Form<ModelFields, 'file'>;
286
372
 
@@ -479,6 +565,103 @@ export interface Part {
479
565
  extras?: { [key: string]: unknown };
480
566
  }
481
567
 
568
+ /**
569
+ * A step of the figure's explanation: its words, and the figure's state while it is shown. What a step does
570
+ * not say goes back to the figure's start (put together, not cut, see-through off, labels as usual, nothing
571
+ * hidden or chosen, the motions at their start), so a step is the same picture however the reader came to it;
572
+ * only the camera stays where the reader left it unless the step says where (view, focus).
573
+ */
574
+ export type Step = Form<StepFields, 'title'> | Form<StepFields, 'text'>;
575
+
576
+ /** the fields of Step, each optional (Step says which are required, together) */
577
+ export interface StepFields {
578
+ /**
579
+ * Unique among the steps: what the page names it by (fig.step(id)).
580
+ * @minLength 1
581
+ */
582
+ id?: string;
583
+ /**
584
+ * The step's heading, a few words.
585
+ * @minLength 1
586
+ */
587
+ title?: string;
588
+ /**
589
+ * What the reader is to look at, and why: a sentence or two, with simple formatting (b i em strong sub sup br)
590
+ * as in a part's note.
591
+ * @minLength 1
592
+ */
593
+ text?: string;
594
+ /**
595
+ * Where the camera goes: a named view (home: the figure's first), or yaw and pitch (degrees), zoom (2: twice
596
+ * as close as the whole model) or dist, and target. Without view or focus the camera stays where it is.
597
+ */
598
+ view?:
599
+ | 'front'
600
+ | 'side'
601
+ | 'top'
602
+ | 'iso'
603
+ | 'home'
604
+ | {
605
+ yaw?: number;
606
+ pitch?: number;
607
+ /** @exclusiveMinimum 0 */
608
+ zoom?: number;
609
+ /** @exclusiveMinimum 0 */
610
+ dist?: number;
611
+ target?: Vec3;
612
+ };
613
+ /**
614
+ * Parts or groups to frame: the camera looks at their middle (as they are once the step has taken them apart)
615
+ * from far enough to see them all, from the view's angles if it gives them.
616
+ */
617
+ focus?: string[];
618
+ /**
619
+ * How far apart (0, the default: put together; 1: all the way).
620
+ * @minimum 0
621
+ * @maximum 1
622
+ */
623
+ explode?: number;
624
+ /** Cut open (true), or how far the plane has swept in (0 to 1); swept in as the step comes. */
625
+ cut?: boolean | number;
626
+ /** The cut's plane for this step (the scene's section by default). */
627
+ section?: {
628
+ normal?: Vec3;
629
+ offset?: number;
630
+ /**
631
+ * A second plane, for a quarter cut: then only what lies beyond both planes is cut away (two planes at right
632
+ * angles take out a quarter). false: none (a step's, over the scene's).
633
+ */
634
+ second?:
635
+ | false
636
+ | {
637
+ normal?: Vec3;
638
+ offset?: number;
639
+ };
640
+ };
641
+ /** Casings see-through. */
642
+ xray?: boolean;
643
+ /**
644
+ * Which labels show: auto (the part pointed at or chosen, and all of them once the model is well apart; the
645
+ * default), all, none, or a list of parts and groups.
646
+ */
647
+ labels?: 'auto' | 'all' | 'none' | string[];
648
+ /** Parts or groups out of sight in this step. */
649
+ hide?: string[];
650
+ /**
651
+ * A part chosen, as if the reader had picked it: lit, with its name and note in the info box.
652
+ * @minLength 1
653
+ */
654
+ select?: string;
655
+ /** Motions' values by id (the others at their start). */
656
+ motion?: { [key: string]: number };
657
+ /** Motions played as the step comes, from the value it gives them. */
658
+ play?: string[];
659
+ /**
660
+ * The dimensions shown in this step, by id (none: [ ]); without it, the scene's own (those not hidden).
661
+ */
662
+ dimensions?: string[];
663
+ }
664
+
482
665
  /** Parts that move one way: moved, turned, or both (moved, then turned). */
483
666
  export type MotionTrack = Form<MotionTrackFields, 'move'> | Form<MotionTrackFields, 'turn'>;
484
667
 
@@ -498,6 +681,22 @@ export interface MotionTrackFields {
498
681
  ease?: boolean;
499
682
  }
500
683
 
684
+ /**
685
+ * A point of the scene, [x, y, z], or one carried by a part, {part, at}: it moves as the part does (taken
686
+ * apart, moved by a motion or a handle), so what is measured to it is measured as shown.
687
+ */
688
+ export type Point =
689
+ | Vec3
690
+ | {
691
+ /**
692
+ * The part that carries it.
693
+ * @minLength 1
694
+ */
695
+ part: string;
696
+ /** The point, in the part's own place at rest. */
697
+ at: Vec3;
698
+ };
699
+
501
700
  /**
502
701
  * How it reflects light in the studio look (and how much light wraps round into it, for soft materials).
503
702
  */