@melite/formats 0.0.0-stage → 0.1.4-alpha

package/lib/pngMetaInfo.js

@@ -0,0 +1,127 @@
+/**
+ * Minimal PNG tEXt chunk injector / reader.
+ *
+ * PNG format: 8-byte signature, then a sequence of chunks.
+ * Each chunk: [4-byte length][4-byte type][N-byte data][4-byte CRC].
+ * tEXt chunk data: <keyword>\0<text> (both Latin-1, no compression).
+ *
+ * We use the key "tech_noir" to store generation params as JSON.
+ */
+const PNG_SIG = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+const KEY = "tech_noir";
+// ── CRC-32 table ────────────────────────────────────────────────────────────
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let i = 0; i < 256; i++) {
+        let c = i;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[i] = c;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function u32be(n) {
+    return new Uint8Array([(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff]);
+}
+function readU32BE(buf, offset) {
+    return ((buf[offset] << 24) | (buf[offset + 1] << 16) | (buf[offset + 2] << 8) | buf[offset + 3]) >>> 0;
+}
+function makeChunk(type, data) {
+    const typeBytes = new TextEncoder().encode(type);
+    const crcInput = new Uint8Array(4 + data.length);
+    crcInput.set(typeBytes, 0);
+    crcInput.set(data, 4);
+    const crc = crc32(crcInput);
+    const chunk = new Uint8Array(4 + 4 + data.length + 4);
+    chunk.set(u32be(data.length), 0);
+    chunk.set(typeBytes, 4);
+    chunk.set(data, 8);
+    chunk.set(u32be(crc), 8 + data.length);
+    return chunk;
+}
+/** Inject generation params into a PNG as a tEXt chunk (inserted after IHDR). */
+export function injectPngMeta(b64, params) {
+    try {
+        const bin = atob(b64);
+        const buf = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            buf[i] = bin.charCodeAt(i);
+        // Verify PNG signature
+        for (let i = 0; i < 8; i++)
+            if (buf[i] !== PNG_SIG[i])
+                return b64;
+        // Find end of IHDR chunk (sig=8, length=4, type=4, data=13, crc=4 → 33 bytes)
+        const ihdrEnd = 8 + 4 + 4 + 13 + 4; // = 33
+        // Build tEXt chunk: "tech_noir\0<json>"
+        const enc = new TextEncoder();
+        const keyBytes = enc.encode(KEY);
+        const valBytes = enc.encode(JSON.stringify(params));
+        const chunkData = new Uint8Array(keyBytes.length + 1 + valBytes.length);
+        chunkData.set(keyBytes, 0);
+        chunkData[keyBytes.length] = 0;
+        chunkData.set(valBytes, keyBytes.length + 1);
+        const textChunk = makeChunk("tEXt", chunkData);
+        // Splice in after IHDR
+        const out = new Uint8Array(buf.length + textChunk.length);
+        out.set(buf.slice(0, ihdrEnd), 0);
+        out.set(textChunk, ihdrEnd);
+        out.set(buf.slice(ihdrEnd), ihdrEnd + textChunk.length);
+        // Re-encode to base64
+        let result = "";
+        for (let i = 0; i < out.length; i++)
+            result += String.fromCharCode(out[i]);
+        return btoa(result);
+    }
+    catch (e) {
+        // NO SILENT SWALLOW — chunk injection failed (corrupt PNG, bad base64,
+        // OOM on huge buffers). Log so we know metadata is being dropped, then
+        // return the original unmodified so the image itself still renders.
+        console.error('[png-meta] injectPngMeta failed, returning original:', e);
+        return b64;
+    }
+}
+/** Read generation params from a PNG's tEXt chunk, or null if not present. */
+export function readPngMeta(b64OrDataUrl) {
+    try {
+        const b64 = b64OrDataUrl.startsWith("data:") ? b64OrDataUrl.split(",")[1] : b64OrDataUrl;
+        const bin = atob(b64);
+        const buf = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            buf[i] = bin.charCodeAt(i);
+        // Walk chunks from offset 8
+        let pos = 8;
+        while (pos + 12 <= buf.length) {
+            const length = readU32BE(buf, pos);
+            const type = String.fromCharCode(buf[pos + 4], buf[pos + 5], buf[pos + 6], buf[pos + 7]);
+            if (type === "IEND")
+                break;
+            if (type === "tEXt" && length > KEY.length) {
+                const data = buf.slice(pos + 8, pos + 8 + length);
+                const nullIdx = data.indexOf(0);
+                if (nullIdx !== -1) {
+                    const key = new TextDecoder().decode(data.slice(0, nullIdx));
+                    if (key === KEY) {
+                        const val = new TextDecoder().decode(data.slice(nullIdx + 1));
+                        return JSON.parse(val);
+                    }
+                }
+            }
+            pos += 4 + 4 + length + 4;
+        }
+        return null;
+    }
+    catch (e) {
+        // NO SILENT SWALLOW — parse failure means either the input wasn't a
+        // valid PNG/data-URL, or the tEXt payload was malformed. Log so we know
+        // metadata is being dropped, then return null ("no params found").
+        console.error('[png-meta] readPngMeta failed:', e);
+        return null;
+    }
+}
+//# sourceMappingURL=pngMetaInfo.js.map

package/lib/poseCodec.d.ts

@@ -0,0 +1,20 @@
+/** poseCodec — the PURE codec half of the old lib/text-to-pose:
+ * byte/b64 codecs + the SOMA-77 bone topology. Fetch-free by law —
+ * the fetch-based off-main-thread decode stays app-side (lib/text-to-pose.ts). */
+/** Canonical SOMA-77 mesh vertex count.
+ *
+ *  The LBS skinning weights are keyed to this exact vertex topology, so every
+ *  shaped mesh — anny, mhr, soma, custom GLB — must have exactly this many
+ *  vertices. The backend echoes the actual count via PoseMotion.vertex_count;
+ *  this constant is the fallback for old responses that don't include it and
+ *  the source of truth for UI prompts (CustomMeshLoader, etc.).
+ */
+export declare const SOMA_VERTEX_COUNT = 18056;
+export declare const SOMA77_BONE_CONNECTIONS: [number, number][];
+/** Encode a Uint8Array to a base64 string.
+ *
+ *  Processes the input in 32KB chunks because String.fromCharCode.apply has
+ *  a ~65K argument limit on some engines (the historical V8 stack-arg limit).
+ *  Uses Array.from() rather than the brittle `as unknown as number[]` cast. */
+export declare function encodeBufferToB64(bytes: Uint8Array): string;
+//# sourceMappingURL=poseCodec.d.ts.map

package/lib/poseCodec.js

@@ -0,0 +1,61 @@
+/** poseCodec — the PURE codec half of the old lib/text-to-pose:
+ * byte/b64 codecs + the SOMA-77 bone topology. Fetch-free by law —
+ * the fetch-based off-main-thread decode stays app-side (lib/text-to-pose.ts). */
+/** Canonical SOMA-77 mesh vertex count.
+ *
+ *  The LBS skinning weights are keyed to this exact vertex topology, so every
+ *  shaped mesh — anny, mhr, soma, custom GLB — must have exactly this many
+ *  vertices. The backend echoes the actual count via PoseMotion.vertex_count;
+ *  this constant is the fallback for old responses that don't include it and
+ *  the source of truth for UI prompts (CustomMeshLoader, etc.).
+ */
+export const SOMA_VERTEX_COUNT = 18056;
+// Generated from SOMASkeleton77.bone_order_names_with_parents
+// (vendor/kimodo/kimodo/skeleton/definitions.py). 77 joints → 76 bones.
+// Joint order: Hips(0) Spine1(1) Spine2(2) Chest(3) Neck1(4) Neck2(5) Head(6)
+//   HeadEnd(7) Jaw(8) LeftEye(9) RightEye(10) LeftShoulder(11) LeftArm(12)
+//   LeftForeArm(13) LeftHand(14) [LeftHand fingers 15..38]
+//   RightShoulder(39) RightArm(40) RightForeArm(41) RightHand(42)
+//   [RightHand fingers 43..66] LeftLeg(67) LeftShin(68) LeftFoot(69)
+//   LeftToeBase(70) LeftToeEnd(71) RightLeg(72) RightShin(73) RightFoot(74)
+//   RightToeBase(75) RightToeEnd(76).
+export const SOMA77_BONE_CONNECTIONS = [
+    // Spine + head
+    [0, 1], [1, 2], [2, 3], [3, 4], [4, 5], [5, 6],
+    [6, 7], [6, 8], [6, 9], [6, 10],
+    // Left shoulder + arm + thumb chain
+    [3, 11], [11, 12], [12, 13], [13, 14],
+    [14, 15], [15, 16], [16, 17], [17, 18],
+    // Left index / middle / ring / pinky
+    [14, 19], [19, 20], [20, 21], [21, 22], [22, 23],
+    [14, 24], [24, 25], [25, 26], [26, 27], [27, 28],
+    [14, 29], [29, 30], [30, 31], [31, 32], [32, 33],
+    [14, 34], [34, 35], [35, 36], [36, 37], [37, 38],
+    // Right shoulder + arm + thumb chain
+    [3, 39], [39, 40], [40, 41], [41, 42],
+    [42, 43], [43, 44], [44, 45], [45, 46],
+    // Right index / middle / ring / pinky
+    [42, 47], [47, 48], [48, 49], [49, 50], [50, 51],
+    [42, 52], [52, 53], [53, 54], [54, 55], [55, 56],
+    [42, 57], [57, 58], [58, 59], [59, 60], [60, 61],
+    [42, 62], [62, 63], [63, 64], [64, 65], [65, 66],
+    // Left leg + foot + toes
+    [0, 67], [67, 68], [68, 69], [69, 70], [70, 71],
+    // Right leg + foot + toes
+    [0, 72], [72, 73], [73, 74], [74, 75], [75, 76],
+];
+// ── Base64 encode (32KB chunks — engine stack-arg limits) ────────────────
+/** Encode a Uint8Array to a base64 string.
+ *
+ *  Processes the input in 32KB chunks because String.fromCharCode.apply has
+ *  a ~65K argument limit on some engines (the historical V8 stack-arg limit).
+ *  Uses Array.from() rather than the brittle `as unknown as number[]` cast. */
+export function encodeBufferToB64(bytes) {
+    let bin = "";
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        bin += String.fromCharCode.apply(null, Array.from(bytes.subarray(i, Math.min(i + CHUNK, bytes.length))));
+    }
+    return btoa(bin);
+}
+//# sourceMappingURL=poseCodec.js.map

package/lib/poseTransforms.d.ts

@@ -0,0 +1,73 @@
+export declare const KP: {
+    readonly NOSE: 0;
+    readonly NECK: 1;
+    readonly R_SHOULDER: 2;
+    readonly R_ELBOW: 3;
+    readonly R_WRIST: 4;
+    readonly L_SHOULDER: 5;
+    readonly L_ELBOW: 6;
+    readonly L_WRIST: 7;
+    readonly R_HIP: 8;
+    readonly R_KNEE: 9;
+    readonly R_ANKLE: 10;
+    readonly L_HIP: 11;
+    readonly L_KNEE: 12;
+    readonly L_ANKLE: 13;
+    readonly R_EYE: 14;
+    readonly L_EYE: 15;
+    readonly R_EAR: 16;
+    readonly L_EAR: 17;
+};
+export declare const NUM_KEYPOINTS = 18;
+export declare const FLAT_LENGTH: number;
+export type Keypoints = number[];
+export interface PosePreset {
+    id: string;
+    name: string;
+    category: string;
+    description: string;
+    tags: string[];
+    render_url: string;
+    keypoints: Keypoints;
+}
+export interface PoseAdjustments {
+    leftArmRaise: number;
+    rightArmRaise: number;
+    leftElbowBend: number;
+    rightElbowBend: number;
+    weightShift: number;
+    crouch: number;
+    headTilt: number;
+    spineLean: number;
+}
+export declare const DEFAULT_ADJUSTMENTS: PoseAdjustments;
+export declare function applyAdjustments(base: Keypoints, adj: PoseAdjustments): Keypoints;
+export declare function fetchPosePresets(): Promise<PosePreset[]>;
+/**
+ * Render keypoints to a PNG skeleton image via the backend.
+ * Returns a Blob (image/png) suitable for object URLs.
+ */
+export declare function renderCustomPose(keypoints: Keypoints, opts?: {
+    width?: number;
+    height?: number;
+}): Promise<Blob>;
+/**
+ * Convert a Blob to a base64 data URL — for saving to the asset store
+ * (which expects data URLs, not object URLs, for persistence).
+ * Delegates to the shared readAsDataURL (@melite/ui SlotSquare — the
+ * ONE read path every slot-shaped attach uses).
+ */
+export declare function blobToDataUrl(blob: Blob): Promise<string>;
+/**
+ * Convert 2D flat COCO-18 keypoints to approximate 3D positions.
+ *
+ * The 2D keypoints are flattened [x, y, confidence, ...] in image-pixel space
+ * (typically 1024×1024). This function maps them into the SOMA coordinate
+ * frame: +X = subject's left, +Y = up, +Z = forward.
+ *
+ * Z-values are estimated from joint category (shoulders forward, hips back).
+ * The result is suitable for the 3D PoseViewer — not physically accurate but
+ * visually coherent for preset poses.
+ */
+export declare function flatTo3D(flat: number[]): [number, number, number][];
+//# sourceMappingURL=poseTransforms.d.ts.map

package/lib/poseTransforms.js

@@ -0,0 +1,237 @@
+/**
+ * Pose Studio — keypoint transform utilities.
+ *
+ * COCO-18 keypoints: 18 joints × (x, y, confidence) = 54 numbers in a flat
+ * array. This is the same format DWPose outputs (see media/workflows/utils/dwpose.py)
+ * and the same format the /poser/* backend endpoints accept.
+ *
+ * The Pose Studio UI lets the user pick a base preset, then tweak it with
+ * semantic sliders (arm raise, elbow bend, head tilt, etc.). Each slider
+ * maps to a transform on the base keypoint array. The result is POSTed to
+ * /poser/render, which returns a PNG skeleton image.
+ *
+ * Convention: subject's RIGHT side = image LEFT (so right-side keypoints
+ * have smaller X values than left-side ones).
+ */
+import { apiFetch } from "@melite/catalog";
+import { readAsDataURL } from "./readFile.js";
+// ── COCO-18 keypoint indices ─────────────────────────────────────────────
+export const KP = {
+    NOSE: 0, NECK: 1,
+    R_SHOULDER: 2, R_ELBOW: 3, R_WRIST: 4,
+    L_SHOULDER: 5, L_ELBOW: 6, L_WRIST: 7,
+    R_HIP: 8, R_KNEE: 9, R_ANKLE: 10,
+    L_HIP: 11, L_KNEE: 12, L_ANKLE: 13,
+    R_EYE: 14, L_EYE: 15, R_EAR: 16, L_EAR: 17,
+};
+export const NUM_KEYPOINTS = 18;
+export const FLAT_LENGTH = NUM_KEYPOINTS * 3; // 54
+export const DEFAULT_ADJUSTMENTS = {
+    leftArmRaise: 0,
+    rightArmRaise: 0,
+    leftElbowBend: 0,
+    rightElbowBend: 0,
+    weightShift: 0,
+    crouch: 0,
+    headTilt: 0,
+    spineLean: 0,
+};
+// ── Math helpers ─────────────────────────────────────────────────────────
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function getX(kp, idx) {
+    return kp[idx * 3];
+}
+function getY(kp, idx) {
+    return kp[idx * 3 + 1];
+}
+function setXY(kp, idx, x, y) {
+    kp[idx * 3] = x;
+    kp[idx * 3 + 1] = y;
+}
+function translate(kp, idx, dx, dy) {
+    kp[idx * 3] += dx;
+    kp[idx * 3 + 1] += dy;
+}
+// ── Transform flow ───────────────────────────────────────────────────
+// Each transform mutates the (already-cloned) keypoint array.
+// Order matters: crouch and weight shift move everything; arm/elbow transforms
+// then operate on the post-shifted shoulder positions; head tilt and spine
+// lean are last because they're independent of limb positions.
+export function applyAdjustments(base, adj) {
+    const kp = [...base]; // shallow clone — numbers are immutable so this is enough
+    // 1. Crouch — compress Y of all keypoints around the hip pivot.
+    if (adj.crouch !== 0) {
+        const hipY = getY(kp, KP.R_HIP); // pivot at hip height
+        const scale = 1 - adj.crouch * 0.30; // up to 30% compression
+        for (let i = 0; i < NUM_KEYPOINTS; i++) {
+            const y = getY(kp, i);
+            setXY(kp, i, getX(kp, i), hipY + (y - hipY) * scale);
+        }
+    }
+    // 2. Weight shift — translate all keypoints horizontally.
+    if (adj.weightShift !== 0) {
+        const dx = adj.weightShift * 80;
+        for (let i = 0; i < NUM_KEYPOINTS; i++) {
+            translate(kp, i, dx, 0);
+        }
+    }
+    // 3. Spine lean — translate head/neck/shoulders forward (down in image space)
+    // or backward (up in image space). Arms follow shoulders partially.
+    if (adj.spineLean !== 0) {
+        const dy = adj.spineLean * 60;
+        const upperBody = [
+            KP.NOSE, KP.NECK, KP.R_SHOULDER, KP.L_SHOULDER,
+            KP.R_EYE, KP.L_EYE, KP.R_EAR, KP.L_EAR,
+        ];
+        for (const idx of upperBody)
+            translate(kp, idx, 0, dy);
+        // Elbows and wrists trail the shoulder motion (less, since arms have inertia)
+        translate(kp, KP.R_ELBOW, 0, dy * 0.5);
+        translate(kp, KP.L_ELBOW, 0, dy * 0.5);
+        translate(kp, KP.R_WRIST, 0, dy * 0.3);
+        translate(kp, KP.L_WRIST, 0, dy * 0.3);
+    }
+    // 4. Head tilt — rotate the head cluster (nose, eyes, ears) around the neck.
+    if (adj.headTilt !== 0) {
+        const nx = getX(kp, KP.NECK);
+        const ny = getY(kp, KP.NECK);
+        const angle = adj.headTilt * 0.35; // ~20° max
+        const cos = Math.cos(angle);
+        const sin = Math.sin(angle);
+        for (const idx of [KP.NOSE, KP.R_EYE, KP.L_EYE, KP.R_EAR, KP.L_EAR]) {
+            const dx = getX(kp, idx) - nx;
+            const dy = getY(kp, idx) - ny;
+            setXY(kp, idx, nx + dx * cos - dy * sin, ny + dx * sin + dy * cos);
+        }
+    }
+    // 5. Arm raises — pull elbow + wrist toward a "raised above head" target.
+    // Slider > 0 raises; slider < 0 is a no-op (can't go lower than "at side").
+    raiseArm(kp, KP.L_SHOULDER, KP.L_ELBOW, KP.L_WRIST, Math.max(0, adj.leftArmRaise));
+    raiseArm(kp, KP.R_SHOULDER, KP.R_ELBOW, KP.R_WRIST, Math.max(0, adj.rightArmRaise));
+    // 6. Elbow bends — draw wrist toward the midline (neck X).
+    bendElbow(kp, KP.L_WRIST, KP.NECK, adj.leftElbowBend);
+    bendElbow(kp, KP.R_WRIST, KP.NECK, adj.rightElbowBend);
+    return kp;
+}
+function raiseArm(kp, shoulderIdx, elbowIdx, wristIdx, amount) {
+    if (amount === 0)
+        return;
+    const shx = getX(kp, shoulderIdx);
+    // Target wrist position: directly above shoulder, near top of frame.
+    const targetWristX = shx;
+    const targetWristY = 80;
+    // Target elbow position: halfway between current and target wrist.
+    const targetElbowX = lerp(getX(kp, elbowIdx), targetWristX, 0.5);
+    const targetElbowY = lerp(getY(kp, elbowIdx), targetWristY, 0.5);
+    // Lerp wrist fully, elbow partially (it trails).
+    setXY(kp, wristIdx, lerp(getX(kp, wristIdx), targetWristX, amount), lerp(getY(kp, wristIdx), targetWristY, amount));
+    setXY(kp, elbowIdx, lerp(getX(kp, elbowIdx), targetElbowX, amount * 0.7), lerp(getY(kp, elbowIdx), targetElbowY, amount * 0.7));
+}
+function bendElbow(kp, wristIdx, neckIdx, amount) {
+    if (amount === 0)
+        return;
+    const targetX = lerp(getX(kp, wristIdx), getX(kp, neckIdx), 0.65);
+    const targetY = lerp(getY(kp, wristIdx), getY(kp, neckIdx), 0.30);
+    setXY(kp, wristIdx, lerp(getX(kp, wristIdx), targetX, amount), lerp(getY(kp, wristIdx), targetY, amount));
+}
+// ── Preset fetch / render helpers ────────────────────────────────────────
+export async function fetchPosePresets() {
+    const res = await apiFetch("/v1/poser/presets");
+    if (!res.ok)
+        throw new Error(`Failed to fetch pose presets: ${res.status}`);
+    return res.json();
+}
+/**
+ * Render keypoints to a PNG skeleton image via the backend.
+ * Returns a Blob (image/png) suitable for object URLs.
+ */
+export async function renderCustomPose(keypoints, opts = {}) {
+    const res = await apiFetch("/v1/poser/render", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            keypoints,
+            width: opts.width ?? 1024,
+            height: opts.height ?? 1024,
+            line_width: 5,
+            point_radius: 6,
+        }),
+    });
+    if (!res.ok) {
+        const txt = await res.text();
+        throw new Error(`Pose render failed: ${res.status} ${txt}`);
+    }
+    return res.blob();
+}
+/**
+ * Convert a Blob to a base64 data URL — for saving to the asset store
+ * (which expects data URLs, not object URLs, for persistence).
+ * Delegates to the shared readAsDataURL (@melite/ui SlotSquare — the
+ * ONE read path every slot-shaped attach uses).
+ */
+export function blobToDataUrl(blob) {
+    return readAsDataURL(blob);
+}
+// ── 2D → approximate 3D projection ──────────────────────────────────────────
+/** SOMA coordinate space constants. */
+const SOMA_SCALE = 0.6; // maps 1024px width to ~0.6 SOMA units (hip-to-hip)
+const SOMA_CENTER_X = 0.5; // image center as fraction of width
+const SOMA_CENTER_Y = 0.55; // approximate hip center as fraction of height
+/** Default z-depths per COCO-18 joint (in SOMA units). Negative = toward viewer. */
+const DEFAULT_Z = {
+    [KP.NOSE]: 0.10,
+    [KP.NECK]: 0.08,
+    [KP.R_SHOULDER]: 0.05,
+    [KP.R_ELBOW]: 0.02,
+    [KP.R_WRIST]: 0.00,
+    [KP.L_SHOULDER]: 0.05,
+    [KP.L_ELBOW]: 0.02,
+    [KP.L_WRIST]: 0.00,
+    [KP.R_HIP]: -0.05,
+    [KP.R_KNEE]: -0.02,
+    [KP.R_ANKLE]: 0.00,
+    [KP.L_HIP]: -0.05,
+    [KP.L_KNEE]: -0.02,
+    [KP.L_ANKLE]: 0.00,
+    [KP.R_EYE]: 0.15,
+    [KP.L_EYE]: 0.15,
+    [KP.R_EAR]: 0.12,
+    [KP.L_EAR]: 0.12,
+};
+/**
+ * Convert 2D flat COCO-18 keypoints to approximate 3D positions.
+ *
+ * The 2D keypoints are flattened [x, y, confidence, ...] in image-pixel space
+ * (typically 1024×1024). This function maps them into the SOMA coordinate
+ * frame: +X = subject's left, +Y = up, +Z = forward.
+ *
+ * Z-values are estimated from joint category (shoulders forward, hips back).
+ * The result is suitable for the 3D PoseViewer — not physically accurate but
+ * visually coherent for preset poses.
+ */
+export function flatTo3D(flat) {
+    const result = [];
+    for (let i = 0; i < NUM_KEYPOINTS; i++) {
+        const x = flat[i * 3] ?? 0;
+        const y = flat[i * 3 + 1] ?? 0;
+        const c = flat[i * 3 + 2] ?? 0;
+        if (c < 0.1) {
+            // Low confidence — place joint at a neutral position
+            result.push([0, 0, 0]);
+            continue;
+        }
+        // Normalize from image coords to SOMA coords
+        const sx = (x / 1024 - SOMA_CENTER_X) * SOMA_SCALE * 2;
+        // Y is inverted in image coords (0 = top)
+        const sy = (SOMA_CENTER_Y - y / 1024) * SOMA_SCALE * 2;
+        // Every COCO-18 joint 0..17 is tabled in DEFAULT_Z above (the loop
+        // bound is NUM_KEYPOINTS = 18), so the lookup is always present —
+        // no fallback to cover. Keep the table and loop in lockstep.
+        const sz = DEFAULT_Z[i];
+        result.push([sx, sy, sz]);
+    }
+    return result;
+}
+//# sourceMappingURL=poseTransforms.js.map

