gps-plus-slam-app-framework 1.10.0 → 1.13.0

package/dist/ar/occupancy-grid.js

@@ -1,8 +1,40 @@
 import { createDepthUnprojector } from "./depth-unprojection.js";
 import { bresenham3d } from "./bresenham3d.js";
-import { i as cellKey, o as unpackCellCoord, r as cellCoordsInKeyRange, s as unpackCellKey, t as CELL_KEY_LIMIT } from "../cell-key-Bj-eYTLA.js";
+import { a as cellCoordsInKeyRange, c as unpackCellCoord, l as unpackCellKey, n as CELL_KEY_STRIDE_X, o as cellKey, r as CELL_KEY_STRIDE_Y, s as packCellKey, t as CELL_KEY_LIMIT } from "../cell-key-D1b_Ix-p.js";
 //#region ../src/ar/occupancy-grid.ts
 /**
+* Recommended reconstruction defaults for apps that build AND render an occupancy
+* mesh (the Recorder, the PhysicsDemo). These are the single framework-level source
+* of truth so every consumer inherits the same tuning — change them here and both
+* apps follow.
+*
+* They are DELIBERATELY separate from {@link OccupancyGrid}'s constructor fallback
+* (`cellSizeM ?? 0.15`, Unity parity): that primitive fallback stays 0.15 because a
+* pile of low-level tests build `new OccupancyGrid()` with no args and assume 0.15
+* quantization. Both apps always pass an explicit `cellSizeM`, so the app-facing
+* recommended default and the primitive fallback can differ without conflict.
+*
+* Tuning (2026-07-16 EVENING, maintainer's on-device framerate/mesh trade-off
+* pass — supersedes the same-day corpus-sweep values 0.18/3): voxel 16 cm,
+* noise floor 2. The sweep's argument for floor 3 (floaters = phantom
+* colliders: mc 3 ≈ 1.9% vs mc 2 ≈ 3.5%) was measured under LEGACY carving;
+* with the decay carve guard the floater gap largely disappears (real
+* pillar-orbit A/B: guarded mc 2 isolates 2.12% vs guarded mc 3 2.19%), so
+* the faster floor is affordable now. `0.16` stays within
+* `OCCUPANCY_CONSTRAINTS.cellSizeM.max` (0.20); `2` within `minConfidence`
+* 1–10. History: 2026-07-16-0557 corpus sweep (0.18/3),
+* 2026-07-15-1640 device-impression change (0.18/2). See the recorder's
+* recording-options.ts.md for the full tuning timeline.
+*/
+const DEFAULT_OCCUPANCY_CELL_SIZE_M = .16;
+/**
+* Recommended occupancy noise floor — the minimum observation count before a cell
+* is rendered/meshed (the Recorder's `minConfidence`, the demo's `minObservations`,
+* and — since the decay guard — both apps' `carveConfidenceThreshold`).
+* See {@link DEFAULT_OCCUPANCY_CELL_SIZE_M} for the rationale and the tuning note.
+*/
+const DEFAULT_OCCUPANCY_MIN_OBSERVATIONS = 2;
+/**
 * Highest `minConfidence` a consumer can ask for (mirrors
 * `OCCUPANCY_CONSTRAINTS.minConfidence.max`). Once a cell's count exceeds this,
 * further observations can no longer change ANY consumer's occupied set, so they
@@ -13,6 +45,13 @@ const MAX_RELEVANT_COUNT = 10;
 var OccupancyGrid = class {
 	cellSizeM;
 	carveStopCells;
+	/**
+	* Carve-blocking observation-count threshold, or undefined for legacy
+	* unguarded carving (see {@link OccupancyGridOptions}). Public + always
+	* present on instances so consumers built against a newer source can
+	* feature-detect the guard on an installed build at runtime.
+	*/
+	carveConfidenceThreshold;
 	cells = /* @__PURE__ */ new Map();
 	/**
 	* Chunk index (Step 2 of the 2026-07-03 long-session fps plan): cell keys
@@ -39,7 +78,7 @@ var OccupancyGrid = class {
 	* an already-settled cell (count `> MAX_RELEVANT_COUNT`) does NOT bump it, so a
 	* consumer can cheaply skip a full re-derive (cube refresh / occluder re-mesh)
 	* when the revision is unchanged — the dominant idle-time saving over a long
-	* session (see `2026-06-30-occluder-tuning-followups.md`).
+	* session (see `2026-06-30-0829-occluder-tuning-followups.md`).
 	*/
 	revision = 0;
 	/**
@@ -58,6 +97,7 @@ var OccupancyGrid = class {
 		if (!Number.isSafeInteger(carveStopCells) || carveStopCells < 0) throw new RangeError(`carveStopCells must be a non-negative integer, got ${carveStopCells}`);
 		this.cellSizeM = cellSizeM;
 		this.carveStopCells = carveStopCells;
+		this.carveConfidenceThreshold = validateCarveConfidenceThreshold(options?.carveConfidenceThreshold);
 	}
 	/** Number of occupied cells. */
 	get size() {
@@ -351,18 +391,153 @@ var OccupancyGrid = class {
 	* steps before the endpoint. The endpoint cell itself is additionally
 	* protected so a current observation is never erased (relevant for
 	* carveStopCells = 0 and for the unconditional start-cell visit).
+	*
+	* With `carveConfidenceThreshold` set, the trace additionally stops at the
+	* first cell whose count has reached the threshold, DECAYING it by one
+	* observation (means preserved) — soft contradiction instead of deletion,
+	* so nothing behind an established surface is carved but repeated
+	* contradictions still un-build it (see the option docs). Note this makes
+	* a repeated identical carve NOT a no-op — the per-sample unique-endpoint
+	* dedupe in `addSample` is therefore semantically load-bearing under the
+	* guard (one decay per contradicting ray per sample).
+	*
+	* PERFORMANCE — fused walk (2026-07-17 perf loop, iteration 1): this is
+	* the framework's hottest non-render loop (hundreds of rays per depth
+	* sample at the 200 ms reconstruction cadence), and the generic
+	* `bresenham3d(callback)` shape dominated the fold profile: a fresh
+	* `[x, y, z]` tuple + callback dispatch + full `cellKey` repack +
+	* `cellsEqual` per visited cell. The Bresenham walk (identical integer
+	* stepping, `bresenham3d` stays the reference — see the fold-oracle
+	* property test) is therefore fused in here with two key tricks:
+	*
+	* - The packed cell key is maintained INCREMENTALLY: stepping one cell
+	*   along an axis moves the key by that axis' constant field stride
+	*   (base-2^17 positional packing), replacing the 3-term repack.
+	* - The endpoint guard compares packed keys (`key === endpointKey`).
+	*   Every walked cell lies inside the camera→point AABB whose corners the
+	*   caller range-checked, so packing is bijective on the whole walk and
+	*   the compare is exactly `cellsEqual` — and key aliasing is impossible.
+	*
+	* The cell tuple is materialized only on an actual delete/decay hit (rare
+	* per trace, handled in {@link carveCellAt}). Measured on the
+	* occupancy-fold bench (devbox-win11, Node 24, 50 samples × 576 pts,
+	* production config): 37.05 → 25.71 ms median of 5, −30.6%.
+	* Input safety: cameraCell/pointCell are integer cells from
+	* `cellForPosition` (finite-checked upstream) and both range-checked by
+	* `addSample`, so dm ≤ 2·CELL_KEY_LIMIT « MAX_TRACE_STEPS and the generic
+	* tracer's integer/span guards are structurally satisfied here.
 	*/
 	carve(cameraCell, pointCell) {
-		bresenham3d(cameraCell, pointCell, (cell) => {
-			if (!cellsEqual(cell, pointCell)) {
-				const key = cellKey(cell);
-				if (this.cells.delete(key)) {
-					this.revision++;
-					this.unindexCell(cell, key);
-				}
+		const threshold = this.carveConfidenceThreshold;
+		const stopDistance = this.carveStopCells;
+		let x = cameraCell[0];
+		let y = cameraCell[1];
+		let z = cameraCell[2];
+		const ex = pointCell[0];
+		const ey = pointCell[1];
+		const ez = pointCell[2];
+		const dx = Math.abs(ex - x);
+		const dy = Math.abs(ey - y);
+		const dz = Math.abs(ez - z);
+		const sx = Math.sign(ex - x);
+		const sy = Math.sign(ey - y);
+		const sz = Math.sign(ez - z);
+		const keyStepX = sx * CELL_KEY_STRIDE_X;
+		const keyStepY = sy * CELL_KEY_STRIDE_Y;
+		const keyStepZ = sz;
+		const endpointKey = packCellKey(ex, ey, ez);
+		let key = packCellKey(x, y, z);
+		const dm = Math.max(dx, dy, dz);
+		let i = dm;
+		let errX = Math.floor(dm / 2);
+		let errY = errX;
+		let errZ = errX;
+		for (;;) {
+			if (key !== endpointKey && !this.carveCellAt(x, y, z, key, threshold)) return;
+			if (i-- <= stopDistance) return;
+			errX -= dx;
+			if (errX < 0) {
+				errX += dm;
+				x += sx;
+				key += keyStepX;
 			}
-			return true;
-		}, this.carveStopCells);
+			errY -= dy;
+			if (errY < 0) {
+				errY += dm;
+				y += sy;
+				key += keyStepY;
+			}
+			errZ -= dz;
+			if (errZ < 0) {
+				errZ += dm;
+				z += sz;
+				key += keyStepZ;
+			}
+		}
+	}
+	/**
+	* Per-cell action of the fused carve walk (extracted so both it and the
+	* walk stay under the lint complexity budget; a monomorphic private-method
+	* call per visited cell measured within noise of the fully-inlined form).
+	*
+	* @returns `false` when the trace must stop: the cell is an established
+	*   surface (count ≥ threshold) that was decayed instead of deleted.
+	*/
+	carveCellAt(x, y, z, key, threshold) {
+		const record = this.cells.get(key);
+		if (record === void 0) return true;
+		if (threshold !== void 0 && record.count >= threshold) {
+			this.decayCell([
+				x,
+				y,
+				z
+			], key, record);
+			return false;
+		}
+		this.cells.delete(key);
+		this.revision++;
+		this.unindexCell([
+			x,
+			y,
+			z
+		], key);
+		return true;
+	}
+	/**
+	* Soft contradiction of an established cell (confidence-guarded carving):
+	* remove one observation while preserving the measured point/color MEANS
+	* (sums are scaled with the count — decrementing the divisor alone would
+	* silently shift `getCellPoint`/`getCellColor`). Deletes outright when the
+	* count would reach 0 (threshold 1). Bumps revisions like any mutation
+	* that can change a consumer's occupied set (counts above
+	* MAX_RELEVANT_COUNT cannot cross any selectable floor, so those decays
+	* stay revision-silent).
+	*/
+	decayCell(cell, key, record) {
+		const newCount = record.count - 1;
+		if (newCount <= 0) {
+			if (this.cells.delete(key)) {
+				this.revision++;
+				this.unindexCell(cell, key);
+			}
+			return;
+		}
+		const scale = newCount / record.count;
+		record.count = newCount;
+		record.posSumX *= scale;
+		record.posSumY *= scale;
+		record.posSumZ *= scale;
+		if (record.colorCount > newCount) {
+			const colorScale = newCount / record.colorCount;
+			record.colorSumR *= colorScale;
+			record.colorSumG *= colorScale;
+			record.colorSumB *= colorScale;
+			record.colorCount = newCount;
+		}
+		if (newCount <= MAX_RELEVANT_COUNT) {
+			this.revision++;
+			this.bumpChunkRevision(chunkKeyOf(Math.floor(cell[0] / CHUNK_EDGE_CELLS), Math.floor(cell[1] / CHUNK_EDGE_CELLS), Math.floor(cell[2] / CHUNK_EDGE_CELLS)));
+		}
 	}
 	/** Add a newly-occupied cell to its chunk's index set. */
 	indexCell(cell, key) {
@@ -440,8 +615,13 @@ function unpackChunkCoord(key, axis) {
 function cellsEqual(a, b) {
 	return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
 }
+/** Constructor guard for {@link OccupancyGridOptions.carveConfidenceThreshold}. */
+function validateCarveConfidenceThreshold(threshold) {
+	if (threshold !== void 0 && (!Number.isSafeInteger(threshold) || threshold < 1)) throw new RangeError(`carveConfidenceThreshold must be a positive integer when set, got ${threshold}`);
+	return threshold;
+}
 function isFiniteTriple(v) {
 	return Number.isFinite(v[0]) && Number.isFinite(v[1]) && Number.isFinite(v[2]);
 }
 //#endregion
-export { OccupancyGrid, cellKey, unpackCellKey };
+export { DEFAULT_OCCUPANCY_CELL_SIZE_M, DEFAULT_OCCUPANCY_MIN_OBSERVATIONS, OccupancyGrid, cellKey, unpackCellKey };

package/dist/ar/occupancy-mesher.d.ts

@@ -1,2 +1,2 @@
-import { a as meshOccupiedCells, i as OccupancyMeshResult, n as MeshMode, r as MeshOccupiedCellsOptions, t as Aabb } from "../occupancy-mesher-BqnRd10x.js";
+import { a as meshOccupiedCells, i as OccupancyMeshResult, n as MeshMode, r as MeshOccupiedCellsOptions, t as Aabb } from "../occupancy-mesher-Co80tOpl.js";
 export { Aabb, MeshMode, MeshOccupiedCellsOptions, OccupancyMeshResult, meshOccupiedCells };