Skip to content

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.

7.6 KB
Raw Blame
/**
 * Selfie refinement — unit tests for the deterministic helpers.
 *
 * The DOM/MediaPipe wrappers (segmentation, detection, canvas compositing) are
 * exercised in the browser; these tests pin the pure math that decides whether
 * a photo is usable and how the subject gets framed — the logic that turns the
 * "whole photo on a card" input into a clean, centred subject.
 */

import { describe, it, expect } from 'vitest';
import {
	laplacianVariance,
	flatnessScore,
	meanSaturation,
	assessPhotoQuality,
	computeSubjectFrame,
	maskBoundingBox,
	smoothstep,
} from '../src/selfie-refine.js';

// Build a w×h grey buffer from a (x,y)=>value fn.
function grey(w, h, fn) {
	const a = new Uint8Array(w * h);
	for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) a[y * w + x] = fn(x, y) | 0;
	return a;
}
// Build a w×h RGBA buffer from a (x,y)=>[r,g,b,a] fn.
function rgba(w, h, fn) {
	const a = new Uint8ClampedArray(w * h * 4);
	for (let y = 0; y < h; y++)
		for (let x = 0; x < w; x++) {
			const [r, g, b, al = 255] = fn(x, y);
			const i = (y * w + x) * 4;
			a[i] = r; a[i + 1] = g; a[i + 2] = b; a[i + 3] = al;
		}
	return a;
}

describe('laplacianVariance', () => {
	it('is ~0 for a flat image', () => {
		expect(laplacianVariance(grey(16, 16, () => 128), 16, 16)).toBe(0);
	});

	it('is higher for an edged image than a flat one', () => {
		const flat = laplacianVariance(grey(16, 16, () => 128), 16, 16);
		const edged = laplacianVariance(grey(16, 16, (x) => (x < 8 ? 0 : 255)), 16, 16);
		expect(edged).toBeGreaterThan(flat);
	});

	it('returns 0 on degenerate sizes', () => {
		expect(laplacianVariance(grey(2, 2, () => 50), 2, 2)).toBe(0);
	});
});

describe('flatnessScore', () => {
	it('is 1 for a perfectly flat image', () => {
		expect(flatnessScore(grey(12, 12, () => 90), 12, 12)).toBe(1);
	});

	it('is low for a high-frequency checkerboard', () => {
		const checker = grey(12, 12, (x, y) => ((x + y) % 2 ? 255 : 0));
		expect(flatnessScore(checker, 12, 12)).toBeLessThan(0.1);
	});
});

describe('meanSaturation', () => {
	it('is 0 for greyscale', () => {
		expect(meanSaturation(rgba(8, 8, () => [120, 120, 120]), 8, 8, 1)).toBe(0);
	});

	it('is ~1 for fully saturated red', () => {
		expect(meanSaturation(rgba(8, 8, () => [255, 0, 0]), 8, 8, 1)).toBeCloseTo(1, 5);
	});
});

describe('assessPhotoQuality', () => {
	const sharpClearFace = {
		width: 1000, height: 1000,
		faceCount: 1,
		faceBox: { x: 350, y: 300, w: 300, h: 300 },
		sharpness: 500, flatness: 0.2, saturation: 0.2,
	};

	it('blocks when there is no face', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, faceCount: 0, faceBox: null });
		expect(r.verdict).toBe('block');
		expect(r.primary).toBe('no-face');
	});

	it('does not block when the detector never loaded, since that says nothing about the photo', () => {
		// null means "no detector", which is how the 2026-09-11 stall surfaced:
		// with the face model unreachable, a perfectly good selfie was being told
		// it had no face in it, and the reconstruction request was never sent.
		const r = assessPhotoQuality({ ...sharpClearFace, faceCount: null, faceBox: null });
		expect(r.verdict).not.toBe('block');
		expect(r.issues).not.toContain('no-face');
	});

	it('does not flag multiple faces when the count is unknown', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, faceCount: null, faceBox: null });
		expect(r.issues).not.toContain('multiple-faces');
	});

	it('still blocks a photo the detector really did examine and found no face in', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, faceCount: 0, faceBox: null });
		expect(r.verdict).toBe('block');
		expect(r.primary).toBe('no-face');
	});

	it('passes a sharp, well-framed real photo', () => {
		const r = assessPhotoQuality(sharpClearFace);
		expect(r.verdict).toBe('good');
		expect(r.issues).toEqual([]);
	});

	it('warns "blurry" on a soft photo', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, sharpness: 10 });
		expect(r.verdict).toBe('warn');
		expect(r.primary).toBe('blurry');
	});

	it('flags a flat, saturated illustration', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, flatness: 0.85, saturation: 0.6 });
		expect(r.issues).toContain('illustration');
		expect(r.primary).toBe('illustration'); // illustration outranks other warnings
	});

	it('does NOT flag a plain-background photo as an illustration (flat but desaturated)', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, flatness: 0.85, saturation: 0.1 });
		expect(r.issues).not.toContain('illustration');
	});

	it('warns "far" when the face is small in frame', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, faceBox: { x: 470, y: 470, w: 90, h: 90 } });
		expect(r.issues).toContain('far');
	});

	it('warns "dark" when the measured face luma is below the lighting gate', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, luma: 25 });
		expect(r.verdict).toBe('warn');
		expect(r.primary).toBe('dark');
	});

	it('warns "bright" when the measured face luma is blown out', () => {
		const r = assessPhotoQuality({ ...sharpClearFace, luma: 240 });
		expect(r.issues).toContain('bright');
	});

	it('does not judge lighting when luma was not measured', () => {
		const r = assessPhotoQuality(sharpClearFace);
		expect(r.issues).not.toContain('dark');
		expect(r.issues).not.toContain('bright');
	});
});

