@meshioplusplus/wasm 9.14.0 → 9.25.0

package/index.d.ts

@@ -294,6 +294,49 @@ export type OpSpec =
       location?: 'point' | 'cell';
       output?: string;
       component?: number;
+    }
+  | {
+      /**
+       * A regular grid around the mesh. One of the two steps that replace their
+       * input's geometry rather than transforming it: what comes out is a
+       * lattice, not the mesh that went in. Give exactly one of `resolution` and
+       * `cellSize`.
+       */
+      op: 'voxelize';
+      resolution?: number[];
+      cellSize?: number;
+      bounds?: number[];
+      padding?: number;
+      paddingRelative?: number;
+      fill?: VoxelFill;
+      attachOccupancy?: boolean;
+      maxCells?: number;
+      sign?: SdfSign;
+    }
+  | {
+      /**
+       * A signed distance field: a grid over the mesh's surface, filled. Like
+       * `voxelize` it replaces the geometry — what comes out is the grid,
+       * carrying `sdf:distance`. `structure: 'octree'` refines only near the
+       * surface and sizes itself from `rootResolution`/`maxDepth`, so passing
+       * `resolution` or `cellSize` with it is an error; its output is
+       * 1-irregular (it has hanging nodes).
+       */
+      op: 'computeSdf';
+      structure?: SdfStructure;
+      resolution?: number[];
+      cellSize?: number;
+      bounds?: number[];
+      padding?: number;
+      paddingRelative?: number;
+      rootResolution?: number;
+      maxDepth?: number;
+      bandCells?: number;
+      recordLevels?: boolean;
+      maxCells?: number;
+      sign?: SdfSign;
+      location?: SdfLocation;
+      band?: number;
     };
 
 /** Per-operation counters and caveats from a pipeline run. */
