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.
- package/CHANGELOG.md +59 -0
- package/README.md +28 -7
- package/bin/lk3d.mjs +24 -13
- package/dist/lk3d-export.min.js +1 -1
- package/dist/lk3d.min.js +73 -35
- package/dist/lk3d.mjs +72 -34
- package/docs/api.md +132 -51
- package/docs/design.md +12 -7
- package/docs/handles-and-lines.md +27 -0
- package/docs/performance.md +42 -10
- package/docs/scene-format.md +31 -29
- package/index.d.ts +53 -2
- package/package.json +2 -3
- package/scene.d.ts +200 -1
- package/schema/scene.schema.json +329 -1
- package/skill/lk3d/SKILL.md +14 -1
- package/src/ao.js +58 -0
- package/src/controls.js +21 -2
- package/src/element.js +111 -0
- package/src/figure/api.js +18 -3
- package/src/figure/camera.js +57 -9
- package/src/figure/context.d.ts +37 -2
- package/src/figure/dimensions.js +140 -0
- package/src/figure/idle.js +57 -19
- package/src/figure/input.js +105 -7
- package/src/figure/labels.js +26 -8
- package/src/figure/loop.js +8 -2
- package/src/figure/pick.js +24 -8
- package/src/figure/steps.js +144 -0
- package/src/flow.js +33 -2
- package/src/index.js +16 -2
- package/src/locales/en.js +7 -0
- package/src/locales/vi.js +7 -0
- package/src/renderer-gl.js +88 -16
- package/src/shaders.js +63 -17
- package/src/stylesheet.js +14 -4
- package/src/validate.js +89 -0
- package/docs/flow.png +0 -0
- package/docs/generator.png +0 -0
- package/docs/pen-blueprint.png +0 -0
- package/docs/pen-dark.png +0 -0
- package/docs/pen-ortho.png +0 -0
- package/docs/shapes/blade.png +0 -0
- package/docs/shapes/blob.png +0 -0
- package/docs/shapes/box.png +0 -0
- package/docs/shapes/capsule.png +0 -0
- package/docs/shapes/cylinder.png +0 -0
- package/docs/shapes/dna.png +0 -0
- package/docs/shapes/ellipsoid.png +0 -0
- package/docs/shapes/extrude.png +0 -0
- package/docs/shapes/helix.png +0 -0
- package/docs/shapes/lathe.png +0 -0
- package/docs/shapes/loop.png +0 -0
- package/docs/shapes/molecule.png +0 -0
- package/docs/shapes/orbit.png +0 -0
- package/docs/shapes/ring.png +0 -0
- package/docs/shapes/scatter.png +0 -0
- package/docs/shapes/shell.png +0 -0
- package/docs/shapes/sphere.png +0 -0
- package/docs/shapes/terrain.png +0 -0
- package/docs/shapes/torus.png +0 -0
- package/docs/shapes/tree.png +0 -0
- package/docs/shapes/tube.png +0 -0
package/docs/performance.md
CHANGED
|
@@ -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
|
|
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`,
|
|
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
|
|
44
|
-
|
|
45
|
-
|
|
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
|
|
68
|
-
CPU on the molecules at 6×),
|
|
69
|
-
|
|
70
|
-
|
|
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
|
package/docs/scene-format.md
CHANGED
|
@@ -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
|
-
| `
|
|
37
|
-
| `
|
|
38
|
-
| `
|
|
39
|
-
| `
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
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
|
|
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;
|
|
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
|
*/
|