@metamesh/modeling 0.11.0 → 0.13.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?`: [`GeometryResolution`](GeometryResolution.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`** · [`GeometryResolution`](GeometryResolution.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
+
+- [GeometryResolution](GeometryResolution.md)
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [resolveCircularSegments](resolveCircularSegments.md)
+
+Package: `@metamesh/modeling@0.13.0`.

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

@@ -0,0 +1,61 @@
+# resolveCircularSegments
+
+Resolves a deterministic full-circle segment count for one radius.
+
+**resolveCircularSegments**(`radius`: `number`, `policy?`: [`GeometryResolution`](GeometryResolution.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. 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`** · [`GeometryResolution`](GeometryResolution.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
+
+- [GeometryResolution](GeometryResolution.md)
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [resolveAlignedCircularSegments](resolveAlignedCircularSegments.md)
+- [resolveArcSegments](resolveArcSegments.md)
+
+Package: `@metamesh/modeling@0.13.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.13.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.13.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) \| [`Region`](Region.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) \| [`Region`](Region.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` \| [`Vector2`](Vector2.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)
+- [Region](Region.md)
+
+Package: `@metamesh/modeling@0.13.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.13.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.13.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.13.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.13.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.13.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.13.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 [`Vector2`](Vector2.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 [`Vector2`](Vector2.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)
+- [Vector2](Vector2.md)
+
+Package: `@metamesh/modeling@0.13.0`.

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

@@ -0,0 +1,38 @@
+# rotateAroundAxis3
+
+Rotates a vector right-handed around an axis by `angle` radians.
+
+`const` **rotateAroundAxis3**: (`vector`: [`Vector3`](Vector3.md), `axis`: [`Vector3`](Vector3.md), `angle`: `number`) => [`Vector3`](Vector3.md)
+
+
+
+## Parameters
+
+<a id="vector"></a>
+
+**`vector`** · [`Vector3`](Vector3.md) · Required
+
+
+
+<a id="axis"></a>
+
+**`axis`** · [`Vector3`](Vector3.md) · Required
+
+
+
+<a id="angle"></a>
+
+**`angle`** · `number` · Required
+
+
+
+## Returns
+
+[`Vector3`](Vector3.md)
+
+
+## Related APIs
+
+- [Vector3](Vector3.md)
+
+Package: `@metamesh/modeling@0.13.0`.

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

@@ -0,0 +1,49 @@
+# rotationTransform3
+
+Creates a right-handed axis-angle rotation transform.
+
+**rotationTransform3**(`axis`: [`Vector3`](Vector3.md), `angle`: [`AxisAngleRotation3`](AxisAngleRotation3.md), `tolerance?`: [`GeometryToleranceOptions`](GeometryToleranceOptions.md)): [`Transform3`](Transform3.md)
+
+
+
+## Parameters
+
+<a id="axis"></a>
+
+**`axis`** · [`Vector3`](Vector3.md) · Required
+
+Rotation axis; normalization is performed internally.
+
+
+
+<a id="angle"></a>
+
+**`angle`** · [`AxisAngleRotation3`](AxisAngleRotation3.md) · Required
+
+Finite right-handed angle with exactly one explicit unit.
+
+
+
+<a id="tolerance"></a>
+
+**`tolerance`** · [`GeometryToleranceOptions`](GeometryToleranceOptions.md) · Optional
+
+Optional zero-length comparison overrides.
+
+
+
+## Returns
+
+[`Transform3`](Transform3.md)
+
+A frozen row-major transform.
+
+
+## Related APIs
+
+- [AxisAngleRotation3](AxisAngleRotation3.md)
+- [GeometryToleranceOptions](GeometryToleranceOptions.md)
+- [Transform3](Transform3.md)
+- [Vector3](Vector3.md)
+
+Package: `@metamesh/modeling@0.13.0`.