occt-wasm 5.17.1 → 5.17.2

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/README.md CHANGED
@@ -9,33 +9,33 @@
9
9
  [![Commit activity](https://img.shields.io/github/commit-activity/m/andymai/occt-wasm?label=commits%2Fmonth)](https://github.com/andymai/occt-wasm/commits/main)
10
10
  [![License](https://img.shields.io/badge/tooling-MIT%20OR%20Apache--2.0-blue.svg)](#license) [![WASM License](https://img.shields.io/badge/wasm%20output-LGPL--2.1--only-blue.svg)](#license)
11
11
 
12
- [OpenCascade](https://github.com/Open-Cascade-SAS/OCCT) V8 compiled to WebAssembly with a clean TypeScript API.
12
+ [OpenCascade](https://github.com/Open-Cascade-SAS/OCCT) (OCCT) V8 compiled to WebAssembly, with a TypeScript API and Web Worker support.
13
13
 
14
- Smaller bundles, branded types, arena-based memory, and modern tooling.
14
+ The module is about 4.5 MB with brotli. The API uses branded types and arena-based memory.
15
15
 
16
16
  </div>
17
17
 
18
- > **Looking for a higher-level CAD library?** [brepjs](https://github.com/andymai/brepjs) builds on occt-wasm with a friendlier API for parametric modeling, sketching, and production CAD applications. Use occt-wasm directly when you need full control over OCCT operations.
18
+ > **Do you need a higher-level CAD library?** [brepjs](https://github.com/andymai/brepjs) builds on occt-wasm, its default kernel, and adds an API for parametric models, sketches, and production CAD applications. Use occt-wasm directly when you need full control over OCCT operations.
19
19
 
20
20
  ## Highlights
21
21
 
22
- - **~4.5 MB brotli** -- roughly 2x smaller than opencascade.js
23
- - **Comprehensive API** -- primitives, booleans, sweeps, XCAF assemblies, curves, surfaces, STEP/STL/glTF/BREP I/O, topology, shape evolution tracking
24
- - **Arena-based API** -- u32 shape handles, no manual `.delete()`, `Symbol.dispose` support
25
- - **TypeScript-first** -- branded `ShapeHandle`, union types for shapes/surfaces/curves, structured returns
26
- - **Structured error handling** -- `OcctErrorCode` enum for programmatic `switch/case` instead of string parsing
27
- - **Web Worker support** -- `OcctWorker` class for off-main-thread CAD operations via [Comlink](https://github.com/GoogleChromeLabs/comlink)
28
- - **Modern browser targets** -- WASM SIMD, tail calls, wasm-exceptions
22
+ - **~4.5 MB brotli**: the module is about half the size of opencascade.js.
23
+ - **170+ methods**: the API covers primitives, booleans, sweeps, XCAF assemblies, curves, surfaces, STEP/STL/glTF/BREP I/O, topology, and shape evolution history.
24
+ - **Arena-based API**: shapes are u32 handles. You do not call `.delete()` by hand, and the API supports `Symbol.dispose`.
25
+ - **TypeScript types**: `ShapeHandle` is a branded type. Shapes, surfaces, and curves have union types, and methods return structured values.
26
+ - **Structured errors**: use the `OcctErrorCode` enum in a `switch/case`. You do not need to parse the error message.
27
+ - **Web Worker support**: the `OcctWorker` class runs CAD operations off the main thread through [Comlink](https://github.com/GoogleChromeLabs/comlink).
28
+ - **Browser targets**: the build uses WASM SIMD, tail calls, and wasm-exceptions.
29
29
 
30
30
  ## Scope
31
31
 
32
- To set expectations, this library deliberately does not:
32
+ This library deliberately does not:
33
33
 
34
- - **Provide a higher-level CAD modeling API** — parametric sketching, constraints, feature trees, and ergonomic modeling belong in [brepjs](https://github.com/andymai/brepjs), which wraps occt-wasm for that purpose
35
- - **Manage memory automatically beyond arena handles** — shapes are freed when the kernel is disposed or you call `release()`; there is no per-shape garbage collection
36
- - **Support non-WASM-SIMD browsers** — the build requires WASM SIMD (baseline `-msimd128`), tail calls, and wasm exceptions, so it needs a recent engine (see [Browser Compatibility](#browser-compatibility)). Relaxed-SIMD is intentionally not used: some Safari/iOS WebKit builds fail to compile relaxed-SIMD modules, and it made geometry non-reproducible across CPUs
37
- - **Include OCCT visualization or display modules** — TKV3d, TKHLR (except the HLR facade), and the AIS interactive context are excluded; bring your own renderer (Three.js, Babylon.js, etc.)
38
- - **Support IGES import/export** -- TKDEIGES is excluded from the link; use STEP for interchange
34
+ - **Provide a higher-level CAD modeling API.** Parametric sketches, constraints, and feature trees belong in [brepjs](https://github.com/andymai/brepjs), which wraps occt-wasm for that purpose.
35
+ - **Manage memory automatically beyond arena handles.** A shape stays in memory until you call `release()` or dispose of the kernel. There is no per-shape garbage collection.
36
+ - **Support browsers without WASM SIMD.** The build requires WASM SIMD (baseline `-msimd128`), tail calls, and wasm exceptions. Thus it needs a recent engine (see [Browser Compatibility](#browser-compatibility)). The build intentionally does not use relaxed SIMD. Some Safari and iOS WebKit builds fail to compile relaxed-SIMD modules, and relaxed SIMD made geometry non-reproducible across CPUs.
37
+ - **Include OCCT visualization or display modules.** The build excludes TKV3d, TKHLR (except the HLR facade), and the AIS interactive context. Bring your own renderer, for example Three.js or Babylon.js.
38
+ - **Support IGES import/export.** The build does not link TKDEIGES. Use STEP for interchange.
39
39
 
40
40
  ## Install
41
41
 
@@ -85,23 +85,23 @@ import { OcctKernel } from "occt-wasm";
85
85
  ```
86
86
 
87
87
  > **Boolean results are compounds.** OCCT's `BRepAlgoAPI` operations wrap their
88
- > output in a `TopoDS_Compound` — a boolean can produce several disjoint solids.
88
+ > output in a `TopoDS_Compound`. A boolean can produce several disjoint solids.
89
89
  > The operations that downcast to a solid (`fillet`, `chamfer`, `filletVariable`,
90
- > `filletBatch`, `healSolid`) reject one, so unwrap first:
90
+ > `filletBatch`, `healSolid`) reject a compound, so unwrap it first:
91
91
  >
92
92
  > ```typescript check kernel,fused
93
93
  > const [solid] = kernel.getSubShapes(fused, "solid");
94
94
  > if (!solid) throw new Error("boolean produced no solid");
95
95
  > ```
96
96
  >
97
- > **Not every edge is filletable.** Seam and degenerate edges are not, so on a
98
- > shape you didn't build yourself, select edges by geometry rather than by index.
99
- > The `slice(0, 4)` above is safe only because all 12 edges of a plain box round
100
- > cleanly — on the box-plus-cylinder fusion, only 13 of 20 edges do.
97
+ > **Not every edge is filletable.** Seam and degenerate edges are not filletable.
98
+ > On a shape that you did not build yourself, select edges by geometry, not by
99
+ > index. The `slice(0, 4)` above is safe only because all 12 edges of a plain box
100
+ > take a fillet. On the box-plus-cylinder fusion, only 13 of 20 edges do.
101
101
 
102
102
  ## Rust Crate
103
103
 
104
- The same OCCT WASM is available as a [Rust crate](https://crates.io/crates/occt-wasm) for native targets (servers, CLIs, build scripts) — no C++ toolchain required:
104
+ The same OCCT WASM is available as a [Rust crate](https://crates.io/crates/occt-wasm) for native targets (servers, CLIs, build scripts). It does not need a C++ toolchain:
105
105
 
106
106
  ```toml
107
107
  [dependencies]
@@ -119,11 +119,11 @@ let mesh = kernel.tessellate(fused, 0.1, 0.5)?;
119
119
  let step = kernel.export_step(fused)?;
120
120
  ```
121
121
 
122
- The crate embeds a brotli-compressed WASM binary (~4.7 MB) and runs it via [wasmtime](https://wasmtime.dev/). Same 170+ facade methods as the TS API. See [`crate/README.md`](./crate/README.md) and [docs.rs/occt-wasm](https://docs.rs/occt-wasm) for full details.
122
+ The crate embeds a brotli-compressed WASM binary (~4.7 MB) and runs it with [wasmtime](https://wasmtime.dev/). It has the same 170+ facade methods as the TypeScript API. See [`crate/README.md`](./crate/README.md) and [docs.rs/occt-wasm](https://docs.rs/occt-wasm) for full details.
123
123
 
124
124
  ## Initialization
125
125
 
126
- By default, `OcctKernel.init()` auto-locates the `.wasm` file next to the JS module. You can also provide explicit paths or pre-loaded binaries:
126
+ By default, `OcctKernel.init()` finds the `.wasm` file next to the JS module. You can also give explicit paths or pre-loaded binaries:
127
127
 
128
128
  ```typescript check
129
129
  import { OcctKernel } from "occt-wasm";
@@ -148,7 +148,7 @@ await OcctKernel.init({ createModule, wasm: "/occt/occt-wasm.wasm" });
148
148
 
149
149
  ## Error Handling
150
150
 
151
- All errors are instances of `OcctError` with a structured `code` field for programmatic handling:
151
+ Each error is an instance of `OcctError`, with a structured `code` field that your code can read:
152
152
 
153
153
  ```typescript check kernel,a,b
154
154
  import { OcctError, OcctErrorCode } from "occt-wasm";
@@ -173,7 +173,7 @@ try {
173
173
  }
174
174
  ```
175
175
 
176
- Available error codes:
176
+ The error codes are:
177
177
 
178
178
  | Code | When |
179
179
  | -------------------- | ----------------------------------------------- |
@@ -188,7 +188,7 @@ Available error codes:
188
188
  | `KernelError` | OCCT `Standard_Failure` (unclassified) |
189
189
  | `Unknown` | Error from outside the kernel |
190
190
 
191
- A fillet or chamfer that OCCT cannot build also sets `faultyEdges` to the edges, as passed in, whose contour failed. The raw message carries the same list as a ` [faulty edges: 3,7]` suffix.
191
+ When OCCT cannot build a fillet or chamfer, the error also has a `faultyEdges` field. It lists the edges, as you passed them in, whose contour failed. The raw message has the same list as a ` [faulty edges: 3,7]` suffix.
192
192
 
193
193
  ```typescript check kernel,a
194
194
  import { OcctError } from "occt-wasm";
@@ -204,14 +204,14 @@ try {
204
204
  ```
205
205
 
206
206
  > **`OcctWorker` is the exception.** Comlink serializes a thrown error down to
207
- > `{ message, name, stack }`, so an error crossing the worker boundary arrives
208
- > as a plain `Error`: the message survives intact, but `code`, `operation`, and
209
- > `instanceof OcctError` do not. Match on `e.message` there, or do the
210
- > `switch (e.code)` inside the worker.
207
+ > `{ message, name, stack }`. Thus an error that crosses the worker boundary
208
+ > arrives as a plain `Error`. The message survives intact, but `code`,
209
+ > `operation`, and `instanceof OcctError` do not. Match on `e.message` there, or
210
+ > do the `switch (e.code)` inside the worker.
211
211
 
212
212
  ## Named Enums
213
213
 
214
- Sweep, offset, and boolean operations use self-documenting enums instead of opaque numbers:
214
+ Sweep, offset, and boolean operations use named enums instead of opaque numbers:
215
215
 
216
216
  ```typescript check kernel,profile,spine,wire,shape,face,base,tool1,tool2
217
217
  import { TransitionMode, JoinType, BooleanOp, BooleanGlue } from "occt-wasm";
@@ -233,11 +233,11 @@ kernel.booleanPipeline(base, [BooleanOp.Cut, BooleanOp.Fuse], [tool1, tool2]);
233
233
  kernel.booleanOp(BooleanOp.Fuse, [base], [tool1, tool2], { glue: BooleanGlue.Shift });
234
234
  ```
235
235
 
236
- Numeric values (0, 1, 2) are still accepted for backwards compatibility.
236
+ These operations still accept numeric values (0, 1, 2) for backwards compatibility.
237
237
 
238
238
  ## Type Predicates
239
239
 
240
- Convenience methods for checking shape topology:
240
+ These convenience methods tell you whether a shape is a solid, face, edge, wire, vertex, shell, or compound:
241
241
 
242
242
  ```typescript check kernel,shape
243
243
  if (kernel.isSolid(shape)) {
@@ -287,11 +287,11 @@ const nurbs = await worker.kernel.getNurbsCurveData(edge);
287
287
  worker.terminate();
288
288
  ```
289
289
 
290
- The worker helper uses [Comlink](https://github.com/GoogleChromeLabs/comlink) (~1.2 KB gzipped) for transparent RPC. Each worker has its own WASM instance and arena -- shape handles are local to the worker.
290
+ The worker helper uses [Comlink](https://github.com/GoogleChromeLabs/comlink) (~1.2 KB gzipped) for transparent RPC. Each worker has its own WASM instance and arena, so shape handles are local to the worker.
291
291
 
292
292
  ## XCAF Assemblies
293
293
 
294
- Create assembly documents with colors, names, and component hierarchies. Colors are sRGB components in [0, 1], as in CSS (`#808080` is `128 / 255`), and names may be any Unicode text:
294
+ Create assembly documents with colors, names, and component hierarchies. Colors are sRGB components in [0, 1], as in CSS (`#808080` is `128 / 255`). Names can be any Unicode text:
295
295
 
296
296
  ```typescript check kernel,box,gear,stepData
297
297
  // Factory method auto-injects Emscripten FS for glTF export
@@ -315,7 +315,7 @@ doc.close();
315
315
  const imported = kernel.importXCAFFromSTEP(stepData);
316
316
  ```
317
317
 
318
- Walking an imported assembly: each component is a placed reference to a prototype label (a part or sub-assembly). Resolve it with `getReferredLabel` to reach the prototype's name, named sub-shapes and children. To author the same structure, add a compound with `doc.addShape(compound, { assembly: true })`.
318
+ In an imported assembly, each component is a placed reference to a prototype label (a part or sub-assembly). To walk the assembly, resolve each component with `getReferredLabel` to reach the name, named sub-shapes, and children of the prototype. To author the same structure, add a compound with `doc.addShape(compound, { assembly: true })`.
319
319
 
320
320
  ```typescript check doc
321
321
  import type { LabelTag } from "occt-wasm";
@@ -332,7 +332,7 @@ function walk(label: LabelTag, depth = 0): void {
332
332
  for (const root of doc.getRoots()) walk(root);
333
333
  ```
334
334
 
335
- `getLocation(label)` returns a component's placement as a 3x4 matrix in the layout `kernel.transform` accepts, so a prototype's geometry can be tessellated once and instanced per component.
335
+ `getLocation(label)` returns the placement of a component as a 3x4 matrix, in the layout that `kernel.transform` accepts. Thus you can tessellate the geometry of a prototype once and instance it for each component.
336
336
 
337
337
  ## Bundler Configuration
338
338
 
@@ -363,14 +363,15 @@ module.exports = {
363
363
  ```
364
364
 
365
365
  Webpack bundles the Emscripten glue and emits `occt-wasm.wasm` as a hashed
366
- asset, rewriting the URL it is loaded from. No manual copy step is needed, and
367
- `OcctKernel.init()` finds the binary without a `wasm` option.
366
+ asset. It also rewrites the URL that the glue loads the binary from. You do not
367
+ need a manual copy step, and `OcctKernel.init()` finds the binary without a
368
+ `wasm` option.
368
369
 
369
370
  ### Next.js
370
371
 
371
- No configuration needed, under either Turbopack or webpack. Both emit the
372
- `.wasm` into `_next/static` and rewrite the URL. Initialize from a client
373
- component (`"use client"`) so the kernel loads in the browser rather than
372
+ Next.js needs no configuration, with Turbopack or with webpack. Both emit the
373
+ `.wasm` into `_next/static` and rewrite the URL. Initialize the kernel from a
374
+ client component (`"use client"`), so that it loads in the browser and not
374
375
  during SSR:
375
376
 
376
377
  ```javascript
@@ -398,7 +399,7 @@ const kernel = await OcctKernel.init();
398
399
 
399
400
  ## API Reference
400
401
 
401
- Generate full docs locally: `cd ts && npm run docs` (TypeDoc output).
402
+ To generate the full docs locally, run `cd ts && npm run docs` (TypeDoc output).
402
403
 
403
404
  | Category | What's covered |
404
405
  | ---------------- | -------------------------------------------------------------------------------------------------------------- |
@@ -432,11 +433,11 @@ OCCT V8.0.1 C++ (git submodule)
432
433
  -> wasm-opt -O4 --converge --gufa -> dist/
433
434
  ```
434
435
 
435
- Built with Rust xtask (`cargo xtask build`), tested with Vitest.
436
+ A Rust xtask (`cargo xtask build`) builds the project, and Vitest runs the tests.
436
437
 
437
438
  ## Size & Performance
438
439
 
439
- Compared against other OCCT-to-WASM builds (all include STEP, XCAF, glTF):
440
+ This table compares occt-wasm with other OCCT-to-WASM builds. All of them include STEP, XCAF, and glTF:
440
441
 
441
442
  | Build | brotli |
442
443
  | ------------------ | ------- |
@@ -444,7 +445,7 @@ Compared against other OCCT-to-WASM builds (all include STEP, XCAF, glTF):
444
445
  | opencascade.js | ~9 MB |
445
446
  | brepjs-opencascade | ~5 MB |
446
447
 
447
- Run benchmarks locally: `npx tsx test/benchmark.ts`
448
+ To run the benchmarks locally, use `npx tsx test/benchmark.ts`.
448
449
 
449
450
  ## Development
450
451
 
@@ -466,7 +467,7 @@ node scripts/static-server.mjs
466
467
 
467
468
  ### Docker Build
468
469
 
469
- No local emsdk or Rust needed -- everything runs in the container.
470
+ You do not need a local emsdk or Rust. Everything runs in the container.
470
471
 
471
472
  ```bash
472
473
  npm run docker:build # Build image (OCCT layer cached after first run)
@@ -475,10 +476,10 @@ npm run docker:dist # Build + copy dist/ artifacts to host
475
476
 
476
477
  ## Browser Compatibility
477
478
 
478
- occt-wasm requires modern browsers with WASM SIMD, tail calls, and exception
479
- handling. WASM **tail calls** are the newest and therefore binding requirement —
480
- they gate the minimum versions below. The versions listed are the lowest
481
- combinations verified to load the kernel:
479
+ occt-wasm requires a browser with WASM SIMD, tail calls, and exception handling.
480
+ WASM **tail calls** are the newest of these requirements, so they set the minimum
481
+ versions in the table. The versions in the table are the lowest combinations
482
+ verified to load the kernel:
482
483
 
483
484
  | Browser | Minimum (verified) | Notes |
484
485
  | ------- | ------------------ | ------------------------------------------- |
@@ -487,27 +488,30 @@ combinations verified to load the kernel:
487
488
  | Safari | 17.2+ | Earliest WebKit verified to load the kernel |
488
489
  | Firefox | 121+ | Tail calls shipped in 121; 146 is verified |
489
490
 
490
- Node.js 22+ is recommended (tail calls via V8). Node.js 18+ works if your V8 version supports the required WASM features.
491
+ The recommended Node.js version is 22+ (tail calls through V8). Node.js 18+ works if your V8 version supports the required WASM features.
491
492
 
492
493
  ## Known Limitations
493
494
 
494
495
  These are upstream OCCT V8.0.1 issues, not occt-wasm bugs:
495
496
 
496
- - **IGES** -- TKDEIGES excluded from link; no IGES import/export
497
- - **Zero-length extrusion** -- WASM exception escapes JS catch boundary (1 test skip)
498
- - **Single WASM thread** -- each kernel instance is single-threaded; use `OcctWorker` (see above) to move work off the main thread
497
+ - **IGES**: the build does not link TKDEIGES, so there is no IGES import/export.
498
+ - **Zero-length extrusion**: a WASM exception escapes the JS catch boundary, so the test suite skips 1 test.
499
+ - **Single WASM thread**: each kernel instance is single-threaded. Use `OcctWorker` (see above) to move work off the main thread.
499
500
 
500
- These will be addressed as upstream OCCT and browser support improve.
501
+ These limits depend on upstream OCCT and on browser support.
501
502
 
502
- OCCT V8.0.1 (2026-07) resolved several upstream hangs and crashes that
503
- affected modeling here: an infinite-loop guard in the boolean section
504
- algorithm, crash guards in chamfer construction (`ChFi3d_Builder`) and
505
- `BRep_Tool::CurveOnPlane`, null-pcurve guards in `UnifySameDomain`, and
506
- an infinite-loop guard in the STEP writer.
503
+ OCCT V8.0.1 (2026-07) includes these fixes for upstream hangs and crashes that
504
+ affected modeling here:
505
+
506
+ - An infinite-loop guard in the boolean section algorithm.
507
+ - Crash guards in chamfer construction (`ChFi3d_Builder`) and
508
+ `BRep_Tool::CurveOnPlane`.
509
+ - Null-pcurve guards in `UnifySameDomain`.
510
+ - An infinite-loop guard in the STEP writer.
507
511
 
508
512
  ## Contributing
509
513
 
510
- This project is open source. Bug reports and feature requests are welcome via GitHub Issues. For pull requests, please open an issue first to discuss the change.
514
+ This project is open source. Bug reports and feature requests are welcome in GitHub Issues. Before you open a pull request, open an issue to discuss the change.
511
515
 
512
516
  ## License
513
517
 
@@ -515,4 +519,4 @@ This project is open source. Bug reports and feature requests are welcome via Gi
515
519
 
516
520
  **Compiled WASM output**: LGPL-2.1-only (inherits from [OCCT](https://dev.opencascade.org/resources/download))
517
521
 
518
- The LGPL requires that end users can replace the LGPL component. For web applications, this is satisfied by loading the `.wasm` file from a URL (which users can override via `OcctKernel.init({ wasm: '...' })`). If you ship a desktop app with the WASM embedded, consult the [LGPL-2.1 FAQ](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html).
522
+ The LGPL requires that end users can replace the LGPL component. A web application meets this requirement when it loads the `.wasm` file from a URL. Users can override that URL with `OcctKernel.init({ wasm: '...' })`. If you ship a desktop app with the WASM embedded, read the [GNU licenses FAQ](https://www.gnu.org/licenses/gpl-faq.html), which covers the LGPL.
package/dist/index.d.ts CHANGED
@@ -513,9 +513,9 @@ export declare class OcctKernel {
513
513
  /**
514
514
  * Volume of a solid (or the signed volume a closed shell encloses).
515
515
  *
516
- * Planar and other elementary faces are integrated exactly; BSpline and
517
- * Bezier faces, and faces trimmed by BSpline curves, adaptively to a
518
- * relative error near 1e-7. {@link OcctKernel.getSurfaceArea},
516
+ * Planar and other elementary faces are integrated exactly; BSpline,
517
+ * Bezier, swept and offset faces, and faces trimmed by BSpline curves,
518
+ * adaptively to a relative error near 1e-7. {@link OcctKernel.getSurfaceArea},
519
519
  * {@link OcctKernel.getCenterOfMass} and {@link OcctKernel.getInertia}
520
520
  * integrate the same way.
521
521
  */
package/dist/index.js CHANGED
@@ -1075,9 +1075,9 @@ export class OcctKernel {
1075
1075
  /**
1076
1076
  * Volume of a solid (or the signed volume a closed shell encloses).
1077
1077
  *
1078
- * Planar and other elementary faces are integrated exactly; BSpline and
1079
- * Bezier faces, and faces trimmed by BSpline curves, adaptively to a
1080
- * relative error near 1e-7. {@link OcctKernel.getSurfaceArea},
1078
+ * Planar and other elementary faces are integrated exactly; BSpline,
1079
+ * Bezier, swept and offset faces, and faces trimmed by BSpline curves,
1080
+ * adaptively to a relative error near 1e-7. {@link OcctKernel.getSurfaceArea},
1081
1081
  * {@link OcctKernel.getCenterOfMass} and {@link OcctKernel.getInertia}
1082
1082
  * integrate the same way.
1083
1083
  */
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "occt-wasm",
3
- "version": "5.17.1",
3
+ "version": "5.17.2",
4
4
  "description": "OpenCascade (OCCT) compiled to WebAssembly with a clean TypeScript API",
5
5
  "type": "module",
6
6
  "exports": {