describe('computeSubjectFrame', () => {
	it('returns a centred square within bounds for a centred face', () => {
		const f = computeSubjectFrame({ x: 400, y: 300, w: 200, h: 200 }, 1000, 1000);
		expect(f.w).toBe(f.h);
		expect(f.x).toBeGreaterThanOrEqual(0);
		expect(f.y).toBeGreaterThanOrEqual(0);
		expect(f.x + f.w).toBeLessThanOrEqual(1000);
		expect(f.y + f.h).toBeLessThanOrEqual(1000);
		// Horizontally centred on the face centre (500).
		expect(f.x + f.w / 2).toBeCloseTo(500, 0);
	});

	it('clamps a square against the right edge without overflow', () => {
		const f = computeSubjectFrame({ x: 900, y: 300, w: 200, h: 200 }, 1000, 1000);
		expect(f.x + f.w).toBeLessThanOrEqual(1000);
		expect(f.w).toBe(f.h);
	});

	it('fits the largest square inside a small image', () => {
		const f = computeSubjectFrame({ x: 150, y: 80, w: 120, h: 120 }, 400, 300);
		expect(f.w).toBe(f.h);
		expect(f.w).toBeLessThanOrEqual(300);
		expect(f.x + f.w).toBeLessThanOrEqual(400);
		expect(f.y + f.h).toBeLessThanOrEqual(300);
	});

	it('widens to include a broad subject (shoulders)', () => {
		const narrow = computeSubjectFrame({ x: 450, y: 300, w: 100, h: 100 }, 2000, 2000);
		const wide = computeSubjectFrame({ x: 450, y: 300, w: 100, h: 100 }, 2000, 2000, {
			subjectBox: { x: 200, y: 250, w: 1000, h: 1200 },
		});
		expect(wide.w).toBeGreaterThan(narrow.w);
	});
});

describe('maskBoundingBox', () => {
	it('scales the foreground box into image space', () => {
		// 4×4 mask, a 2×2 foreground block at (1,1)-(2,2); image is 8×8 (scale 2).
		const mask = new Float32Array(16);
		for (const [x, y] of [[1, 1], [2, 1], [1, 2], [2, 2]]) mask[y * 4 + x] = 1;
		const box = maskBoundingBox(mask, 4, 4, 8, 8, 0.5);
		expect(box).toEqual({ x: 2, y: 2, w: 4, h: 4 });
	});

	it('returns null when nothing crosses the threshold', () => {
		expect(maskBoundingBox(new Float32Array(16), 4, 4, 8, 8, 0.5)).toBeNull();
	});
});

describe('smoothstep', () => {
	it('clamps below/above the edges', () => {
		expect(smoothstep(0, 1, -2)).toBe(0);
		expect(smoothstep(0, 1, 5)).toBe(1);
	});
	it('is 0.5 at the midpoint and monotonic', () => {
		expect(smoothstep(0, 1, 0.5)).toBeCloseTo(0.5, 5);
		expect(smoothstep(0, 1, 0.25)).toBeLessThan(smoothstep(0, 1, 0.75));
	});
	it('degenerates to a step when edges are equal', () => {
		expect(smoothstep(0.5, 0.5, 0.4)).toBe(0);
		expect(smoothstep(0.5, 0.5, 0.6)).toBe(1);
	});
});