@hatiolab/figure-model 0.1.32 → 0.1.34

package/dist/v3-driver.js

@@ -0,0 +1,145 @@
+/*
+ * Copyright © HatioLab Inc. All rights reserved.
+ */
+/*
+ * Drivers: time → state value (docs/v3-motion-contract.md).
+ *
+ * This is the one place interpolation, looping and phase normalisation are written. things-scene, a thumbnail
+ * renderer and a test all call `driverValue`; none of them reimplements it. The kernel itself never reads time:
+ * the consumer takes the value this returns and passes it as a state override to `compileV3Asset(...).evaluate`.
+ *
+ * Continuous rotation is two numbers, an accumulated angle and a phase. Keys hold the accumulated angle; the
+ * interpolation happens on it; only then is the result wrapped into [-180°, 180°) for the kernel. Wrapping the
+ * keys first would make 350° → 370° turn the wrong way.
+ */
+import { V3ContractError } from "./v3-contract.js";
+const fail = (code, path, detail) => {
+    throw new V3ContractError(code, path, detail);
+};
+/** The inputs a driver may write, with their units: the asset's state inputs. */
+function stateUnits(asset) {
+    return new Map(asset.document.model.inputs.filter(i => i.role === 'state').map(i => [i.id, i.unit]));
+}
+/** Refuses a driver list the contract does not allow. Called by `compileV3Asset`. */
+export function validateV3Drivers(asset) {
+    const drivers = asset.drivers;
+    if (drivers === undefined)
+        return;
+    if (!Array.isArray(drivers))
+        fail('DRIVER', 'drivers', 'array required');
+    const states = stateUnits(asset);
+    const seenIds = new Set();
+    const seenStates = new Set();
+    for (const d of drivers) {
+        const path = `drivers.${String(d?.id ?? '?')}`;
+        const keysOf = (o) => (o && typeof o === 'object' ? Object.keys(o).sort() : null);
+        if (JSON.stringify(keysOf(d)) !== JSON.stringify(['accumulates', 'id', 'interpolation', 'keys', 'loop', 'state', 'time']))
+            fail('DRIVER', path, 'exactly id, state, time, keys, interpolation, loop, accumulates required');
+        if (typeof d.id !== 'string' || !d.id.trim())
+            fail('DRIVER', path, 'id required');
+        if (seenIds.has(d.id))
+            fail('DRIVER', path, 'duplicate driver id');
+        seenIds.add(d.id);
+        if (!states.has(d.state))
+            fail('DRIVER_STATE', path, `${String(d.state)} is not a state input of this asset`);
+        if (seenStates.has(d.state))
+            fail('DRIVER_STATE', path, `two drivers write ${d.state}; one writer per state`);
+        seenStates.add(d.state);
+        if (JSON.stringify(keysOf(d.time)) !== JSON.stringify(['duration', 'unit']) || d.time.unit !== 's')
+            fail('DRIVER_TIME', path, 'time must be { unit: "s", duration }');
+        if (!(Number.isFinite(d.time.duration) && d.time.duration > 0))
+            fail('DRIVER_TIME', path, 'positive duration in seconds required');
+        if (!Array.isArray(d.keys) || d.keys.length < 2)
+            fail('DRIVER_KEYS', path, 'at least two keys required');
+        let last = -Infinity;
+        for (const k of d.keys) {
+            if (JSON.stringify(keysOf(k)) !== JSON.stringify(['at', 'value']))
+                fail('DRIVER_KEYS', path, 'a key is { at, value }');
+            if (!(Number.isFinite(k.at) && k.at >= 0 && k.at <= 1))
+                fail('DRIVER_KEYS', path, 'key at must be a fraction of the duration in [0, 1]');
+            if (!(k.at > last))
+                fail('DRIVER_KEYS', path, 'key at values must strictly increase');
+            last = k.at;
+            if (!Number.isFinite(k.value))
+                fail('DRIVER_KEYS', path, 'finite key value required');
+        }
+        if (d.keys[0].at !== 0)
+            fail('DRIVER_KEYS', path, 'the first key is at 0');
+        if (!['linear', 'step'].includes(d.interpolation))
+            fail('DRIVER', path, 'interpolation is linear or step');
+        if (!['wrap', 'hold'].includes(d.loop))
+            fail('DRIVER', path, 'loop is wrap or hold');
+        if (typeof d.accumulates !== 'boolean')
+            fail('DRIVER', path, 'accumulates must be a boolean');
+        const unit = states.get(d.state);
+        if (d.accumulates && unit !== 'deg' && unit !== 'rad')
+            fail('DRIVER_STATE', path, `an accumulating driver writes an angle; ${d.state} is in ${unit}`);
+    }
+}
+/** Reads the keys at a fraction of the duration in [0, 1]. Outside the keys' span, holds the end value. */
+function sampleKeys(driver, fraction) {
+    const keys = driver.keys;
+    if (fraction <= keys[0].at)
+        return keys[0].value;
+    const last = keys[keys.length - 1];
+    if (fraction >= last.at)
+        return last.value;
+    let i = 0;
+    while (i < keys.length - 2 && keys[i + 1].at <= fraction)
+        i++;
+    const from = keys[i], to = keys[i + 1];
+    if (driver.interpolation === 'step')
+        return from.value;
+    const span = to.at - from.at;
+    return from.value + ((fraction - from.at) / span) * (to.value - from.value);
+}
+/** Wraps an angle into [-half, half) for the unit: half is 180 for degrees, π for radians. */
+export function normalisePhase(value, unit) {
+    const full = unit === 'deg' ? 360 : Math.PI * 2;
+    const half = full / 2;
+    const wrapped = ((((value + half) % full) + full) % full) - half;
+    return wrapped === half ? -half : wrapped;
+}
+/**
+ * The state value a driver writes at a time in seconds. Time before 0 reads as 0.
+ * Interpolation first, then the loop, then (for an accumulating driver) the phase. Never the other order.
+ */
+export function driverValue(driver, timeSeconds, unit = 'other') {
+    if (!Number.isFinite(timeSeconds))
+        fail('DRIVER_TIME', driver.id, 'finite time required');
+    const t = Math.max(0, timeSeconds);
+    const duration = driver.time.duration;
+    const first = driver.keys[0].value, lastKey = driver.keys[driver.keys.length - 1];
+    let value;
+    if (driver.loop === 'hold') {
+        value = sampleKeys(driver, Math.min(t / duration, 1));
+    }
+    else {
+        const periods = Math.floor(t / duration);
+        const within = t - periods * duration;
+        value = sampleKeys(driver, within / duration);
+        // A wrapping accumulating driver keeps adding each period's travel, so a roller keeps turning.
+        if (driver.accumulates)
+            value += periods * (lastKey.value - first);
+    }
+    if (driver.accumulates) {
+        if (unit === 'deg' || unit === 'rad')
+            return normalisePhase(value, unit);
+        return fail('DRIVER_STATE', driver.id, 'an accumulating driver needs an angle unit');
+    }
+    return value;
+}
+/**
+ * Every driven state at one time, ready to pass as state overrides. The consumer chooses, per state, whether
+ * the driver or an external input is the active control source; this returns the drivers' side only.
+ */
+export function driverStates(asset, timeSeconds) {
+    const units = stateUnits(asset);
+    const out = {};
+    for (const d of asset.drivers ?? []) {
+        const unit = units.get(d.state);
+        out[d.state] = driverValue(d, timeSeconds, unit === 'deg' || unit === 'rad' ? unit : 'other');
+    }
+    return out;
+}
+//# sourceMappingURL=v3-driver.js.map

