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
/**
* Bounded part-vs-part solid-overlap observation — T4.1
*
* ## Why intersection VOLUME, not triangle overlap
*
* The accept criterion demands true negatives for "intentional contact and
* socketed parts", and that is what rules out the cheaper checks:
*
* - **Bounding boxes** call a bolt in a hole, a wheel in a wheel well, and a
* handle through a loop all intersecting. Every one is correct geometry.
* - **Triangle overlap** cannot separate two parts that merely touch — a lid
* resting on a box, a wheel meeting the ground — from two parts occupying the
* same space. Contact is coplanar triangles; interpenetration is shared
* volume. A triangle test sees both as "they overlap".
*
* Boolean intersection volume distinguishes these fixtures: surfaces in
* contact enclose zero volume, interpenetrating solids enclose a real one. That
* is exactly the distinction the gate has to make, so it is measured directly
* rather than inferred from bounding boxes. Numeric tolerance and representation
* limits still apply; intentional joints can also share real volume.
*
* manifold-3d is already a dependency (`solids.ts`), so this costs no new
* package and reuses the same watertight-solid machinery CSG runs on.
*
* ## Bounded time
*
* Booleans are expensive and pair count grows quadratically, so the pass is
* staged:
*
* 1. **Broad phase** — world-space AABB overlap, capped at 250,000 pair checks.
* Rejects separated pairs for the price of six comparisons. Parts that do
* not share a bounding box cannot share volume. Parts on different LOD
* levels are alternates, not parts present together, and are not compared.
* 2. **Narrow phase** — candidates are visited deepest box overlap first
* (overlap volume over the smaller box). Each part is built as a solid at
* most once, capped by {@link MAX_SOLID_BUILDS}; a pair with a part that
* cannot be built (an open shell) is unmeasurable and costs no boolean.
* Builds left once every pair is classified check the parts met only
* beside such a part, so open parts are named rather than left unexamined.
* Booleans are capped by {@link MAX_NARROW_PHASE_PAIRS}. Pairs either cap
* leaves unvisited are counted and reported in `truncated` instead of
* silently checking less than the analysis claims.
*
* Meshes are also capped at {@link MAX_PART_TRIANGLES}; above that a single
* boolean stops being bounded-time in any useful sense. Skipped parts are
* reported, never dropped quietly.
*
* ## Intentionally open shells
*
* A part the author marked with `markOpenShell` (on itself or an ancestor)
* that cannot be built as a closed solid is listed in `acknowledged` with the
* author's reason, not in `skipped`. Nothing else changes: it is still
* attempted as a solid, a marked part that closes is measured like any other,
* a mark covers no other reason to skip, and every pair it leaves unmeasured
* is still counted. A mark states intent; it is never a measurement.
*
* ## Determinism
*
* Parts are collected in traversal order, candidates with equal box overlap
* keep traversal pair order, volumes are rounded to a fixed precision, and
* findings are sorted by name. The same scene yields the same report on every
* run and every machine.
*/
import * as THREE from 'three';
import { openShellIntent } from '../open-shell';
import { lodMembership } from './lod';
import type { QaContext, QaFinding } from './types';
import { KILN_ENGINE_QA_OWNER, type QaRule } from './registry';
/** Above this, one boolean is no longer bounded-time in any useful sense. */
export const MAX_PART_TRIANGLES = 20000;
/** Narrow-phase boolean budget. Broad phase normally leaves far fewer than this. */
export const MAX_NARROW_PHASE_PAIRS = 64;
/** Solid-build budget: as many parts as the boolean budget could ever need. */
export const MAX_SOLID_BUILDS = 2 * MAX_NARROW_PHASE_PAIRS;
/** Bound normalization of merged, disconnected closed shells before measuring volume. */
export const MAX_SOLID_COMPONENTS = 32;
/** Bound pair discovery even when many boxes overlap. */
export const MAX_BROAD_PHASE_PAIRS = 250_000;
/**
* Intersection volume below this fraction of the smaller part's volume is
* treated as contact rather than penetration.
*
* Not zero: two parts snapped flush share a surface, and floating-point
* evaluation of a boolean on coincident faces yields a sliver of volume rather
* than exactly nothing. The threshold is a fraction rather than an absolute so
* it means the same thing on a 2 cm bolt and a 20 m wall.
*/
export const CONTACT_VOLUME_FRACTION = 0.001;
export interface PartPenetrationPairV1 {
a: string;
b: string;
/** Absolute intersection volume in cubic meters. */
volume: number;
/** Intersection volume over the smaller part's volume, 0..1. */
fraction: number;
}
export interface PartPenetrationEvidenceV1 {
schemaVersion: 1;
source: 'engine-scene-analysis';
/** Eligible mesh parts collected; not every part necessarily reaches a boolean. */
partsAnalyzed: number;
/**
* Overlapping pairs found, excluding LOD alternates; a lower bound when
* broadPhaseTruncated is true. Equals pairsTested + pairsUnmeasurable + pairsNotReached.
*/
candidatePairs: number;
/** Pair discovery itself exhausted its budget; later pairs were not considered. */
broadPhaseTruncated?: boolean;
/** Pairs a boolean was actually run on. */
pairsTested: number;
/** Candidate pairs with a part that could not be built as a closed solid. */
pairsUnmeasurable: number;
/**
* Of pairsUnmeasurable, the pairs whose unbuildable parts are all acknowledged open shells.
* Present only with `acknowledged`. Overlap in these pairs is not ruled out.
*/
pairsUnmeasurableAcknowledged?: number;
/** Candidate pairs left unvisited by the boolean or solid-build budget. */
pairsNotReached: number;
/** Overlapping pairs on different LOD levels: alternates, deliberately not compared. */
pairsLodAlternates: number;
/** True when pair discovery or the narrow-phase budgets left pairs unexamined. */
truncated: boolean;
/** Parts skipped, with the reason — never silently dropped. */
skipped: { part: string; reason: string }[];
/** Pairs whose shared volume exceeds the contact threshold, worst first. */
penetrations: PartPenetrationPairV1[];
/**
* Parts marked with `markOpenShell` that could not be built as a closed solid, in traversal
* order: `reason` is why, as in `skipped`; `intent` is the author's reason for the mark.
* Present only when non-empty. These parts are not in `skipped`.
*/
acknowledged?: { part: string; reason: string; intent: string }[];
}
interface AnalyzedPart {
name: string;
mesh: THREE.Mesh;
box: THREE.Box3;
triangles: number;
center: THREE.Vector3;
scale: number;
/** Named sibling chain membership; independent chains can appear together. */
lod: ReturnType<typeof lodMembership>;
/** The author's `markOpenShell` reason on the part or an ancestor. */
intent: string | undefined;
}
/** An overlapping pair, by traversal index, with its box overlap over the smaller box. */
interface CandidatePair {
a: number;
b: number;
overlap: number;
}
const boxVolume = (box: THREE.Box3): number =>
(box.max.x - box.min.x) * (box.max.y - box.min.y) * (box.max.z - box.min.z);
/** Shared box volume over the smaller box's volume, 0..1; 0 for flat boxes. */
function boxOverlapRatio(a: THREE.Box3, b: THREE.Box3): number {
const shared =
Math.max(0, Math.min(a.max.x, b.max.x) - Math.max(a.min.x, b.min.x)) *
Math.max(0, Math.min(a.max.y, b.max.y) - Math.max(a.min.y, b.min.y)) *
Math.max(0, Math.min(a.max.z, b.max.z) - Math.max(a.min.z, b.min.z));
const ratio = shared / Math.min(boxVolume(a), boxVolume(b));
return Number.isFinite(ratio) ? ratio : 0;
}
/** Fixed precision so a report is byte-comparable across runs. */
const round = (n: number): number => Math.round(n * 1e9) / 1e9;
// Absolute decimal rounding erased micron-scale positive volumes. Keep relative precision.
const roundVolume = (n: number): number => Number(n.toPrecision(9));
function triangleCount(geometry: THREE.BufferGeometry): number {
const index = geometry.getIndex();
const position = geometry.getAttribute('position');
if (!position) return 0;
return Math.floor((index ? index.count : position.count) / 3);
}
/**
* Collect the meshes worth comparing, in traversal order.
*
* Only meshes with real geometry participate: a part with no triangles cannot
* penetrate anything, and including it would produce a boolean on an empty
* operand — which `solids.ts` now (correctly) throws on.
*/
function collectParts(
root: THREE.Object3D,
skipped: PartPenetrationEvidenceV1['skipped'],
): AnalyzedPart[] {
const parts: AnalyzedPart[] = [];
root.updateWorldMatrix(true, true);
root.traverseVisible((node) => {
const mesh = node as THREE.Mesh;
if (!mesh.isMesh || !mesh.geometry) return;
const name = mesh.name || '(unnamed mesh)';
if (
(mesh as THREE.InstancedMesh).isInstancedMesh ||
(mesh as THREE.SkinnedMesh).isSkinnedMesh ||
Object.values(mesh.geometry.morphAttributes).some((targets) => targets.length)
) {
skipped.push({
part: name,
reason: 'instancing, skin or morph deformation is unsupported by part-volume analysis',
});
return;
}
const total = mesh.geometry.index?.count ?? mesh.geometry.getAttribute('position')?.count ?? 0;
const range = mesh.geometry.drawRange;
if (range.start !== 0 || range.count < total) {
skipped.push({
part: name,
reason: 'partial triangle draw ranges are unsupported by part-volume analysis',
});
return;
}
const triangles = triangleCount(mesh.geometry);
if (triangles === 0) return;
if (triangles > MAX_PART_TRIANGLES) {
skipped.push({
part: name,
reason: `${triangles} triangles exceeds the ${MAX_PART_TRIANGLES}-triangle analysis budget`,
});
return;
}
// Bounds belong to this mesh, never its child meshes (which are independent parts).
mesh.geometry.computeBoundingBox();
const box = mesh.geometry.boundingBox!.clone().applyMatrix4(mesh.matrixWorld);
if (box.isEmpty()) return;
const center = box.getCenter(new THREE.Vector3());
const size = box.getSize(new THREE.Vector3());
const scale = Math.max(size.x, size.y, size.z);
if (
![...box.min, ...box.max, scale].every(Number.isFinite) ||
!(scale > 0) ||
!Number.isFinite(mesh.matrixWorld.determinant()) ||
mesh.matrixWorld.determinant() === 0
) {
skipped.push({
part: name,
reason: 'non-finite or collapsed transformed bounds cannot be measured',
});
return;
}
parts.push({
name,
mesh,
box,
triangles,
center,
scale,
lod: lodMembership(mesh),
intent: openShellIntent(mesh),
});
});
return parts;
}
/**
* Which pairs a caller wants measured. Filtered pairs spend no budget, so a composition of
* modules is not starved by the overlaps inside each one, which normal QA already reported.
*/
export type PartPairFilter = (a: THREE.Mesh, b: THREE.Mesh) => boolean;
/**
* Normalized triangle soup for one static mesh, as manifold wants it.
*
* Deliberately independent of `solids.ts`'s `threeToManifold`: that one walks a
* whole Object3D and enforces CSG's stricter operand contract, whereas this
* needs one already-located mesh and must tolerate geometry a QA pass should
* report on rather than throw over.
*/
function meshToArrays(
part: AnalyzedPart,
): { vertProperties: Float32Array; triVerts: Uint32Array } | null {
const { mesh, center, scale } = part;
const geometry = mesh.geometry;
const position = geometry.getAttribute('position') as THREE.BufferAttribute | undefined;
if (position?.itemSize !== 3) return null;
// Translate before transforming vertices, then normalize before Float32 conversion.
// Manifold solids are later placed in a shared pair frame using double transforms.
const matrix = mesh.matrixWorld.clone();
matrix.elements[12] -= center.x;
matrix.elements[13] -= center.y;
matrix.elements[14] -= center.z;
const v = new THREE.Vector3();
const verts = new Float32Array(position.count * 3);
for (let i = 0; i < position.count; i++) {
v.set(position.getX(i), position.getY(i), position.getZ(i))
.applyMatrix4(matrix)
.divideScalar(scale);
if (![v.x, v.y, v.z].every((n) => Number.isFinite(Math.fround(n)))) return null;
verts[i * 3] = v.x;
verts[i * 3 + 1] = v.y;
verts[i * 3 + 2] = v.z;
}
const index = geometry.getIndex();
let tris: Uint32Array;
if (index) {
if (index.count % 3 !== 0) return null;
tris = new Uint32Array(index.count);
for (let i = 0; i < index.count; i++) {
const id = index.getX(i);
if (!Number.isSafeInteger(id) || id < 0 || id >= position.count) return null;
tris[i] = id;
}
} else {
if (position.count % 3 !== 0) return null;
tris = new Uint32Array(position.count);
for (let i = 0; i < position.count; i++) tris[i] = i;
}
if (mesh.matrixWorld.determinant() < 0)
for (let i = 0; i < tris.length; i += 3)
[tris[i + 1], tris[i + 2]] = [tris[i + 2]!, tris[i + 1]!];
return { vertProperties: verts, triVerts: tris };
}
/**
* Measure how much volume every pair of parts shares.
*
* Async because manifold is WASM and initializes on first use. The QA registry
* evaluates rules synchronously, so this runs as a pre-pass and its result
* travels to the rule through `QaContext.derivedEvidence` — the seam that
* exists precisely for engine measurements a rule cannot take itself.
*/
export async function analyzePartPenetration(
root: THREE.Object3D,
options: { comparable?: PartPairFilter } = {},
): Promise<PartPenetrationEvidenceV1> {
const skipped: PartPenetrationEvidenceV1['skipped'] = [];
const parts = collectParts(root, skipped);
const base: PartPenetrationEvidenceV1 = {
schemaVersion: 1,
source: 'engine-scene-analysis',
partsAnalyzed: parts.length,
candidatePairs: 0,
pairsTested: 0,
pairsUnmeasurable: 0,
pairsNotReached: 0,
pairsLodAlternates: 0,
truncated: false,
skipped,
penetrations: [],
};
if (parts.length < 2) return base;
// Broad phase first, so an unwinnable scene never pays for WASM init.
const candidates: CandidatePair[] = [];
let considered = 0;
broadPhase: for (let i = 0; i < parts.length; i++) {
for (let j = i + 1; j < parts.length; j++) {
const a = parts[i]!;
const b = parts[j]!;
if (options.comparable && !options.comparable(a.mesh, b.mesh)) continue;
if (considered++ === MAX_BROAD_PHASE_PAIRS) {
base.broadPhaseTruncated = true;
break broadPhase;
}
if (!a.box.intersectsBox(b.box)) continue;
if (
a.lod &&
b.lod &&
a.lod.parent === b.lod.parent &&
a.lod.stem === b.lod.stem &&
a.lod.level !== b.lod.level
) {
base.pairsLodAlternates++;
continue;
}
candidates.push({ a: i, b: j, overlap: boxOverlapRatio(a.box, b.box) });
}
}
base.candidatePairs = candidates.length;
base.truncated = !!base.broadPhaseTruncated;
if (candidates.length === 0) return base;
// Deepest box overlap first: a small part buried in another's box is the likeliest
// real overlap, a grazing contact the least. Ties keep traversal pair order.
candidates.sort((x, y) => y.overlap - x.overlap || x.a - y.a || x.b - y.b);
const Module = await import('manifold-3d');
const wasm = await Module.default();
wasm.setup();
const { Manifold, Mesh } = wasm;
// Each part is built once. `null` records a part that cannot be a closed solid, so
// every later pair with it is unmeasurable without spending the boolean budget.
const solids = new Map<number, InstanceType<typeof Manifold> | null>();
// `open`: manifold could not close the part, the one failure a mark acknowledges.
const unbuildable: { index: number; reason: string; open: boolean }[] = [];
const build = (index: number): InstanceType<typeof Manifold> | null | undefined => {
if (solids.has(index)) return solids.get(index)!;
if (solids.size === MAX_SOLID_BUILDS) return undefined;
const part = parts[index]!;
let solid: InstanceType<typeof Manifold> | null = null;
try {
const arrays = meshToArrays(part);
if (arrays) {
const mesh = new Mesh({ numProp: 3, ...arrays });
// Three's primitives split vertices at UV/normal seams — a BoxGeometry
// has 24 positions for 8 corners — and manifold reads that as an open
// surface ("Not manifold"). merge() welds coincident positions, which
// is the same step `solids.ts` takes before every CSG operand.
mesh.merge();
solid = new Manifold(mesh);
const components = solid.decompose();
try {
if (
components.length > MAX_SOLID_COMPONENTS ||
components.some((part) => part.volume() <= 0)
) {
unbuildable.push({
index,
reason:
'compound solid exceeds the component budget or contains an unsupported inward shell',
open: false,
});
solid.delete();
solid = null;
} else if (components.length > 1) {
// Concatenating closed meshes does not take their union: intersections can
// double-count their overlapping interiors and exceed an operand's volume.
const union = Manifold.union(components);
solid.delete();
solid = union;
}
} finally {
for (const component of components) component.delete();
}
} else {
unbuildable.push({
index,
reason: 'its triangle positions or indices are invalid',
open: false,
});
}
} catch (err) {
// Failure to build a closed solid is unmeasured, never evidence of no intersection.
unbuildable.push({
index,
reason: `a valid closed solid could not be measured (${err instanceof Error ? err.message : String(err)})`,
open: true,
});
solid?.delete();
solid = null;
}
solids.set(index, solid);
return solid;
};
const penetrations: PartPenetrationPairV1[] = [];
const rangeSkips: PartPenetrationEvidenceV1['skipped'] = [];
const unmeasured: CandidatePair[] = [];
try {
for (const pair of candidates) {
if (solids.get(pair.a) === null || solids.get(pair.b) === null) {
base.pairsUnmeasurable++;
unmeasured.push(pair);
continue;
}
// Building also classifies parts past the boolean budget, within the build budget,
// so every open part the candidates reach is named rather than left unexamined.
const sa = build(pair.a);
const sb = sa === null ? null : build(pair.b);
if (sa === null || sb === null) {
base.pairsUnmeasurable++;
unmeasured.push(pair);
continue;
}
if (!sa || !sb || base.pairsTested === MAX_NARROW_PHASE_PAIRS) {
base.pairsNotReached++;
continue;
}
base.pairsTested++;
const a = parts[pair.a]!;
const b = parts[pair.b]!;
let overlap: InstanceType<typeof Manifold> | null = null;
const scale = Math.max(a.scale, b.scale);
const pa = sa.scale(a.scale / scale);
const scaledB = sb.scale(b.scale / scale);
const pb = scaledB.translate(b.center.clone().sub(a.center).divideScalar(scale).toArray());
try {
overlap = Manifold.intersection(pa, pb);
const volume = overlap.volume();
if (volume > 0) {
const smaller = Math.min(Math.abs(pa.volume()), Math.abs(pb.volume()));
const fraction = smaller > 0 ? volume / smaller : 0;
if (fraction > CONTACT_VOLUME_FRACTION) {
const assetVolume = volume * scale ** 3;
if (!Number.isFinite(assetVolume) || !(assetVolume > 0)) {
rangeSkips.push({
part: a.name,
reason: `intersection with ${JSON.stringify(b.name)} is outside representable volume range`,
});
continue;
}
penetrations.push({
a: a.name,
b: b.name,
volume: roundVolume(assetVolume),
fraction: round(fraction),
});
}
}
} finally {
overlap?.delete();
pa.delete();
pb.delete();
scaledB.delete();
}
}
// A part met only beside partners already known to be unbuildable was never built.
// Measurable pairs had the build budget first; what remains classifies these parts,
// so an open part is named even when its partner already made the pair unmeasurable.
for (const pair of candidates) {
if (solids.get(pair.a) === null) build(pair.b);
else if (solids.get(pair.b) === null) build(pair.a);
}
} finally {
for (const solid of solids.values()) solid?.delete();
}
base.truncated = !!base.broadPhaseTruncated || base.pairsNotReached > 0;
// Unbuildable parts are reported in traversal order, whatever order reached them. An open
// part the author marked is acknowledged with the mark's reason; every other one is skipped.
unbuildable.sort((x, y) => x.index - y.index);
const acknowledged: NonNullable<PartPenetrationEvidenceV1['acknowledged']> = [];
const acknowledgedIndices = new Set<number>();
for (const { index, reason, open } of unbuildable) {
const part = parts[index]!;
if (open && part.intent !== undefined) {
acknowledged.push({ part: part.name, reason, intent: part.intent });
acknowledgedIndices.add(index);
} else skipped.push({ part: part.name, reason });
}
skipped.push(...rangeSkips);
if (acknowledged.length) {
base.acknowledged = acknowledged;
// A pair is acknowledged only when every part that left it unmeasured is acknowledged.
base.pairsUnmeasurableAcknowledged = unmeasured.filter((pair) =>
[pair.a, pair.b]
.filter((index) => solids.get(index) === null)
.every((index) => acknowledgedIndices.has(index)),
).length;
}
// Worst first, then by name so equal-volume pairs keep a stable order.
penetrations.sort(
(x, y) => y.fraction - x.fraction || `${x.a}:${x.b}`.localeCompare(`${y.a}:${y.b}`),
);
base.penetrations = penetrations;
return base;
}
// -----------------------------------------------------------------------------
// The rule
// -----------------------------------------------------------------------------
function readEvidence(context: {
derivedEvidence?: Record<string, unknown>;
}): PartPenetrationEvidenceV1 | undefined {
const evidence = context.derivedEvidence?.['partPenetration'] as
| PartPenetrationEvidenceV1
| undefined;
return evidence?.schemaVersion === 1 ? evidence : undefined;
}
/**
* Report parts that occupy the same space.
*
* Starts in `observe` as the plan requires: it has no promotion evidence yet,
* and the registry will not let an unpromoted rule warn or block regardless.
*/
export const SELF_INTERSECTION_QA_RULE: QaRule = Object.freeze({
id: 'GEO_PART_SELF_INTERSECTION',
profile: 'geometry.selfIntersection',
scope: { kind: 'universal' as const },
// 'heuristic', not 'exact', even though the measurement IS exact — a boolean
// volume, not a proxy for one. In this registry `exact` is a promotion
// contract, not a statement about the arithmetic: every `exact` rule must sit
// in `enforce` with frozen conformance evidence, and the registry test
// enforces that. A rule with no evidence yet is `heuristic` regardless of how
// precise its measurement is. Reclassify to `exact` at the same time as
// freezing a fixture set and promoting, never before.
ruleClass: 'heuristic',
owner: KILN_ENGINE_QA_OWNER,
defaultMode: 'observe',
evaluate(context: QaContext): readonly QaFinding[] {
return inspectPartPenetration(readEvidence(context));
},
});
/** Names listed per unmeasured reason; the count covers the rest. */
const UNMEASURED_NAMES_SHOWN = 5;
/** Author reasons listed for acknowledged open shells; the count covers the rest. */
const ACKNOWLEDGED_REASONS_SHOWN = 5;
/** `"A", "B" and 3 more` for the first names of a group. */
const namedParts = (parts: readonly string[]): string => {
const named = parts.slice(0, UNMEASURED_NAMES_SHOWN).map((part) => JSON.stringify(part));
const more =
parts.length > UNMEASURED_NAMES_SHOWN
? ` and ${parts.length - UNMEASURED_NAMES_SHOWN} more`
: '';
return `${named.join(', ')}${more}`;
};
/**
* Open shells the author marked: one line per mark reason and build failure, the author's words
* quoted, and the pairs left unmeasured because of these parts alone. Overlap there stays open.
*/
function acknowledgedFinding(
acknowledged: NonNullable<PartPenetrationEvidenceV1['acknowledged']>,
pairs: number,
): QaFinding {
const groups = new Map<string, { intent: string; reason: string; parts: string[] }>();
for (const { part, reason, intent } of acknowledged) {
const key = JSON.stringify([intent, reason]);
const group = groups.get(key);
if (group) group.parts.push(part);
else groups.set(key, { intent, reason, parts: [part] });
}
const listed = [...groups.values()];
const shown = listed.slice(0, ACKNOWLEDGED_REASONS_SHOWN);
const lines = shown.map(
({ intent, reason, parts }) =>
`${parts.length} marked ${JSON.stringify(intent)}, because ${reason}: ${namedParts(parts)}.`,
);
const rest = listed.slice(ACKNOWLEDGED_REASONS_SHOWN);
if (rest.length) {
const count = rest.reduce((sum, group) => sum + group.parts.length, 0);
lines.push(
`${count} more ${count === 1 ? 'part' : 'parts'} marked with ${rest.length} other ${rest.length === 1 ? 'reason' : 'reasons'}.`,
);
}
const one = acknowledged.length === 1;
const which = one ? 'this part' : 'these parts';
const pairText =
pairs === 1
? ` 1 overlapping part pair was not measured because of ${which} alone; overlap there is not ruled out.`
: pairs > 1
? ` ${pairs} overlapping part pairs were not measured because of ${which} alone; overlap there is not ruled out.`
: '';
return {
code: 'GEO_PART_SELF_INTERSECTION_ACKNOWLEDGED',
disposition: 'observe' as const,
dimension: 'visualQuality' as const,
profile: 'geometry.selfIntersection',
message:
`${acknowledged.length} ${one ? 'part' : 'parts'} marked intentionally open (markOpenShell) ${one ? 'was' : 'were'} not measured as ${one ? 'a closed solid' : 'closed solids'}. ` +
`${lines.join(' ')}${pairText}`,
measurement: {
name: 'acknowledgedOpenShells',
actual: acknowledged.length,
breakdown: { pairsUnmeasurable: pairs },
},
};
}
/** Shared observation kernel; the measurement is derived by the engine, never asset metadata. */
export function inspectPartPenetration(evidence?: PartPenetrationEvidenceV1): readonly QaFinding[] {
if (!evidence) return [];
const findings: QaFinding[] = evidence.penetrations.map((pair) => ({
code: 'GEO_PART_SELF_INTERSECTION',
disposition: 'observe' as const,
dimension: 'visualQuality' as const,
profile: 'geometry.selfIntersection',
message: `Parts ${JSON.stringify(pair.a)} and ${JSON.stringify(pair.b)} occupy the same space: they share ${pair.volume.toPrecision(3)} m³, which is ${(pair.fraction * 100).toFixed(1)}% of the smaller part.`,
affected: { node: pair.a },
measurement: {
name: 'intersectionVolumeFraction',
actual: pair.fraction,
expected: CONTACT_VOLUME_FRACTION,
},
repairText:
'Check whether this overlap is intentional, such as a joined beam or embedded detail. For unintended solid overlap, move a part or use boolDiff to cut clearance. This observation does not test intersections within a single mesh, open surfaces, empty passage space or motion.',
}));
const pairsUnmeasurable = evidence.pairsUnmeasurable ?? 0;
const acknowledged = evidence.acknowledged ?? [];
const pairsAcknowledged = acknowledged.length
? Math.min(evidence.pairsUnmeasurableAcknowledged ?? 0, pairsUnmeasurable)
: 0;
if (evidence.truncated) {
const pairsNotReached = evidence.pairsNotReached ?? 0;
findings.push({
code: 'GEO_PART_SELF_INTERSECTION_TRUNCATED',
disposition: 'observe' as const,
dimension: 'visualQuality' as const,
profile: 'geometry.selfIntersection',
message:
`Tested ${evidence.pairsTested} of ${evidence.broadPhaseTruncated ? 'at least ' : ''}${evidence.candidatePairs} overlapping part pairs: ` +
`${pairsUnmeasurable} involve parts that could not be measured, ${pairsNotReached} were beyond the analysis budget (${MAX_NARROW_PHASE_PAIRS} booleans, ${MAX_SOLID_BUILDS} solids).` +
(evidence.broadPhaseTruncated
? ` Pair discovery stopped after ${MAX_BROAD_PHASE_PAIRS} box comparisons.`
: '') +
' Unreached pairs were not examined; the most overlapping bounding boxes were tested first.',
measurement: {
name: 'overlappingPartPairsTested',
actual: evidence.pairsTested,
expected: evidence.candidatePairs,
breakdown: { pairsUnmeasurable, pairsNotReached },
},
});
}
if (evidence.skipped.length) {
// One line per reason: an asset with forty open shells needs the reason once, not forty times.
const byReason = new Map<string, string[]>();
for (const { part, reason } of evidence.skipped) {
const parts = byReason.get(reason);
if (parts) parts.push(part);
else byReason.set(reason, [part]);
}
const reasons = [...byReason].map(
([reason, parts]) => `${parts.length} because ${reason}: ${namedParts(parts)}.`,
);
const one = evidence.skipped.length === 1;
const includes = one ? 'this part' : 'one of these parts';
// Pairs left unmeasured only by acknowledged open shells are counted with those.
const unmarked = pairsUnmeasurable - pairsAcknowledged;
const pairs =
unmarked === 1
? ` 1 overlapping part pair includes ${includes} and was not measured.`
: unmarked > 1
? ` ${unmarked} overlapping part pairs include ${includes} and were not measured.`
: '';
findings.push({
code: 'GEO_PART_SELF_INTERSECTION_UNMEASURED',
disposition: 'observe' as const,
dimension: 'visualQuality' as const,
profile: 'geometry.selfIntersection',
message: `${evidence.skipped.length} part-volume ${one ? 'measurement was' : 'measurements were'} unavailable. ${reasons.join(' ')}${pairs} ${one ? 'This part is' : 'These parts are'} not certified clear.`,
});
}
if (acknowledged.length) findings.push(acknowledgedFinding(acknowledged, pairsAcknowledged));
return findings;
}