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
fix(viewer): frame the avatar's face, not its back, whatever axis its rig faces
nirholas66de9305b1f6
diff --git a/src/shared/idle-avatar.js b/src/shared/idle-avatar.jsindex 6ee4098dc..14c2d51e2 100644--- a/src/shared/idle-avatar.js+++ b/src/shared/idle-avatar.js@@ -35,6 +35,11 @@ function loadAnimationDefs() {return _manifestPromise;}+/** True when the reader asked the platform to hold decorative motion still. */+function prefersReducedMotion() {+ return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;+}+/*** Mount a living, idle-animated avatar into `container`.*@@ -44,6 +49,7 @@ function loadAnimationDefs() {* @param {string} glbUrl Avatar model URL.* @param {Object} [opts]* @param {boolean} [opts.autoRotate=true] Slowly turn the figure on a turntable.+ * Held still regardless when the reader prefers reduced motion.* @param {string} [opts.seed] Stable seed so the idle phase is deterministic per agent.* @param {string} [opts.environment='Neutral'] Lighting environment name.* @param {boolean} [opts.cameraControls=false] Allow orbit/zoom (used in the modal).@@ -83,7 +89,10 @@ export function mountIdleAvatar(container, glbUrl, opts = {}) {}viewer.state.environment = environment;- viewer.state.autoRotate = autoRotate;+ // A turntable is decorative motion nobody asked for: a reader who set+ // "reduce motion" gets the figure held still, and its idle life (breathing,+ // blink) still plays because that is the content, not the decoration.+ viewer.state.autoRotate = autoRotate && !prefersReducedMotion();viewer.controls.enabled = cameraControls;viewer.controls.enableZoom = cameraControls;viewer.controls.enablePan = false;diff --git a/src/viewer.js b/src/viewer.jsindex 953b7a798..78bc64578 100644--- a/src/viewer.js+++ b/src/viewer.js@@ -54,6 +54,7 @@ import { getCubeMapTexture } from './viewer/environment.js';import { takeScreenshot, captureScreenshot } from './viewer/screenshot.js';import { setClips, playAllClips } from './viewer/animation.js';import { computeFramingExtent, computeFramingWidth } from './viewer/framing.js';+import { estimateFacingYaw, forwardFromYaw, horizontalExtentAt } from './viewer/facing.js';import { LightProbeGrid } from './light-probe-grid.js';import { AnimationManager } from './animation-manager.js';import { applyAvatarMaterialRealism, looksLikeAvatarMesh } from './shared/avatar-material-realism.js';@@ -712,9 +713,14 @@ export class Viewer {const framingMode = this.options?.framing === 'portrait' ? 'portrait' : 'full';const { visH, baseY } = computeFramingExtent(bbSize.y, box.max.y, framingMode);+ // Sit the camera in front of the avatar's face, whichever way its rig+ // was authored; yaw 0 (no readable rig) keeps the historical +Z seat.+ const yaw = estimateFacingYaw(this.content, bbSize.y) ?? 0;+ const forward = forwardFromYaw(yaw);+const extentV = (visH / 2) * PAD_V / usableFrac;const distV = extentV / Math.tan(vFovRad / 2);- const framingWidth = computeFramingWidth(bbSize.x, bbSize.y, framingMode);+ const framingWidth = computeFramingWidth(horizontalExtentAt(bbSize.x, bbSize.z, yaw), bbSize.y, framingMode);const distH = (framingWidth / 2) * PAD_H / Math.tan(hFovRad / 2);const dist = Math.max(distV, distH);@@ -722,7 +728,11 @@ export class Viewer {// with a bottom panel, shift down so the avatar rises into the upper area.const focusY = baseY - extentV * panelFrac;const target = new Vector3(bbCenter.x, focusY, bbCenter.z);- const pos = new Vector3(bbCenter.x + dist * 0.12, focusY, bbCenter.z + dist);+ const pos = new Vector3(+ bbCenter.x + forward.x * dist,+ focusY,+ bbCenter.z + forward.z * dist,+ );if (animate) {this._tweenCamera(pos, target, durationMs);@@ -1343,9 +1353,14 @@ export class Viewer {const framingMode = this.options?.framing === 'portrait' ? 'portrait' : 'full';const { visH, baseY } = computeFramingExtent(bbSize.y, bbSize.y / 2, framingMode);+ // Same front-on seat as frameContent(): read the rig's facing rather+ // than assuming the avatar was authored looking down +Z.+ const yaw = estimateFacingYaw(this.content, bbSize.y) ?? 0;+ const forward = forwardFromYaw(yaw);+const extentV = (visH / 2) * PAD_V / usableFrac;const distV = extentV / Math.tan(vFovRad / 2);- const framingWidth = computeFramingWidth(bbSize.x, bbSize.y, framingMode);+ const framingWidth = computeFramingWidth(horizontalExtentAt(bbSize.x, bbSize.z, yaw), bbSize.y, framingMode);const distH = (framingWidth / 2) * PAD_H / Math.tan(hFovRad / 2);const dist = Math.max(distV, distH);@@ -1355,14 +1370,13 @@ export class Viewer {const focusY = baseY - extentV * panelFrac;// Final framed camera (the position the user should end up at).- // Avatar sits dead-centered front-on by default — no lateral offset.- // (The legacy 6% 3/4 angle pan was an aesthetic choice; removing it so- // every embed opens with the character squarely facing the viewer.)+ // Avatar sits dead-centered front-on by default: no lateral offset, and+ // the seat rotates with the rig's facing so "front" means the face.const framedPos = new Vector3();if (this.options.cameraPosition) {framedPos.fromArray(this.options.cameraPosition);} else {- framedPos.set(0, focusY, dist);+ framedPos.set(forward.x * dist, focusY, forward.z * dist);}const orbitalTarget = new Vector3(0, focusY, 0);diff --git a/src/viewer/facing.js b/src/viewer/facing.jsnew file mode 100644index 000000000..c8b1fe884--- /dev/null+++ b/src/viewer/facing.js@@ -0,0 +1,110 @@+// Which way is the avatar looking? Pure geometry plus a scene-graph probe, kept+// out of viewer.js so both framing paths (setContent's first frame and+// frameContent's re-frame) can agree and so the math is unit-testable without a+// WebGL context.+//+// The viewer used to place the camera on +Z unconditionally and describe that as+// "front-on". That only holds for rigs authored facing +Z. glTF characters+// arrive facing every axis (Mixamo and Unreal exports commonly face -Z, VRM+// faces +Z), so a large share of avatars opened showing the viewer their back.+// Reading the facing off the rig fixes that for every avatar at once, with no+// per-model metadata and no allowlist.++import { canonicalizeBoneName } from '../glb-canonicalize.js';++/**+ * Bone pairs that span the body left-to-right, best first. Shoulders barely+ * move in an idle clip, so they give a steadier read than hands or feet.+ * Names are canonical (see CANONICAL_BONES in ../glb-canonicalize.js).+ */+const SPAN_PAIRS = [+ ['LeftShoulder', 'RightShoulder'],+ ['LeftArm', 'RightArm'],+ ['LeftUpLeg', 'RightUpLeg'],+];++/**+ * Yaw of the direction a body faces, from the horizontal span between its left+ * and right side.+ *+ * With Y up, the character's right vector r and forward f satisfy f = up x r,+ * so f = (r.z, 0, -r.x). Yaw is measured from +Z, the axis the camera has+ * always sat on, which makes 0 the exact legacy behaviour.+ *+ * @param {number} dx world x of (right landmark - left landmark)+ * @param {number} dz world z of (right landmark - left landmark)+ * @param {number} [minSpan=0] reject spans shorter than this (world units)+ * @returns {number|null} yaw in radians, or null when the span is degenerate+ */+export function yawFromRightSpan(dx, dz, minSpan = 0) {+ if (!Number.isFinite(dx) || !Number.isFinite(dz)) return null;+ if (Math.hypot(dx, dz) <= Math.max(minSpan, 0)) return null;+ return Math.atan2(dz, -dx);+}++/**+ * Unit forward vector for a yaw, in the horizontal plane.+ * @param {number} yaw radians, measured from +Z+ * @returns {{x:number, z:number}}+ */+export function forwardFromYaw(yaw) {+ return { x: Math.sin(yaw), z: Math.cos(yaw) };+}++/**+ * Width of an axis-aligned bounding box as seen from a camera at `yaw`.+ *+ * Camera distance is driven partly by how wide the subject is on screen, and+ * that width is the box projected onto the camera's right vector+ * (cos(yaw), 0, -sin(yaw)). At yaw 0 this returns sizeX, so a +Z-facing avatar+ * is framed exactly as before; a side-facing one is now measured across its+ * depth instead of being framed against the wrong axis.+ *+ * @param {number} sizeX bounding-box size on x+ * @param {number} sizeZ bounding-box size on z+ * @param {number} yaw radians+ * @returns {number}+ */+export function horizontalExtentAt(sizeX, sizeZ, yaw) {+ return Math.abs(Math.cos(yaw)) * sizeX + Math.abs(Math.sin(yaw)) * sizeZ;+}++/**+ * Read the facing yaw off a loaded model's rig.+ *+ * Walks the graph once for the best available left/right bone pair and measures+ * the span between their world positions. World translation is read straight+ * out of matrixWorld, so this needs no THREE import and can be tested with+ * plain objects; call it after the world matrices are up to date (Box3's+ * setFromObject does that, and both framing paths compute a box first).+ *+ * @param {{traverse:Function}} root loaded model root+ * @param {number} [bodyHeight=0] bounding-box height, used to reject a+ * degenerate span (a rig collapsed onto its own centre line)+ * @returns {number|null} yaw in radians, or null when the rig cannot say+ */+export function estimateFacingYaw(root, bodyHeight = 0) {+ if (!root || typeof root.traverse !== 'function') return null;++ const found = new Map();+ root.traverse((node) => {+ if (!node?.isBone || typeof node.name !== 'string') return;+ const canonical = canonicalizeBoneName(node.name);+ if (!canonical || found.has(canonical)) return;+ const e = node.matrixWorld?.elements;+ if (!e) return;+ found.set(canonical, { x: e[12], z: e[14] });+ });++ // A body collapsed to a line has no readable facing; 4% of height is well+ // under any real shoulder span and well over floating-point noise.+ const minSpan = bodyHeight * 0.04;+ for (const [left, right] of SPAN_PAIRS) {+ const l = found.get(left);+ const r = found.get(right);+ if (!l || !r) continue;+ const yaw = yawFromRightSpan(r.x - l.x, r.z - l.z, minSpan);+ if (yaw !== null) return yaw;+ }+ return null;+}diff --git a/tests/viewer-facing.test.js b/tests/viewer-facing.test.jsnew file mode 100644index 000000000..1e657fdc3--- /dev/null+++ b/tests/viewer-facing.test.js@@ -0,0 +1,130 @@+/**+ * Viewer facing detection: which way does the avatar look?+ *+ * The camera seat used to be hardcoded to +Z and called "front-on", which only+ * held for rigs authored facing +Z. These tests pin the geometry that replaced+ * it, including the one case that must never regress: a model with no readable+ * rig still gets the legacy +Z seat.+ */++import { describe, it, expect } from 'vitest';+import {+ yawFromRightSpan,+ forwardFromYaw,+ horizontalExtentAt,+ estimateFacingYaw,+} from '../src/viewer/facing.js';++/** Minimal stand-in for a THREE.Bone: only name + world translation are read. */+function bone(name, x, z) {+ const elements = new Array(16).fill(0);+ elements[12] = x;+ elements[14] = z;+ return { isBone: true, name, matrixWorld: { elements } };+}++/** Minimal stand-in for an Object3D root that owns the bones. */+function model(...bones) {+ return { traverse(fn) { fn(this); bones.forEach(fn); } };+}++describe('yawFromRightSpan', () => {+ it('reads +Z facing when the right side sits on -X (the legacy assumption)', () => {+ expect(yawFromRightSpan(-1, 0)).toBeCloseTo(0, 12);+ });++ it('reads -Z facing when the right side sits on +X', () => {+ expect(Math.abs(yawFromRightSpan(1, 0))).toBeCloseTo(Math.PI, 12);+ });++ it('reads +X facing when the right side sits on +Z', () => {+ expect(yawFromRightSpan(0, 1)).toBeCloseTo(Math.PI / 2, 12);+ });++ it('rejects a span shorter than the floor, so a collapsed rig cannot spin the camera', () => {+ expect(yawFromRightSpan(0.001, 0.001, 0.05)).toBeNull();+ });++ it('rejects non-finite input rather than producing NaN yaw', () => {+ expect(yawFromRightSpan(Number.NaN, 0)).toBeNull();+ expect(yawFromRightSpan(0, Number.POSITIVE_INFINITY)).toBeNull();+ });+});++describe('forwardFromYaw', () => {+ it('maps yaw 0 to +Z, the seat every existing embed already had', () => {+ const f = forwardFromYaw(0);+ expect(f.x).toBeCloseTo(0, 12);+ expect(f.z).toBeCloseTo(1, 12);+ });++ it('maps a quarter turn to +X', () => {+ const f = forwardFromYaw(Math.PI / 2);+ expect(f.x).toBeCloseTo(1, 12);+ expect(f.z).toBeCloseTo(0, 12);+ });++ it('stays a unit vector at an arbitrary angle', () => {+ const f = forwardFromYaw(1.2345);+ expect(Math.hypot(f.x, f.z)).toBeCloseTo(1, 12);+ });+});++describe('horizontalExtentAt', () => {+ it('is the box width at yaw 0, so full-body framing is unchanged', () => {+ expect(horizontalExtentAt(0.9, 0.3, 0)).toBeCloseTo(0.9, 12);+ });++ it('is the box depth when the camera looks along X', () => {+ expect(horizontalExtentAt(0.9, 0.3, Math.PI / 2)).toBeCloseTo(0.3, 12);+ });++ it('blends the two axes at an oblique angle', () => {+ const e = horizontalExtentAt(0.9, 0.3, Math.PI / 4);+ expect(e).toBeCloseTo(Math.SQRT1_2 * (0.9 + 0.3), 12);+ expect(e).toBeGreaterThan(0.3);+ expect(e).toBeLessThan(0.9 + 0.3);+ });+});++describe('estimateFacingYaw', () => {+ it('prefers shoulders and reads a -Z facing rig', () => {+ const yaw = estimateFacingYaw(model(+ bone('mixamorigLeftShoulder', -0.18, 0),+ bone('mixamorigRightShoulder', 0.18, 0),+ ), 1.8);+ expect(Math.abs(yaw)).toBeCloseTo(Math.PI, 6);+ });++ it('canonicalizes vendor bone names before matching', () => {+ const yaw = estimateFacingYaw(model(+ bone('J_Bip_L_UpperArm', 0, -0.2),+ bone('J_Bip_R_UpperArm', 0, 0.2),+ ), 1.8);+ expect(yaw).toBeCloseTo(Math.PI / 2, 6);+ });++ it('falls back to the legs when the rig has no arms', () => {+ const yaw = estimateFacingYaw(model(+ bone('LeftUpLeg', -0.1, 0),+ bone('RightUpLeg', 0.1, 0),+ ), 1.8);+ expect(Math.abs(yaw)).toBeCloseTo(Math.PI, 6);+ });++ it('returns null for a prop with no bones, leaving the camera on +Z', () => {+ expect(estimateFacingYaw(model(), 1.8)).toBeNull();+ });++ it('returns null when the left and right bones sit on top of each other', () => {+ expect(estimateFacingYaw(model(+ bone('LeftShoulder', 0, 0),+ bone('RightShoulder', 0.0001, 0),+ ), 1.8)).toBeNull();+ });++ it('tolerates a root that is not a scene graph', () => {+ expect(estimateFacingYaw(null, 1.8)).toBeNull();+ expect(estimateFacingYaw({}, 1.8)).toBeNull();+ });+});