package/dist/v3-driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3-driver.js","sourceRoot":"","sources":["../src/v3-driver.ts"],"names":[],"mappings":"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"}

package/dist/v3-from-v2.d.ts

@@ -0,0 +1,116 @@
+import { type V3WorldBox } from './v3-gate.ts';
+import { type InstanceScale } from './sizing.ts';
+import type { AnimationChannel, Axis, FigureSource, Vec3 } from './types.ts';
+import type { V3Asset } from './v3-asset-types.ts';
+/** A rule the converter cannot write in V3. The asset is not converted. */
+export interface V3ConversionRefusal {
+    code: string;
+    part?: string;
+    detail: string;
+}
+/** Something the V3 asset does not carry over from the V2 source. Listed, never dropped quietly. */
+export interface V3ConversionLoss {
+    code: string;
+    part?: string;
+    detail: string;
+}
+/**
+ * Something the converter normalised on purpose, with the value before and after. Not a loss: the V3 asset draws
+ * what V2 drew. The report keeps it so nobody has to rediscover why a number differs from the source.
+ */
+export interface V3ConversionNote {
+    code: string;
+    part?: string;
+    detail: string;
+}
+export type V3ConversionResult = {
+    status: 'converted';
+    asset: V3Asset;
+    lost: V3ConversionLoss[];
+    notes: V3ConversionNote[];
+} | {
+    status: 'refused';
+    refusals: V3ConversionRefusal[];
+    lost: V3ConversionLoss[];
+    notes: V3ConversionNote[];
+};
+export interface V3ConversionOptions {
+    /** Colour of every palette token the source uses. The converter invents no colours. */
+    palette: Record<string, string>;
+    /** What that palette is called, for the report (ADR-0087 ruling 5). Without it the report carries a hash. */
+    paletteId?: string;
+    /** Asset name. Defaults to the V2 `type`. */
+    name?: string;
+}
+/** A short stable fingerprint of the palette, so a report can say which colours it snapshotted. */
+export declare function paletteHash(palette: Record<string, string>): string;
+/** The V3 design inputs that stand for the instance size, in mm. */
+export declare const V3_SIZE_INPUTS: Readonly<Record<Axis, string>>;
+/** Rx·Ry·Rz for degrees, the order V2 (`three` 'XYZ') and V3 `rigid@1` share. */
+export declare function eulerXYZ(rotation: Partial<Vec3> | undefined): number[][];
+/**
+ * Convert one validated V2 source to a V3 asset that places every part where V2 places it, at every
+ * instance size in the input range. See the file comment for what is refused and what is listed as lost.
+ */
+export declare function convertV2ToV3(source: unknown, options: V3ConversionOptions): V3ConversionResult;
+/** One placed body in the world, from either side, in the bottom-origin asset frame. */
+export type WorldBox = V3WorldBox;
+/** Values that move a V2 figure: parameter values by name and, per animation clip, an elapsed time in seconds. */
+export interface V2MotionState {
+    parameters?: Record<string, number>;
+    clipTime?: Record<string, number>;
+}
+type Mat = number[][];
+/** Rotation about a unit axis by degrees (Rodrigues), the matrix three's setFromAxisAngle builds. */
+export declare function axisAngle(axis: Vec3, deg: number): Mat;
+/** V2's clip length: the last key time across its channels, in seconds. */
+export declare function v2ClipDuration(clip: {
+    channels: AnimationChannel[];
+}): number;
+/**
+ * Where V2 draws every part (and copy) at an instance scale and a motion state, as oriented world boxes.
+ * Motion follows things-scene: a translation channel shifts the part in the figure frame by the part's world
+ * factor; a rotation channel turns it about its own centre in its own frame (R_part·R_ch·R_part⁻¹); a joint turns
+ * everything in its frame about its sized origin, parents first (ADR-0066).
+ */
+export declare function v2WorldBoxes(source: FigureSource, scale: InstanceScale, state?: V2MotionState): WorldBox[];
+/** Where a converted V3 asset draws every part at an instance size, as world boxes. */
+export declare function v3WorldBoxes(asset: V3Asset, size: Vec3, stateOverrides?: Record<string, number>): WorldBox[];
+export interface V3SameDifference {
+    part: string;
+    scale: InstanceScale;
+    /** Which motion state was being compared; `rest` when none. */
+    state: string;
+    what: string;
+    v2: string;
+    v3: string;
+}
+export interface V3SameReport {
+    same: boolean;
+    /** Instance scales checked: the base and every combination of doubled axes. */
+    scales: InstanceScale[];
+    /** Motion states checked; `rest` is always first. */
+    states: string[];
+    boxesCompared: number;
+    differences: V3SameDifference[];
+}
+/** ADR-0087 decision 2 tolerances. */
+export declare const SAME_TOLERANCE_MM = 1;
+export declare const SAME_TOLERANCE_DEG = 0.1;
+export interface V3CompareOptions {
+    factor?: number;
+    /** Motion states to compare beyond rest, each with a label for the report. */
+    states?: Array<{
+        label: string;
+    } & V2MotionState>;
+}
+/** The V3 state overrides that stand for a V2 motion state: parameters by name, drivers at their clip's time. */
+export declare function v3StateOverrides(asset: V3Asset, state: V2MotionState): Record<string, number>;
+/**
+ * "The same" (ADR-0087 decision 2): the V2 source and the V3 asset draw the same parts, each with the same
+ * centre and local dimensions within 1 mm and the same rotation within 0.1° (as a relative angle), with the same
+ * material, at the base size and at every combination of doubled axes, at rest and at every motion state given.
+ */
+export declare function compareV2WithV3(source: FigureSource, asset: V3Asset, options?: V3CompareOptions | number): V3SameReport;
+export {};
+//# sourceMappingURL=v3-from-v2.d.ts.map

package/dist/v3-from-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v3-from-v2.d.ts","sourceRoot":"","sources":["../src/v3-from-v2.ts"],"names":[],"mappings":"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"}