@metamesh/modeling 0.18.0 → 0.19.0

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

@@ -0,0 +1,252 @@
+# 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. For a plate, gasket, cup, or knob,
+solve the filled cross section first, then add depth or revolve it around an axis.
+
+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, transform3, tube } from "@metamesh/modeling";
+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.
+
+Ordinary extrusion also accepts `twist` and `scaleTop`. Keep those operations separate from
+enabled end treatments, which require a straight extrusion.
+
+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 an explicitly shaped cutting profile if the finished mouth needs a countersink.
+
+## 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 and straight extrusion rims use independent `ends.bottom` and `ends.top`.
+- 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 exclude twist, top scaling, and exact divisions.
+- 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).