@code3d/core 0.0.1-alpha.0

package/src/library/kernel-cache.ts

@@ -0,0 +1,337 @@
+import type {OpenCascadeInstance} from '@code3d/opencascade';
+import {getOC} from 'replicad';
+import {estimateRetainedBytes} from './retained-memory.js';
+import {
+  decodeKernelArtifact,
+  encodeKernelArtifact,
+} from './kernel-artifact-codec.js';
+
+/** The host opens storage before synchronous evaluation and owns its lifetime. */
+export interface KernelArtifactStore {
+  get(id: string): Uint8Array | undefined;
+  set(id: string, bytes: Uint8Array): void;
+  touch(id: string): boolean;
+  delete(id: string): void;
+  flush(): void;
+}
+
+export type KernelKeyPart =
+  string | number | boolean | null | readonly KernelKeyPart[];
+
+export type KernelArtifact<Value> = Readonly<{
+  id: string;
+  value: Value;
+}>;
+
+export type KernelValueLifecycle<Value> = Readonly<{
+  estimateBytes(value: Value): number;
+  retain(value: Value): Value;
+  instantiate(retained: Value): Value;
+  release(value: Value): void;
+}>;
+
+type CacheEntry<Value> = Readonly<{
+  estimatedBytes: number;
+  signature: string;
+  value: Value;
+  instantiate(retained: Value): Value;
+  release(value: Value): void;
+}>;
+
+export function createKernelOperationCache({
+  maximumBytes = 2 * 1024 ** 3,
+  nativeAllocatedBytes,
+}: {
+  maximumBytes?: number;
+  nativeAllocatedBytes: () => number;
+}) {
+  const entries = new Map<string, CacheEntry<unknown>>();
+  const historicalEntries = new Map<string, CacheEntry<unknown>>();
+  let retainedEvaluation = new Set<string>();
+  let currentEvaluation:
+    {used: Set<string>; checkCancelled?: () => void} | undefined;
+  let hits = 0;
+  let misses = 0;
+  let estimatedJavaScriptBytes = 0;
+  let store: KernelArtifactStore | undefined;
+  let persistentHits = 0;
+  let persistentWrites = 0;
+  let persistenceErrors = 0;
+  const persisted = new Set<string>();
+  let externalBytes = 0;
+
+  /** The host accounts for in-flight inputs and all auxiliary native heaps. */
+  function setKernelExternalBytes(bytes: number): void {
+    externalBytes = bytes;
+    evictHistoricalEntries();
+  }
+
+  function setKernelArtifactStore(next: KernelArtifactStore | undefined): void {
+    store = next;
+    persisted.clear();
+  }
+
+  function accessStore<Result>(
+    action: (store: KernelArtifactStore) => Result,
+  ): Result | undefined {
+    if (!store) return undefined;
+    try {
+      return action(store);
+    } catch {
+      // Cache storage is optional. Its failures must not change model execution.
+      persistenceErrors += 1;
+      store = undefined;
+      return undefined;
+    }
+  }
+
+  /**
+   * Keep a serial evaluation's complete working set, including snapshot queries.
+   * The previous working set stays available until this evaluation finishes so
+   * a changed prefix cannot evict unchanged operations that execute later.
+   * Outside evaluations, only the bounded historical LRU admits new entries.
+   */
+  function beginKernelOperationEvaluation(
+    checkCancelled?: () => void,
+  ): () => void {
+    const used = new Set<string>();
+    currentEvaluation = {used, checkCancelled};
+    return () => {
+      for (const id of retainedEvaluation) {
+        if (!used.has(id)) historicalEntries.set(id, entries.get(id)!);
+      }
+      retainedEvaluation = used;
+      currentEvaluation = undefined;
+      evictHistoricalEntries();
+      accessStore(store => store.flush());
+    };
+  }
+
+  /**
+   * Reuses one complete, deterministic kernel operation. Arguments describe
+   * scalar semantics; inputs carry the content identities of prior operations.
+   * The lifecycle keeps the retained value independent from each disposable use.
+   */
+  function evaluateKernelOperation<Value>(
+    operation: string,
+    arguments_: readonly KernelKeyPart[],
+    inputs: readonly KernelArtifact<unknown>[],
+    lifecycle: KernelValueLifecycle<Value>,
+    compute: () => Value,
+  ): KernelArtifact<Value> {
+    const key = kernelOperationKey(operation, arguments_, inputs);
+    const cached = findKernelOperation(key, lifecycle);
+    if (cached) return cached;
+    const value = compute();
+    acceptKernelOperation(key, lifecycle, value);
+    return {id: key.id, value};
+  }
+
+  function findKernelOperation<Value>(
+    key: KernelOperationKey,
+    lifecycle: KernelValueLifecycle<Value>,
+  ): KernelArtifact<Value> | undefined {
+    currentEvaluation?.checkCancelled?.();
+    const {id, signature} = key;
+    let cached = entries.get(id) as CacheEntry<Value> | undefined;
+    if (!cached) {
+      const bytes = accessStore(store => store.get(id));
+      if (bytes) {
+        let restored: Value;
+        try {
+          restored = decodeKernelArtifact<Value>(bytes, signature);
+        } catch {
+          persistenceErrors += 1;
+          accessStore(store => store.delete(id));
+          misses += 1;
+          return undefined;
+        }
+        cached = retainEntry(key, lifecycle, restored);
+        persistentHits += 1;
+        persisted.add(id);
+      }
+    }
+    if (!cached) {
+      misses += 1;
+      return undefined;
+    }
+    if (cached.signature !== signature)
+      throw new Error(`Kernel operation cache identity collision: ${id}`);
+    hits += 1;
+    const value = cached.instantiate(cached.value);
+    persist(key, cached.value);
+    touchEntry(id, cached as CacheEntry<unknown>);
+    return {id, value};
+  }
+
+  /** Accept completed work even when cancellation arrived during computation. */
+  function acceptKernelOperation<Value>(
+    key: KernelOperationKey,
+    lifecycle: KernelValueLifecycle<Value>,
+    value: Value,
+  ): void {
+    const existing = entries.get(key.id);
+    if (existing) {
+      if (existing.signature !== key.signature)
+        throw new Error(`Kernel operation cache identity collision: ${key.id}`);
+      touchEntry(key.id, existing);
+      return;
+    }
+    let retained: Value;
+    try {
+      retained = lifecycle.retain(value);
+    } catch (error) {
+      lifecycle.release(value);
+      throw error;
+    }
+    const entry = retainEntry(key, lifecycle, retained);
+    persist(key, retained);
+    touchEntry(key.id, entry as CacheEntry<unknown>);
+  }
+
+  function persist(key: KernelOperationKey, value: unknown): void {
+    if (!store || persisted.has(key.id)) return;
+    accessStore(store => {
+      if (!store.touch(key.id)) {
+        store.set(key.id, encodeKernelArtifact(key.signature, value));
+        persistentWrites += 1;
+      }
+      persisted.add(key.id);
+    });
+  }
+
+  function retainEntry<Value>(
+    key: KernelOperationKey,
+    lifecycle: KernelValueLifecycle<Value>,
+    retained: Value,
+  ): CacheEntry<Value> {
+    const entry: CacheEntry<Value> = {
+      estimatedBytes:
+        256 +
+        estimateRetainedBytes(key.signature) +
+        lifecycle.estimateBytes(retained),
+      signature: key.signature,
+      value: retained,
+      instantiate: lifecycle.instantiate,
+      release: lifecycle.release,
+    };
+    entries.set(key.id, entry as CacheEntry<unknown>);
+    estimatedJavaScriptBytes += entry.estimatedBytes;
+    return entry;
+  }
+
+  function touchEntry(id: string, entry: CacheEntry<unknown>): void {
+    historicalEntries.delete(id);
+    if (currentEvaluation) {
+      currentEvaluation.used.delete(id);
+      currentEvaluation.used.add(id);
+    } else if (!retainedEvaluation.has(id)) {
+      historicalEntries.set(id, entry);
+    }
+    evictHistoricalEntries();
+  }
+
+  function clearKernelOperationCache(): void {
+    for (const entry of entries.values()) {
+      entry.release(entry.value);
+    }
+    entries.clear();
+    historicalEntries.clear();
+    retainedEvaluation.clear();
+    currentEvaluation?.used.clear();
+    hits = 0;
+    misses = 0;
+    estimatedJavaScriptBytes = 0;
+    persistentHits = 0;
+    persistentWrites = 0;
+    persistenceErrors = 0;
+    persisted.clear();
+  }
+
+  function kernelOperationCacheStats() {
+    return {
+      entries: entries.size,
+      hits,
+      misses,
+      historicalEntries: historicalEntries.size,
+      estimatedJavaScriptBytes,
+      nativeAllocatedBytes: nativeAllocatedBytes(),
+      maximumBytes,
+      externalBytes,
+      persistentHits,
+      persistentWrites,
+      persistenceErrors,
+    };
+  }
+
+  function evictHistoricalEntries(): void {
+    while (
+      historicalEntries.size &&
+      nativeAllocatedBytes() + estimatedJavaScriptBytes + externalBytes >
+        maximumBytes
+    ) {
+      const [id, entry] = historicalEntries.entries().next().value!;
+      historicalEntries.delete(id);
+      entries.delete(id);
+      estimatedJavaScriptBytes -= entry.estimatedBytes;
+      entry.release(entry.value);
+    }
+  }
+
+  return {
+    beginKernelOperationEvaluation,
+    evaluateKernelOperation,
+    clearKernelOperationCache,
+    kernelOperationCacheStats,
+    setKernelArtifactStore,
+    findKernelOperation,
+    acceptKernelOperation,
+    setKernelExternalBytes,
+  };
+}
+
+export const {
+  beginKernelOperationEvaluation,
+  evaluateKernelOperation,
+  clearKernelOperationCache,
+  kernelOperationCacheStats,
+  setKernelArtifactStore,
+  findKernelOperation,
+  acceptKernelOperation,
+  setKernelExternalBytes,
+} = createKernelOperationCache({
+  nativeAllocatedBytes: () =>
+    (getOC() as OpenCascadeInstance).Code3dMemory.AllocatedBytes(),
+});
+
+export type KernelOperationKey = Readonly<{id: string; signature: string}>;
+
+export function kernelOperationKey(
+  operation: string,
+  arguments_: readonly KernelKeyPart[],
+  inputs: readonly Pick<KernelArtifact<unknown>, 'id'>[],
+): KernelOperationKey {
+  const signature = JSON.stringify([
+    operation,
+    arguments_,
+    inputs.map(input => input.id),
+  ]);
+  return {id: contentId(signature), signature};
+}
+
+function contentId(value: string): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  let third = 0x85ebca6b;
+  let fourth = 0xc2b2ae35;
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    first = Math.imul(first ^ code, 0x01000193);
+    second = Math.imul(second ^ code, 0x27d4eb2d);
+    third = Math.imul(third ^ code, 0x165667b1);
+    fourth = Math.imul(fourth ^ code, 0x85ebca77);
+  }
+  return [first, second, third, fourth]
+    .map(part => (part >>> 0).toString(16).padStart(8, '0'))
+    .join('');
+}

