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 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.0/dist/lk3d.min.js"></script>
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 | 166 KB | 64.9 KB |
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.0/dist/lk3d.min.js`, or `https://cdn.jsdelivr.net/npm/lk3d@0.2.0/dist/lk3d.min.js`), or a
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.0/dist/lk3d.min.js"></script>
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
@@ -1,2 +1,2 @@
1
- /*! lk3d 0.2.0 | MIT License | Copyright (c) 2026 xoai */
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;})();