@es3d/es3d 1.0.1 → 1.1.0

package/README.md

@@ -1,11 +1,20 @@
 # ES3D
 
+<p align="center">
+  <a href="https://www.jsdelivr.com/package/npm/@es3d/es3d"><img src="https://img.shields.io/jsdelivr/npm/hm/@es3d/es3d?label=jsDelivr" alt="jsDelivr"></a>
+  <a href="https://www.npmjs.com/package/@es3d/es3d"><img src="https://img.shields.io/npm/v/@es3d/es3d" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@es3d/es3d"><img src="https://img.shields.io/npm/dm/@es3d/es3d" alt="npm downloads"></a>
+  <a href="https://github.com/bitilia/es3d/stargazers"><img src="https://img.shields.io/github/stars/bitilia/es3d" alt="GitHub stars"></a>
+  <a href="https://github.com/bitilia/es3d/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bitilia/es3d" alt="License"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@es3d/es3d" alt="Node.js"></a>
+</p>
+
 **A file format for 3D scenes you can write by hand, the way people write SVG.** The file describes objects, not triangles: a rounded box, an outline extruded into a solid, two thousand trees placed by a rule. The viewer builds the triangles, at the detail the screen needs.
 
 This package is the reference implementation:
 - a strict parser and validator;
 - a WebGPU renderer with a WebGL2 fallback;
-- converters from SVG, OBJ, STL, STEP and glTF, and back;
+- converters from SVG, OBJ, STL, STEP, glTF, X3D, USDA and OpenSCAD, and to glTF, OBJ, STL, STEP, X3D, USDA, OpenSCAD and a three.js module;
 - the `es3d` command.
 
 It has no dependencies.
@@ -47,6 +56,17 @@ stage.show(source); // ES3D markup, compact syntax or JSON
 
 The canvas is sized by its parent element. The stage draws only when something changes, plays animations, and follows the document's `<controls>`: orbit limits, collision with the scene, or a camera that follows page scroll.
 
+A page that moves shapes itself can load the stage as one file:
+
+```js
+import { createStage, mulberry32, es3dSin, es3dCos } from '@es3d/es3d/stage';
+
+const stage = await createStage(document.querySelector('canvas'), { background: true });
+stage.show(source);
+```
+
+`background: true` runs the clock and leaves the camera still. `stage.setTransform(id, matrix)` replaces the local matrix of an element that is placed once (column-major, the same layout as `matrix()`). `stage.setTransforms([[id, matrix], ...])` stores every matrix, walks each affected part of the scene once, and returns a boolean for each entry. A shared definition or a `<repeat>` / `<scatter>` copy is left unchanged and that entry is false. `stage.reducedMotion` follows the visitor's reduced-motion preference, and the clock stays still while it matches. `clock: 'always'` runs the clock when the document has no `<animate>`. `mulberry32`, `es3dSin` and `es3dCos` are the reader's placement functions. The format stays version 1.
+
 ## Compile, check and convert
 
 ```js
@@ -55,19 +75,19 @@ import { compile, importFiles, exportFormat } from '@es3d/es3d';
 const result = compile(source);
 if (!result.ok) console.error(result.diagnostics.map((d) => d.format()).join('\n\n'));
 
-const { text } = await importFiles([{ name: 'logo.svg', bytes }]); // SVG, OBJ, STL, STEP, glTF → ES3D
-const { files } = exportFormat(text, 'glb');                         // ES3D → glTF, OBJ, STL, STEP
+const { text } = await importFiles([{ name: 'logo.svg', bytes }]); // SVG, OBJ, STL, STEP, glTF, X3D, USDA, OpenSCAD → ES3D
+const { files } = exportFormat(text, 'glb');                         // ES3D → glTF, OBJ, STL, STEP, X3D, USDA, OpenSCAD, three.js
 ```
 
-Every error has a line, a column, a code and, where it can, a "did you mean" suggestion.
+Every error has a line, a column, a code and, where it can, a "did you mean" suggestion. Repeated warnings that share a code, an element name and a message are printed once, with a count. `validate --json` still lists every warning.
 
 ## The command
 
 ```bash
-npx @es3d/es3d validate scene.es3d               # every diagnostic; exit code 1 on errors
+npx @es3d/es3d validate scene.es3d               # diagnostics, repeated warnings grouped; exit code 1 on errors
 npx @es3d/es3d compact scene.es3d                # convert to the compact syntax (also: markup, json, fmt, minify)
-npx @es3d/es3d glb scene.es3d -o scene.glb       # export (also: obj, stl, step)
-npx @es3d/es3d import logo.svg -o logo.es3d      # SVG, OBJ, STL, STEP or glTF to ES3D
+npx @es3d/es3d glb scene.es3d -o scene.glb       # export (also: obj, stl, step, x3d, usd, scad, js)
+npx @es3d/es3d import logo.svg -o logo.es3d      # SVG, OBJ, STL, STEP, glTF, X3D, USDA or OpenSCAD to ES3D
 npx @es3d/es3d stats scene.es3d                  # sizes, counts and timings
 ```