package/src/library/kernel-shapes.ts

@@ -0,0 +1,135 @@
+import {
+  cast,
+  getOC,
+  type AnyShape,
+  type Edge,
+  type Face,
+  type Shape3D,
+  type Vertex,
+  type Wire,
+} from 'replicad';
+import type {
+  NCollection_List_TopoDS_Shape,
+  TopoDS_Shape,
+  gp_Trsf,
+} from 'replicad-opencascadejs';
+
+export function centeredBoxShape(x: number, y: number, z: number): Shape3D {
+  const oc = getOC();
+  const corner = new oc.gp_Pnt(-x / 2, -y / 2, -z / 2);
+  try {
+    const builder = new oc.BRepPrimAPI_MakeBox(corner, x, y, z);
+    try {
+      return castOwnedShape3D(builder.Shape());
+    } finally {
+      builder.delete();
+    }
+  } finally {
+    corner.delete();
+  }
+}
+
+/** Consumes a raw handle; Replicad's cast creates a separate native handle. */
+export function castOwnedShape(shape: TopoDS_Shape): AnyShape {
+  try {
+    return cast(shape);
+  } finally {
+    shape.delete();
+  }
+}
+
+export function castOwnedShape3D(shape: TopoDS_Shape): Shape3D {
+  const result = castOwnedShape(shape);
+  try {
+    return result.asShape3D();
+  } catch (error) {
+    result.delete();
+    throw error;
+  }
+}
+
+type Subshapes = {vertex: Vertex; edge: Edge; face: Face; wire: Wire};
+
+/** Returns owned, distinct subshapes in kernel traversal order. */
+export function shapeSubshapes<Kind extends keyof Subshapes>(
+  shape: AnyShape,
+  kind: Kind,
+): Subshapes[Kind][] {
+  const oc = getOC();
+  const kinds = {
+    vertex: oc.TopAbs_ShapeEnum.TopAbs_VERTEX,
+    edge: oc.TopAbs_ShapeEnum.TopAbs_EDGE,
+    face: oc.TopAbs_ShapeEnum.TopAbs_FACE,
+    wire: oc.TopAbs_ShapeEnum.TopAbs_WIRE,
+  };
+  const explorer = new oc.TopExp_Explorer(
+    shape.wrapped,
+    kinds[kind],
+    oc.TopAbs_ShapeEnum.TopAbs_SHAPE,
+  );
+  const values: Subshapes[Kind][] = [];
+  try {
+    while (explorer.More()) {
+      const raw = explorer.Current();
+      try {
+        if (!values.some(value => value.wrapped.IsSame(raw))) {
+          values.push(cast(raw) as Subshapes[Kind]);
+        }
+      } finally {
+        // Current() owns a handle even for duplicate topology occurrences.
+        raw.delete();
+      }
+      explorer.Next();
+    }
+    return values;
+  } catch (error) {
+    values.forEach(value => value.delete());
+    throw error;
+  } finally {
+    explorer.delete();
+  }
+}
+
+/** Consumes a native list and transfers its owned element handles to the caller. */
+export function consumeShapeList(
+  list: NCollection_List_TopoDS_Shape,
+): TopoDS_Shape[] {
+  const shapes: TopoDS_Shape[] = [];
+  try {
+    while (!list.IsEmpty()) {
+      shapes.push(list.First());
+      list.RemoveFirst();
+    }
+    return shapes;
+  } catch (error) {
+    shapes.forEach(shape => shape.delete());
+    throw error;
+  } finally {
+    list.delete();
+  }
+}
+
+/** Borrows the input and owns every builder/returned native handle. */
+export function transformShape<Shape extends AnyShape>(
+  source: Shape,
+  configure: (transform: gp_Trsf) => void,
+): Shape {
+  const oc = getOC();
+  const transform = new oc.gp_Trsf();
+  try {
+    configure(transform);
+    const builder = new oc.BRepBuilderAPI_Transform(
+      source.wrapped,
+      transform,
+      true,
+      false,
+    );
+    try {
+      return castOwnedShape(builder.ModifiedShape(source.wrapped)) as Shape;
+    } finally {
+      builder.delete();
+    }
+  } finally {
+    transform.delete();
+  }
+}

