@code3d/core 0.0.1-alpha.11 → 0.0.1-alpha.12

package/docs/api.md

@@ -31,6 +31,7 @@ radius. For coils, `coilRadius` is measured to the wire centerline and
 `pitch` is the advance per turn. Fractional turns are supported; the wire
 must fit inside the coil radius and neighboring turns must remain separated.
 Use [`@code3d/screws`](../../screws/docs/assembly.mdx) for standard fasteners and matching hole tools.
+Use [`@code3d/gears`](../../gears/README.md) for nominal spur, helical and internal gear parts.
 
 To build a solid beyond these primitives, import `definePrimitive` and
 `replicad` from `@code3d/core/replicad`. See
@@ -40,19 +41,21 @@ To build a solid beyond these primitives, import `definePrimitive` and
 
 Planar profiles lie in the local XZ plane with a +Y normal.
 
-| Function                                   | Meaning                                      |
-| ------------------------------------------ | -------------------------------------------- |
-| `circle(radius)`                           | Circular face                                |
-| `ellipse(xRadius, zRadius)`                | Elliptical face                              |
-| `rectangle(x, z)`                          | Rectangular face                             |
-| `regularPolygon(radius, sides, rotation?)` | Regular polygonal face                       |
-| `point()` or `point([x, y, z])`            | Vertex model                                 |
-| `line([x, y, z])` or `line(start, end)`    | Straight edge                                |
-| `arc(start, middle, end)`                  | Arc through three points                     |
-| `bezier(points)`                           | Bézier curve                                 |
-| `spline(points)`                           | Interpolating spline                         |
-| `loft(sections, options?)`                 | Solid through sections; optional curve spine |
-| `extrude(faceOrFaces, distance)`           | Solid extruded along one face's local normal |
+| Function                                   | Meaning                                                                   |
+| ------------------------------------------ | ------------------------------------------------------------------------- |
+| `circle(radius)`                           | Circular face                                                             |
+| `ellipse(xRadius, zRadius)`                | Elliptical face                                                           |
+| `rectangle(x, z)`                          | Rectangular face                                                          |
+| `regularPolygon(radius, sides, rotation?)` | Regular polygonal face                                                    |
+| `point()` or `point([x, y, z])`            | Vertex model                                                              |
+| `line([x, y, z])` or `line(start, end)`    | Straight edge                                                             |
+| `arc(start, middle, end)`                  | Arc through three points                                                  |
+| `bezier(points)`                           | Bézier curve                                                              |
+| `spline(points)`                           | Interpolating spline                                                      |
+| `loft(sections, options?)`                 | Solid through sections; optional curve spine                              |
+| `extrude(faceOrFaces, distance)`           | Solid extruded along one face's local normal                              |
+| `revolve(profile, axis, config)`           | Solid rotated about a straight directed axis, with optional axial advance |
+| `sweep(profile, spine)`                    | Solid formed by carrying one face along an open curve                     |
 
 See [local coordinates and placement](local-coordinates.md) for
 the coordinate frame of a model, reference, or composition.
