lk3d 0.2.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 +24 -0
- package/README.md +14 -6
- package/dist/lk3d-export.min.js +1 -1
- package/dist/lk3d.min.js +28 -22
- package/dist/lk3d.mjs +31 -25
- package/docs/api.md +31 -31
- package/docs/design.md +5 -3
- package/docs/handles-and-lines.md +27 -0
- package/docs/performance.md +2 -1
- package/docs/scene-format.md +1 -0
- package/index.d.ts +4 -0
- package/package.json +2 -1
- package/scene.d.ts +104 -0
- package/schema/scene.schema.json +164 -0
- package/skill/lk3d/SKILL.md +3 -0
- package/src/figure/api.js +7 -2
- package/src/figure/camera.js +11 -3
- package/src/figure/context.d.ts +16 -3
- package/src/figure/dimensions.js +140 -0
- package/src/figure/input.js +40 -16
- package/src/figure/labels.js +25 -10
- package/src/figure/loop.js +2 -0
- package/src/figure/pick.js +6 -4
- package/src/figure/steps.js +1 -0
- package/src/index.js +3 -0
- package/src/locales/en.js +1 -0
- package/src/locales/vi.js +1 -0
- package/src/renderer-gl.js +3 -1
- package/src/shaders.js +24 -16
- package/src/stylesheet.js +4 -2
- package/src/validate.js +39 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,30 @@
|
|
|
3
3
|
lk3d follows [semantic versioning](https://semver.org): before 1.0, a minor version (0.x.0) may change the scene
|
|
4
4
|
format or the API, and says how to move.
|
|
5
5
|
|
|
6
|
+
## 0.2.1 (11 November 2026)
|
|
7
|
+
|
|
8
|
+
- **Quarter cuts**: a second plane, `section.second` (`{normal, offset}`), and only what lies beyond both planes is cut
|
|
9
|
+
away, as in a technical cutaway; both faces are filled and hatched, the reader drags either, and `fig.section` reports
|
|
10
|
+
both. A step or the page drops it with `second: false` / `null`.
|
|
11
|
+
- **The playground** (`playground/`, published at https://xoai.github.io/lk3d/playground/): a scene's JSON beside the
|
|
12
|
+
figure, drawn as it is typed and checked as `lk3d check` does (the format and the geometry, in a worker), each problem
|
|
13
|
+
shown at its place in the text; the examples to start from; a look and a theme; Share makes a link with the scene in
|
|
14
|
+
it, and the scene goes out as .json or .glb. `npm run playground` serves it from a checkout.
|
|
15
|
+
- **Dimensions** (`dimensions` in the scene): lengths between points and angles at vertices, drawn as on a technical
|
|
16
|
+
drawing (extension lines, arrows, the value), their values worked out from the figure as shown, in the scene's unit or
|
|
17
|
+
the dimension's own (`unit`); a point may ride on a part (`{part, at}`), so a length to it follows the part as the
|
|
18
|
+
reader moves it. Steps (`dimensions: [ids]`) and the page (`fig.set({ dimensions })`) choose which show; screen
|
|
19
|
+
readers find them listed. The lens bench example measures the object's distance and the focal length. New word:
|
|
20
|
+
`dimensions`.
|
|
21
|
+
- **Examples**: a tour of a human cell (`examples/cell-tour.html`, its scene made by `examples/cell-tour.mjs`), made as
|
|
22
|
+
detailed as an illustrated film: proteins in the membrane, nuclear pores, loose chromatin, smooth ER, mitochondria
|
|
23
|
+
with folded cristae, a Golgi stack with swollen rims and budding vesicles, centrioles of nine triplets, and the
|
|
24
|
+
cytoskeleton's three fibres; eleven guided steps, messenger RNA leaving through the pores, a close-up of the
|
|
25
|
+
membrane. The lens bench measures the object's distance and the focal length.
|
|
26
|
+
- A label whose point the cut has taken points at its part's cut face instead; it hides only when the cut has taken
|
|
27
|
+
the whole part. (0.2.0 hid the label of any part whose label point was cut away, though the rest of it still showed:
|
|
28
|
+
the generator's south magnet when cut open, say.)
|
|
29
|
+
|
|
6
30
|
## 0.2.0 (11 November 2026)
|
|
7
31
|
|
|
8
32
|
- **Guided steps** (`steps` in the scene): the figure explained in order, each step its words (`title`, `text`) and a
|
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ The scene is plain data (JSON), so it can be written, reviewed and checked like
|
|
|
10
10
|
|
|
11
11
|
```html
|
|
12
12
|
<div id="fig"></div>
|
|
13
|
-
<script src="https://unpkg.com/lk3d@0.2.
|
|
13
|
+
<script src="https://unpkg.com/lk3d@0.2.1/dist/lk3d.min.js"></script>
|
|
14
14
|
<script>
|
|
15
15
|
LK3D.mount(document.getElementById('fig'), {
|
|
16
16
|
title: 'A bolt and a nut',
|
|
@@ -40,7 +40,7 @@ The scene is plain data (JSON), so it can be written, reviewed and checked like
|
|
|
40
40
|
## What it does
|
|
41
41
|
|
|
42
42
|
- **Explore**: turn and zoom (mouse, touch, pen, keyboard) and pan (Shift-drag or right-drag); preset views; take the
|
|
43
|
-
model apart (each part along its own path); cut it open, with the cut faces filled and hatched, and move the cut through it (drag its face); see through casings;
|
|
43
|
+
model apart (each part along its own path); cut it open, with the cut faces filled and hatched (a half, or a quarter with two planes), and move the cut through it (drag its face); see through casings;
|
|
44
44
|
labels with leader lines that do not overlap; a note for each part.
|
|
45
45
|
- **Move parts by hand**: handles that turn (a focus ring, a rotor), slide (a piston, an object on a bench) or follow a
|
|
46
46
|
path (a planet on its orbit), each also a range input for the keyboard and screen readers. Rays, field lines and
|
|
@@ -67,6 +67,8 @@ The scene is plain data (JSON), so it can be written, reviewed and checked like
|
|
|
67
67
|
shadows, surface detail, glass that bends light) and a hand-drawn ink look, with an orthographic camera for a
|
|
68
68
|
technical illustration; light, dark, blueprint and sepia themes, or the reader's own setting
|
|
69
69
|
([looks](docs/looks-and-materials.md)).
|
|
70
|
+
- **Dimensions**: lengths and angles drawn as on a technical drawing, their values worked out from the figure as shown,
|
|
71
|
+
so a length to a part changes as the reader moves it ([dimensions](docs/handles-and-lines.md#dimensions)).
|
|
70
72
|
- **Honest scale**: a scale bar that keeps its true length as the view zooms, or a note saying what is not to scale.
|
|
71
73
|
- **Accessible**: the figure has a text description and lists its parts for screen readers; the keyboard turns it,
|
|
72
74
|
zooms and goes through its parts (each said aloud with its note); every control works by keyboard, handles are read out, motion
|
|
@@ -82,7 +84,7 @@ The scene is plain data (JSON), so it can be written, reviewed and checked like
|
|
|
82
84
|
|
|
83
85
|
| | Minified | Gzipped |
|
|
84
86
|
| --------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
|
|
85
|
-
| lk3d |
|
|
87
|
+
| lk3d | 171 KB | 66.6 KB |
|
|
86
88
|
| three.js r187, the smallest page | 522 KB | 131 KB |
|
|
87
89
|
| three.js r187 with what lk3d does (PBR and glass, shadows, environment, controls, picking, glTF, labels, bloom, shape generators) | 708 KB | 181 KB |
|
|
88
90
|
|
|
@@ -100,10 +102,16 @@ lk3d explains objects. For games, character animation (skins, morph targets), VR
|
|
|
100
102
|
scenes, use [three.js](https://threejs.org) or [Babylon.js](https://www.babylonjs.com); to show a single glTF model
|
|
101
103
|
with hotspots and AR, use [model-viewer](https://modelviewer.dev).
|
|
102
104
|
|
|
105
|
+
## Try it
|
|
106
|
+
|
|
107
|
+
The [playground](https://xoai.github.io/lk3d/playground/): write a scene as JSON and see it drawn as you type,
|
|
108
|
+
checked as `lk3d check` does (each problem shown where it is in the text), starting from an example; share it as a
|
|
109
|
+
link, or take it away as a .json or .glb file. From a checkout: `npm run playground`, then open `/playground/`.
|
|
110
|
+
|
|
103
111
|
## Use it
|
|
104
112
|
|
|
105
113
|
A page loads one script, the global `LK3D`, as above: from a CDN with its version pinned
|
|
106
|
-
(`https://unpkg.com/lk3d@0.2.
|
|
114
|
+
(`https://unpkg.com/lk3d@0.2.1/dist/lk3d.min.js`, or `https://cdn.jsdelivr.net/npm/lk3d@0.2.1/dist/lk3d.min.js`), or a
|
|
107
115
|
copy of `dist/lk3d.min.js` next to the page. A project with a bundler installs it and imports it:
|
|
108
116
|
|
|
109
117
|
```sh
|
|
@@ -122,7 +130,7 @@ same script defines: the scene from `src`, or from a JSON script inside it, and
|
|
|
122
130
|
moves come as events ([the element](docs/api.md#the-element-lk3d-figure)).
|
|
123
131
|
|
|
124
132
|
```html
|
|
125
|
-
<script src="https://unpkg.com/lk3d@0.2.
|
|
133
|
+
<script src="https://unpkg.com/lk3d@0.2.1/dist/lk3d.min.js"></script>
|
|
126
134
|
<lk3d-figure src="generator.json" look="pen" locale="vi"></lk3d-figure>
|
|
127
135
|
```
|
|
128
136
|
|
|
@@ -133,7 +141,7 @@ To build it yourself, or to work on it: `git clone https://github.com/xoai/lk3d.
|
|
|
133
141
|
- [Scene format](docs/scene-format.md) · [Shapes](docs/shapes.md) · [Handles and lines](docs/handles-and-lines.md) ·
|
|
134
142
|
[Looks and materials](docs/looks-and-materials.md) · [Models](docs/models.md) · [How it works](docs/design.md) ·
|
|
135
143
|
[Performance](docs/performance.md).
|
|
136
|
-
- [Examples](examples/): a generator, a lens bench, a cell, molecules, the Solar System, rock layers, a gauge, a fossil
|
|
144
|
+
- [Examples](examples/): a generator, a lens bench, a cell (and a guided tour of one), molecules, the Solar System, rock layers, a gauge, a fossil
|
|
137
145
|
skull, the three looks, a circuit, air through a fan, and a figure on a page that writes no script. `npm run examples` serves them.
|
|
138
146
|
- Reading a figure: drag to turn it, Shift-drag or right-drag to pan, pinch to zoom; the wheel zooms only with Ctrl
|
|
139
147
|
held or once the figure has been clicked, and a finger moved up or down scrolls the page until the figure has been
|
package/dist/lk3d-export.min.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
/*! lk3d 0.2.
|
|
1
|
+
/*! lk3d 0.2.1 | MIT License | Copyright (c) 2026 xoai */
|
|
2
2
|
"use strict";(()=>{var _={mm:.001,cm:.01,dm:.1,m:1,km:1e3},q=i=>i<=.04045?i/12.92:((i+.055)/1.055)**2.4;function B(i){let s=n=>Math.hypot(i[4*n],i[4*n+1],i[4*n+2]);if([0,1,2].some(n=>Math.abs(s(n)-1)>1e-4))return null;let[g,y,p,,x,d,h,,A,m,L]=i,b=g+d+L,M;if(b>0){let n=Math.sqrt(b+1)*2;M=[(h-m)/n,(A-p)/n,(y-x)/n,n/4]}else if(g>d&&g>L){let n=Math.sqrt(1+g-d-L)*2;M=[n/4,(y+x)/n,(A+p)/n,(h-m)/n]}else if(d>L){let n=Math.sqrt(1+d-g-L)*2;M=[(y+x)/n,n/4,(h+m)/n,(A-p)/n]}else{let n=Math.sqrt(1+L-g-d)*2;M=[(A+p)/n,(h+m)/n,n/4,(y-x)/n]}let F=Math.hypot(...M);return{translation:[i[12],i[13],i[14]],rotation:M.map(n=>n/F)}}function N(i,s={}){let g=[],y=[],p=[],x=[],d=[],h=[],A=[],m=0,L=(t,e)=>{for(;m%4;)g.push(new Uint8Array(1)),m++;let o=new Uint8Array(t.buffer,t.byteOffset,t.byteLength);return g.push(o),y.push({buffer:0,byteOffset:m,byteLength:o.byteLength,...e&&{target:e}}),m+=o.byteLength,y.length-1},b=(t,e,o={})=>{let l={SCALAR:1,VEC3:3,VEC4:4}[e],a=t instanceof Float32Array?5126:t instanceof Uint32Array?5125:5123;return p.push({bufferView:L(t,o.target),componentType:a,count:t.length/l,type:e,...o.minMax}),p.length-1},M=(t,e)=>{let o=Array(e).fill(1/0),l=Array(e).fill(-1/0);for(let a=0;a<t.length;a++)o[a%e]=Math.min(o[a%e],t[a]),l[a%e]=Math.max(l[a%e],t[a]);return{min:o,max:l}},F=(t,e)=>{let o=B(e);o?(o.translation.some(l=>Math.abs(l)>1e-7)&&(t.translation=o.translation),Math.abs(o.rotation[3])<1-1e-7&&(t.rotation=o.rotation)):t.matrix=Array.from(e)},n=new Map;for(let t of i.parts){if(t.hidden||!t.batches.length)continue;let e=s.flatten(t);if(!e.count)continue;let o=new Float32Array(e.positions),l=new Float32Array(e.normals),a=e.count>65535?new Uint32Array(e.indices):new Uint16Array(e.indices),k=t.studioColor.map(q),V={POSITION:b(o,"VEC3",{target:34962,minMax:M(o,3)}),NORMAL:b(l,"VEC3",{target:34962})};if(e.colors){let O=new Float32Array(e.count*4);for(let r=0;r<e.count;r++){let u=e.colors[4*r+3]/255;for(let f=0;f<3;f++)O[4*r+f]=k[f]+(q(e.colors[4*r+f]/255)-k[f])*u;O[4*r+3]=1}V.COLOR_0=b(O,"VEC4",{target:34962})}d.push({name:t.name||t.id,pbrMetallicRoughness:{baseColorFactor:[...e.colors?[1,1,1]:k,t.alpha],metallicFactor:t.metalRoughness[0],roughnessFactor:t.metalRoughness[1]},...t.alpha<1&&{alphaMode:"BLEND"},doubleSided:!0}),x.push({name:t.name||t.id,primitives:[{attributes:V,indices:b(a,"SCALAR",{target:34963}),material:d.length-1}]});let c={name:t.name||t.id,mesh:x.length-1,extras:{lk3d:{id:t.id,...t.note&&{note:t.note}}}};s.matrix&&F(c,s.matrix(t)),h.push(c),n.set(t,h.length-1)}for(let t of s.animations||[]){let e=new Float32Array(t.times),o=[],l=[],a=null;for(let[k,V]of n){let c=t.times.map((r,u)=>B(t.matrix(k,u)));if(c.some(r=>!r))continue;let O=r=>c.some(u=>u[r].some((f,R)=>Math.abs(f-c[0][r][R])>1e-6));for(let r=1;r<c.length;r++)c[r].rotation.reduce((u,f,R)=>u+f*c[r-1].rotation[R],0)<0&&(c[r].rotation=c[r].rotation.map(u=>-u));for(let[r,u]of[["translation","VEC3"],["rotation","VEC4"]])O(r)&&(a==null&&(a=b(e,"SCALAR",{minMax:{min:[e[0]],max:[e[e.length-1]]}})),l.push({input:a,output:b(new Float32Array(c.flatMap(f=>f[r])),u),interpolation:"LINEAR"}),o.push({sampler:l.length-1,target:{node:V,path:r}}))}o.length&&A.push({name:t.name,channels:o,samplers:l})}let j=_[s.unit]??1;h.push({name:s.title||"lk3d",children:h.map((t,e)=>e),...j!==1&&{scale:[j,j,j]}});let I={asset:{version:"2.0",generator:"lk3d",...(s.author||s.license)&&{copyright:[s.author&&"\xA9 "+s.author,s.license].filter(Boolean).join(", ")}},scene:0,scenes:[{name:s.title||"lk3d",nodes:[h.length-1]}],nodes:h,meshes:x,materials:d,accessors:p,bufferViews:y,buffers:[{byteLength:m+(4-m%4)%4}],...A.length&&{animations:A}},E=new TextEncoder().encode(JSON.stringify(I)),C=E.length+(4-E.length%4)%4,S=I.buffers[0].byteLength,U=new Uint8Array(20+C+8+S),w=new DataView(U.buffer);w.setUint32(0,1179937895,!0),w.setUint32(4,2,!0),w.setUint32(8,U.length,!0),w.setUint32(12,C,!0),w.setUint32(16,1313821514,!0),U.set(E,20),U.fill(32,20+E.length,20+C),w.setUint32(20+C,S,!0),w.setUint32(24+C,5130562,!0);let T=28+C;for(let t of g)U.set(t,T),T+=t.length;return U}if(!globalThis.LK3D)throw new Error("lk3d-export: load dist/lk3d.min.js first");globalThis.LK3D.toGLB=N;})();
|