Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
/**
* Capture gate scoring: unit tests for the pure math behind the /create/selfie
* viewfinder and review-still gates (src/selfie-gates.js). These pin the
* thresholds to the reconstruction pipeline's real failure modes: the no-face
* hard rejection, the 35-degree morph-yaw ceiling, provider blur failures,
* and the dim/backlit lighting band the robustness benchmark models.
*/
import { describe, it, expect } from 'vitest';
import { GATES, SLOT_PRESETS, grayFaceStats, gradeFrame } from '../src/selfie-gates.js';
// Build a w*h grey buffer from a (x,y)=>value fn.
function grey(w, h, fn) {
const a = new Float32Array(w * h);
for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) a[y * w + x] = fn(x, y);
return a;
}
describe('grayFaceStats', () => {
it('reports the mean luma of a flat buffer exactly', () => {
const { luma } = grayFaceStats(grey(16, 16, () => 128), 16, 16);
expect(luma).toBe(128);
});
it('reports zero blur response on a flat buffer', () => {
const { blurStddev } = grayFaceStats(grey(16, 16, () => 128), 16, 16);
expect(blurStddev).toBe(0);
});
it('reports a higher blur response for detailed content than smooth content', () => {
const detail = grayFaceStats(grey(32, 32, (x, y) => ((x + y) % 2 ? 255 : 0)), 32, 32);
const smooth = grayFaceStats(grey(32, 32, (x) => x * 4), 32, 32);
expect(detail.blurStddev).toBeGreaterThan(smooth.blurStddev);
});
it('a checkerboard face crop clears the live blur gate; a gradient does not', () => {
const detail = grayFaceStats(grey(64, 64, (x, y) => ((x + y) % 2 ? 255 : 0)), 64, 64);
const smooth = grayFaceStats(grey(64, 64, (x) => x * 2), 64, 64);
expect(detail.blurStddev).toBeGreaterThan(GATES.BLUR_STDDEV_MIN);
expect(smooth.blurStddev).toBeLessThan(GATES.BLUR_STDDEV_MIN);
});
it('keeps the blur floor above the blurred population measured on real faces', () => {
// Measured on six real portrait photographs framed as 720x1280 phone
// selfies: the worst heavily-blurred reading (GaussianBlur r=10) was
// 9.4, the least sharp real face read 22.8. A floor outside that band
// is decoration: it either never fires or rejects usable captures.
expect(GATES.BLUR_STDDEV_MIN).toBeGreaterThan(9.4);
expect(GATES.BLUR_STDDEV_MIN).toBeLessThan(22.8);
});
it('reports the blown-highlight share of the crop', () => {
const half = grayFaceStats(grey(16, 16, (x, y) => (y < 8 ? 255 : 128)), 16, 16);
expect(half.clippedFrac).toBeCloseTo(0.5, 5);
expect(grayFaceStats(grey(16, 16, () => 128), 16, 16).clippedFrac).toBe(0);
});
it('counts only pixels at or above the clip level', () => {
expect(grayFaceStats(grey(8, 8, () => GATES.CLIP_LEVEL - 1), 8, 8).clippedFrac).toBe(0);
expect(grayFaceStats(grey(8, 8, () => GATES.CLIP_LEVEL), 8, 8).clippedFrac).toBe(1);
});
it('handles degenerate sizes without NaN', () => {
expect(grayFaceStats(grey(2, 2, () => 50), 2, 2)).toEqual({ luma: 50, blurStddev: 0, clippedFrac: 0 });
expect(grayFaceStats([], 0, 0)).toEqual({ luma: 0, blurStddev: 0, clippedFrac: 0 });
});
});
describe('gradeFrame', () => {
const goodFrontal = {
faceFound: true,
slot: 'frontal',
yaw: 2,
noseX: 0.5,
noseY: 0.5,
blur: 20,
luma: 120,
};
it('fails everything and names the face gate when no face is found', () => {
const g = gradeFrame({ faceFound: false });
expect(g.allPass).toBe(false);
expect(g.faceFound).toBe(false);
expect(g.reason).toMatch(/face/i);
});
it('passes a sharp, lit, centred frontal with no retake reason', () => {
const g = gradeFrame(goodFrontal);
expect(g.allPass).toBe(true);
expect(g.reason).toBeNull();
});
it('keeps the frontal window inside the morph-safe yaw ceiling', () => {
expect(SLOT_PRESETS.frontal.max).toBeLessThan(GATES.MORPH_YAW_MAX);
expect(Math.abs(SLOT_PRESETS.frontal.min)).toBeLessThan(GATES.MORPH_YAW_MAX);
});
it('rejects a turned head on the frontal slot and says to face the camera', () => {
const g = gradeFrame({ ...goodFrontal, yaw: 25 });
expect(g.yawOk).toBe(false);
expect(g.allPass).toBe(false);
expect(g.reason).toMatch(/straight on/i);
});
it('rejects a frontal pose on the left slot and says to turn left', () => {
const g = gradeFrame({ ...goodFrontal, slot: 'left', yaw: 2 });
expect(g.yawOk).toBe(false);
expect(g.reason).toMatch(/left/i);
});
it('accepts a ~45 degree turn on the left slot', () => {
const g = gradeFrame({ ...goodFrontal, slot: 'left', yaw: 45 });
expect(g.yawOk).toBe(true);
expect(g.allPass).toBe(true);
});
it('accepts a ~-45 degree turn on the right slot', () => {
const g = gradeFrame({ ...goodFrontal, slot: 'right', yaw: -45 });
expect(g.yawOk).toBe(true);
});
it('rejects an off-centre face and says to recenter', () => {
const g = gradeFrame({ ...goodFrontal, noseX: 0.9 });
expect(g.centered).toBe(false);
expect(g.reason).toMatch(/center/i);
});
it('rejects a blurry frame and says to hold steady', () => {
const g = gradeFrame({ ...goodFrontal, blur: GATES.BLUR_STDDEV_MIN - 0.5 });
expect(g.blurOk).toBe(false);
expect(g.reason).toMatch(/steady|blurry/i);
});
it('rejects a dark frame and says to find light', () => {
const g = gradeFrame({ ...goodFrontal, luma: GATES.LUMA_MIN - 5 });
expect(g.lumaOk).toBe(false);
expect(g.reason).toMatch(/dark|light/i);
});
it('rejects a blown-out frame and says to reduce glare', () => {
const g = gradeFrame({ ...goodFrontal, luma: GATES.LUMA_MAX + 5 });
expect(g.lumaOk).toBe(false);
expect(g.reason).toMatch(/bright|glare/i);
});
it('accepts the exact luma boundaries', () => {
expect(gradeFrame({ ...goodFrontal, luma: GATES.LUMA_MIN }).lumaOk).toBe(true);
expect(gradeFrame({ ...goodFrontal, luma: GATES.LUMA_MAX }).lumaOk).toBe(true);
});
it('rejects a face blown out in patches even when its mean luma looks fine', () => {
// Window glare pins part of the face to white while the rest stays in
// shadow, so the mean lands mid-band. Clipping also *raises* Laplacian
// response, so neither the luma nor the blur gate can see it.
const g = gradeFrame({
...goodFrontal,
luma: 130,
clippedFrac: GATES.CLIPPED_FRAC_MAX + 0.05,
});
expect(g.lumaOk).toBe(false);
expect(g.allPass).toBe(false);
expect(g.reason).toMatch(/bright|light|window/i);
});
it('accepts the specular highlights every real face carries', () => {
const g = gradeFrame({ ...goodFrontal, clippedFrac: GATES.CLIPPED_FRAC_MAX });
expect(g.lumaOk).toBe(true);
expect(g.allPass).toBe(true);
});
it('treats a missing clipping measurement as unclipped', () => {
expect(gradeFrame(goodFrontal).lumaOk).toBe(true);
});
it('names the yaw fix before the blur fix when both fail', () => {
const g = gradeFrame({ ...goodFrontal, yaw: 30, blur: 0 });
expect(g.reason).toMatch(/straight on/i);
});
it('blames the light, not the hands, when a dim frame also reads as blurry', () => {
// A dim room suppresses contrast, so the Laplacian response collapses
// and the blur gate trips alongside the luma one. "Hold steady" would
// send the user to fix a symptom while the room stayed dark.
const g = gradeFrame({ ...goodFrontal, luma: GATES.LUMA_MIN - 5, blur: 0 });
expect(g.blurOk).toBe(false);
expect(g.lumaOk).toBe(false);
expect(g.reason).toMatch(/dark|light/i);
});
it('still names blur when the frame is well lit', () => {
const g = gradeFrame({ ...goodFrontal, blur: 0 });
expect(g.reason).toMatch(/steady|blurry/i);
});
it('falls back to the frontal window for an unknown slot', () => {
const g = gradeFrame({ ...goodFrontal, slot: 'profile' });
expect(g.yawOk).toBe(true);
});
});