@zkmake/three-audit 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BufferGeometry, Mesh, Object3D } from "three";
+import { BatchedMesh, BufferGeometry, Mesh, Object3D } from "three";
 //#region src/scene.d.ts
 /**
  * Any three.js object, from whichever copy of three's types the app has. The checks take this, so
@@ -32,6 +32,18 @@ type BadGeometryRow = {
 };
 /** Meshes with geometry that renders NaN, hidden ones included. `[]` is a pass. */
 export declare const findBadGeometry: (root: AnyObject3D, options?: BadGeometryOptions) => BadGeometryRow[];
+type EmptyMeshRow = {
+  /** `path/to/mesh [material]`. */
+  mesh: string;
+  /** Not enumerable: kept out of JSON and `console.table`. */
+  readonly object: Mesh;
+};
+/**
+ * Meshes with no vertices, hidden ones included: what a merge of nothing leaves behind. They draw
+ * nothing, but each one is still a draw call and a leak to dispose. A draw range of zero doesn't
+ * count: that's usually a pool waiting to fill.
+ */
+export declare const findEmptyMeshes: (root: AnyObject3D, options?: Pick<BadGeometryOptions, "skip" | "tagKey">) => EmptyMeshRow[];
 //#endregion
 //#region src/triangles.d.ts
 type TriangleOptions = {
@@ -41,7 +53,7 @@ type MeshRow = {
   /** `path/to/mesh`: its named ancestors, then its name (or its geometry's name or type). */
   name: string;
   material: string;
-  /** Triangles in one copy (a batch's average). */
+  /** Triangles in one copy. A batch's is an average: `geometryCensus` breaks it down. */
   triangles: number;
   instances: number;
   total: number;
@@ -49,12 +61,28 @@ type MeshRow = {
   readonly mesh: Mesh;
 };
 type GeometryRow = {
-  /** `geometry.name`, or its type and the start of its uuid. */
+  /**
+   * `geometry.name`, or its type and the start of its uuid. For a geometry in a batch, the batch's
+   * `label` for it, or `batch#id`.
+   */
   geometry: string;
   /** Copies drawn: every mesh using it, instances counted. */
   uses: number;
   triangles: number;
   total: number;
+  /** Its part of the census's total, 0–1. */
+  share: number;
+  /** With `budget`: whether `share` is over it. */
+  overBudget?: boolean;
+};
+type CensusOptions = TriangleOptions & {
+  /**
+   * Names a geometry inside a batch, e.g. from the app's own table of what it added. Default
+   * `batch#id`, the batch named by its path.
+   */
+  label?: ((batch: BatchedMesh, geometryId: number) => string | undefined) | undefined;
+  /** Flag rows whose share of the total is over this, 0–1: `0.2` for anything over 20%. */
+  budget?: number | undefined;
 };
 /**
  * Triangles one pass draws: visible meshes, instances counted, no frustum culling. A shadow pass
@@ -65,10 +93,16 @@ export declare const countTriangles: (root: AnyObject3D, options?: TriangleOptio
 export declare const listMeshes: (scene: AnyObject3D, options?: TriangleOptions) => MeshRow[];
 /**
  * Geometries by triangles drawn, hidden meshes included, most first. Name geometries
- * (`geometry.name`) to make this readable. Batches are left out: their shared buffer is not one
- * geometry; `listMeshes` counts them.
+ * (`geometry.name`) to make this readable. A batch counts each geometry in it separately, by its
+ * visible instances: the row a budget is really spent on.
+ */
+export declare const geometryCensus: (root: AnyObject3D, options?: CensusOptions) => GeometryRow[];
+/**
+ * Draw calls one main pass makes: one per visible mesh, line or point cloud, or one per material
+ * group for a mesh with several materials. Before frustum culling; each shadow-casting light adds
+ * one per caster. `recordDrawLedger` counts the real thing.
  */
-export declare const geometryCensus: (root: AnyObject3D, options?: TriangleOptions) => GeometryRow[];
+export declare const countDraws: (root: AnyObject3D, options?: TriangleOptions) => number;
 //#endregion
 //#region src/z-fighting.d.ts
 type ZFightingOptions = {
@@ -117,21 +151,46 @@ export declare const findZFighting: (scene: AnyObject3D, options?: ZFightingOpti
 type AuditSceneOptions = Pick<ZFightingOptions, "gap" | "self" | "tagged"> & {
   skip?: Skip | undefined;
   tagKey?: string;
+  /** Only the object(s) tagged this (`userData[tagKey]`): one studio object out of a scene. */
+  tag?: string | undefined;
   /** How many of the costliest meshes to list. */
   top?: number;
 };
 type AuditReport = {
   triangles: number;
+  /** Draw calls one main pass makes, before culling and shadows: see `countDraws`. */
+  draws: number;
   zFighting: ZFightingRow[];
   badGeometry: BadGeometryRow[];
+  emptyMeshes: EmptyMeshRow[];
   /** The costliest meshes, most triangles first. */
   meshes: MeshRow[];
 };
 /**
  * Every check at once, JSON-safe: what a test asserts on or a headless browser prints. A clean
- * scene has `zFighting` and `badGeometry` both `[]`.
+ * scene has `zFighting`, `badGeometry` and `emptyMeshes` all `[]`.
  */
 export declare const auditScene: (root: AnyObject3D, options?: AuditSceneOptions) => AuditReport;
+type AuditSummaryOptions = Pick<AuditSceneOptions, "gap" | "skip" | "tag" | "tagKey"> & {
+  /** Run the z-fighting check, the slow one. Default true; false gives `null` counts. */
+  zFighting?: boolean;
+};
+type AuditSummary = {
+  triangles: number;
+  draws: number;
+  meshes: number;
+  /** Pairs of meshes that z-fight, identical pairs counted each. */
+  zFighting: number | null;
+  /** Meshes that z-fight with themselves: merged geometry whose parts overlap. */
+  selfZFighting: number | null;
+  badGeometry: number;
+  emptyMeshes: number;
+};
+/**
+ * Every check as one count each: the single call to run after every edit. `0` everywhere (and
+ * `triangles`, `draws` where you expect them) is a pass. Use `auditScene` to see what failed.
+ */
+export declare const summarizeScene: (root: AnyObject3D, options?: AuditSummaryOptions) => AuditSummary;
 //#endregion
 //#region src/black-frames.d.ts
 /** The `WebGLRenderer` methods the probe uses, typed loosely to fit any copy of three's types. */
@@ -170,6 +229,10 @@ export declare const watchBlackFrames: (renderer: ProbeRenderer, options?: Black
 type LedgerRenderer = {
   render(scene: AnyObject3D, camera: object): void;
   renderBufferDirect(camera: object, scene: object | null, geometry: object, material: object, object: AnyObject3D, group: unknown): void;
+  /** For pass sizes: the target being drawn to, `null` for the screen. */
+  getRenderTarget?(): unknown;
+  /** For pass sizes: the screen's drawing buffer, device pixels. */
+  getContext?(): unknown;
 };
 type DrawLedgerOptions = {
   /**
@@ -193,6 +256,18 @@ type LedgerRow = {
   /** Draws per pass name. */
   passes: Record<string, number>;
 };
+type PassRow = {
+  name: string;
+  draws: number;
+  /** Distinct objects drawn: for `shadow`, the casters. */
+  objects: number;
+  /** Triangles drawn, instances counted. */
+  triangles: number;
+  /** Sizes drawn to, in device pixels: `2880×1800`, or `screen 2880×1800`. */
+  targets: string[];
+  /** Every call was one small mesh through an orthographic camera: a post-processing pass. */
+  fullscreen: boolean;
+};
 type DrawLedger = {
   /**
    * Pass names in the order they first drew: `shadow`, then each `render()` call as its scene's
@@ -204,6 +279,11 @@ type DrawLedger = {
   /** By object name, most draws first. */
   objects: LedgerRow[];
   draws: number;
+  /** Each pass's draws, triangles, casters and target sizes, in `passes` order. */
+  passStats: PassRow[];
+  /** `render()` calls that drew one fullscreen pass, and the pixels they shaded between them. */
+  fullscreenPasses: number;
+  fullscreenPixels: number;
 };
 type DrawLedgerRecording = {
   /** Restore the renderer and return what was drawn since `beginDrawLedger`. */
@@ -234,6 +314,8 @@ type AuditHelpersOptions = {
   renderer?: (LedgerRenderer & ProbeRenderer) | undefined;
   skip?: Skip | undefined;
   tagKey?: string;
+  /** Names geometries inside a batch in `census()`: see `geometryCensus`'s `label`. */
+  batchLabel?: ((batch: BatchedMesh, geometryId: number) => string | undefined) | undefined;
   /**
    * Also put each helper on `globalThis` under its short name (`tris`, `report`…). Default true;
    * false leaves only `threeAudit`, for pages where short names collide with other tooling.
@@ -250,5 +332,38 @@ type AuditHelpersOptions = {
  */
 export declare const installAuditHelpers: (root: AnyObject3D, options?: AuditHelpersOptions) => () => void;
 //#endregion
-export type { AuditHelpersOptions, AuditReport, AuditSceneOptions, BadGeometryOptions, BadGeometryRow, BlackFrameOptions, BlackFrameWatch, DrawLedger, DrawLedgerOptions, DrawLedgerRecording, GeometryRow, LedgerRenderer, LedgerRow, MeshRow, ProbeRenderer, Skip, TriangleOptions, ZFightingOptions, ZFightingRow };
+//#region src/measure.d.ts
+type MeasureOptions = {
+  /** `userData` key a string target is looked up by. Default `studioObject`. */
+  tagKey?: string;
+};
+/** What to measure: an object, or a tag (`userData[tagKey]`), or failing that an object name. */
+type Target = string | AnyObject3D;
+type Bounds = {
+  min: [number, number, number];
+  max: [number, number, number];
+  size: [number, number, number];
+  centre: [number, number, number];
+};
+type Clearance = {
+  /**
+   * The smallest gap between the two, in world units. Measured between triangles' bounding boxes:
+   * exact for faces square to the axes, a slight underestimate for sloped ones. 0 when they touch
+   * or intersect.
+   */
+  gap: number;
+  /** The axis the gap is measured along, when it's straight along one; `null` when diagonal. */
+  axis: "x" | "y" | "z" | null;
+  /** The closest meshes, one from each side. */
+  between: [string, string];
+};
+/** A target's world envelope, from its visible meshes' vertices; `null` when it draws nothing. */
+export declare const measureBounds: (root: AnyObject3D, target: Target, options?: MeasureOptions) => Bounds | null;
+/**
+ * The gap between two targets, and which of their meshes come closest. Throws when a target
+ * matches nothing; `null` when either draws nothing. Meshes in both targets are left out of `a`.
+ */
+export declare const measureClearance: (root: AnyObject3D, a: Target, b: Target, options?: MeasureOptions) => Clearance | null;
+//#endregion
+export type { AnyObject3D, AuditHelpersOptions, AuditReport, AuditSceneOptions, AuditSummary, AuditSummaryOptions, BadGeometryOptions, BadGeometryRow, BlackFrameOptions, BlackFrameWatch, Bounds, CensusOptions, Clearance, DrawLedger, DrawLedgerOptions, DrawLedgerRecording, EmptyMeshRow, GeometryRow, LedgerRenderer, LedgerRow, MeasureOptions, MeshRow, PassRow, ProbeRenderer, RecordDrawLedgerOptions, Skip, Target, TriangleOptions, ZFightingOptions, ZFightingRow };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as listMeshes, c as triangleCount, i as geometryCensus, n as findZFighting, o as findBadGeometry, r as countTriangles, s as pathOf, t as auditScene } from "./audit-scene-BYsJcco9.js";
+import { _ as triangleCount, a as countTriangles, c as findBadGeometry, d as batchedTriangles, f as isBatched, g as pathOf, h as meshLabel, i as countDraws, l as findEmptyMeshes, m as isMesh, n as summarizeScene, o as geometryCensus, p as isInstanced, r as findZFighting, s as listMeshes, t as auditScene, u as asObject3D, v as walk } from "./audit-scene-CJG1DgRF.js";
 //#region src/patch.ts
 /** Swap `key` on `target` for `value`; the returned function puts back exactly what was there. */
 const patch = (target, key, value) => {
@@ -122,6 +122,15 @@ const tally = (rows, name, pass) => {
 	rows.set(name, row);
 };
 const sorted = (rows) => [...rows.values()].sort((a, b) => b.total - a.total);
+/** Triangles one draw makes: its material group's range, times its instances. */
+const drawTriangles = (geometry, object, group) => {
+	const mesh = object;
+	if (mesh.isMesh !== true) return 0;
+	if (isBatched(mesh)) return batchedTriangles(mesh).triangles;
+	const range = group;
+	const elements = geometry.index?.count ?? geometry.attributes.position?.count ?? 0;
+	return (range && typeof range.count === "number" ? Math.floor(Math.max(0, Math.min(range.count, elements - (range.start ?? 0))) / 3) : triangleCount(geometry)) * (isInstanced(mesh) ? mesh.count : 1);
+};
 /** Start counting every draw. Call `end()` after the frame to restore the renderer and read it. */
 const beginDrawLedger = (renderer, options = {}) => {
 	if (typeof renderer.renderBufferDirect !== "function") throw new TypeError("three-audit: the draw ledger needs a WebGLRenderer");
@@ -131,23 +140,89 @@ const beginDrawLedger = (renderer, options = {}) => {
 	const passes = [];
 	const objects = /* @__PURE__ */ new Map();
 	const groups = /* @__PURE__ */ new Map();
+	const stats = /* @__PURE__ */ new Map();
+	const calls = [];
 	let renders = 0;
 	let current = "direct";
 	let draws = 0;
+	let fullscreenPasses = 0;
+	let fullscreenPixels = 0;
+	const statOf = (pass) => {
+		let stat = stats.get(pass);
+		if (!stat) {
+			stat = {
+				name: pass,
+				draws: 0,
+				triangles: 0,
+				objects: /* @__PURE__ */ new Set(),
+				targets: /* @__PURE__ */ new Set(),
+				calls: 0,
+				fullscreenCalls: 0
+			};
+			stats.set(pass, stat);
+		}
+		return stat;
+	};
+	const sizeNow = () => {
+		const target = renderer.getRenderTarget?.();
+		if (target && typeof target.width === "number" && typeof target.height === "number") return {
+			width: target.width,
+			height: target.height,
+			screen: false
+		};
+		const gl = renderer.getContext?.();
+		return target === null && typeof gl?.drawingBufferWidth === "number" ? {
+			width: gl.drawingBufferWidth,
+			height: gl.drawingBufferHeight ?? 0,
+			screen: true
+		} : null;
+	};
 	const restoreRender = patch(renderer, "render", function(scene, camera) {
 		const outer = current;
 		renders += 1;
 		current = scene.name || `render ${renders}`;
+		const call = {
+			pass: current,
+			draws: 0,
+			orthographic: camera.isOrthographicCamera === true,
+			vertices: 0,
+			size: null
+		};
+		calls.push(call);
 		try {
 			render.call(this, scene, camera);
 		} finally {
+			calls.pop();
 			current = outer;
+			const stat = stats.get(call.pass);
+			if (stat) {
+				stat.calls += 1;
+				if (call.draws === 1 && call.orthographic && call.vertices <= 6) {
+					stat.fullscreenCalls += 1;
+					fullscreenPasses += 1;
+					fullscreenPixels += call.size ? call.size.width * call.size.height : 0;
+				}
+			}
 		}
 	});
 	const restoreDraw = patch(renderer, "renderBufferDirect", function(camera, scene, geometry, material, object, group) {
-		const pass = material.isMeshDepthMaterial === true || material.isMeshDistanceMaterial === true ? "shadow" : current;
+		const shadow = material.isMeshDepthMaterial === true || material.isMeshDistanceMaterial === true;
+		const pass = shadow ? "shadow" : current;
 		const name = nameOf(object, material);
 		if (!passes.includes(pass)) passes.push(pass);
+		const stat = statOf(pass);
+		const size = sizeNow();
+		const drawn = geometry;
+		stat.draws += 1;
+		stat.triangles += drawTriangles(drawn, object, group);
+		stat.objects.add(object);
+		if (size) stat.targets.add(`${size.screen ? "screen " : ""}${size.width}×${size.height}`);
+		const call = calls.at(-1);
+		if (call && !shadow) {
+			call.draws += 1;
+			call.vertices = drawn.attributes?.position?.count ?? Infinity;
+			call.size = size;
+		}
 		draws += 1;
 		tally(objects, name, pass);
 		tally(groups, groupOf(name), pass);
@@ -160,7 +235,20 @@ const beginDrawLedger = (renderer, options = {}) => {
 			passes,
 			groups: sorted(groups),
 			objects: sorted(objects),
-			draws
+			draws,
+			passStats: passes.map((pass) => {
+				const stat = stats.get(pass);
+				return {
+					name: pass,
+					draws: stat.draws,
+					objects: stat.objects.size,
+					triangles: stat.triangles,
+					targets: [...stat.targets],
+					fullscreen: stat.calls > 0 && stat.fullscreenCalls === stat.calls
+				};
+			}),
+			fullscreenPasses,
+			fullscreenPixels
 		};
 	} };
 };
@@ -205,28 +293,281 @@ const ledgerTable = (rows, passes) => rows.map((row) => ({
 const printDrawLedger = (ledger) => {
 	console.group(`Draw ledger: ${ledger.draws} draws in one frame`);
 	console.table(ledgerTable(ledger.groups, ledger.passes));
+	console.table(ledger.passStats.map((pass) => ({
+		...pass,
+		targets: pass.targets.join(", ")
+	})));
+	if (ledger.fullscreenPasses > 0) console.log(`${ledger.fullscreenPasses} fullscreen passes: ${(ledger.fullscreenPixels / 1e6).toFixed(1)} Mpx shaded`);
 	console.groupCollapsed("Every object");
 	console.table(ledgerTable(ledger.objects, ledger.passes));
 	console.groupEnd();
 	console.groupEnd();
 };
 //#endregion
-//#region src/console-helpers.ts
+//#region src/measure.ts
+const multiply = (a, b, out) => {
+	for (let row = 0; row < 4; row += 1) for (let column = 0; column < 4; column += 1) {
+		let sum = 0;
+		for (let k = 0; k < 4; k += 1) sum += a[k * 4 + row] * b[column * 4 + k];
+		out[column * 4 + row] = sum;
+	}
+	return out;
+};
+/** Every triangle a mesh draws, in world space: each instance of an instanced or batched mesh. */
+const eachTriangle = (mesh, visit) => {
+	const { index, attributes } = mesh.geometry;
+	const position = attributes.position;
+	if (!position) return;
+	const world = mesh.matrixWorld.elements;
+	const corner = [
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0,
+		0
+	];
+	const emit = (matrix, first, count, indexed) => {
+		for (let k = first; k + 2 < first + count; k += 3) {
+			for (let c = 0; c < 3; c += 1) {
+				const v = indexed ? index.getX(k + c) : k + c;
+				const x = position.getX(v);
+				const y = position.getY(v);
+				const z = position.getZ(v);
+				for (let axis = 0; axis < 3; axis += 1) corner[c * 3 + axis] = matrix[axis] * x + matrix[axis + 4] * y + matrix[axis + 8] * z + matrix[axis + 12];
+			}
+			visit(...corner);
+		}
+	};
+	if (isBatched(mesh)) {
+		const batch = mesh;
+		const instance = Array.from({ length: 16 }, () => 0);
+		const matrix = Array.from({ length: 16 }, () => 0);
+		const target = { fromArray(array, offset = 0) {
+			for (let i = 0; i < 16; i += 1) instance[i] = array[offset + i];
+			return target;
+		} };
+		for (let id = 0; id < batch.maxInstanceCount; id += 1) {
+			let range;
+			try {
+				if (!batch.getVisibleAt(id)) continue;
+				range = batch.getGeometryRangeAt(batch.getGeometryIdAt(id));
+				batch.getMatrixAt(id, target);
+			} catch {
+				continue;
+			}
+			multiply(world, instance, matrix);
+			if (index) emit(matrix, range.indexStart, range.indexCount, true);
+			else emit(matrix, range.vertexStart, range.vertexCount, false);
+		}
+		return;
+	}
+	const { start, count } = mesh.geometry.drawRange;
+	const elements = index?.count ?? position.count;
+	const first = Math.min(start, elements);
+	const drawn = Math.min(elements, start + count) - first;
+	if (isInstanced(mesh)) {
+		const matrix = Array.from({ length: 16 }, () => 0);
+		const instances = mesh.instanceMatrix.array;
+		for (let i = 0; i < mesh.count; i += 1) {
+			multiply(world, Array.prototype.slice.call(instances, i * 16, i * 16 + 16), matrix);
+			emit(matrix, first, drawn, index !== null);
+		}
+		return;
+	}
+	emit(world, first, drawn, index !== null);
+};
+const emptyBox = () => [
+	Infinity,
+	Infinity,
+	Infinity,
+	-Infinity,
+	-Infinity,
+	-Infinity
+];
+const grow = (box, x, y, z) => {
+	box[0] = Math.min(box[0], x);
+	box[1] = Math.min(box[1], y);
+	box[2] = Math.min(box[2], z);
+	box[3] = Math.max(box[3], x);
+	box[4] = Math.max(box[4], y);
+	box[5] = Math.max(box[5], z);
+};
+/** Per axis, how far apart two boxes are (0 where they overlap). */
+const apart = (a, ai, b, bi, out) => {
+	for (let axis = 0; axis < 3; axis += 1) out[axis] = Math.max(0, a[ai + axis] - b[bi + axis + 3], b[bi + axis] - a[ai + axis + 3]);
+	return Math.hypot(out[0], out[1], out[2]);
+};
+const round = (value) => {
+	const rounded = Math.round(value * 1e3) / 1e3;
+	return rounded === 0 ? 0 : rounded;
+};
+/** The visible meshes a target stands for. */
+const meshesOf = (root, target, tagKey, role) => {
+	let objects;
+	if (typeof target === "string") {
+		const tagged = [];
+		const named = [];
+		walk(root, {}, (object) => {
+			const tag = object.userData[tagKey];
+			if (tag !== void 0 && tag !== null && String(tag) === target) tagged.push(object);
+			else if (object.name === target) named.push(object);
+		});
+		objects = tagged.length > 0 ? tagged : named;
+		if (objects.length === 0) throw new Error(`three-audit: ${role}: nothing is tagged userData.${tagKey} = "${target}" or named "${target}"`);
+	} else objects = [asObject3D(target)];
+	const meshes = /* @__PURE__ */ new Set();
+	for (const object of objects) walk(object, { visibleOnly: true }, (child) => {
+		if (isMesh(child)) meshes.add(child);
+	});
+	return meshes;
+};
+/** A target's world envelope, from its visible meshes' vertices; `null` when it draws nothing. */
+const measureBounds = (root, target, options = {}) => {
+	const scene = asObject3D(root);
+	scene.updateWorldMatrix(true, true);
+	const box = emptyBox();
+	for (const mesh of meshesOf(scene, target, options.tagKey ?? "studioObject", "bounds")) eachTriangle(mesh, (ax, ay, az, bx, by, bz, cx, cy, cz) => {
+		grow(box, ax, ay, az);
+		grow(box, bx, by, bz);
+		grow(box, cx, cy, cz);
+	});
+	if (box[0] > box[3]) return null;
+	return {
+		min: [
+			box[0],
+			box[1],
+			box[2]
+		].map(round),
+		max: [
+			box[3],
+			box[4],
+			box[5]
+		].map(round),
+		size: [
+			0,
+			1,
+			2
+		].map((axis) => round(box[axis + 3] - box[axis])),
+		centre: [
+			0,
+			1,
+			2
+		].map((axis) => round((box[axis] + box[axis + 3]) / 2))
+	};
+};
+/** Triangle boxes past this many pairs, a mesh pair is measured by its whole boxes instead. */
+const PAIR_LIMIT = 4e6;
 /**
-* The checks as console globals, for a dev page or a headless browser's `eval`: `tris()`,
-* `meshes()`, `census()`, `audit()`, `zfight()`, `report()`, and with a renderer `ledger()`,
-* `beginLedger()` and `blackFrames()`. All of them also sit on `threeAudit`, which is the only
-* global with `globals: false`.
+* The gap between two targets, and which of their meshes come closest. Throws when a target
+* matches nothing; `null` when either draws nothing. Meshes in both targets are left out of `a`.
 */
+const measureClearance = (root, a, b, options = {}) => {
+	const scene = asObject3D(root);
+	const tagKey = options.tagKey ?? "studioObject";
+	scene.updateWorldMatrix(true, true);
+	const inB = meshesOf(scene, b, tagKey, "clearance b");
+	const inA = [...meshesOf(scene, a, tagKey, "clearance a")].filter((mesh) => !inB.has(mesh));
+	const measure = (mesh) => {
+		const box = emptyBox();
+		eachTriangle(mesh, (ax, ay, az, bx, by, bz, cx, cy, cz) => {
+			grow(box, ax, ay, az);
+			grow(box, bx, by, bz);
+			grow(box, cx, cy, cz);
+		});
+		return {
+			mesh,
+			box,
+			triangles: null
+		};
+	};
+	const sideA = inA.map(measure).filter(({ box }) => box[0] <= box[3]);
+	const sideB = [...inB].map(measure).filter(({ box }) => box[0] <= box[3]);
+	if (sideA.length === 0 || sideB.length === 0) return null;
+	const trianglesOf = (side) => {
+		if (!side.triangles) {
+			const boxes = [];
+			eachTriangle(side.mesh, (ax, ay, az, bx, by, bz, cx, cy, cz) => {
+				boxes.push(Math.min(ax, bx, cx), Math.min(ay, by, cy), Math.min(az, bz, cz), Math.max(ax, bx, cx), Math.max(ay, by, cy), Math.max(az, bz, cz));
+			});
+			side.triangles = Float64Array.from(boxes);
+		}
+		return side.triangles;
+	};
+	const axes = [
+		0,
+		0,
+		0
+	];
+	const pairs = sideA.flatMap((left) => sideB.map((right) => ({
+		left,
+		right,
+		distance: apart(left.box, 0, right.box, 0, axes)
+	}))).sort((x, y) => x.distance - y.distance);
+	let best = Infinity;
+	let bestAxes = [
+		0,
+		0,
+		0
+	];
+	let between = [pairs[0].left.mesh, pairs[0].right.mesh];
+	for (const { left, right, distance } of pairs) {
+		if (distance >= best) break;
+		const leftTriangles = trianglesOf(left);
+		const rightTriangles = trianglesOf(right);
+		const near = (triangles, other) => {
+			const kept = [];
+			for (let t = 0; t < triangles.length; t += 6) if (apart(triangles, t, other, 0, axes) < best) kept.push(t);
+			return kept;
+		};
+		const nearLeft = near(leftTriangles, right.box);
+		const nearRight = near(rightTriangles, left.box);
+		if (nearLeft.length * nearRight.length > PAIR_LIMIT) {
+			if (distance < best) {
+				best = distance;
+				apart(left.box, 0, right.box, 0, axes);
+				bestAxes = [...axes];
+				between = [left.mesh, right.mesh];
+			}
+			continue;
+		}
+		for (const i of nearLeft) for (const j of nearRight) {
+			const gap = apart(leftTriangles, i, rightTriangles, j, axes);
+			if (gap < best) {
+				best = gap;
+				bestAxes = [...axes];
+				between = [left.mesh, right.mesh];
+			}
+		}
+	}
+	const separated = bestAxes.flatMap((value, axis) => value > 0 ? [axis] : []);
+	return {
+		gap: round(best),
+		axis: separated.length === 1 ? [
+			"x",
+			"y",
+			"z"
+		][separated[0]] : null,
+		between: [meshLabel(between[0], scene, tagKey), meshLabel(between[1], scene, tagKey)]
+	};
+};
+//#endregion
+//#region src/console-helpers.ts
 const NAMESPACE = "threeAudit";
 const NAMES = [
 	"auditRoot",
+	"summary",
 	"tris",
 	"meshes",
 	"census",
 	"audit",
 	"zfight",
 	"report",
+	"bbox",
+	"clearance",
 	"ledger",
 	"beginLedger",
 	"blackFrames"
@@ -243,13 +584,23 @@ const needsRenderer = (name) => () => {
 *            useLayoutEffect(() => installAuditHelpers(scene, { renderer: gl }), [scene, gl]);
 */
 const installAuditHelpers = (root, options = {}) => {
-	const { renderer, skip } = options;
+	const { renderer, skip, batchLabel } = options;
 	const tagKey = options.tagKey ?? "studioObject";
 	const helpers = {
 		auditRoot: root,
+		summary: (tag, summaryOptions = {}) => summarizeScene(root, {
+			skip,
+			tagKey,
+			...summaryOptions,
+			...tag === void 0 ? {} : { tag }
+		}),
 		tris: () => countTriangles(root, { skip }),
 		meshes: () => listMeshes(root, { skip }),
-		census: () => geometryCensus(root, { skip }),
+		census: (censusOptions = {}) => geometryCensus(root, {
+			skip,
+			label: batchLabel,
+			...censusOptions
+		}),
 		audit: () => findBadGeometry(root, {
 			skip,
 			tagKey
@@ -260,10 +611,13 @@ const installAuditHelpers = (root, options = {}) => {
 			...gap === void 0 ? {} : { gap },
 			...self === void 0 ? {} : { self }
 		}),
-		report: () => auditScene(root, {
+		report: (tag) => auditScene(root, {
 			skip,
-			tagKey
+			tagKey,
+			...tag === void 0 ? {} : { tag }
 		}),
+		bbox: (target) => measureBounds(root, target, { tagKey }),
+		clearance: (a, b) => measureClearance(root, a, b, { tagKey }),
 		ledger: renderer ? async (ledgerOptions) => {
 			const ledger = await recordDrawLedger(renderer, ledgerOptions);
 			printDrawLedger(ledger);
@@ -301,6 +655,6 @@ const installAuditHelpers = (root, options = {}) => {
 	};
 };
 //#endregion
-export { auditScene, beginDrawLedger, countTriangles, findBadGeometry, findZFighting, geometryCensus, installAuditHelpers, ledgerTable, listMeshes, printDrawLedger, recordDrawLedger, triangleCount, watchBlackFrames };
+export { auditScene, beginDrawLedger, countDraws, countTriangles, findBadGeometry, findEmptyMeshes, findZFighting, geometryCensus, installAuditHelpers, ledgerTable, listMeshes, measureBounds, measureClearance, printDrawLedger, recordDrawLedger, summarizeScene, triangleCount, watchBlackFrames };
 
 //# sourceMappingURL=index.js.map