@meshioplusplus/wasm 17.0.0 → 17.2.0

package/index.d.ts

@@ -367,6 +367,13 @@ export interface IgaOptions {
   trim?: boolean;
 }
 
+/**
+ * A B-rep in CAD JSON's shape: what a `cad_json` file holds, what `fitCad`
+ * returns as `info`, and -- in the full artifact -- what reading a `step` or
+ * `iges` file with `{info: true}` returns (still `format: 'cad_json'`, so
+ * `writeMesh(path, mesh, 'cad_json', {info})` and the `iga*` operations take
+ * it unchanged).
+ */
 export interface CadJsonInfo {
   format: 'cad_json';
   /** The face surfaces: two degrees, two full knot vectors, (points, 3) control net (u fastest). */
@@ -1695,14 +1702,37 @@ export interface MeshioPlusPlusModule {
    */
   hasCgnslib(): boolean;
 
+  /**
+   * Whether OpenCASCADE is linked in, so `step` and `iges` read and `fitCad`
+   * runs: true in the full artifact (`{full: true}`), false in the lean one.
+   */
+  hasOcct(): boolean;
+
+  /** Whether the VTK XML zstd block codec is linked in (the full artifact). */
+  hasZstd(): boolean;
+
+  /** Whether the VTK XML lz4 block codec is linked in (the full artifact). */
+  hasLz4(): boolean;
+
+  /** Whether bzip2 is linked in, for libMesh `.xda.bz2`/`.xdr.bz2` (the full artifact). */
+  hasBzip2(): boolean;
+
+  /**
+   * Which artifact loaded: `'lean'` (`meshioplusplus_wasm[_mt]`, MIT) or
+   * `'full'` (`meshioplusplus_wasm_full[_mt]`, with OpenCASCADE, zstd, lz4 and
+   * bzip2; mixed licence, see the package's THIRD_PARTY_NOTICES.md).
+   */
+  buildFlavour(): 'lean' | 'full';
+
   /**
    * The format names this build can actually read and write, both sorted.
    *
    * Prefer this over a hardcoded table when building a file-picker filter or a
-   * "convert to" menu: the two lists genuinely differ (`openfoam` is
-   * read-only, `gltf` and `step` are write-only), and the set depends on how
+   * "convert to" menu: the two lists genuinely differ (`gmsh22` is
+   * write-only), and the set depends on how
    * the artifact was built -- an official build carries the HDF5/netCDF-backed
-   * formats, one built with `--without-hdf5` does not.
+   * formats, one built with `--without-hdf5` does not, and `step` and `iges`
+   * are readers only in the full artifact.
    */
   availableFormats(): { readers: string[]; writers: string[] };
 
@@ -2516,6 +2546,18 @@ export interface MeshioPlusPlusModule {
     numUnfitted: number;
   };
 
+  /**
+   * Build a CAD solid from the fitted patches of a closed skin (normally the
+   * output of `segment` then `fitPrimitives`): planes, spheres, cylinders,
+   * cones and tori, fillets and blends, threads and freeform B-spline faces,
+   * sewn and checked by OpenCASCADE, optionally written as STEP to
+   * `stepPath` on the virtual FS. Needs OpenCASCADE: the full artifact only.
+   * See doc/fit_cad.md.
+   * @throws {Error} in the lean artifact (naming `{full: true}`), on a bad
+   *   option, or on a skin that is not closed.
+   */
+  fitCad(mesh: Mesh, options?: FitCadOptions): FitCadResult;
+
   /**
    * Refine every patch (every face surface of a B-rep) of a NURBS model
    * exactly: degree elevation by `elevate`, then knot insertion splitting each
@@ -3197,16 +3239,104 @@ export interface MeshioPlusPlusModule {
  *   `locateFile`/`onAbort` wrapped for diagnostics (your own overrides still
  *   run first) -- see {@link MeshioPlusPlusLoadError}. `locateFile` receives
  *   the requested filename, so return the URL matching the loaded variant
- *   (`meshioplusplus_wasm.wasm` or `meshioplusplus_wasm_mt.wasm`).
+ *   (`meshioplusplus_wasm.wasm` or `meshioplusplus_wasm_mt.wasm`, and their
+ *   `_full` counterparts with `full`).
  * @param options.variant which native artifact to load: `'auto'` (default),
  *   `'mt'` (force threaded), or `'seq'` (force sequential).
+ * @param options.full load the full artifact (OpenCASCADE, zstd, lz4, bzip2;
+ *   mixed licence) rather than the lean, MIT one. Only the chosen artifact's
+ *   bytes are fetched.
+ * @param options.fullGlue where the full artifact's glue module lives, for a
+ *   bundled app that copied `dist/meshioplusplus_wasm_full*.{mjs,wasm}`
+ *   itself; the loader never names the full glue literally, so a bundler
+ *   does not pull it into a lean bundle.
  * @throws {MeshioPlusPlusLoadError} if the WASM module fails to instantiate.
  */
 export function loadMeshioPlusPlus(
     moduleOverrides?: ModuleOverrides,
-    options?: { variant?: 'auto' | 'mt' | 'seq' },
+    options?: LoadOptions,
 ): Promise<MeshioPlusPlusModule>;
 
+/** The second argument of {@link loadMeshioPlusPlus}. */
+export interface LoadOptions {
+  variant?: 'auto' | 'mt' | 'seq';
+  full?: boolean;
+  fullGlue?: string | URL;
+}
+
+/** The options of {@link MeshioPlusPlusModule.fitCad}; every key is optional. */
+export interface FitCadOptions {
+  /** Write the solid as AP214 STEP here (virtual FS); omitted writes nothing. */
+  stepPath?: string;
+  /** The largest distance a face may lie from the skin; <= 0 is automatic. */
+  tolerance?: number;
+  /** Try the exact intersection of two analytic surfaces first (default true). */
+  exactEdges?: boolean;
+  /** The accepted primitive types that become analytic faces (default: all five). */
+  types?: Array<'plane' | 'sphere' | 'cylinder' | 'cone' | 'torus'>;
+  /** The re-meshed solid's chordal deflection; <= 0 takes tolerance / 4. */
+  meshDeflection?: number;
+  /** Rounds of demoting failed faces before every patch is faceted (default 8). */
+  maxDemotionRounds?: number;
+  /** Try a freeform B-spline face where no primitive fits (default true). */
+  freeform?: boolean;
+  /** The freeform B-spline's highest degree, 3 to 8 (default 3). */
+  freeformDegree?: number;
+  /** The most grid points per direction a freeform fit samples (default 64). */
+  freeformMaxControl?: number;
+  /** Split a freeform patch that folds over every flattening (default true). */
+  freeformSplit?: boolean;
+  /** Try fillets, blends, chamfers and vertex blends (default true). */
+  fillets?: boolean;
+  /** Try thread faces, tapered and of varying pitch included (default true). */
+  threads?: boolean;
+}
+
+/** What {@link MeshioPlusPlusModule.fitCad} built. */
+export interface FitCadResult {
+  /** The solid re-meshed, with `fit_cad:face`, `fit_cad:type` and `fit_cad:patch` cell data. */
+  mesh: Mesh;
+  /** Whether the solid passed OpenCASCADE's B-rep check. */
+  valid: boolean;
+  tolerance: number;
+  volume: number;
+  skinVolume: number;
+  volumeRatio: number;
+  /** Symmetric Hausdorff distance, skin to re-meshed solid. */
+  maxDeviation: number;
+  numFaces: number;
+  numPlane: number;
+  numSphere: number;
+  numCylinder: number;
+  numCone: number;
+  numTorus: number;
+  numFacetedFaces: number;
+  numPatches: number;
+  numDemoted: number;
+  numExactEdges: number;
+  numApproxEdges: number;
+  numSolids: number;
+  numBspline: number;
+  numSplitPatches: number;
+  numFillet: number;
+  numHelical: number;
+  numVariableFillet: number;
+  numBlend: number;
+  numRoundedThread: number;
+  /** Vertex blends (setback corners), type 9. */
+  numVertexBlend: number;
+  /** Chamfers (straight-section blends), type 10. */
+  numChamfer: number;
+  /** Fillet faces whose section is a conic rather than a circle. */
+  numConicBlend: number;
+  /** Thread flanks on a tapered (conical) thread. */
+  numTaperedThread: number;
+  /** Thread flanks whose pitch varies along the axis. */
+  numVariablePitchThread: number;
+  /** The solid's B-rep, for `writeMesh(path, mesh, 'cad_json', {info})`. */
+  info: CadJsonInfo;
+}
+
 /** Overrides forwarded to the underlying Emscripten module factory. */
 export interface ModuleOverrides {
   /**
@@ -3234,6 +3364,8 @@ export interface MeshioPlusPlusLoadError extends Error {
   name: 'MeshioPlusPlusLoadError';
   /** Which native artifact was being loaded. */
   variant: 'mt' | 'seq';
+  /** Whether it was the full artifact. */
+  full: boolean;
   /** The glue module specifier (e.g. '../dist/meshioplusplus_wasm_mt.mjs'). */
   glue: string;
   /** The filename Emscripten asked `locateFile` to resolve, if it got that far. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@meshioplusplus/wasm",
-  "version": "17.0.0",
-  "description": "meshio++ mesh I/O compiled to WebAssembly: read 76 and write 68 mesh formats (incl. MED, CGNS, Exodus) in the browser or Node.js",
+  "version": "17.2.0",
+  "description": "meshio++ mesh I/O compiled to WebAssembly: read 80 and write 75 mesh formats (incl. MED, CGNS, Exodus; STEP and IGES in the full build) in the browser or Node.js",
   "type": "module",
   "main": "./src/index.mjs",
   "module": "./src/index.mjs",
@@ -12,8 +12,13 @@
     "dist/meshioplusplus_wasm.wasm",
     "dist/meshioplusplus_wasm_mt.mjs",
     "dist/meshioplusplus_wasm_mt.wasm",
+    "dist/meshioplusplus_wasm_full.mjs",
+    "dist/meshioplusplus_wasm_full.wasm",
+    "dist/meshioplusplus_wasm_full_mt.mjs",
+    "dist/meshioplusplus_wasm_full_mt.wasm",
     "index.d.ts",
-    "README.md"
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "engines": {
     "node": ">=18"
@@ -29,9 +34,12 @@
     "obj",
     "finite-elements",
     "fem",
+    "step",
+    "iges",
+    "cad",
     "scientific-computing"
   ],
-  "license": "MIT",
+  "license": "MIT AND (LGPL-2.1-only WITH OCCT-exception-1.0)",
   "author": "Vicente Mataix Ferrandiz",
   "homepage": "https://github.com/loumalouomega/meshioplusplus",
   "repository": {

package/src/index.mjs

@@ -29,6 +29,16 @@
 // context, else the sequential one. The dynamic import()s are literal so
 // bundlers (Vite) emit both chunks. Callers can force a build with the
 // `{ variant }` option.
+//
+// Beside that lean pair the package ships the FULL pair (roadmap 6.2),
+// meshioplusplus_wasm_full and meshioplusplus_wasm_full_mt: the same API, with
+// OpenCASCADE (STEP/IGES reading, fitCad), zstd, lz4 and bzip2 linked in, and
+// a mixed licence (OpenCASCADE is LGPL-2.1 with its exception; see
+// THIRD_PARTY_NOTICES.md). `{ full: true }` loads it, with the same variant
+// choice. Its import() is deliberately NOT literal: a bundler that saw it would
+// pull the full bytes into every lean consumer's bundle. Node and native
+// browser ESM resolve it next to this file; a bundled app copies the full
+// glue and .wasm itself and passes `fullGlue` (and `locateFile`).
 
 // The raw xdmfSeriesWriteDataArrays embind call still converts every value
 // with emscripten::convertJSArrayToNumberVector<double>, which throws on a
@@ -61,6 +71,17 @@ function resolveVariant(variant) {
     return crossOriginIsolated ? 'mt' : 'seq';
 }
 
+/**
+ * The glue module of the full artifact for a variant, relative to this file.
+ * @param {'mt'|'seq'} chosen
+ * @returns {string}
+ */
+function fullGlueFor(chosen) {
+    return chosen === 'mt'
+        ? '../dist/meshioplusplus_wasm_full_mt.mjs'
+        : '../dist/meshioplusplus_wasm_full.mjs';
+}
+
 /**
  * Thrown by `loadMeshioPlusPlus()` when a WASM module fails to instantiate,
  * so a caller can tell a wrong `.wasm` URL from an environment that cannot
@@ -72,6 +93,7 @@ export class MeshioPlusPlusLoadError extends Error {
      * @param {string} message
      * @param {object} details
      * @param {'mt'|'seq'} details.variant - which artifact was being loaded.
+     * @param {boolean} [details.full] - whether it was the full artifact.
      * @param {string} details.glue - the glue module specifier (e.g.
      *   '../dist/meshioplusplus_wasm_mt.mjs').
      * @param {string} [details.requestedFile] - the filename Emscripten asked
@@ -79,10 +101,11 @@ export class MeshioPlusPlusLoadError extends Error {
      * @param {string} [details.resolvedUrl] - what `locateFile` returned for it.
      * @param {unknown} [details.cause] - the underlying error/abort reason.
      */
-    constructor(message, { variant, glue, requestedFile, resolvedUrl, cause }) {
+    constructor(message, { variant, full = false, glue, requestedFile, resolvedUrl, cause }) {
         super(message, cause === undefined ? undefined : { cause });
         this.name = 'MeshioPlusPlusLoadError';
         this.variant = variant;
+        this.full = full;
         this.glue = glue;
         this.requestedFile = requestedFile;
         this.resolvedUrl = resolvedUrl;
@@ -190,12 +213,19 @@ export class MeshioPlusPlusLoadError extends Error {
  *   `{ locateFile: (p) => new URL(p, import.meta.url) }` relocates the
  *   `.wasm` binary for a bundler/CDN setup; `locateFile` receives the
  *   requested filename, so return the URL matching the loaded variant
- *   (`meshioplusplus_wasm.wasm` or `_wasm_mt.wasm`).
+ *   (`meshioplusplus_wasm.wasm` or `_wasm_mt.wasm`, and `_wasm_full.wasm` or
+ *   `_wasm_full_mt.wasm` with `full`).
  * @param {object} [options]
  * @param {'auto'|'mt'|'seq'} [options.variant='auto'] - which native artifact to
  *   load. `auto` picks the threaded (`mt`) build under Node and in a
  *   cross-origin-isolated browser, else the sequential (`seq`) build; `mt`/`seq`
  *   force one (`mt` aborts if the environment cannot host Wasm threads).
+ * @param {boolean} [options.full=false] - load the full artifact (OpenCASCADE,
+ *   zstd, lz4, bzip2; mixed licence) instead of the lean, MIT one. The lean
+ *   bytes are never fetched then, nor the full ones without it.
+ * @param {string|URL} [options.fullGlue] - where the full artifact's glue module
+ *   lives, for a bundled app that copied it (default: `../dist/` beside this
+ *   file). Pair it with a `locateFile` that finds the matching `.wasm`.
  * @returns {Promise<{
  *   FS: object,
  *   readMesh: (path: string, format?: string) => Mesh,
@@ -218,6 +248,11 @@ export class MeshioPlusPlusLoadError extends Error {
  *   meshBackend: () => string,
  *   parallelBackend: () => string,
  *   hasCgnslib: () => boolean,
+ *   hasOcct: () => boolean,
+ *   hasZstd: () => boolean,
+ *   hasLz4: () => boolean,
+ *   hasBzip2: () => boolean,
+ *   buildFlavour: () => 'lean' | 'full',
  *   availableFormats: () => {readers: string[], writers: string[]},
  *   extractSurface: (mesh: Mesh, recordParentIds?: boolean) => Mesh,
  *   extractSkin: (mesh: Mesh, linearize?: boolean) => Mesh,
@@ -260,6 +295,7 @@ export class MeshioPlusPlusLoadError extends Error {
  *   igaSample: (info: object, options?: {sampleSubdivisions?: number, trimSamples?: number, edges?: boolean, trim?: boolean}) => {mesh: Mesh, info: object},
  *   igaEvaluate: (info: object, patch: number, params: ArrayLike<number>, options?: {derivatives?: 0 | 1, trimSamples?: number}) => object,
  *   fitPrimitives: (mesh: Mesh, patchData?: string, tolerance?: number, relative?: boolean, minInlierFraction?: number, types?: string[], maxIterations?: number) => {mesh: Mesh, numPatches: number, numPlane: number, numSphere: number, numCylinder: number, numCone: number, numTorus: number, numUnfitted: number},
+ *   fitCad: (mesh: Mesh, options?: {stepPath?: string, tolerance?: number, exactEdges?: boolean, types?: string[], meshDeflection?: number, maxDemotionRounds?: number, freeform?: boolean, freeformDegree?: number, freeformMaxControl?: number, freeformSplit?: boolean, fillets?: boolean, threads?: boolean}) => object,
  *   tessellate: (mesh: Mesh, levels?: number, curved?: boolean, fields?: boolean, recordStencil?: boolean) => {mesh: Mesh, numSourcePoints: number, numSourceCells: number, numCurvedSourceCells: number, numPassThroughSourceCells: number, numPoints: number, numCells: number, numBoundaryFacets: number, numInteriorFacets: number, numFacetsWithBadCount: number},
  *   render: (mesh: Mesh, options?: RenderOptions) => RenderedFrame,
  *   renderText: (mesh: Mesh, options?: RenderOptions, text?: RenderTextOptions) => string,
@@ -314,16 +350,43 @@ export class MeshioPlusPlusLoadError extends Error {
  * }>}
  * @throws {MeshioPlusPlusLoadError} if the WASM module fails to instantiate.
  */
-export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto' } = {}) {
+export async function loadMeshioPlusPlus(
+    moduleOverrides = {},
+    { variant = 'auto', full = false, fullGlue } = {},
+) {
     const chosen = resolveVariant(variant);
-    const glue =
-        chosen === 'mt' ? '../dist/meshioplusplus_wasm_mt.mjs' : '../dist/meshioplusplus_wasm.mjs';
-    // Literal specifiers so bundlers emit both chunks; the sequential one is
-    // the fallback whenever threads are unavailable.
-    const { default: createRawModule } =
-        chosen === 'mt'
-            ? await import('../dist/meshioplusplus_wasm_mt.mjs')
-            : await import('../dist/meshioplusplus_wasm.mjs');
+    const flavour = full ? 'full' : 'lean';
+    const label = full ? `full ${chosen}` : chosen;
+    let glue;
+    let createRawModule;
+    if (full) {
+        glue = String(fullGlue ?? fullGlueFor(chosen));
+        // A computed specifier on purpose (see the header): bundlers leave it
+        // alone, so a lean bundle never carries the full artifact.
+        try {
+            ({ default: createRawModule } = await import(
+                /* @vite-ignore */ /* webpackIgnore: true */ fullGlue === undefined
+                    ? new URL(glue, import.meta.url).href
+                    : glue
+            ));
+        } catch (cause) {
+            throw new MeshioPlusPlusLoadError(
+                `meshio++ (wasm): cannot import the full artifact's glue (${glue}): ` +
+                    `${cause.message ?? cause}. A bundled app copies ` +
+                    "dist/meshioplusplus_wasm_full*.{mjs,wasm} and passes `fullGlue`.",
+                { variant: chosen, full, glue, cause },
+            );
+        }
+    } else {
+        glue =
+            chosen === 'mt' ? '../dist/meshioplusplus_wasm_mt.mjs' : '../dist/meshioplusplus_wasm.mjs';
+        // Literal specifiers so bundlers emit both chunks; the sequential one
+        // is the fallback whenever threads are unavailable.
+        ({ default: createRawModule } =
+            chosen === 'mt'
+                ? await import('../dist/meshioplusplus_wasm_mt.mjs')
+                : await import('../dist/meshioplusplus_wasm.mjs'));
+    }
 
     // Wrap locateFile/onAbort (rather than passing moduleOverrides through
     // untouched) so a failed instantiation can be reported with which file
@@ -355,10 +418,10 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         Module = await createRawModule(wrappedOverrides);
     } catch (cause) {
         throw new MeshioPlusPlusLoadError(
-            `meshio++ (wasm): failed to instantiate the '${chosen}' variant (${glue}): ` +
+            `meshio++ (wasm): failed to instantiate the '${label}' variant (${glue}): ` +
                 `${abortReason ?? cause.message ?? cause}. Emscripten requested ` +
                 `'${requestedFile}' and locateFile returned '${resolvedUrl}'.`,
-            { variant: chosen, glue, requestedFile, resolvedUrl, cause },
+            { variant: chosen, full, glue, requestedFile, resolvedUrl, cause },
         );
     }
 
@@ -371,11 +434,25 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
     const actualBackend = Module.parallelBackend();
     if (actualBackend !== expectedBackend) {
         throw new MeshioPlusPlusLoadError(
-            `meshio++ (wasm): failed to instantiate the '${chosen}' variant (${glue}): ` +
+            `meshio++ (wasm): failed to instantiate the '${label}' variant (${glue}): ` +
                 `loaded, but reports parallel backend '${actualBackend}' (expected ` +
                 `'${expectedBackend}') -- locateFile likely returned the wrong .wasm binary. ` +
                 `Emscripten requested '${requestedFile}' and locateFile returned '${resolvedUrl}'.`,
-            { variant: chosen, glue, requestedFile, resolvedUrl },
+            { variant: chosen, full, glue, requestedFile, resolvedUrl },
+        );
+    }
+    // The same tell for the lean/full split: the two share the whole export
+    // surface, so a lean .wasm behind the full glue (or the reverse) can link.
+    // A binary from before buildFlavour existed is a lean one.
+    const actualFlavour =
+        typeof Module.buildFlavour === 'function' ? Module.buildFlavour() : 'lean';
+    if (actualFlavour !== flavour) {
+        throw new MeshioPlusPlusLoadError(
+            `meshio++ (wasm): failed to instantiate the '${label}' variant (${glue}): ` +
+                `loaded, but reports the '${actualFlavour}' artifact (expected '${flavour}') -- ` +
+                `locateFile likely returned the wrong .wasm binary. Emscripten requested ` +
+                `'${requestedFile}' and locateFile returned '${resolvedUrl}'.`,
+            { variant: chosen, full, glue, requestedFile, resolvedUrl },
         );
     }
 
@@ -523,10 +600,17 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         // meshioplusplus_wasm_mt one -- which of the two this instance loaded.
         parallelBackend: () => Module.parallelBackend(),
         hasCgnslib: () => Module.hasCgnslib(),
+        // The full artifact's libraries (roadmap 6.2): all four are true there
+        // and false in the lean one. buildFlavour() names which loaded.
+        hasOcct: () => Module.hasOcct(),
+        hasZstd: () => Module.hasZstd(),
+        hasLz4: () => Module.hasLz4(),
+        hasBzip2: () => Module.hasBzip2(),
+        buildFlavour: () => Module.buildFlavour(),
         // What this build can actually read/write, both sorted. Prefer this
-        // over a hardcoded table: a few formats are read-only (openfoam) or
-        // write-only (gltf), and the HDF5/netCDF-backed ones are present
-        // only in a build that linked them (the official artifact does).
+        // over a hardcoded table: a few formats are write-only (gmsh22), and the
+        // HDF5/netCDF-backed ones are present only in a build that linked them
+        // (the official artifact does).
         availableFormats: () => Module.availableFormats(),
         // Mesh operations (see doc/*.md per operation): computations ON a mesh,
         // not file formats. Index maps (crop/split/convertCells) are not carried
@@ -862,6 +946,8 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         ) =>
             Module.fitPrimitives(mesh, patchData, tolerance, relative, minInlierFraction,
                 Array.isArray(types) ? types : [types], maxIterations),
+        // OpenCASCADE: the full artifact only; the lean one throws by name.
+        fitCad: (mesh, options = {}) => Module.fitCad(mesh, options),
         igaRefine: (info, options = {}) => Module.igaRefine(info, options),
         igaSample: (info, options = {}) => Module.igaSample(info, options),
         igaEvaluate: (info, patch, params, options = {}) =>