@@ -305,6 +348,18 @@ export interface OpReport {
 /** `gradient`'s differential operator. See doc/gradient.md. */
 export type GradientOperator = 'gradient' | 'divergence' | 'curl';
 
+/** Which cells `voxelize` keeps. See doc/voxelize.md. */
+export type VoxelFill = 'all' | 'surface' | 'inside';
+
+/** How a signed distance decides which side of the surface a point is on. */
+export type SdfSign = 'unsigned' | 'pseudonormal' | 'winding-number';
+
+/** Where a distance is evaluated on a mesh. */
+export type SdfLocation = 'corner' | 'center';
+
+/** What to do about a surface that is not watertight. */
+export type SdfWatertightCheck = 'off' | 'warn' | 'error';
+
 /** `gradient`'s reconstruction method. See doc/gradient.md. */
 export type GradientMethod = 'green-gauss' | 'least-squares';
 
@@ -327,6 +382,12 @@ export type NanPolicy = 'ignore' | 'replace' | 'fail';
 /** Cell-keeping rule for the crop operations: every node inside, or any. */
 export type CropMode = 'all' | 'any';
 
+/** Comparison for `cropPredicate` — the same vocabulary `refine`'s selector uses. */
+export type CropCompare = '<' | '<=' | '>' | '>=' | '==' | '!=';
+
+/** What `computeSdf` generates to carry the field. */
+export type SdfStructure = 'voxel' | 'octree';
+
 /** Partitioning criterion for `split`. */
 export type SplitBy = 'type' | 'component' | 'region' | 'tag';
 
@@ -787,6 +848,14 @@ export interface MeshioPlusPlusModule {
    */
   parallelBackend(): string;
 
+  /**
+   * Whether the optional cgnslib (CGNS MLL) backend is linked in.
+   *
+   * CGNS works either way; this reports whether ADF-backed containers and the
+   * CGNS 3.x `NGON_n` section layout are reachable.
+   */
+  hasCgnslib(): boolean;
+
   /**
    * The format names this build can actually read and write, both sorted.
    *
@@ -916,6 +985,34 @@ export interface MeshioPlusPlusModule {
     recordIds?: boolean,
   ): Mesh;
 
+  /**
+   * Subset a mesh to the cells whose value in a scalar `cell_data` array
+   * satisfies a comparison.
+   *
+   * Deliberately general rather than inside/outside-a-surface specific:
+   * inside/outside composes as `distanceToSurface(m, skin, 'pseudonormal',
+   * 'center')` then `cropPredicate(field.mesh, 'sdf:distance', '<', 0)`, and the
+   * same one mode also crops by `quality:*`, by a material id, or by anything
+   * `dataCalc` can produce.
+   *
+   * There is **no `mode`**: `cropBbox`/`cropPlane` test *points* and then need
+   * an all/any rule, whereas a `cell_data` predicate is already one value per
+   * cell and has nothing to reduce.
+   *
+   * **A non-finite cell value never matches**, whatever the comparison —
+   * `attachQuality` reports NaN where a metric does not apply.
+   * @throws {Error} when `array` is not a scalar `cell_data` array covering
+   *   every block, or the comparison is not one of `<`, `<=`, `>`, `>=`, `==`,
+   *   `!=`.
+   */
+  cropPredicate(
+    mesh: Mesh,
+    array: string,
+    compare?: CropCompare,
+    value?: number,
+    recordIds?: boolean,
+  ): Mesh;
+
   /**
    * Planar cross-section of a mesh (marching tetrahedra on a simplexified
    * input): a volume mesh yields a triangle/quad surface, a 2D surface mesh a
@@ -945,6 +1042,120 @@ export interface MeshioPlusPlusModule {
     recordParentIds?: boolean,
   ): Mesh;
 
+  /**
+   * A regular hexahedron lattice from nothing — the only entry point here that
+   * creates a mesh rather than transforming one. Points run x fastest, then y,
+   * then z; every cell is a right parallelepiped.
+   * @throws {Error} on a negative cell count, a non-positive spacing, or a grid
+   *   above `maxCells`.
+   */
+  grid(dims: number[], origin?: number[] | null, spacing?: number[] | null,
+       maxCells?: number): Mesh;
+
+  /**
+   * Build a regular grid around a mesh. Give exactly one of `resolution` and
+   * `cellSize`; `fill` selects the whole bounding box, only the cells a triangle
+   * passes through, or only the cells inside the surface.
+   * @throws {Error} when neither or both size options are given, on an unknown
+   *   `fill`/`sign`, or when the grid exceeds `maxCells`.
+   */
+  voxelize(
+    mesh: Mesh,
+    resolution?: number[] | null,
+    cellSize?: number,
+    bounds?: number[] | null,
+    padding?: number,
+    paddingRelative?: number,
+    fill?: VoxelFill,
+    sign?: SdfSign,
+    attachOccupancy?: boolean,
+    maxCells?: number,
+    watertightCheck?: SdfWatertightCheck,
+  ): {
+    mesh: Mesh;
+    dims: number[];
+    origin: number[];
+    spacing: number[];
+    numOccupied: number;
+  };
+
+  /** What is wrong with a surface, in numbers rather than a bare flag. */
+  surfaceWatertightCheck(mesh: Mesh): {
+    boundaryEdges: number;
+    nonManifoldEdges: number;
+    inconsistentPairs: number;
+    degenerateTriangles: number;
+    watertight: boolean;
+  };
+
+  /**
+   * Signed distances from a flat `[x0,y0,z0, x1,y1,z1, …]` array of query points
+   * to a surface. Negative is inside.
+   * @throws {Error} when the array length is not a multiple of three, or the
+   *   surface has no triangles.
+   */
+  sampleDistance(surface: Mesh, points: number[], sign?: SdfSign, band?: number,
+                 watertightCheck?: SdfWatertightCheck): Float64Array;
+
+  /**
+   * Attach the signed distance from a query mesh's points (or cell centres) to a
+   * surface, as `sdf:distance`.
+   */
+  distanceToSurface(
+    query: Mesh,
+    surface: Mesh,
+    sign?: SdfSign,
+    location?: SdfLocation,
+    band?: number,
+    recordInside?: boolean,
+    watertightCheck?: SdfWatertightCheck,
+  ): { mesh: Mesh; numBanded: number; quality: object };
+
+  /**
+   * Generate a grid over a surface and fill it with signed distances — the one
+   * call that turns a surface into a field.
+   *
+   * `structure` is `'voxel'` (a dense lattice) or `'octree'` (refined near the
+   * surface, and therefore **1-irregular**: it has hanging nodes, like
+   * `refine`'s `'balanced'` closure). `resolution`/`cellSize` size a voxel grid
+   * and are an **error** with `'octree'`, whose finest cell is
+   * `rootResolution / 2 ** maxDepth` and is therefore already determined.
+   *
+   * `dims` reports the ROOT cell counts and `spacing` the FINEST cell size. The
+   * mesh also carries the numeric `sdf:*` `field_data` header describing itself;
+   * no file format persists arbitrary `field_data`, so write it as `.vti`, whose
+   * `Origin`/`Spacing`/`WholeExtent` attributes are the same information.
+   * @throws {Error} when neither or both size options are given for a voxel
+   *   grid, when either is given for an octree, on a non-positive
+   *   `rootResolution`/`bandCells`, or when the grid exceeds `maxCells`.
+   */
+  computeSdf(
+    surface: Mesh,
+    structure?: SdfStructure,
+    resolution?: number[] | null,
+    cellSize?: number,
+    bounds?: number[] | null,
+    padding?: number,
+    paddingRelative?: number,
+    rootResolution?: number,
+    maxDepth?: number,
+    bandCells?: number,
+    recordLevels?: boolean,
+    maxCells?: number,
+    sign?: SdfSign,
+    location?: SdfLocation,
+    band?: number,
+    watertightCheck?: SdfWatertightCheck,
+  ): {
+    mesh: Mesh;
+    dims: number[];
+    origin: number[];
+    spacing: number[];
+    maxDepth: number;
+    numBanded: number;
+    quality: object;
+  };
+
   /**
    * Field differential operators: the gradient, divergence or curl of a
    * `point_data` field. `"green-gauss"` applies the divergence theorem over the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshioplusplus/wasm",
-  "version": "9.14.0",
+  "version": "9.25.0",
   "description": "meshio++ mesh I/O compiled to WebAssembly: read/write 41 mesh formats (incl. MED, CGNS, Exodus) in the browser or Node.js",
   "type": "module",
   "main": "./src/index.mjs",

package/src/index.mjs

@@ -44,12 +44,40 @@ function resolveVariant(variant) {
 }
 
 /**
- * @typedef {Object} CellBlock
+ * A rectangular (uniform node count) group of cells.
+ * @typedef {Object} RectangularCellBlock
  * @property {string} type - meshio++ cell type name (e.g. "triangle", "tetra10").
  * @property {Int32Array} data - flat, row-major connectivity (numCells * nodesPerCell).
  * @property {number} nodesPerCell
  */
 
+/**
+ * A 1-level ragged (jagged polygon) block: rows of varying node count, so
+ * there is no single `nodesPerCell`. Two flat CSR arrays instead of a nested
+ * array of arrays, which embind has no efficient representation for.
+ * @typedef {Object} PolygonCellBlock
+ * @property {string} type
+ * @property {Int32Array} data - every row's node ids concatenated.
+ * @property {Int32Array} rowOffsets - each cell's start in `data` (numCells + 1).
+ */
+
+/**
+ * A 2-level ragged (polyhedron) block: each cell a list of faces, each face a
+ * list of node ids.
+ * @typedef {Object} PolyhedronCellBlock
+ * @property {string} type
+ * @property {Int32Array} data - every face's node ids concatenated.
+ * @property {Int32Array} faceOffsets - each face's start in `data` (totalFaces + 1).
+ * @property {Int32Array} cellOffsets - each cell's start in the face list (numCells + 1).
+ */
+
+/**
+ * One homogeneous group of cells. Which shape it is is told by key presence:
+ * `cellOffsets` means polyhedron, `rowOffsets` means polygon, `nodesPerCell`
+ * means rectangular. See doc/polyhedra.md.
+ * @typedef {RectangularCellBlock | PolygonCellBlock | PolyhedronCellBlock} CellBlock
+ */
+
 /**
  * @typedef {Object} XdmfTimeSeriesWriter
  * @property {(mesh: Mesh) => void} writePointsCells - the static grid, once.
@@ -106,6 +134,7 @@ function resolveVariant(variant) {
  *   topologicalDimension: () => Object<string, number>,
  *   meshBackend: () => string,
  *   parallelBackend: () => string,
+ *   hasCgnslib: () => boolean,
  *   availableFormats: () => {readers: string[], writers: string[]},
  *   extractSurface: (mesh: Mesh, recordParentIds?: boolean) => Mesh,
  *   extractSkin: (mesh: Mesh, linearize?: boolean) => Mesh,
@@ -121,8 +150,15 @@ function resolveVariant(variant) {
  *   smooth: (mesh: Mesh, method?: string, iterations?: number, lambda?: number, mu?: number, fixBoundary?: boolean, preserveFeatures?: boolean, featureAngle?: number, guardInversion?: boolean) => {mesh: Mesh, numNodesMoved: number, maxDisplacement: number, numSkippedInversion: number},
  *   cropBbox: (mesh: Mesh, lo: number[], hi: number[], mode?: string, recordIds?: boolean) => Mesh,
  *   cropPlane: (mesh: Mesh, point: number[], normal: number[], mode?: string, recordIds?: boolean) => Mesh,
+ *   cropPredicate: (mesh: Mesh, array: string, compare?: string, value?: number, recordIds?: boolean) => Mesh,
  *   slice: (mesh: Mesh, origin: number[], normal: number[], recordParentIds?: boolean) => Mesh,
  *   isosurface: (mesh: Mesh, array: string, isovalues: number|number[], component?: number, recordParentIds?: boolean) => Mesh,
+ *   grid: (dims: number[], origin?: number[], spacing?: number[], maxCells?: number) => Mesh,
+ *   voxelize: (mesh: Mesh, resolution?: number[], cellSize?: number, bounds?: number[], padding?: number, paddingRelative?: number, fill?: string, sign?: string, attachOccupancy?: boolean, maxCells?: number, watertightCheck?: string) => {mesh: Mesh, dims: number[], origin: number[], spacing: number[], numOccupied: number},
+ *   surfaceWatertightCheck: (mesh: Mesh) => {boundaryEdges: number, nonManifoldEdges: number, inconsistentPairs: number, degenerateTriangles: number, watertight: boolean},
+ *   sampleDistance: (surface: Mesh, points: number[], sign?: string, band?: number, watertightCheck?: string) => Float64Array,
+ *   distanceToSurface: (query: Mesh, surface: Mesh, sign?: string, location?: string, band?: number, recordInside?: boolean, watertightCheck?: string) => {mesh: Mesh, numBanded: number, quality: object},
+ *   computeSdf: (surface: Mesh, structure?: string, resolution?: number[], cellSize?: number, bounds?: number[], padding?: number, paddingRelative?: number, rootResolution?: number, maxDepth?: number, bandCells?: number, recordLevels?: boolean, maxCells?: number, sign?: string, location?: string, band?: number, watertightCheck?: string) => {mesh: Mesh, dims: number[], origin: number[], spacing: number[], maxDepth: number, numBanded: number, quality: object},
  *   gradient: (mesh: Mesh, array: string, operator?: string, method?: string, location?: string, output?: string, component?: number, overwrite?: boolean) => {mesh: Mesh, numSkipped: number, numFallback: number},
  *   split: (mesh: Mesh, by: string, tagName?: string) => {key: string, mesh: Mesh}[],
  *   convertCells: (mesh: Mesh, mode?: string, recordParentIds?: boolean) => Mesh,
@@ -232,6 +268,7 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         // "seq" for the sequential artifact, "openmp" for the threaded
         // meshioplusplus_wasm_mt one -- which of the two this instance loaded.
         parallelBackend: () => Module.parallelBackend(),
+        hasCgnslib: () => Module.hasCgnslib(),
         // 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 (svg/tikz), and the HDF5/netCDF-backed ones are present
@@ -319,8 +356,62 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
             Module.cropBbox(mesh, lo, hi, mode, recordIds),
         cropPlane: (mesh, point, normal, mode = 'all', recordIds = false) =>
             Module.cropPlane(mesh, point, normal, mode, recordIds),
+        cropPredicate: (mesh, array, compare = '<', value = 0, recordIds = false) =>
+            Module.cropPredicate(mesh, array, compare, value, recordIds),
         slice: (mesh, origin, normal, recordParentIds = false) =>
             Module.slice(mesh, origin, normal, recordParentIds),
+        grid: (dims, origin = null, spacing = null, maxCells = 20000000) =>
+            Module.grid(dims, origin, spacing, maxCells),
+        voxelize: (
+            mesh,
+            resolution = null,
+            cellSize = 0,
+            bounds = null,
+            padding = 0,
+            paddingRelative = 0,
+            fill = 'all',
+            sign = 'pseudonormal',
+            attachOccupancy = false,
+            maxCells = 20000000,
+            watertightCheck = 'warn',
+        ) =>
+            Module.voxelize(mesh, resolution, cellSize, bounds, padding, paddingRelative,
+                fill, sign, attachOccupancy, maxCells, watertightCheck),
+        surfaceWatertightCheck: (mesh) => Module.surfaceWatertightCheck(mesh),
+        sampleDistance: (surface, points, sign = 'pseudonormal', band = 0, watertightCheck = 'warn') =>
+            Module.sampleDistance(surface, points, sign, band, watertightCheck),
+        distanceToSurface: (
+            query,
+            surface,
+            sign = 'pseudonormal',
+            location = 'corner',
+            band = 0,
+            recordInside = false,
+            watertightCheck = 'warn',
+        ) =>
+            Module.distanceToSurface(query, surface, sign, location, band, recordInside,
+                watertightCheck),
+        computeSdf: (
+            surface,
+            structure = 'voxel',
+            resolution = null,
+            cellSize = 0,
+            bounds = null,
+            padding = 0,
+            paddingRelative = 0.1,
+            rootResolution = 8,
+            maxDepth = 4,
+            bandCells = 1,
+            recordLevels = true,
+            maxCells = 20000000,
+            sign = 'pseudonormal',
+            location = 'corner',
+            band = 0,
+            watertightCheck = 'warn',
+        ) =>
+            Module.computeSdf(surface, structure, resolution, cellSize, bounds, padding,
+                paddingRelative, rootResolution, maxDepth, bandCells, recordLevels, maxCells,
+                sign, location, band, watertightCheck),
         isosurface: (mesh, array, isovalues, component = -1, recordParentIds = false) =>
             Module.isosurface(
                 mesh,