@omrips/viewstl 2.0.0-rc.3 → 2.0.0-rc.5

package/README.md

@@ -1,191 +1,40 @@
-# ViewSTL v2.00
+> This is the maintained `@omrips/viewstl` package. The shorter `npm install viewstl` installs the same plugin. Existing `@omrips/viewstl` and `@omrips/viewstl/node` imports remain supported.
 
-**A new JavaScript 3D viewer built on native WebGL 2.**
+# Viewstl
 
-Embed a viewer in your website, open local 3D files, inspect models and save the result. ViewSTL v2 uses its own renderer, with no Three.js runtime required. File parsing and geometry analysis run in workers, with memory limits and cancellation support.
+Javascript STL/OBJ/3MF/STEP/IGES 3D files Viewer
 
-[Try the preview](https://preview.viewstl.com/) · [v2 usage and API notes](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md) · [Legacy plugin documentation](https://www.viewstl.com/plugin/)
+**ViewSTL v2.00 — release candidate 2.0.0-rc.5.** A new native WebGL 2 implementation; no THREE.js runtime required. Reads local files on the user's device, with model exports, animation, VSB/VSJ scene saving and mesh checks.
 
-> **Preview release: 2.0.0-rc.3.** v2 is a new implementation, with documented differences from v1. Existing versions remain available at their original paths. Read the migration notes before updating an existing integration.
+The new plugin is in `src/` and `build/`. Previous versions remain available in [legacy/](https://github.com/omrips/viewstl/tree/main/legacy), on the unchanged [master branch](https://github.com/omrips/viewstl/tree/master), and through their existing tags. v2 has [documented compatibility differences](docs/v2-usage.md#existing-api-and-intentional-differences).
 
-## Quick start
+## Usage:
 
-Install with `npm install @omrips/viewstl@2.0.0-rc.3`, then copy the complete `node_modules/@omrips/viewstl/build/v2/` folder to `/viewstl-v2/` on your website.
-
-Paste these three lines into your page's `<body>`:
+Download the [v2 plugin ZIP](https://github.com/omrips/viewstl/releases/download/v2.0.0-rc.5/viewstl-2.0.0-rc.5.zip) and copy its complete `build/` folder to your website. Add to your page:
 
 ```html
-<div id="viewer" style="height:500px"></div>
-<script src="/viewstl-v2/viewstl.min.js"></script>
-<script>new StlViewer(document.getElementById('viewer'), { models: [{ filename: 'model.stl' }] });</script>
-```
-
-Replace `model.stl` with your model's path and open the page over HTTP(S). That's it. You can also drag local files onto the viewer.
-
-## Quick start (Node.js)
-
-For server-side model analysis, install `npm install @omrips/viewstl@2.0.0-rc.3` and run:
-
-```js
-import { analyzeFile } from '@omrips/viewstl/node';
-const report = await analyzeFile('part.stl', { units: 'mm' });
+<div id="stl_cont" style="height:500px"></div>
+<script src="build/viewstl.min.js"></script>
+<script>var stl_viewer=new StlViewer(document.getElementById("stl_cont"), {models:[{id:0, filename:"mystl.stl"}]});</script>
 ```
 
-Requires Node.js 20+. Workers and CAD assets load directly from the installed package. The result is a JSON-compatible report with dimensions, surface area, validated volume and mesh checks. STL, OBJ, 3MF, STEP and IGES are supported. See [server API and limits](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md#nodejs-model-analysis) for buffers, batch processing, cancellation and unit handling.
-
-## What v2 can do
-
-- **Open models:** binary and ASCII STL, OBJ, 3MF, STEP/STP and IGES/IGS.
-- **Work with scenes:** multiple models, selection, independent position, rotation and scale, colors, camera controls and an infinite grid.
-- **Inspect geometry:** solid, smooth, edges, wireframe, X-ray and face-orientation views, section cuts, dimensions and mesh information.
-- **Save locally:** PNG images and mesh exports in binary STL, OBJ, 3MF, STEP and IGES.
-- **Save and restore scenes:** VSB packages the scene and meshes; VSJ stores scene settings and references to model files.
-- **Check meshes for 3D printing:** topology checks, detailed intersection and volume analysis, issue highlights and optional FDM estimates.
-- **Analyze on a server:** a Node.js API reuses the same parsers and mesh checks in background workers, with bounded concurrency and cancellation.
-- **Embed in your own interface:** use the `StlViewer` API, or bind your own markup to the optional `mountViewstlApp` controller.
-
-## Usage
-
-Choose a script tag, a browser ES module, or an npm package with your bundler. Each option uses the same viewer API and processes local files on the user's device.
-
-### Script tag
-
-Copy the **complete `build/v2/` directory** to your web server, for example as `/viewstl-v2/`. Keep its worker, `chunks/`, `cad/` and notice files together with the viewer.
-
-```html
-<input id="model-file" type="file" accept=".stl,.obj,.3mf,.step,.stp,.iges,.igs">
-<div id="viewer" style="width:100%;height:500px"></div>
+Replace `mystl.stl` with your model and serve the page over HTTP(S). Keep the worker, `chunks/` and `cad/` folders alongside the viewer. Archive/CAD dependencies are included and load only when needed; v2 does not require a separate JSZip setup.
 
-<script src="/viewstl-v2/viewstl.min.js"></script>
-<script>
-  const viewer = new StlViewer(document.getElementById('viewer'), {
-    load_error_callback: message => console.error(message)
-  });
-
-  document.getElementById('model-file').addEventListener('change', event => {
-    const file = event.target.files[0];
-    if (file) viewer.add_model({ local_file: file });
-  });
-</script>
-```
-
-Each file selected in this example is added to the viewer. Files are read on the user's device. Serve the page over HTTP(S), and give the viewer container a nonzero height.
-
-### ES modules
-
-With the same `build/v2/` directory hosted on your server, use a module script:
-
-```html
-<div id="viewer" style="width:100%;height:500px"></div>
-<script type="module">
-  import StlViewer from '/viewstl-v2/viewstl.js';
-
-  const viewer = new StlViewer(document.getElementById('viewer'), {
-    models: [{ id: 0, filename: '/models/part.stl' }]
-  });
-</script>
-```
-
-Replace `/models/part.stl` with a model URL you serve. To open a local file instead, call `viewer.add_model({ local_file: file })` with a browser `File`, as in the script-tag example.
-
-### npm and bundlers
-
-> **Release candidate:** `2.0.0-rc.3` adds the Node.js model-analysis API to ViewSTL v2.00. Candidates use the `next` dist-tag; pin the version below for a repeatable installation.
-
-Install the package in your application:
+## npm / Node.js:
 
 ```sh
-npm install @omrips/viewstl@2.0.0-rc.3
+npm install viewstl
 ```
 
-Copy the **complete `node_modules/@omrips/viewstl/build/v2/` directory** to your application's static assets. For an application that serves `public/` at its root, use `public/viewstl-v2/`. Keep the worker, `chunks/`, `cad/` and notices together; repeat this copy when updating the package.
-
-Add a container to your page:
-
-```html
-<div id="viewer" style="width:100%;height:500px"></div>
-```
-
-Then import the viewer in your application's browser entry point, after the container exists:
+Browser apps can import `StlViewer` from `viewstl`; see [worker setup](https://github.com/omrips/viewstl/blob/main/docs/v2-usage.md#es-modules-and-npm). Server-only analysis requires Node.js 20+:
 
 ```js
-import StlViewer from '@omrips/viewstl';
-
-const viewer = new StlViewer(document.getElementById('viewer'), {
-  worker_url: '/viewstl-v2/viewstl.worker.js',
-  models: [{ id: 0, filename: '/models/part.stl' }],
-  load_error_callback: message => console.error(message)
-});
-```
-
-Set `worker_url` to the URL where your application serves the copied worker, and replace `/models/part.stl` with your model URL. The bundler handles the viewer import; the static directory supplies its worker and optional parser assets. Creating a viewer requires a browser DOM and WebGL 2.
-
-The distribution includes TypeScript declarations and a CommonJS entry point. The static-assets setup above is verified with Vite 8.3.4 and Webpack 5.112.0. See [usage and packaging](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md) for worker factories, callbacks and more examples.
-
-## Formats and saving
-
-| Format | Open | Save |
-| --- | --- | --- |
-| STL | Binary and ASCII, including supported color variants | Binary STL |
-| OBJ | Geometry | Geometry; optional colors through an MTL companion |
-| 3MF | Supported mesh, component, unit and color data | Meshes and colors |
-| STEP / STP | CAD surfaces tessellated for viewing | Triangle surfaces |
-| IGES / IGS | CAD surfaces tessellated for viewing | Triangle surfaces |
-| VSB | Packaged ViewSTL scene | Scene settings and meshes in one archive |
-| VSJ | ViewSTL scene with model references | Scene settings and model references |
-| PNG | — | Image of the current view |
-
-STL, OBJ, 3MF, STEP and IGES export model geometry. **VSB and VSJ save the scene**, including its models, transforms and viewing settings. VSJ requires access to its referenced model files; VSB carries its mesh data inside the archive.
-
-STEP/IGES exports describe the loaded triangle mesh. They do not reconstruct original CAD solids, curves, feature history or assemblies. OBJ import does not load external materials or textures, and 3MF support does not cover every extension. See the [format and export details](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md#rendering-and-file-processing).
-
-## Local files and URL imports
-
-In the browser, local file contents are processed on the user's device. Rendering, mesh checks, model exports and scene saving do not require an upload or a conversion service. Archive and CAD support load additional assets only when needed.
-
-The optional Node.js API processes files on the machine running Node. If your application accepts uploads for server analysis, those files leave the user's device. The package itself provides no upload endpoint and does not send model data anywhere.
-
-Direct URL imports require the remote server to allow browser access through CORS. A host application can configure its own streaming relay for other public URLs. **The relay is a separate server service**, not part of the plugin's JavaScript bundle. The preview website uses such a relay; URL imports pass through that server. See [URL import configuration](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md#optional-streaming-url-imports).
-
-## Existing users and previous versions
-
-**The legacy plugin remains available in the GitHub repository.** v2 has separate source and build directories, so switching to it is an explicit choice. The npm package contains the v2 distribution; it does not replace legacy download paths.
-
-| | Legacy v1 | New v2 |
-| --- | --- | --- |
-| Source | Existing files in `src/` | `src/v2/` |
-| Browser script | `build/stl_viewer.min.js` | `build/v2/viewstl.min.js` |
-| Renderer | Three.js | Native WebGL 2 |
-| Documentation | [viewstl.com/plugin](https://www.viewstl.com/plugin/) | [Package usage and API notes](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md) |
-
-The familiar `StlViewer` constructor and many public methods are retained. Integrations that access Three.js camera, scene, renderer or model internals need migration. v2 requires WebGL 2 and does not include the legacy WebGL 1 or Canvas fallback. See [API differences and migration notes](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-usage.md#existing-api-and-intentional-differences).
-
-Existing tags and release history are retained. The [legacy archive notes](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/legacy/README.md) also describe the separate local v1.14 snapshot and its provenance.
-
-The documentation link remains **https://www.viewstl.com/plugin/**. It currently documents the legacy plugin; v2 guidance is included in this package while the website documentation is prepared.
-
-## Requirements and current limits
-
-- A browser with WebGL 2 and module-worker support; WebAssembly is required for STEP/IGES import.
-- Model capacity depends on geometry complexity and available browser/GPU memory. Configured limits reject files that exceed the budget.
-- Print checks describe the loaded mesh. FDM results are estimates, and checks do not guarantee a successful print. Models are checked separately; assembly overlaps are not evaluated.
-- The preview has automated and desktop Chromium/Edge coverage. Firefox, Safari and physical mobile-device validation remain pending. See [verification and known limits](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/docs/v2-verification.md).
-
-## Development
-
-For contributors working in the source checkout, use Node.js 20 or newer and pnpm. The npm package contains the built viewer and documentation:
-
-```sh
-pnpm install --frozen-lockfile
-pnpm build
-pnpm test
-pnpm check:types
-pnpm check:legacy
-pnpm start
+import { analyzeFile } from 'viewstl/node';
+console.log(await analyzeFile('part.stl', { units: 'mm' }));
 ```
 
-Open `http://127.0.0.1:8772/examples/v2/` for the local demo. The build writes to `build/v2/`; the legacy check verifies that preserved source, builds and archived files remain unchanged.
+No version suffix is needed. `npm install @omrips/viewstl` also installs the current release; existing scoped imports remain supported. Both names contain the same plugin, including animation and VSB/VSJ scene persistence.
 
-## License
+More at [viewstl.com/plugin](https://www.viewstl.com/plugin/) (legacy documentation). For v2, see [usage and API notes](docs/v2-usage.md), [release notes](docs/releases/2.0.0-rc.5.md) and [verification](docs/v2-verification.md).
 
-ViewSTL is available under the [MIT license](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/LICENSE). Optional archive and CAD dependencies have their own licenses and notices; see [third-party notices](https://unpkg.com/@omrips/viewstl@2.0.0-rc.3/THIRD-PARTY-NOTICES.txt).
+The [original README and usage examples](https://github.com/omrips/viewstl/blob/main/legacy/v1/README.md) are preserved with the legacy plugin. ViewSTL uses the [MIT license](LICENSE); optional dependencies retain their [third-party notices](THIRD-PARTY-NOTICES.txt).