Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
/**
* #277 — open surfaces measured against closed solids.
*
* The difficulty is the same as T4.1's and sharper: a cloth has no volume, so
* the boolean pass cannot measure it at all, and the true negatives are the
* whole problem. A throw resting on a seat, a canopy touching its mast and a
* cloth deliberately sunk a millimetre or two to hide a seam are all correct
* geometry. Every one has a fixture here beside the true positives.
*/
import { describe, expect, spyOn, test } from 'bun:test';
import * as THREE from 'three';
import * as geometryModule from '../geometry';
import {
analyzeOpenSurfacePenetration,
inspectOpenSurfacePenetration,
OPEN_SURFACE_CONTACT_TOLERANCE,
OPEN_SURFACE_PENETRATION_QA_RULE,
} from './open-surface-penetration';
import { analyzePartPenetration } from './self-intersection';
import { EXTERNAL_SUPPORT_TOLERANCE } from '../external-support';
import { createAssetIntentV1 } from '../contracts';
import { markOpenShell } from '../open-shell';
function solid(name: string, size: [number, number, number], at: [number, number, number]) {
const mesh = new THREE.Mesh(new THREE.BoxGeometry(...size));
mesh.name = name;
mesh.position.set(...at);
return mesh;
}
/** An open surface: one plane, no thickness, no volume. */
function cloth(
name: string,
size: [number, number],
at: [number, number, number],
rotationX = -Math.PI / 2,
segments = 8,
) {
const mesh = new THREE.Mesh(new THREE.PlaneGeometry(size[0], size[1], segments, segments));
mesh.name = name;
mesh.rotation.x = rotationX;
mesh.position.set(...at);
return mesh;
}
function sceneOf(...nodes: THREE.Object3D[]): THREE.Object3D {
const root = new THREE.Object3D();
root.name = 'Asset';
for (const node of nodes) root.add(node);
return root;
}
describe('true positives — an open surface inside a closed solid', () => {
test('a cloth running through a wall names both parts and the depth', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]),
cloth('Mesh_ThrowBlanket', [1, 1], [0, 0.7, 0.4], 0),
),
);
expect(evidence.penetrations).toHaveLength(1);
const [pair] = evidence.penetrations;
expect(pair!.open).toBe('Mesh_ThrowBlanket');
expect(pair!.solid).toBe('Mesh_CurvedWall');
// The cloth sits on the wall's mid-plane, so the nearest face is half its thickness away.
expect(pair!.depth).toBeCloseTo(0.06, 4);
const [finding] = inspectOpenSurfacePenetration(evidence);
expect(finding!.code).toBe('GEO_OPEN_SURFACE_PENETRATION');
expect(finding!.message).toContain('Mesh_ThrowBlanket');
expect(finding!.message).toContain('Mesh_CurvedWall');
expect(finding!.message).toContain('0.0600');
});
test('a canopy pierced by one mast is reported from a single penetrating vertex', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_Mast', [0.06, 2, 0.06], [0, 1, 0]),
cloth('Mesh_Canopy', [1.2, 1.2], [0, 1, 0]),
),
);
expect(evidence.penetrations).toHaveLength(1);
expect(evidence.penetrations[0]!.vertices).toBe(1);
expect(evidence.penetrations[0]!.depth).toBeCloseTo(0.03, 4);
});
});
describe('true negatives — correct geometry that must stay silent', () => {
test('a cloth resting exactly on a seat top is contact, not penetration', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_Seat', [1, 0.4, 1], [0, 0.2, 0]),
cloth('Mesh_Throw', [0.8, 0.8], [0, 0.4, 0]),
),
);
expect(evidence.candidatePairs).toBe(1);
expect(evidence.penetrations).toEqual([]);
expect(inspectOpenSurfacePenetration(evidence)).toEqual([]);
});
test('a cloth sunk inside the contact tolerance to hide a seam stays silent', () => {
const sunk = OPEN_SURFACE_CONTACT_TOLERANCE / 2;
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_Cushion', [1, 0.4, 1], [0, 0.2, 0]),
cloth('Mesh_Throw', [0.8, 0.8], [0, 0.4 - sunk, 0]),
),
);
expect(evidence.penetrations).toEqual([]);
});
test('a cloth clear above a seat is neither contact nor penetration', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_Seat', [1, 0.4, 1], [0, 0.2, 0]),
cloth('Mesh_Throw', [0.8, 0.8], [0, 0.45, 0]),
),
);
expect(evidence.candidatePairs).toBe(0);
expect(evidence.penetrations).toEqual([]);
});
test('two closed solids are left to the boolean pass', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(solid('Mesh_A', [1, 1, 1], [0, 0, 0]), solid('Mesh_B', [1, 1, 1], [0.5, 0, 0])),
);
expect(evidence.openParts).toBe(0);
expect(evidence.candidatePairs).toBe(0);
expect(evidence.penetrations).toEqual([]);
});
});
describe('composed modules', () => {
test('a cloth from one module through a wall in another is reported', () => {
const seating = new THREE.Group();
seating.name = 'SeatingModule';
seating.add(solid('Mesh_Bench', [1.2, 0.4, 0.5], [0, 0.2, 0]));
seating.add(cloth('Mesh_ThrowBlanket', [1, 1], [0, 0.7, 0.4], 0));
const structure = new THREE.Group();
structure.name = 'StructureModule';
structure.add(solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]));
const evidence = analyzeOpenSurfacePenetration(sceneOf(seating, structure));
expect(evidence.penetrations.map((pair) => [pair.open, pair.solid])).toEqual([
['Mesh_ThrowBlanket', 'Mesh_CurvedWall'],
]);
});
});
describe('the tolerance regime', () => {
test('penetration uses its own tolerance, not the 2 cm adjacency tolerance', () => {
expect(OPEN_SURFACE_CONTACT_TOLERANCE).toBeLessThan(EXTERNAL_SUPPORT_TOLERANCE);
expect(EXTERNAL_SUPPORT_TOLERANCE).toBe(0.02);
});
test('a cloth 1 cm inside a 3 cm panel is reported, where a 2 cm tolerance would hide it', () => {
// The panel's mid-plane is 15 mm from either face, so a cloth on it reads 15 mm:
// under the adjacency tolerance, over this pass's.
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_WallCap', [1.5, 0.4, 0.03], [0, 0.5, 0]),
cloth('Mesh_Throw', [0.6, 0.3], [0, 0.5, 0], 0),
),
);
expect(evidence.penetrations).toHaveLength(1);
expect(evidence.penetrations[0]!.depth).toBeCloseTo(0.015, 4);
expect(evidence.penetrations[0]!.depth).toBeLessThan(EXTERNAL_SUPPORT_TOLERANCE);
});
test('an explicit tolerance widens intended contact without changing the measurement', () => {
const build = () =>
sceneOf(
solid('Mesh_Cushion', [1, 0.4, 1], [0, 0.2, 0]),
cloth('Mesh_Throw', [0.8, 0.8], [0, 0.39, 0]),
);
expect(analyzeOpenSurfacePenetration(build()).penetrations).toHaveLength(1);
expect(analyzeOpenSurfacePenetration(build(), 0.02).penetrations).toEqual([]);
});
});
describe('coverage this pass does not claim', () => {
test('a marked open shell is measured here, which the volume pass says it cannot be', async () => {
const throwBlanket = cloth('Mesh_ThrowBlanket', [1, 1], [0, 0.7, 0.4], 0);
markOpenShell(throwBlanket, 'a single-sided wool throw');
const scene = sceneOf(solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]), throwBlanket);
// The volume pass can only acknowledge the mark; this one takes the measurement.
const volume = await analyzePartPenetration(scene);
expect(volume.penetrations).toEqual([]);
expect(volume.acknowledged?.map((part) => part.part)).toEqual(['Mesh_ThrowBlanket']);
expect(analyzeOpenSurfacePenetration(scene).penetrations).toHaveLength(1);
});
test('a solid thinner than the surface facet spacing passes between vertices unreported', () => {
// One quad, 1 m across, and a 2 cm post through its middle: no vertex is inside.
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_Post', [0.02, 2, 0.02], [0, 1, 0]),
cloth('Mesh_Canopy', [1, 1], [0, 1, 0], -Math.PI / 2, 1),
),
);
expect(evidence.candidatePairs).toBe(1);
expect(evidence.penetrations).toEqual([]);
});
test('LOD alternates are not compared', () => {
const low = new THREE.Group();
low.name = 'Awning_LOD1';
low.add(cloth('Mesh_AwningCloth', [1, 1], [0, 0.7, 0.4], 0));
const high = new THREE.Group();
high.name = 'Awning_LOD0';
high.add(solid('Mesh_AwningFrame', [2, 1.4, 0.12], [0, 0.7, 0.4]));
const evidence = analyzeOpenSurfacePenetration(sceneOf(low, high));
expect(evidence.pairsLodAlternates).toBe(1);
expect(evidence.candidatePairs).toBe(0);
expect(evidence.penetrations).toEqual([]);
});
test('an instanced part is named as unmeasured rather than dropped', () => {
const instanced = new THREE.InstancedMesh(new THREE.BoxGeometry(1, 1, 1), undefined, 2);
instanced.name = 'Mesh_Pebbles';
const evidence = analyzeOpenSurfacePenetration(
sceneOf(instanced, cloth('Mesh_Throw', [1, 1], [0, 0, 0])),
);
expect(evidence.skipped.map((part) => part.part)).toEqual(['Mesh_Pebbles']);
const codes = inspectOpenSurfacePenetration(evidence).map((finding) => finding.code);
expect(codes).toContain('GEO_OPEN_SURFACE_PENETRATION_UNMEASURED');
});
test('a non-Object3D scene yields an empty measurement, never a clean pass claim', () => {
const evidence = analyzeOpenSurfacePenetration(undefined);
expect(evidence.openParts).toBe(0);
expect(evidence.closedParts).toBe(0);
expect(inspectOpenSurfacePenetration(evidence)).toEqual([]);
});
});
describe('determinism and wiring', () => {
test('the same scene yields the same evidence', () => {
const build = () =>
sceneOf(
solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]),
solid('Mesh_Mast', [0.06, 2, 0.06], [0.4, 1, 0.4]),
cloth('Mesh_ThrowBlanket', [1.4, 1.4], [0, 0.7, 0.4], 0),
);
const first = analyzeOpenSurfacePenetration(build());
expect(JSON.stringify(analyzeOpenSurfacePenetration(build()))).toBe(JSON.stringify(first));
expect(first.penetrations.map((pair) => pair.solid)).toEqual(['Mesh_CurvedWall']);
});
test('a geometry shared by many meshes is measured once, with the same evidence', () => {
// The 2.6M-triangle cathedral places 1,707 meshes over 184 geometries; topology belongs to
// the geometry, so each placement measuring it again was pure repetition.
const wall = new THREE.BoxGeometry(2, 1.4, 0.12);
const sheet = new THREE.PlaneGeometry(1.4, 1.4, 8, 8);
const place = (geometry: THREE.BufferGeometry, name: string, x: number) => {
const mesh = new THREE.Mesh(geometry);
mesh.name = name;
mesh.position.set(x, 0.7, 0.4);
return mesh;
};
const build = (shared: boolean) =>
sceneOf(
...[0, 3, 6].flatMap((x, i) => [
place(shared ? wall : wall.clone(), `Mesh_Wall_${i}`, x),
place(shared ? sheet : sheet.clone(), `Mesh_Throw_${i}`, x),
]),
);
const separate = analyzeOpenSurfacePenetration(build(false));
const measured = spyOn(geometryModule, 'geometryDiagnostics');
try {
const sharedEvidence = analyzeOpenSurfacePenetration(build(true));
expect(measured).toHaveBeenCalledTimes(2);
expect(JSON.stringify(sharedEvidence)).toBe(JSON.stringify(separate));
expect(sharedEvidence.penetrations).toHaveLength(3);
} finally {
measured.mockRestore();
}
});
test('the rule takes its own measurement from the scene', () => {
const findings = OPEN_SURFACE_PENETRATION_QA_RULE.evaluate({
intent: createAssetIntentV1({ category: 'prop' }),
scene: sceneOf(
solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]),
cloth('Mesh_ThrowBlanket', [1, 1], [0, 0.7, 0.4], 0),
),
});
expect(findings.map((finding) => finding.code)).toEqual(['GEO_OPEN_SURFACE_PENETRATION']);
expect(findings[0]!.disposition).toBe('observe');
expect(findings[0]!.dimension).toBe('visualQuality');
});
});
describe('reported coverage', () => {
const base = {
schemaVersion: 1 as const,
source: 'engine-scene-analysis' as const,
contactTolerance: OPEN_SURFACE_CONTACT_TOLERANCE,
openParts: 2,
closedParts: 2,
candidatePairs: 4,
pairsTested: 1,
pairsNotReached: 3,
pairsLodAlternates: 0,
verticesUnresolved: 0,
truncated: true,
skipped: [],
penetrations: [],
};
test('a budget shortfall names the pairs it did not sample', () => {
const [finding] = inspectOpenSurfacePenetration(base);
expect(finding!.code).toBe('GEO_OPEN_SURFACE_PENETRATION_TRUNCATED');
expect(finding!.message).toContain('Sampled 1 of 4');
expect(finding!.message).not.toContain('could not be resolved');
expect(finding!.measurement!.breakdown).toEqual({
pairsNotReached: 3,
verticesUnresolved: 0,
});
});
test('unresolved vertices are reported apart from the budget, not as skipped work', () => {
const [finding] = inspectOpenSurfacePenetration({
...base,
pairsTested: 4,
pairsNotReached: 0,
truncated: false,
verticesUnresolved: 2,
});
expect(finding!.code).toBe('GEO_OPEN_SURFACE_PENETRATION_TRUNCATED');
expect(finding!.message).not.toContain('analysis budget');
expect(finding!.message).toContain('2 vertices');
expect(finding!.message).toContain('counted as neither');
});
test('complete coverage reports nothing', () => {
expect(
inspectOpenSurfacePenetration({
...base,
pairsTested: 4,
pairsNotReached: 0,
truncated: false,
}),
).toEqual([]);
});
});
describe('a positive is a measurement, not a verdict', () => {
/**
* Measured over the 86 shipped examples, 916 findings across 51 of them, against
* 3,575 from the part-volume pass across all 86. The dominant real case is not
* cloth: it is a fitting socketed into a structural shell, which is correct
* geometry and is still reported, exactly as the volume pass reports a bolt in a
* hole. This fixture pins that, so the pass is never mistaken for a defect gate.
*/
test('a fitting socketed into a hull shell is reported, like a bolt in a hole', () => {
// An open hull panel with a lamp recess set into it: the recess is meant to be there.
const hull = cloth('Mesh_HullPanel', [2, 1.2], [0, 0.6, 0], 0, 12);
const recess = solid('Mesh_LampRecess', [0.12, 0.12, 0.2], [0, 0.6, 0]);
const evidence = analyzeOpenSurfacePenetration(sceneOf(recess, hull));
expect(evidence.penetrations).toHaveLength(1);
const [finding] = inspectOpenSurfacePenetration(evidence);
expect(finding!.disposition).toBe('observe');
expect(finding!.repairText).toContain('not a defect');
expect(finding!.repairText).toContain('a bolt in a hole');
});
test('the finding carries the depth as a measurement against the tolerance', () => {
const evidence = analyzeOpenSurfacePenetration(
sceneOf(
solid('Mesh_CurvedWall', [2, 1.4, 0.12], [0, 0.7, 0.4]),
cloth('Mesh_ThrowBlanket', [1, 1], [0, 0.7, 0.4], 0),
),
);
const [finding] = inspectOpenSurfacePenetration(evidence);
expect(finding!.measurement).toMatchObject({
name: 'openSurfacePenetrationDepth',
expected: OPEN_SURFACE_CONTACT_TOLERANCE,
unit: 'm',
});
expect(finding!.measurement!.actual).toBeCloseTo(0.06, 4);
});
});