Code-first video & image, rendered natively on WebGPU.
feat(forge): baked skin textures, tiling pore normals, texture transforms and tangents; camera x/y/z tracks move the eye
okanasl5ce5575b56ec
diff --git a/.changeset/forge-human-skin.md b/.changeset/forge-human-skin.mdnew file mode 100644index 00000000..fb02e422--- /dev/null+++ b/.changeset/forge-human-skin.md@@ -0,0 +1,5 @@+---+"framefields": minor+---++Skin textures for `human()`: `addHuman` bakes a base color (blush, red lips, mottling) and a roughness map into the body's UVs, plus a tiling normal map of pores and creases (`skinTextures`, `poreNormalMap`). The GLB writer gains texture transforms on texture slots, generated tangents for normal-mapped primitives, and `encodePng`.diff --git a/nodes/node-compositor/src/renderers/transform3d.test.ts b/nodes/node-compositor/src/renderers/transform3d.test.tsindex 4f78c9af..61e8e226 100644--- a/nodes/node-compositor/src/renderers/transform3d.test.ts+++ b/nodes/node-compositor/src/renderers/transform3d.test.ts@@ -288,3 +288,55 @@ describe("GSAP Timeline 3D Compilation Continuity", () => {expect(cardStub.rotateX).toBe(25);});});++describe("Camera eye tracks", () => {+ it("moves the eye from x / y / z tracks as from cameraX / cameraY / cameraZ", () => {+ const keys = (id: string, prop: string, from: number, to: number) => ({+ id,+ prop,+ keyframes: [+ { id: `${id}0`, frame: 0, value: from },+ { id: `${id}1`, frame: 24, value: to },+ ],+ });+ const virtualMedia = {+ metadata: { width: 1920, height: 1080, durationMs: 2000 },+ operation: { op: "Compositor" },+ children: [+ {+ operation: {+ op: "CompositorLayer",+ id: "cam",+ kind: "camera",+ x: 960,+ y: 540,+ z: -1500,+ targetX: 960,+ targetY: 540,+ targetZ: 0,+ animation: {+ tracks: [+ keys("z", "z", -1500, -300),+ keys("x", "x", 960, 760),+ keys("ty", "targetY", 540, 200),+ ],+ },+ },+ children: [],+ },+ ],+ };+ const { tl, targetsById } = compileTimeline(+ "camera-eye-tracks",+ virtualMedia as CompilerVirtualMedia,+ { fps: 24, durationSec: 2 },+ );+ const cam = targetsById.cam;+ tl.seek(0);+ expect([cam.cameraX, cam.cameraZ, cam.targetY]).toEqual([960, -1500, 540]);+ tl.seek(1);+ expect([cam.cameraX, cam.cameraZ, cam.targetY]).toEqual([760, -300, 200]);+ // The camera's own y, untouched by any track, stays where it was put.+ expect(cam.cameraY).toBe(540);+ });+});diff --git a/nodes/node-compositor/src/shared/compiler.ts b/nodes/node-compositor/src/shared/compiler.tsindex 0aa26222..bcc71056 100644--- a/nodes/node-compositor/src/shared/compiler.ts+++ b/nodes/node-compositor/src/shared/compiler.ts@@ -552,6 +552,30 @@ export interface TruncationInfo {maxAuthoredFrame: number;}+/** A camera's `x` / `y` / `z` are its eye, the same as `cameraX` / `cameraY` / `cameraZ`. */+const CAMERA_EYE: Readonly<Record<string, AnimationTrack["prop"]>> = {+ x: "cameraX",+ y: "cameraY",+ z: "cameraZ",+};++/**+ * A layer's tracks, with a camera's `x` / `y` / `z` tracks driving its eye:+ * the eye is read from `cameraX` / `cameraY` / `cameraZ`, which the static+ * `x` / `y` / `z` seed, so a track left on `x` would never move it.+ */+function layerTracks(lop: {+ kind?: string;+ animation?: { tracks?: AnimationTrack[] };+}): AnimationTrack[] {+ const tracks = lop.animation?.tracks ?? [];+ if (lop.kind !== "camera") return tracks;+ return tracks.map((t) => {+ const eye = CAMERA_EYE[t.prop];+ return eye ? { ...t, prop: eye } : t;+ });+}+/*** Dedupe per compiled cache key — a fresh render of the same broken doc SHOULD* re-warn. Single-frame renders are the exception: each `renderFrame` call has@@ -884,7 +908,7 @@ export function compileTimeline(volumetricFogNoiseStrength: lop.volumetricFogNoiseStrength,};- for (const track of lop.animation?.tracks ?? []) {+ for (const track of layerTracks(lop)) {const source = track.source ?? { type: "keyframe" };if (source.type !== "keyframe") {(stub as Record<string, unknown>)[track.prop] = evaluateTrackAtFrame(@@ -952,7 +976,7 @@ export function compileTimeline(durationFrames = Math.max(1, Math.round((durationMs / 1000) * fps));}- for (const track of lop.animation?.tracks ?? []) {+ for (const track of layerTracks(lop)) {const { dropped, maxAuthoredFrame } = compileTrackToTimeline(tl,stub,diff --git a/packages/forge/src/document.ts b/packages/forge/src/document.tsindex b90db588..451b5ecd 100644--- a/packages/forge/src/document.ts+++ b/packages/forge/src/document.ts@@ -14,6 +14,7 @@* fs.writeFileSync("ithrael.glb", doc.toGlb());* ```*/+import { GlbBuilder } from "./glb-builder.js";import {type MaterialSpec,@@ -21,6 +22,7 @@ import {type TextureRef,} from "./material.js";import type { Skeleton } from "./skeleton.js";+import { computeTangents } from "./tangents.js";type Numbers = ArrayLike<number>;@@ -287,9 +289,10 @@ export class GltfDocument {floats(`${label} normals`, p.normals, 3, count),"VEC3",);- if (p.tangents)+ const tangents = p.tangents ?? this.generatedTangents(p);+ if (tangents)attributes.TANGENT = vertex(- floats(`${label} tangents`, p.tangents, 4, count),+ floats(`${label} tangents`, tangents, 4, count),"VEC4",);if (p.uvs)@@ -367,6 +370,24 @@ export class GltfDocument {return { json, maxJoint };}+ /**+ * Tangents for a normal-mapped triangle primitive that brings none, from+ * the UV set its normal map reads (glTF viewers otherwise each make+ * their own, and normal maps shade differently between them).+ */+ private generatedTangents(p: PrimitiveSpec): Float32Array | undefined {+ if (!p.material || !p.normals || (p.mode ?? "triangles") !== "triangles")+ return undefined;+ const normal = this.materials[p.material.material]?.normalTexture as+ | { texCoord?: number }+ | undefined;+ if (!normal) return undefined;+ const uvs = normal.texCoord === 1 ? p.uvs1 : p.uvs;+ return uvs+ ? computeTangents(p.positions, p.normals, uvs, p.indices)+ : undefined;+ }+/** A morph target's deltas, sparse when they move under half the vertices. */private targetAccessor(deltas: Float32Array, bounds: boolean): number {const count = deltas.length / 3;diff --git a/packages/forge/src/forge.test.ts b/packages/forge/src/forge.test.tsindex 7c181a6e..53eb92f4 100644--- a/packages/forge/src/forge.test.ts+++ b/packages/forge/src/forge.test.ts@@ -8,11 +8,13 @@ import { validateBytes } from "gltf-validator";import { describe, expect, it } from "vitest";import {boneGizmo,+ encodePng,GltfDocument,humanoidSkeleton,linearRgba,Skeleton,} from "./index.js";+import { readPng } from "./read-png.test-util.js";async function validate(glb: Uint8Array) {const report = await validateBytes(glb, { maxIssues: 50 });@@ -206,6 +208,47 @@ describe("GltfDocument", () => {expect(m.morphTargetNames).toEqual(["poke"]);});+ it("encodes PNGs that decode to the same pixels", () => {+ const w = 7;+ const h = 5;+ const rgba = Uint8Array.from(+ { length: w * h * 4 },+ (_, i) => (i * 37 + (i >> 3) * 11) & 0xff,+ );+ const png = encodePng(rgba, w, h);+ expect(Array.from(png.subarray(1, 4))).toEqual([0x50, 0x4e, 0x47]);+ const back = readPng(png);+ expect([back.width, back.height]).toEqual([w, h]);+ expect(Array.from(back.rgba)).toEqual(Array.from(rgba));+ });++ it("writes texture transforms that tile a map, and the loader applies them to that map alone", async () => {+ const s = strip(1, 10);+ const uvs = [0, 1, 1, 1, 0, 0, 1, 0];+ const doc = new GltfDocument();+ const png = encodePng(new Uint8Array(4 * 4 * 4).fill(200), 4, 4);+ const material = doc.addMaterial({+ colorTexture: doc.addTexture({ image: png, mimeType: "image/png" }),+ normalTexture: {+ texture: doc.addTexture({ image: png, mimeType: "image/png" }),+ scale: 0.5,+ transform: { scale: [8, 8] },+ },+ });+ doc.addNode({+ mesh: doc.addMesh({ primitives: [{ ...s, uvs, material }] }),+ });+ const glb = doc.toGlb();+ const report = await validate(glb);+ expect(report.issues).toEqual([]);+ expect(+ (doc.json() as { extensionsUsed: string[] }).extensionsUsed,+ ).toContain("KHR_texture_transform");+ const m = parseGLB(glb).meshes[0]!;+ expect(Array.from(m.uvs ?? [])).toEqual(uvs);+ expect(Array.from(m.mapUvs?.normal ?? [])).toEqual(uvs.map((x) => x * 8));+ });+it("writes every material extension in a valid form", async () => {const doc = new GltfDocument();const material = doc.addMaterial({diff --git a/packages/forge/src/human/add-human.ts b/packages/forge/src/human/add-human.tsindex aecad25f..fcac81c9 100644--- a/packages/forge/src/human/add-human.ts+++ b/packages/forge/src/human/add-human.ts@@ -11,12 +11,23 @@ import type {} from "../document.js";import type { MaterialSpec } from "../material.js";import type { HumanModel, HumanPart } from "./human.js";+import { type SkinOptions, skinTextures } from "./skin.js";export interface AddHumanOptions {/** Node name. Default "Human". */name?: string;- /** Skin material. Default: a warm skin with subsurface scattering. */+ /**+ * Skin material. Default: a warm skin with subsurface scattering. Its+ * `color` and `roughness` seed the baked skin textures; maps it sets+ * itself win over the baked ones.+ */skin?: MaterialSpec;+ /**+ * Baked skin textures (`skinTextures`): color with blush, lips and+ * mottling, roughness, and tiling pores. `false` leaves the skin a flat+ * color. Default: baked with the skin's color.+ */+ skinTextures?: SkinOptions | false;/** Eyeball material; its color texture defaults to the model's eye texture. */eyes?: MaterialSpec;/** Cornea material. Default: clear glass (IOR 1.376, 3 mm deep). */@@ -43,13 +54,16 @@ export function addHuman(): AddedHuman {const name = options.name ?? "Human";const rig = doc.addSkeleton(h.skeleton);+ const skinSpec: MaterialSpec = options.skin ?? {+ name: `${name}Skin`,+ color: "#d9b29a",+ roughness: 0.5,+ subsurface: { factor: 0.7, color: "#ff6a4a" },+ };const skin = doc.addMaterial(- options.skin ?? {- name: `${name}Skin`,- color: "#d9b29a",- roughness: 0.5,- subsurface: { factor: 0.7, color: "#ff6a4a" },- },+ options.skinTextures === false+ ? skinSpec+ : texturedSkin(doc, h, skinSpec, options.skinTextures ?? {}),);const eyes = doc.addMaterial({name: `${name}Eyes`,@@ -96,3 +110,35 @@ export function addHuman(for (const d of h.drivers) doc.addDriver(d);return { rig, nodes, materials: { skin, eyes, cornea, mouth } };}++/** The skin spec with baked maps in the slots it leaves empty. */+function texturedSkin(+ doc: GltfDocument,+ h: HumanModel,+ spec: MaterialSpec,+ options: SkinOptions,+): MaterialSpec {+ const maps = skinTextures(h, {+ color: spec.color ?? "#d9b29a",+ roughness: spec.roughness ?? 0.5,+ ...options,+ });+ const png = (image: Uint8Array) =>+ doc.addTexture({ image, mimeType: "image/png" });+ const repeat = maps.detailRepeat;+ return {+ ...spec,+ // The maps carry the color and roughness; the factors pass them through.+ color: spec.colorTexture ? spec.color : "#ffffff",+ roughness: spec.metallicRoughnessTexture ? spec.roughness : 1,+ metallic: 0,+ colorTexture: spec.colorTexture ?? png(maps.color),+ metallicRoughnessTexture:+ spec.metallicRoughnessTexture ?? png(maps.roughness),+ normalTexture: spec.normalTexture ?? {+ texture: png(maps.detail),+ scale: 0.45,+ transform: { scale: [repeat, repeat] },+ },+ };+}diff --git a/packages/forge/src/human/human.test.ts b/packages/forge/src/human/human.test.tsindex 6c3eb247..c9952553 100644--- a/packages/forge/src/human/human.test.ts+++ b/packages/forge/src/human/human.test.ts@@ -17,7 +17,9 @@ import {HumanAssetStore,human,humanCacheDir,+ skinTextures,} from "../index.js";+import { readPng } from "../read-png.test-util.js";import { macroTargets } from "./human.js";const sha = (b: Uint8Array) => createHash("sha256").update(b).digest("hex");@@ -243,6 +245,56 @@ describe.skipIf(!cached)("human (cached MakeHuman assets)", () => {expect(mouth.has("eyeBlinkLeft")).toBe(false);});+ it("bakes skin textures with red lips and a tiling pore map", async () => {+ const h = await human({});+ const maps = skinTextures(h, { size: 512 });+ const color = readPng(maps.color);+ expect(color.width).toBe(512);+ // Sample the map at a vertex's UV.+ const at = (v: number) => {+ const x = Math.min(511, Math.floor((h.body.uvs[v * 2] as number) * 512));+ const y = Math.min(+ 511,+ Math.floor((h.body.uvs[v * 2 + 1] as number) * 512),+ );+ const i = (y * 512 + x) * 4;+ return [color.rgba[i], color.rgba[i + 1], color.rgba[i + 2]] as [+ number,+ number,+ number,+ ];+ };+ // The front-most vertex of the lips (at the mouth corners' height) and of the forehead.+ const p = h.body.positions;+ const n = p.length / 3;+ const frontMost = (y0: number, y1: number) => {+ let best = 0;+ for (let v = 0; v < n; v++) {+ const y = (p[v * 3 + 1] as number) / h.height;+ if (+ y > y0 &&+ y < y1 &&+ Math.abs(p[v * 3] as number) < 0.5 &&+ (p[v * 3 + 2] as number) > (p[best * 3 + 2] as number)+ )+ best = v;+ }+ return best;+ };+ const lip = at(frontMost(0.891, 0.895));+ const brow = at(frontMost(0.96, 0.97));+ expect(lip[1] / lip[0]).toBeLessThan((brow[1] / brow[0]) * 0.85);+ const rough = readPng(maps.roughness);+ expect(rough.rgba[2]).toBe(0); // no metal+ const detail = readPng(maps.detail);+ // Tangent-space normals point out of the surface on average.+ let z = 0;+ for (let i = 2; i < detail.rgba.length; i += 4)+ z += detail.rgba[i] as number;+ expect(z / (detail.rgba.length / 4)).toBeGreaterThan(240);+ expect(maps.detailRepeat).toBeGreaterThan(5);+ });+it("adds named targets on top of the macro shape", async () => {const plain = await human({});const shaped = await human({ targets: { "nose/nose-base-up": 1 } });diff --git a/packages/forge/src/human/skin.ts b/packages/forge/src/human/skin.tsnew file mode 100644index 00000000..8b2af5a7--- /dev/null+++ b/packages/forge/src/human/skin.ts@@ -0,0 +1,489 @@+/**+ * Skin textures for a `human()`, made in code: a base color and a roughness+ * map baked into the body's own UV layout, and a tiling detail normal map+ * of pores and fine creases.+ *+ * Color varies where real skin does. Blood shows through as redness on+ * the cheeks, nose and eyelids, the lips are darker and redder, and+ * melanin and blood mottle the whole body at two scales. Roughness drops+ * on the wet lips and the oily nose. The facial regions come from the+ * face's own blend shapes (the lips are what `mouthPucker` moves, the+ * cheeks what `mouthSmile` lifts), so they follow any shaped face without+ * a hand-painted mask.+ */+import { type ColorInput, linearRgb } from "../color.js";+import { encodePng } from "../png.js";+import { Noise3 } from "../sculpt/noise.js";+import type { HumanModel } from "./human.js";++export interface SkinOptions {+ /** Base skin color (display sRGB). Default "#d9b29a". */+ color?: ColorInput;+ /** Lip color. Default: the skin, darker and redder. */+ lips?: ColorInput;+ /** Redness of the cheeks, nose and lids, 0 … 1. Default 0.5. */+ blush?: number;+ /** Mottling of the base color, 0 … 1. Default 0.5. */+ mottle?: number;+ /** Base roughness. Default 0.5. */+ roughness?: number;+ /** Color and roughness map size, pixels. Default 2048. */+ size?: number;+ /** Pore spacing, cm. Default 0.14. */+ poreSpacing?: number;+ seed?: number;+}++export interface SkinTextures {+ /** Base color, PNG (sRGB), on the body's UVs. */+ color: Uint8Array;+ /** glTF metallic-roughness PNG (roughness in green, metal 0), on the body's UVs. */+ roughness: Uint8Array;+ /** Tiling tangent-space normal map of pores and creases, PNG. */+ detail: Uint8Array;+ /** How many times `detail` repeats across the UV square for the pores to come out at `poreSpacing`. */+ detailRepeat: number;+}++const clamp01 = (x: number) => Math.min(1, Math.max(0, x));+const smooth = (a: number, b: number, x: number) => {+ const t = clamp01((x - a) / (b - a));+ return t * t * (3 - 2 * t);+};++/** Per vertex, how far a named blend shape moves it, over the shape's largest move (0 when the body has no such shape). */+function reach(body: HumanModel["body"], names: string[]): Float32Array {+ const n = body.positions.length / 3;+ const out = new Float32Array(n);+ for (const name of names) {+ const d = body.targets.find((t) => t.name === name)?.positions;+ if (!d) continue;+ let max = 0;+ const m = new Float32Array(n);+ for (let v = 0; v < n; v++) {+ m[v] = Math.hypot(+ d[v * 3] as number,+ d[v * 3 + 1] as number,+ d[v * 3 + 2] as number,+ );+ max = Math.max(max, m[v] as number);+ }+ if (max > 0)+ for (let v = 0; v < n; v++)+ out[v] = Math.max(out[v] as number, (m[v] as number) / max);+ }+ return out;+}++/**+ * The lips per vertex, 0 … 1. Pursing moves the mouth corners furthest,+ * which places them; the lips are the lens between them, the upper about+ * a sixth of the mouth's width tall and the lower a fifth, with soft edges.+ * Vertices inside the mouth fall in the lens too, which colors the inner+ * lips and gums alike.+ */+function lipMask(body: HumanModel["body"], pucker: Float32Array): Float32Array {+ const p = body.positions;+ const n = pucker.length;+ const corner = (side: 1 | -1) => {+ let best = -1;+ for (let v = 0; v < n; v++)+ if (+ side * (p[v * 3] as number) > 0 &&+ (best < 0 || (pucker[v] as number) > (pucker[best] as number))+ )+ best = v;+ return best;+ };+ const l = corner(1);+ const r = corner(-1);+ const out = new Float32Array(n);+ if (l < 0 || r < 0) return out;+ const cx = ((p[l * 3] as number) - (p[r * 3] as number)) / 2;+ const mx = ((p[l * 3] as number) + (p[r * 3] as number)) / 2;+ const my = ((p[l * 3 + 1] as number) + (p[r * 3 + 1] as number)) / 2;+ const mz = Math.min(p[l * 3 + 2] as number, p[r * 3 + 2] as number);+ const width = 2 * cx;+ const soft = width * 0.04;+ for (let v = 0; v < n; v++) {+ const x = ((p[v * 3] as number) - mx) / cx;+ const y = (p[v * 3 + 1] as number) - my;+ // Only the front of the face, not the back of the head.+ if (Math.abs(x) >= 1 || (p[v * 3 + 2] as number) < mz - width * 0.3)+ continue;+ const lens = Math.sqrt(1 - x * x);+ const extent = (y >= 0 ? 0.17 : 0.2) * width * lens;+ out[v] =+ (1 - smooth(extent - soft, extent + soft, Math.abs(y))) *+ (1 - smooth(0.88, 1, Math.abs(x)));+ }+ return out;+}++/** Facial regions per vertex, 0 … 1. */+function regions(body: HumanModel["body"]) {+ const pucker = reach(body, ["mouthPucker"]);+ const smile = reach(body, ["mouthSmileLeft", "mouthSmileRight"]);+ const nose = reach(body, ["noseWrinkle", "noseSneerLeft", "noseSneerRight"]);+ const lids = reach(body, ["eyeBlinkLeft", "eyeBlinkRight"]);+ const lips = lipMask(body, pucker);+ const n = pucker.length;+ const blush = new Float32Array(n);+ const lid = new Float32Array(n);+ for (let v = 0; v < n; v++) {+ blush[v] = Math.max(+ smooth(0.03, 0.35, smile[v] as number) * (1 - (lips[v] as number)),+ smooth(0.1, 0.6, nose[v] as number) * 0.8,+ );+ lid[v] = smooth(0.2, 0.7, lids[v] as number);+ }+ return { lips, blush, lid };+}++/** Model units (cm) per UV unit over the head, where the pores matter. */+function headTexelScale(body: HumanModel["body"], height: number): number {+ const p = body.positions;+ const uv = body.uvs;+ const idx = body.indices;+ const ratios: number[] = [];+ for (let f = 0; f < idx.length; f += 3) {+ const [a, b, c] = [idx[f], idx[f + 1], idx[f + 2]] as [+ number,+ number,+ number,+ ];+ if ((p[a * 3 + 1] as number) < height * 0.88) continue;+ const e = (i: number, j: number, k: number) =>+ (p[j * 3 + k] as number) - (p[i * 3 + k] as number);+ const ex = [e(a, b, 0), e(a, b, 1), e(a, b, 2)];+ const fx = [e(a, c, 0), e(a, c, 1), e(a, c, 2)];+ const area3 =+ Math.hypot(+ (ex[1] as number) * (fx[2] as number) -+ (ex[2] as number) * (fx[1] as number),+ (ex[2] as number) * (fx[0] as number) -+ (ex[0] as number) * (fx[2] as number),+ (ex[0] as number) * (fx[1] as number) -+ (ex[1] as number) * (fx[0] as number),+ ) / 2;+ const du1 = (uv[b * 2] as number) - (uv[a * 2] as number);+ const dv1 = (uv[b * 2 + 1] as number) - (uv[a * 2 + 1] as number);+ const du2 = (uv[c * 2] as number) - (uv[a * 2] as number);+ const dv2 = (uv[c * 2 + 1] as number) - (uv[a * 2 + 1] as number);+ const areaUv = Math.abs(du1 * dv2 - du2 * dv1) / 2;+ if (areaUv > 1e-12 && area3 > 0) ratios.push(Math.sqrt(area3 / areaUv));+ }+ ratios.sort((x, y) => x - y);+ return ratios[Math.floor(ratios.length / 2)] ?? 100;+}++/** Periodic 2D value lattice for tileable noise: `period` cells per tile. */+class TileNoise {+ private readonly values: Float32Array;+ constructor(+ private readonly period: number,+ seed: number,+ ) {+ let s = seed >>> 0;+ this.values = Float32Array.from({ length: period * period * 2 }, () => {+ s = (Math.imul(s ^ (s >>> 15), 0x2c1b3c6d) + 0x9e3779b9) >>> 0;+ return (s / 4294967296) * 2 - 1;+ });+ }++ /** Gradient noise at tile coordinates `u, v` in 0 … 1, about -1 … 1. */+ at(u: number, v: number): number {+ const P = this.period;+ const x = u * P;+ const y = v * P;+ const xi = Math.floor(x);+ const yi = Math.floor(y);+ const fx = x - xi;+ const fy = y - yi;+ const g = (i: number, j: number, dx: number, dy: number) => {+ const k = ((((i % P) + P) % P) + (((j % P) + P) % P) * P) * 2;+ const a = (this.values[k] as number) * Math.PI;+ return Math.cos(a) * dx + Math.sin(a) * dy;+ };+ const fade = (t: number) => t * t * t * (t * (t * 6 - 15) + 10);+ const sx = fade(fx);+ const sy = fade(fy);+ const n00 = g(xi, yi, fx, fy);+ const n10 = g(xi + 1, yi, fx - 1, fy);+ const n01 = g(xi, yi + 1, fx, fy - 1);+ const n11 = g(xi + 1, yi + 1, fx - 1, fy - 1);+ return (+ (n00 ++ sx * (n10 - n00) ++ sy * (n01 + sx * (n11 - n01) - n00 - sx * (n10 - n00))) *+ 1.4+ );+ }+}++/** Pore cells across one tile of the detail map. */+const PORE_CELLS = 24;++/**+ * A tiling tangent-space normal map of skin microrelief: pits on a+ * jittered grid (one per cell, varied in size and depth), two families of+ * fine creases crossing at an angle, and a soft unevenness.+ */+export function poreNormalMap(size = 512, seed = 7): Uint8Array {+ const N = size;+ const height = new Float32Array(N * N);+ let s = seed >>> 0;+ const rand = () => {+ s = (s + 0x6d2b79f5) >>> 0;+ let t = s;+ t = Math.imul(t ^ (t >>> 15), t | 1);+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;+ };+ const G = PORE_CELLS;+ const pores = Array.from({ length: G * G }, () => ({+ x: rand(),+ y: rand(),+ r: 0.18 + 0.2 * rand(),+ depth: 0.5 + 0.5 * rand(),+ }));+ // Crease networks at about the pore spacing: pores sit where they cross.+ const creaseA = new TileNoise(G, seed + 1);+ const creaseB = new TileNoise(Math.round(G * 1.5), seed + 2);+ const soft = new TileNoise(4, seed + 3);+ for (let py = 0; py < N; py++)+ for (let px = 0; px < N; px++) {+ const u = (px + 0.5) / N;+ const v = (py + 0.5) / N;+ let h = 0;+ const cx = Math.floor(u * G);+ const cy = Math.floor(v * G);+ for (let oy = -1; oy <= 1; oy++)+ for (let ox = -1; ox <= 1; ox++) {+ const gx = cx + ox;+ const gy = cy + oy;+ const pore = pores[(((gx % G) + G) % G) + (((gy % G) + G) % G) * G];+ if (!pore) continue;+ const dx = u * G - (gx + pore.x);+ const dy = v * G - (gy + pore.y);+ const d = Math.hypot(dx, dy) / pore.r;+ if (d < 1) h -= pore.depth * (1 - d * d) ** 2;+ }+ // Creases: the zero lines of two noises, sharpened into grooves.+ const a = creaseA.at(u + 0.05 * soft.at(v, u), v);+ const b = creaseB.at(u, v + 0.05 * soft.at(u, v));+ h -= 0.2 * (1 - smooth(0, 0.15, Math.abs(a)));+ h -= 0.12 * (1 - smooth(0, 0.12, Math.abs(b)));+ h += 0.3 * soft.at(u, v);+ height[py * N + px] = h;+ }+ const rgba = new Uint8Array(N * N * 4);+ const k = N / 64; // slope scale: a unit of height over 1/64 of the tile+ const hAt = (x: number, y: number) =>+ height[(((y % N) + N) % N) * N + (((x % N) + N) % N)] as number;+ for (let y = 0; y < N; y++)+ for (let x = 0; x < N; x++) {+ const dx = (hAt(x + 1, y) - hAt(x - 1, y)) * 0.5 * (k / 8);+ // +Y in a glTF normal map points up the image (toward row 0).+ const dy = (hAt(x, y - 1) - hAt(x, y + 1)) * 0.5 * (k / 8);+ const l = Math.hypot(dx, dy, 1);+ const i = (y * N + x) * 4;+ rgba[i] = Math.round((-dx / l) * 127.5 + 127.5);+ rgba[i + 1] = Math.round((-dy / l) * 127.5 + 127.5);+ rgba[i + 2] = Math.round((1 / l) * 127.5 + 127.5);+ rgba[i + 3] = 255;+ }+ return encodePng(rgba, N, N);+}++const toSrgb8 = (c: number) => {+ const x = clamp01(c);+ return Math.round(+ (x <= 0.0031308 ? x * 12.92 : 1.055 * x ** (1 / 2.4) - 0.055) * 255,+ );+};++/** Bakes the body's skin textures (see `SkinTextures`). */+export function skinTextures(+ h: Pick<HumanModel, "body" | "height">,+ options: SkinOptions = {},+): SkinTextures {+ const S = options.size ?? 2048;+ const base = linearRgb(options.color ?? "#d9b29a");+ const lipColor = options.lips+ ? linearRgb(options.lips)+ : ([base[0] * 0.78, base[1] * 0.42, base[2] * 0.45] as [+ number,+ number,+ number,+ ]);+ const blushAmount = options.blush ?? 0.5;+ const mottle = options.mottle ?? 0.5;+ const rough = options.roughness ?? 0.5;+ const seed = options.seed ?? 1;+ const { body } = h;+ const { lips, blush, lid } = regions(body);+ const melanin = new Noise3(seed);+ const blood = new Noise3(seed + 1);+ const p = body.positions;+ const uv = body.uvs;+ const idx = body.indices;++ // Per vertex: the skin's linear color and roughness. Broad variation+ // lives on the vertices (a few mm apart on the face); the texels add+ // the fine freckling.+ const n = p.length / 3;+ const vColor = new Float32Array(n * 3);+ const vRough = new Float32Array(n);+ for (let v = 0; v < n; v++) {+ const [x, y, z] = [+ p[v * 3] as number,+ p[v * 3 + 1] as number,+ p[v * 3 + 2] as number,+ ];+ const lip = lips[v] as number;+ const red =+ ((blush[v] as number) + (lid[v] as number) * 0.35) * blushAmount;+ const m = melanin.fbm(x / 8, y / 8, z / 8, 2);+ const b = blood.fbm(x / 3, y / 3, z / 3, 2);+ const dark = 1 - 0.08 * mottle * m;+ const flush = clamp01(red + 0.25 * mottle * b);+ for (let k = 0; k < 3; k++) {+ // Blood absorbs green and blue: redness scales them down.+ const skin =+ (base[k] as number) * dark * (k === 0 ? 1 : 1 - 0.28 * flush);+ vColor[v * 3 + k] = skin + ((lipColor[k] as number) - skin) * lip;+ }+ vRough[v] = clamp01(+ rough - 0.16 * lip - 0.04 * (blush[v] as number) + 0.04 * b,+ );+ }++ const color = new Float32Array(S * S * 3);+ const roughness = new Float32Array(S * S);+ const filled = new Uint8Array(S * S);+ const shade = (+ texel: number,+ w0: number,+ w1: number,+ w2: number,+ a: number,+ b: number,+ c: number,+ ) => {+ const x =+ w0 * (p[a * 3] as number) ++ w1 * (p[b * 3] as number) ++ w2 * (p[c * 3] as number);+ const y =+ w0 * (p[a * 3 + 1] as number) ++ w1 * (p[b * 3 + 1] as number) ++ w2 * (p[c * 3 + 1] as number);+ const z =+ w0 * (p[a * 3 + 2] as number) ++ w1 * (p[b * 3 + 2] as number) ++ w2 * (p[c * 3 + 2] as number);+ // Freckling at about 1 cm.+ const fine = 1 - 0.05 * mottle * melanin.at(x, y, z);+ for (let k = 0; k < 3; k++)+ color[texel * 3 + k] =+ (w0 * (vColor[a * 3 + k] as number) ++ w1 * (vColor[b * 3 + k] as number) ++ w2 * (vColor[c * 3 + k] as number)) *+ fine;+ roughness[texel] =+ w0 * (vRough[a] as number) ++ w1 * (vRough[b] as number) ++ w2 * (vRough[c] as number);+ filled[texel] = 1;+ };+ for (let f = 0; f < idx.length; f += 3) {+ const vs = [idx[f], idx[f + 1], idx[f + 2]] as [number, number, number];+ const X = vs.map((v) => (uv[v * 2] as number) * S - 0.5);+ const Y = vs.map((v) => (uv[v * 2 + 1] as number) * S - 0.5);+ const [x0, x1, x2] = X as [number, number, number];+ const [y0, y1, y2] = Y as [number, number, number];+ const area = (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0);+ if (Math.abs(area) < 1e-12) continue;+ const minX = Math.max(0, Math.floor(Math.min(x0, x1, x2)));+ const maxX = Math.min(S - 1, Math.ceil(Math.max(x0, x1, x2)));+ const minY = Math.max(0, Math.floor(Math.min(y0, y1, y2)));+ const maxY = Math.min(S - 1, Math.ceil(Math.max(y0, y1, y2)));+ for (let ty = minY; ty <= maxY; ty++)+ for (let tx = minX; tx <= maxX; tx++) {+ const w0 = ((x1 - tx) * (y2 - ty) - (x2 - tx) * (y1 - ty)) / area;+ const w1 = ((x2 - tx) * (y0 - ty) - (x0 - tx) * (y2 - ty)) / area;+ const w2 = 1 - w0 - w1;+ if (w0 < -1e-6 || w1 < -1e-6 || w2 < -1e-6) continue;+ shade(ty * S + tx, w0, w1, w2, vs[0], vs[1], vs[2]);+ }+ }+ dilate(S, filled, [color, 3], [roughness, 1]);++ const colorRgba = new Uint8Array(S * S * 4);+ const roughRgba = new Uint8Array(S * S * 4);+ for (let t = 0; t < S * S; t++) {+ for (let k = 0; k < 3; k++)+ colorRgba[t * 4 + k] = toSrgb8(color[t * 3 + k] as number);+ colorRgba[t * 4 + 3] = 255;+ roughRgba[t * 4] = 255;+ roughRgba[t * 4 + 1] = Math.round((roughness[t] as number) * 255);+ roughRgba[t * 4 + 2] = 0;+ roughRgba[t * 4 + 3] = 255;+ }+ const tileCm = (options.poreSpacing ?? 0.14) * PORE_CELLS;+ return {+ color: encodePng(colorRgba, S, S),+ roughness: encodePng(roughRgba, S, S),+ detail: poreNormalMap(512, seed + 7),+ detailRepeat: Math.max(+ 1,+ Math.round(headTexelScale(body, h.height) / tileCm),+ ),+ };+}++/**+ * Grows the painted texels outward into the empty ones, so filtering and+ * mipmaps at UV seams average skin with skin instead of with black.+ */+function dilate(+ S: number,+ filled: Uint8Array,+ ...channels: [Float32Array, number][]+) {+ let front = filled;+ for (let pass = 0; pass < 8; pass++) {+ const next = front.slice();+ for (let y = 0; y < S; y++)+ for (let x = 0; x < S; x++) {+ const t = y * S + x;+ if (front[t]) continue;+ let n = 0;+ for (const [dx, dy] of [+ [1, 0],+ [-1, 0],+ [0, 1],+ [0, -1],+ ] as const) {+ const xx = x + dx;+ const yy = y + dy;+ if (xx < 0 || yy < 0 || xx >= S || yy >= S || !front[yy * S + xx])+ continue;+ const s = yy * S + xx;+ for (const [data, size] of channels)+ for (let k = 0; k < size; k++)+ data[t * size + k] =+ (n ? (data[t * size + k] as number) : 0) ++ (data[s * size + k] as number);+ n++;+ }+ if (!n) continue;+ for (const [data, size] of channels)+ for (let k = 0; k < size; k++)+ data[t * size + k] = (data[t * size + k] as number) / n;+ next[t] = 1;+ }+ front = next;+ }+}diff --git a/packages/forge/src/index.ts b/packages/forge/src/index.tsindex b93834a3..fd78febd 100644--- a/packages/forge/src/index.ts+++ b/packages/forge/src/index.ts@@ -44,6 +44,12 @@ export {type HumanPart,human,} from "./human/human.js";+export {+ poreNormalMap,+ type SkinOptions,+ type SkinTextures,+ skinTextures,+} from "./human/skin.js";export { MAKEHUMAN_SOURCE } from "./human/source.js";export {HumanAssetStore,@@ -57,6 +63,7 @@ export {type TextureRef,type TextureSlot,} from "./material.js";+export { encodePng } from "./png.js";export {type Displacement,type Part,@@ -96,3 +103,4 @@ export {smoothNormals,subdivide,} from "./subdivide.js";+export { computeTangents } from "./tangents.js";diff --git a/packages/forge/src/material.ts b/packages/forge/src/material.tsindex eb89a29b..e0481d3b 100644--- a/packages/forge/src/material.ts+++ b/packages/forge/src/material.ts@@ -15,6 +15,16 @@ export interface TextureSlot {texture: TextureRef;/** UV set. Default 0. */texCoord?: number;+ /**+ * Placement of the image on the UVs (KHR_texture_transform): `scale`+ * repeats it (a tiling detail map), `offset` shifts it, `rotation` turns+ * it (degrees, counterclockwise).+ */+ transform?: {+ scale?: [number, number];+ offset?: [number, number];+ rotation?: number;+ };}export interface MaterialSpec {@@ -88,14 +98,27 @@ const slot = (t: TextureRef | TextureSlot): TextureSlot =>function textureInfo(t: TextureRef | TextureSlot,+ used: Set<string>,extra: Record<string, number> = {},-): Record<string, number> {+): Record<string, unknown> {const s = slot(t);- return {+ const info: Record<string, unknown> = {index: s.texture.texture,...(s.texCoord ? { texCoord: s.texCoord } : {}),...extra,};+ const tr = s.transform;+ if (tr && (tr.scale || tr.offset || tr.rotation)) {+ used.add("KHR_texture_transform");+ info.extensions = {+ KHR_texture_transform: {+ ...(tr.offset ? { offset: tr.offset } : {}),+ ...(tr.rotation ? { rotation: (tr.rotation * Math.PI) / 180 } : {}),+ ...(tr.scale ? { scale: tr.scale } : {}),+ },+ };+ }+ return info;}function check(name: string, v: number | undefined, lo = 0, hi = 1) {@@ -113,21 +136,24 @@ export function materialJson(m: MaterialSpec): MaterialJson {check("ior", m.ior, 1, 4);check("emissiveStrength", m.emissiveStrength, 0, 1e6);+ const used = new Set<string>();+ const info = (t: TextureRef | TextureSlot, extra?: Record<string, number>) =>+ textureInfo(t, used, extra);const pbr: Record<string, unknown> = {baseColorFactor: linearRgba(m.color ?? "#ffffff"),metallicFactor: m.metallic ?? 0,roughnessFactor: m.roughness ?? 0.5,};- if (m.colorTexture) pbr.baseColorTexture = textureInfo(m.colorTexture);+ if (m.colorTexture) pbr.baseColorTexture = info(m.colorTexture);if (m.metallicRoughnessTexture)- pbr.metallicRoughnessTexture = textureInfo(m.metallicRoughnessTexture);+ pbr.metallicRoughnessTexture = info(m.metallicRoughnessTexture);const json: Record<string, unknown> = { pbrMetallicRoughness: pbr };if (m.name) json.name = m.name;if (m.normalTexture) {const scale ="scale" in m.normalTexture ? m.normalTexture.scale : undefined;- json.normalTexture = textureInfo(+ json.normalTexture = info(m.normalTexture,scale === undefined ? {} : { scale },);@@ -137,14 +163,14 @@ export function materialJson(m: MaterialSpec): MaterialJson {"strength" in m.occlusionTexture? m.occlusionTexture.strength: undefined;- json.occlusionTexture = textureInfo(+ json.occlusionTexture = info(m.occlusionTexture,strength === undefined ? {} : { strength },);}if (m.emissive) json.emissiveFactor = linearRgb(m.emissive);if (m.emissiveTexture) {- json.emissiveTexture = textureInfo(m.emissiveTexture);+ json.emissiveTexture = info(m.emissiveTexture);json.emissiveFactor ??= [1, 1, 1];}if (m.alphaMode && m.alphaMode !== "opaque") {@@ -249,5 +275,5 @@ export function materialJson(m: MaterialSpec): MaterialJson {};}if (Object.keys(ext).length) json.extensions = ext;- return { json, extensions: Object.keys(ext) };+ return { json, extensions: [...Object.keys(ext), ...used] };}diff --git a/packages/forge/src/png.ts b/packages/forge/src/png.tsnew file mode 100644index 00000000..c2e72378--- /dev/null+++ b/packages/forge/src/png.ts@@ -0,0 +1,65 @@+/**+ * A minimal PNG encoder for textures built in code: 8-bit RGBA, each row+ * filtered with Paeth (smooth maps compress several times better than+ * unfiltered), deflated by Node's zlib.+ */+import { crc32, deflateSync } from "node:zlib";++function chunk(type: string, data: Uint8Array): Uint8Array {+ const out = new Uint8Array(12 + data.length);+ const view = new DataView(out.buffer);+ view.setUint32(0, data.length);+ for (let i = 0; i < 4; i++) out[4 + i] = type.charCodeAt(i);+ out.set(data, 8);+ view.setUint32(8 + data.length, crc32(out.subarray(4, 8 + data.length)));+ return out;+}++const paeth = (a: number, b: number, c: number) => {+ const p = a + b - c;+ const pa = Math.abs(p - a);+ const pb = Math.abs(p - b);+ const pc = Math.abs(p - c);+ return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;+};++/** `rgba` holds width × height × 4 bytes, rows top to bottom. */+export function encodePng(+ rgba: Uint8Array,+ width: number,+ height: number,+): Uint8Array {+ if (rgba.length !== width * height * 4)+ throw new Error(`png: ${rgba.length} bytes for ${width}x${height} RGBA`);+ const stride = width * 4;+ const raw = new Uint8Array((stride + 1) * height);+ for (let y = 0; y < height; y++) {+ const row = y * (stride + 1);+ raw[row] = 4; // Paeth+ for (let x = 0; x < stride; x++) {+ const i = y * stride + x;+ const a = x >= 4 ? (rgba[i - 4] as number) : 0;+ const b = y > 0 ? (rgba[i - stride] as number) : 0;+ const c = x >= 4 && y > 0 ? (rgba[i - stride - 4] as number) : 0;+ raw[row + 1 + x] = ((rgba[i] as number) - paeth(a, b, c)) & 0xff;+ }+ }+ const header = new Uint8Array(13);+ const hv = new DataView(header.buffer);+ hv.setUint32(0, width);+ hv.setUint32(4, height);+ header.set([8, 6, 0, 0, 0], 8); // 8-bit, RGBA, deflate, adaptive, no interlace+ const parts = [+ new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),+ chunk("IHDR", header),+ chunk("IDAT", deflateSync(raw, { level: 6 })),+ chunk("IEND", new Uint8Array(0)),+ ];+ const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));+ let at = 0;+ for (const p of parts) {+ out.set(p, at);+ at += p.length;+ }+ return out;+}diff --git a/packages/forge/src/read-png.test-util.ts b/packages/forge/src/read-png.test-util.tsnew file mode 100644index 00000000..ee3b809c--- /dev/null+++ b/packages/forge/src/read-png.test-util.ts@@ -0,0 +1,49 @@+/** Decodes the 8-bit RGBA PNGs `encodePng` writes (tests only). */+import { inflateSync } from "node:zlib";++export function readPng(png: Uint8Array): {+ width: number;+ height: number;+ rgba: Uint8Array;+} {+ const view = new DataView(png.buffer, png.byteOffset, png.byteLength);+ let at = 8;+ let width = 0;+ let height = 0;+ const idat: Uint8Array[] = [];+ while (at < png.length) {+ const length = view.getUint32(at);+ const type = String.fromCharCode(...png.subarray(at + 4, at + 8));+ const data = png.subarray(at + 8, at + 8 + length);+ if (type === "IHDR") {+ width = view.getUint32(at + 8);+ height = view.getUint32(at + 12);+ } else if (type === "IDAT") idat.push(data);+ at += 12 + length;+ }+ const raw = inflateSync(Buffer.concat(idat));+ const stride = width * 4;+ const rgba = new Uint8Array(stride * height);+ for (let y = 0; y < height; y++) {+ const filter = raw[y * (stride + 1)] as number;+ for (let x = 0; x < stride; x++) {+ const i = y * stride + x;+ const a = x >= 4 ? (rgba[i - 4] as number) : 0;+ const b = y > 0 ? (rgba[i - stride] as number) : 0;+ const c = x >= 4 && y > 0 ? (rgba[i - stride - 4] as number) : 0;+ const p = a + b - c;+ const pa = Math.abs(p - a);+ const pb = Math.abs(p - b);+ const pc = Math.abs(p - c);+ const pred = [+ 0,+ a,+ b,+ (a + b) >> 1,+ pa <= pb && pa <= pc ? a : pb <= pc ? b : c,+ ][filter] as number;+ rgba[i] = ((raw[y * (stride + 1) + 1 + x] as number) + pred) & 0xff;+ }+ }+ return { width, height, rgba };+}diff --git a/packages/forge/src/tangents.ts b/packages/forge/src/tangents.tsnew file mode 100644index 00000000..fa68a97a--- /dev/null+++ b/packages/forge/src/tangents.ts@@ -0,0 +1,90 @@+/**+ * Per-vertex tangents for normal mapping, from a triangle mesh's UVs+ * (Lengyel's method): each triangle's direction of increasing u, summed+ * at its corners, made perpendicular to the vertex normal; the fourth+ * component is the handedness of the UV mapping (+1 or -1).+ */+type Numbers = ArrayLike<number>;++export function computeTangents(+ positions: Numbers,+ normals: Numbers,+ uvs: Numbers,+ indices?: Numbers,+): Float32Array {+ const n = positions.length / 3;+ const idx = indices ?? Array.from({ length: n }, (_, i) => i);+ const tan = new Float64Array(n * 3);+ const bit = new Float64Array(n * 3);+ for (let f = 0; f + 2 < idx.length; f += 3) {+ const a = idx[f] as number;+ const b = idx[f + 1] as number;+ const c = idx[f + 2] as number;+ const e1 = [0, 1, 2].map(+ (k) =>+ (positions[b * 3 + k] as number) - (positions[a * 3 + k] as number),+ );+ const e2 = [0, 1, 2].map(+ (k) =>+ (positions[c * 3 + k] as number) - (positions[a * 3 + k] as number),+ );+ const du1 = (uvs[b * 2] as number) - (uvs[a * 2] as number);+ const dv1 = (uvs[b * 2 + 1] as number) - (uvs[a * 2 + 1] as number);+ const du2 = (uvs[c * 2] as number) - (uvs[a * 2] as number);+ const dv2 = (uvs[c * 2 + 1] as number) - (uvs[a * 2 + 1] as number);+ const det = du1 * dv2 - du2 * dv1;+ if (Math.abs(det) < 1e-20) continue;+ const r = 1 / det;+ for (let k = 0; k < 3; k++) {+ const t = (dv2 * (e1[k] as number) - dv1 * (e2[k] as number)) * r;+ const s = (du1 * (e2[k] as number) - du2 * (e1[k] as number)) * r;+ for (const v of [a, b, c]) {+ tan[v * 3 + k] = (tan[v * 3 + k] as number) + t;+ bit[v * 3 + k] = (bit[v * 3 + k] as number) + s;+ }+ }+ }+ const out = new Float32Array(n * 4);+ for (let v = 0; v < n; v++) {+ const N = [+ normals[v * 3] as number,+ normals[v * 3 + 1] as number,+ normals[v * 3 + 2] as number,+ ];+ let T = [+ tan[v * 3] as number,+ tan[v * 3 + 1] as number,+ tan[v * 3 + 2] as number,+ ];+ const d =+ (N[0] as number) * (T[0] as number) ++ (N[1] as number) * (T[1] as number) ++ (N[2] as number) * (T[2] as number);+ T = T.map((t, k) => t - (N[k] as number) * d);+ let l = Math.hypot(...T);+ if (l < 1e-12) {+ // No UV gradient here: any direction perpendicular to the normal.+ const ax = Math.abs(N[0] as number) < 0.9 ? [1, 0, 0] : [0, 1, 0];+ const dd = ax.reduce((s, x, k) => s + x * (N[k] as number), 0);+ T = ax.map((x, k) => x - (N[k] as number) * dd);+ l = Math.hypot(...T);+ }+ const B = [+ bit[v * 3] as number,+ bit[v * 3 + 1] as number,+ bit[v * 3 + 2] as number,+ ];+ const cross = [+ (N[1] as number) * (T[2] as number) - (N[2] as number) * (T[1] as number),+ (N[2] as number) * (T[0] as number) - (N[0] as number) * (T[2] as number),+ (N[0] as number) * (T[1] as number) - (N[1] as number) * (T[0] as number),+ ];+ const w =+ cross.reduce((s, x, k) => s + x * (B[k] as number), 0) < 0 ? -1 : 1;+ out.set(+ [(T[0] as number) / l, (T[1] as number) / l, (T[2] as number) / l, w],+ v * 4,+ );+ }+ return out;+}diff --git a/plugins/framefields/skills/framefields-compose/SKILL.md b/plugins/framefields/skills/framefields-compose/SKILL.mdindex e7684cf0..428fc444 100644--- a/plugins/framefields/skills/framefields-compose/SKILL.md+++ b/plugins/framefields/skills/framefields-compose/SKILL.md@@ -476,6 +476,8 @@ Layer.glb("rig.glb", { rotateX: 180, pose: { LeftArm: { rotateZ: 90 } } });**Realistic humans (`human`)**: `await human({ sex, age, muscle, weight, proportions, ethnicity, height, targets })` builds a rigged, skinned body from MakeHuman's CC0 base mesh: `sex` 0 female … 1 male, `age` 0 baby / 0.1875 child / 0.5 adult / 1 old, `muscle` and `weight` 0 … 1 (0.5 average), `height` in cm (exact), and any MakeHuman target by path with a weight (`targets: { "nose/nose-base-up": 0.6, "ears/l-ear-shape-pointed": 1 }`). Its skeleton is placed from the shaped body with Mixamo names on the main bones (twist, extra spine and face bones keep MakeHuman names), so `pose`, `aim` and `retarget({ rig: "mixamo" })` work; weights are MakeHuman's painted weights; UVs come with the mesh. Assets download on first use (about 2 MB base plus only the targets a body needs; 131 MB if every target is used) into `~/.cache/framefields/makehuman`, verified by SHA-256 (`FRAMEFIELDS_CACHE_DIR`, `FRAMEFIELDS_HUMAN_BASE_URL` for a mirror). Use `sculpt` for costume, armor and non-human characters.+**Skin**: `addHuman` bakes the skin's textures by default (`skinTextures`, about 3 s): a base color on the body's UVs with blush on the cheeks, nose and lids, darker red lips and two scales of mottling; a roughness map (wet lips, oily nose); and a tiling normal map of pores and fine creases, repeated (via `KHR_texture_transform`) so pores come out about 1.4 mm apart. The regions come from the face's own blend shapes, so they follow any shaped face. Tune it with `addHuman(doc, h, { skin: { color, roughness, subsurface }, skinTextures: { lips, blush, mottle, size, poreSpacing, seed } })`; `skinTextures: false` keeps a flat color. `skinTextures(h)` returns the PNGs for your own materials, and `poreNormalMap()` the detail map alone. The writer adds tangents to normal-mapped primitives that bring none, and texture slots take `transform: { scale, offset, rotation }`. Each map samples with its own glTF sampler (wrap per axis, filter), so a tiling detail map works under a clamped base color.+**Faces**: the body carries facial blend shapes under ARKit names (`eyeBlinkLeft`, `eyeWideRight`, `eyeSquintLeft`, `browDownLeft`, `browInnerUp`, `browOuterUpRight`, `noseSneerLeft`, `jawOpen`, `mouthSmileLeft`, `mouthFrownRight`, `mouthPucker`, `mouthFunnel`, `mouthPressLeft`, `mouthStretchRight`, `mouthUpperUpLeft`, `mouthLowerDownRight`, `mouthDimpleLeft`, `mouthRollLower`, plus `noseFlareLeft/Right`, `noseWrinkle`, `mouthPart`, `neckTense`; the list is `FACE_SHAPES`), built from MakeHuman's expression units for the body's ethnicity; symmetric mouth units are split into sides. `human().mouth` (teeth and tongue) moves with `jawOpen` and the lips. Drive them per layer with `morphs`: names match the file's target names case-insensitively, each a number, keys or a signal; unnamed targets keep the clip's weights. `expressions: false` leaves them out; `subdivide: 1` (Loop, blend shapes and weights carried exactly) smooths faceting in close-ups. Morph targets that move few vertices are written sparse (a face-rigged body is about 2 MB, 6 MB subdivided).```ts