@metamesh/modeling 0.18.0 → 0.19.0

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.