@hypersoniclabs/helix-cli 0.1.7 → 0.1.24-helix3.438

package/dist/visualQa/worldWalkMath.d.ts

@@ -0,0 +1,263 @@
+import { TriGrid, type Skeleton } from './vehiclePenetration';
+import type { Vec3 } from './vehicleMath';
+export declare const WORLD_WALK_THRESHOLDS: {
+    /** Rest-pose coverage: a garment surface within this distance OUTSIDE a body vertex covers it. */
+    readonly coverReachM: 0.15;
+    /** In motion, a vertex the garment crossed inwards is still covered (not through) when a garment surface lies within
+     *  this distance outside it (a lining crossed, the shell still over it). */
+    readonly outsideReachM: 0.08;
+    /** A vertex through the garment must be out in the open: at most this share of its outward directions meets the
+     *  garment within `pokeEnclosureReachM` (loose trousers' shell sits 8-10 cm off the knee: 0.78; a thigh out through a skirt
+     *  panel: 0.27; a foot out of a gown: 0.20). */
+    readonly pokeEnclosedMax: 0.5;
+    readonly pokeEnclosureReachM: 0.15;
+    /** A vertex counts as through the garment beyond this depth (below it, touching). */
+    readonly contactMinM: 0.002;
+    /** A poke cluster fails with at least `failMinPoints` points deeper than this... */
+    readonly failDepthM: 0.008;
+    /** ...whose part deeper than `failDepthM` covers at least this much (4 cm²). */
+    readonly failAreaM2: 0.0004;
+    readonly failMinPoints: 3;
+    /** Poking vertices closer than this are one cluster. */
+    readonly linkM: 0.03;
+    /** A joint whose chain crossed the garment since the rest pose counts as through it only this far past the crossing. */
+    readonly limbMinM: 0.015;
+    /** A chain crossing this close to the garment's open edge (a hem, a cuff's rim) is a bone grazing the opening: not counted. */
+    readonly limbEdgeM: 0.04;
+    /** Enclosure rays (see `enclosure`) reach this far. */
+    readonly enclosureReachM: 0.3;
+    /** A joint counts as having left the garment only when at most this share of directions still meets it... */
+    readonly limbEnclosedMax: 0.5;
+    /** ...and at least this much less than at rest. */
+    readonly limbEnclosureDrop: 0.25;
+    /** Hands and fingers swing against a garment by design (a hand brushing a skirt): through its surface they fail only
+     *  beyond this depth. */
+    readonly handFailDepthM: 0.02;
+    /** Depth recorded for the vertices of a limb that went through (distance back to the crossing), at most this. */
+    readonly limbDepthCapM: 0.25;
+    /** Holes: covered skin within this distance of skin the garment does not cover at rest is the garment's edge band (a hem
+     *  or a slit may uncover it in a normal stride), so it is not drawn as sentinel. */
+    readonly holeErodeM: 0.05;
+    /** Holes: a connected group of see-through pixels (magenta not under the garment's outer faces) smaller than this
+     *  share of the garment's drawn pixels in the same frame is a seam speck, not a hole... */
+    readonly holeMinBlobFraction: 0.004;
+    /** ...and smaller than this many pixels (at the frame's own resolution) too. */
+    readonly holeMinBlobPx: 120;
+};
+export type WorldWalkThresholds = typeof WORLD_WALK_THRESHOLDS;
+/** three.js `PropertyBinding.sanitizeNodeName`: the name a GLB node gets as an Object3D. */
+export declare function sanitizeNodeName(name: string): string;
+interface GltfJson {
+    nodes?: Array<{
+        name?: string;
+        mesh?: number;
+    }>;
+    meshes?: Array<{
+        name?: string;
+        primitives: Array<{
+            attributes: Record<string, number>;
+            indices?: number;
+        }>;
+    }>;
+    accessors?: Array<{
+        bufferView?: number;
+        byteOffset?: number;
+        componentType: number;
+        count: number;
+        type: string;
+    }>;
+    bufferViews?: Array<{
+        buffer: number;
+        byteOffset?: number;
+        byteLength: number;
+        byteStride?: number;
+    }>;
+}
+/** The JSON and BIN chunks of a GLB, or null when it is not one. */
+export declare function readGlb(glb: Uint8Array): {
+    json: GltfJson;
+    bin: Uint8Array | null;
+} | null;
+/** The names an item's meshes get in the scene: every mesh node's and mesh's name, sanitised as three.js does. */
+export declare function glbMeshNames(glb: Uint8Array): string[];
+export interface GlbPrimitiveIndex {
+    mesh: string;
+    vertexCount: number;
+    indices: Uint32Array;
+}
+/** Every indexed primitive's index buffer (uncompressed GLBs; a compressed one yields none). */
+export declare function glbPrimitiveIndices(glb: Uint8Array): GlbPrimitiveIndex[];
+/**
+ * The master (unhidden) index of a drawn body mesh: the primitive with the same vertex and index counts whose every
+ * triangle agrees with the drawn index — identical where the drawn triangle is whole, and the same first corner where the
+ * runtime collapsed it (`regionHide.ts` keeps corner 0 and repeats it). Null when no primitive matches exactly.
+ */
+export declare function masterIndexFor(prims: GlbPrimitiveIndex[], vertexCount: number, current: ArrayLike<number>): Uint32Array | null;
+/** Triangles the runtime hid (collapsed in the drawn index, whole in the master): the master's corners, flat. */
+export declare function hiddenTriangles(master: ArrayLike<number>, current: ArrayLike<number>): number[];
+export declare const countDegenerate: (ix: ArrayLike<number>) => number;
+export interface WalkMeshPull {
+    name: string;
+    pos: number[];
+    index: number[] | null;
+    bone?: Array<string | null>;
+}
+export interface WalkPull {
+    bones: Record<string, Vec3>;
+    parents: Record<string, string | null>;
+    body: WalkMeshPull[];
+    item: WalkMeshPull[];
+}
+/** The item's posed triangles, flat (9 numbers per triangle). `index` per item mesh comes from the rest pull. */
+export declare function itemTriangles(item: WalkMeshPull[], indexByMesh?: Record<string, ArrayLike<number>>): Float64Array;
+/** Vertices referenced by a whole (drawn) triangle. */
+export declare function drawnVertices(index: ArrayLike<number>, vertexCount: number): Uint8Array;
+export interface BodyVertexRef {
+    mesh: number;
+    vertex: number;
+}
+/**
+ * How many times the bone chain from the root (pelvis) to each joint crosses the garment, and the last crossing on the
+ * way. A joint whose count changes parity between the rest pose and a walk pose has moved THROUGH the garment (a shin out
+ * through a gown's front panel, a knee through a skirt), however deep — the case a vertex-to-own-bone test cannot see,
+ * because the whole limb is then on the outside. Accessory (spring) chains are not followed.
+ */
+export declare function chainParity(sk: Skeleton, grid: TriGrid, edges?: EdgeIndex | null, edgeM?: number): Map<string, {
+    n: number;
+    via: Vec3 | null;
+}>;
+/** How enclosed a point is by the garment: the share of 26 directions in which a ray of `reach` hits it. A joint inside a
+ *  sleeve or a gown reads high (most directions meet cloth), one out in the open low, whatever the garment's internal
+ *  layers do to a crossing count. */
+export declare function enclosure(p: Vec3, grid: TriGrid, reach?: number): number;
+/** The share of the directions in the hemisphere around `u` in which a ray of `reach` from p meets the garment: a vertex
+ *  through an inner layer (a lining, a liner under loose trousers) still has the shell around it and reads high; one out
+ *  in the open reads low. */
+export declare function outwardEnclosure(p: Vec3, u: Vec3, grid: TriGrid, reach: number): number;
+/** The garment's open edges (edges of exactly one triangle, vertices welded at 0.1 mm), for proximity queries. */
+export interface EdgeIndex {
+    count: number;
+    near(p: Vec3, r: number): boolean;
+}
+export declare function garmentEdges(item: WalkMeshPull[], indexByMesh?: Record<string, ArrayLike<number>>): EdgeIndex;
+export interface RestCoverage {
+    /** Per body mesh, the DRAWN vertices the garment covers in the rest pose. */
+    covered: Uint8Array[];
+    coveredCount: number;
+    judged: number;
+    skeleton: boolean;
+    /** Per joint, the parity of the root-to-joint chain's garment crossings in the rest pose. */
+    parity: Record<string, number>;
+    /** Per joint, how enclosed by the garment it is in the rest pose (`enclosure`). */
+    enclosed?: Record<string, number>;
+}
+/**
+ * Rest-pose coverage: per body mesh, which DRAWN vertices the garment covers — a garment surface within `coverReachM`
+ * outside the vertex (along the line from its bone through it) and none between it and its bone — and the rest parity of
+ * every joint's chain.
+ */
+export declare function restCoverage(pull: WalkPull, T?: WorldWalkThresholds, indexByMesh?: Record<string, ArrayLike<number>>): RestCoverage;
+/**
+ * The body a garment covers deep inside its coverage, for the hole renders: covered DRAWN vertices (rest pose) with no
+ * uncovered drawn vertex within `erodeM`, and per body mesh the drawn triangles all three of whose corners are such
+ * vertices (`sentinel`) and the rest of its drawn triangles (`rest`). Eroding keeps the band a garment's own edge (a hem, a
+ * slit, a neckline) can uncover in a normal stride out of the count: only skin that a hole IN the garment can expose stays.
+ */
+export declare function deepCoveredTriangles(pull: WalkPull, rest: RestCoverage, erodeM?: number): Array<{
+    sentinel: number[];
+    rest: number[];
+    vertices: number;
+}>;
+export interface PokePoint {
+    mesh: string;
+    vertex: number;
+    p: Vec3;
+    depth: number;
+    bone: string;
+    u: Vec3;
+    kind: 'surface' | 'limb';
+}
+export interface PokeCluster {
+    sample: string;
+    bone: string;
+    /** Bones in the cluster with their point counts, largest first. */
+    bones: Array<[string, number]>;
+    /** `surface`: skin through the garment's surface; `limb`: a bone moved through it (the whole part outside). */
+    kind: 'surface' | 'limb' | 'mixed';
+    points: number;
+    deepPoints: number;
+    maxDepthM: number;
+    areaM2: number;
+    areaDeepM2: number;
+    centroid: Vec3;
+    /** Mean outward direction (bone to vertex) of the cluster's points: where to look at it from. */
+    normal: Vec3;
+    verdict: 'fail' | 'near';
+}
+export interface PokeSample {
+    sample: string;
+    judged: number;
+    poking: number;
+    limbsThrough: string[];
+    clusters: PokeCluster[];
+}
+/**
+ * One walk pose: every drawn body vertex now through the garment, clustered. Two ways through: (1) a vertex the garment
+ * covered at rest with a garment surface between it and its bone and none over it within a cloth's thickness; (2) any
+ * drawn vertex of a bone whose root-to-joint chain changed crossing parity since the rest pose by more than
+ * `limbMinM` (the bone itself went through), its depth the distance back to that crossing.
+ */
+export declare function measurePoke(sample: string, pull: WalkPull, rest: RestCoverage, T?: WorldWalkThresholds, indexByMesh?: Record<string, ArrayLike<number>>): PokeSample;
+export declare function clusterPoke(sample: string, pts: PokePoint[], T?: WorldWalkThresholds): PokeCluster[];
+export interface HoleFrame {
+    frame: string;
+    width: number;
+    height: number;
+    /** Pixels of the item (P1 green), of the hidden body in sight (P1 magenta), and of those the item's outer faces do not
+     *  cover (the see-through holes). */
+    itemPx: number;
+    sentinelPx: number;
+    holePx: number;
+    /** The largest 8-connected see-through group, in pixels and as a share of the item's pixels. */
+    largestBlobPx: number;
+    largestBlobFraction: number;
+    blobs: number;
+    /** Bounding box of the largest group (x, y, w, h), for the close-up. */
+    largestBlobBox: [number, number, number, number] | null;
+}
+/** Classify one pose/camera: P1 (hidden body magenta, item green) against P2 (item's outer faces green), RGB(A) bytes. */
+export declare function classifyHoles(frame: string, p1: Uint8Array, p2: Uint8Array, width: number, height: number, channels?: number): HoleFrame;
+/** 8-connected components of a mask: pixel count and bounding box each. */
+export declare function components(mask: Uint8Array, width: number, height: number): Array<{
+    px: number;
+    box: [number, number, number, number];
+}>;
+export interface WalkVerdict {
+    pass: boolean;
+    detail: string;
+    measured: Record<string, unknown>;
+}
+export declare function holeFrameFails(f: HoleFrame, T?: WorldWalkThresholds): boolean;
+/** `wear.walk.no_holes` over every pose/camera of one base. `hidden.triangles` = triangles the runtime hid on that base,
+ *  `hidden.covered` = drawn triangles deep inside the garment's rest coverage (both drawn as sentinel). */
+export declare function judgeHoles(frames: HoleFrame[], hidden: {
+    triangles: number;
+    covered?: number;
+    measurable: boolean;
+    why?: string;
+}, T?: WorldWalkThresholds): WalkVerdict;
+/** `wear.walk.no_poke_through` over every walk pose of one base. */
+export declare function judgePoke(samples: PokeSample[], cover: {
+    covered: number;
+    judged: number;
+    skeleton: boolean;
+    itemTriangles?: number;
+}, T?: WorldWalkThresholds): WalkVerdict;
+export declare const WORLD_WALK_CATEGORIES: Set<string>;
+/** Whether the world-walk stage runs: on for wearables, character add-ons and avatars unless `--no-world-walk` or
+ *  `HELIX_VQA_WORLD_WALK=0|off|false`. Anything else in the variable is ignored (on). */
+export declare function worldWalkEnabled(category: string, flag: boolean | undefined, env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    reason: string;
+};
+export {};