package/src/library/loft.ts

@@ -0,0 +1,196 @@
+import {
+  cast,
+  getOC,
+  type AnyShape,
+  type Face,
+  type Wire,
+  type Shape3D,
+} from 'replicad';
+import type {TopoDS_Shape} from 'replicad-opencascadejs';
+import {
+  castOwnedShape,
+  castOwnedShape3D,
+  consumeShapeList,
+  shapeSubshapes,
+} from './kernel-shapes.js';
+import {
+  transferShapeTopology,
+  booleanWithTopology,
+  type TopologyInput,
+  type ShapeTopology,
+} from './topology.js';
+
+export function loftWithTopology(
+  sections: readonly TopologyInput[],
+  spine: Wire | undefined,
+  ruled: boolean,
+): Readonly<{shape: Shape3D; topology: ShapeTopology}> {
+  const holes: Wire[][] = [];
+  let outer: {shape: Shape3D; topology: ShapeTopology} | undefined;
+  let inner: {shape: Shape3D; topology: ShapeTopology} | undefined;
+  try {
+    for (const section of sections) {
+      const boundary = (section.shape as Face).clone().outerWire();
+      try {
+        const wires = shapeSubshapes(section.shape, 'wire');
+        holes.push(
+          wires.filter(wire => {
+            if (!wire.isSame(boundary)) return true;
+            wire.delete();
+            return false;
+          }),
+        );
+      } finally {
+        boundary.delete();
+      }
+    }
+    if (holes.some(wires => wires.length !== holes[0].length))
+      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.',
+      );
+    outer = loftContoursWithTopology(sections, spine, ruled);
+    if (!holes[0].length) {
+      const result = outer;
+      outer = undefined;
+      return result;
+    }
+    inner = loftContoursWithTopology(
+      sections,
+      spine,
+      ruled,
+      holes.map(wires => wires[0]),
+    );
+    return booleanWithTopology(outer, inner, 'cut');
+  } finally {
+    inner?.shape.delete();
+    outer?.shape.delete();
+    holes.flat().forEach(wire => wire.delete());
+  }
+}
+
+function loftContoursWithTopology(
+  sections: readonly TopologyInput[],
+  spine: Wire | undefined,
+  ruled: boolean,
+  holes?: readonly Wire[],
+): Readonly<{shape: Shape3D; topology: ShapeTopology}> {
+  const oc = getOC();
+  const builder = spine
+    ? new oc.BRepOffsetAPI_MakePipeShell(spine.wrapped)
+    : new oc.BRepOffsetAPI_ThruSections(true, ruled, 1e-6);
+  const wires: Wire[] = [];
+  let result: Shape3D | undefined;
+  const caps: (Face | undefined)[] = [];
+  try {
+    for (const [index, section] of sections.entries())
+      wires.push(
+        holes
+          ? holes[index].clone()
+          : (section.shape as Face).clone().outerWire(),
+      );
+    if (builder instanceof oc.BRepOffsetAPI_MakePipeShell) {
+      builder.SetMode(false);
+      for (const wire of wires) builder.Add(wire.wrapped, false, false);
+      if (!builder.IsReady())
+        throw new Error(
+          'The loft sections could not be associated with the spine.',
+        );
+      builder.Build();
+      if (!builder.IsDone() || !builder.MakeSolid())
+        throw new Error('Could not construct a solid loft along the spine.');
+    } else {
+      builder.SetMutableInput(false);
+      for (const wire of wires) builder.AddWire(wire.wrapped);
+      builder.Build();
+    }
+    result = castOwnedShape3D(builder.Shape());
+    caps[0] = castOwnedShape(builder.FirstShape()) as Face;
+    caps[sections.length - 1] = castOwnedShape(builder.LastShape()) as Face;
+    const topology = transferShapeTopology(
+      sections,
+      result,
+      (input, kind, index) => {
+        const cap = caps[index];
+        // The builder consumes wires, so the profile faces need explicit cap history.
+        if (kind === 'surface')
+          return cap && !holes ? [copyShapeHandle(cap.wrapped)] : [];
+        const modified = consumeShapeList(builder.Modified(input));
+        if (!cap && kind === 'vertex') return modified;
+        let generated: TopoDS_Shape[] = [];
+        let capParts: AnyShape[] = [];
+        let source: AnyShape | undefined;
+        try {
+          generated = consumeShapeList(builder.Generated(input));
+          if (cap) capParts = shapeSubshapes(cap, kind);
+          else source = cast(input);
+          // Sweeps generate side faces from edges and side edges from vertices.
+          // Their intersection with this section's cap identifies its descendants,
+          // including splits, without relying on traversal or geometric proximity.
+          for (const raw of generated) {
+            const shape = cast(raw);
+            try {
+              const parts = shapeSubshapes(shape, kind);
+              try {
+                for (const part of capParts) {
+                  if (parts.some(candidate => candidate.isSame(part)))
+                    modified.push(copyShapeHandle(part.wrapped));
+                }
+                // Ruled lofts can copy intermediate profile edges while
+                // retaining their vertices. Generated side faces plus the
+                // exact endpoint identities establish the copied edge history.
+                if (source)
+                  for (const part of parts)
+                    if (sameVertices(source, part))
+                      modified.push(copyShapeHandle(part.wrapped));
+              } finally {
+                parts.forEach(part => part.delete());
+              }
+            } finally {
+              shape.delete();
+            }
+          }
+          return modified;
+        } catch (error) {
+          modified.forEach(shape => shape.delete());
+          throw error;
+        } finally {
+          generated.forEach(shape => shape.delete());
+          capParts.forEach(part => part.delete());
+          source?.delete();
+        }
+      },
+    );
+    return {shape: result, topology};
+  } catch (error) {
+    result?.delete();
+    throw error;
+  } finally {
+    caps.forEach(cap => cap?.delete());
+    wires.forEach(wire => wire.delete());
+    builder.delete();
+  }
+}
+
+function copyShapeHandle(shape: TopoDS_Shape): TopoDS_Shape {
+  return shape.Oriented(shape.Orientation());
+}
+
+function sameVertices(left: AnyShape, right: AnyShape): boolean {
+  const leftVertices = shapeSubshapes(left, 'vertex');
+  let rightVertices: AnyShape[] = [];
+  try {
+    rightVertices = shapeSubshapes(right, 'vertex');
+    return (
+      leftVertices.length > 0 &&
+      leftVertices.length === rightVertices.length &&
+      leftVertices.every(vertex =>
+        rightVertices.some(candidate => candidate.isSame(vertex)),
+      )
+    );
+  } finally {
+    leftVertices.forEach(vertex => vertex.delete());
+    rightVertices.forEach(vertex => vertex.delete());
+  }
+}