@@ -83,8 +86,126 @@ export const plate = rectangle(30, 20).extrude(3).fillet(0.5);
 export const pin = extrude(circle(2), -10);
 ```
 
+### Rotational solids
+
+`revolve(profile, axis, config: RevolveConfig)` and
+`profile.revolve(axis, config)` rotate one face about a straight directed axis.
+`line(...)` can be passed directly; an existing straight edge or axis reference
+also works.
+`config.angle` is a required finite, non-zero angle in degrees. `config.advance`
+is the signed total distance traveled along the directed axis during that angle;
+it defaults to zero. A positive angle follows the axis's right-hand direction.
+Reversing the axis reverses both the rotation sense and the direction of a positive
+advance. With zero advance, the angle may cover at most one turn. With non-zero
+advance, it may cover multiple turns to form a simple screw-motion solid.
+
+```ts
+import {circle, line, rectangle, revolve} from '@code3d/core';
+
+const axis = line([0, -20, 0], [0, 20, 0]);
+const ringSection = rectangle(4, 6).rotate(90, 0, 0).originOffset(-8, 0, 0);
+export const ring = revolve(ringSection, axis, {angle: 360});
+
+const wireSection = circle(1).rotate(90, 0, 0).originOffset(-8, 0, 0);
+export const spring = wireSection.revolve(axis, {angle: 5 * 360, advance: 25});
+```
+
+The authoring signature requires `config`. While editing an incomplete call,
+the App uses 360 degrees and zero advance so its parameter tool can add the
+config object.
+
+The result keeps the profile's local frame and is an ordinary `SolidModel`.
+The axis participates in the same relation solve as the profile; its own model
+placement is respected. A helical profile must have one outer boundary without
+holes. Intersecting turns and profiles that cross the axis may fail to produce a
+valid solid; leave clearance between turns and keep the profile off the axis.
+For a multi-turn coil with round wire and automatic pitch clearance checks,
+[`coil`](#solid-primitives) remains the shorter constructor.
+
+### Path sweeps
+
+`sweep(profile, spine)` and `profile.sweep(spine)` carry one planar face along a
+continuous open `EdgeModel`, such as a line or Bézier curve. The face's local
+origin must meet the path's start, and its normal must point along the starting
+tangent. The operation respects the solved placement of both inputs and returns
+a solid in the profile's local frame; it does not move or rotate the supplied
+profile to fit the path.
+
+```ts
+import {bezier, circle, sweep} from '@code3d/core';
+
+const profile = circle(2);
+const spine = bezier([
+  [0, 0, 0],
+  [0, 8, 0],
+  [5, 16, 0],
+  [5, 24, 0],
+]);
+export const bentRod = sweep(profile, spine);
+```
+
+The path must be open with a non-zero starting tangent. The output is an ordinary
+`SolidModel` that supports subsequent Boolean and finishing operations. Very
+tight bends or self-intersections may prevent the kernel from producing a valid
+solid. One through hole in the profile is supported; profiles with multiple
+holes currently need explicit contour correspondence. Use the
+[App example](../../app/examples/operations/sweep.ts) to inspect
+the profile, path and result.
+
 ## Measurements
 
+### Length and area
+
+Read `edge.length` or `line(...).length` for a finite edge's actual arc length.
+A straight edge uses its endpoint distance; a closed edge uses its circumference.
+Read `surface.area` or `faceModel.area` for a finite face's area, including curved
+surfaces and trimming holes. `solid.area` / `solidModel.area` includes every
+boundary face, including inner walls and cavity faces.
+
+These properties return ordinary numbers in model units (area in square model
+units). They are read-only. Rotation, origin changes, placement and reversing an
+edge or flipping a face preserve the result. `scaled(s)` multiplies lengths by
+`s` and areas by `s²`; exposed references use the scale of their actual geometry.
+`LineAnchor` and `FaceAnchor` can describe infinite references and have no length
+or area. Groups have no aggregate area.
+
+```ts
+import {line, rectangle, box} from '@code3d/core';
+const length = line([3, 4, 0]).length; // 5
+const area = rectangle(4, 6).area; // 24
+const surfaceArea = box(2, 3, 4).area; // 52
+```
+
+Select `.length` or `.area` in App to inspect the measured geometry and value.
+Straight lengths use a dimension line; curves highlight their actual path with an
+arc-length label. Area highlights the finite face or whole solid with an area
+label. The read-only display does not create editable size constraints.
+Try the [length example](../../app/examples/operations/length.ts) and
+[area example](../../app/examples/operations/area.ts).
+
+### Volume
+
+Read `solid.volume` or `solidModel.volume` for the space occupied by the solid's
+material. Holes and enclosed cavities are excluded. The result is a read-only
+number in cubic model units. Rotation, origin changes and placement preserve it;
+`scaled(s)` multiplies it by `s³`. Exposed solid references include the scale of
+their actual geometry. Faces, edges, infinite references and groups have no volume
+property.
+
+```ts
+import {box, tube} from '@code3d/core';
+const blockVolume = box(2, 3, 4).volume; // 24
+const pipeVolume = tube(5, 3, 7).volume; // 112 * Math.PI
+const enlargedVolume = box(2, 3, 4).scaled(2).volume; // 192
+```
+
+Select `.volume` in App to inspect the whole solid with a volume label at its
+volume centroid. This read-only display uses the getter's recorded result and
+does not create an editable size constraint.
+Try the [volume example](../../app/examples/operations/volume.ts).
+
+### Distance between references
+
 `distance(a, b, axis?)` returns a non-negative `number` from the models and
 relations available at the call. It accepts vertex, edge, face and solid models,
 non-empty groups, finite topology references, directional bounds, and point

package/docs/local-coordinates.md

@@ -47,6 +47,8 @@ Only an explicit origin operation chooses a different local zero.
 | `text`                                            | All returned faces share the text layout's baseline origin, including its glyph advances and offsets. Individual letters are not centered. |
 | `definePrimitive`                                 | Retain the frame used by the returned geometry; no automatic recentering.                                                                  |
 | `extrude`                                         | Inherit the input face's frame, without centering the extrusion.                                                                           |
+| `revolve`                                         | Inherit the input profile's frame; the axis's solved placement is converted into that frame.                                               |
+| `sweep`                                           | Inherit the input profile's frame; the spine's solved placement is converted into that frame.                                              |
 | `union`, `intersect`                              | Inherit the first operand's frame.                                                                                                         |
 | `cut`                                             | Inherit the stock's frame.                                                                                                                 |
 | `loft`                                            | Inherit the first section's frame.                                                                                                         |

package/docs/runtime.md

@@ -79,9 +79,9 @@ shows the selected inputs and ambient operands without inventing a result.
 These region inspectors use ordinary unlit materials with depth testing disabled,
 so their colors remain visible through the translucent inputs.
 
-Core uses this mechanism for distance measurements, relate calls and their
+Core uses this mechanism for length/area/volume properties, distance measurements, relate calls and their
 closures, on/align references, relative transformation stages, group children,
-expose sources, Boolean operands and loft sections/spines, plus box and extrusion
+expose sources, Boolean operands, loft sections/spines and sweep profiles/spines, plus box and extrusion
 dimensions. Selecting a normal constructor or Boolean function name
 still previews its return value. Inspectors retain the original operation frame,
 so a later relation or a different consumer cannot move its inspection.
@@ -108,6 +108,46 @@ the owner as `ambient` when the call fails or the reference collection is empty.
 The owner therefore has the same background appearance before and after a
 selection; missing or invalid IDs still produce their normal modeling errors.
 
+### Getter inspection
+
+A getter can declare `@code3d.inspect callback` in its JSDoc. A package can put
+the same annotation on its public `readonly` property declaration when the
+implementation getter is not present in its declarations. The callback receives
+`[]`, with the actual receiver in `context.receiver`, the recorded property value
+in `context.return`, and any `captureInspectData` payload in `context.data`.
+
+```ts
+import {
+  captureInspectData,
+  type InspectContext,
+  type Model,
+} from '@code3d/core';
+
+function inspectSize(_args: readonly [], context: InspectContext<number>) {
+  return {target: [context.data as Model]};
+}
+class Part {
+  constructor(readonly body: Model) {}
+  /** @code3d.inspect inspectSize */
+  get size() {
+    captureInspectData(this.body);
+    return 42;
+  }
+}
+```
+
+Read `part.size` normally to record it. Selecting the property runs only its
+inspector; it never runs the getter again. Each reached read keeps its own
+receiver, return and data, even if several reads return the same number. Local
+getters retain their declaration's lexical inspector binding; published callbacks
+must be runtime exports of the package. Optional reads that short-circuit do not
+invoke an inspector. A failed getter can still inspect its captured data, with
+`context.return` undefined. Merely enumerating an object never invokes its getters.
+
+Core's `.length`, `.area` and `.volume` use this mechanism. Passive `dimension` annotations
+accept either `start`/`end`, alternative `candidates`, or `at: [x, y, z]` to show
+only a value at an owner's local position. Labels do not add CAD geometry.
+
 ### Call data
 
 The App runs JSDoc inspection callbacks when the corresponding source is selected.

package/docs/topology.md

@@ -127,6 +127,12 @@ const corners = boundary[0].vertices();
 const center = face.center;
 ```
 
