@metamesh/modeling 0.17.0 → 0.19.0

package/dist/api/mesh.d.ts

@@ -0,0 +1,489 @@
+import type {
+  Bounds3Data,
+  ExtrudeMeshOptions,
+  HeightfieldMeshLimits,
+  HeightfieldOptions,
+  HeightfieldPreflight,
+  ImmutableTriangleMesh,
+  LoftMeshStation,
+  LoftOptions,
+  Path2Input,
+  Path3Input,
+  PlanarMeshOptimizationOptions,
+  PlanarMeshOptimizationResult,
+  RevolveOptions,
+  SolidMeshValidationOptions,
+  SweepOptions,
+  ThreadRidgeOptions,
+  ThreadSolidOptions,
+  ThreadSolidPreflight,
+  Transform3Input,
+  TriangleMesh,
+  TriangleMeshAnalysis,
+  TriangleMeshAnalysisOptions,
+  TriangleMeshInput,
+  TriangleMeshQualityOptions,
+  TriangleMeshQualityReport,
+  TriangleMeshSignature,
+  TriangleMeshSignatureOptions,
+  TriangleMeshTopologyAnalysis,
+  TriangleMeshValidationOptions,
+  Vector3Data,
+} from "@metamesh/modeling/geometry";
+export type {
+  AcmeThreadProfileSpec,
+  Bevel,
+  BevelSize,
+  Bounds2,
+  Bounds2Data,
+  Bounds2Input,
+  Bounds3,
+  Bounds3Data,
+  Bounds3Input,
+  ButtressPressureFlankSide,
+  ButtressThreadProfileSpec,
+  CircularPrimitiveOptions,
+  CurveSamplingOptions,
+  CustomThreadProfileSpec,
+  ExtrudeMeshOptions,
+  ExtrusionSamplingOptions,
+  Frame3,
+  GeometryResolution,
+  GeometrySamplingLimits,
+  GeometryToleranceOptions,
+  HeightfieldMeshLimits,
+  HeightfieldOptions,
+  HeightfieldPreflight,
+  ImmutableBuffer,
+  ImmutableTriangleMesh,
+  LoftCorrespondence,
+  LoftMeshStation,
+  LoftOptions,
+  LoftPlacement,
+  ModelingLimits,
+  NumericArray,
+  Path2,
+  Path2Data,
+  Path2Input,
+  Path3,
+  Path3Data,
+  Path3Input,
+  PathLocation,
+  PathNormalGuide,
+  PathResamplingOptions,
+  Pivot2Options,
+  Pivot3Options,
+  PlanarMeshOptimizationFallbackReason,
+  PlanarMeshOptimizationOptions,
+  PlanarMeshOptimizationResult,
+  PlanarPatchQuality,
+  RevolveOptions,
+  SolidMeshValidationOptions,
+  SquareThreadProfileSpec,
+  SweepOptions,
+  SweepOrientation,
+  ThreadEndStyle,
+  ThreadEndTreatmentOptions,
+  ThreadHandedness,
+  ThreadLeadInEnvelope,
+  ThreadLeadInShape,
+  ThreadProfile,
+  ThreadProfileBaseSpec,
+  ThreadProfileSpec,
+  ThreadRidgeOptions,
+  ThreadSolidOptions,
+  ThreadSolidPreflight,
+  Transform2,
+  Transform2Data,
+  Transform2Input,
+  Transform3,
+  Transform3Data,
+  Transform3Input,
+  TrapezoidalThreadProfileSpec,
+  TriangleMesh,
+  TriangleMeshAnalysis,
+  TriangleMeshAnalysisOptions,
+  TriangleMeshInput,
+  TriangleMeshMeasurements,
+  TriangleMeshQualityOptions,
+  TriangleMeshQualityReport,
+  TriangleMeshSignature,
+  TriangleMeshSignatureOptions,
+  TriangleMeshSignatureTolerances,
+  TriangleMeshTopologyAnalysis,
+  TriangleMeshValidationOptions,
+  TriangularThreadProfileSpec,
+  Vector2,
+  Vector2Data,
+  Vector2Input,
+  Vector3,
+  Vector3Data,
+  Vector3Input,
+} from "@metamesh/modeling/geometry";
+
+/**
+ * Validates and measures a mesh with one pass over positions and one over triangles.
+ *
+ * Bounds, area in square model units and signed volume in cubic model units are computed without
+ * copying or changing the input buffers. Volume is meaningful for consistently wound closed
+ * geometry; `requireClosed` checks oriented edge closure. Optional indexed topology counts require
+ * every position vertex to be referenced and do not establish freedom from self-intersections.
+ * Results and nested bounds are immutable snapshots. Caller-owned mutable meshes are freshly
+ * inspected on every call, never cached.
+ */
+export declare function analyze(
+  mesh: TriangleMeshInput,
+  options: TriangleMeshAnalysisOptions & {
+    readonly includeTopology: true;
+  },
+): TriangleMeshTopologyAnalysis;
+
+/** Measures a mesh; topology fields are present only when includeTopology is enabled. */
+export declare function analyze(
+  mesh: TriangleMeshInput,
+  options?: TriangleMeshAnalysisOptions,
+): TriangleMeshAnalysis;
+
+/**
+ * Measures triangle shape, edge topology, vertex concentration, and connected planar patches.
+ *
+ * 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.
+ *
+ * @param mesh - Indexed triangle mesh in arbitrary consistent model units.
+ * @param options - Scale-aware tolerance and analysis budget.
+ * @returns A deterministic report without mutating or copying the mesh.
+ */
+export declare function analyzeQuality(
+  mesh: TriangleMeshInput,
+  options?: TriangleMeshQualityOptions,
+): TriangleMeshQualityReport;
+
+/**
+ * Computes axis-aligned bounds for a non-empty mesh.
+ *
+ * @param mesh - Mesh whose finite complete vertices will be measured.
+ * @returns Fresh immutable minimum and maximum XYZ tuples.
+ * @throws `GeometryError` When the mesh is structurally invalid.
+ */
+export declare const bounds: (mesh: TriangleMeshInput) => Bounds3Data;
+
+/**
+ * Computes the uniform-density volume centroid of an oriented closed solid, including cavity shells.
+ *
+ * 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.
+ *
+ * @param mesh - Consistently oriented closed mesh with positive enclosed volume.
+ * @returns A fresh immutable XYZ volume centroid.
+ */
+export declare function centroid(mesh: TriangleMeshInput): Vector3Data;
+
+/**
+ * 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.
+ *
+ * @example Extrude point data without an engine
+ * ```ts
+ * const outline = rectangleContour({ size: [30, 20], treatment: { kind: "round", radius: 3 } });
+ * mesh.extrude(outline, { height: 8 });
+ * ```
+ */
+export declare function extrude(
+  input: Path2Input,
+  options: ExtrudeMeshOptions,
+): TriangleMesh;
+
+/**
+ * Builds a closed indexed mesh from a rectilinear top, matched boundary walls, and flat base.
+ *
+ * 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.
+ *
+ * @see `mesh.preflightHeightfield`
+ *
+ * @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),
+ * });
+ * ```
+ */
+export declare function heightfield(
+  options: HeightfieldOptions,
+  limits?: HeightfieldMeshLimits,
+): TriangleMesh;
+
+/**
+ * Copies mesh buffers into immutable data; geometric validation still occurs when modeling or finalizing.
+ * @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)));
+ * ```
+ */
+export declare function immutable(mesh: {
+  readonly positions: Float32Array;
+  readonly indices: Uint32Array;
+}): ImmutableTriangleMesh;
+
+/**
+ * Concatenates meshes into one indexed mesh without welding coincident vertices.
+ *
+ * Inputs are validated and never mutated. Face order and winding remain stable.
+ *
+ * @param meshes - One or more meshes to concatenate.
+ * @returns Fresh typed arrays with indices offset to their source vertex ranges.
+ * @throws `GeometryError` When no mesh is supplied or an input is invalid.
+ */
+export declare function join(
+  meshes: readonly TriangleMeshInput[],
+): TriangleMesh;
+
+/**
+ * Lofts simple point loops at z heights or explicit right-handed frames, in input order.
+ *
+ * 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.
+ *
+ * @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" });
+ * ```
+ */
+export declare function loft(
+  stations: readonly LoftMeshStation[],
+  options?: LoftOptions,
+): TriangleMesh;
+
+/** Shading policy for a render copy; manufacturing positions and triangle order never change. */
+export declare interface MeshRenderOptions {
+  /** Maximum angle between averaged face normals, in degrees. Defaults to `20`; `0` is flat. */
+  readonly creaseAngle?: number;
+}
+
+/**
+ * Improves pathological planar triangulation with bounded legal diagonal flips.
+ *
+ * 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.
+ *
+ * @param mesh - Closed, consistently wound indexed triangle mesh in arbitrary consistent units.
+ * @param options - Patch eligibility, numeric tolerance, and deterministic work bounds.
+ * @returns Optimized connectivity and before/after diagnostics, or an unchanged safe fallback.
+ */
+export declare function optimizePlanarPatches(
+  mesh: TriangleMeshInput,
+  options?: PlanarMeshOptimizationOptions,
+): PlanarMeshOptimizationResult;
+
+/**
+ * Checks grid options, Float32 axis precision, and output limits; returns exact mesh buffer counts.
+ *
+ * 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.
+ *
+ * @see `mesh.heightfield`
+ */
+export declare function preflightHeightfield(
+  options: HeightfieldOptions,
+  limits?: HeightfieldMeshLimits,
+): HeightfieldPreflight;
+
+/**
+ * Checks thread dimensions, profile, end treatments, sampling, and conservative estimates against output limits.
+ *
+ * This pure operation needs no engine and constructs planning data without vertex or index buffers.
+ * `circularSegments` is the selected count; row and triangle counts are conservative estimates.
+ * Successful preflight leaves generated coordinate and topology checks to mesh construction.
+ *
+ * See `mesh.threadSolid` for standalone mesh construction.
+ */
+export declare function preflightThreadSolid(
+  options: ThreadSolidOptions,
+): ThreadSolidPreflight;
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import * as mesh from "@metamesh/modeling/geometry/mesh";
+ * const surface = mesh.heightfield({ size: [10, 10], segments: [2, 2], height: () => 0 });
+ * const rendered = mesh.render(surface);
+ * // rendered.positions and rendered.normals can be passed to a renderer or GLB writer.
+ * ```
+ */
+export declare function render(
+  input: TriangleMeshInput,
+  options?: MeshRenderOptions,
+): RenderMesh;
+
+/** Owned indexed render buffers with unit vertex normals and positions in millimetres. */
+export declare interface RenderMesh extends TriangleMesh {
+  /** XYZ unit normals, one for each render vertex. Vertices split at shading discontinuities. */
+  readonly normals: Float32Array;
+}
+
+/**
+ * Returns a copy of a mesh with every triangle winding reversed.
+ *
+ * @param mesh - Mesh to copy and reverse.
+ * @returns Fresh position and index buffers; the input remains unchanged.
+ */
+export declare function reverse(mesh: TriangleMeshInput): TriangleMesh;
+
+/**
+ * Revolves a non-duplicated closed `[radius, z]` profile around +Z.
+ *
+ * The profile is ordered counter-clockwise when radius points right and Z
+ * points up. Angular and profile seams wrap by index. A profile point on the
+ * axis is emitted once and joined as a triangle fan, avoiding coincident seam
+ * vertices and zero-area quads. Profile edges that lie entirely on the axis
+ * collapse to the solid's interior and are intentionally omitted.
+ * Profile coordinates must fit finite Float32 mesh storage.
+ * Path2 profiles must be closed; raw point collections have an implicit closing edge.
+ *
+ * @param profile - Closed CCW `[radius, z]` profile without a duplicated seam point.
+ * @param options - Optional physical or exact circumferential sampling controls. Defaults to `{}`.
+ * @returns A closed indexed triangle mesh revolved counter-clockwise around +Z.
+ *
+ * @example Partial revolution with end caps
+ * ```ts
+ * // Each point is [radius, Z]; the profile seam is implicit.
+ * mesh.revolve([[0, 0], [12, 0], [8, 20], [0, 20]], { degrees: 270 });
+ * ```
+ */
+export declare const revolve: (
+  input: Path2Input,
+  options?: RevolveOptions,
+) => TriangleMesh;
+
+/**
+ * Creates an order-independent regression signature for a manufacturing mesh.
+ *
+ * The input must be non-empty, closed, consistently wound, and have no unreferenced vertices.
+ * Vertex and triangle order do not affect the fingerprint; winding, quantized geometry, and
+ * connectivity metrics do. The fingerprint is a regression aid, not a cryptographic digest.
+ *
+ * @param mesh - Closed oriented mesh to measure without mutation.
+ * @param options - Absolute quantization and complexity limits.
+ * @returns Compact counts, bounds, volume, topology, tolerances, and canonical fingerprint.
+ * @throws `GeometryError` When validation, topology, tolerance, or complexity checks fail.
+ */
+export declare function signature(
+  mesh: TriangleMeshInput,
+  options?: TriangleMeshSignatureOptions,
+): TriangleMeshSignature;
+
+/**
+ * Sweeps one explicitly ordered point loop, with caps or a geometrically matching closed seam.
+ *
+ * @example Sweep point data along a bent path
+ * ```ts
+ * const profile = rectangleContour({ size: [6, 3] });
+ * mesh.sweep(profile, [[0, 0, 0], [0, 0, 15], [10, 0, 25]], {
+ *   orientation: { kind: "transport", initialNormal: [0, 1, 0] },
+ * });
+ * ```
+ */
+export declare function sweep(
+  profile: Path2Input,
+  path: Path3Input,
+  options?: SweepOptions,
+): TriangleMesh;
+
+/**
+ * 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.
+ */
+export declare function threadRidge(options: ThreadRidgeOptions): TriangleMesh;
+
+/**
+ * Builds one closed threaded cylinder without a ridge/core Boolean seam.
+ *
+ * Each circular facet includes its exact phase-shifted profile breakpoints, including duplicate-Z
+ * samples for vertical flanks and blunt transitions. Adjacent variable grids are stitched as a
+ * monotone strip, with optional intermediate rows bounded by physical `maxSegmentLength`. A
+ * conservative pre-allocation estimate rejects excessive meshes before constructing position
+ * arrays.
+ */
+export declare function threadSolid(options: ThreadSolidOptions): TriangleMesh;
+
+/**
+ * Applies an affine transform to a mesh and preserves outward face orientation.
+ *
+ * A transform with a negative linear determinant reflects space, so this helper
+ * automatically reverses every triangle. Singular transforms are rejected.
+ *
+ * @param mesh - Mesh to transform without mutation.
+ * @param placement - Immutable spatial placement or canonical row-major affine matrix.
+ * @returns A mesh with fresh transformed positions and copied or reversed indices.
+ */
+export declare function transform(
+  mesh: TriangleMeshInput,
+  placement: Transform3Input,
+): TriangleMesh;
+
+/**
+ * Validates mesh buffers, indices, triangle area, and optionally closed topology.
+ *
+ * Closed validation requires exactly two oppositely directed uses per edge, rejecting boundary
+ * and non-manifold edges. It establishes edge connectivity without detecting geometric
+ * self-intersections between faces. The mesh is neither mutated nor copied.
+ *
+ * @param mesh - Mesh to inspect.
+ * @param options - Empty-mesh, topology, and tolerance policy.
+ * @returns The original mesh after successful validation.
+ * @throws `GeometryError` When any requested invariant fails.
+ */
+export declare function validate<T extends TriangleMeshInput>(
+  mesh: T,
+  options?: TriangleMeshValidationOptions,
+): T;
+
+/**
+ * Checks closed indexed topology, triangle intersections, and alternating nested shell orientation.
+ *
+ * Outward exterior shells and inward cavity shells are accepted. Separate shells must not touch,
+ * intersect, or overlap as material. Indexed neighbours may share their own vertex or edge.
+ *
+ * Uses bounded floating-point tests, not exact predicates or repair. Contacts within the selected
+ * tolerance reject conservatively. At most 200,000 triangles and 2,000,000 spatial/containment tests
+ * are supported; exhausting a ceiling throws COMPLEXITY_LIMIT rather than claiming validity.
+ * Input buffers are freshly inspected and never modified; units are millimetres.
+ *
+ * @param mesh - Closed triangle mesh to inspect.
+ * @param options - Optional lower work ceiling and numeric comparison policy.
+ * @returns The original mesh after every requested check succeeds.
+ */
+export declare function validateSolid<T extends TriangleMeshInput>(
+  mesh: T,
+  options?: SolidMeshValidationOptions,
+): T;
+
+export {};

package/dist/api/text.d.ts

@@ -6,7 +6,7 @@ export declare interface Bounds2Data {
   readonly min: Vector2Data;
 }
 
-/** Limits apply before parsing or shaping untrusted font data. */
+/** Maximum input font size in bytes, checked before parsing or shaping untrusted font data. */
 export declare const MAX_VECTOR_FONT_BYTES: number;
 
 /**