Skip to content

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.md
index 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