@metamesh/modeling 0.17.0 → 0.19.0

package/dist/docs/guides/sweeps-and-lofts.md

@@ -0,0 +1,179 @@
+# Build sweeps, lofts, and heightfields
+
+Sweep a section along a curved path, blend different cross sections with a loft, or sample a heightfield.
+
+Use a sweep when one cross section follows a route, a loft when cross sections change between
+stations, or a heightfield when an XY grid can describe the top surface. Choose the representation
+before increasing sampling detail.
+
+Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop/code-projects), where Studio supplies
+typed controls and prepared services. For a local model, follow the
+[standalone workflow](standalone-model.md) and use its host entry point.
+
+## Rotation-minimizing path sweep
+
+
+
+```ts
+import { rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  // An asymmetric section makes the frame orientation visible in the result.
+  const section = rectangle({
+    size: [8, 3],
+    treatment: { kind: "round", radius: 0.8 },
+  });
+  const path = [
+    [0, 0, 0],
+    [15, 0, 8],
+    [25, 10, 18],
+    [25, 25, 24],
+  ] as const;
+  // The initial normal sets profile +X; transport carries it along the path.
+  // The path is open, so the sweep closes both ends with caps.
+  return [
+    part(
+      "model",
+      section.sweep(path, { orientation: { kind: "transport", initialNormal: [0, 1, 0] } })
+    ),
+  ];
+});
+```
+
+The asymmetric section makes its transported orientation visible as the path turns.
+
+
+
+`section.sweep(path, options)` transports a filled shape along a path:
+
+- `orientation: { kind: "transport", initialNormal: [0, 1, 0] }` chooses the starting profile-X
+  direction. Fixed normals, directed normal guides, and discrete Frenet frames are alternatives;
+  the sweep rejects a selected policy that becomes singular.
+- `twist` adds total rotation by physical path length. Set `twistBy: "stations"` to use the authored
+  station schedule instead.
+- `scale` accepts a positive uniform size, an XY pair, or one XY pair per normalized station.
+- `closed: true` joins an implicitly closed path without repeated endpoints. Orientation, scales,
+  and `seamProfileOffset` must describe a compatible closing seam.
+
+Start with the open path above, inspect the first cap and the turns, then replace the rectangle
+with a [`circle`](../reference/model/circle.md) for a round rod. A sweep follows the supplied path
+stations; it does not infer a smooth curve between them. Sample a curve with the
+[path helpers](../reference/geometry/categories/curves-paths.md) when you need a curved trajectory.
+
+## Matched-section loft
+
+
+
+```ts
+import { loft, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const base = rectangle({
+    size: [24, 16],
+    treatment: { kind: "round", radius: 3 },
+  });
+  // Transform the Section in its XY plane; loft supplies the station heights.
+  // Keeping the original rectangle landmarks preserves corner correspondence.
+  const top = base.scale([0.8, 1.2]).rotate(10).translate([3, 0]);
+  return [
+    part(
+      "model",
+      loft([
+        {
+          profile: base,
+          z: 0,
+        },
+        {
+          profile: top,
+          z: 18,
+        },
+      ])
+    ),
+  ];
+});
+```
+
+The two rounded rectangles retain matching corner identities while their size and pose change.
+
+
+
+This [`loft`](../reference/model/loft.md) example places a rounded rectangle at two heights. Use
+`scale`, `rotate` and `translate` to pose the top profile in XY; `rotate` takes degrees. Each
+station uses `z` for an ordinary horizontal plane. To tilt a station, pass
+`frame: anchorFrame3(anchor3(position, direction, up))` instead; the direction chooses its
+normal and a nonparallel `up` vector chooses its roll.
+
+The primitive retains its corner identities, so `loft` pairs corresponding landmarks without
+extra setup. The same approach works when corners become square or fully rounded. For a hollow
+adapter, loft the outer shape and bore separately, then subtract the bore.
+
+Compatible circle or ellipse stations can also transition to rectangles. Invertible XY transforms
+must retain consistent handedness across the stations.
+
+Custom hole topology or disconnected components can use an explicit
+[`Profile`](../reference/geometry/Profile.md) family with stable component, contour, and span IDs.
+Prepare [`matchProfiles`](../reference/geometry/matchProfiles.md) once and pass its
+[`CorrespondingProfile`](../reference/geometry/CorrespondingProfile.md) stations to the same `loft`
+function. Topology must remain constant across stations. Arbitrary Boolean Sections default to
+`correspondence: "direct"`; choose `"reindex"`, `"fast-distance"`, or `"distance"` to change the
+association strategy, or use explicit profiles for landmarks. Direct association preserves the supplied seams;
+reindex also chooses a cyclic phase, while distance methods optimize ordered connections. See
+[`LoftOptions`](../reference/geometry/LoftOptions.md) for sampling and work limits.
+
+## Sample a heightfield
+
+Build a relief tile from absolute Z heights over a rectangular XY grid.
+[`heightfield`](../reference/model/heightfield.md) returns a Solid for Booleans and placement during
+generation. Pure [`mesh.heightfield`](../reference/mesh/heightfield.md) accepts the same options
+and returns an indexed mesh without an engine. Pass it directly as a mesh part, or wrap it in
+[`mesh.immutable`](../reference/mesh/immutable.md) when returning it from a cached computation.
+
+
+
+```ts
+import { heightfield } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  return [
+    part(
+      "model",
+      heightfield({
+        coordinates: {
+          x: [-20, -18, -14, -8, 0, 8, 14, 18, 20],
+          y: [-12, -10, -6, 0, 6, 10, 12],
+        },
+        triangulation: "min-edge",
+        height: ([x, y]) => 3 + 0.8 * Math.cos(x / 6) * Math.cos(y / 5),
+      })
+    ),
+  ];
+});
+```
+
+
+
+The uneven axes place more samples near the border. Coordinates are absolute millimetres, strictly
+increasing, and must remain distinct in Float32 storage. For a uniform grid, replace `coordinates`
+with `size: [40, 24]` and `segments: [40, 24]`; this centers the footprint unless `origin` supplies
+its lower-left corner. Choose one sampling form per call.
+
+`baseZ` defaults to zero. Every height is an absolute Z coordinate strictly above that base;
+the builder preserves the sampled heights without rescaling them. It closes the top with shared
+boundary walls and a flat underside.
+
+| `triangulation`  | Selection per top cell                                                       |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `"fixed"`        | The default lower-left to upper-right diagonal                               |
+| `"min-edge"`     | The shorter 3D diagonal, using the existing corner heights                   |
+| `"center-error"` | The diagonal whose interpolated center is closest to one extra height sample |
+
+All choices keep two triangles per cell and the same vertices. Center matching evaluates one
+additional physical midpoint per cell. Both selection policies use the fixed diagonal for ties.
+Choose sample spacing for the surface detail you need: these policies do not adapt the grid or
+guarantee accuracy throughout each cell. Explicit axes let your model refine selected regions
+while keeping allocation bounded.
+[`mesh.preflightHeightfield`](../reference/mesh/preflightHeightfield.md) reports output counts and
+checks limits without evaluating heights.

