@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/visualQa/vehicleMath.d.ts

@@ -0,0 +1,440 @@
+import { type PenetrationResult } from './vehiclePenetration';
+import type { OccupantPosture } from './vehiclePosture';
+export type Vec3 = [number, number, number];
+/** Thresholds. Calibrated on live cars — see the calibration table in `vehicle.spec.ts`. */
+export declare const VEHICLE_QA_THRESHOLDS: {
+    /** Drawn wheel centre vs physics hub, lateral (x) and longitudinal (z). */
+    readonly hubPlanarTolM: 0.03;
+    /** Drawn wheel centre vs physics hub, vertical (y). */
+    readonly hubVerticalTolM: 0.03;
+    /** Drawn axle vs the wheel node's spin axis. Geometry that is not square to its spin axis wobbles. */
+    readonly axleAgreementMaxDeg: 10;
+    /** Drawn tyre radius vs physics radius (warn-level: a big mismatch sinks or floats the tyre). */
+    readonly radiusTolM: 0.03;
+    /** A body vertex this far inside the tyre volume is poke-through. */
+    readonly penetrationDepthM: 0.01;
+    /** Body points inside this fraction of the tyre radius are inside the rim barrel (brakes, hub, knuckle — often baked
+     *  into a single body mesh): never judged. Road-car rims sit at 0.62–0.72 of the tyre radius. */
+    readonly hubZoneFraction: 0.72;
+    /** Body vertices this many points inside the tyre (deeper than `penetrationDepthM`) fail the wheel. */
+    readonly penetrationMaxCount: 0;
+    /** Arch window: body over the tyre within this angle of vertical. */
+    readonly archWindowDeg: 60;
+    /** Fender skin outboard of the tyre's outer face that still counts as the arch lip. */
+    readonly archOutboardBandM: 0.12;
+    /** The lip band starts this far inboard of the tyre's outer face (sidewall bulge, lip curl). */
+    readonly archLipInsetM: 0.02;
+    /** Lip points are judged down to this fraction of the tyre radius (there is no hardware outboard of the tyre). */
+    readonly lipFloorFraction: 0.3;
+    /** The side-view cutout measure looks down to this fraction of the radius (below it: brake discs, hub). */
+    readonly cutoutFloorFraction: 0.45;
+    /** Minimum radial gap from the tyre's top arc to the body. */
+    readonly archGapMinM: 0;
+    /** Lowest body point above the contact plane, road cars. */
+    readonly rideHeightMinM: 0.05;
+    /** Duplicate wheel geometry within this distance of a hub is a second drawn wheel on that hub. */
+    readonly duplicateHubM: 0.25;
+    /** Spin: drawn rotation / (distance / radius). */
+    readonly spinRatioMin: 0.8;
+    readonly spinRatioMax: 1.25;
+    /** Spin needs at least this much sampled time and this much rolled angle to judge. */
+    readonly spinMinSeconds: 1;
+    readonly spinMinExpectedRad: 3;
+    /** Largest per-sample expected step before the samples alias (can't unwrap beyond π). */
+    readonly spinMaxStepRad: 2.6;
+    /** Steering at full lock: front wheels must yaw at least this much, and the steering wheel at least this much. */
+    readonly steerWheelMinDeg: 10;
+    readonly steeringWheelMinDeg: 30;
+    /** Steered wheels vs the physics steer angle at full lock. */
+    readonly steerAgreementTolDeg: 4;
+    /** Articulation: open angle within this of the declared hinge travel; closed again within this of closed. */
+    readonly panelTolDeg: 5;
+    readonly panelReturnTolDeg: 2;
+    /** Attached nodes (glass, door card, mirror) must stay rigid to the panel's main node. */
+    readonly rigidPosTolM: 0.005;
+    readonly rigidQuatDotMin: 0.9999;
+};
+export type Thresholds = typeof VEHICLE_QA_THRESHOLDS;
+export declare const dot: (a: Vec3, b: Vec3) => number;
+export declare const sub: (a: Vec3, b: Vec3) => Vec3;
+export declare const add: (a: Vec3, b: Vec3) => Vec3;
+export declare const scale: (a: Vec3, s: number) => Vec3;
+export declare const cross: (a: Vec3, b: Vec3) => Vec3;
+export declare const len: (a: Vec3) => number;
+export declare const norm: (a: Vec3) => Vec3;
+export declare const r4: (v: number) => number;
+export declare const r3v: (v: Vec3) => Vec3;
+/** Orthonormal basis around an axle: `a` the axle, `u` body-up projected off the axle, `v = a × u` (forward-ish). */
+export declare function axleBasis(axle: Vec3): {
+    a: Vec3;
+    u: Vec3;
+    v: Vec3;
+};
+/** Eigenvector of the smallest eigenvalue of a symmetric 3×3 matrix (Jacobi). */
+export declare function smallestEigenvector(m: number[][]): Vec3;
+export interface WheelGeometry {
+    /** Drawn wheel centre: tyre midplane on the axle, centre of the tyre circle in the wheel plane. */
+    centre: Vec3;
+    /** Spin axis used (unit, body frame). */
+    axle: Vec3;
+    /** Smallest-variance axis of the drawn geometry (the axle the geometry is actually built around). */
+    pcaAxle: Vec3;
+    axleAgreementDeg: number;
+    /** Outer tyre radius (max radial distance of the drawn geometry from the centre). */
+    radius: number;
+    /** Tyre width: axial extent of the tread (points within 10 % of the outer radius). */
+    width: number;
+    points: number;
+}
+/**
+ * Measure a drawn wheel from its vertices (flat xyz, body frame). `axleHint` is the wheel node's spin axis; the centre
+ * is the centre of the tyre circle in the plane perpendicular to it and the midpoint of the tread along it. Node
+ * origins are never used — a rim node can sit at the car's origin with its geometry baked at the hub.
+ */
+export declare function wheelGeometry(points: ArrayLike<number>, axleHint: Vec3): WheelGeometry | null;
+export interface BodyPoints {
+    /** Flat xyz, body frame. */
+    points: ArrayLike<number>;
+    /** Index into `names` per point. */
+    mesh: ArrayLike<number>;
+    names: string[];
+}
+export interface ArchResult {
+    /** Body surface samples (≈8 mm grid) inside the tyre volume deeper than the threshold (outside the hub zone). */
+    penetrationCount: number;
+    maxPenetrationM: number;
+    penetrationMeshes: string[];
+    /** Min radial gap (ρ − r) from the tyre's top arc (±window) to the body, tread + outboard lip band. null = nothing over the tyre. */
+    archGapM: number | null;
+    /** Same, restricted to ±15° of vertical (the visible gap over the tyre top). */
+    archGapTopM: number | null;
+    /**
+     * The side view: lowest body surface over the tyre top (±15°) in the tyre's outer half or outboard of it, minus the
+     * tyre radius. Negative = the tyre top sits that far above the arch cutout (what the static GLB analysis measures).
+     */
+    archCutoutTopM: number | null;
+    /** Angle from vertical (deg, + = towards the front) where the min gap was found, and which mesh. */
+    archGapAtDeg: number | null;
+    archGapMesh: string | null;
+    archPoints: number;
+}
+/**
+ * Body vs one tyre. `outward` is +1 when the axle direction points away from the car's centreline at this wheel.
+ * The tyre is the cylinder (centre, axle, radius r, width w).
+ */
+export declare function archAnalysis(body: BodyPoints, w: WheelGeometry, outward: 1 | -1, t?: Thresholds): ArchResult;
+/** Least-squares plane y = c0 + c1·x + c2·z through the tyre contact points (centre − r·up for each wheel). */
+export declare function contactPlane(wheels: Array<{
+    centre: Vec3;
+    radius: number;
+    axle: Vec3;
+}>): [number, number, number];
+export interface RideHeight {
+    /** Lowest body point above the contact plane (m). Negative = body below the road. */
+    minM: number | null;
+    mesh: string | null;
+    at: Vec3 | null;
+}
+export declare function rideHeight(body: BodyPoints, plane: [number, number, number], filter?: (p: Vec3) => boolean): RideHeight;
+export interface WheelRow {
+    id: string;
+    /** Physics hub (body frame): tuning contact mount − up·(restLength − compression). */
+    hub: Vec3;
+    /** Where the runtime posed the wheel node (for diagnosis only). */
+    node: Vec3 | null;
+    drawnCentre: Vec3 | null;
+    delta: Vec3 | null;
+    radius: number | null;
+    /** The wheel contact's radius: where the suspension puts the physics ground under this hub. */
+    physicsRadius: number;
+    /**
+     * The radius the runtime ROLLS this wheel on: its axle's v2 tyre (`simulation.land.tyreByAxle[min(axle, n-1)].radius`,
+     * so front and rear differ on a staggered car), else the contact's. Spin and drawn-radius checks use this, per wheel.
+     */
+    rollRadius?: number;
+    /** The wheel's axle index (0 = front), from the live tuning. */
+    axle?: number | null;
+    width: number | null;
+    axleAgreementDeg: number | null;
+    meshes: string[];
+    penetrationCount: number | null;
+    maxPenetrationM: number | null;
+    penetrationMeshes: string[];
+    archGapM: number | null;
+    archGapTopM: number | null;
+    archCutoutTopM?: number | null;
+    archGapAtDeg: number | null;
+    archGapMesh: string | null;
+    /** Lowest body point above this wheel's own contact level, within ±0.6 m longitudinally of the hub. */
+    rideHeightLocalM: number | null;
+    /** Suspension compression the row was judged at (median of the sampling window), and the window. */
+    compression?: number | null;
+    compressionWindow?: {
+        n: number;
+        min: number | null;
+        median: number | null;
+        max: number | null;
+    } | null;
+}
+export interface Verdict {
+    pass: boolean;
+    detail: string;
+    measured: Record<string, unknown>;
+}
+export declare function judgeAtHubs(rows: WheelRow[], physicsWheelCount: number, duplicates: Array<{
+    mesh: string;
+    nearWheel: string;
+    distM: number;
+}>, t?: Thresholds): Verdict;
+export declare function judgeArchClearance(rows: WheelRow[], ride: RideHeight, t?: Thresholds): Verdict;
+export declare function judgeRadius(rows: WheelRow[], t?: Thresholds): Verdict;
+export interface SpinSample {
+    t: number;
+    x: number;
+    z: number;
+    forwardSpeed: number;
+    /** Per wheel: angle of the drawn wheel about its own axle (axle oriented towards body +X), rad, wrapped. */
+    ang: number[];
+}
+export interface SpinResult {
+    pass: boolean;
+    seconds: number;
+    distanceM: number;
+    fps: number;
+    wheels: Array<{
+        id: string;
+        drawnRad: number;
+        expectedRad: number;
+        ratio: number | null;
+        maxStepRad: number;
+    }>;
+    reason: string | null;
+}
+export declare function spinAnalysis(samples: SpinSample[], ids: string[], radii: number[], t?: Thresholds): SpinResult;
+export type Quat = [number, number, number, number];
+export declare const qMul: (a: Quat, b: Quat) => Quat;
+export declare const qInv: (q: Quat) => Quat;
+export declare const qAngleDeg: (q: Quat) => number;
+/** Signed angle (deg) of the rotation taking `from` to `to`, measured about `axis` (both quats in the same frame). */
+export declare function signedAngleAboutDeg(from: Quat, to: Quat, axis: Vec3): number;
+/** Yaw (deg) of an axle direction about body +Y, 0 = square across the car. */
+export declare function axleYawDeg(axle: Vec3): number;
+export interface PanelSweep {
+    id: string;
+    expectedDeg: number;
+    openDeg: number | null;
+    closedAgainDeg: number | null;
+    durable: {
+        closed: unknown;
+        open: unknown;
+        closedAgain: unknown;
+    };
+    /** Max drift of each attached node relative to the main node between closed and open. */
+    attached: Array<{
+        node: string;
+        maxPosDeltaM: number;
+        quatDot: number;
+    } | {
+        node: string;
+        missing: true;
+    }>;
+    key: string | null;
+    /** How the travel ended: `reached`, `stopped-short`, `state-flipped-but-panel-did-not-move`, `toggle-not-accepted`. */
+    opening?: {
+        status: string;
+        reissued: number;
+        seconds: number;
+        trace?: unknown;
+    } | null;
+    closing?: {
+        status: string;
+        reissued: number;
+        seconds: number;
+        trace?: unknown;
+    } | null;
+}
+export declare function judgePanel(p: PanelSweep, t?: Thresholds): {
+    pass: boolean;
+    why: string;
+};
+export interface CamSpec {
+    pos: Vec3;
+    target: Vec3;
+    fov: number;
+    near?: number;
+}
+/**
+ * Camera (body frame) looking at the centre of a box from direction `dir`, far enough that the box fills ~`fill` of
+ * the frame. `fov` is vertical, `aspect` = width / height.
+ */
+export declare function camFit(min: Vec3, max: Vec3, dir: Vec3, fov?: number, aspect?: number, fill?: number): CamSpec;
+export interface BodyTriangles {
+    /** Flat, 9 numbers per triangle (three body-frame vertices). */
+    tris: ArrayLike<number>;
+    /** Index into `names` per triangle. */
+    mesh: ArrayLike<number>;
+    names: string[];
+}
+/**
+ * Points on the body SURFACE (not just its vertices) inside `box`, on a barycentric grid of about `spacing` metres.
+ * Vertices alone miss the case that matters most: a fender skin whose large triangles have every vertex outside the
+ * tyre while the face itself cuts through it — the 993's arches are exactly that.
+ */
+export declare function sampleTriangles(body: BodyTriangles, box: {
+    min: Vec3;
+    max: Vec3;
+}, spacing?: number, maxPoints?: number): BodyPoints;
+/** The region around a wheel whose body surface can touch or overhang the tyre. */
+export declare function wheelNeighbourhood(w: WheelGeometry, t?: Thresholds): {
+    min: Vec3;
+    max: Vec3;
+};
+/**
+ * Match a package's declared `module.seatVars` keys to the seats the world actually produced.
+ *
+ * The engine does not compare raw strings: `core/vehicle/seatIdResolution.ts` (`cabinSeatIdFor`) accepts a key
+ * that is EITHER a cabin seat id (`seat_dside_f`, …) OR the legacy driver role key (`module.driverSeat`, default
+ * `'driver'`), which means the driver's cabin seat. A legacy single-driver package that declares `driver` is a
+ * valid manifest and boards correctly, so requiring the key itself to be an evidence seat id failed it.
+ * Everything else must still be a real seat id: a passenger key the cabin does not have is exactly the defect
+ * this assert exists to catch (the engine itself warns that such a seat "can never replicate").
+ */
+export declare function resolveDeclaredSeats(declared: {
+    driver: string | null;
+    seats: string[];
+}, evidence: ReadonlyArray<{
+    id: string;
+    role: string;
+}>): {
+    absent: string[];
+    resolved: Record<string, string>;
+    driverId: string | null;
+};
+/** The first engine whose cabin fit honours authored seat-socket heights. Anything older makes the occupant numbers meaningless. */
+export declare const OCCUPANT_MIN_ENGINE = "0.3.169";
+export declare const OCCUPANT_QA_THRESHOLDS: {
+    /** Crown (highest skinned vertex of the head) to the first car surface above it. Below this the head touches or is through the lining. */
+    readonly headGapMinM: 0.01;
+    /** The occupant must not hover above the cushion: lowest buttock vertex above the cushion top by more than this. */
+    readonly hipFloatMaxM: 0.12;
+    /** ...nor go through the seat's base: lowest buttock vertex below the first up-facing surface under the seat by more than this. */
+    readonly hipThroughBaseMaxM: 0.02;
+    /** Warn-level: how deep the buttocks sit INTO the cushion volume. A bucket seat swallows some of a body; this much is a lot. */
+    readonly hipSinkWarnM: 0.1;
+    /** Sole vs the first car surface below the foot (floor mat, sill, pedal pad). A sole this far under it is through the floor. */
+    readonly footSinkMaxM: 0.05;
+    /** A sole this far above it hovers in mid air. */
+    readonly footFloatMaxM: 0.3;
+    /** Driver: the nearest finger-or-hand bone to the steering wheel, per hand. */
+    readonly handToRimMaxM: 0.07;
+    /** The pelvis must sit on the seat node the engine says it is on. */
+    readonly seatResidualMaxM: 0.03;
+};
+export type OccupantThresholds = typeof OCCUPANT_QA_THRESHOLDS;
+/** `0.3.169` vs `0.3.170-beta` etc. Compares the numeric dotted prefix; an unreadable version is NOT at least anything. */
+export declare function engineAtLeast(version: string | null | undefined, min: string): boolean;
+/** Flat triangle soup (9 numbers per triangle) with the mesh index of each triangle and the mesh names. */
+export interface CabinTriangles {
+    tris: number[];
+    mesh: number[];
+    names: string[];
+}
+export interface RayHit {
+    t: number;
+    y: number;
+    point: Vec3;
+    mesh: string;
+}
+/**
+ * Nearest TWO-SIDED hit of a ray against a triangle soup (Möller–Trumbore, no back-face culling: a headliner or a seat
+ * cushion is usually modelled as a single-sided shell that faces away from the occupant).
+ */
+export declare function rayFirst(soup: CabinTriangles, origin: Vec3, dir: Vec3, opts?: {
+    cull?: boolean;
+    minT?: number;
+    maxT?: number;
+}): RayHit | null;
+/** Every hit of the ray, nearest first. See `rayFirst` for `cull`. */
+export declare function rayHits(soup: CabinTriangles, origin: Vec3, dir: Vec3, opts?: {
+    cull?: boolean;
+    minT?: number;
+    maxT?: number;
+}): RayHit[];
+export interface OccupantPull {
+    /** Seat key as declared by the package, and the cabin seat id it resolved to. */
+    seatKey: string;
+    seatId: string;
+    role: string;
+    /** Every bone of the occupant's skeleton, body frame. */
+    bones: Record<string, Vec3>;
+    /** Skinned vertices of the occupant (every drawn skinned mesh: body, hair, hats...), body frame, flat xyz. */
+    points: number[];
+    /** Vertices of the steering wheel (rim, spokes, hub), body frame, flat xyz. Null when the vehicle has none. */
+    rim: number[] | null;
+    /** The car's own drawn triangles around the seat. */
+    cabin: CabinTriangles;
+    /** The engine's own readout for this occupant (pelvis-to-seat residual etc.), as read. */
+    seatResidualM: number | null;
+}
+export interface OccupantMeasure {
+    seatKey: string;
+    seatId: string;
+    role: string;
+    occupantPoints: number;
+    cabinTriangles: number;
+    head: {
+        boneY: number | null;
+        crownY: number | null;
+        ceilingY: number | null;
+        gapM: number | null;
+        ceilingMesh: string | null;
+        openRoof: boolean;
+    };
+    hips: {
+        pelvisY: number | null;
+        buttockY: number | null;
+        seatSurfaceY: number | null;
+        seatMesh: string | null;
+        /** buttock bottom minus cushion top: negative = into the cushion, positive = hovering. */
+        gapM: number | null;
+        /** First up-facing surface below the buttocks (the seat's base / floor pan), and the buttock bottom's height above it. */
+        baseY: number | null;
+        baseGapM: number | null;
+    };
+    feet: Array<{
+        side: 'l' | 'r';
+        soleY: number | null;
+        floorY: number | null;
+        floorMesh: string | null;
+        gapM: number | null;
+    }>;
+    hands: Array<{
+        side: 'l' | 'r';
+        nearestBone: string | null;
+        distM: number | null;
+    }> | null;
+    seatResidualM: number | null;
+    /** Measured clipping of this occupant into the cabin (vehiclePenetration.measurePenetration), when it was measured. */
+    penetration?: PenetrationResult;
+    /** Seated posture read off the drawn bones and skull (vehiclePosture.measurePosture), when it was measured. */
+    posture?: OccupantPosture;
+}
+/** Everything the occupant asserts judge, from one pull. Pure. */
+/** How far ABOVE the pelvis bone the buttock search reaches (see measureOccupant). */
+export declare const HIP_WINDOW_ABOVE_PELVIS_M = 0.15;
+export declare function measureOccupant(pull: OccupantPull): OccupantMeasure;
+export interface OccupantVerdict {
+    id: string;
+    pass: boolean;
+    severity?: 'block' | 'warn';
+    detail: string;
+    measured: Record<string, unknown>;
+}
+/**
+ * The occupant asserts, one per question the critic also answers visually. `boarded` lists the declared seats the harness
+ * could NOT sit in (with why): a declared seat nobody can use is itself a defect.
+ */
+export declare function judgeOccupants(measures: OccupantMeasure[], failedSeats: Array<{
+    seatKey: string;
+    why: string;
+}>, declaredSeats: string[], engineVersion: string | null, T?: OccupantThresholds): OccupantVerdict[];