package/lib/poserSkin.d.ts

@@ -0,0 +1,75 @@
+export interface SkinMeshData {
+    vertices: number[][];
+    faces: number[][];
+}
+export interface IdentityGroup {
+    label: string;
+    start: number;
+    count: number;
+}
+export interface LocalChangeGroup {
+    label: string;
+    indices: number[];
+    category: "body" | "face";
+}
+export interface LocalChangeSpace {
+    dims: number;
+    labels: string[];
+    defaults: number[];
+    range: [number, number];
+    groups: LocalChangeGroup[];
+}
+/**
+ * A community MakeHuman .target blendshape exposed as a single slider.
+ *
+ * Each entry corresponds to a .target file in media/motion's
+ * references/makehuman_targets/ directory. The `id` is the slider key sent
+ * back to POST /poser/skin/mesh as `custom_targets[id]`. The `name` and
+ * `description` power the slider row UI.
+ */
+export interface CustomTargetItem {
+    id: string;
+    name: string;
+    description: string;
+    glyph: string;
+    /** Absolute path on the server (debug only - not used by the UI). */
+    file?: string;
+}
+export interface CustomTargetSpace {
+    /** Ordered list - one slider row per entry. */
+    items: CustomTargetItem[];
+    defaults: number[];
+    range: [number, number];
+}
+export interface IdentitySpace {
+    identity_model: string;
+    dims: number;
+    labels: string[];
+    defaults: number[];
+    range: [number, number];
+    groups: IdentityGroup[] | null;
+    local_changes: LocalChangeSpace | null;
+    /**
+     * Community .target blendshapes (Anny only). null for MHR/SOMA - the UI
+     * hides the Stylization tab in that case.
+     */
+    custom_targets: CustomTargetSpace | null;
+}
+export type PreviewPose = "tpose" | "arms_down";
+
+
+
+
+export interface BindMeshQuery {
+    identityModel?: string;
+    identityCoeffs?: number[] | null;
+    localChanges?: Record<string, number> | null;
+    previewPose?: PreviewPose | null;
+    customTargets?: Record<string, number> | null;
+}
+export declare function fetchBindMesh(query?: BindMeshQuery): Promise<SkinMeshData>;
+export declare function fetchIdentitySpace(model: string): Promise<IdentitySpace>;
+/** SkinMeshData → flat Float32Array positions (V*3) in METERS with the
+ *  floor lift applied (the body-studio preview geometry path). */
+export declare function buildFlatPositions(meshData: SkinMeshData): Float32Array;
+//# sourceMappingURL=poserSkin.d.ts.map