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/api.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# API
|
|
2
2
|
|
|
3
3
|
```js
|
|
4
|
-
// a page: one script tag, the global LK3D (https://unpkg.com/lk3d@0.1
|
|
5
|
-
<script src="https://unpkg.com/lk3d@0.1
|
|
4
|
+
// a page: one script tag, the global LK3D (https://unpkg.com/lk3d@0.2.1/dist/lk3d.min.js, or a copy of dist/lk3d.min.js)
|
|
5
|
+
<script src="https://unpkg.com/lk3d@0.2.1/dist/lk3d.min.js"></script>;
|
|
6
6
|
// or a module
|
|
7
7
|
import LK3D, { mount, build, defaults, locales } from 'lk3d';
|
|
8
8
|
```
|
|
@@ -16,25 +16,29 @@ the part's name and note, not what the pointer passes over), and every named par
|
|
|
16
16
|
list after the figure (not drawn on the page). Every handle is also a range input for the keyboard and screen
|
|
17
17
|
readers.
|
|
18
18
|
|
|
19
|
-
| Option
|
|
20
|
-
|
|
|
21
|
-
| `info`, `infoIdle`
|
|
22
|
-
| `controls`
|
|
23
|
-
| `
|
|
24
|
-
| `
|
|
25
|
-
| `
|
|
26
|
-
| `
|
|
27
|
-
| `
|
|
28
|
-
| `
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
| `
|
|
32
|
-
| `
|
|
33
|
-
| `
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
| `
|
|
37
|
-
| `
|
|
19
|
+
| Option | Default | Meaning |
|
|
20
|
+
| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| `info`, `infoIdle` | | an element that shows the name and note of the part pointed at (only `b i em strong sub sup br` kept as HTML; the rest as text); what it says when none is |
|
|
22
|
+
| `controls` | `true` | `false`: no built-in buttons (build your own with the figure's methods) |
|
|
23
|
+
| `steps` | `controls` | `false`: no panel for the scene's [guided steps](#guided-steps) under the figure (the page goes through them with `step()`) |
|
|
24
|
+
| `step` | `0` | the step the figure starts at, by its place (from 0) or id; `-1`: before the first, the figure at its own start |
|
|
25
|
+
| `onSection({normal, offset})` | | the cut moved by the reader, by dragging its face or by its slider (not by the page's own `set()`) |
|
|
26
|
+
| `onStep(index, step)` | | the reader went to another step with the panel's Back or Next (not the page's own `step()`) |
|
|
27
|
+
| `style` | scene's, else `'pen'` | the first look: `'pen'`, `'studio'` or `'ink'` |
|
|
28
|
+
| `theme` | scene's, else none | the colours: `'light'`, `'dark'`, `'blueprint'`, `'sepia'`, `'auto'`, or a name added to `LK3D.themes` |
|
|
29
|
+
| `labels` | `'auto'` | `'auto'` (on hover and when taken apart), `'all'`, `'none'`, or `[ids or groups]`: exactly those parts' labels |
|
|
30
|
+
| `transparent` | `false` | `true`: nothing painted behind the model, in any look and theme (the canvas is clear; the theme's lines, solids and words still apply) |
|
|
31
|
+
| `onPick(part)` | | a part chosen by the reader (a tap, a click, a handle reached by Tab), or `null` when they let it go; a part is `{ id, name, note, group, min, max, center, triangleCount }` (its box's corners and middle in the scene) |
|
|
32
|
+
| `onHover(part)` | | the part under the pointer as it moves onto one, or `null` as it moves off |
|
|
33
|
+
| `onHandle(id, value)` | | a handle moved by the reader (not by the page's own `handle(id).set`) |
|
|
34
|
+
| `handleText(id, value)` | | what a screen reader says for a handle's value, e.g. `` `d = ${v} cm` `` |
|
|
35
|
+
| `locale`, `strings` | `'en'` | the language of the built-in words (`'en'`, `'vi'`, or any key of `LK3D.locales`); single words changed |
|
|
36
|
+
| `buttonClass` | lk3d's own | the page's class for the built-in buttons |
|
|
37
|
+
| `quality` | 1 (0.6 on small screens) | shape detail |
|
|
38
|
+
| `maxTriangles` | 1 million or 10 million | the most triangles the scene may have here: 1 million where memory is small (a screen under 700 px a side, or `navigator.deviceMemory` under 4 GB), else 10 million (2 million a part); over it, the scene is built coarser, down to a quarter of `quality`, else refused |
|
|
39
|
+
| `validate` | the engine's guard | the full rules to check the scene by before it is built: `validate` from `lk3d/validate`; its first problem is thrown |
|
|
40
|
+
| `maxDpr`, `adaptive`, `ao` | 3, `true`, `true` | the highest pixel density; lowering resolution while frames run late; crease shading |
|
|
41
|
+
| `force2d`, `webgl1` | | for testing: the Canvas 2D fallback, or WebGL 1 |
|
|
38
42
|
|
|
39
43
|
`LK3D.defaults` (`locale`, `strings`, `buttonClass`) sets these for every figure on a page.
|
|
40
44
|
|
|
@@ -58,37 +62,110 @@ try {
|
|
|
58
62
|
|
|
59
63
|
## The figure
|
|
60
64
|
|
|
61
|
-
|
|
|
62
|
-
|
|
|
63
|
-
| `set({ spin, explode, cut, section, xray, labels, style, theme, transparent, timeScale, projection, camera, glow, hide, move, joints })` | the spin angle (degrees) of parts with `spin`; how far apart (0 to 1); the cut (`true`, or 0 to 1: how far the plane has swept in, from just outside the model to the section); `section: {normal, offset}` moves the cut's plane; see-through casings; labels (`'auto'`, `'all'`, `'none'` or `[ids or groups]`); the look; the theme (`null`: none); no page behind the model; how fast particles and flows run (1; 0.2 for slow motion); `'perspective'` or `'ortho'`; `camera: {yaw, pitch, dist or zoom, target}`, placed at once (a gliding view stops); `glow: {id: 0..1}`; `hide: [ids or groups]`; `move: {id: [x, y, z]}` (a part moved by that much); `joints: {id: value}` (joints' values over their drives; each call replaces the last, so a joint left out follows its drive again; [joints](handles-and-lines.md#joints-parts-posed-by-how-they-are-joined)) |
|
|
64
|
-
| `view(name or [yaw, pitch] or {yaw, pitch, dist, zoom, target}, {ms})`
|
|
65
|
-
| `zoom(factor, x, y)`, `zoomLevel`
|
|
66
|
-
| `focus([ids or groups], {yaw, pitch, ms})`
|
|
67
|
-
| `
|
|
68
|
-
| `
|
|
69
|
-
| `
|
|
70
|
-
| `
|
|
71
|
-
| `
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
65
|
+
| | |
|
|
66
|
+
| ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
67
|
+
| `set({ spin, explode, cut, section, xray, labels, style, theme, transparent, timeScale, projection, camera, glow, hide, move, joints, dimensions })` | the spin angle (degrees) of parts with `spin`; how far apart (0 to 1); the cut (`true`, or 0 to 1: how far the plane has swept in, from just outside the model to the section); `section: {normal, offset, second}` moves the cut's plane (`second: {normal, offset}` a second plane for a quarter cut, only what lies beyond both cut away; `second: null` none); see-through casings; labels (`'auto'`, `'all'`, `'none'` or `[ids or groups]`); the look; the theme (`null`: none); no page behind the model; how fast particles and flows run (1; 0.2 for slow motion); `'perspective'` or `'ortho'`; `camera: {yaw, pitch, dist or zoom, target}`, placed at once (a gliding view stops); `glow: {id: 0..1}`; `hide: [ids or groups]`; `move: {id: [x, y, z]}` (a part moved by that much); `joints: {id: value}` (joints' values over their drives; each call replaces the last, so a joint left out follows its drive again; [joints](handles-and-lines.md#joints-parts-posed-by-how-they-are-joined)); `dimensions: [ids]` (the dimensions shown; `[]` none, `null` the scene's own: [dimensions](handles-and-lines.md#dimensions)) |
|
|
68
|
+
| `view(name or [yaw, pitch] or {yaw, pitch, dist, zoom, target}, {ms})` | glide the camera: `'front'`, `'side'`, `'top'`, `'iso'`, `'home'`; `zoom`: how close (2: twice as close as the whole model); `ms`: how long the glide takes (600; 0: at once) |
|
|
69
|
+
| `zoom(factor, x, y)`, `zoomLevel` | zoom by a factor towards a point of the stage (what is under it stays under it), as the wheel and a pinch do; how close the view is (the scene's `view.minZoom`, 0.02 by default, is the limit: 50 times closer) |
|
|
70
|
+
| `focus([ids or groups], {yaw, pitch, ms})` | frame those parts |
|
|
71
|
+
| `step(index or id, {ms})`, `currentStep`, `steps` | go to one of the scene's [guided steps](#guided-steps), gliding there (`ms: 0`: at once), without calling `onStep`; the step shown (from 0; `-1` for none); the scene's steps |
|
|
72
|
+
| `explode(0 or 1)` | take apart or put together, animated |
|
|
73
|
+
| `camera()` | `{yaw, pitch, dist, target}` (degrees, scene units) |
|
|
74
|
+
| `select(id or null)`, `selected` | choose a part (lit, its note shown) without calling `onPick`; the part chosen |
|
|
75
|
+
| `section` | the cut's plane now, `{normal, offset}`: the scene's, a step's, the page's, or where the reader moved it |
|
|
76
|
+
| `labels`, `style`, `theme`, `timeScale`, `renderer`, `hifi`, `parts` | the labels, look, theme and time scale in use; `'webgl2'`, `'webgl1'` or `'2d'`; the studio look's full lighting; the parts as built |
|
|
77
|
+
| `handle(id)` | `{ value, set(v) }` for a part with a handle ([handles](handles-and-lines.md)) |
|
|
78
|
+
| `motion(id)` | `{ value, playing, set(v), play(), stop() }` for a motion of the scene; `set({ motion: { id: value } })` sets several ([motions](handles-and-lines.md#motions-parts-that-move-together)) |
|
|
79
|
+
| `exportGLB({ animate, samples })` | the figure as glTF 2.0 binary (`Uint8Array`), posed as it is now; `animate`: each motion as an animation ([exporting](handles-and-lines.md#exporting-gltf)); needs the exporter, a script of its own |
|
|
80
|
+
| `liquid(id)`, `vessel(id)`, `gas(id)` | a liquid (`{ volume, level, set({volume}) }`), a vessel (`{ open, flow, set({open}) }`), a gas (`{ height, n, T, set({n, T, p, mass}) }`) ([liquids and gases](fluids.md)) |
|
|
81
|
+
| `plume({at, height, radius})` | warm air or smoke rising from `at` as a buoyant plume: a stream that widens and slows as one does |
|
|
82
|
+
| `lines({ count, radius, color, studioColor, glow })` | rods between points: `.set(k, a, b, r)` (segment k from a to b, its own radius r if given; `set(k, null)` hides it), `.clear()`, `.glow(v)`, `.remove()`; `.radius` and `.visible` (setting one draws again) |
|
|
83
|
+
| `flow({ path or paths, count, speed, amount, length, width, spread, ramp, part, closed })` | streaks of air, water or blood along paths, coloured by a ramp along them (also `opacity`): `.speed`, `.amount` (the share drawn), `.visible`, `.set({…})`, `.remove()` ([flow](handles-and-lines.md#flow)) |
|
|
84
|
+
| `stream({ path, radius, speed, speeds, fade, density, turbulence, swirl, ramp })` | air or gas as a moving volume along a path (a jet, an intake): `.speed`, `.density`, `.visible`, `.set({…})`, `.remove()` ([streams](handles-and-lines.md#streams)) |
|
|
85
|
+
| `particles({ path, count, color, size, part, closed })` | dots running along a path at `.speed` (negative: backwards); `part`: in that part's coordinates, so they move with it |
|
|
86
|
+
| `particles({ count, radius, colors })` | solid balls the page places: write `.positionsAndColors` (x, y, z, and 0..1 picking one of three colours), add 1 to `.version`, call `redraw()`; `.resize(n)` |
|
|
87
|
+
| `tick(fn)` | call `fn(now)` every frame while it returns true (`now`: the clock's milliseconds); returns a function that removes it |
|
|
88
|
+
| `ready` | a promise, resolved with the figure once it is complete: the first picture, the crease shading, every texture (for screenshots, print and tools) |
|
|
89
|
+
| `redraw()`, `pick(x, y)`, `refreshMs` | ask for a frame; the part under a point of the canvas; this screen's frame interval |
|
|
90
|
+
| `drawNow()` | draw the state as it is now, before returning (a tool that takes a picture right after setting it); `false` while the shaders are still compiling (await `ready` first) |
|
|
91
|
+
| `project([x, y, z], id)` | where a point of the scene is on the stage, `[x, y]` in CSS pixels from its top left, or `null` behind the eye; with a part's `id`, a point of that part as it is placed now (taken apart, moved, turned): for a page's own labels |
|
|
92
|
+
| `stats()` | what drawing costs here: setup, first picture, trees, crease shading (ms), triangles, resolution, textures still decoding, GPU |
|
|
93
|
+
| `destroy()` | take the figure down: timers, listeners and the GPU context released |
|
|
88
94
|
|
|
89
95
|
The figure draws only when something changes and pauses while it is off screen. A page's own simulation is better on
|
|
90
96
|
its own `requestAnimationFrame`, telling the figure the new state with `set` and `redraw`.
|
|
91
97
|
|
|
98
|
+
## The element: `<lk3d-figure>`
|
|
99
|
+
|
|
100
|
+
The same script defines an HTML element for a page that writes no script of its own (Markdown, a content system, a
|
|
101
|
+
framework's template): a figure where the element is, with its controls, and a line under it with the name and note
|
|
102
|
+
of the part pointed at.
|
|
103
|
+
|
|
104
|
+
```html
|
|
105
|
+
<lk3d-figure src="generator.json" look="studio" locale="vi" step="rotor"></lk3d-figure>
|
|
106
|
+
|
|
107
|
+
<lk3d-figure labels="all">
|
|
108
|
+
<script type="application/json">
|
|
109
|
+
{ "title": "A bolt and a nut", "parts": [ … ] }
|
|
110
|
+
</script>
|
|
111
|
+
</lk3d-figure>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
| Attribute | Meaning |
|
|
115
|
+
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| `src` | the scene's address (JSON); without it, a `<script type="application/json">` inside the element |
|
|
117
|
+
| `look`, `theme`, `labels`, `step` | the look, the theme, which labels show, the guided step (its place from 0, or its id): set as they change |
|
|
118
|
+
| `locale`, `controls="false"`, `steps="false"`, `info="false"`, `transparent` | the words; no buttons; no steps' panel; no line for the part's name and note; nothing painted behind (the figure is mounted again as they change) |
|
|
119
|
+
|
|
120
|
+
`element.figure` is the figure's API ([above](#the-figure); a new one each time the element mounts it again) and
|
|
121
|
+
`element.ready` resolves with the first, once complete. The reader's moves come as events that bubble:
|
|
122
|
+
`lk3d-pick` (`{ id }`), `lk3d-handle` (`{ id, value }`), `lk3d-step` (`{ index, step }`), `lk3d-section`
|
|
123
|
+
(`{ normal, offset }`). A scene that cannot be fetched, read or drawn shows its problem in the element and sends
|
|
124
|
+
`lk3d-error` (`{ message }`). Taken out of the page, the element destroys its figure; put back, it draws it again.
|
|
125
|
+
|
|
126
|
+
## Guided steps
|
|
127
|
+
|
|
128
|
+
A scene's `steps` ([format](scene-format.md)) explain the figure in order. Each has its words (a `title`, `text`, or
|
|
129
|
+
both) and the state of the figure while it is shown: where the camera goes (`view`, `focus`), how far apart
|
|
130
|
+
(`explode`), the cut (`cut`, `section`), see-through (`xray`), which `labels` show, parts hidden (`hide`), a part
|
|
131
|
+
chosen (`select`), the motions' values (`motion`) and which play (`play`).
|
|
132
|
+
|
|
133
|
+
```json
|
|
134
|
+
"steps": [
|
|
135
|
+
{ "id": "whole", "title": "An AC generator", "text": "Turn the rotor and a current lights the lamp.", "view": "home" },
|
|
136
|
+
{ "id": "rotor", "title": "The rotor", "text": "Cut open: magnets turn inside the coils.", "cut": true,
|
|
137
|
+
"labels": ["magnet-n", "magnet-s"], "view": { "yaw": -20, "pitch": 16 } },
|
|
138
|
+
{ "id": "circuit", "title": "The circuit", "text": "Each half-turn turns the current round.",
|
|
139
|
+
"focus": ["circuit"], "select": "filament" }
|
|
140
|
+
]
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
The figure starts at the first step (or `opts.step`), and a panel under it shows the step's words with Back and Next;
|
|
144
|
+
its words are said aloud as the reader comes to each. Going to a step sets everything it describes, and what it leaves
|
|
145
|
+
out goes back to the figure's start: put together, not cut, see-through off, labels as `opts.labels` says, nothing
|
|
146
|
+
hidden or chosen, every motion at its start and stopped. So a step is the same picture however the reader came to it,
|
|
147
|
+
by Next, by Back or straight from the page. The camera is the exception: it moves only when the step gives a `view`
|
|
148
|
+
or parts to `focus` on, so a step that only changes what is shown leaves the reader's view alone. `focus` frames the
|
|
149
|
+
parts as they will be once the step has taken them apart, from the view's angles if it gives them. The explode, the
|
|
150
|
+
cut and the camera glide there together (at once when the reader asked for reduced motion). In between, the reader
|
|
151
|
+
explores as usual; the next step sets its own state again.
|
|
152
|
+
|
|
153
|
+
A page can go through the steps itself instead, say as the reader scrolls through its own text, with the panel left
|
|
154
|
+
out:
|
|
155
|
+
|
|
156
|
+
```js
|
|
157
|
+
const fig = LK3D.mount(el, scene, { steps: false });
|
|
158
|
+
for (const section of document.querySelectorAll('[data-step]'))
|
|
159
|
+
new IntersectionObserver(([entry]) => entry.isIntersecting && fig.step(section.dataset.step), {
|
|
160
|
+
threshold: 0.6,
|
|
161
|
+
}).observe(section);
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
`lk3d check` checks that what each step names exists (parts and groups, motions within their range), that a labelled
|
|
165
|
+
part has a label and is not hidden by the same step, and that a step cuts only where the scene offers a cut; `lk3d
|
|
166
|
+
render` draws each step as a picture of its own (`--poses steps`, with the others by default when the scene has
|
|
167
|
+
steps).
|
|
168
|
+
|
|
92
169
|
## Driving a figure from a timeline
|
|
93
170
|
|
|
94
171
|
A page whose every frame is a function of its own time `t` (a video renderer that seeks to any time and takes a
|
|
@@ -154,11 +231,13 @@ and the exporter apart: `lk3d/export` (lk3d with `fig.exportGLB()` working, and
|
|
|
154
231
|
| presses `+` or `=`, `-` | zooms in, out |
|
|
155
232
|
| presses Page Down, Page Up (canvas focused) | chooses the next, the previous named part on show (as a click: `onPick`, lit, its note shown and said); Escape lets it go |
|
|
156
233
|
| Tabs to a handle | reaches its range input: arrow keys, Page Up and Page Down move it |
|
|
234
|
+
| drags the cut face (the model cut open) | moves the cut along its normal, held within the parts it cuts (seen face on, up and down move it); the view stays; a tap chooses the part (`onSection`; not when the scene's `section` is `fixed`) |
|
|
157
235
|
|
|
158
236
|
Zoom stops at `view.minZoom` of the distance that fits the whole model (0.02: 50 times closer) and at three times that
|
|
159
237
|
distance going out. The built-in controls under the figure (each where the scene has a use for it) take it apart (a
|
|
160
|
-
slider and a button), cut it open,
|
|
161
|
-
|
|
238
|
+
slider and a button), cut it open (and, while it is, move the cut: a slider, the keys' way to do what dragging the
|
|
239
|
+
cut face does), see through, show all labels, go round the looks, glide to the views (front, side, top, home), and
|
|
240
|
+
give each named motion a slider and a play button. Labels whose place the cut has passed are not shown.
|
|
162
241
|
|
|
163
242
|
## The command line
|
|
164
243
|
|
|
@@ -186,4 +265,6 @@ runs. Flags go anywhere on the line.
|
|
|
186
265
|
Without a [theme](looks-and-materials.md#themes) (which sets them on the stage itself), the figure's colours and
|
|
187
266
|
lettering come from CSS variables a page sets on `:root` or any element around the figure:
|
|
188
267
|
`--lk3d-ink`, `--lk3d-paper`, `--lk3d-muted`, `--lk3d-accent` (focus), `--lk3d-warn` (the scale note),
|
|
189
|
-
`--lk3d-highlight` (pressed buttons)
|
|
268
|
+
`--lk3d-highlight` (pressed buttons) and `--lk3d-highlight-ink` (their words: dark by default, for the light
|
|
269
|
+
highlight; a page whose highlight is dark sets it light), `--lk3d-font` (labels in the drawn look). Printed, the
|
|
270
|
+
figure keeps its picture and a step's words, without the buttons and the hint.
|
package/docs/design.md
CHANGED
|
@@ -19,17 +19,19 @@ lk3d is about 8 000 lines of plain JavaScript (ES modules, no dependencies). Thi
|
|
|
19
19
|
| `src/figure/labels.js` | labels and leader lines (measured once, moved with transforms), the scale bar |
|
|
20
20
|
| `src/figure/pick.js` | picking: a ray through the stage against each part's bounding-volume trees |
|
|
21
21
|
| `src/figure/idle.js` | the work done in idle slices after the first picture (the trees, crease shading, edges) and `ready` |
|
|
22
|
-
| `src/figure/input.js` | the pointer, wheel and keys; handles grabbed and dragged, and each as a range input
|
|
22
|
+
| `src/figure/input.js` | the pointer, wheel and keys; handles grabbed and dragged, and each as a range input; the cut face dragged |
|
|
23
23
|
| `src/figure/additions.js`, `src/figure/api.js` | what a page adds (particles, flows, streams, lines); the figure's API |
|
|
24
|
+
| `src/figure/steps.js` | guided steps: going to one (everything it describes set, the rest back at the start; the cut swept in, the camera framing what it focuses on), and the panel of words with Back and Next |
|
|
24
25
|
| `src/geometry.js` | `Mesh` (positions, normals, indices, optional vertex colours and texture coordinates), the shapes for machines (lathe, cylinder, box, sphere, torus, tube, helix, loop), placement and repeats, `buildScene` (parts → batches), materials |
|
|
25
26
|
| `src/science.js` | the shapes for the sciences: ellipsoid, capsule, blob, shell, tree, molecule, dna, extrude, terrain, ring, orbit, blade, and a seeded random generator |
|
|
26
27
|
| `src/gltf.js` | reading `.glb` models (synchronously, from base64): nodes, quantized attributes, colours, texture coordinates and maps |
|
|
27
28
|
| `src/gltf-write.js` | writing a figure out as `.glb`: a node, mesh and material for each part, posed as shown, and each motion as an animation when asked |
|
|
28
29
|
| `src/export.js`, `src/export-script.js` | the exporter apart from the engine: `lk3d/export` (the module, with lk3d) and `dist/lk3d-export.min.js` (the script) |
|
|
29
|
-
| `src/flow.js` | streaks along paths: their geometry each frame (seeded, so pictures repeat)
|
|
30
|
+
| `src/flow.js` | streaks along paths: placed on the GPU on WebGL 2 from their paths and fixed numbers (gpuData), elsewhere their geometry each frame (seeded, so pictures repeat); the colour ramps, and the path measure particles share |
|
|
30
31
|
| `src/renderer-gl.js`, `src/shaders.js` | the WebGL 2 and WebGL 1 renderer and its shaders (written once, compiled as GLSL ES 1.00 or 3.00) |
|
|
31
32
|
| `src/renderer-2d.js` | the Canvas 2D fallback |
|
|
32
33
|
| `src/bvh.js` | bounding-volume trees: picking and ambient occlusion by rays on the CPU |
|
|
34
|
+
| `src/ao.js` | the crease shading worked out in a Web Worker made of lk3d's own script (the page's one worker; the same script, marked, answers its jobs), or nowhere, where none can be made |
|
|
33
35
|
| `src/math.js` | small vector and 4×4 matrix helpers (column-major, as WebGL wants them), colours |
|
|
34
36
|
| `src/changed.js` | whether what something was made from has changed since (values compared without garbage): a part's matrix, groups of parts alike, the shadow map, the liquids' bodies |
|
|
35
37
|
| `src/handles.js` | the handle maths: a pointer ray to an angle, a distance or a place along a path (pure, tested in Node) |
|
|
@@ -43,6 +45,7 @@ lk3d is about 8 000 lines of plain JavaScript (ES modules, no dependencies). Thi
|
|
|
43
45
|
| `index.d.ts`, `scene.d.ts`, `scripts/types.mjs`, `tsconfig.json` | the TypeScript types: the page API by hand (`index.d.ts`), the scene's types generated from the schema (`scene.d.ts`, by `scripts/types.mjs`: `npm run types`); the sources are type-checked as JavaScript against them (`tsconfig.json`) |
|
|
44
46
|
| `build.mjs` | the bundle (esbuild), with the shaders' GLSL squeezed (comments and spaces out, line breaks kept) and the context's fields renamed short |
|
|
45
47
|
| `bin/lk3d.mjs` | the command line: `lk3d check`, `lk3d render` (the built engine in a headless browser) and `lk3d export` |
|
|
48
|
+
| `playground/` | the playground: an editor and the live figure (playground.js), the checks in a worker (check.js: lk3d/validate and lk3d/lint), each problem's place in the text (locate.js); published on GitHub Pages by `.github/workflows/pages.yml` |
|
|
46
49
|
|
|
47
50
|
## A mounted figure
|
|
48
51
|
|
|
@@ -88,7 +91,7 @@ renderer = { kind: 'webgl2' | 'webgl1' | '2d', hifi, shadows, parallel,
|
|
|
88
91
|
A frame (WebGL 2, studio look): the shadow map (drawn again only when something that casts a shadow moves, the cut
|
|
89
92
|
changes or lines move, not when the camera turns); the outline; the solid parts; the ground's shadow; solid
|
|
90
93
|
particles; see-through parts far to near (glass that refracts samples a copy of the picture made just before); the
|
|
91
|
-
pen look's edges; path particles; flow streaks (ribbons widened on screen in the vertex shader, inked over a light page
|
|
94
|
+
pen look's edges; path particles; flow streaks (ribbons placed and widened on screen in the vertex shader, inked over a light page
|
|
92
95
|
or added to a dark one); streams (the solid parts' depth, drawn again only when they or the camera move; each stream,
|
|
93
96
|
far to near, marched once per pixel from its hull's farthest face into a half-size picture, put over the page); the
|
|
94
97
|
glow (emission at half resolution, blurred at a quarter, added). Every look has one sun, fixed in the scene: it shades the
|
|
@@ -137,7 +140,7 @@ Liquids and gases are shaped again only when a volume or a height changed.
|
|
|
137
140
|
Labels are HTML, measured once (canvas text metrics, cached, measured again when web fonts arrive) and moved with
|
|
138
141
|
transforms, so a frame never forces the page to lay itself out. Picking casts a ray on the CPU against each batch's
|
|
139
142
|
bounding-volume tree (built in idle slices just after the first picture) instead of reading a pixel back from the GPU.
|
|
140
|
-
Ambient occlusion is computed the same way, a
|
|
143
|
+
Ambient occlusion is computed the same way, by rays against each shape's tree, in a Web Worker (ao.js; on the page in idle slices where there is none), then uploaded.
|
|
141
144
|
|
|
142
145
|
## Handles
|
|
143
146
|
|
|
@@ -160,7 +163,7 @@ environments the engine draws.
|
|
|
160
163
|
instancing, picking against brute force), glTF reading and writing, handle maths, motions and joints, liquids and gases,
|
|
161
164
|
the validator and the geometry check against planted mistakes, the command line, the skill, the locales. `npm run
|
|
162
165
|
typecheck`: the sources (as JavaScript, against the types), the types, and every reference and example scene against
|
|
163
|
-
them. `npm run size`: the
|
|
166
|
+
them. `npm run size`: the 67 KB budget. `npm run test:visual`: 18 reference scenes in their looks
|
|
164
167
|
(some also in the 2D fallback, a theme or the orthographic camera) and the page API, compared with stored pictures
|
|
165
168
|
(`test/visual/`). Pictures are stored per browser and platform: Chromium and Firefox on macOS, and Chromium, Firefox
|
|
166
169
|
and WebKit on Linux (the CI workflow's). WebKit is skipped on macOS 14 and older (Playwright cannot drive it there).
|
|
@@ -179,8 +182,10 @@ schema makes.
|
|
|
179
182
|
a slider and a play button under the figure; liquids pouring and gases settling by their laws) or driven by the page
|
|
180
183
|
(spin, glow, particles, moved parts, a motion's value). There is no general physics engine; a page that simulates
|
|
181
184
|
writes its own model.
|
|
182
|
-
- The cut is one plane
|
|
183
|
-
(`set({ section, cut })`)
|
|
185
|
+
- The cut is one plane, or two for a quarter cut: the scene's (`section`), which the reader moves along its normal (dragging the cut
|
|
186
|
+
face, or its slider) and a page can move, turn or sweep through the model (`set({ section, cut })`). A second plane
|
|
187
|
+
(`section.second`) makes a quarter cut: only what lies beyond both is cut away; the reader drags either face. The
|
|
188
|
+
reader cannot turn a plane.
|
|
184
189
|
- Ambient occlusion is computed per part (a part's own creases and hollows), not between parts.
|
|
185
190
|
- The 2D fallback has no section view (its button is not offered) and no shadows, and draws balls without sorting them
|
|
186
191
|
by depth; WebGL 1 has no cast shadows, no glow halo, no surface detail, refraction or textures.
|
|
@@ -245,3 +245,30 @@ fig.drawNow();
|
|
|
245
245
|
Their time starts at 0, or where the clock last ran. When a speed changes, the thing goes on from where it was last
|
|
246
246
|
drawn at its new speed; a timeline that changes speeds as it goes seeks in order, as an export does, to draw the same
|
|
247
247
|
picture each time. No re-simulation is needed: their places follow from their seeds and the distance travelled.
|
|
248
|
+
|
|
249
|
+
## Dimensions
|
|
250
|
+
|
|
251
|
+
A scene's `dimensions` are drawn on the figure as on a technical drawing: a **length** between two points, with
|
|
252
|
+
extension lines out to a dimension line, arrows at its ends and its value; an **angle** at a vertex, an arc with arrows
|
|
253
|
+
and its value in degrees.
|
|
254
|
+
|
|
255
|
+
```json
|
|
256
|
+
"unit": "dm",
|
|
257
|
+
"dimensions": [
|
|
258
|
+
{ "id": "d", "name": "the object's distance", "from": { "part": "object", "at": [-4.5, 0, 0] }, "to": [0, 0, 0],
|
|
259
|
+
"offset": [0, -0.3, 0.5], "unit": "cm", "digits": 0 },
|
|
260
|
+
{ "id": "tilt", "angle": [[1, 0, 0], [0, 0, 0], [0.8, 0.6, 0]], "radius": 0.4 }
|
|
261
|
+
]
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
- **The value** is worked out from the points as they are shown, three significant figures by default (`digits` for a
|
|
265
|
+
fixed number of decimals), in the scene's `unit`, or converted to the dimension's own (`unit: "cm"` in a scene in
|
|
266
|
+
decimetres); an angle in degrees. `text` gives words of its own instead (`"Ø 40"`).
|
|
267
|
+
- **A point on a part**, `{part, at}` (`at` where it is with the part at rest), moves with the part: taken apart, moved
|
|
268
|
+
by a motion or a joint, or by the reader's handle. A length to it changes as it moves: the lens bench's distance from
|
|
269
|
+
the object to the lens follows the object as the reader slides it ([example](../examples/lens.html)).
|
|
270
|
+
- **Where the line goes**: `offset` moves the dimension line off the points, extension lines reaching out to it. An
|
|
271
|
+
angle's arc is a third of its shorter arm from the vertex unless `radius` says; `arms: true` draws the arms too.
|
|
272
|
+
- **Which show**: every dimension the scene does not mark `hidden`; a step shows exactly the ones it names
|
|
273
|
+
(`dimensions: ["d"]`, or `[]` for none), and a page sets them (`fig.set({ dimensions: ["d"] })`, `null` for the
|
|
274
|
+
scene's own). Screen readers find them listed with their values, each called by its `name`.
|