@hatiolab/figure-model 0.1.33 → 0.1.35

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

@@ -1,6 +1,6 @@
 import { type V3WorldBox } from './v3-gate.ts';
 import { type InstanceScale } from './sizing.ts';
-import type { Axis, FigureSource, Vec3 } from './types.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 {
@@ -14,21 +14,62 @@ export interface V3ConversionLoss {
     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;
+}
+/**
+ * How the V3 asset was produced: written by the converter from the V2 rules, or re-authored by a person
+ * (ADR-0087 ruling 1). This says nothing about whether it matches or what was lost; those are `compareV2WithV3`
+ * and `lost` / `rangeChanges` (designer's ruling, 2026-09-22: method, verification and preservation are three
+ * separate facts).
+ */
+export type V3ConversionMethod = 'mechanical' | 're-authored';
+/**
+ * A change to the range of inputs the asset accepts, compared with V2. This is a behaviour-contract change, not a
+ * remark: an instance V2 drew (however badly) is one V3 refuses.
+ */
+export interface V3RangeChange {
+    input: string;
+    /** What V2 accepted, in words. */
+    v2: string;
+    /** The V3 input range. */
+    v3: {
+        min: number;
+        max: number;
+    };
+    part?: string;
+    reason: string;
+}
 export type V3ConversionResult = {
     status: 'converted';
+    method: V3ConversionMethod;
     asset: V3Asset;
     lost: V3ConversionLoss[];
+    rangeChanges: V3RangeChange[];
+    notes: V3ConversionNote[];
 } | {
     status: 'refused';
     refusals: V3ConversionRefusal[];
     lost: V3ConversionLoss[];
+    rangeChanges: V3RangeChange[];
+    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. */
@@ -40,31 +81,90 @@ export declare function eulerXYZ(rotation: Partial<Vec3> | undefined): number[][
 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;
-/** Where V2 draws every part (and copy) at an instance scale, as world boxes. */
-export declare function v2WorldBoxes(source: FigureSource, scale: InstanceScale): WorldBox[];
+/** 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, options?: {
+    points?: boolean;
+}): WorldBox[];
 /** Where a converted V3 asset draws every part at an instance size, as world boxes. */
-export declare function v3WorldBoxes(asset: V3Asset, size: Vec3): WorldBox[];
+export declare function v3WorldBoxes(asset: V3Asset, size: Vec3, stateOverrides?: Record<string, number>, options?: {
+    points?: boolean;
+}): WorldBox[];
+/**
+ * Instance scales at which a repeated part's copy count changes, one just below and one just above each
+ * boundary near the base count (completion criterion: repeat-count boundaries).
+ */
+export declare function repeatBoundaryScales(source: FigureSource): InstanceScale[];
 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 {
+    /** True when no difference was found over the checked scales and states. Not a guarantee over all inputs. */
     same: boolean;
-    /** Instance scales checked: the base and every combination of doubled axes. */
+    /** Instance scales checked. */
     scales: InstanceScale[];
+    /** Motion states checked; `rest` is always first. */
+    states: string[];
     boxesCompared: number;
+    /**
+     * How the surfaces were sampled, so the report says what a Hausdorff gap under tolerance does and does not
+     * prove: a bound at these sample points, not the maximum error over the whole surface.
+     */
+    sampling: {
+        toleranceMm: number;
+        toleranceDeg: number;
+        mesh: boolean;
+        cornerDivisions: number;
+        sphereGrid: string;
+        cylinderSegments: string;
+    };
     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;
+    /** Also check at half size on every axis combination (completion criterion: shrunken sizes). */
+    shrink?: boolean;
+    /** Extra instance scales, e.g. `repeatBoundaryScales(source)`. */
+    extraScales?: InstanceScale[];
+    /** Compare sampled surfaces too, not only oriented boxes. Default true. */
+    mesh?: boolean;
+    /** 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 at the same
- * centre and world extents within 1 mm and the same rotation within 0.1°, with the same material, at the
- * base size and at every combination of doubled axes.
+ * "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, factor?: number): V3SameReport;
+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

@@ -1 +1 @@
-{"version":3,"file":"v3-from-v2.d.ts","sourceRoot":"","sources":["../src/v3-from-v2.ts"],"names":[],"mappings":"AA4BA,OAAO,EAA+B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAA;AAK3E,OAAO,EAQL,KAAK,aAAa,EACnB,MAAM,aAAa,CAAA;AAEpB,OAAO,KAAK,EAAE,IAAI,EAAuB,YAAY,EAAgB,IAAI,EAAE,MAAM,YAAY,CAAA;AAC7F,OAAO,KAAK,EAAE,OAAO,EAA4B,MAAM,qBAAqB,CAAA;AAG5E,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,gBAAgB,EAAE,CAAA;CAAE,GACjE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAAC,IAAI,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAA;AAEpF,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAA4D,CAAA;AA4EtH,iFAAiF;AACjF,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,SAAS,GAAG,MAAM,EAAE,EAAE,CAaxE;AA0CD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAmU/F;AAOD,wFAAwF;AACxF,MAAM,MAAM,QAAQ,GAAG,UAAU,CAAA;AAEjC,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,aAAa,GAAG,QAAQ,EAAE,CAqBnF;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,QAAQ,EAAE,CAInE;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,aAAa,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAA;IACb,+EAA+E;IAC/E,MAAM,EAAE,aAAa,EAAE,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAChC;AAED,sCAAsC;AACtC,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAClC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAUrC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,YAAY,CAuD9F"}
+{"version":3,"file":"v3-from-v2.d.ts","sourceRoot":"","sources":["../src/v3-from-v2.ts"],"names":[],"mappings":"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"}