@code3d/core 0.0.1-alpha.0

package/src/library/spatial.ts

@@ -0,0 +1,254 @@
+export type Vec3 = readonly [x: number, y: number, z: number];
+
+export type Quaternion = readonly [x: number, y: number, z: number, w: number];
+
+export type RigidTransform = Readonly<{
+  position: Vec3;
+  quaternion: Quaternion;
+}>;
+
+export const origin: Vec3 = [0, 0, 0];
+export const identityQuaternion: Quaternion = [0, 0, 0, 1];
+export const halfTurnAroundX: Quaternion = [1, 0, 0, 0];
+export const identityRigidTransform: RigidTransform = {
+  position: origin,
+  quaternion: identityQuaternion,
+};
+
+export function translation(position: Vec3): RigidTransform {
+  return {position, quaternion: identityQuaternion};
+}
+
+export function rotation(quaternion: Quaternion): RigidTransform {
+  return {position: origin, quaternion};
+}
+
+/** Degrees, applied about fixed X, then Y, then Z axes. */
+export function xyzRotation(angles: Vec3): Quaternion {
+  const [x, y, z] = angles.map(angle => (angle * Math.PI) / 360);
+  const rx: Quaternion = [Math.sin(x), 0, 0, Math.cos(x)];
+  const ry: Quaternion = [0, Math.sin(y), 0, Math.cos(y)];
+  const rz: Quaternion = [0, 0, Math.sin(z), Math.cos(z)];
+  return multiplyQuaternions(rz, multiplyQuaternions(ry, rx));
+}
+
+export function rotationAround(position: Vec3, angles: Vec3): RigidTransform {
+  const quaternion = xyzRotation(angles);
+  return {
+    position: addVectors(
+      position,
+      negateVector(rotateVector(position, quaternion)),
+    ),
+    quaternion,
+  };
+}
+
+export function frameFromYAxis(
+  position: Vec3,
+  direction: Vec3,
+): RigidTransform {
+  const y = normalizeVector(direction);
+  const preferredX: Vec3 = Math.abs(y[0]) < 0.9 ? [1, 0, 0] : [0, 0, 1];
+  const x = normalizeVector(rejectVector(preferredX, y));
+  const z = crossVectors(x, y);
+  return {
+    position,
+    quaternion: quaternionFromBasis(x, y, z),
+  };
+}
+
+export function composeTransforms(
+  outer: RigidTransform,
+  inner: RigidTransform,
+): RigidTransform {
+  return {
+    position: addVectors(
+      outer.position,
+      rotateVector(inner.position, outer.quaternion),
+    ),
+    quaternion: multiplyQuaternions(outer.quaternion, inner.quaternion),
+  };
+}
+
+export function invertTransform(transform: RigidTransform): RigidTransform {
+  const quaternion = conjugateQuaternion(transform.quaternion);
+  return {
+    position: rotateVector(negateVector(transform.position), quaternion),
+    quaternion,
+  };
+}
+
+export function relativeTransform(
+  source: RigidTransform,
+  target: RigidTransform,
+): RigidTransform {
+  return composeTransforms(invertTransform(target), source);
+}
+
+export function rotateVector(vector: Vec3, quaternion: Quaternion): Vec3 {
+  const [x, y, z] = vector;
+  const [qx, qy, qz, qw] = quaternion;
+  const tx = 2 * (qy * z - qz * y);
+  const ty = 2 * (qz * x - qx * z);
+  const tz = 2 * (qx * y - qy * x);
+  return [
+    x + qw * tx + (qy * tz - qz * ty),
+    y + qw * ty + (qz * tx - qx * tz),
+    z + qw * tz + (qx * ty - qy * tx),
+  ];
+}
+
+export function addVectors(left: Vec3, right: Vec3): Vec3 {
+  return [left[0] + right[0], left[1] + right[1], left[2] + right[2]];
+}
+
+export function negateVector(vector: Vec3): Vec3 {
+  return [-vector[0], -vector[1], -vector[2]];
+}
+
+export function transformsAreEquivalent(
+  left: RigidTransform,
+  right: RigidTransform,
+  tolerance = 1e-7,
+): boolean {
+  const positionDelta = Math.hypot(
+    left.position[0] - right.position[0],
+    left.position[1] - right.position[1],
+    left.position[2] - right.position[2],
+  );
+  const quaternionDot = Math.abs(
+    left.quaternion[0] * right.quaternion[0] +
+      left.quaternion[1] * right.quaternion[1] +
+      left.quaternion[2] * right.quaternion[2] +
+      left.quaternion[3] * right.quaternion[3],
+  );
+  return positionDelta <= tolerance && 1 - quaternionDot <= tolerance;
+}
+
+export function quaternionAxisAngle(quaternion: Quaternion): Readonly<{
+  axis: Vec3;
+  angleDegrees: number;
+}> {
+  const normalized = normalizeQuaternion(quaternion);
+  const sign = normalized[3] < 0 ? -1 : 1;
+  const canonical: Quaternion = [
+    normalized[0] * sign,
+    normalized[1] * sign,
+    normalized[2] * sign,
+    normalized[3] * sign,
+  ];
+  const angle = 2 * Math.acos(clamp(canonical[3], -1, 1));
+  const sine = Math.sqrt(Math.max(0, 1 - canonical[3] * canonical[3]));
+  return {
+    axis:
+      sine < 1e-9
+        ? [1, 0, 0]
+        : [canonical[0] / sine, canonical[1] / sine, canonical[2] / sine],
+    angleDegrees: (angle * 180) / Math.PI,
+  };
+}
+
+function multiplyQuaternions(left: Quaternion, right: Quaternion): Quaternion {
+  const [lx, ly, lz, lw] = left;
+  const [rx, ry, rz, rw] = right;
+  return normalizeQuaternion([
+    lw * rx + lx * rw + ly * rz - lz * ry,
+    lw * ry - lx * rz + ly * rw + lz * rx,
+    lw * rz + lx * ry - ly * rx + lz * rw,
+    lw * rw - lx * rx - ly * ry - lz * rz,
+  ]);
+}
+
+function conjugateQuaternion(quaternion: Quaternion): Quaternion {
+  return [-quaternion[0], -quaternion[1], -quaternion[2], quaternion[3]];
+}
+
+function normalizeQuaternion(quaternion: Quaternion): Quaternion {
+  const length = Math.hypot(...quaternion);
+  return [
+    quaternion[0] / length,
+    quaternion[1] / length,
+    quaternion[2] / length,
+    quaternion[3] / length,
+  ];
+}
+
+function normalizeVector(vector: Vec3): Vec3 {
+  const length = Math.hypot(...vector);
+  if (length < 1e-12) {
+    throw new Error('A relation frame direction cannot be zero.');
+  }
+  return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+
+function rejectVector(vector: Vec3, normal: Vec3): Vec3 {
+  const projection = dotVectors(vector, normal);
+  return [
+    vector[0] - projection * normal[0],
+    vector[1] - projection * normal[1],
+    vector[2] - projection * normal[2],
+  ];
+}
+
+function dotVectors(left: Vec3, right: Vec3): number {
+  return left[0] * right[0] + left[1] * right[1] + left[2] * right[2];
+}
+
+function crossVectors(left: Vec3, right: Vec3): Vec3 {
+  return [
+    left[1] * right[2] - left[2] * right[1],
+    left[2] * right[0] - left[0] * right[2],
+    left[0] * right[1] - left[1] * right[0],
+  ];
+}
+
+function quaternionFromBasis(x: Vec3, y: Vec3, z: Vec3): Quaternion {
+  const m00 = x[0];
+  const m01 = y[0];
+  const m02 = z[0];
+  const m10 = x[1];
+  const m11 = y[1];
+  const m12 = z[1];
+  const m20 = x[2];
+  const m21 = y[2];
+  const m22 = z[2];
+  const trace = m00 + m11 + m22;
+  if (trace > 0) {
+    const scale = Math.sqrt(trace + 1) * 2;
+    return normalizeQuaternion([
+      (m21 - m12) / scale,
+      (m02 - m20) / scale,
+      (m10 - m01) / scale,
+      scale / 4,
+    ]);
+  }
+  if (m00 > m11 && m00 > m22) {
+    const scale = Math.sqrt(1 + m00 - m11 - m22) * 2;
+    return normalizeQuaternion([
+      scale / 4,
+      (m01 + m10) / scale,
+      (m02 + m20) / scale,
+      (m21 - m12) / scale,
+    ]);
+  }
+  if (m11 > m22) {
+    const scale = Math.sqrt(1 + m11 - m00 - m22) * 2;
+    return normalizeQuaternion([
+      (m01 + m10) / scale,
+      scale / 4,
+      (m12 + m21) / scale,
+      (m02 - m20) / scale,
+    ]);
+  }
+  const scale = Math.sqrt(1 + m22 - m00 - m11) * 2;
+  return normalizeQuaternion([
+    (m02 + m20) / scale,
+    (m12 + m21) / scale,
+    scale / 4,
+    (m10 - m01) / scale,
+  ]);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}

package/src/library/three.ts

@@ -0,0 +1,2 @@
+/** Native Three.js exports from the same dependency instance used by Core. */
+export * from 'three';

package/src/library/topology-id.ts

@@ -0,0 +1,81 @@
+/** A result-local ID, or an input path ending in an earlier result's local ID. */
+export type TopologyId = number | readonly [number, number, ...number[]];
+export type VertexId = TopologyId;
+export type EdgeId = TopologyId;
+export type SurfaceId = TopologyId;
+export type TopologyKind = 'vertex' | 'edge' | 'surface';
+
+export function isTopologyId(value: unknown): value is TopologyId {
+  const positiveInteger = (part: unknown): part is number =>
+    typeof part === 'number' && Number.isSafeInteger(part) && part > 0;
+  if (positiveInteger(value)) return true;
+  if (!Array.isArray(value) || value.length < 2) return false;
+  for (const part of value) if (!positiveInteger(part)) return false;
+  return true;
+}
+
+export function topologyIdKey(id: TopologyId): string {
+  return typeof id === 'number' ? String(id) : id.join('/');
+}
+
+export function sameTopologyId(
+  left: TopologyId | undefined,
+  right: TopologyId | undefined,
+): boolean {
+  return (
+    left === right ||
+    (left !== undefined &&
+      right !== undefined &&
+      topologyIdKey(left) === topologyIdKey(right))
+  );
+}
+
+export function inheritedTopologyId(input: number, id: TopologyId): TopologyId {
+  return typeof id === 'number' ? [input, id] : [input, ...id];
+}
+
+export function compareTopologyIds(
+  left: TopologyId,
+  right: TopologyId,
+): number {
+  if (typeof left === 'number')
+    return typeof right === 'number' ? left - right : -1;
+  if (typeof right === 'number') return 1;
+  for (let index = 0; index < Math.min(left.length, right.length); index++) {
+    const difference = left[index] - right[index];
+    if (difference) return difference;
+  }
+  return left.length - right.length;
+}
+
+export function formatTopologyId(kind: TopologyKind, id: TopologyId): string {
+  const prefix = {vertex: 'V', edge: 'E', surface: 'S'}[kind];
+  return `${prefix}${typeof id === 'number' ? id : `[${id.join(',')}]`}`;
+}
+
+/** Value equality also works for IDs reconstructed from source or a Worker. */
+export class TopologyIdSet implements Iterable<TopologyId> {
+  private readonly entries = new Map<string, TopologyId>();
+  constructor(ids: Iterable<TopologyId> = []) {
+    for (const id of ids) this.add(id);
+  }
+  get size(): number {
+    return this.entries.size;
+  }
+  has(id: TopologyId): boolean {
+    return this.entries.has(topologyIdKey(id));
+  }
+  add(id: TopologyId): this {
+    this.entries.set(topologyIdKey(id), id);
+    return this;
+  }
+  delete(id: TopologyId): boolean {
+    return this.entries.delete(topologyIdKey(id));
+  }
+  clear(): void {
+    this.entries.clear();
+  }
+  [Symbol.iterator](): MapIterator<TopologyId> {
+    return this.entries.values();
+  }
+}

package/src/library/topology-inspection.ts

@@ -0,0 +1,368 @@
+import {
+  BoundingBox,
+  getOC,
+  measureShapeLinearProperties,
+  measureShapeSurfaceProperties,
+  type AnyShape,
+  type Edge,
+  type Face,
+  type Vector,
+} from 'replicad';
+import {shapeSubshapes} from './kernel-shapes.js';
+import type {ShapeTopology, TopologyId, TopologyKind} from './topology.js';
+import {sameTopologyId} from './topology-id.js';
+import {
+  identityRigidTransform,
+  quaternionAxisAngle,
+  type RigidTransform,
+  type Vec3,
+} from './spatial.js';
+
+export type TopologyInspectionOptions = Readonly<{
+  kind?: TopologyKind;
+  ids?: readonly TopologyId[];
+  offset?: number;
+  limit?: number;
+  transform?: RigidTransform & {scale?: Vec3};
+}>;
+export type TopologyGeometry = {
+  type: string;
+  position?: Vec3;
+  length?: number;
+  area?: number;
+  centroid?: Vec3;
+  start?: Vec3;
+  end?: Vec3;
+  closed?: boolean;
+  direction?: Vec3;
+  normal?: Vec3;
+  normalSample?: {
+    position: Vec3;
+    normal: Vec3;
+    method: 'uv-domain-midpoint';
+    trimMembership: 'unchecked';
+  };
+  center?: Vec3;
+  axis?: Vec3;
+  radius?: number;
+  majorRadius?: number;
+  minorRadius?: number;
+};
+export type TopologyInspectionItem = {
+  kind: TopologyKind;
+  id: TopologyId;
+  geometry?: TopologyGeometry;
+  vertices?: readonly TopologyId[];
+  edges?: readonly TopologyId[];
+  surfaces?: readonly TopologyId[];
+  unavailable?: string;
+};
+export type TopologyInspection = Readonly<{
+  counts: Record<TopologyKind, number>;
+  bounds: {min: Vec3; max: Vec3; size: Vec3; method: 'kernel-enclosure'};
+  total: number;
+  offset: number;
+  nextOffset?: number;
+  items: readonly TopologyInspectionItem[];
+  units: 'model';
+  coordinates: 'scene';
+  geometrySource: 'kernel';
+  transform: NonNullable<TopologyInspectionOptions['transform']>;
+}>;
+
+/** Query retained B-rep geometry and its actual ID namespace, never the render mesh. */
+export function inspectShapeTopology(
+  original: AnyShape,
+  topology: ShapeTopology,
+  options: TopologyInspectionOptions = {},
+): TopologyInspection {
+  const offset = options.offset ?? 0;
+  const limit = options.limit ?? 48;
+  if (
+    !Number.isSafeInteger(offset) ||
+    offset < 0 ||
+    !Number.isSafeInteger(limit) ||
+    limit < 1 ||
+    limit > 200
+  )
+    throw new Error(
+      'Topology pages require a nonnegative offset and a limit from 1 to 200.',
+    );
+  if (options.ids && !options.kind)
+    throw new Error('Specify a topology kind when filtering IDs.');
+  const transform: NonNullable<TopologyInspectionOptions['transform']> =
+    options.transform ?? identityRigidTransform;
+  const scale = transform.scale ?? [1, 1, 1];
+  if (
+    scale.some(
+      value => !Number.isFinite(value) || value === 0 || value !== scale[0],
+    )
+  )
+    throw new Error('Topology inspection requires a uniform nonzero scale.');
+  let shape = original.clone();
+  const owned: AnyShape[] = [];
+  try {
+    if (scale[0] !== 1) shape = shape.scale(scale[0]);
+    const {axis, angleDegrees} = quaternionAxisAngle(transform.quaternion);
+    if (Math.abs(angleDegrees) > 1e-9)
+      shape = shape.rotate(angleDegrees, [0, 0, 0], [...axis]);
+    shape = shape.translate([...transform.position]);
+    const vertices = shapeSubshapes(shape, 'vertex');
+    owned.push(...vertices);
+    const edges = shapeSubshapes(shape, 'edge');
+    owned.push(...edges);
+    const surfaces = shapeSubshapes(shape, 'face');
+    owned.push(...surfaces);
+    const shapes = {vertex: vertices, edge: edges, surface: surfaces};
+    const ids = {
+      vertex: topology.vertices.ids,
+      edge: topology.edges.ids,
+      surface: topology.surfaces.ids,
+    };
+    for (const kind of ['vertex', 'edge', 'surface'] as const)
+      if (shapes[kind].length !== ids[kind].length)
+        throw new Error(
+          'Retained geometry does not match its topology namespace.',
+        );
+    if (
+      options.ids?.some(
+        id =>
+          !ids[options.kind!].some(available => sameTopologyId(available, id)),
+      )
+    )
+      throw new Error(
+        'A requested topology ID is absent from this model snapshot.',
+      );
+    const all = (
+      options.kind ? [options.kind] : (['surface', 'edge', 'vertex'] as const)
+    ).flatMap(kind =>
+      ids[kind].flatMap((id, index) =>
+        !options.ids ||
+        options.ids.some(requested => sameTopologyId(requested, id))
+          ? [{kind, id, index}]
+          : [],
+      ),
+    );
+    const page = all.slice(offset, offset + limit);
+    const childIndices = (
+      parent: AnyShape,
+      kind: 'edge' | 'vertex',
+    ): number[] => {
+      const children = shapeSubshapes(parent, kind);
+      try {
+        return shapes[kind].flatMap((candidate, index) =>
+          children.some(child => child.isSame(candidate)) ? [index] : [],
+        );
+      } finally {
+        children.forEach(child => child.delete());
+      }
+    };
+    const edgeVertices = new Map<number, number[]>();
+    const surfaceEdges = new Map<number, number[]>();
+    const verticesOf = (index: number) => {
+      if (!edgeVertices.has(index))
+        edgeVertices.set(index, childIndices(edges[index], 'vertex'));
+      return edgeVertices.get(index)!;
+    };
+    const edgesOf = (index: number) => {
+      if (!surfaceEdges.has(index))
+        surfaceEdges.set(index, childIndices(surfaces[index], 'edge'));
+      return surfaceEdges.get(index)!;
+    };
+    const items = page.map(({kind, id, index}): TopologyInspectionItem => {
+      try {
+        if (kind === 'vertex')
+          return {
+            kind,
+            id,
+            geometry: {type: 'POINT', position: vertices[index].asTuple()},
+            edges: edges.flatMap((_, edge) =>
+              verticesOf(edge).includes(index) ? [ids.edge[edge]] : [],
+            ),
+          };
+        if (kind === 'edge')
+          return {
+            kind,
+            id,
+            geometry: inspectEdge(edges[index]),
+            vertices: verticesOf(index).map(vertex => ids.vertex[vertex]),
+            surfaces: surfaces.flatMap((_, surface) =>
+              edgesOf(surface).includes(index) ? [ids.surface[surface]] : [],
+            ),
+          };
+        return {
+          kind,
+          id,
+          geometry: inspectSurface(surfaces[index]),
+          edges: edgesOf(index).map(edge => ids.edge[edge]),
+        };
+      } catch (error) {
+        return {
+          kind,
+          id,
+          unavailable:
+            error instanceof Error
+              ? error.message
+              : 'Kernel geometry query failed.',
+        };
+      }
+    });
+    const box = new BoundingBox();
+    let min: Vec3, max: Vec3;
+    try {
+      getOC().BRepBndLib.Add(shape.wrapped, box.wrapped, false);
+      [min, max] = box.bounds;
+    } finally {
+      box.delete();
+    }
+    return {
+      counts: {
+        vertex: vertices.length,
+        edge: edges.length,
+        surface: surfaces.length,
+      },
+      bounds: {
+        min,
+        max,
+        size: [max[0] - min[0], max[1] - min[1], max[2] - min[2]],
+        method: 'kernel-enclosure',
+      },
+      total: all.length,
+      offset,
+      ...(offset + page.length < all.length
+        ? {nextOffset: offset + page.length}
+        : {}),
+      items,
+      units: 'model',
+      coordinates: 'scene',
+      geometrySource: 'kernel',
+      transform,
+    };
+  } finally {
+    owned.forEach(value => value.delete());
+    shape.delete();
+  }
+}
+
+function vector(value: Vector, normalize = false): Vec3 {
+  try {
+    const tuple = value.toTuple();
+    if (!normalize) return tuple;
+    const length = Math.hypot(...tuple);
+    if (length < 1e-14) throw new Error('The sampled direction is singular.');
+    return [tuple[0] / length, tuple[1] / length, tuple[2] / length];
+  } finally {
+    value.delete();
+  }
+}
+function xyz(value: {
+  X(): number;
+  Y(): number;
+  Z(): number;
+  delete(): void;
+}): Vec3 {
+  try {
+    return [value.X(), value.Y(), value.Z()];
+  } finally {
+    value.delete();
+  }
+}
+function analytic(value: {
+  Location(): {X(): number; Y(): number; Z(): number; delete(): void};
+  Axis(): {
+    Direction(): {X(): number; Y(): number; Z(): number; delete(): void};
+    delete(): void;
+  };
+  delete(): void;
+}): {center: Vec3; axis: Vec3} {
+  try {
+    const axis = value.Axis();
+    try {
+      return {center: xyz(value.Location()), axis: xyz(axis.Direction())};
+    } finally {
+      axis.delete();
+    }
+  } finally {
+    value.delete();
+  }
+}
+
+function inspectEdge(edge: Edge): TopologyGeometry {
+  const properties = measureShapeLinearProperties(edge);
+  let length: number;
+  try {
+    length = properties.length;
+  } finally {
+    properties.delete();
+  }
+  const type = edge.geomType;
+  const result: TopologyGeometry = {
+    type,
+    length,
+    start: vector(edge.startPoint),
+    end: vector(edge.endPoint),
+    closed: edge.isClosed,
+  };
+  if (type === 'LINE') result.direction = vector(edge.tangentAt(0.5), true);
+  if (type === 'CIRCLE' || type === 'ELLIPSE') {
+    const curve = new (getOC().BRepAdaptor_Curve)(edge.wrapped);
+    try {
+      if (type === 'CIRCLE') {
+        const circle = curve.Circle();
+        result.radius = circle.Radius();
+        Object.assign(result, analytic(circle));
+      } else {
+        const ellipse = curve.Ellipse();
+        result.majorRadius = ellipse.MajorRadius();
+        result.minorRadius = ellipse.MinorRadius();
+        Object.assign(result, analytic(ellipse));
+      }
+    } finally {
+      curve.delete();
+    }
+  }
+  return result;
+}
+
+function inspectSurface(face: Face): TopologyGeometry {
+  const properties = measureShapeSurfaceProperties(face);
+  const type = face.geomType;
+  let result: TopologyGeometry;
+  try {
+    result = {
+      type: type === 'CYLINDRE' ? 'CYLINDER' : type,
+      area: properties.area,
+      centroid: properties.centerOfMass,
+    };
+  } finally {
+    properties.delete();
+  }
+  if (type === 'PLANE') result.normal = vector(face.normalAt(), true);
+  else
+    result.normalSample = {
+      position: vector(face.pointOnSurface(0.5, 0.5)),
+      normal: vector(face.normalAt(), true),
+      method: 'uv-domain-midpoint',
+      trimMembership: 'unchecked',
+    };
+  const surface = face.surface;
+  try {
+    if (type === 'CYLINDRE') {
+      const cylinder = surface.wrapped.Cylinder();
+      result.radius = cylinder.Radius();
+      Object.assign(result, analytic(cylinder));
+    }
+    if (type === 'SPHERE') {
+      const sphere = surface.wrapped.Sphere();
+      try {
+        result.radius = sphere.Radius();
+        result.center = xyz(sphere.Location());
+      } finally {
+        sphere.delete();
+      }
+    }
+  } finally {
+    surface.delete();
+  }
+  return result;
+}