+Edges expose readonly `.length` for actual arc length; surfaces expose `.area`
+for their trimmed finite area. Exposed solids provide total boundary `.area` and
+material `.volume`, excluding holes and cavities. These measurements include the
+scale of the selected geometry. See [length and area](api.md#length-and-area)
+and [volume](api.md#volume).
+
 Queries use the original model's IDs and stay within the selected element.
 `face.edge(id)` reports an error if that edge is outside the face. The viewport
 picker offers only the eligible edges or vertices, including when the geometry

package/docs/values.md

@@ -63,6 +63,15 @@ finite geometry, nested occurrences, axis frames and source-order dependencies.
 
 ## Geometry measurements
 
+Finite edges and edge models provide readonly `.length`; finite surfaces and
+face models provide `.area`. Solids provide `.area` for their total boundary
+surface, including inner walls, and `.volume` for material volume, excluding holes
+and cavities. These are plain numbers, follow geometry scaling, and retain the
+original value when later operations create a new model. Infinite axes/planes
+and groups do not have these measurements. See [length and area](api.md#length-and-area)
+and [volume](api.md#volume), and select these properties in App for a read-only
+visual measurement.
+
 `model.bounds(relativeTo?)` returns readonly `minimum`, `maximum` and `size`
 XYZ vectors for tight finite geometry bounds. By default it uses the model's
 own local frame. An explicit reference includes solved placement and nested

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@code3d/core",
-  "version": "0.0.1-alpha.11",
+  "version": "0.0.1-alpha.12",
   "publishConfig": {
     "access": "public"
   },

package/src/library/extrude.ts

@@ -1,5 +1,14 @@
-import {getOC, Vector, type Shape3D} from 'replicad';
-import {castOwnedShape3D} from './kernel-shapes.js';
+import {
+  assembleWire,
+  getOC,
+  makeHelix,
+  makeLine,
+  measureVolume,
+  Vector,
+  type Face,
+  type Shape3D,
+} from 'replicad';
+import {castOwnedShape3D, shapeSubshapes} from './kernel-shapes.js';
 import {
   transferShapeTopology,
   type TopologyInput,
@@ -36,3 +45,121 @@ export function extrudeWithTopology(
     vector.delete();
   }
 }
+
+/** Sweep a face around a directed axis, optionally advancing along it. */
+export function revolveWithTopology(
+  source: TopologyInput,
+  center: Vec3,
+  direction: Vec3,
+  angle: number,
+  advance: number,
+): {shape: Shape3D; topology?: ShapeTopology} {
+  const oc = getOC();
+  if (advance === 0) {
+    const point = new oc.gp_Pnt(...center);
+    let dir: InstanceType<typeof oc.gp_Dir> | undefined;
+    let axis: InstanceType<typeof oc.gp_Ax1> | undefined;
+    let shape: Shape3D | undefined;
+    try {
+      dir = new oc.gp_Dir(...direction);
+      axis = new oc.gp_Ax1(point, dir);
+      const builder = new oc.BRepPrimAPI_MakeRevol(
+        source.shape.wrapped,
+        axis,
+        angle * (Math.PI / 180),
+        false,
+      );
+      try {
+        if (!builder.IsDone()) throw new Error('Could not revolve the face.');
+        shape = castOwnedShape3D(builder.Shape());
+        requireRevolvedVolume(shape);
+        return {
+          shape,
+          topology: transferShapeTopology([source], shape, builder),
+        };
+      } finally {
+        builder.delete();
+      }
+    } catch (error) {
+      shape?.delete();
+      throw error;
+    } finally {
+      axis?.delete();
+      dir?.delete();
+      point.delete();
+    }
+  }
+
+  const boundaries = shapeSubshapes(source.shape, 'wire');
+  try {
+    if (boundaries.length !== 1)
+      throw new Error('Helical revolution requires a face without holes.');
+  } finally {
+    boundaries.forEach(boundary => boundary.delete());
+  }
+  const end: Vec3 = [
+    center[0] + direction[0] * advance,
+    center[1] + direction[1] * advance,
+    center[2] + direction[2] * advance,
+  ];
+  let startVector: Vector | undefined;
+  let endVector: Vector | undefined;
+  let line: ReturnType<typeof makeLine> | undefined;
+  let spine: ReturnType<typeof assembleWire> | undefined;
+  let guide: ReturnType<typeof makeHelix> | undefined;
+  let wire: ReturnType<Face['outerWire']> | undefined;
+  let shape: Shape3D | undefined;
+  try {
+    startVector = new Vector([...center]);
+    endVector = new Vector([...end]);
+    line = makeLine(startVector, endVector);
+    spine = assembleWire([line]);
+    guide = makeHelix(
+      (advance * 360) / angle,
+      advance,
+      1,
+      [...center],
+      [...direction],
+    );
+    // Replicad's outerWire consumes its cloned Face wrapper.
+    wire = (source.shape as Face).clone().outerWire();
+    const builder = new oc.BRepOffsetAPI_MakePipeShell(spine.wrapped);
+    try {
+      builder.SetMode(
+        guide.wrapped,
+        false,
+        oc.BRepFill_TypeOfContact.BRepFill_NoContact,
+      );
+      builder.Add(wire.wrapped, false, false);
+      if (!builder.IsReady())
+        throw new Error(
+          'Could not associate the profile with the rotation axis.',
+        );
+      builder.Build();
+      if (!builder.IsDone() || !builder.MakeSolid())
+        throw new Error('Could not construct a solid helical revolution.');
+      shape = castOwnedShape3D(builder.Shape());
+      requireRevolvedVolume(shape);
+      // PipeShell does not expose face-cap history for an input face. Assign
+      // stable output IDs without guessing an inherited input correspondence.
+      return {shape};
+    } finally {
+      builder.delete();
+    }
+  } catch (error) {
+    shape?.delete();
+    throw error;
+  } finally {
+    wire?.delete();
+    guide?.delete();
+    spine?.delete();
+    line?.delete();
+    endVector?.delete();
+    startVector?.delete();
+  }
+}
+
+function requireRevolvedVolume(shape: Shape3D): void {
+  if (!(Math.abs(measureVolume(shape)) > 0))
+    throw new Error('Revolution did not produce a non-degenerate solid.');
+}

package/src/library/index.ts

@@ -13,6 +13,9 @@ export {
   align,
   expose,
   inspectTopologyReference,
+  inspectLength,
+  inspectArea,
+  inspectVolume,
 } from './runtime.js';
 export type {
   Dimension,
@@ -71,7 +74,9 @@ export {
   rectangle,
   regularPolygon,
   regularPrism,
+  revolve,
   spline,
+  sweep,
   sphere,
   tube,
   union,
@@ -117,6 +122,7 @@ export type {
   NamedElements,
   PlanarElements,
   PointAnchor,
+  RevolveConfig,
   Solid,
   SolidModel,
   SolidModificationCapabilities,

package/src/library/inspect.ts

@@ -49,14 +49,16 @@ export function recordInspectionCalls(
 export type DimensionSegment = Readonly<{start: Vec3; end: Vec3}>;
 
 type DimensionLines =
-  DimensionSegment | Readonly<{candidates: readonly DimensionSegment[]}>;
+  | DimensionSegment
+  | Readonly<{candidates: readonly DimensionSegment[]}>
+  | Readonly<{at: Vec3}>;
 type DimensionOptions = Readonly<{
   owner: Model;
   value: number;
   axisLabel?: string;
 }>;
 
-/** A passive dimension; a candidate is selected on entry and retained while inspecting it. */
+/** A passive measurement. `at` labels a point without a dimension line. */
 export type Dimension = Readonly<{kind: 'dimension'}> &
   DimensionOptions &
   DimensionLines;

package/src/library/loft.ts

@@ -1,7 +1,10 @@
 import {
+  assembleWire,
   cast,
   getOC,
+  measureVolume,
   type AnyShape,
+  type Edge,
   type Face,
   type Wire,
   type Shape3D,
@@ -19,6 +22,66 @@ import {
   type TopologyInput,
   type ShapeTopology,
 } from './topology.js';
+import type {Vec3} from './spatial.js';
+
+/** Sweep a face along one open edge, keeping the authored starting frame. */
+export function sweepWithTopology(
+  profile: TopologyInput,
+  path: Edge,
+  normal: Vec3,
+): Readonly<{shape: Shape3D; topology: ShapeTopology}> {
+  if (path.isClosed || !(path.length > 1e-9))
+    throw new Error('Sweep spine must be a non-degenerate open curve.');
+  const start = path.pointAt(0);
+  let tangent: ReturnType<Edge['tangentAt']> | undefined;
+  try {
+    tangent = path.tangentAt(0);
+    const position = start.toTuple();
+    const direction = tangent.toTuple();
+    const magnitude = Math.hypot(...direction);
+    if (!(magnitude > 1e-9))
+      throw new Error('Sweep spine must have a non-zero starting tangent.');
+    if (Math.hypot(...position) > 1e-6)
+      throw new Error(
+        'Sweep profile origin must coincide with the spine start.',
+      );
+    if (
+      (normal[0] * direction[0] +
+        normal[1] * direction[1] +
+        normal[2] * direction[2]) /
+        magnitude <
+      1 - 1e-6
+    )
+      throw new Error(
+        'Sweep profile normal must point along the spine start tangent.',
+      );
+  } finally {
+    tangent?.delete();
+    start.delete();
+  }
+  const spine = assembleWire([path]);
+  let result: Readonly<{shape: Shape3D; topology: ShapeTopology}> | undefined;
+  try {
+    result = loftWithTopology([profile], spine, false);
+    if (!(Math.abs(measureVolume(result.shape)) > 0))
+      throw new Error('Sweep did not produce a non-degenerate solid.');
+    const validation = new (getOC().BRepCheck_Analyzer)(result.shape.wrapped);
+    try {
+      if (!validation.IsValid())
+        throw new Error(
+          'Sweep produced an invalid solid. Adjust the profile or path to avoid tight bends and intersections.',
+        );
+    } finally {
+      validation.delete();
+    }
+    return result;
+  } catch (error) {
+    result?.shape.delete();
+    throw error;
+  } finally {
+    spine.delete();
+  }
+}
 
 export function loftWithTopology(
   sections: readonly TopologyInput[],
@@ -48,7 +111,7 @@ export function loftWithTopology(
       throw new Error('Loft sections must have matching hole counts.');
     if (holes[0].length > 1)
       throw new Error(
-        'Loft currently supports at most one hole per section; multiple holes need explicit correspondence.',
+        'A swept or lofted profile currently supports at most one hole; multiple holes need explicit correspondence.',
       );
     outer = loftContoursWithTopology(sections, spine, ruled);
     if (!holes[0].length) {
@@ -115,7 +178,9 @@ function loftContoursWithTopology(
     }
     result = castOwnedShape3D(builder.Shape());
     caps[0] = castOwnedShape(builder.FirstShape()) as Face;
-    caps[sections.length - 1] = castOwnedShape(builder.LastShape()) as Face;
+    // A single profile has one inherited start cap; its end cap is new topology.
+    if (sections.length > 1)
+      caps[sections.length - 1] = castOwnedShape(builder.LastShape()) as Face;
     const topology = transferShapeTopology(
       sections,
       result,