@metamesh/modeling 0.11.0 → 0.13.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 [`Vector3`](Vector3.md)[], `radius`: `number`, `segmentsPerCorner`: `number`, `limits?`: `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\>) => readonly [`Vector3`](Vector3.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 [`Vector3`](Vector3.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 [`Vector3`](Vector3.md)[]
+
+
+## Related APIs
+
+- [GeometrySamplingLimits](GeometrySamplingLimits.md)
+- [Vector3](Vector3.md)
+
+Package: `@metamesh/modeling@0.13.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.13.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.13.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.13.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.13.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 [`Vector3`](Vector3.md)[]
+
+
+
+## Parameters
+
+
+
+**`{
+  turns,
+  radius,
+  height,
+  segments,
+  limits,
+  axialWeight,
+}`** · [`SampleHelixOptions`](SampleHelixOptions.md) · Required
+
+
+
+## Returns
+
+readonly [`Vector3`](Vector3.md)[]
+
+
+## Related APIs
+
+- [SampleHelixOptions](SampleHelixOptions.md)
+- [Vector3](Vector3.md)
+
+Package: `@metamesh/modeling@0.13.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.13.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.13.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 [`Vector2`](Vector2.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 [`Vector2`](Vector2.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)
+- [Vector2](Vector2.md)
+
+Package: `@metamesh/modeling@0.13.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.13.0`.

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

@@ -0,0 +1,63 @@
+# sampleThreadHelices
+
+Samples evenly phased thread helices with finite `lead = pitch * starts`. All starts together respect maxPathPoints (default 100000); excessive counts fail before allocation.
+
+**sampleThreadHelices**(`options`: [`ThreadHelixOptions`](ThreadHelixOptions.md)): [`SampledThreadHelices`](SampledThreadHelices.md)
+
+
+
+## Parameters
+
+<a id="options"></a>
+
+**`options`** · [`ThreadHelixOptions`](ThreadHelixOptions.md) · Required
+
+- [`length`](ThreadHelixOptions.md#length) · `number` · Required
+
+  Total sampled axial length in millimetres.
+
+- [`pitch`](ThreadHelixOptions.md#pitch) · `number` · Required
+
+  Adjacent axial thread spacing in millimetres.
+
+- [`radius`](ThreadHelixOptions.md#radius) · `number` · Required
+
+  Radial distance from the +Z axis in millimetres.
+
+- [`handedness`](ThreadHelixOptions.md#handedness) · [`ThreadHandedness`](ThreadHandedness.md) · Optional
+
+  Helix direction. Default: `right`.
+
+- [`limits`](ThreadHelixOptions.md#limits) · `Partial`\<[`GeometrySamplingLimits`](GeometrySamplingLimits.md)\> · Optional
+
+  Explicit aggregate path allocation ceilings across all starts.
+
+- [`phaseDegrees`](ThreadHelixOptions.md#phasedegrees) · `number` · Optional
+
+  Angular offset of the first start in degrees. Default: `0`.
+
+- [`segmentsPerTurn`](ThreadHelixOptions.md#segmentsperturn) · `number` · Optional
+
+  Angular sampling density for each revolution. Default: `32`.
+
+- [`starts`](ThreadHelixOptions.md#starts) · `number` · Optional
+
+  Number of evenly phased helices. Default: `1`.
+
+- [`tolerance`](ThreadHelixOptions.md#tolerance) · [`GeometryToleranceOptions`](GeometryToleranceOptions.md) · Optional
+
+  Optional numerical tolerance overrides.
+
+
+
+## Returns
+
+[`SampledThreadHelices`](SampledThreadHelices.md)
+
+
+## Related APIs
+
+- [SampledThreadHelices](SampledThreadHelices.md)
+- [ThreadHelixOptions](ThreadHelixOptions.md)
+
+Package: `@metamesh/modeling@0.13.0`.

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

@@ -0,0 +1,38 @@
+# scale3
+
+Multiplies a vector by a dimensionless scalar.
+
+`const` **scale3**: (`vector`: [`Vector3`](Vector3.md), `scale`: `number`) => [`Vector3`](Vector3.md)
+
+
+
+## Example
+
+```ts
+scale3([1, 2, 3], 2); // [2, 4, 6]
+```
+
+## Parameters
+
+<a id="vector"></a>
+
+**`vector`** · [`Vector3`](Vector3.md) · Required
+
+
+
+<a id="scale"></a>
+
+**`scale`** · `number` · Required
+
+
+
+## Returns
+
+[`Vector3`](Vector3.md)
+
+
+## Related APIs
+
+- [Vector3](Vector3.md)
+
+Package: `@metamesh/modeling@0.13.0`.