package/dist/docs/guides/transforms-and-placement.md

@@ -0,0 +1,313 @@
+# Place shapes and coordinate parts
+
+Position shapes, align mating parts, and repeat features with transforms, anchors, patterns, and bounds.
+
+Build a placement once, then reuse it for the shape, its measurements, and any related parts. Keep
+local construction separate from finished part placement so repeated parts can share geometry.
+
+Run the examples in a [Studio code Project](https://metamesh.studio/docs/develop/code-projects), where Studio supplies
+typed controls and prepared services. For a local model, follow the
+[standalone workflow](standalone-model.md) and use its host entry point.
+
+## Reuse a transform across shapes and coordinates
+
+Use [`transform2`](../reference/geometry/transform2.md) and
+[`transform3`](../reference/geometry/transform3.md) chains for reusable placements. They are immutable
+and pure, so you don't need an engine to build them. Calls apply in written order. A rotation
+followed by a translation rotates around the origin, then moves the result:
+
+
+
+```ts
+import { transform3, vector3 } from "@metamesh/modeling";
+
+// Calls apply in written order: rotate, then translate.
+const placement = transform3().rotate([0, 0, 90]).translate([20, 0, 5]);
+export const placedPoint = placement.applyPoint([10, 0, 0]); // approximately [20, 10, 5]
+export const placedDirection = placement.applyDirection([10, 0, 0]); // approximately [0, 10, 0]
+```
+
+
+
+Pass a transform directly to `solid.transform(placement)`, `section.transform(placement)` and
+matching path helpers. Finished parts accept rigid transforms through `part(id, { geometry, transform })`;
+pattern and attachment matrices work directly. Part placement rejects scale, shear and reflection.
+`toData()` supplies a canonical matrix when another system needs it.
+Construct the placement once and reuse it across point collections.
+
+`current.andThen(next)` applies `current` first and `next` second, accepting another chain or a
+same-dimensional matrix. `inverse()` returns the reverse placement. Each operation returns a new
+chain, so you can derive different placements from a shared starting point.
+
+Use `rotate(degrees, { pivot })` or `scale(factors, { pivot })` to work around a world-space pivot after
+the preceding operations. In 3D, `rotate` takes XYZ Euler degrees, applied about global X, Y, then
+Z; `rotateAxis(axis, degrees, { pivot })` normalizes its nonzero axis. Omitted pivots use the
+coordinate origin. Uniform and per-axis scales must be finite and nonzero; negative factors reflect.
+Nonfinite inputs, invalid axes, and singular matrices throw `GeometryError`.
+
+`applyPoint` includes translation. `applyDirection` excludes translation and preserves scale;
+its result is not normalized. `applyNormal` applies the inverse transpose and returns a unit normal,
+including under nonuniform scaling; it rejects zero normals. All three return fluent vectors.
+
+`Transform2` works directly with Sections and pure XY helpers; its `Transform2Data` is the same
+canonical 3x3 representation throughout. Use `to3D()` when that XY placement
+also needs to position a Solid or 3D path. The reverse `to2D()` conversion rejects transforms
+that move the XY plane or collapse its dimensions; it doesn't project 3D points.
+See the [2D placement recipe](transforms-and-placement.md#reuse-a-2d-placement).
+
+### Transform composition order
+
+For low-level matrix interoperability, the factories accept existing canonical matrices. Use
+`transform3(frameTransform3(frame))` for an orthonormal frame. The raw constructors and
+`composeTransform3(after, before)` remain available; composition applies `before` first:
+
+
+
+```ts
+import { transform3 } from "@metamesh/modeling";
+import { applyTransformPoint3, composeTransform3 } from "@metamesh/modeling/geometry";
+
+const current = transform3().rotate([0, 0, 90]);
+const next = transform3().translate([20, 0, 5]);
+export const chainedPoint = current.andThen(next).applyPoint([10, 0, 0]);
+export const composedPoint = applyTransformPoint3(
+  composeTransform3(next.toData(), current.toData()),
+  [10, 0, 0]
+); // Both results are approximately [20, 10, 5].
+export const reversedPoint = next.andThen(current).applyPoint([10, 0, 0]);
+// approximately [0, 30, 5]
+```
+
+
+
+## Calculate with vectors
+
+Use [`vector2`](../reference/geometry/vector2.md) and [`vector3`](../reference/geometry/vector3.md)
+for readable arithmetic chains. Operands accept tuples or vectors; `dot`, `length` and `distance`
+return numbers. `cross` returns a signed scalar in 2D and a right-handed vector in 3D.
+
+
+
+```ts
+export const direction = vector3([1, 2, 3]).add([4, 0, 0]).normalize().scale(10);
+export const alignment = direction.dot([0, 0, 1]); // number
+```
+
+
+
+Values snapshot their input and operations return new values. `toData()` returns the value's
+frozen coordinate tuple without allocating another copy. Normalization rejects zero-length vectors;
+nonfinite coordinates, scalar parameters and overflowing results throw `GeometryError`.
+
+For rotations and nonuniform scaling, use a reusable transform's `applyDirection`. Use
+`applyNormal` for surface normals:
+
+
+
+```ts
+const stretched = transform3().scale([2, 1, 1]);
+export const normal = stretched.applyNormal([1, 1, 0]);
+export const tangent = stretched.applyDirection([1, -1, 0]);
+export const perpendicular = normal.dot(tangent); // approximately 0
+```
+
+
+
+Fluent math and shape transforms accept vector values directly; compose a transform for part placement. Serialized
+geometry and low-level kernels use tuples. Keep model-specific equations beside the model.
+
+## Measure and compare bounds
+
+Use [`bounds2`](../reference/geometry/bounds2.md) and
+[`bounds3`](../reference/geometry/bounds3.md) for immutable axis-aligned bounds. `size()` and
+`center()` return fluent vectors. `containsBounds(other)` tests positioned containment in the
+same coordinate frame, including touching boundaries. It doesn't establish a manufacturing fit.
+
+
+
+```ts
+import { bounds3 } from "@metamesh/modeling";
+import { fitBounds, layoutRow, rectangleContour } from "@metamesh/modeling/geometry";
+import * as mesh from "@metamesh/modeling/geometry/mesh";
+
+export const envelope = bounds3({ min: [-10, -5, 0], max: [10, 5, 8] });
+export const size = envelope.size(); // Vector3: [20, 10, 8] mm
+export const center = envelope.center(); // Vector3: [0, 0, 4] mm
+
+const triangleMesh = mesh.extrude(rectangleContour({ size: [12, 6] }), { height: 4 });
+// Mesh measurements are plain data. Wrap once for fluent queries.
+export const measured = bounds3(mesh.bounds(triangleMesh));
+export const fits = envelope.containsBounds(measured); // true
+export const data = measured.toData(); // Frozen { min, max } record for interchange.
+
+// Collection and placement algorithms accept bounds values directly.
+export const fitting = fitBounds(measured, envelope, { maxScale: 1 });
+export const positions = layoutRow([measured, envelope], { gap: 2 });
+```
+
+
+
+Factories snapshot finite, ordered coordinates with finite extents; zero extents are valid.
+Alternatively construct from nonnegative dimensions with `bounds2({ size: [30, 18] })` or
+`bounds3({ size: [30, 18, 8], center: false })`. Size construction centers on the origin by default;
+size and min/max construction are mutually exclusive.
+`min` and `max` are frozen tuples, and `toData()` returns the value's stable frozen plain record.
+Path `bounds()` queries return matching fluent bounds, or `undefined` for an empty path.
+Mesh and region measurements, inspection results, and engine snapshots retain plain
+`Bounds2Data` or `Bounds3Data`; wrap a measurement when you need fluent queries.
+
+Use [`fitBounds`](../reference/geometry/fitBounds.md) to calculate a placement and
+[`layoutRow`](../reference/geometry/layoutRow.md) to arrange a collection. These standalone
+algorithms accept values or plain records. Supply bounds after any intended rotation; an
+axis-aligned box alone doesn't describe the underlying shape.
+
+## Primitive booleans and repeated placement
+
+
+
+```ts
+import { box, cylinder, radialPattern, union } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const hub = cylinder({ height: 12, radius: 14 });
+  const arm = box({ size: [30, 6, 6] });
+  // Translate first, then rotate the whole arm about the world origin.
+  // Its inner end overlaps the hub so union creates one connected part.
+  const arms = radialPattern(arm.translate([18, 0, 0]).rotate([0, 0, 30]), {
+    count: 6,
+    axis: [0, 0, 1],
+    angle: 60,
+  });
+  // Both shapes are Z-centered; extra cutter height clears both hub faces.
+  const bore = cylinder({ height: 16, radius: 4 });
+  // Combine the repeated features once, then cut the common bore.
+  return [part("model", union([hub, ...arms]).subtract(bore))];
+});
+```
+
+Position and rotate one arm, repeat it about +Z, union the overlaps, then cut a common bore.
+
+
+
+Transforms apply in written order: `arm.translate(...).rotate(...)` moves the arm first, then rotates
+its position about the origin. Reversing those calls rotates the arm locally before moving it.
+Keep a deliberate overlap between each arm and the hub so the result is one connected solid.
+
+Exact signatures: [`box`](../reference/model/box.md),
+[`cylinder`](../reference/model/cylinder.md), and
+[`radialPattern`](../reference/model/radialPattern.md).
+
+## Reuse a 2D placement
+
+Build one [`transform2`](../reference/geometry/transform2.md) chain when the same placement applies
+to a Section and its plain point data. This placement rotates around `[2, 1]`, then translates:
+
+
+
+```ts
+import { path2, pathPattern, polygon, rectangle, transform2, union } from "@metamesh/modeling";
+
+const planarPlacement = transform2()
+  .rotate(90, { pivot: [2, 1] })
+  .translate([10, 0]);
+const outline = [
+  [0, 0],
+  [4, 0],
+  [0, 2],
+] as const;
+
+// Shape construction and composition are pure; the host evaluates the finished body.
+export const placedBody = polygon({ outer: outline, holes: [] })
+  .transform(planarPlacement)
+  .extrude({ height: 8 });
+
+// Paths accept the same placement. Matrices and tuples remain available for interchange.
+export const sectionMatrix = planarPlacement.toData();
+export const placedContour = path2(outline, { closed: true }).transform(planarPlacement);
+```
+
+
+
+Pass the placement directly to `section.transform(planarPlacement)` or `path.transform(planarPlacement)`.
+Fill the transformed closed path with `polygon(placedContour)` when you need material.
+[`transformRegionData`](../reference/geometry/transformRegionData.md) serves serialized filled data.
+
+A negative scale factor reflects the placement. Paths retain traversal order, including closed
+paths; filled Sections and serialized regions restore outer and hole winding. `andThen(next)`
+composes another placement in execution order;
+reuse the placement instead of rebuilding the chain for every point. Use `toData()` when another
+system needs the matrix.
+
+Section path patterns consume `Path2` values directly. Tangent orientation aligns the Section's
+local +X direction with the path while preserving its XY plane:
+
+
+
+```ts
+const guide = path2([
+  [0, 0],
+  [12, 0],
+  [12, 12],
+]);
+const tabs = pathPattern(rectangle({ size: [4, 2] }), guide, {
+  count: 5,
+  orientation: "tangent",
+});
+export const patternedTabs = union(tabs).extrude({ height: 3 });
+```
+
+
+
+Linear Section patterns use XY directions. Radial Section patterns rotate about an optional XY
+`pivot` using the implicit +Z axis; spatial Solid patterns retain their explicit rotation axis.
+
+## Named anchors and custom frames
+
+
+
+```ts
+import { box, cylinder } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const base = box({ size: [40, 24, 6], center: false });
+  // Named anchors follow dimensions: no duplicated half-height calculation.
+  // Mating bottom to top opposes the two outward normals automatically.
+  const pin = cylinder({ diameter: 8, height: 12 }).attach("bottom", base.anchor("top"), {
+    gap: 0.2,
+  });
+  // Keep the gap and the two physical pieces instead of unioning the assembly.
+  return [part("base", { geometry: base }), part("pin", { geometry: pin })];
+});
+```
+
+The pin's bottom mates to the base's top with a 0.2 mm gap. They remain two named parts.
+
+
+
+Ordinary primitives know their named anchors, so `base.anchor("top")` follows the box's dimensions
+and placement. `pin.attach("bottom", base.anchor("top"))` mates opposed directions. Transforms and
+patterns carry those frames with the shape, with outward normals preserved under nonuniform scale
+and reflection. The axis names are `left/right` (−X/+X), `back/front` (−Y/+Y) and `bottom/top` (−Z/+Z).
+
+Use `shape.withAnchors({ mount: anchor3(position, direction, up) })` to define a custom datum
+without changing the original shape. Existing names remain unless replaced; definitions are copied
+and immutable.
+Boolean and other constructed shapes need explicit definitions because their surfaces may change.
+Anchor names use lowercase kebab-case, with at most 64 characters and 128 definitions per shape.
+Look up anchors during active synchronous generation; the lookup evaluates the required recipe.
+Returned frames are plain data.
+
+Primitive anchors describe nominal construction dimensions. Finishing and curve sampling do not
+move them. Tube and torus axial datums may lie over an opening; a cone has no cap anchor at its apex.
+Regular polygons and stars expose only `center`. Custom `Anchor3` frames, including pure
+`boxAnchor3` and `cylinderAnchor3` helpers, work wherever a source or target frame is required.
+
+Primitive `attachment` uses the same source/target anchor, `alignment`, `gap`, and `spin`
+options as `attach`, including a named `source`. It applies after local construction; Section
+attachment must preserve the XY plane.
+
+The `gap` here separates the two pieces along the target normal; it is a placement distance, not
+a radial fit clearance. Keep separate named parts for an assembly. For one fused part, remove the
+gap, add a small intended overlap, and [`union`](../reference/model/union.md) the solids.