@hypersoniclabs/helix-cli 0.1.7 → 0.1.23

package/dist/character/helixPalette.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELIX_MATERIAL_BINDING_CONTRACT = exports.HELIX_PALETTE_CONTRACT = void 0;
+exports.validateHelixPaletteSelection = validateHelixPaletteSelection;
+exports.resolveHelixPaletteSelection = resolveHelixPaletteSelection;
+exports.applyHelixPaletteSelection = applyHelixPaletteSelection;
+const node_fs_1 = require("node:fs");
+exports.HELIX_PALETTE_CONTRACT = 'helix-palette/3';
+exports.HELIX_MATERIAL_BINDING_CONTRACT = 'helix-material-binding/1';
+function record(value, label) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`HELIX Palette ${label} must be an object.`);
+    }
+    return value;
+}
+function bounded(value, label) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`HELIX Palette ${label} must be between 0 and 1.`);
+    }
+    return value;
+}
+function physicalSize(value) {
+    if (!Array.isArray(value) || value.length !== 2 || value.some((entry) => typeof entry !== 'number' || !Number.isFinite(entry) || entry <= 0)) {
+        return null;
+    }
+    return [value[0], value[1]];
+}
+function alphaMode(material) {
+    const mode = material.getAlphaMode();
+    return mode === 'MASK' ? 'mask' : mode === 'BLEND' ? 'blend' : 'opaque';
+}
+function hexTint(value, alpha) {
+    const channels = value.slice(1).match(/.{2}/g).map((entry) => Number.parseInt(entry, 16) / 255);
+    return [channels[0], channels[1], channels[2], alpha];
+}
+function validateHelixPaletteSelection(value) {
+    const row = record(value, 'selection');
+    const allowed = new Set(['action', 'familyId', 'familyVersion', 'presetId', 'overrides']);
+    const unknown = Object.keys(row).filter((key) => !allowed.has(key));
+    if (unknown.length > 0)
+        throw new Error(`HELIX Palette selection has unsupported field(s): ${unknown.join(', ')}.`);
+    if (row.action !== 'forceFamilyId')
+        throw new Error("HELIX Palette selection action must be 'forceFamilyId'.");
+    if (typeof row.familyId !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.familyId)) {
+        throw new Error('HELIX Palette selection familyId must be lowercase kebab-case.');
+    }
+    if (typeof row.familyVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(row.familyVersion)) {
+        throw new Error('HELIX Palette selection familyVersion must be semantic version text.');
+    }
+    if (row.presetId !== null && (typeof row.presetId !== 'string' || row.presetId.trim() === '')) {
+        throw new Error('HELIX Palette selection presetId must be a non-empty string or null.');
+    }
+    const overrides = record(row.overrides, 'selection overrides');
+    const overrideAllowed = new Set(['tint', 'roughness', 'metallic']);
+    const overrideUnknown = Object.keys(overrides).filter((key) => !overrideAllowed.has(key));
+    if (overrideUnknown.length > 0)
+        throw new Error(`HELIX Palette selection overrides have unsupported field(s): ${overrideUnknown.join(', ')}.`);
+    const parsedOverrides = {};
+    if (overrides.tint !== undefined) {
+        if (typeof overrides.tint !== 'string' || !/^#[a-fA-F0-9]{6}$/.test(overrides.tint)) {
+            throw new Error('HELIX Palette selection tint must be a #RRGGBB color.');
+        }
+        parsedOverrides.tint = overrides.tint;
+    }
+    if (overrides.roughness !== undefined)
+        parsedOverrides.roughness = bounded(overrides.roughness, 'selection roughness');
+    if (overrides.metallic !== undefined)
+        parsedOverrides.metallic = bounded(overrides.metallic, 'selection metallic');
+    return {
+        action: 'forceFamilyId',
+        familyId: row.familyId,
+        familyVersion: row.familyVersion,
+        presetId: row.presetId,
+        overrides: parsedOverrides,
+    };
+}
+function resolveHelixPaletteSelection(path, input) {
+    let parsed;
+    try {
+        parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`HELIX Palette input is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const root = record(parsed, 'document');
+    if (root.contract !== exports.HELIX_PALETTE_CONTRACT) {
+        throw new Error(`HELIX Palette input contract must be '${exports.HELIX_PALETTE_CONTRACT}'.`);
+    }
+    if (!Array.isArray(root.families))
+        throw new Error('HELIX Palette document families must be an array.');
+    const families = root.families
+        .map((entry) => record(entry, 'family'))
+        .filter((entry) => entry.id === input.familyId);
+    if (families.length === 0)
+        throw new Error(`HELIX Palette family '${input.familyId}' does not exist.`);
+    if (families.length > 1)
+        throw new Error(`HELIX Palette family '${input.familyId}' is duplicated.`);
+    const row = families[0];
+    if (row.definitionVersion !== input.familyVersion) {
+        throw new Error(`HELIX Palette family '${input.familyId}' is version ${String(row.definitionVersion)}, not ${input.familyVersion}.`);
+    }
+    const shader = record(row.shader, `family '${input.familyId}' shader`);
+    const defaults = record(shader.defaults, `family '${input.familyId}' shader defaults`);
+    const physical = record(row.physical, `family '${input.familyId}' physical data`);
+    const assets = record(row.assets, `family '${input.familyId}' assets`);
+    if (input.presetId !== null) {
+        const variants = record(root.variants, 'variants');
+        if (!Array.isArray(variants.presets) || !variants.presets.some((entry) => record(entry, 'preset').id === input.presetId)) {
+            throw new Error(`HELIX Palette preset '${input.presetId}' does not exist.`);
+        }
+    }
+    return {
+        selection: input,
+        familyName: typeof row.name === 'string' && row.name.trim() !== '' ? row.name : input.familyId,
+        assetsState: typeof assets.state === 'string' ? assets.state : 'unknown',
+        physicalSizeMeters: physicalSize(physical.sizeMeters),
+        roughness: input.overrides.roughness ?? bounded(defaults.roughness, `family '${input.familyId}' roughness`),
+        metallic: input.overrides.metallic ?? bounded(defaults.metallic, `family '${input.familyId}' metallic`),
+    };
+}
+function applyHelixPaletteSelection(document, resolved) {
+    const root = document.getRoot();
+    const unassignedPrimitives = root.listMeshes()
+        .flatMap((mesh) => mesh.listPrimitives())
+        .filter((primitive) => primitive.getMaterial() === null);
+    if (unassignedPrimitives.length > 0) {
+        const fallback = document.createMaterial('HELIX Palette Default');
+        for (const primitive of unassignedPrimitives)
+            primitive.setMaterial(fallback);
+    }
+    const materials = root.listMaterials();
+    for (const material of materials) {
+        if (resolved.selection.overrides.tint !== undefined) {
+            material.setBaseColorFactor(hexTint(resolved.selection.overrides.tint, material.getBaseColorFactor()[3]));
+        }
+        material.setRoughnessFactor(resolved.roughness).setMetallicFactor(resolved.metallic);
+        const binding = {
+            contract: exports.HELIX_MATERIAL_BINDING_CONTRACT,
+            familyId: resolved.selection.familyId,
+            familyVersion: resolved.selection.familyVersion,
+            presetId: resolved.selection.presetId,
+            overrides: resolved.selection.overrides,
+            uv: {
+                uvSet: 0,
+                offset: [0, 0],
+                scale: [1, 1],
+                rotationRadians: 0,
+                physicalSizeMeters: resolved.physicalSizeMeters,
+            },
+            preserved: {
+                identityBearingDetails: true,
+                sourceMaterialId: material.getName() || null,
+                maskBindings: [],
+                decals: [],
+            },
+            renderState: {
+                alphaMode: alphaMode(material),
+                alphaCutoff: material.getAlphaCutoff(),
+                doubleSided: material.getDoubleSided(),
+                depthWrite: true,
+                depthTest: true,
+                blendMode: 'normal',
+            },
+        };
+        material.setExtras({ ...material.getExtras(), helixMaterialBinding: binding });
+    }
+    return {
+        contract: exports.HELIX_MATERIAL_BINDING_CONTRACT,
+        action: 'forceFamilyId',
+        familyId: resolved.selection.familyId,
+        familyVersion: resolved.selection.familyVersion,
+        familyName: resolved.familyName,
+        assetsState: resolved.assetsState,
+        appliedMaterialCount: materials.length,
+        preservedAuthoredTextures: true,
+        materials: materials.map((material) => ({
+            name: material.getName(),
+            roughness: material.getRoughnessFactor(),
+            metallic: material.getMetallicFactor(),
+        })),
+    };
+}
+//# sourceMappingURL=helixPalette.js.map

package/dist/character/helixPalette.js.map

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

package/dist/character/hideCoverage.d.ts

@@ -0,0 +1,135 @@
+import { type Document } from '@gltf-transform/core';
+/**
+ * MEASURED hide coverage: which of the body regions a garment is granted to hide does it actually enclose?
+ *
+ * ── WHY ────────────────────────────────────────────────────────────────────────────────────────────────────
+ * A character add-on's `hide` op collapses the base body's triangles for whole `_REGION` labels. Conform used
+ * to emit the slot's FULL platform grant whatever the garment covered, so short sleeves hid the whole upper
+ * arm, cropped trousers the whole shin, and every hem that lands inside a region seam rendered a sawtooth
+ * (the engine drops a triangle when >= 2 of its 3 corners are hidden; labels interleave across a band several
+ * cm wide where two regions meet). The rule here: hide a granted region ONLY when the garment occludes it.
+ *
+ * ── THE METRIC ─────────────────────────────────────────────────────────────────────────────────────────────
+ * Bind pose. For every body vertex v with outward normal n, v is OCCLUDED when a garment surface is crossed by
+ * a ray along n starting `backoffM` behind the skin and reaching `standoffM` in front of it (60 mm: the
+ * "fabric within 60 mm" measure of `run/open-alpha-qa/wearables-import/coverage-derivation`; 20 mm behind so a
+ * garment that sits a few mm inside the skin — which the conform push-out fit then corrects — still counts as
+ * covering it). A region's coverage is the occluded fraction of its vertices; it is hidden at >= 98 %.
+ *
+ * Two lessons from that earlier work are built in rather than rediscovered:
+ *  - NEAREST-surface-within-60-mm is the wrong question: fabric 45 mm ABOVE a vertex (a hem above the ankle)
+ *    is within 60 mm and covers nothing. Casting along the NORMAL makes a hem above the skin point a miss.
+ *  - A ray that lands exactly on a shared edge or vertex can slip between two triangles in floating point, so
+ *    each vertex also casts four rays tilted by `coneDeg` (0.5 deg, <1 mm of lateral reach) — enough to rescue
+ *    an edge hit, far too little to bridge a hem. (An 8 deg cone, ~11 mm, was tried and credited vertices up to
+ *    a centimetre below a hem as covered: Warehouse Uniform's right shin read 100 % instead of 96 %.)
+ *
+ * Every garment LOD (scene) is measured separately — each LOD is drawn alone and the hide op is shared by all
+ * of them — and a region's coverage is the MINIMUM across LODs, so a region is hidden only if no LOD leaves a
+ * void. Body vertices come from the first scene (highest LOD) of the base body, face mesh included.
+ */
+export declare const DEFAULT_COVERAGE_THRESHOLD = 0.98;
+export declare const DEFAULT_STANDOFF_M = 0.06;
+export declare const DEFAULT_BACKOFF_M = 0.02;
+/** Half-angle (degrees) of the tilted-ray fan. 0.5 deg is ~0.7 mm at the far end of the reach: it only rescues a
+ *  ray that lands exactly on a shared edge or vertex, and cannot bridge a hem (an 8 deg cone could, ~11 mm). */
+export declare const DEFAULT_CONE_DEG = 0.5;
+export interface HideCoverageOptions {
+    /** How far in front of the skin a garment surface may be and still occlude the vertex. Default 0.06 m. */
+    standoffM?: number;
+    /** How far behind the skin the ray starts, so a garment sitting just inside the skin still counts. Default 0.02 m. */
+    backoffM?: number;
+    /** Half-angle of the tilted-ray fan, degrees. Default 0.5. 0 = normal ray only. */
+    coneDeg?: number;
+    /** Restrict the measurement to regions matching these globs. Default: every region the body has. */
+    regions?: readonly string[];
+    /** Which base-body LOD scene supplies the vertices and region labels. Default 0. */
+    bodyLod?: number;
+}
+export interface RegionCoverage {
+    region: string;
+    /** Body vertices carrying this region label (highest-LOD body). */
+    vertices: number;
+    /** Occluded fraction, 0..1 — the minimum across LODs. */
+    fraction: number;
+    /** Largest number of NOT-occluded vertices of this region at any single LOD. */
+    bareVertices: number;
+    /** Occluded fraction at each LOD (body LOD k drawn with garment LOD k). */
+    perLod: number[];
+    /** Bounding box (metres, bind pose) of the not-occluded vertices at the LOD with the most of them; null when none. */
+    bareBounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    } | null;
+}
+export interface HideCoverageReport {
+    standoffM: number;
+    backoffM: number;
+    coneDeg: number;
+    /** LOD levels measured (body LOD k is paired with garment LOD k). */
+    lods: number;
+    /** Where the body's region labels came from. `_REGION` is the baked, published classification. */
+    regionSource: '_REGION' | 'dominant-joint';
+    /** Vertices whose region could not be placed (never counted toward any region). */
+    unclassifiedVertices: number;
+    regions: RegionCoverage[];
+    /**
+     * Per body LOD, what the hole-edge check needs (see `pruneHoleEdges`). Not enumerable, so JSON dumps of a
+     * report stay small; absent on a hand-built report, in which case the check is skipped.
+     */
+    lodSurfaces?: LodSurface[];
+}
+/** One body LOD as the engine's hide op sees it: labelled vertices, triangles, and which vertices a garment covers. */
+export interface LodSurface {
+    regions: Array<string | null>;
+    triangles: Uint32Array;
+    occluded: Uint8Array;
+}
+/**
+ * Per-region occlusion of the base body by `garment`. Both documents must be in their authored (bind) pose.
+ * See the file header for the metric and why it is built this way.
+ */
+export declare function measureHideCoverage(garment: Document, body: Document, options?: HideCoverageOptions): HideCoverageReport;
+/** `measureHideCoverage` on two GLB files (meshopt-compressed renditions included). */
+export declare function measureHideCoverageFiles(garmentPath: string, bodyPath: string, options?: HideCoverageOptions): Promise<HideCoverageReport>;
+export interface DerivedHide {
+    slotType: string;
+    threshold: number;
+    /** The slot's platform grant, expanded to the concrete regions the body has. */
+    granted: string[];
+    /** Granted regions the garment occludes (>= threshold). */
+    hidden: string[];
+    /** Granted regions left visible, each with the measured occluded fraction (and `holeEdge` when the region met the
+     *  threshold but hiding it would have left a bare triangle corner at its hole edge — see `pruneHoleEdges`). */
+    visible: Array<{
+        region: string;
+        fraction: number;
+        holeEdge?: boolean;
+    }>;
+    /** `hidden` collapsed to the grant's own globs where both sides are hidden (`body_thigh_*`). */
+    hideNodes: string[];
+    /** The `ops` array to hand to `publish-version --ops` (empty when nothing may be hidden). */
+    ops: Array<{
+        v: 'hide';
+        nodes: string[];
+    }>;
+    coverage: HideCoverageReport;
+}
+/** Collapse concrete regions back to the grant's globs: `body_thigh_l` + `body_thigh_r` -> `body_thigh_*`. */
+export declare function collapseRegionsToGlobs(hidden: readonly string[], grantGlobs: readonly string[]): string[];
+/**
+ * HOLE-EDGE CHECK. The region fraction alone lets a handful of bare vertices through (98 % of 363 torso vertices
+ * is seven of them), and those are exactly the ones on a hem: the engine collapses every triangle with >= 2
+ * corners in a hidden region, so a collapsed triangle whose third corner (or any corner) is NOT under the
+ * garment opens a notch in the skin the fabric does not cross — the black sawtooth under a jacket hem or a
+ * collar (Bomber Jacket, Clare Top, Casual Blazer, Black Shorts). So after the threshold: collapse triangles
+ * with the engine's rule at every LOD, and while any corner of a collapsed triangle is bare, drop the hidden
+ * region carrying the most such corners and recompute. A region dropped here is left visible (the push-out fit
+ * then handles its skin); a vertex facing the body itself already counts as covered. Returns the regions
+ * dropped. Skipped when the report carries no surfaces (a hand-built one).
+ */
+export declare function pruneHoleEdges(hidden: string[], coverage: HideCoverageReport): string[];
+/** The regions of `slotType`'s platform grant that `coverage` shows the garment fully occludes. */
+export declare function deriveHideFromCoverage(slotType: string, coverage: HideCoverageReport, threshold?: number): DerivedHide;
+/** One human line per granted region, for terminal output. */
+export declare function formatDerivedHide(derived: DerivedHide): string;