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

package/src/library/runtime.ts

@@ -14,6 +14,9 @@ import {
   makeSphere,
   makeThreePointArc,
   makeVertex,
+  measureShapeLinearProperties,
+  measureShapeSurfaceProperties,
+  measureShapeVolumeProperties,
   sketchCircle,
   sketchEllipse,
   sketchPolysides,
@@ -35,7 +38,7 @@ import {
   type AlignmentGeometry,
 } from './alignment-geometry.js';
 import {cache, cachedArtifact} from './cached.js';
-import {extrudeWithTopology} from './extrude.js';
+import {extrudeWithTopology, revolveWithTopology} from './extrude.js';
 import {font, googleFont, type Font} from './font.js';
 import {
   anchorAnnotation,
@@ -66,7 +69,7 @@ import {
   shapeSubshapes,
   transformShape,
 } from './kernel-shapes.js';
-import {loftWithTopology} from './loft.js';
+import {loftWithTopology, sweepWithTopology} from './loft.js';
 import {captureModelMaterial, type ModelMaterialSnapshot} from './material.js';
 import {
   axisRotation,
@@ -277,6 +280,8 @@ export type ModelOperationKind =
   | 'sketchFace'
   | 'text'
   | 'extrude'
+  | 'revolve'
+  | 'sweep'
   | 'primitive'
   | 'material'
   | 'scaled'
@@ -851,8 +856,33 @@ export interface Vertex
   readonly id: VertexId;
 }
 
+interface LengthMeasurement {
+  /** Actual arc length of this finite edge.
+   * @code3d.inspect inspectLength
+   */
+  readonly length: number;
+}
+
+interface AreaMeasurement {
+  /** Finite surface area; solids include all boundary faces.
+   * @code3d.inspect inspectArea
+   */
+  readonly area: number;
+}
+
+interface VolumeMeasurement {
+  /** Volume occupied by the solid, excluding cavities.
+   * @code3d.inspect inspectVolume
+   */
+  readonly volume: number;
+}
+
 export interface Edge
-  extends LineAnchor, GeometryQueryCapabilities, EdgeTopologyCapabilities {
+  extends
+    LineAnchor,
+    GeometryQueryCapabilities,
+    EdgeTopologyCapabilities,
+    LengthMeasurement {
   readonly kind: 'edge';
   readonly id: EdgeId;
   readonly start: PointAnchor;
@@ -861,7 +891,11 @@ export interface Edge
 }
 
 export interface Surface
-  extends FaceAnchor, GeometryQueryCapabilities, SurfaceTopologyCapabilities {
+  extends
+    FaceAnchor,
+    GeometryQueryCapabilities,
+    SurfaceTopologyCapabilities,
+    AreaMeasurement {
   readonly kind: 'surface';
   readonly id: SurfaceId;
 }
@@ -870,7 +904,9 @@ export interface Solid
   extends
     Anchor<'frame'>,
     GeometryQueryCapabilities,
-    SurfaceTopologyCapabilities {
+    SurfaceTopologyCapabilities,
+    AreaMeasurement,
+    VolumeMeasurement {
   readonly kind: 'solid';
 }
 
@@ -1099,12 +1135,14 @@ export type VertexModel<Elements extends NamedElements = {}> =
 export type EdgeModel<Elements extends NamedElements = CurveElements> =
   ModelCapabilities<Elements, 'edge'> &
     GeometryCapabilities<Elements, 'edge'> &
-    EdgeTopologyCapabilities & {reverse(): Edge} & Elements;
+    EdgeTopologyCapabilities &
+    LengthMeasurement & {reverse(): Edge} & Elements;
 
 export type FaceModel<Elements extends NamedElements = PlanarElements> =
   ModelCapabilities<Elements, 'face'> &
     GeometryCapabilities<Elements, 'face'> &
-    SurfaceTopologyCapabilities & {
+    SurfaceTopologyCapabilities &
+    AreaMeasurement & {
       flip(): Surface;
       /**
        * Extrudes along the face's local plane normal. Signed distance; no recentering.
@@ -1113,13 +1151,35 @@ export type FaceModel<Elements extends NamedElements = PlanarElements> =
        * @code3d.param distance {kind: 'length', default: 10, label: 'Extrusion distance'}
        */
       extrude(distance: number): SolidModel;
+      /**
+       * Rotate this face about a straight directed axis.
+       * @code3d.inspect axis revolve.inspectMethodAxis
+       * @code3d.inspect config revolve.inspectMethodProfile
+       * @code3d.param config.angle {kind: 'angle', default: 360, label: 'Revolution angle'}
+       * @code3d.param config.advance {kind: 'length', default: 0, label: 'Axial advance'}
+       */
+      revolve(axis: LineAnchor, config: RevolveConfig): SolidModel;
+      /**
+       * Sweep this face along an open curve beginning at its local origin.
+       * @code3d.inspect this sweep.inspectMethodProfile
+       * @code3d.inspect spine sweep.inspectMethodSpine
+       */
+      sweep(spine: EdgeModel<{}>): SolidModel;
     } & Elements;
 
+/** Core parameters for rotational and screw-motion solids. */
+export type RevolveConfig = Readonly<{
+  angle: number;
+  advance?: number;
+}>;
+
 export type SolidModel<Elements extends NamedElements = CanonicalElements> =
   ModelCapabilities<Elements, 'solid'> &
     GeometryCapabilities<Elements, 'solid'> &
     SurfaceTopologyCapabilities &
     SolidModificationCapabilities<Elements> &
+    AreaMeasurement &
+    VolumeMeasurement &
     Elements;
 
 type RuntimeModel<
@@ -1261,6 +1321,21 @@ class ModelTopologyElement extends ModelAnchor {
     );
   }
 
+  /** @code3d.inspect inspectLength */
+  get length(): number {
+    return measureFiniteGeometry(this, 'length');
+  }
+
+  /** @code3d.inspect inspectArea */
+  get area(): number {
+    return measureFiniteGeometry(this, 'area');
+  }
+
+  /** @code3d.inspect inspectVolume */
+  get volume(): number {
+    return measureFiniteGeometry(this, 'volume');
+  }
+
   get start(): PointAnchor {
     return this.#curvePoint('start', 0);
   }
@@ -3037,6 +3112,21 @@ export class ModelObject<
     return new ModelObject<Elements, Kind>(init);
   }
 
+  /** @code3d.inspect inspectLength */
+  get length(): number {
+    return measureFiniteGeometry(this, 'length');
+  }
+
+  /** @code3d.inspect inspectArea */
+  get area(): number {
+    return measureFiniteGeometry(this, 'area');
+  }
+
+  /** @code3d.inspect inspectVolume */
+  get volume(): number {
+    return measureFiniteGeometry(this, 'volume');
+  }
+
   get origin(): PointAnchor {
     return this.frame.origin;
   }
@@ -3584,6 +3674,145 @@ export class ModelObject<
     return result as unknown as SolidModel;
   }
 
+  revolve(
+    this: ModelObject<Elements, 'face'>,
+    axis: LineAnchor,
+    config: RevolveConfig = {angle: 360},
+  ): SolidModel {
+    if (this.kind !== 'face')
+      throw new Error('revolve requires a single face model.');
+    const {angle = 360, advance = 0} = config;
+    if (!Number.isFinite(angle) || angle === 0)
+      throw new Error('Revolution angle must be finite and non-zero.');
+    if (!Number.isFinite(advance))
+      throw new Error('Revolution advance must be finite.');
+    if (advance === 0 && Math.abs(angle) > 360)
+      throw new Error('A revolution without advance cannot exceed one turn.');
+    const axisReference = straightAxisReference(axis, 'revolve() axis');
+    const context = ModelObject.createSolveContext([this, axisReference.model]);
+    const facePose = this.solvePose(context);
+    const axisFrame = relativeTransform(
+      composeTransforms(
+        axisReference.model.solvePose(context),
+        axisReference.transform,
+      ),
+      facePose,
+    );
+    const direction = rotateVector(
+      [0, axisReference.direction ?? 1, 0],
+      axisFrame.quaternion,
+    );
+    const source = this.requireGeometry();
+    const axisModel = isModelObject(axisReference.model)
+      ? axisReference.model
+      : undefined;
+    ModelObject.recordCompositionInspection(context, []);
+    const geometry = evaluateSolidGeometry(
+      'revolve',
+      [axisFrame.position, direction, angle, advance],
+      [source],
+      () =>
+        revolveWithTopology(
+          {
+            shape: source.value.shape,
+            topology: source.value.topology,
+            namespace: 1,
+          },
+          axisFrame.position,
+          direction,
+          angle,
+          advance,
+        ),
+    );
+    const result = ModelObject.create<CanonicalElements, 'solid'>({
+      kind: 'solid',
+      name: 'Revolve',
+      geometry,
+      material: this.materialSnapshot,
+      placements: this.placements,
+      sourceRefs: [...this.sourceRefs, ...(axisModel?.sourceRefs ?? [])],
+      parameters: uniqueParameters([
+        ...this.allParameters(),
+        ...(axisModel?.allParameters() ?? []),
+      ]),
+      meshTolerance: this.meshTolerance,
+      operation: storedOperation('revolve', [
+        {model: this, role: 'receiver', index: 0},
+        ...(axisModel
+          ? [{model: axisModel, role: 'reference' as const, index: 1}]
+          : []),
+      ]),
+    });
+    ModelObject.recordCompositionInspection(context, [[result, this]]);
+    return result as unknown as SolidModel;
+  }
+
+  sweep(this: ModelObject<Elements, 'face'>, spine: EdgeModel<{}>): SolidModel {
+    if (this.kind !== 'face')
+      throw new Error('sweep requires a single face model.');
+    const path = requireModelKind(
+      spine,
+      'edge',
+      'sweep requires an edge model as its spine.',
+    );
+    const context = ModelObject.createSolveContext([this, path]);
+    const profilePose = this.solvePose(context);
+    const pathTransform = relativeTransform(
+      path.solvePose(context),
+      profilePose,
+    );
+    const source = this.requireGeometry();
+    const pathGeometry = path.requireGeometry();
+    const normal = rotateVector(
+      [0, 1, 0],
+      this.geometryAnchor.transform.quaternion,
+    );
+    ModelObject.recordCompositionInspection(context, []);
+    const geometry = evaluateSolidGeometry(
+      'sweep',
+      [pathTransform.position, pathTransform.quaternion, normal],
+      [source, pathGeometry],
+      () => {
+        const positionedPath = shapeWithTransform(
+          pathGeometry.value.shape as ReplicadEdge,
+          pathTransform,
+        );
+        try {
+          return sweepWithTopology(
+            {
+              shape: source.value.shape,
+              topology: source.value.topology,
+              namespace: 1,
+            },
+            positionedPath,
+            normal,
+          );
+        } finally {
+          positionedPath.delete();
+        }
+      },
+    );
+    const result = ModelObject.create<CanonicalElements, 'solid'>({
+      kind: 'solid',
+      name: 'Sweep',
+      geometry,
+      material: this.materialSnapshot,
+      placements: this.placements,
+      sourceRefs: [...this.sourceRefs, ...path.sourceRefs],
+      parameters: uniqueParameters([
+        ...this.allParameters(),
+        ...path.allParameters(),
+      ]),
+      meshTolerance: Math.min(this.meshTolerance, path.meshTolerance),
+      operation: storedOperation('sweep', [
+        {model: this, role: 'receiver', index: 0},
+        {model: path, role: 'spine', index: 1},
+      ]),
+    });
+    ModelObject.recordCompositionInspection(context, [[result, this]]);
+    return result as unknown as SolidModel;
+  }
+
   cut(
     this: ModelObject<Elements, 'solid'>,
     tools: readonly SolidModel<{}>[],
@@ -4532,6 +4761,46 @@ export class ModelObject<
     };
   }
 
+  /** @internal */
+  static recordRevolve(
+    profile: ModelObject,
+    axis: LineAnchor,
+    result?: ModelObject,
+  ): void {
+    if (!isRecordingInspection()) return;
+    const reference = straightAxisReference(axis, 'revolve() axis');
+    const context = this.createSolveContext([profile, reference.model]);
+    this.recordCompositionInspection(
+      context,
+      result ? [[result, profile]] : [],
+    );
+  }
+
+  /** @internal */
+  static inspectRevolve(
+    profile: FaceModel<{}>,
+    axis: LineAnchor,
+    result: SolidModel | undefined,
+    data: CompositionInspectData,
+    focus: 'profile' | 'axis',
+  ): InspectResult {
+    const frame = this.inspectionFrame(data.poses);
+    const shownProfile = frame.positioned(profile)!;
+    const shownAxis = anchorAnnotation(frame.positioned(axis)! as LineAnchor, {
+      direction: 'forward',
+    });
+    const shownResult = result ? frame.positioned(result)! : undefined;
+    return focus === 'axis'
+      ? {
+          ambient: [shownProfile, ...(shownResult ? [shownResult] : [])],
+          target: [shownAxis],
+        }
+      : {
+          ambient: [shownAxis, ...(shownResult ? [shownResult] : [])],
+          target: [shownProfile],
+        };
+  }
+
   /** @internal Derive the focused cut volume using the original solved operands. */
   static inspectCutTools(
     stock: SolidModel<{}>,
@@ -5820,6 +6089,136 @@ export namespace relate {
   }
 }
 
+type MeasurementInspectData = Readonly<{
+  owner: Model;
+  target: Model | Anchor;
+  placement: DimensionSegment | Readonly<{at: Vec3}>;
+}>;
+
+function measureFiniteGeometry(
+  value: ModelObject | ModelTopologyElement,
+  measure: 'length' | 'area' | 'volume',
+): number {
+  const topology =
+    value instanceof ModelTopologyElement
+      ? value[anchorReferenceValue].topology
+      : undefined;
+  const owner =
+    value instanceof ModelObject ? value : value[anchorReferenceValue].model;
+  const geometry = (topology?.source ?? (value as ModelObject))[
+    modelGeometry
+  ]()!.value;
+  const scale = topology?.scale ?? 1;
+  const position = (point: Vec3): Vec3 =>
+    topology ? topologyTransform(topology, translation(point)).position : point;
+  const read = (shape: AnyShape): number => {
+    const properties =
+      measure === 'length'
+        ? measureShapeLinearProperties(shape)
+        : measure === 'area'
+          ? measureShapeSurfaceProperties(shape as ReplicadFace | Shape3D)
+          : measureShapeVolumeProperties(shape as Shape3D);
+    try {
+      const magnitude =
+        'length' in properties
+          ? properties.length
+          : 'area' in properties
+            ? properties.area
+            : properties.volume;
+      const power = measure === 'length' ? 1 : measure === 'area' ? 2 : 3;
+      const result = magnitude * scale ** power;
+      if (isRecordingInspection()) {
+        const edge = shape as ReplicadEdge;
+        const edgePoint = (parameter: number): Vec3 => {
+          const point = edge.pointAt(parameter);
+          try {
+            return position(point.toTuple());
+          } finally {
+            point.delete();
+          }
+        };
+        const placement =
+          measure === 'length' && edge.geomType === 'LINE'
+            ? {start: edgePoint(0), end: edgePoint(1)}
+            : {
+                at:
+                  measure === 'length'
+                    ? edgePoint(0.5)
+                    : position(properties.centerOfMass),
+              };
+        const target =
+          value instanceof ModelObject
+            ? value.kind === 'edge'
+              ? value.edges()[0]
+              : value.kind === 'face'
+                ? value.surfaces()[0]
+                : value
+            : value;
+        captureInspectData({owner, target, placement});
+      }
+      return result;
+    } finally {
+      properties.delete();
+    }
+  };
+  return topology
+    ? withTopologyShape(
+        geometry.shape,
+        geometry.topology,
+        topology.selection,
+        read,
+      )
+    : read(geometry.shape);
+}
+
+/** @internal */
+export function inspectLength(
+  _args: readonly [],
+  context: InspectContext<number, unknown, MeasurementInspectData | undefined>,
+): InspectResult | undefined {
+  return inspectMeasurement(context, 'length');
+}
+
+/** @internal */
+export function inspectArea(
+  _args: readonly [],
+  context: InspectContext<number, unknown, MeasurementInspectData | undefined>,
+): InspectResult | undefined {
+  return inspectMeasurement(context, 'area');
+}
+
+/** @internal */
+export function inspectVolume(
+  _args: readonly [],
+  context: InspectContext<number, unknown, MeasurementInspectData | undefined>,
+): InspectResult | undefined {
+  return inspectMeasurement(context, 'volume');
+}
+
+function inspectMeasurement(
+  context: InspectContext<number, unknown, MeasurementInspectData | undefined>,
+  kind: 'length' | 'area' | 'volume',
+): InspectResult | undefined {
+  if (context.return === undefined || !context.data) return;
+  const {owner, target, placement} = context.data;
+  return {
+    target: [
+      target,
+      dimension({
+        owner,
+        value: context.return,
+        ...placement,
+        axisLabel:
+          kind === 'length'
+            ? 'at' in placement
+              ? 'arc length'
+              : undefined
+            : kind,
+      }),
+    ],
+  };
+}
+
 /** @internal */
 export function inspectTopologyReference(
   _args: readonly unknown[],
@@ -5927,6 +6326,57 @@ export function extrude(
   }
 }
 
+/**
+ * @code3d.inspect profile revolve.inspectProfile
+ * @code3d.inspect axis revolve.inspectAxis
+ * @code3d.inspect config revolve.inspectProfile
+ * @code3d.param config.angle {kind: 'angle', default: 360, label: 'Revolution angle'}
+ * @code3d.param config.advance {kind: 'length', default: 0, label: 'Axial advance'}
+ */
+export function revolve(
+  profile: FaceModel<{}>,
+  axis: LineAnchor,
+  config: RevolveConfig,
+): SolidModel;
+export function revolve(
+  profile: FaceModel<{}>,
+  axis: LineAnchor,
+  config: RevolveConfig = {angle: 360},
+): SolidModel {
+  const runtimeProfile = requireModelKind(
+    profile,
+    'face',
+    'revolve requires a face model.',
+  );
+  let result: SolidModel | undefined;
+  try {
+    result = runtimeProfile.revolve(axis, config);
+    return result;
+  } finally {
+    ModelObject.recordRevolve(
+      runtimeProfile,
+      axis,
+      result as ModelObject | undefined,
+    );
+  }
+}
+
+/**
+ * Sweeps one planar profile along an open curve.
+ * @code3d.inspect profile sweep.inspectProfile
+ * @code3d.inspect spine sweep.inspectSpine
+ */
+export function sweep(
+  profile: FaceModel<{}>,
+  spine: EdgeModel<{}>,
+): SolidModel {
+  return requireModelKind(
+    profile,
+    'face',
+    'sweep requires a face model.',
+  ).sweep(spine);
+}
+
 /**
  * Creates connected text faces on the XZ plane: +X right, -Z up, normal +Y.
  * All faces share the baseline origin. Size is the font em in model units.
@@ -6474,6 +6924,8 @@ export const authoringApi = Object.freeze({
   bezier,
   spline,
   loft,
+  revolve,
+  sweep,
   box,
   cylinder,
   tube,
@@ -7504,6 +7956,146 @@ export namespace extrude {
   }
 }
 
+/** @internal */
+export namespace revolve {
+  export function inspectProfile(
+    [profile, axis]: [FaceModel<{}>, LineAnchor, RevolveConfig],
+    context: InspectContext<
+      SolidModel,
+      unknown,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return (
+      context.data &&
+      ModelObject.inspectRevolve(
+        profile,
+        axis,
+        context.return,
+        context.data,
+        'profile',
+      )
+    );
+  }
+
+  export function inspectAxis(
+    [profile, axis]: [FaceModel<{}>, LineAnchor, RevolveConfig],
+    context: InspectContext<
+      SolidModel,
+      unknown,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return (
+      context.data &&
+      ModelObject.inspectRevolve(
+        profile,
+        axis,
+        context.return,
+        context.data,
+        'axis',
+      )
+    );
+  }
+
+  export function inspectMethodProfile(
+    [axis]: [LineAnchor, RevolveConfig],
+    context: InspectContext<
+      SolidModel,
+      FaceModel<{}>,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return (
+      context.data &&
+      ModelObject.inspectRevolve(
+        context.receiver,
+        axis,
+        context.return,
+        context.data,
+        'profile',
+      )
+    );
+  }
+
+  export function inspectMethodAxis(
+    [axis]: [LineAnchor, RevolveConfig],
+    context: InspectContext<
+      SolidModel,
+      FaceModel<{}>,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return (
+      context.data &&
+      ModelObject.inspectRevolve(
+        context.receiver,
+        axis,
+        context.return,
+        context.data,
+        'axis',
+      )
+    );
+  }
+}
+
+/** @internal */
+export namespace sweep {
+  export function inspectProfile(
+    [profile, spine]: [FaceModel<{}>, EdgeModel<{}>],
+    context: InspectContext<
+      SolidModel,
+      unknown,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    if (!context.data) return undefined;
+    return ModelObject.inspectComposition(
+      context.data,
+      [spine, ...(context.return ? [context.return] : [])],
+      [profile],
+    );
+  }
+
+  export function inspectSpine(
+    [profile, spine]: [FaceModel<{}>, EdgeModel<{}>],
+    context: InspectContext<
+      SolidModel,
+      unknown,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    if (!context.data) return undefined;
+    return ModelObject.inspectComposition(
+      context.data,
+      [profile, ...(context.return ? [context.return] : [])],
+      [spine],
+    );
+  }
+
+  export function inspectMethodProfile(
+    [spine]: [EdgeModel<{}>],
+    context: InspectContext<
+      SolidModel,
+      FaceModel<{}>,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return inspectProfile([context.receiver, spine], context);
+  }
+
+  export function inspectMethodSpine(
+    [spine]: [EdgeModel<{}>],
+    context: InspectContext<
+      SolidModel,
+      FaceModel<{}>,
+      CompositionInspectData | undefined
+    >,
+  ): InspectResult | undefined {
+    return inspectSpine([context.receiver, spine], context);
+  }
+}
+
 /** @internal */
 export namespace union {
   export function inspectOperands(