@code3d/core 0.0.1-alpha.4 → 0.0.1-alpha.7

package/src/library/index.ts

@@ -1,5 +1,5 @@
-export {cached} from './cached.js';
-export type {CachedOptions} from './cached.js';
+export {cache} from './cached.js';
+export type {CacheOptions} from './cached.js';
 export {font, googleFont} from './font.js';
 export type {Font} from './font.js';
 export type {GoogleFontOptions} from './google-font.js';
@@ -16,6 +16,13 @@ export type {
 } from './sketch.js';
 
 export {
+  offset,
+  rotate,
+  pivot,
+  pivotVertex,
+  pivotPoint,
+  axisEdge,
+  axisLine,
   arc,
   bezier,
   box,
@@ -45,8 +52,12 @@ export type {
   Anchor,
   Bound,
   DirectionalBounds,
-  ConstraintPivotChain,
-  ConstraintAroundChain,
+  PivotChain,
+  PivotRotation,
+  AxisRotation,
+  AxisChain,
+  Transformation,
+  Relation,
   CanonicalElements,
   Constraint,
   CurveElements,

package/src/library/kernel-cache.ts

@@ -40,6 +40,7 @@ export type KernelValueLifecycle<Value> = Readonly<{
 }>;
 
 type CacheEntry<Value> = Readonly<{
+  persistenceEligible: boolean;
   estimatedBytes: number;
   signature: string;
   value: Value;
@@ -49,9 +50,11 @@ type CacheEntry<Value> = Readonly<{
 
 export function createComputationCache({
   maximumBytes = 2 * 1024 ** 3,
+  minimumPersistenceMilliseconds = 1,
   nativeAllocatedBytes,
 }: {
   maximumBytes?: number;
+  minimumPersistenceMilliseconds?: number;
   nativeAllocatedBytes: () => number;
 }) {
   const entries = new Map<string, CacheEntry<unknown>>();
@@ -71,6 +74,17 @@ export function createComputationCache({
   const pendingPersistence = new Map<string, () => Uint8Array>();
   let externalBytes = 0;
 
+  /** Adjust historical retention without invalidating the current model. */
+  function setKernelCacheBudget(bytes: number): void {
+    maximumBytes = bytes;
+    evictHistoricalEntries();
+  }
+
+  /** Apply to future computations without changing existing entries' admission. */
+  function setKernelCachePersistenceThreshold(milliseconds: number): void {
+    minimumPersistenceMilliseconds = milliseconds;
+  }
+
   /** The host accounts for in-flight inputs and all auxiliary native heaps. */
   function setKernelExternalBytes(bytes: number): void {
     externalBytes = bytes;
@@ -128,8 +142,10 @@ export function createComputationCache({
   ): KernelArtifact<Value> {
     const hit = findKernelOperation(key, lifecycle, codec);
     if (hit) return hit;
+    const started = performance.now();
     const value = compute();
-    acceptKernelOperation(key, lifecycle, value, codec);
+    const milliseconds = performance.now() - started;
+    acceptKernelOperation(key, lifecycle, value, milliseconds, codec);
     return {id: key.id, value};
   }
 
@@ -185,7 +201,9 @@ export function createComputationCache({
           misses += 1;
           return undefined;
         }
-        cached = retainEntry(key, lifecycle, restored);
+        // Existing disk records have already been admitted; reading one must
+        // not reinterpret decode time as its original computation cost.
+        cached = retainEntry(key, lifecycle, restored, true);
         persistentHits += 1;
         persisted.add(id);
       }
@@ -198,7 +216,8 @@ export function createComputationCache({
       throw new Error(`Kernel operation cache identity collision: ${id}`);
     hits += 1;
     const value = cached.instantiate(cached.value);
-    if (codec !== false) persist(key, cached.value, codec, true);
+    if (cached.persistenceEligible && codec !== false)
+      persist(key, cached.value, codec, true);
     touchEntry(id, cached as CacheEntry<unknown>);
     return {id, value};
   }
@@ -208,6 +227,7 @@ export function createComputationCache({
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
     value: Value,
+    milliseconds: number,
     codec?: CacheCodec<Value> | false,
   ): void {
     const existing = entries.get(key.id);
@@ -224,8 +244,14 @@ export function createComputationCache({
       lifecycle.release(value);
       throw error;
     }
-    const entry = retainEntry(key, lifecycle, retained);
-    if (codec !== false) persist(key, retained, codec);
+    const entry = retainEntry(
+      key,
+      lifecycle,
+      retained,
+      milliseconds >= minimumPersistenceMilliseconds,
+    );
+    if (entry.persistenceEligible && codec !== false)
+      persist(key, retained, codec);
     touchEntry(key.id, entry as CacheEntry<unknown>);
   }
 
@@ -282,8 +308,10 @@ export function createComputationCache({
     key: KernelOperationKey,
     lifecycle: KernelValueLifecycle<Value>,
     retained: Value,
+    persistenceEligible: boolean,
   ): CacheEntry<Value> {
     const entry: CacheEntry<Value> = {
+      persistenceEligible,
       estimatedBytes:
         256 +
         estimateRetainedBytes(key.signature) +
@@ -368,6 +396,8 @@ export function createComputationCache({
     beginKernelOperationEvaluation,
     clearKernelOperationCache,
     kernelOperationCacheStats,
+    setKernelCacheBudget,
+    setKernelCachePersistenceThreshold,
     setKernelArtifactStore,
     findKernelOperation,
     findKernelOperations,
@@ -388,6 +418,8 @@ export const {
   beginKernelOperationEvaluation,
   clearKernelOperationCache,
   kernelOperationCacheStats,
+  setKernelCacheBudget,
+  setKernelCachePersistenceThreshold,
   setKernelArtifactStore,
   findKernelOperation,
   findKernelOperations,

package/src/library/relation-solver.ts

@@ -1,8 +1,10 @@
 import {
   axisRotation,
+  externalRotationFrame,
   solveBodies as solveBoundBodies,
   type BodyRelation as BoundRelation,
-  type BodyRotation,
+  type BodyAction,
+  solveTranslations,
 } from './bound-solver.js';
 import {
   alignmentResidual,
@@ -24,16 +26,14 @@ import {
   composeTransforms,
   identityRigidTransform,
   invertTransform,
-  origin,
   rotateVector,
   rotation,
-  translation,
   type Quaternion,
   type RigidTransform,
   type Vec3,
 } from './spatial.js';
 
-export {axisRotation, type BodyRotation};
+export {axisRotation, type BodyAction};
 type AlignEndpoint = Readonly<{
   body: number;
   geometry: AlignmentGeometry;
@@ -44,76 +44,70 @@ type AlignRelation = Readonly<{
   id: string;
   source: AlignEndpoint;
   target: AlignEndpoint;
-  offset: Vec3 | undefined;
-  rotations: readonly BodyRotation[];
 }>;
 type Relation = (BoundRelation & {kind: 'on'}) | AlignRelation;
-export type Body = Readonly<{name: string; relations: readonly Relation[]}>;
+export type Body = Readonly<{
+  name: string;
+  relations: readonly Relation[];
+  initial?: RigidTransform;
+  transformations?: readonly BodyAction[];
+}>;
 
-/** Authored actions apply after satisfying the relation, about self or an external axis. */
-export function beforeRelation(
+function applyExternalRotation(
   pose: RigidTransform,
-  relation: Pick<Relation, 'kind' | 'rotations' | 'offset' | 'target'>,
+  action: Exclude<BodyAction, {offset: Vec3} | {local: RigidTransform}>,
+  reference: RigidTransform,
+  inverse = false,
+): RigidTransform {
+  const {center, quaternion} = externalRotationFrame(
+    action,
+    pose.quaternion,
+    reference.quaternion,
+    inverse,
+  );
+  const point = addVectors(reference.position, center);
+  return composeTransforms(
+    {quaternion, position: subtract(point, rotateVector(point, quaternion))},
+    pose,
+  );
+}
+
+/** Undo exactly the authored prefix, in reverse call order. */
+export function beforeTransformations(
+  pose: RigidTransform,
+  relation: {
+    actions: readonly BodyAction[];
+  },
   poses: readonly RigidTransform[],
-  owner: number,
 ): RigidTransform {
-  for (const action of [...relation.rotations].reverse())
-    pose =
-      'local' in action
-        ? composeTransforms(pose, invertTransform(action.local))
-        : composeTransforms(
-            axisRotation(
-              composeTransforms(poses[action.body], action.axis),
-              -action.angle,
-            ),
-            pose,
-          );
-  if (relation.kind === 'align' && relation.offset) {
-    const target =
-      relation.target.body === owner ? pose : poses[relation.target.body];
-    const frame = composeTransforms(target, relation.target.transform);
-    pose = {
-      ...pose,
-      position: subtract(
-        pose.position,
-        rotateVector(relation.offset, frame.quaternion),
-      ),
-    };
+  for (const action of [...relation.actions].reverse()) {
+    if ('offset' in action) {
+      pose = {...pose, position: subtract(pose.position, action.offset)};
+    } else
+      pose =
+        'local' in action
+          ? composeTransforms(pose, invertTransform(action.local))
+          : applyExternalRotation(pose, action, poses[action.body], true);
   }
   return pose;
 }
 
-function afterRelation(
+export function afterTransformations(
   pose: RigidTransform,
-  relation: Relation,
+  relation: {
+    actions: readonly BodyAction[];
+  },
   poses: readonly RigidTransform[],
-  owner: number,
 ): RigidTransform {
-  if (relation.kind === 'align' && relation.offset) {
-    const target =
-      relation.target.body === owner ? pose : poses[relation.target.body];
-    pose = {
-      ...pose,
-      position: addVectors(
-        pose.position,
-        rotateVector(
-          relation.offset,
-          composeTransforms(target, relation.target.transform).quaternion,
-        ),
-      ),
-    };
+  for (const action of relation.actions) {
+    if ('offset' in action) {
+      pose = {...pose, position: addVectors(pose.position, action.offset)};
+    } else
+      pose =
+        'local' in action
+          ? composeTransforms(pose, action.local)
+          : applyExternalRotation(pose, action, poses[action.body]);
   }
-  for (const action of relation.rotations)
-    pose =
-      'local' in action
-        ? composeTransforms(pose, action.local)
-        : composeTransforms(
-            axisRotation(
-              composeTransforms(poses[action.body], action.axis),
-              action.angle,
-            ),
-            pose,
-          );
   return pose;
 }
 
@@ -271,8 +265,33 @@ export function solveBodies(
       if (relation.kind === 'align')
         validateAlignment(relation.source.geometry, relation.target.geometry);
   const active = bodies.flatMap((body, i) =>
-    body.relations.length ? [i] : [],
+    body.relations.length || body.transformations?.length ? [i] : [],
   );
+  const unplace = (
+    pose: RigidTransform,
+    owner: number,
+    poses: readonly RigidTransform[],
+  ) =>
+    beforeTransformations(
+      pose,
+      {actions: bodies[owner].transformations ?? []},
+      poses,
+    );
+  const place = (
+    pose: RigidTransform,
+    owner: number,
+    poses: readonly RigidTransform[],
+  ) =>
+    afterTransformations(
+      pose,
+      {actions: bodies[owner].transformations ?? []},
+      poses,
+    );
+  const baselinePose = (
+    pose: RigidTransform,
+    poses: readonly RigidTransform[],
+    owner: number,
+  ) => unplace(pose, owner, poses);
   const flexible = bodies.map(body =>
     body.relations.some(r => r.kind === 'align'),
   );
@@ -287,31 +306,13 @@ export function solveBodies(
   ]
     .sort(([a], [b]) => a.localeCompare(b))
     .map(([, entry]) => entry);
-  let poses = bodies.map(() => identityRigidTransform);
-  for (const owner of active) {
-    const authored =
-      unique.find(
-        entry => entry.owner === owner && entry.relation.rotations.length,
-      )?.relation ??
-      unique.find(
-        entry =>
-          entry.owner === owner &&
-          entry.relation.kind === 'align' &&
-          entry.relation.offset,
-      )?.relation;
-    if (authored)
-      poses[owner] = afterRelation(
-        identityRigidTransform,
-        authored,
-        poses,
-        owner,
-      );
-  }
+  let poses = bodies.map(body => body.initial ?? identityRigidTransform);
+  for (const owner of active) poses[owner] = place(poses[owner], owner, poses);
   for (const {owner, relation} of unique) {
     if (relation.kind !== 'align') continue;
     const sourceSelf = relation.source.body === owner;
     if (relation.target.body === relation.source.body) continue;
-    const baseline = beforeRelation(poses[owner], relation, poses, owner);
+    const baseline = baselinePose(poses[owner], poses, owner);
     const source = transformGeometry(
         relation.source.geometry,
         relation.source.body === owner ? baseline : poses[relation.source.body],
@@ -323,12 +324,7 @@ export function solveBodies(
     const seed = sourceSelf
       ? alignmentSeed(source, target)
       : alignmentSeed(target, source);
-    poses[owner] = afterRelation(
-      composeTransforms(seed, baseline),
-      relation,
-      poses,
-      owner,
-    );
+    poses[owner] = place(composeTransforms(seed, baseline), owner, poses);
   }
   const geometryScale = Math.max(
     1,
@@ -340,12 +336,25 @@ export function solveBodies(
         : [],
     ),
   );
-  const variables = active.flatMap(body =>
-    Array.from({length: 6}, (_, axis) => ({body, axis})),
+  const fullVariables = active.flatMap(body =>
+    // Bound-only bodies without authored rotations have exactly identity
+    // orientation. Do not numerically perturb those fixed axes: native bound
+    // queries can introduce noise that prevents convergence at the identity.
+    Array.from(
+      {
+        length:
+          flexible[body] ||
+          bodies[body].transformations?.some(action => !('offset' in action))
+            ? 6
+            : 3,
+      },
+      (_, axis) => ({body, axis}),
+    ),
   );
+  let variables = fullVariables.filter(variable => variable.axis < 3);
   const residual = (candidate: readonly RigidTransform[]): number[] => [
     ...unique.flatMap(({owner, relation: r}) => {
-      const baseline = beforeRelation(candidate[owner], r, candidate, owner);
+      const baseline = baselinePose(candidate[owner], candidate, owner);
       const source =
           r.source.body === owner ? baseline : candidate[r.source.body],
         target = r.target.body === owner ? baseline : candidate[r.target.body];
@@ -369,29 +378,28 @@ export function solveBodies(
         source.position,
         rotateVector(center, frame.quaternion),
       );
-      const b = composeTransforms(
-        frame,
-        translation(r.offset ?? origin),
-      ).position;
+      const b = frame.position;
       const delta = rotateVector(
         subtract(a, b),
         invertTransform(frame).quaternion,
       );
-      return r.offset ? [...delta] : [delta[1]];
+      return [delta[1]];
     }),
     ...active.flatMap(owner => {
       if (flexible[owner]) return [];
-      const rotations = bodies[owner].relations.filter(r => r.rotations.length);
-      return rotations.length
-        ? rotations.flatMap(r =>
-            beforeRelation(
-              candidate[owner],
-              r,
-              candidate,
-              owner,
-            ).quaternion.slice(0, 3),
-          )
-        : candidate[owner].quaternion.slice(0, 3);
+      const initial = bodies[owner].initial ?? identityRigidTransform;
+      const unplaced = unplace(candidate[owner], owner, candidate);
+      const orientationResidual = (pose: RigidTransform) =>
+        composeTransforms(
+          invertTransform(rotation(initial.quaternion)),
+          rotation(pose.quaternion),
+        ).quaternion.slice(0, 3);
+      return [
+        ...(bodies[owner].relations.length
+          ? []
+          : subtract(unplaced.position, initial.position)),
+        ...orientationResidual(unplaced),
+      ];
     }),
   ];
   const perturb = (
@@ -420,12 +428,80 @@ export function solveBodies(
       };
     });
   };
+  // Restore bound-only bodies' free translations without breaking alignments to
+  // dependent bodies. Every active translation participates in the nullspace;
+  // only bound-only bodies contribute preferences for their incoming pose.
+  const settleBoundTranslations = (): readonly RigidTransform[] => {
+    if (!active.some(owner => !flexible[owner])) return poses;
+    const free = active.flatMap(body => [0, 1, 2].map(axis => ({body, axis})));
+    if (!free.length) return poses;
+    const shift = (steps: readonly number[]) => {
+      const result = poses.map(pose => ({
+        ...pose,
+        position: [...pose.position] as [number, number, number],
+      }));
+      free.forEach(({body, axis}, i) => {
+        result[body].position[axis] += steps[i];
+      });
+      return result;
+    };
+    const preferences = (candidate: readonly RigidTransform[]) =>
+      unique
+        .filter(({owner}) => !flexible[owner])
+        .flatMap(({owner}) =>
+          subtract(
+            baselinePose(candidate[owner], candidate, owner).position,
+            bodies[owner].initial?.position ?? [0, 0, 0],
+          ),
+        );
+    const h = 1e-5;
+    const initial = residual(poses),
+      preference = preferences(poses);
+    const columns = free.map((_, i) => {
+      const plus = shift(free.map((_, j) => (i === j ? h : 0)));
+      const minus = shift(free.map((_, j) => (i === j ? -h : 0)));
+      const a = residual(plus),
+        b = residual(minus),
+        p = preferences(plus),
+        q = preferences(minus);
+      return {
+        constraints: a.map((v, j) => (v - b[j]) / (2 * h)),
+        preferences: p.map((v, j) => (v - q[j]) / (2 * h)),
+      };
+    });
+    const step = solveTranslations(
+      initial.map((value, i) => ({
+        id: 'bound translation',
+        value: -value,
+        coefficients: columns.map(column => column.constraints[i]),
+      })),
+      preference.map((value, i) => ({
+        id: 'pre-action position',
+        value: -value,
+        coefficients: columns.map(column => column.preferences[i]),
+      })),
+      free.length,
+    );
+    const candidate = shift(step);
+    // A nonlinear geometric locus need not admit its linearized free step.
+    // Preserve the valid geometric solution when that direction is not free.
+    return residual(candidate).every(value => Math.abs(value) < 1e-8)
+      ? candidate
+      : poses;
+  };
   let values = residual(poses),
     damping = 1e-5;
   const norm = (values: readonly number[]) =>
     values.reduce((sum, x) => sum + x * x, 0);
-  for (let iteration = 0; iteration < 160; iteration++) {
-    if (values.every(v => Math.abs(v) < 1e-8)) return poses;
+  for (let iteration = 0; iteration < 168; iteration++) {
+    // First settle translation along the seeded orientations. This prevents
+    // unconstrained rotations from tilting a contact chain merely to move it.
+    // Relations that genuinely require rotation then use the full rigid solve.
+    if (iteration === 8) {
+      variables = fullVariables;
+      damping = 1e-5;
+    }
+    if (values.every(v => Math.abs(v) < 1e-8)) return settleBoundTranslations();
     const h = 1e-6;
     const columns = variables.map((_, i) => {
       const shifted = residual(
@@ -434,7 +510,15 @@ export function solveBodies(
           variables.map((_, j) => (i === j ? h : 0)),
         ),
       );
-      return values.map((v, j) => (shifted[j] - v) / h);
+      const opposite = residual(
+        perturb(
+          poses,
+          variables.map((_, j) => (i === j ? -h : 0)),
+        ),
+      );
+      // A directional bound has a cusp at an axis-aligned pose. A forward
+      // difference invents a rotation gradient there; use both sides.
+      return values.map((_, j) => (shifted[j] - opposite[j]) / (2 * h));
     });
     const multiply = (a: readonly number[], b: readonly number[]) =>
       a.reduce((sum, x, i) => sum + x * b[i], 0);