@omrips/viewstl 0.0.0-stage → 2.0.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 omrips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# ViewSTL v2.00
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**A new JavaScript 3D viewer built on native WebGL 2.**
+
+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.
+
+[Try the preview](https://preview.viewstl.com/) · [v2 usage and API notes](https://unpkg.com/@omrips/viewstl@2.0.0-rc.1/docs/v2-usage.md) · [Legacy plugin documentation](https://www.viewstl.com/plugin/)
+
+> **Preview release: 2.0.0-rc.1.** 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.
+
+## 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.
+- **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>
+
+<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.1` is the first npm release of ViewSTL v2.00. Candidates use the `next` dist-tag; pin the version below for a repeatable installation.
+
+Install the package in your application:
+
+```sh
+npm install @omrips/viewstl@2.0.0-rc.1
+```
+
+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:
+
+```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.1/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.1/docs/v2-usage.md#rendering-and-file-processing).
+
+## Local files and URL imports
+
+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.
+
+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.1/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.1/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.1/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.1/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.1/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
+```
+
+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.
+
+## License
+
+ViewSTL is available under the [MIT license](https://unpkg.com/@omrips/viewstl@2.0.0-rc.1/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.1/THIRD-PARTY-NOTICES.txt).