3D engine that AI agents drive
Draw mirrored skin vertices pinched and warn instead of failing (issue #581)
Nguyen Xuan An9ecbcddcedf9
diff --git a/changes/581.md b/changes/581.mdnew file mode 100644index 00000000..bc6fbadc--- /dev/null+++ b/changes/581.md@@ -0,0 +1 @@+- A few mirrored skin vertices (a finger pinched between two joints) no longer fail the frame. They draw pinched, and `renderer.diagnostics` lists `skin-reflected-vertices` with the count and the joints and weights of the first one (#581)diff --git a/changes/581.size.md b/changes/581.size.mdnew file mode 100644index 00000000..cdbd8abc--- /dev/null+++ b/changes/581.size.md@@ -0,0 +1,8 @@+- entry:core: the core entry exports skinning.js, which now counts mirrored weighted vertices and builds the warning text instead of throwing (issue #581). A frame that used to fail now draws.+- entry:surface-attachment: carries skinning.js, same reason.+- entry:retarget: carries skinning.js, same reason.+- scene:gltf-box: loads skinning.js, same reason.+- scene:gltf-box+lazy: loads skinning.js, same reason.+- scene:agent-scene: loads skinning.js, same reason.+- scene:agent-scene+lazy: loads skinning.js, same reason.+- goal:lit-box: 23 bytes for the renderer to pass the skin warnings into renderer.diagnostics. Accepted by the lead under the trade-off rule: it turns a failed frame into a drawn one with a named warning.diff --git a/docs/skinning.md b/docs/skinning.mdindex c790e3f1..1e400b4c 100644--- a/docs/skinning.md+++ b/docs/skinning.md@@ -74,7 +74,7 @@ The installed Three.js skin shader transforms normals directly with the blendedThe methods agree when the blended matrix represents a rigid transform. They can differ under nonuniform scale or blended rotations.Tests compare positions with Three.js and verify the normal's perpendicularity to a transformed tangent.-Singular joints and singular weighted vertex transforms fail explicitly. Reflected weighted transforms in world space also fail.+Singular joints and singular weighted vertex transforms fail explicitly. A vertex whose weighted transform mirrors the mesh, as when linear blend skinning pinches a finger between two joints that turn opposite ways, draws pinched as in other engines. The renderer lists it in `renderer.diagnostics` as `skin-reflected-vertices`, with the count and the joints and weights of the first one. `{ checks: false }` skips the check, so the warning then keeps its last value.The renderer validates weighted transforms on the CPU before uploads. This validation visits every influenced vertex in submitted parts.Skinning uses linear matrix blending. It does not implement dual-quaternion deformation or preserve volume around bent joints.diff --git a/src/frame-diagnostics.js b/src/frame-diagnostics.jsindex c38fca08..cdc5cb02 100644--- a/src/frame-diagnostics.js+++ b/src/frame-diagnostics.js@@ -28,7 +28,7 @@ function shadowDirectionProblem(world, lightDirection, shadowBounds) {'Drop shadowBounds.eye, or point lightDirection from shadowBounds.target to it.');}-export function frameDiagnostics({ world, depth, effects, lightDirection, shadowBounds, coplanarProblems = null }) {+export function frameDiagnostics({ world, depth, effects, lightDirection, shadowBounds, coplanarProblems = null, skinProblems = null }) {const problems = [];if (effects.ambientOcclusion > 0 && !depth) {problems.push(warning('ambient-occlusion-without-depth', 'effects.ambientOcclusion',@@ -40,5 +40,6 @@ export function frameDiagnostics({ world, depth, effects, lightDirection, shadowif (problem) problems.push(problem);}if (coplanarProblems?.length) problems.push(...coplanarProblems);+ if (skinProblems?.length) problems.push(...skinProblems);return problems.length ? problems : NO_DIAGNOSTICS;}diff --git a/src/renderer.js b/src/renderer.jsindex 0711b6b9..d7f03a1a 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -20,7 +20,7 @@ import { MaterialSnapshot } from './material-snapshot.js';import { fittedFogDensity } from './fog-fit.js';import { InstanceSelection, extractFrustumPlanes, geometryBoundingSphere, selectInstances } from './render-culling.js';import { resolveShadowLight, shadowBiasPerSlope } from './shadow-light.js';-import { requireDeformationSupport, texturedReplaceSupport, textureUpdateSupport } from './shader-registry.js';+import { deformationSupport, requireDeformationSupport, texturedReplaceSupport, textureUpdateSupport } from './shader-registry.js';const SHADOW_MAP_SIZE = 2048;// Liquid and foam see the resolved opaque scene, so they draw in their own pass after it.@@ -2155,7 +2155,7 @@ export class Renderer67 {// The shadow view follows the sun, so a moved sun redraws the map.const lightChanged = String(this.activeLightDirection) !== String(environment.lightDirection);this.activeLightDirection = environment.lightDirection;- this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds, coplanarProblems: this.coplanarDiagnostics?.(this.batches) });+ this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds, coplanarProblems: this.coplanarDiagnostics?.(this.batches), skinProblems: deformationSupport.reflectedSkinDiagnostics?.(this.partLocations) });const start = performance.now();const context = this.context;this.beginGpuTiming();diff --git a/src/shader-registry.js b/src/shader-registry.jsindex dd88627c..01c7da47 100644--- a/src/shader-registry.js+++ b/src/shader-registry.js@@ -68,7 +68,7 @@ export const MAX_MORPH_TARGETS = 64;// skinning.js and morph.js set the JavaScript half of skinned and morphed parts: validation, texture layout and packing.// The renderer calls them only for a part with a skin or morph targets, so a renderer without those parts never carries them.-const deformationSupport = {};+export const deformationSupport = {};export function registerDeformationSupport(functions) {Object.assign(deformationSupport, functions);diff --git a/src/skinning.js b/src/skinning.jsindex f61f2feb..77a5a94b 100644--- a/src/skinning.js+++ b/src/skinning.js@@ -151,13 +151,27 @@ export function skinInfluenceSets(geometry) {return sets;}-/** Validate weighted normal transforms without allocating temporary matrices, once per distinct influence set. */+// The last check of each pose that found mirrored weighted transforms. The renderer reads it into renderer.diagnostics.+const reflectedReports = new WeakMap();++/** What the last checked pose drew mirrored: { sets, joints, weights } for the first such influence set, or null. */+export function reflectedSkinReport(pose) {+ return reflectedReports.get(pose) ?? null;+}++/**+ * Validate weighted normal transforms without allocating temporary matrices, once per distinct influence set.+ * A singular set throws. A set whose blend mirrors the mesh (linear blend skinning between joints that turn opposite+ * ways, as a pinched finger) draws pinched, like other engines, and is reported through reflectedSkinReport.+ */export function validateSkinPose(pose, geometry, worldMatrix) {const matrices = pose.jointMatrices;validateMatrices(matrices, matrices.length / 16, 'Joint palette');if (!geometry) return;const { joints, weights } = skinInfluenceSets(geometry);const worldDeterminant = worldMatrix ? matrixDeterminant(worldMatrix, 0) : 0;+ let reflectedSets = 0;+ let firstReflected = -1;for (let set = 0; set < joints.length / 4; set++) {let matrixXX = 0;let matrixYX = 0;@@ -183,8 +197,24 @@ export function validateSkinPose(pose, geometry, worldMatrix) {}const determinant = matrixXX * (matrixYY * matrixZZ - matrixYZ * matrixZY) - matrixXY * (matrixYX * matrixZZ - matrixYZ * matrixZX) + matrixXZ * (matrixYX * matrixZY - matrixYY * matrixZX);if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-8) throw new Error('Skin pose produces a singular weighted vertex transform.');- if (worldMatrix && determinant * worldDeterminant < 0) throw new Error('Reflected weighted skin transforms are unsupported.');+ if (worldMatrix && determinant * worldDeterminant < 0) {+ if (firstReflected < 0) firstReflected = set;+ reflectedSets++;+ }+ }+ if (!worldMatrix) return;+ if (reflectedSets === 0) {+ reflectedReports.delete(pose);+ return;+ }+ const report = { sets: reflectedSets, joints: [], weights: [] };+ for (let influence = 0; influence < 4; influence++) {+ const weight = weights[firstReflected * 4 + influence];+ if (weight <= 0) continue;+ report.joints.push(joints[firstReflected * 4 + influence]);+ report.weights.push(Math.round(weight * 100) / 100);}+ reflectedReports.set(pose, report);}export function packSkinInfluences(geometry, layout) {@@ -226,4 +256,31 @@ mat4 jointMatrix(int joint) {`,});-registerDeformationSupport({ validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences });+// The skinned entries of each renderer part map. A renderer swaps in a new map when its parts change.+const skinnedPartLists = new WeakMap();++/** renderer.diagnostics warnings for skinned parts whose last checked pose drew mirrored vertices. */+export function reflectedSkinDiagnostics(partLocations) {+ let skinnedParts = skinnedPartLists.get(partLocations);+ if (!skinnedParts) {+ skinnedParts = [...partLocations].filter(([, location]) => location.skin);+ skinnedPartLists.set(partLocations, skinnedParts);+ }+ const problems = [];+ for (const [part, location] of skinnedParts) {+ const report = reflectedSkinReport(location.skin);+ if (!report) continue;+ const name = part.name ?? 'a skinned part';+ const joints = report.joints.map((joint, index) => `joint ${joint} at ${report.weights[index]}`).join(', ');+ problems.push({+ kind: 'skin-reflected-vertices',+ severity: 'warning',+ target: name,+ message: `${report.sets} vertex weight set(s) of ${name} mirror in this pose and draw pinched. First: ${joints}.`,+ fix: 'Move the weights of joints that turn opposite ways onto one joint, such as finger weights onto the hand.',+ });+ }+ return problems;+}++registerDeformationSupport({ validateSkinGeometry, validateSkinPose, reflectedSkinDiagnostics, skinTextureLayout, packSkinInfluences });diff --git a/src/surface-attachment.js b/src/surface-attachment.jsindex 82e89ea2..774a719a 100644--- a/src/surface-attachment.js+++ b/src/surface-attachment.js@@ -206,7 +206,7 @@ export function createSurfaceAttachment(target, options = {}) {}const blendedDeterminant = determinant(blended);if (!Number.isFinite(blendedDeterminant) || Math.abs(blendedDeterminant) < 1e-8) throw new RangeError('Attachment has a singular weighted skin transform.');- if (blendedDeterminant * worldDeterminant < 0) throw new RangeError('Reflected weighted skin transforms are unsupported by the renderer.');+ if (blendedDeterminant * worldDeterminant < 0) throw new RangeError('A surface attachment cannot sit on a mirrored weighted skin vertex. Move it to a face whose joints do not turn opposite ways.');for (let column = 0; column < 4; column++) {for (let row = 0; row < 4; row++) {let coefficient = 0;diff --git a/tests/skinning.test.js b/tests/skinning.test.jsindex 89a441cf..1cfc1caf 100644--- a/tests/skinning.test.js+++ b/tests/skinning.test.js@@ -2,7 +2,7 @@ import test from 'node:test';import assert from 'node:assert/strict';import { mat4 } from 'gl-matrix';import { Bone, Skeleton, SkinnedMesh, BufferGeometry, Float32BufferAttribute, Uint16BufferAttribute, Matrix4, Matrix3, Vector3 } from 'three';-import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences, skinInfluenceSets } from '../src/skinning.js';+import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences, skinInfluenceSets, reflectedSkinReport, reflectedSkinDiagnostics } from '../src/skinning.js';function influences() {return { positions: new Float32Array([0.2, 1, 0]), skinIndices: new Uint16Array([0, 1, 0, 0]), skinWeights: new Float32Array([0.3, 0.7, 0, 0]) };@@ -201,3 +201,24 @@ test('skinInfluenceSets rebuilds when the index array is replaced', () => {assert.notEqual(first, replaced);assert.deepEqual([...replaced.joints.subarray(0, 4)], [1, 0, 0, 0]);});++test('a mirrored weighted vertex draws pinched and is reported instead of failing the pose (issue #581)', () => {+ const pose = createSkinPose(2);+ // Joint 1 mirrors x. A 25/75 blend with the identity scales x by -0.5: a mirrored but healthy transform.+ pose.jointMatrices.set([-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);+ const geometry = {+ skinIndices: new Uint16Array([0, 0, 0, 0, 0, 1, 0, 0]),+ skinWeights: new Float32Array([1, 0, 0, 0, 0.25, 0.75, 0, 0]),+ };+ const world = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);+ assert.doesNotThrow(() => validateSkinPose(pose, geometry, world));+ assert.deepEqual(reflectedSkinReport(pose), { sets: 1, joints: [0, 1], weights: [0.25, 0.75] });+ const [problem] = reflectedSkinDiagnostics(new Map([[{ name: "knight" }, { skin: pose }]]));+ assert.equal(problem.kind, 'skin-reflected-vertices');+ assert.match(problem.message, /1 vertex weight set\(s\) of knight mirror .*joint 0 at 0\.25, joint 1 at 0\.75/);+ // Once the joint stops mirroring, the report clears.+ pose.jointMatrices.set([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);+ validateSkinPose(pose, geometry, world);+ assert.equal(reflectedSkinReport(pose), null);+ assert.deepEqual(reflectedSkinDiagnostics(new Map([[{ name: "knight" }, { skin: pose }]])), []);+});