@meshioplusplus/wasm 16.31.0 → 16.39.0

package/index.d.ts

@@ -394,10 +394,124 @@ export interface RegionSummary {
  * `WriteOptions` field on the C++ side (gzip level 4 is a fixed registry
  * default; `vtk42`/`vtk51` are separate format keys, not a `vtk` option).
  */
+/** A built-in colormap (shared with the SVG and TikZ writers). */
+export type ColormapBase = "viridis" | "coolwarm" | "turbo" | "magma" | "inferno" | "plasma" | "grey" | "synthwave";
+/** A built-in colormap or its reversed `_r` variant. */
+export type ColormapName = ColormapBase | `${ColormapBase}_r`;
+
+/** A colour: `0xRRGGBBAA` as a number (alpha 0 is transparent), or `[r, g, b, a?]` in 0-255. */
+export type RenderColor = number | [number, number, number] | [number, number, number, number];
+
+/**
+ * Options of the software rasterizer (`render`, `renderText`, `renderPng`); every
+ * field is optional and an unknown key is an error. See doc/tui.md.
+ */
+export interface RenderOptions {
+  width?: number;
+  height?: number;
+  pixelAspect?: number;
+  /** 1, 2 or 4 samples per pixel along each axis. */
+  supersample?: number;
+  azimuth?: number;
+  elevation?: number;
+  roll?: number;
+  /** `"iso"`, `"+x"`, `"-x"`, `"+y"`, `"-y"`, `"+z"` or `"-z"`: the side the camera sits on. */
+  view?: string;
+  projection?: "orthographic" | "perspective";
+  fov?: number;
+  zoom?: number;
+  pan?: [number, number];
+  shading?: "none" | "flat" | "smooth";
+  twoSided?: boolean;
+  ambient?: number;
+  lightDir?: [number, number, number];
+  splitAngle?: number;
+  edges?: "none" | "all" | "feature";
+  featureAngle?: number;
+  edgeColor?: RenderColor;
+  fillColor?: RenderColor;
+  lineColor?: RenderColor;
+  background?: RenderColor;
+  pointRadius?: number;
+  colorBy?: string;
+  component?: number;
+  cmap?: ColormapName;
+  vmin?: number;
+  vmax?: number;
+  nanColor?: RenderColor;
+  colorbar?: boolean;
+  axes?: boolean;
+  scaleBar?: boolean;
+  /** `"mises"`, `"hydrostatic"` or `"principal"` reduction of the `colorBy` tensor array. */
+  reduce?: "mises" | "hydrostatic" | "principal";
+  /** A `dataCalc` expression to colour by instead of `colorBy`. */
+  expr?: string;
+  /** Percentiles bounding the automatic range; `null` leaves an end alone. */
+  clip?: [number | null, number | null];
+  symmetric?: boolean;
+  scale?: "linear" | "log" | "symlog";
+  scaleThreshold?: number;
+  categorical?: boolean;
+  colorRegions?: boolean;
+  categoryEdges?: boolean;
+  isolines?: number;
+  isoLevels?: number[];
+  isoColor?: RenderColor;
+  vectors?: string;
+  vectorCount?: number;
+  vectorLength?: number;
+  vectorColor?: RenderColor;
+  warp?: string;
+  warpScale?: number;
+  warpOutline?: boolean;
+  outlineColor?: RenderColor;
+  diagnostic?: "none" | "quality" | "inverted" | "degenerate" | "orientation" | "free_edges" | "edge_length";
+  qualityMetric?: string;
+  /**
+   * One or two cut-away planes that clip the geometry away: each is six numbers,
+   * a point and then the normal of the side kept (`[0.5, 0, 0, 1, 0, 0]` keeps `x >= 0.5`).
+   * The back faces then in view, the inside of the cut, are drawn in `cutawayTint`.
+   */
+  cutaway?: number[] | number[][];
+  cutawayTint?: RenderColor;
+  /** A vector point array to follow with streamlines, drawn over the mesh's own cells. */
+  streamlines?: string;
+  /** About this many seeds (default 40). */
+  streamSeeds?: number;
+  /** The longest a line grows each way from its seed, in model diagonals (default 0.5). */
+  streamLength?: number;
+  streamColor?: RenderColor;
+}
+
+/** Options of `renderText`: the cell encodings only (the graphics protocols are CLI features). */
+export interface RenderTextOptions {
+  encoding?: "halfblock" | "quadrant" | "sextant" | "braille" | "ascii";
+  colorDepth?: "truecolor" | "256" | "16" | "mono";
+  format?: "ansi" | "plain" | "html";
+  cols?: number;
+  rows?: number;
+  cellAspect?: number;
+  notes?: boolean;
+}
+
+/** A rendered image. */
+export interface RenderedFrame {
+  width: number;
+  height: number;
+  /** RGBA, rows top to bottom, straight alpha: `new ImageData(frame.rgba, frame.width, frame.height)`. */
+  rgba: Uint8ClampedArray;
+  /** The input cell (global, block-major) drawn at each pixel; -1 for none. */
+  cellIds: Float64Array;
+  /** The mapped `[vmin, vmax]`, or `null` when no field is mapped. */
+  range: [number, number] | null;
+  /** The colour range, ticks and keys, as text. */
+  notes: string[];
+}
+
 /** glTF writer parameters. Components are 0-based; omitted selects magnitude. */
 export interface GltfWriteOptions {
   colorBy?: string;
-  cmap?: "viridis" | "coolwarm" | "turbo";
+  cmap?: ColormapName;
   component?: number;
   vmin?: number;
   vmax?: number;
@@ -677,6 +791,37 @@ export interface OpReport {
   warnings: string[];
 }
 
+/** One named point- or cell-data array of a {@link SurfaceBuffers}. */
+export interface SurfaceArray {
+  name: string;
+  /**
+   * `components` values per point or cell, in the array's own dtype, except
+   * that a 64-bit integer array arrives as `Int32Array`/`Uint32Array` when
+   * every value fits and as `Float64Array` when one does not: never a
+   * `BigInt64Array`, which vtk.js cannot hold.
+   */
+  values: Exclude<DataArray, BigInt64Array | BigUint64Array>;
+  /** Values per tuple: a vector has 3, a 3x3 tensor 9, a scalar 1. */
+  components: number;
+}
+
+/**
+ * A renderable surface as the arrays a vtk.js `vtkPolyData` is built from,
+ * numbered exactly as the VTP file of the same surface would be.
+ */
+export interface SurfaceBuffers {
+  /** x, y, z per point (2-D meshes padded with z = 0). */
+  points: Float32Array | Float64Array;
+  /** VTK legacy cell layout, `[n, id0, …, idn-1, n, …]`, per PolyData section. */
+  verts: Uint32Array;
+  lines: Uint32Array;
+  polys: Uint32Array;
+  /** Sorted by name. */
+  pointData: SurfaceArray[];
+  /** Sorted by name; values in Verts, then Lines, then Polys order. */
+  cellData: SurfaceArray[];
+}
+
 /** `gradient`'s differential operator. See doc/gradient.md. */
 export type GradientOperator = 'gradient' | 'divergence' | 'curl';
 
@@ -1180,9 +1325,8 @@ export interface MeshioPlusPlusModule {
    * node, so `triangle6` connectivity drawn verbatim is visible garbage).
    *
    * Prefer this over `readMesh` -> `extractSkin` -> `writeMesh` for anything
-   * headed to a renderer. It never materializes a JS {@link Mesh}, so
-   * multi-component (vector/tensor) arrays survive -- the flat JS
-   * representation cannot carry them.
+   * headed to a renderer. It never materializes a JS {@link Mesh}, so the
+   * mesh is not copied across the boundary and back.
    */
   convertSurface(inPath: string, outPath: string, options?: ConvertOptions): void;
 
@@ -1191,8 +1335,8 @@ export interface MeshioPlusPlusModule {
    * first — all inside C++.
    *
    * Chaining the individual operation bindings (`smooth`, `clean`, …) would
-   * route the mesh through the flat JS {@link Mesh} on every step and so
-   * destroy every multi-component array; nothing crosses the boundary here.
+   * copy the mesh into a JS {@link Mesh} and back on every step; here nothing
+   * crosses the boundary until the result is written.
    *
    * An **empty** pipeline is exactly {@link convertSurface}. That is
    * deliberate: one call serves both the plain and the post-operation display,
@@ -1227,6 +1371,29 @@ export interface MeshioPlusPlusModule {
     }
   ): OpReport;
 
+  /**
+   * {@link convertSurfaceOps} without the file: the same pipeline and surface,
+   * returned as typed arrays ready for a vtk.js `vtkPolyData` instead of being
+   * written, base64-encoded and compressed for a VTP reader to undo. The
+   * browser viewer renders through this.
+   *
+   * Cells are numbered as the VTP file of the surface numbers them (Verts,
+   * Lines, then Polys, each in block order), so `surface:parent_cell` and a
+   * picked cell id mean the same in both.
+   *
+   * @throws {Error} on an unknown operation name, an unreadable file, or a
+   *   surface PolyData cannot hold (a polyhedron block left by an operation).
+   */
+  surfaceBuffersOps(
+    inPath: string,
+    ops?: OpSpec[],
+    options?: {
+      inFormat?: string;
+      /** Keep `surface:parent_cell` (the picker needs it). */
+      keepProvenance?: boolean;
+    }
+  ): OpReport & { surface: SurfaceBuffers };
+
   /**
    * Run a whole settings pipeline: read `Input.Path`, apply `Operations` in
    * order, write `Output.Path` — the `settings.json` engine (see
@@ -1397,7 +1564,7 @@ export interface MeshioPlusPlusModule {
    *
    * 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, `svg`, `tikz` and `gltf` are write-only), and the set depends on how
+   * read-only, `gltf` and `step` are 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.
    */
@@ -2131,6 +2298,20 @@ export interface MeshioPlusPlusModule {
    * cover the whole surface, selected or not. See doc/feature_edges.md.
    * @throws {Error} on an angle outside [0, 180] or an unknown region.
    */
+  /**
+   * Render a mesh into an RGBA frame with a deterministic software rasterizer: no
+   * WebGL, so it works in a Node script or a server-side preview. Volume cells
+   * are drawn through their boundary skin. See doc/tui.md.
+   * @throws {Error} on an unknown option, an invalid value or an unknown array.
+   */
+  render(mesh: Mesh, options?: RenderOptions): RenderedFrame;
+  /**
+   * Render a mesh as terminal-cell text sized `cols` x `rows` (default 80 x 24).
+   * The Kitty, iTerm2 and Sixel encodings are not exported here.
+   */
+  renderText(mesh: Mesh, options?: RenderOptions, text?: RenderTextOptions): string;
+  /** Render a mesh and encode it as an RGBA PNG; `compress` 0 stores it uncompressed (default). */
+  renderPng(mesh: Mesh, options?: RenderOptions, compress?: number): Uint8Array;
   featureEdges(
     mesh: Mesh,
     featureAngle?: number,
@@ -2147,6 +2328,58 @@ export interface MeshioPlusPlusModule {
     numInconsistent: number;
   };
 
+  /**
+   * Split a surface into smooth patches by region growing, bounded by its
+   * feature edges. The mesh comes back unchanged plus cell data
+   * `segment:patch` (-1 off the surface), field data `segment:adjacency`
+   * (rows `[a, b, sharedEdges]`) and one cell region per patch,
+   * `<prefix>:<k>`. See doc/segment.md.
+   * @throws {Error} on an option out of range, an unknown region or a volume block.
+   */
+  segment(
+    mesh: Mesh,
+    featureAngle?: number,
+    normalTolerance?: number,
+    curvatureTolerance?: number,
+    minPatchCells?: number,
+    region?: string,
+    prefix?: string,
+  ): {
+    mesh: Mesh;
+    numPatches: number;
+    numMerged: number;
+    numFeatureEdges: number;
+    numBoundaryEdges: number;
+    numNonManifoldEdges: number;
+  };
+
+  /**
+   * Fit a plane, sphere, cylinder, cone or torus to each patch of a surface
+   * (the first accepted in that order, or none). The mesh comes back unchanged
+   * plus cell data `fit:type`, `fit:rms`, `fit:max` and per-patch field data
+   * `fit:patch_*`; `patchData = ''` fits the whole surface. See
+   * doc/fit_primitives.md.
+   * @throws {Error} on a bad option, an unknown type or a missing label array.
+   */
+  fitPrimitives(
+    mesh: Mesh,
+    patchData?: string,
+    tolerance?: number,
+    relative?: boolean,
+    minInlierFraction?: number,
+    types?: Array<'plane' | 'sphere' | 'cylinder' | 'cone' | 'torus'>,
+    maxIterations?: number,
+  ): {
+    mesh: Mesh;
+    numPatches: number;
+    numPlane: number;
+    numSphere: number;
+    numCylinder: number;
+    numCone: number;
+    numTorus: number;
+    numUnfitted: number;
+  };
+
   /**
    * The (sampled) Hausdorff distance between the surfaces of two meshes; a
    * volume mesh contributes its skin. `faceSamples = s > 0` also samples the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshioplusplus/wasm",
-  "version": "16.31.0",
+  "version": "16.39.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",
   "type": "module",
   "main": "./src/index.mjs",

package/src/index.mjs

@@ -206,6 +206,7 @@ export class MeshioPlusPlusLoadError extends Error {
  *   convert: (inPath: string, outPath: string, options?: {inFormat?: string, outFormat?: string, encoding?: string, codec?: string, floatFormat?: string}) => string[],
  *   convertSurface: (inPath: string, outPath: string, options?: {inFormat?: string, outFormat?: string}) => void,
  *   convertSurfaceOps: (inPath: string, outPath: string, ops?: object[], options?: {inFormat?: string, outFormat?: string, keepProvenance?: boolean, compressVtp?: boolean}) => {steps: object[], warnings: string[]},
+ *   surfaceBuffersOps: (inPath: string, ops?: object[], options?: {inFormat?: string, keepProvenance?: boolean}) => {surface: object, steps: object[], warnings: string[]},
  *   runPipeline: (settings: object|string) => {steps: object[], warnings: string[]},
  *   sequenceEntries: (source: string|string[], options?: object) => object[],
  *   sequenceToTimeseries: (source: string|string[], outPath: string, outFormat?: string, options?: object) => number,
@@ -254,6 +255,11 @@ export class MeshioPlusPlusLoadError extends Error {
  *   computeNormals: (mesh: Mesh, pointNormals?: boolean, cellNormals?: boolean, weight?: string, splitAngle?: number, recordParentIds?: boolean, region?: string) => {mesh: Mesh, numIsolated: number, numUndefined: number, numDegenerate: number, numSplitPoints: number, numAddedPoints: number, quality: {boundaryEdges: number, nonManifoldEdges: number, inconsistentPairs: number, degenerateTriangles: number, watertight: boolean}},
  *   checkQuality: (mesh: Mesh, require?: string, maxInverted?: number, maxDegenerate?: number) => {passed: boolean, numCells: number, numInverted: number, numDegenerate: number, checks: Array<object>, summary: string},
  *   featureEdges: (mesh: Mesh, featureAngle?: number, feature?: boolean, boundary?: boolean, nonManifold?: boolean, inconsistent?: boolean, region?: string) => {mesh: Mesh, numFeature: number, numBoundary: number, numNonManifold: number, numInconsistent: number},
+ *   segment: (mesh: Mesh, featureAngle?: number, normalTolerance?: number, curvatureTolerance?: number, minPatchCells?: number, region?: string, prefix?: string) => {mesh: Mesh, numPatches: number, numMerged: number, numFeatureEdges: number, numBoundaryEdges: number, numNonManifoldEdges: number},
+ *   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},
+ *   render: (mesh: Mesh, options?: RenderOptions) => RenderedFrame,
+ *   renderText: (mesh: Mesh, options?: RenderOptions, text?: RenderTextOptions) => string,
+ *   renderPng: (mesh: Mesh, options?: RenderOptions, compress?: number) => Uint8Array,
  *   hausdorffDistance: (a: Mesh, b: Mesh, faceSamples?: number, regionA?: string, regionB?: string) => {distance: number, aToB: number, bToA: number, meanAToB: number, rmsAToB: number, meanBToA: number, rmsBToA: number, numSamplesA: number, numSamplesB: number, worstPointA: Float64Array, worstPointB: Float64Array},
  *   editRegions: (mesh: Mesh, edits: Array<{op: string, inputs: Array<string | {name: string, kind?: string, dim?: number, tag?: number}>, output?: string, dim?: number, tag?: number, keepInputs?: boolean}>) => Mesh,
  *   regionAdjacency: (mesh: Mesh, regions?: Array<string | {name: string, kind?: string, dim?: number, tag?: number}>) => Mesh,
@@ -443,12 +449,12 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         // Like `convert`, but writes a renderable *surface*: a volume mesh
         // becomes its boundary, everything else passes through, and the result
         // is linearized. Prefer this over readMesh -> extractSkin -> writeMesh
-        // for anything headed to a renderer: it stays inside C++, so
-        // multi-component data survives, which the flat JS mesh cannot carry.
+        // for anything headed to a renderer: it stays inside C++, so the mesh
+        // is never copied into a JS object and back.
         convertSurface: (inPath, outPath, { inFormat = '', outFormat = '' } = {}) =>
             Module.convertSurface(inPath, inFormat, outPath, outFormat),
         // Like `convertSurface`, but applies a pipeline of mesh operations
-        // first -- entirely inside C++, so multi-component data survives them.
+        // first -- entirely inside C++, with no JS mesh between the steps.
         // An empty pipeline is exactly `convertSurface`, which is what lets a
         // caller use one code path for both the plain and the post-operation
         // display, and what makes undo a replay rather than an inverse.
@@ -467,6 +473,10 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
                 keepProvenance,
                 compressVtp
             ),
+        // `convertSurfaceOps` without the file: the surface comes back as the
+        // typed arrays a vtk.js vtkPolyData is built from (see index.d.ts).
+        surfaceBuffersOps: (inPath, ops = [], { inFormat = '', keepProvenance = false } = {}) =>
+            Module.surfaceBuffersOps(inPath, inFormat, ops, keepProvenance),
         // A whole settings.json pipeline (PascalCase vocabulary, see
         // doc/pipeline.md). Accepts the parsed object, the JSON text, or a
         // MEMFS path ending in ".json" -- the wasm binary carries no JSON
@@ -511,7 +521,7 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         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/gltf), and the HDF5/netCDF-backed ones are present
+        // write-only (gltf), 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,
@@ -826,6 +836,31 @@ export async function loadMeshioPlusPlus(moduleOverrides = {}, { variant = 'auto
         ) =>
             Module.featureEdges(mesh, featureAngle, feature, boundary, nonManifold,
                 inconsistent, region),
+        segment: (
+            mesh,
+            featureAngle = 30,
+            normalTolerance = 0,
+            curvatureTolerance = 0,
+            minPatchCells = 1,
+            region = '',
+            prefix = 'patch',
+        ) =>
+            Module.segment(mesh, featureAngle, normalTolerance, curvatureTolerance,
+                minPatchCells, region, prefix),
+        fitPrimitives: (
+            mesh,
+            patchData = 'segment:patch',
+            tolerance = 1e-3,
+            relative = true,
+            minInlierFraction = 0.9,
+            types = ['plane', 'sphere', 'cylinder', 'cone', 'torus'],
+            maxIterations = 50,
+        ) =>
+            Module.fitPrimitives(mesh, patchData, tolerance, relative, minInlierFraction,
+                Array.isArray(types) ? types : [types], maxIterations),
+        render: (mesh, options = {}) => Module.render(mesh, options),
+        renderText: (mesh, options = {}, text = {}) => Module.renderText(mesh, options, text),
+        renderPng: (mesh, options = {}, compress = 0) => Module.renderPng(mesh, options, compress),
         hausdorffDistance: (a, b, faceSamples = 0, regionA = '', regionB = '') =>
             Module.hausdorffDistance(a, b, faceSamples, regionA, regionB),
         editRegions: (mesh, edits) =>