@metamesh/modeling 0.18.0 → 0.20.0

package/dist/docs/guides/profiles-and-extrusion.md

@@ -0,0 +1,400 @@
+# Build solids from profiles and primitives
+
+Choose primitives, extrude filled outlines, revolve radial profiles, and finish their rims.
+
+Start with a primitive when it already describes the material.
+
+
+
+**Solve the cross section first**
+
+For a plate or gasket, make the filled outline and add depth. For a cup or knob, describe its
+  radial section and revolve it. Keep the simplest representation until you need the next dimension.
+
+
+
+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.
+
+## Choose a primitive
+
+Start with the factory that most closely describes the shape. The first row below contains ready
+Solids; the second contains filled Sections extruded to `5 mm` thickness. Each result remains a
+separate named part so you can inspect it in the interactive preview.
+
+
+
+```ts
+import { ellipse, regularPolygon, sphere, star, torus, tube } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  // Solid primitives are ready for placement; filled Sections need depth first.
+  // Place finished parts on two rows while keeping local geometry reusable.
+  return [
+    part("sphere", {
+      geometry: sphere({ diameter: 14 }),
+      transform: transform3().translate([0, 0, 7]),
+      color: "#60a5fa",
+    }),
+    part("torus", {
+      geometry: torus({ majorRadius: 7, minorRadius: 2 }),
+      transform: transform3().translate([24, 0, 2]),
+      color: "#34d399",
+    }),
+    part("tube", {
+      geometry: tube({ outerRadius: 7, innerRadius: 4, height: 10, center: false }),
+      transform: transform3().translate([48, 0, 0]),
+      color: "#f59e0b",
+    }),
+    part("ellipse", {
+      geometry: ellipse({ size: [18, 12] }).extrude({ height: 5 }),
+      transform: transform3().translate([0, 24, 0]),
+      color: "#c084fc",
+    }),
+    part("star", {
+      geometry: star({ outerRadius: 9, innerRadius: 4.5, points: 5 }).extrude({ height: 5 }),
+      transform: transform3().translate([24, 24, 0]),
+      color: "#fb7185",
+    }),
+    part("hexagon", {
+      geometry: regularPolygon({ radius: 7, sides: 6, sizing: "face" }).extrude({ height: 5 }),
+      transform: transform3().translate([48, 24, 0]),
+      color: "#22d3ee",
+    }),
+  ];
+});
+```
+
+Sphere, torus, and tube are solid factories. Ellipse, star, and regular polygon create Sections that can be extruded.
+
+
+
+Use a [`tube`](../reference/model/tube.md) when the bore is concentric; it avoids a separate cutter.
+A [`torus`](../reference/model/torus.md) uses the distance to the circular profile's center as its
+major radius. [`regularPolygon`](../reference/model/regularPolygon.md) has an exact side count;
+`sizing: "face"` makes the specified radius reach the faces instead of the vertices. Keep physical
+curve tolerance for ordinary round shapes and use exact segment counts for deliberate faceting.
+
+`circle` and `cylinder` support the same vertex or face sizing convention.
+`tube` accepts a complete pair of inner/outer radii or diameters, with independent `innerSizing`
+and `outerSizing`. For example, `tube({ innerDiameter: 8, outerDiameter: 12, height: 10,
+innerSizing: "face" })` preserves an 8 mm clear bore between the sampled faces. Both defaults are
+`"vertex"`; compensation that removes the wall rejects. Sampling and sizing do not establish a
+manufacturing fit allowance.
+
+## Section, hole, offset, and extrusion
+
+
+
+```ts
+import { circle, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const plate = rectangle({ size: [80, 45] });
+  const hole = circle({ radius: 4 });
+  // Positive offset expands material: the outer edge grows and the hole shrinks.
+  const rimmedPlate = plate.subtract(hole).offset(1.2);
+  // Keep the plate centered about Z = 0 for later symmetric placement.
+  return part("model", rimmedPlate.extrude({ height: 5, center: true }));
+});
+```
+
+Subtract the opening in 2D, offset the filled material, then extrude it into one plate.
+
+
+
+`rectangle` and `circle` take object options and return filled Sections. The `union`, `subtract`, and
+`intersect` methods accept one shape or an array and also support Solids; every operand in a call
+must have the same dimension. Use collection `union(shapes)` or `intersect(shapes)` to combine peers.
+`section.offset(distance)` offsets the filled material. `section.extrude({ height })` preserves
+holes and places the bottom at zero unless `center: true` is requested.
+
+`twist` rotates the top around +Z in degrees. `scale` sets its final scale factor: `0.5` finishes at half
+size, while `[0.5, 1]` halves profile-local X and preserves Y. Scale factors interpolate from one
+with height and apply before twist. Uniform `scale: 0` closes a single simple outline at an apex; holes
+and disconnected islands cannot share that apex. Negative scales and a pair with only one zero
+component reject.
+
+Use physical `resolution` for ordinary quality control. Explicit `slices: 20` selects 20 longitudinal
+intervals and 21 layers before end treatments. Chamfered ends can follow a twist; enabled end
+treatments require unit `scale` and insert additional rings where needed.
+
+Positive offset grows material on every boundary: this example grows the outside by `1.2 mm` and
+reduces the hole radius from `4 mm` to `2.8 mm`. If the final bore must remain `8 mm` in diameter,
+offset the outside first and subtract the hole afterward. See
+[`Section.offset`](../reference/model/Section.md#offset) and [`Section.extrude`](../reference/model/Section.md#extrude).
+
+## Revolve a radial profile
+
+Use revolution when one side outline can describe the entire part around an axis. In the Section
+below, X is radius and Y is final Z height; radii must stay nonnegative. The closed loop includes
+the cup's floor, outside, rim, and inside, so you can describe the wall and opening together.
+
+
+
+```ts
+import { polygon } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  // Here Section X means radius and Section Y becomes the final Z height.
+  // Walk the filled wall counterclockwise, omitting a repeated closing point.
+  const wall = polygon([
+    [0, 0],
+    [16, 0],
+    [16, 4],
+    [12, 4],
+    [10, 28],
+    [7, 28],
+    [9, 4],
+    [0, 4],
+  ]);
+  // A full revolution creates the floor, tapered wall, and open top together.
+  return part("model", wall.revolve());
+});
+```
+
+One radial wall profile revolved around +Z creates the floor and tapered cup wall.
+
+
+
+[`polygon`](../reference/model/polygon.md) fills the ordered contour.
+[`Section.revolve`](../reference/model/Section.md#revolve) defaults to a complete `360°` turn. Set
+`degrees: 270` for a capped partial turn that exposes the cross section. Keep the closed
+profile free of self-intersections and never repeat its first point at the end.
+
+For an open side outline, [`sampleSideProfile`](../reference/geometry/sampleSideProfile.md)
+returns physical `[radius, height]` points. [`closeToAxis`](../reference/geometry/closeToAxis.md)
+adds the horizontal bottom/top edges needed for a solid body. Fill the result with `polygon`,
+then revolve it. Hollow walls and mounting bores need their own closed material contour.
+
+## Treated boxes, frustums, and mirrored arrays
+
+
+
+```ts
+import { box, cylinder, gridPattern } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+export default generate(({ part }) => {
+  const housing = box({
+    size: [46, 30, 12],
+    treatment: { kind: "round", radius: 3 },
+  });
+  const taperedBore = cylinder({
+    // The centered cutter extends beyond both faces of the 12 mm housing.
+    height: 16,
+    // Tuples run from the bottom diameter to the top diameter along +Z.
+    diameter: [8, 6],
+    sizing: "face",
+    ends: { top: { kind: "chamfer", distance: 0.8 } },
+  });
+  // Pattern the already-positioned tool; X varies fastest through the array.
+  const perforations = gridPattern(taperedBore.translate([-13, -6, 0]), {
+    count: [3, 2],
+    spacing: [13, 12],
+  });
+  // Mirror the completed housing across the plane with normal +X.
+  return part("model", housing.subtract(perforations).mirror([1, 0, 0]));
+});
+```
+
+Six non-overlapping cutters share the same taper and rim treatment; the completed housing is mirrored.
+
+
+
+Paired cylinder radii or diameters are always `[bottom, top]` in +Z order. A zero endpoint makes a cone;
+chamfers under `ends.bottom` and `ends.top` may treat either nonzero end and follow the tapered side.
+Boxes and rectangles share `round`, `chamfer`, `smooth`, and explicit `profile` treatments. Boxes
+can select disjoint named edges or groups; rectangles can select each corner. `gridPattern` places
+the cutters on an XY grid, with X varying fastest.
+Zero rounding radius or zero chamfer/smooth setbacks disable that treatment, so an adjustable
+feature can remain in the options object when switched off.
+
+The bores use `diameter: [8, 6]` and `13 × 12 mm` spacing to leave material between them. Check
+the widest cutter diameter and the outer wall when changing either value. In this example the
+tool's top chamfer lies above the housing; it shapes the cutter end, not the finished hole's rim.
+Use `holeCutter.openings` when the finished mouth needs a roundover, chamfer, or screw seat.
+
+## Shape openings and local edges
+
+
+
+```ts
+import { box, cornerCutter, edgeCutter, holeCutter, tube } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+const treatment = { kind: "round", radius: 2 } as const;
+const edge = (length: number) => edgeCutter({ length, treatment });
+
+// Three matching edges and their corner share the positive XYZ material octant.
+const plate = box({ size: [40, 24, 8], center: false }).subtract([
+  edge(8),
+  edge(40).rotate([0, -90, 0]).translate([40, 0, 0]),
+  edge(24).rotate([90, 0, 0]).translate([0, 24, 0]),
+  cornerCutter({ treatment }),
+  holeCutter({
+    diameter: 10,
+    height: 8,
+    sizing: "face",
+    openings: {
+      top: { kind: "round", radius: 1 },
+      bottom: { kind: "smooth", distance: 0.5 },
+    },
+    // Numerical overlap is independent of the nominal bore and mouth dimensions.
+    overrun: { top: 0.05, bottom: 0.05 },
+  }).translate([24, 12, 0]),
+]);
+
+const sleeve = tube({
+  outerDiameter: 20,
+  innerDiameter: 12,
+  height: 8,
+  center: false,
+  ends: {
+    top: { kind: "round", radius: 0.75 },
+    bottom: { kind: "chamfer", distance: 0.4 },
+  },
+});
+
+export default generate(({ part }) => [
+  part("plate", { geometry: plate, transform: transform3().translate([-20, -12, 0]) }),
+  part("sleeve", { geometry: sleeve, transform: transform3().translate([32, 0, 0]) }),
+]);
+```
+
+Opening treatments widen the mouth while preserving the bore. Explicit edge and corner cutters remove local material; tube ends finish both rims.
+
+
+
+`holeCutter` accepts a circular `diameter` or an existing Section `profile`. Its nominal interval
+is Z=0 to `height`. Set `openings.top` and `openings.bottom` independently with the shared
+`round`, `chamfer`, `smooth`, or sampled `profile` treatments. Circular openings also accept
+`counterbore` and `countersink`, using explicit seat dimensions. Each end accepts one treatment.
+For blind pockets, leave the floor end plain and extend only the open end.
+
+The first treatment setback widens the mouth; the second reaches into the hole along its axis.
+Both opening depths must leave a positive untreated throat. Circular roundovers use a radius
+in the radial/axial section. Treated Section pockets require one strictly convex contour without
+holes; plain and zero-treated pockets accept arbitrary Section topology.
+
+`overrun` extends the terminal cross section beyond the nominal end without changing the
+opening dimensions. Both extensions default to zero. Set overrun independently from the
+clearance already included in the bore or pocket dimensions.
+
+`edgeCutter` places the sharp reference edge at XY=0 and runs along +Z from zero to `length`.
+The material wedge runs counterclockwise from +X through `angle` degrees (default 90).
+Use existing transforms, anchors, and patterns to position the cutter, then subtract it.
+`cornerCutter` complements matching cuts where three perpendicular material faces meet in the
+positive XYZ octant. It accepts a spherical `round` or equal-setback `chamfer`; arbitrary edge
+profiles do not define a unique three-face corner surface. Numerical `excess` extends outside
+the reference faces and defaults to 0.05 mm, independently of the finished treatment.
+Perpendicular round edges and spherical corners use a common native sampling lattice. Matching
+treatments meet on the same vertices; full-circle facet requests round up to a multiple of four.
+
+These cutters use explicit construction datums. They do not select edges in an existing mesh or
+infer the mating surface. Keep each complete treatment inside the intended local material.
+
+## Finish a profile with a hole
+
+
+
+```ts
+import { circle, rectangle } from "@metamesh/modeling";
+import { generate } from "@metamesh/project";
+
+const profile = rectangle({ size: [36, 24] })
+  .subtract(rectangle({ size: [8, 8] }).translate([18, 0]))
+  .subtract(circle({ diameter: 10 }));
+
+const plate = profile.extrude({
+  height: 6,
+  ends: {
+    top: { kind: "round", radius: 1.5 },
+    bottom: { kind: "chamfer", distance: 0.5 },
+  },
+});
+
+export default generate(({ part }) => part("finished-plate", plate));
+```
+
+One treatment finishes every material boundary at each end, including the notch and the hole.
+
+
+
+Form the complete filled profile first, then apply `ends.top` and `ends.bottom` during extrusion.
+The same treatment follows the outer outline, concave notch, and hole. Removing material at the
+top contracts the outside and opens the hole mouth; the plan-view corners remain mitered.
+Choose amounts that leave every boundary distinct and a positive straight wall interval.
+
+Finishing options share `round` (radius), `chamfer` (setbacks), `smooth` (cubic setbacks), and exact
+`profile` points:
+
+- Boxes select disjoint named edges or groups; rectangles select individual corners.
+- Cylinder/frustum, tube, and straight extrusion rims use independent `ends.bottom` and `ends.top`.
+  Tube end treatments finish both the outer rim and bore mouth and must retain a positive wall.
+- Straight extrusions admit concave outlines, holes, and disconnected material components when
+  every source boundary survives the treatment without contact, collapse, or topology changes.
+  One treatment applies to every material boundary at that end; inward material trimming expands
+  hole mouths. Enabled treatments require unit `scale`. Explicit `slices` controls the base
+  longitudinal grid; treatment and refinement rings may increase the final layer count.
+- Zero radius, zero chamfer/smooth distance, or an all-zero distance pair leaves a feature untreated.
+  Other setback pairs require two positive values; negative and nonfinite amounts reject.
+- Disabled extrusion end treatments retain ordinary support, including holes and twist.
+
+For a local connection between completed solids, use [solid joins](solid-joins.md).
+
+## Chamfer a twisted extrusion
+
+
+
+```ts
+import { rectangle } from "@metamesh/modeling";
+import { transform3 } from "@metamesh/modeling/geometry";
+import { generate } from "@metamesh/project";
+
+const core = rectangle({ size: 20 });
+const sleeve = rectangle({ size: 27 }).subtract(rectangle({ size: 20.7 }));
+const chamfer = { kind: "chamfer", distance: 0.7 } as const;
+const options = {
+  height: 70,
+  twist: 180,
+  slices: 20,
+  ends: { bottom: chamfer, top: chamfer },
+  resolution: { maxChordError: 0.025 },
+};
+
+export default generate(({ part }) => [
+  part("core", { geometry: core.extrude(options), color: "#E9B45D" }),
+  part("sleeve", {
+    geometry: sleeve.extrude(options),
+    color: "#2D8490",
+    transform: transform3().translate([40, 0, 0]),
+  }),
+]);
+```
+
+Chamfer the finished twisted rims, including the sleeve bore, through the same extrusion options.
+
+
+
+Build the sleeve's complete filled section before extrusion. The same `ends` options finish its
+outside and bore, preserving matching corners without separate cutters or independently offset lofts.
+
+For a chamfer, `distance: 0.7` sets equal setbacks on the cap and the finished wall. A pair sets
+`[cap, wall]`. The wall distance is measured from the rim in a normal section through the helical
+wall; it is a straight-line distance, rather than axial depth or surface arc length. Equal distances
+give 45° on perpendicular walls; a twisted wall can give a different angle around the rim.
+
+Twisted ends support `chamfer`. Rounded, smooth, and custom-profile ends require zero twist.
+Use `maxChordError` and optional `maxSegmentLength` for physical sampling. `slices` selects the
+base longitudinal intervals; additional treatment rings and physical refinement resolve the rim.
+Without explicit `slices`, extrusion resolution chooses the base schedule. This example requests
+20 intervals and lets the chamfer add the rings it needs.
+Keep enough material between the two ends and between neighboring boundaries. Large twists over
+a short chamfer collar can fold normal sections and reject; reduce the twist or the setback.