@metamesh/modeling 0.12.0 → 0.14.0

package/dist/docs/reference/geometry/resolveAlignedCircularSegments.md

@@ -0,0 +1,83 @@
+# resolveAlignedCircularSegments
+
+Resolves a deterministic full-circle count aligned to reusable topology factors.
+
+**resolveAlignedCircularSegments**(`radius`: `number`, `options`: [`AlignedCircularSegmentsOptions`](AlignedCircularSegmentsOptions.md)): `number`
+
+
+
+## Example
+
+```ts
+const alignedSegments = resolveAlignedCircularSegments(20, { alignTo: [4, 6] });
+```
+
+`alignTo` must be non-empty and contain only positive safe integers. Its checked least common
+multiple defines the alignment grid. An exact `segments` value wins over
+`resolution.circularSegments` and adaptive sampling, but is never rounded: it must already be
+aligned and meet `minimumSegments`. Adaptive counts are rounded upward and fail with
+`COMPLEXITY_LIMIT` when the aligned result exceeds the configured safety cap.
+
+## Parameters
+
+<a id="radius"></a>
+
+**`radius`** · `number` · Required
+
+Positive circle radius in millimetres used for adaptive physical sampling.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`AlignedCircularSegmentsOptions`](AlignedCircularSegmentsOptions.md) · Required
+
+Required alignment factors plus optional floor, exact count, and resolution.
+
+- [`alignTo`](AlignedCircularSegmentsOptions.md#alignto) · readonly `number`[] · Required
+
+  Non-empty alignment factors. Every value must be a positive safe integer; the returned count
+  is divisible by their checked least common multiple.
+
+- [`sizing`](AlignedCircularSegmentsOptions.md#sizing) · [`RadialSizing`](RadialSizing.md) · Optional
+
+  Radial sizing used by adaptive error and edge-length checks. Defaults to vertex.
+
+- [`limits`](AlignedCircularSegmentsOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit sampling allocation ceilings.
+
+- [`minimumSegments`](AlignedCircularSegmentsOptions.md#minimumsegments) · `number` · Optional · Default: `3`
+
+  Additional full-circle segment floor, as a safe integer of at least three.
+
+- [`segments`](AlignedCircularSegmentsOptions.md#segments) · `number` · Optional
+
+  Exact full-circle segment count.
+
+  This takes precedence over `resolution.circularSegments` and adaptive sampling, and must
+  already satisfy every alignment factor and `minimumSegments`.
+
+- [`resolution`](AlignedCircularSegmentsOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Operation-level physical tessellation policy over the active model-wide policy.
+
+
+
+## Returns
+
+`number`
+
+An aligned full-circle segment count.
+
+
+## Throws
+
+- GeometryError when radius, alignment factors, segment floors, or resolution are invalid, or alignment exceeds safe integer or configured complexity limits.
+
+## Related APIs
+
+- [AlignedCircularSegmentsOptions](AlignedCircularSegmentsOptions.md)
+- [resolveCircularSegments](resolveCircularSegments.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveArcSegments.md

@@ -0,0 +1,67 @@
+# resolveArcSegments
+
+Resolves the number of segments needed for a circular arc.
+
+**resolveArcSegments**(`radius`: `number`, `angleDegrees`: `number`, `policy?`: [`CircularResolutionOptions`](CircularResolutionOptions.md), `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>): `number`
+
+
+
+## Example
+
+```ts
+const quarterTurnSegments = resolveArcSegments(10, 90);
+```
+
+Full-circle limits and exact circular counts are scaled to the requested angular span, matching
+the reusable BOSL2-style convention while retaining at least one segment.
+
+## Parameters
+
+<a id="radius"></a>
+
+**`radius`** · `number` · Required
+
+Arc radius in millimetres.
+
+
+
+<a id="angledegrees"></a>
+
+**`angleDegrees`** · `number` · Required
+
+Non-zero signed sweep angle no greater than 360 degrees in magnitude.
+
+
+
+<a id="policy"></a>
+
+**`policy`** · [`CircularResolutionOptions`](CircularResolutionOptions.md) · Optional
+
+Optional operation-level policy over the active model scope.
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+
+
+## Returns
+
+`number`
+
+Segment count for the requested arc span.
+
+
+## Throws
+
+- GeometryError when radius, angle, or resolution policy is invalid, or the corresponding full-circle tolerance exceeds the configured safety limit.
+
+## Related APIs
+
+- [CircularResolutionOptions](CircularResolutionOptions.md)
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [resolveCircularSegments](resolveCircularSegments.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveCircularSegments.md

@@ -0,0 +1,62 @@
+# resolveCircularSegments
+
+Resolves a deterministic full-circle segment count for one radius.
+
+**resolveCircularSegments**(`radius`: `number`, `policy?`: [`CircularResolutionOptions`](CircularResolutionOptions.md), `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>): `number`
+
+
+
+## Example
+
+```ts
+const circleSegments = resolveCircularSegments(25, { maxChordError: 0.05 });
+```
+
+An exact `circularSegments` value wins. Otherwise the smallest regular polygon satisfying both
+physical error criteria is used. Face sizing bounds the circumscribed polygon's outward
+excess and actual edge length. A safety cap that would violate either criterion raises
+`COMPLEXITY_LIMIT` rather than silently reducing quality.
+
+## Parameters
+
+<a id="radius"></a>
+
+**`radius`** · `number` · Required
+
+Circle radius in millimetres.
+
+
+
+<a id="policy"></a>
+
+**`policy`** · [`CircularResolutionOptions`](CircularResolutionOptions.md) · Optional
+
+Optional operation-level policy under explicit sampling ceilings.
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+
+
+## Returns
+
+`number`
+
+Full-circle segment count.
+
+
+## Throws
+
+- GeometryError when radius or policy is invalid, or the requested tolerance exceeds the configured segment safety limit.
+
+## Related APIs
+
+- [CircularResolutionOptions](CircularResolutionOptions.md)
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [resolveAlignedCircularSegments](resolveAlignedCircularSegments.md)
+- [resolveArcSegments](resolveArcSegments.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveCylindricalGear.md

@@ -0,0 +1,31 @@
+# resolveCylindricalGear
+
+Resolves a validated unshifted full-depth external cylindrical gear.
+
+**resolveCylindricalGear**(`spec`: [`CylindricalGearSpec`](CylindricalGearSpec.md)): [`CylindricalGearDimensions`](CylindricalGearDimensions.md)
+
+
+
+The gear axis is +Z and the returned radii describe its XY pitch plane. Inputs below the
+pressure- and helix-dependent no-undercut tooth count are rejected because profile shift is not
+currently supported.
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`CylindricalGearSpec`](CylindricalGearSpec.md) · Required
+
+
+
+## Returns
+
+[`CylindricalGearDimensions`](CylindricalGearDimensions.md)
+
+
+## Related APIs
+
+- [CylindricalGearDimensions](CylindricalGearDimensions.md)
+- [CylindricalGearSpec](CylindricalGearSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveCylindricalGearPair.md

@@ -0,0 +1,31 @@
+# resolveCylindricalGearPair
+
+Resolves ratio, center distance, and helix relationship for a gear pair.
+
+**resolveCylindricalGearPair**(`spec`: [`CylindricalGearPairSpec`](CylindricalGearPairSpec.md)): [`CylindricalGearPairDimensions`](CylindricalGearPairDimensions.md)
+
+
+
+Both gears must use the same normal module, pressure angle, and helix-angle
+magnitude. An external pair uses opposite helix hands; an internal pair uses
+the same hand. The function validates those conjugate pitch invariants.
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`CylindricalGearPairSpec`](CylindricalGearPairSpec.md) · Required
+
+
+
+## Returns
+
+[`CylindricalGearPairDimensions`](CylindricalGearPairDimensions.md)
+
+
+## Related APIs
+
+- [CylindricalGearPairDimensions](CylindricalGearPairDimensions.md)
+- [CylindricalGearPairSpec](CylindricalGearPairSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveExtrusionDivisions.md

@@ -0,0 +1,74 @@
+# resolveExtrusionDivisions
+
+Resolves intermediate profile copies for linear extrusion from physical curve resolution.
+
+**resolveExtrusionDivisions**(`profile`: [`Contour`](Contour.md) \| [`RegionData`](RegionData.md), `height`: `number`, `options?`: [`ExtrusionSamplingOptions`](ExtrusionSamplingOptions.md)): `number`
+
+
+
+Accepts one XY loop or a filled XY region, including every hole and disconnected component.
+Exact `divisions`, including zero, override physical sampling. Otherwise chord error bounds
+the triangulated side surface, including rotation across each profile edge. Optional segment
+length bounds station travel including Z. Straight extrusions need no intermediate copies by default.
+Exceeding the selected maxPathPoints ceiling raises `COMPLEXITY_LIMIT` instead of reducing fidelity.
+
+## Parameters
+
+<a id="profile"></a>
+
+**`profile`** · [`Contour`](Contour.md) \| [`RegionData`](RegionData.md) · Required
+
+Ordered XY millimetre contours with implicit closing edges.
+
+
+
+<a id="height"></a>
+
+**`height`** · `number` · Required
+
+Positive extrusion height in millimetres.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`ExtrusionSamplingOptions`](ExtrusionSamplingOptions.md) · Optional
+
+Twist, scale, exact divisions, and physical resolution controls.
+
+- [`divisions`](ExtrusionSamplingOptions.md#divisions) · `number` · Optional
+
+  Exact number of intermediate profiles, nonnegative; overrides physical sampling.
+
+- [`limits`](ExtrusionSamplingOptions.md#limits) · `Partial`\<[`ModelingLimits`](ModelingLimits.md)\> · Optional
+
+  Explicit output and sampling allocation ceilings.
+
+- [`resolution`](ExtrusionSamplingOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Operation-level physical policy over the nearest model scope.
+
+- [`scaleTop`](ExtrusionSamplingOptions.md#scaletop) · `number` \| [`Vector2Tuple`](Vector2Tuple.md) · Optional
+
+  Finite uniform or XY scale of the top profile; defaults to one.
+
+- [`twistDegrees`](ExtrusionSamplingOptions.md#twistdegrees) · `number` · Optional
+
+  Finite rotation of the top profile about +Z, in degrees; defaults to zero.
+
+
+
+## Returns
+
+`number`
+
+Number of intermediate copies, excluding the two end profiles.
+
+
+## Related APIs
+
+- [Contour](Contour.md)
+- [ExtrusionSamplingOptions](ExtrusionSamplingOptions.md)
+- [RegionData](RegionData.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveGeometrySamplingLimits.md

@@ -0,0 +1,26 @@
+# resolveGeometrySamplingLimits
+
+Resolves finite positive safe-integer allocation ceilings without ambient state.
+
+**resolveGeometrySamplingLimits**(`overrides?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>): [`GeometrySamplingLimits`](GeometrySamplingLimits.md)
+
+
+
+## Parameters
+
+<a id="overrides"></a>
+
+**`overrides`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+
+
+## Returns
+
+[`GeometrySamplingLimits`](GeometrySamplingLimits.md)
+
+
+## Related APIs
+
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveGeometryTolerance.md

@@ -0,0 +1,59 @@
+# resolveGeometryTolerance
+
+Resolves comparison tolerances for a characteristic model scale.
+
+**resolveGeometryTolerance**(`scale?`: `number`, `options?`: [`GeometryToleranceOptions`](GeometryToleranceOptions.md)): [`ResolvedGeometryTolerance`](ResolvedGeometryTolerance.md)
+
+
+
+The effective linear tolerance is `max(absolute, relative * abs(scale))`.
+A zero scale retains the absolute floor. Returns a new frozen value with finite distance and
+area thresholds without mutating `options`.
+
+## Parameters
+
+<a id="scale"></a>
+
+**`scale`** · `number` · Optional
+
+Finite characteristic size in model units.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`GeometryToleranceOptions`](GeometryToleranceOptions.md) · Optional
+
+Optional policy overrides.
+
+- [`absolute`](GeometryToleranceOptions.md#absolute) · `number` · Optional
+
+  Absolute distance floor in model units. Must be finite and greater than zero.
+
+- [`angular`](GeometryToleranceOptions.md#angular) · `number` · Optional
+
+  Angular comparison threshold in radians. Must be finite and greater than zero.
+
+- [`relative`](GeometryToleranceOptions.md#relative) · `number` · Optional
+
+  Dimensionless scale multiplier. Must be finite and non-negative.
+
+
+
+## Returns
+
+[`ResolvedGeometryTolerance`](ResolvedGeometryTolerance.md)
+
+A complete tolerance policy including the scale-resolved distance.
+
+
+## Throws
+
+- GeometryError When a scale or override is invalid.
+
+## Related APIs
+
+- [GeometryToleranceOptions](GeometryToleranceOptions.md)
+- [ResolvedGeometryTolerance](ResolvedGeometryTolerance.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolvePrintableThreadFitPolicy.md

@@ -0,0 +1,27 @@
+# resolvePrintableThreadFitPolicy
+
+Resolves and validates a named or caller-defined print-fit policy.
+
+**resolvePrintableThreadFitPolicy**(`fit?`: [`PrintableThreadFit`](PrintableThreadFit.md) \| [`PrintableThreadFitPolicy`](PrintableThreadFitPolicy.md)): [`PrintableThreadFitPolicy`](PrintableThreadFitPolicy.md)
+
+
+
+## Parameters
+
+<a id="fit"></a>
+
+**`fit`** · [`PrintableThreadFit`](PrintableThreadFit.md) \| [`PrintableThreadFitPolicy`](PrintableThreadFitPolicy.md) · Optional
+
+
+
+## Returns
+
+[`PrintableThreadFitPolicy`](PrintableThreadFitPolicy.md)
+
+
+## Related APIs
+
+- [PrintableThreadFit](PrintableThreadFit.md)
+- [PrintableThreadFitPolicy](PrintableThreadFitPolicy.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveRackPitch.md

@@ -0,0 +1,27 @@
+# resolveRackPitch
+
+Resolves a rack segment that is conjugate with the same normal cylindrical pitch system.
+
+**resolveRackPitch**(`spec`: [`RackPitchSpec`](RackPitchSpec.md)): [`RackPitchDimensions`](RackPitchDimensions.md)
+
+
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`RackPitchSpec`](RackPitchSpec.md) · Required
+
+
+
+## Returns
+
+[`RackPitchDimensions`](RackPitchDimensions.md)
+
+
+## Related APIs
+
+- [RackPitchDimensions](RackPitchDimensions.md)
+- [RackPitchSpec](RackPitchSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/resolveThreadCircularSegments.md

@@ -0,0 +1,59 @@
+# resolveThreadCircularSegments
+
+Resolves a role-independent, start-aligned facet count from the larger female mating envelope.
+
+**resolveThreadCircularSegments**(`options`: [`ThreadCircularSegmentsOptions`](ThreadCircularSegmentsOptions.md)): `number`
+
+
+
+An exact `circularSegments` value must already be divisible by `starts`; it is never silently
+raised. Adaptive policies align upward and fail if that would exceed `maximumSegments`.
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`ThreadCircularSegmentsOptions`](ThreadCircularSegmentsOptions.md) · Required
+
+- [`nominalMajorDiameter`](ThreadCircularSegmentsOptions.md#nominalmajordiameter) · `number` · Required
+
+  Nominal major diameter before role-specific compensation.
+
+- [`profile`](ThreadCircularSegmentsOptions.md#profile) · [`ThreadProfile`](ThreadProfile.md) · Required
+
+  Validated mating profile whose pitch and flank capacities govern tessellation.
+
+- [`limits`](ThreadCircularSegmentsOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit circular allocation ceiling for the shared mating grid.
+
+- [`fit`](ThreadCircularSegmentsOptions.md#fit) · [`PrintableThreadFit`](PrintableThreadFit.md) \| [`PrintableThreadFitPolicy`](PrintableThreadFitPolicy.md) · Optional
+
+  Printable fit whose larger compensated female envelope governs tessellation.
+
+- [`maximumRadialOutset`](ThreadCircularSegmentsOptions.md#maximumradialoutset) · `number` · Optional
+
+  Maximum active female face outset beyond the compensated major envelope, in millimetres.
+  This keeps a compensated male/female pair on one role-independent grid when an internal
+  cutter has an enlarged entrance bevel. Default: `0`.
+
+- [`resolution`](ThreadCircularSegmentsOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Physical or exact circular resolution policy.
+
+- [`starts`](ThreadCircularSegmentsOptions.md#starts) · `number` · Optional
+
+  Number of phased starts. Default: `1`.
+
+
+
+## Returns
+
+`number`
+
+
+## Related APIs
+
+- [ThreadCircularSegmentsOptions](ThreadCircularSegmentsOptions.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/reverseTriangleMesh.md

@@ -0,0 +1,30 @@
+# reverseTriangleMesh
+
+Returns a copy of a mesh with every triangle winding reversed.
+
+**reverseTriangleMesh**(`mesh`: [`TriangleMesh`](TriangleMesh.md)): [`TriangleMesh`](TriangleMesh.md)
+
+
+
+## Parameters
+
+<a id="mesh"></a>
+
+**`mesh`** · [`TriangleMesh`](TriangleMesh.md) · Required
+
+Mesh to copy and reverse.
+
+
+
+## Returns
+
+[`TriangleMesh`](TriangleMesh.md)
+
+Fresh position and index buffers; the input remains unchanged.
+
+
+## Related APIs
+
+- [TriangleMesh](TriangleMesh.md)
+
+Package: `@metamesh/modeling@0.14.0`.

package/dist/docs/reference/geometry/revolveMesh.md

@@ -0,0 +1,76 @@
+# revolveMesh
+
+Revolves a non-duplicated closed `[radius, z]` profile around +Z.
+
+`const` **revolveMesh**: (`profile`: readonly [`Vector2Tuple`](Vector2Tuple.md)[], `options?`: [`RevolveOptions`](RevolveOptions.md)) => [`TriangleMesh`](TriangleMesh.md)
+
+
+
+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.
+
+## Example: Partial revolution with end caps
+
+```ts
+// Each point is [radius, Z]; the profile seam is implicit.
+revolveMesh([[0, 0], [12, 0], [8, 20], [0, 20]], { revolveDegrees: 270 });
+```
+
+## Parameters
+
+<a id="profile"></a>
+
+**`profile`** · readonly [`Vector2Tuple`](Vector2Tuple.md)[] · Required
+
+Closed CCW `[radius, z]` profile without a duplicated seam point.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`RevolveOptions`](RevolveOptions.md) · Optional
+
+Optional physical or exact circumferential sampling controls. Defaults to `{}`.
+
+- [`segments`](RevolveOptions.md#segments) · `number` · Optional
+
+  Exact circumferential segment count from three through the configured safety limit.
+
+  This local topology override takes precedence over [CircularPrimitiveOptions.resolution](CircularPrimitiveOptions.md#resolution)
+  and any active model-wide resolution policy.
+
+- [`resolution`](RevolveOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Operation-level physical tessellation policy over the active model-wide policy.
+
+- [`revolveDegrees`](RevolveOptions.md#revolvedegrees) · `number` · Optional
+
+  Positive angular sweep no greater than 360 degrees; partial revolutions have end caps.
+  Segment counts describe a complete circle and scale to this angular span. Native filled
+  revolutions require at least three sweep intervals: adaptive sampling refines to that floor,
+  while exact counts that imply fewer intervals reject. Pure revolveMesh supports one interval.
+
+- [`limits`](RevolveOptions.md#limits) · `Partial`\<[`ModelingLimits`](ModelingLimits.md)\> · Optional
+
+  Explicit output and sampling allocation ceilings.
+
+
+
+## Returns
+
+[`TriangleMesh`](TriangleMesh.md)
+
+A closed indexed triangle mesh revolved counter-clockwise around +Z.
+
+
+## Related APIs
+
+- [RevolveOptions](RevolveOptions.md)
+- [TriangleMesh](TriangleMesh.md)
+- [Vector2Tuple](Vector2Tuple.md)
+
+Package: `@metamesh/modeling@0.14.0`.