@metamesh/modeling 0.12.0 → 0.14.0

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

@@ -0,0 +1,36 @@
+# rotate2
+
+Rotates a finite vector counter-clockwise in XY by `degrees` about the origin. Throws `NON_FINITE_VALUE` for nonfinite coordinates, angles, or derived coordinates.
+
+`const` **rotate2**: (`vector`: [`Vector2Tuple`](Vector2Tuple.md), `degrees`: `number`) => [`Vector2Tuple`](Vector2Tuple.md)
+
+
+
+## Parameters
+
+<a id="vector"></a>
+
+**`vector`** · [`Vector2Tuple`](Vector2Tuple.md) · Required
+
+
+
+<a id="degrees"></a>
+
+**`degrees`** · `number` · Required
+
+
+
+## Returns
+
+[`Vector2Tuple`](Vector2Tuple.md)
+
+
+## Related APIs
+
+- [Vector2Tuple](Vector2Tuple.md)
+
+## Guides
+
+- [Reusable transforms and vector math](../../guides/concepts.md#reuse-a-transform-across-shapes-and-coordinates)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,53 @@
+# rotationTransform3
+
+Creates a right-handed axis-angle rotation transform.
+
+**rotationTransform3**(`axis`: [`Vector3Tuple`](Vector3Tuple.md), `angle`: [`AxisAngleRotation3`](AxisAngleRotation3.md), `tolerance?`: [`GeometryToleranceOptions`](GeometryToleranceOptions.md)): [`Transform3Matrix`](Transform3Matrix.md)
+
+
+
+## Parameters
+
+<a id="axis"></a>
+
+**`axis`** · [`Vector3Tuple`](Vector3Tuple.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
+
+[`Transform3Matrix`](Transform3Matrix.md)
+
+A frozen row-major transform.
+
+
+## Related APIs
+
+- [AxisAngleRotation3](AxisAngleRotation3.md)
+- [GeometryToleranceOptions](GeometryToleranceOptions.md)
+- [Transform3Matrix](Transform3Matrix.md)
+- [Vector3Tuple](Vector3Tuple.md)
+
+## Guides
+
+- [Reusable transforms and vector math](../../guides/concepts.md#reuse-a-transform-across-shapes-and-coordinates)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,50 @@
+# roundClosedPolylinePath
+
+Replaces each vertex of a non-duplicated closed polyline with a sampled quadratic corner in the same coordinate system as the input.
+
+`const` **roundClosedPolylinePath**: (`points`: readonly [`Vector3Tuple`](Vector3Tuple.md)[], `radius`: `number`, `segmentsPerCorner`: `number`, `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>) => readonly [`Vector3Tuple`](Vector3Tuple.md)[]
+
+
+
+`radius` is the desired tangent distance for a right angle and is capped to
+45% of adjacent segment lengths to prevent neighboring corners from crossing.
+The returned path does not duplicate its closing point.
+Coordinates and radius must be finite; input and output are each limited by maxPathPoints (default 100000).
+
+## Parameters
+
+<a id="points"></a>
+
+**`points`** · readonly [`Vector3Tuple`](Vector3Tuple.md)[] · Required
+
+
+
+<a id="radius"></a>
+
+**`radius`** · `number` · Required
+
+
+
+<a id="segmentspercorner"></a>
+
+**`segmentsPerCorner`** · `number` · Required
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+
+
+## Returns
+
+readonly [`Vector3Tuple`](Vector3Tuple.md)[]
+
+
+## Related APIs
+
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [Vector3Tuple](Vector3Tuple.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,77 @@
+# sampleContour
+
+Samples 2–32 connected line/cubic segments into a simple, nonzero-area, immutable CCW XY loop. Physical scaling precedes adaptive curve sampling; the final end must repeat start exactly. Shared anchors and the closing seam are emitted once. Winding normalization may change the starting vertex. The sampled loop is checked for self-intersection and degeneracy by `normalizeContour`; this is a single contour without holes. No editor modes or normalized coordinate range are required. No native engine, SDK, or ambient resolution is used.
+
+**sampleContour**(`curve`: [`ContourCurve`](ContourCurve.md), `options?`: [`SampleContourOptions`](SampleContourOptions.md)): [`Contour`](Contour.md)
+
+
+
+## Example
+
+```ts
+const section = sampleContour({
+  start: { x: 0, y: 0 },
+  segments: [
+    { type: "line", end: { x: 1, y: 0 } },
+    { type: "line", end: { x: 0.5, y: 1 } },
+    { type: "line", end: { x: 0, y: 0 } },
+  ],
+}, { widthScale: 20, heightScale: 12 });
+```
+
+## Parameters
+
+<a id="curve"></a>
+
+**`curve`** · [`ContourCurve`](ContourCurve.md) · Required
+
+Closed contour in millimetres unless positive scales convert its coordinates.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`SampleContourOptions`](SampleContourOptions.md) · Optional
+
+Physical resolution and unique vertex budget; defaults to 4096 vertices.
+
+- [`widthScale`](SampleContourOptions.md#widthscale) · `number` · Optional
+
+  Positive horizontal scale; normalized inputs span this width envelope. Defaults to 1.
+
+- [`heightScale`](SampleContourOptions.md#heightscale) · `number` · Optional
+
+  Positive vertical scale; normalized inputs span this height envelope. Defaults to 1.
+
+- [`resolution`](SampleContourOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Physical policy evaluated after scaling, using the shared curve sampler.
+
+- [`maximumVertices`](SampleContourOptions.md#maximumvertices) · `number` · Optional
+
+  Unique output vertex ceiling, at least three, within maxProfilePoints. Defaults to min(4096, maxProfilePoints).
+
+- [`limits`](SampleContourOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Selected profile and per-segment path ceilings; omitted values use package defaults.
+
+
+
+## Returns
+
+[`Contour`](Contour.md)
+
+Frozen counterclockwise loop in millimetres, without a repeated seam endpoint.
+
+
+## Throws
+
+- GeometryError for invalid data, topology, scale, or exceeded sampling budgets.
+
+## Related APIs
+
+- [Contour](Contour.md)
+- [ContourCurve](ContourCurve.md)
+- [SampleContourOptions](SampleContourOptions.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,61 @@
+# sampleCurve2
+
+Samples a planar curve with the same guarantees and policy as spatial sampling.
+
+**sampleCurve2**(`curve`: [`Curve2`](Curve2.md), `options?`: [`CurveSamplingOptions`](CurveSamplingOptions.md)): [`SampledCurve2`](SampledCurve2.md)
+
+
+
+## Example
+
+```ts
+const turn = sampleCurve2({kind: "arc", center: [0,0], radius: 10, sweepDegrees: 90});
+```
+
+## Parameters
+
+<a id="curve"></a>
+
+**`curve`** · [`Curve2`](Curve2.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`CurveSamplingOptions`](CurveSamplingOptions.md) · Optional
+
+- [`segments`](CurveSamplingOptions.md#segments) · `number` · Optional
+
+  Exact segment count overrides physical criteria; curve parameters are spaced uniformly.
+
+- [`resolution`](CurveSamplingOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Millimetre sampling policy; circularSegments applies only to arcs.
+
+- [`maximumVertices`](CurveSamplingOptions.md#maximumvertices) · `number` · Optional
+
+  Output vertex ceiling of at least two; may only lower limits.maxPathPoints.
+
+- [`limits`](CurveSamplingOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit sampling ceilings; omitted values use package defaults without ambient state.
+
+
+
+## Returns
+
+[`SampledCurve2`](SampledCurve2.md)
+
+## Remarks
+
+Private spatial scratch math is shared, while only final planar vectors are copied and
+frozen. At stationary tangents, outgoing secants are preferred and endpoints use a backward fallback.
+
+
+## Related APIs
+
+- [Curve2](Curve2.md)
+- [CurveSamplingOptions](CurveSamplingOptions.md)
+- [SampledCurve2](SampledCurve2.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,61 @@
+# sampleCurve3
+
+Samples a spatial curve, preserving endpoints and directed unit tangents.
+
+**sampleCurve3**(`curve`: [`Curve3`](Curve3.md), `options?`: [`CurveSamplingOptions`](CurveSamplingOptions.md)): [`SampledCurve3`](SampledCurve3.md)
+
+
+
+## Example
+
+```ts
+const path = sampleCurve3({kind: "cubic", start: [0,0,0], control1: [5,0,0], control2: [5,5,5], end: [10,5,5]});
+```
+
+## Parameters
+
+<a id="curve"></a>
+
+**`curve`** · [`Curve3`](Curve3.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`CurveSamplingOptions`](CurveSamplingOptions.md) · Optional
+
+- [`segments`](CurveSamplingOptions.md#segments) · `number` · Optional
+
+  Exact segment count overrides physical criteria; curve parameters are spaced uniformly.
+
+- [`resolution`](CurveSamplingOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Millimetre sampling policy; circularSegments applies only to arcs.
+
+- [`maximumVertices`](CurveSamplingOptions.md#maximumvertices) · `number` · Optional
+
+  Output vertex ceiling of at least two; may only lower limits.maxPathPoints.
+
+- [`limits`](CurveSamplingOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit sampling ceilings; omitted values use package defaults without ambient state.
+
+
+
+## Returns
+
+[`SampledCurve3`](SampledCurve3.md)
+
+## Remarks
+
+Exact counts use uniform curve parameters, not equal physical distances. Adaptive cubics
+bound the full control hull. Full-circle arcs repeat their endpoint; closed polylines do not.
+
+
+## Related APIs
+
+- [Curve3](Curve3.md)
+- [CurveSamplingOptions](CurveSamplingOptions.md)
+- [SampledCurve3](SampledCurve3.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,58 @@
+# sampleCylindricalGearOutline
+
+Samples a complete external involute gear boundary in the XY plane.
+
+**sampleCylindricalGearOutline**(`spec`: [`CylindricalGearSpec`](CylindricalGearSpec.md), `options?`: [`CylindricalGearOutlineOptions`](CylindricalGearOutlineOptions.md)): [`Contour`](Contour.md)
+
+
+
+The returned loop is counter-clockwise, closed implicitly without a repeated
+seam point, and contains no holes. Its center is the origin and its axis is
++Z. Bore, hub, keyway, twist, and face-width choices remain generator-owned.
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`CylindricalGearSpec`](CylindricalGearSpec.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`CylindricalGearOutlineOptions`](CylindricalGearOutlineOptions.md) · Optional
+
+- [`flankSamples`](CylindricalGearOutlineOptions.md#flanksamples) · `number` · Optional
+
+  Exact samples per involute flank, at least two, within the aggregate profile ceiling.
+
+- [`rootArcSamples`](CylindricalGearOutlineOptions.md#rootarcsamples) · `number` · Optional
+
+  Exact samples along each bottom land, at least one, within selected circular/profile ceilings.
+
+- [`limits`](CylindricalGearOutlineOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit profile and circular allocation ceilings.
+
+- [`resolution`](CylindricalGearOutlineOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Explicit physical sampling policy for adaptive defaults.
+
+- [`tipArcSamples`](CylindricalGearOutlineOptions.md#tiparcsamples) · `number` · Optional
+
+  Exact samples along each tooth tip, at least one, within selected circular/profile ceilings.
+
+
+
+## Returns
+
+[`Contour`](Contour.md)
+
+
+## Related APIs
+
+- [Contour](Contour.md)
+- [CylindricalGearOutlineOptions](CylindricalGearOutlineOptions.md)
+- [CylindricalGearSpec](CylindricalGearSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,41 @@
+# sampleHelix
+
+Creates `segments + 1` points including exact helix endpoints from finite positive dimensions. Integrated weights must remain finite. The maxPathPoints ceiling defaults to 100000; excessive exact counts reject before evaluating axial weights or allocating sample arrays.
+
+`const` **sampleHelix**: (`{
+  turns,
+  radius,
+  height,
+  segments,
+  limits,
+  axialWeight,
+}`: [`SampleHelixOptions`](SampleHelixOptions.md)) => readonly [`Vector3Tuple`](Vector3Tuple.md)[]
+
+
+
+## Parameters
+
+
+
+**`{
+  turns,
+  radius,
+  height,
+  segments,
+  limits,
+  axialWeight,
+}`** · [`SampleHelixOptions`](SampleHelixOptions.md) · Required
+
+
+
+## Returns
+
+readonly [`Vector3Tuple`](Vector3Tuple.md)[]
+
+
+## Related APIs
+
+- [SampleHelixOptions](SampleHelixOptions.md)
+- [Vector3Tuple](Vector3Tuple.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,59 @@
+# sampleInternalCylindricalGearSpaceOutline
+
+Samples the center opening and tooth spaces used to subtract an internal ring gear.
+
+**sampleInternalCylindricalGearSpaceOutline**(`spec`: [`CylindricalGearSpec`](CylindricalGearSpec.md), `options?`: [`CylindricalGearOutlineOptions`](CylindricalGearOutlineOptions.md)): [`Contour`](Contour.md)
+
+
+
+Internal tooth tips lie one addendum below the pitch radius and their roots lie one
+dedendum above it. At the pitch circle, positive backlash widens each sampled space
+tangentially. The returned CCW loop encloses the center and is intended to be reversed
+when used as a region hole.
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`CylindricalGearSpec`](CylindricalGearSpec.md) · Required
+
+
+
+<a id="options"></a>
+
+**`options`** · [`CylindricalGearOutlineOptions`](CylindricalGearOutlineOptions.md) · Optional
+
+- [`flankSamples`](CylindricalGearOutlineOptions.md#flanksamples) · `number` · Optional
+
+  Exact samples per involute flank, at least two, within the aggregate profile ceiling.
+
+- [`rootArcSamples`](CylindricalGearOutlineOptions.md#rootarcsamples) · `number` · Optional
+
+  Exact samples along each bottom land, at least one, within selected circular/profile ceilings.
+
+- [`limits`](CylindricalGearOutlineOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit profile and circular allocation ceilings.
+
+- [`resolution`](CylindricalGearOutlineOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Explicit physical sampling policy for adaptive defaults.
+
+- [`tipArcSamples`](CylindricalGearOutlineOptions.md#tiparcsamples) · `number` · Optional
+
+  Exact samples along each tooth tip, at least one, within selected circular/profile ceilings.
+
+
+
+## Returns
+
+[`Contour`](Contour.md)
+
+
+## Related APIs
+
+- [Contour](Contour.md)
+- [CylindricalGearOutlineOptions](CylindricalGearOutlineOptions.md)
+- [CylindricalGearSpec](CylindricalGearSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,39 @@
+# sampleRackToothPath
+
+Samples the open top boundary of a finite rack in its XY pitch plane.
+
+**sampleRackToothPath**(`spec`: [`RackPitchSpec`](RackPitchSpec.md), `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>): [`Path2`](Path2.md)
+
+
+
+X follows rack travel, Y is tooth height, and the pitch line is `Y = 0`.
+The path begins and ends on the root line, omits duplicate adjacent points,
+and leaves base thickness, mounting features, extrusion, and helical sweep to
+the owning generator.
+
+## Parameters
+
+<a id="spec"></a>
+
+**`spec`** · [`RackPitchSpec`](RackPitchSpec.md) · Required
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+
+
+## Returns
+
+[`Path2`](Path2.md)
+
+
+## Related APIs
+
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [Path2](Path2.md)
+- [RackPitchSpec](RackPitchSpec.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,73 @@
+# sampleSideProfile
+
+Samples 1–31 line/cubic segments into a deeply immutable open [radius,height] polyline. Anchors must progress strictly upward; nonnegative-radius cubic controls must have ordered heights between their endpoints. Cubics use de Casteljau subdivision with a conservative control-hull chord-error bound. Lines also obey the optional physical edge-length ceiling. Neither normalized coordinates nor editor metadata are required. Endpoints are retained once; no axis closure, winding normalization, or manufacturing repair is performed.
+
+**sampleSideProfile**(`curve`: [`SideProfileCurve`](SideProfileCurve.md), `options?`: [`SampleSideProfileOptions`](SampleSideProfileOptions.md)): readonly [`Vector2Tuple`](Vector2Tuple.md)[]
+
+
+
+## Example
+
+```ts
+const side = sampleSideProfile({
+  start: { radius: 0.5, height: 0 },
+  segments: [{ type: "line", end: { radius: 1, height: 1 } }],
+}, { radiusScale: 12, heightScale: 30 });
+```
+
+## Parameters
+
+<a id="curve"></a>
+
+**`curve`** · [`SideProfileCurve`](SideProfileCurve.md) · Required
+
+Open outline in millimetres unless the positive scales convert its coordinates.
+
+
+
+<a id="options"></a>
+
+**`options`** · [`SampleSideProfileOptions`](SampleSideProfileOptions.md) · Optional
+
+Physical resolution and output budget; defaults to 4096 vertices.
+
+- [`radiusScale`](SampleSideProfileOptions.md#radiusscale) · `number` · Optional
+
+  Positive radius scale; use the desired maximum radius for normalized coordinates. Defaults to 1.
+
+- [`heightScale`](SampleSideProfileOptions.md#heightscale) · `number` · Optional
+
+  Positive height scale; use the desired total height for normalized coordinates. Defaults to 1.
+
+- [`resolution`](SampleSideProfileOptions.md#resolution) · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+  Shared physical policy, evaluated after scaling; exact circular counts do not affect curves.
+
+- [`maximumVertices`](SampleSideProfileOptions.md#maximumvertices) · `number` · Optional
+
+  Maximum output vertex count within maxProfilePoints. Defaults to the smaller of 4096 and that ceiling.
+
+- [`limits`](SampleSideProfileOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit profile and circular allocation ceilings.
+
+
+
+## Returns
+
+readonly [`Vector2Tuple`](Vector2Tuple.md)[]
+
+Frozen open polyline in millimetres, ordered from lowest to highest anchor.
+
+
+## Throws
+
+- GeometryError for invalid coordinates, order, scale, or exceeded subdivision budget.
+
+## Related APIs
+
+- [SampleSideProfileOptions](SampleSideProfileOptions.md)
+- [SideProfileCurve](SideProfileCurve.md)
+- [Vector2Tuple](Vector2Tuple.md)
+
+Package: `@metamesh/modeling@0.14.0`.

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

@@ -0,0 +1,53 @@
+# sampleTextContours
+
+Samples a prepared text layout without shaping text again or loading a font.
+
+**sampleTextContours**(`layout`: [`VectorTextLayout`](VectorTextLayout.md), `resolution?`: [`GeometryResolution`](GeometryResolution.md), `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>): readonly [`Contour`](Contour.md)[]
+
+
+
+## Parameters
+
+<a id="layout"></a>
+
+**`layout`** · [`VectorTextLayout`](VectorTextLayout.md) · Required
+
+Immutable millimetre paths and measurements retained from text preparation.
+
+
+
+<a id="resolution"></a>
+
+**`resolution`** · [`GeometryResolution`](GeometryResolution.md) · Optional
+
+Explicit curve sampling policy; omitted uses the pure default policy.
+
+
+
+<a id="limits"></a>
+
+**`limits`** · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+Explicit profile and circular allocation ceilings.
+
+
+
+## Returns
+
+readonly [`Contour`](Contour.md)[]
+
+Frozen contours with original glyph winding and no repeated closing vertex.
+
+
+## Throws
+
+- GeometryError for empty outlines, invalid paths or policies, over 1000 paths or selected sampling ceilings.
+
+## Related APIs
+
+- [Contour](Contour.md)
+- [GeometryResolution](GeometryResolution.md)
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [VectorTextLayout](VectorTextLayout.md)
+
+Package: `@metamesh/modeling@0.14.0`.