@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/reference/mesh/analyzeQuality.md

@@ -0,0 +1,62 @@
+# analyzeQuality
+
+Measures triangle shape, edge topology, vertex concentration, and connected planar patches.
+
+**analyzeQuality**(`mesh`: [`TriangleMeshInput`](../geometry/TriangleMeshInput.md), `options?`: [`TriangleMeshQualityOptions`](../geometry/TriangleMeshQualityOptions.md)): [`TriangleMeshQualityReport`](../geometry/TriangleMeshQualityReport.md)
+
+
+
+Positions are never welded: valence and manifold status describe the supplied indexed topology.
+Degenerate triangles are reported rather than rejected, while malformed buffers, non-finite
+positions, missing vertex references, and the configured complexity limit throw.
+
+## Parameters
+
+<a id="mesh"></a>
+
+**`mesh`** · [`TriangleMeshInput`](../geometry/TriangleMeshInput.md) · Required
+
+Indexed triangle mesh in arbitrary consistent model units.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`TriangleMeshQualityOptions`](../geometry/TriangleMeshQualityOptions.md) · Optional
+
+Scale-aware tolerance and analysis budget.
+
+- [`maxTriangles`](../geometry/TriangleMeshQualityOptions.md#maxtriangles) · `number` · Optional
+
+  Maximum number of triangles inspected. Defaults to `200000`.
+
+- [`tolerance`](../geometry/TriangleMeshQualityOptions.md#tolerance) · [`GeometryToleranceOptions`](../geometry/GeometryToleranceOptions.md) · Optional
+
+  Numeric comparison overrides; model coordinates are interpreted in their existing units.
+
+
+
+## Returns
+
+[`TriangleMeshQualityReport`](../geometry/TriangleMeshQualityReport.md)
+
+A deterministic report without mutating or copying the mesh.
+
+
+## Related APIs
+
+- [TriangleMeshInput](../geometry/TriangleMeshInput.md)
+- [TriangleMeshQualityOptions](../geometry/TriangleMeshQualityOptions.md)
+- [TriangleMeshQualityReport](../geometry/TriangleMeshQualityReport.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/bounds.md

@@ -0,0 +1,45 @@
+# bounds
+
+Computes axis-aligned bounds for a non-empty mesh.
+
+`const` **bounds**: (`mesh`: [`TriangleMeshInput`](../geometry/TriangleMeshInput.md)) => [`Bounds3Data`](../geometry/Bounds3Data.md)
+
+
+
+## Parameters
+
+<a id="mesh"></a>
+
+**`mesh`** · [`TriangleMeshInput`](../geometry/TriangleMeshInput.md) · Required
+
+Mesh whose finite complete vertices will be measured.
+
+
+
+## Returns
+
+[`Bounds3Data`](../geometry/Bounds3Data.md)
+
+Fresh immutable minimum and maximum XYZ tuples.
+
+
+## Throws
+
+- `GeometryError` When the mesh is structurally invalid.
+
+## Related APIs
+
+- [Bounds3Data](../geometry/Bounds3Data.md)
+- [TriangleMeshInput](../geometry/TriangleMeshInput.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/categories/operations.md

@@ -0,0 +1,57 @@
+# Mesh operations
+
+Construct, transform, validate, analyze, and optimize indexed meshes.
+
+Use `import * as mesh from "@metamesh/modeling/geometry/mesh"` for static, removable operation imports. `mesh.join` concatenates buffers; overlapping geometry remains overlapping.
+
+Manufacturing meshes use `Float32Array` XYZ positions and `Uint32Array` triangle indices. Mesh analysis accepts raw arrays or stable immutable buffers directly; signatures add quantized topology and a regression hash. Predictable constructors reject unsafe allocations before sampling.
+
+- **Construct:** `mesh.extrude`, `mesh.loft`, `mesh.sweep`, `mesh.revolve`, `mesh.threadRidge`, and `mesh.threadSolid` return `TriangleMesh` data without a host engine. `LoftOptions`, `SweepOptions`, and `ExtrudeMeshOptions` describe pure construction. Native `ExtrudeOptions` additionally accepts end treatments.
+- **Match lofts:** `mesh.loft` defaults to `direct` correspondence; select `reindex`, `fast-distance`, or `distance` explicitly when needed. Stations specify exactly one `z` or `frame`, retain original vertices, and interpolate slices in world coordinates. Profile association and sampling-grid work have explicit limits; fidelity isn't reduced to meet them.
+- **Validate:** closed oriented-edge checks do not establish freedom from self-intersections. `mesh.validateSolid` adds bounded floating-point intersection and nested-shell orientation checks, including cavity boundaries. Contacts within tolerance reject conservatively; exhausted work limits fail explicitly.
+- **Measure:** `mesh.centroid` returns the uniform-density volume centroid of consistently oriented closed geometry, including cavities.
+
+## Functions
+
+| API | Summary |
+| --- | --- |
+| [extrude](../extrude.md) | Linearly extrudes one simple profile along +Z with robust ear-clipped caps. Path2 profiles must be closed; raw point collections have an implicit closing edge. End treatments are unsupported and reject at runtime. Use Section.extrude for finished ends. |
+| [loft](../loft.md) | Lofts simple point loops at z heights or explicit right-handed frames, in input order. |
+| [sweep](../sweep.md) | Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam. |
+| [heightfield](../heightfield.md) | Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base. |
+| [preflightHeightfield](../preflightHeightfield.md) | Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts. |
+| [threadRidge](../threadRidge.md) | Builds closed thread-ridge components with every profile locked to the shaft's radial/axial frame. The mesh is intended for union with its minor-envelope cylinder and never owns WASM objects. |
+| [threadSolid](../threadSolid.md) | Builds one closed threaded cylinder without a ridge/core Boolean seam. |
+| [preflightThreadSolid](../preflightThreadSolid.md) | Checks thread dimensions, profile, end treatments, sampling, and conservative estimates against output limits. |
+| [transform](../transform.md) | Applies an affine transform to a mesh and preserves outward face orientation. |
+| [join](../join.md) | Concatenates meshes into one indexed mesh without welding coincident vertices. |
+| [reverse](../reverse.md) | Returns a copy of a mesh with every triangle winding reversed. |
+| [centroid](../centroid.md) | Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells. |
+| [analyze](../analyze.md) | Validates and measures a mesh with one pass over positions and one over triangles. |
+| [analyzeQuality](../analyzeQuality.md) | Measures triangle shape, edge topology, vertex concentration, and connected planar patches. |
+| [signature](../signature.md) | Creates an order-independent regression signature for a manufacturing mesh. |
+| [validate](../validate.md) | Validates mesh buffers, indices, triangle area, and optionally closed topology. |
+| [validateSolid](../validateSolid.md) | Checks closed indexed topology, triangle intersections, and alternating nested shell orientation. |
+| [optimizePlanarPatches](../optimizePlanarPatches.md) | Improves pathological planar triangulation with bounded legal diagonal flips. |
+| [immutable](../immutable.md) | Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing. |
+| [render](../render.md) | Builds crease-aware render buffers without moving or merging distinct positions. Face normals are averaged only at exactly coincident positions within the crease angle. Returns owned buffers; every triangle retains its coordinates, order and winding. Pathological vertex fans exceeding 50 million normal comparisons reject with a complexity error. |
+
+## Interfaces
+
+| API | Summary |
+| --- | --- |
+| [MeshRenderOptions](../MeshRenderOptions.md) | Shading policy for a render copy; manufacturing positions and triangle order never change. |
+| [RenderMesh](../RenderMesh.md) | Owned indexed render buffers with unit vertex normals and positions in millimetres. |
+
+## Values
+
+| API | Summary |
+| --- | --- |
+| [revolve](../revolve.md) | Revolves a non-duplicated closed `[radius, z]` profile around +Z. |
+| [bounds](../bounds.md) | Computes axis-aligned bounds for a non-empty mesh. |
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/centroid.md

@@ -0,0 +1,45 @@
+# centroid
+
+Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+
+**centroid**(`mesh`: [`TriangleMeshInput`](../geometry/TriangleMeshInput.md)): [`Vector3Data`](../geometry/Vector3Data.md)
+
+
+
+Coordinates are millimetres. Indexed closure and positive aggregate volume are required; callers
+may use mesh.validateSolid first when geometric intersections and shell orientation are untrusted.
+Fresh mutable input is inspected on every call, and buffers are never changed.
+
+## Parameters
+
+<a id="mesh"></a>
+
+**`mesh`** · [`TriangleMeshInput`](../geometry/TriangleMeshInput.md) · Required
+
+Consistently oriented closed mesh with positive enclosed volume.
+
+
+
+## Returns
+
+[`Vector3Data`](../geometry/Vector3Data.md)
+
+A fresh immutable XYZ volume centroid.
+
+
+## Related APIs
+
+- [TriangleMeshInput](../geometry/TriangleMeshInput.md)
+- [Vector3Data](../geometry/Vector3Data.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/extrude.md

@@ -0,0 +1,79 @@
+# extrude
+
+Linearly extrudes one simple profile along +Z with robust ear-clipped caps. Path2 profiles must be closed; raw point collections have an implicit closing edge. End treatments are unsupported and reject at runtime. Use Section.extrude for finished ends.
+
+**extrude**(`input`: [`Path2Input`](../geometry/Path2Input.md), `options`: [`ExtrudeMeshOptions`](../geometry/ExtrudeMeshOptions.md)): [`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+
+## Example: Extrude point data without an engine
+
+```ts
+const outline = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+mesh.extrude(outline, { height: 8 });
+```
+
+## Parameters
+
+<a id="input"></a>
+
+**`input`** · [`Path2Input`](../geometry/Path2Input.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`ExtrudeMeshOptions`](../geometry/ExtrudeMeshOptions.md) · Required
+
+- [`height`](../geometry/ExtrudeMeshOptions.md#height) · `number` · Required
+
+  Positive extrusion height in millimetres.
+
+- [`center`](../geometry/ExtrudeMeshOptions.md#center) · `boolean` · Optional
+
+  Center the extrusion on Z; otherwise its bottom is at zero. Defaults to false.
+
+- [`divisions`](../geometry/ExtrudeMeshOptions.md#divisions) · `number` · Optional
+
+  Exact number of intermediate profiles, nonnegative; overrides physical sampling.
+
+- [`limits`](../geometry/ExtrudeMeshOptions.md#limits) · `Partial`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\> · Optional
+
+  Explicit output and sampling allocation ceilings.
+
+- [`resolution`](../geometry/ExtrudeMeshOptions.md#resolution) · [`GeometryResolution`](../geometry/GeometryResolution.md) · Optional
+
+  Operation-level physical policy over the nearest model scope.
+
+- [`scaleTop`](../geometry/ExtrudeMeshOptions.md#scaletop) · `number` \| [`Vector2Input`](../geometry/Vector2Input.md) · Optional
+
+  Finite uniform or XY scale of the top profile; defaults to one.
+
+- [`twist`](../geometry/ExtrudeMeshOptions.md#twist) · `number` · Optional
+
+  Finite rotation of the top profile about +Z, in degrees; defaults to zero.
+
+
+
+## Returns
+
+[`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+## Related APIs
+
+- [ExtrudeMeshOptions](../geometry/ExtrudeMeshOptions.md)
+- [Path2Input](../geometry/Path2Input.md)
+- [TriangleMesh](../geometry/TriangleMesh.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/heightfield.md

@@ -0,0 +1,57 @@
+# heightfield
+
+Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+
+**heightfield**(`options`: [`HeightfieldOptions`](../geometry/HeightfieldOptions.md), `limits?`: `Partial`\<`Pick`\<[`ModelingLimits`](../geometry/ModelingLimits.md), `"maxVertices"` \| `"maxTriangles"` \| `"maxBytes"`\>\>): [`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+
+## Example: Sample a closed wavy mesh
+
+```ts
+mesh.heightfield({
+  size: [30, 20], segments: [24, 16],
+  height: ([x, y]) => 3 + Math.cos(x / 5) * Math.cos(y / 5),
+});
+```
+
+Heights run once per grid point after preflight; center-error adds one evaluation per cell.
+Top winding is +Z, the base is -Z, and sides face outward. Coordinates and heights must fit
+Float32 storage. Explicit axes are captured before sampling; shared wall vertices prevent cracks.
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`HeightfieldOptions`](../geometry/HeightfieldOptions.md) · Required
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<`Pick`\<[`ModelingLimits`](../geometry/ModelingLimits.md), `"maxVertices"` \| `"maxTriangles"` \| `"maxBytes"`\>\> · Optional
+
+
+
+## Returns
+
+[`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+## Related APIs
+
+- [HeightfieldOptions](../geometry/HeightfieldOptions.md)
+- [ModelingLimits](../geometry/ModelingLimits.md)
+- [TriangleMesh](../geometry/TriangleMesh.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/immutable.md

@@ -0,0 +1,51 @@
+# immutable
+
+Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
+
+**immutable**(`mesh`: `object`): [`ImmutableTriangleMesh`](../geometry/ImmutableTriangleMesh.md)
+
+
+
+## Example
+
+```ts
+import { generate } from "@metamesh/modeling";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+const buildSurface = () => mesh.immutable(mesh.heightfield({
+  size: [10, 10], segments: [8, 8], height: () => 2,
+}));
+const model = generate(({ memo, part }) => part("surface", memo(buildSurface)));
+```
+
+## Parameters
+
+### mesh
+
+#### positions
+
+`Float32Array`
+
+#### indices
+
+`Uint32Array`
+
+## Returns
+
+[`ImmutableTriangleMesh`](../geometry/ImmutableTriangleMesh.md)
+
+
+## Related APIs
+
+- [ImmutableTriangleMesh](../geometry/ImmutableTriangleMesh.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/join.md

@@ -0,0 +1,47 @@
+# join
+
+Concatenates meshes into one indexed mesh without welding coincident vertices.
+
+**join**(`meshes`: readonly [`TriangleMeshInput`](../geometry/TriangleMeshInput.md)[]): [`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+
+Inputs are validated and never mutated. Face order and winding remain stable.
+
+## Parameters
+
+<a id="meshes"></a>
+
+**`meshes`** · readonly [`TriangleMeshInput`](../geometry/TriangleMeshInput.md)[] · Required
+
+One or more meshes to concatenate.
+
+
+
+## Returns
+
+[`TriangleMesh`](../geometry/TriangleMesh.md)
+
+Fresh typed arrays with indices offset to their source vertex ranges.
+
+
+## Throws
+
+- `GeometryError` When no mesh is supplied or an input is invalid.
+
+## Related APIs
+
+- [TriangleMesh](../geometry/TriangleMesh.md)
+- [TriangleMeshInput](../geometry/TriangleMeshInput.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/loft.md

@@ -0,0 +1,83 @@
+# loft
+
+Lofts simple point loops at z heights or explicit right-handed frames, in input order.
+
+**loft**(`stations`: readonly [`LoftMeshStation`](../geometry/LoftMeshStation.md)[], `options?`: [`LoftOptions`](../geometry/LoftOptions.md)): [`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+
+## Example: Loft with explicit point correspondence
+
+```ts
+const bottom = rectangleContour({ size: [20, 12] });
+const top = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+mesh.loft([{ profile: bottom, z: 0 }, { profile: top, z: 30 }], { correspondence: "reindex" });
+```
+
+Correspondence defaults to direct. CCW-normalized loops retain their
+seam and original vertices; unequal counts gain subdivisions or repeated fan slots.
+Both ends use ear-clipped caps, supporting concave profiles without center fans.
+Intermediate slices interpolate placed world vertices, never frame axes.
+Transformed coordinates must fit finite Float32 mesh storage.
+Path2 profiles must be closed; raw point collections are interpreted as closed.
+
+## Parameters
+
+<a id="stations"></a>
+
+**`stations`** · readonly [`LoftMeshStation`](../geometry/LoftMeshStation.md)[] · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`LoftOptions`](../geometry/LoftOptions.md) · Optional
+
+- [`correspondence`](../geometry/LoftOptions.md#correspondence) · [`LoftCorrespondence`](../geometry/LoftCorrespondence.md) \| readonly [`LoftCorrespondence`](../geometry/LoftCorrespondence.md)[] · Optional
+
+  One method or one per consecutive station gap. Omitted preserves known primitive landmarks, including circle/ellipse-to-rectangle corners, and otherwise uses direct correspondence with the supplied seams.
+
+- [`distribution`](../geometry/LoftOptions.md#distribution) · `"perimeter"` \| `"segments"` · Optional
+
+  Extra points follow edge length or distribute equally across existing segments. Defaults to perimeter for direct/reindex, or segments when any distance method is selected; distance methods require segments.
+
+- [`refine`](../geometry/LoftOptions.md#refine) · `number` \| readonly `number`[] · Optional
+
+  Positive integer point-density multiplier, uniformly or per input profile. Original vertices are retained. Defaults to one.
+
+- [`slices`](../geometry/LoftOptions.md#slices) · `number` \| readonly `number`[] · Optional
+
+  Nonnegative count of world-linearly interpolated profiles, uniformly or per gap. Defaults to zero.
+
+- [`resolution`](../geometry/LoftOptions.md#resolution) · [`GeometryResolution`](../geometry/GeometryResolution.md) · Optional
+
+  Physical curve policy for retained primitives, and maximum edge length for point data. Exact primitive curve counts take precedence.
+
+- [`limits`](../geometry/LoftOptions.md#limits) · `Partial`\<[`ModelingLimits`](../geometry/ModelingLimits.md)\> · Optional
+
+  Explicit output and sampling budgets; native operations may only lower host ceilings.
+
+
+
+## Returns
+
+[`TriangleMesh`](../geometry/TriangleMesh.md)
+
+
+## Related APIs
+
+- [LoftMeshStation](../geometry/LoftMeshStation.md)
+- [LoftOptions](../geometry/LoftOptions.md)
+- [TriangleMesh](../geometry/TriangleMesh.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/optimizePlanarPatches.md

@@ -0,0 +1,102 @@
+# optimizePlanarPatches
+
+Improves pathological planar triangulation with bounded legal diagonal flips.
+
+**optimizePlanarPatches**(`mesh`: [`TriangleMeshInput`](../geometry/TriangleMeshInput.md), `options?`: [`PlanarMeshOptimizationOptions`](../geometry/PlanarMeshOptimizationOptions.md)): [`PlanarMeshOptimizationResult`](../geometry/PlanarMeshOptimizationResult.md)
+
+
+
+The operation changes indices only: it never moves, adds, welds, or removes vertices; never
+crosses a coplanar-patch boundary; and never changes the face count. Each accepted flip improves
+a deterministic ordering of triangle angles, aspect ratio, diagonal locality, and local
+incidence/valence concentration. Unsupported input or a failed final integrity check preserves the
+original raw mesh object. Immutable inputs produce owned raw output buffers, including unchanged
+results. Malformed buffers and the configured analysis complexity limit throw.
+
+## Parameters
+
+<a id="mesh"></a>
+
+**`mesh`** · [`TriangleMeshInput`](../geometry/TriangleMeshInput.md) · Required
+
+Closed, consistently wound indexed triangle mesh in arbitrary consistent units.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`PlanarMeshOptimizationOptions`](../geometry/PlanarMeshOptimizationOptions.md) · Optional
+
+Patch eligibility, numeric tolerance, and deterministic work bounds.
+
+- [`maxFlipAttempts`](../geometry/PlanarMeshOptimizationOptions.md#maxflipattempts) · `number` · Optional
+
+  Maximum attempted edge evaluations. By default this is twenty times the initial candidate
+  edge count, capped at `1000000`.
+
+- [`maxEdgeRevisits`](../geometry/PlanarMeshOptimizationOptions.md#maxedgerevisits) · `number` · Optional
+
+  Maximum times one edge may be reconsidered after neighbouring flips. Defaults to `12`.
+
+- [`maxPatchTriangles`](../geometry/PlanarMeshOptimizationOptions.md#maxpatchtriangles) · `number` · Optional
+
+  Maximum triangles allowed in one selected patch. Defaults to `50000`.
+
+- [`maxProcessedTriangles`](../geometry/PlanarMeshOptimizationOptions.md#maxprocessedtriangles) · `number` · Optional
+
+  Maximum cumulative triangles across selected patches. Defaults to `200000`.
+
+- [`minPatchTriangles`](../geometry/PlanarMeshOptimizationOptions.md#minpatchtriangles) · `number` · Optional
+
+  Minimum triangles required before a planar patch is eligible. Defaults to `8`.
+
+- [`triggerMaxAspectRatio`](../geometry/PlanarMeshOptimizationOptions.md#triggermaxaspectratio) · `number` · Optional
+
+  Select patches whose worst normalized aspect ratio exceeds this value. Defaults to `12`.
+
+- [`triggerMaxFanRatio`](../geometry/PlanarMeshOptimizationOptions.md#triggermaxfanratio) · `number` · Optional
+
+  Select patches whose largest per-vertex triangle share exceeds this ratio. Defaults to `0.2`.
+
+- [`triggerMaxVertexTriangleIncidence`](../geometry/PlanarMeshOptimizationOptions.md#triggermaxvertextriangleincidence) · `number` · Optional
+
+  Select patches whose largest vertex triangle incidence exceeds this value. Defaults to `16`.
+
+- [`triggerMinAngleDegrees`](../geometry/PlanarMeshOptimizationOptions.md#triggerminangledegrees) · `number` · Optional
+
+  Select patches whose smallest interior angle is below this many degrees. Defaults to `8`.
+
+- [`maxTriangles`](../geometry/PlanarMeshOptimizationOptions.md#maxtriangles) · `number` · Optional
+
+  Maximum number of triangles inspected. Defaults to `200000`.
+
+- [`tolerance`](../geometry/PlanarMeshOptimizationOptions.md#tolerance) · [`GeometryToleranceOptions`](../geometry/GeometryToleranceOptions.md) · Optional
+
+  Numeric comparison overrides; model coordinates are interpreted in their existing units.
+
+
+
+## Returns
+
+[`PlanarMeshOptimizationResult`](../geometry/PlanarMeshOptimizationResult.md)
+
+Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
+
+
+## Related APIs
+
+- [PlanarMeshOptimizationOptions](../geometry/PlanarMeshOptimizationOptions.md)
+- [PlanarMeshOptimizationResult](../geometry/PlanarMeshOptimizationResult.md)
+- [TriangleMeshInput](../geometry/TriangleMeshInput.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.

package/dist/docs/reference/mesh/preflightHeightfield.md

@@ -0,0 +1,48 @@
+# preflightHeightfield
+
+Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
+
+**preflightHeightfield**(`options`: [`HeightfieldOptions`](../geometry/HeightfieldOptions.md), `limits?`: `Partial`\<`Pick`\<[`ModelingLimits`](../geometry/ModelingLimits.md), `"maxVertices"` \| `"maxTriangles"` \| `"maxBytes"`\>\>): [`HeightfieldPreflight`](../geometry/HeightfieldPreflight.md)
+
+
+
+This pure operation needs no engine and neither evaluates `height` nor allocates mesh buffers.
+Successful preflight leaves height values, Float32 base storage, and generated mesh validity to
+construction. `byteCount` covers position and index buffers, not total working memory.
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`HeightfieldOptions`](../geometry/HeightfieldOptions.md) · Required
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<`Pick`\<[`ModelingLimits`](../geometry/ModelingLimits.md), `"maxVertices"` \| `"maxTriangles"` \| `"maxBytes"`\>\> · Optional
+
+
+
+## Returns
+
+[`HeightfieldPreflight`](../geometry/HeightfieldPreflight.md)
+
+
+## Related APIs
+
+- [HeightfieldOptions](../geometry/HeightfieldOptions.md)
+- [HeightfieldPreflight](../geometry/HeightfieldPreflight.md)
+- [ModelingLimits](../geometry/ModelingLimits.md)
+
+## Guides
+
+- [Exact counts and preflight guarantees](../../guides/resolution-and-inspection.md#check-preflight-guarantees)
+
+## Supported imports
+
+```ts
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+```
+
+Package: `@metamesh/modeling@0.19.0`.