gps-plus-slam-app-framework 1.0.7 → 1.1.0

package/dist/gps-anchor-DjC_3MoT.js

@@ -1,257 +0,0 @@
-import { registerFrameUpdate } from "./ar/frame-loop.js";
-import { isObjectInCameraFrustum } from "./visualization/frustum-visibility.js";
-import { calcRelativeCoordsInMeters } from "./core/index.js";
-import * as THREE from "three";
-//#region ../src/visualization/frame-conversions.ts
-/**
-* `frame-conversions` — small, pure coordinate-frame helpers for the AR scene
-* graph. Currently a single function, `nueToArLocal`, that converts a
-* GPS-world NUE point into the AR-odometry local frame of `arWorldGroup`.
-*
-* Background: the scene root is GPS-world NUE; `arWorldGroup.matrix` IS the
-* alignment matrix, which maps **AR-odometry NUE → GPS-world NUE**. So a
-* direct child of `arWorldGroup` whose WORLD position must equal a GPS-world
-* point `nue` has to store `alignment⁻¹ · nue` as its LOCAL position —
-* writing raw `nue` double-applies the alignment. Getting this wrong was the
-* alignment-frame bug
-* (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md);
-* this helper centralises the conversion behind one tested, well-named seam.
-*
-* Design (see the plan
-* gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-nue-to-ar-local-helper-plan.md):
-*  - **Takes the explicit alignment matrix array**, NOT `Object3D.worldToLocal`.
-*    `worldToLocal` would read the live, mid-lerp `matrixWorld` and break
-*    replay determinism; the explicit target matrix keeps the result a pure
-*    function of its inputs. Full rationale in the review doc
-*    (gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-worldtolocal-frame-helper-review.md).
-*  - **Positions only.** No pose/quaternion variant exists until a caller
-*    needs one (YAGNI). No caller currently sets a GPS-world rotation.
-*/
-const scratchMatrix = new THREE.Matrix4();
-/**
-* Convert a GPS-world NUE point into the AR-local position to write into a
-* direct child of `arWorldGroup`, given the current alignment matrix.
-*
-* Computes `alignment⁻¹ · nue`. When the result is later composed back by the
-* group's matrix (the same `alignment`), the child's WORLD position equals
-* `nue` exactly.
-*
-* @param alignment - The alignment matrix as a 16-element **column-major**
-*   array (AR-odometry NUE → GPS-world NUE), e.g. from `getAlignmentMatrix()`
-*   or `THREE.Matrix4.toArray()`. Not mutated.
-* @param nue - The GPS-world NUE point `[north, up, east]` in metres. Not
-*   mutated.
-* @param out - Optional target vector to write into and return (pass a reused
-*   scratch to avoid allocation on hot paths). Defaults to a fresh
-*   `THREE.Vector3`.
-* @returns `out`, set to the AR-local position.
-*/
-function nueToArLocal(alignment, nue, out = new THREE.Vector3()) {
-	scratchMatrix.fromArray(alignment).invert();
-	return out.set(nue[0], nue[1], nue[2]).applyMatrix4(scratchMatrix);
-}
-//#endregion
-//#region ../src/visualization/gps-anchor.ts
-/**
-* `createGpsAnchor` — GPS-anchored placement of a single `THREE.Object3D`.
-*
-* See the colocated sidecar (`gps-anchor.ts.md`) and the port plan at
-* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-13-gps-anchor-port-plan.md`
-* for the full design, state machine, and test matrix.
-*
-* This file implements sub-steps 2 (bootstrap phase), 3 (steady-state
-* `'snap-every-tick'` + distance-scaled threshold gate), and 4
-* (`'snap-when-offscreen'` mode gate + alignment-matrix large-jump
-* bypass). Floor-Y correction is sub-step 6 and remains deferred.
-*/
-/**
-* Module-level registry of objects currently owned by a `GpsAnchor`.
-* Used to detect nested anchors (parent + child both anchored) which
-* we explicitly forbid; mirrors the C# invariant.
-*/
-const anchoredObjects = /* @__PURE__ */ new WeakSet();
-function isObjectInAnchoredChain(object) {
-	let cursor = object;
-	while (cursor) {
-		if (anchoredObjects.has(cursor)) return true;
-		cursor = cursor.parent;
-	}
-	return false;
-}
-function median(values) {
-	const sorted = [...values].sort((a, b) => a - b);
-	const mid = Math.floor(sorted.length / 2);
-	if (sorted.length % 2 === 0) return (sorted[mid - 1] + sorted[mid]) / 2;
-	return sorted[mid];
-}
-function medianPoint(samples) {
-	const lat = median(samples.map((s) => s.lat));
-	const lon = median(samples.map((s) => s.lon));
-	const alts = samples.map((s) => "altitude" in s ? s.altitude : void 0).filter((a) => typeof a === "number");
-	if (alts.length > 0) return {
-		lat,
-		lon,
-		altitude: median(alts)
-	};
-	return {
-		lat,
-		lon
-	};
-}
-function createGpsAnchor(options) {
-	if (isObjectInAnchoredChain(options.object3D)) throw new Error("createGpsAnchor: nested GpsAnchors are not supported — the supplied object3D is already inside an anchored parent chain.");
-	anchoredObjects.add(options.object3D);
-	const sampleCount = options.secondsToAccumulateGpsPose ?? 7;
-	if (sampleCount < 1) {
-		anchoredObjects.delete(options.object3D);
-		throw new Error("createGpsAnchor: secondsToAccumulateGpsPose must be >= 1 — use skipBootstrap:true to bypass the accumulation phase.");
-	}
-	const settlingSeconds = options.settlingSeconds ?? 0;
-	const distanceThreshold = options.distanceThreshold ?? 2;
-	options.angleThresholdInDegrees;
-	const mode = options.mode ?? "snap-when-offscreen";
-	const LARGE_JUMP_TRANSLATION_M = 4;
-	const LARGE_JUMP_Y_M = 20;
-	const LARGE_JUMP_ROTATION_DEG = 2;
-	const scratchTarget = new THREE.Vector3();
-	const scratchCamWorld = new THREE.Vector3();
-	const scratchObjWorld = new THREE.Vector3();
-	const scratchPrevMatrix = new THREE.Matrix4();
-	const scratchCurrMatrix = new THREE.Matrix4();
-	const scratchPrevTrans = new THREE.Vector3();
-	const scratchCurrTrans = new THREE.Vector3();
-	const scratchPrevQuat = new THREE.Quaternion();
-	const scratchCurrQuat = new THREE.Quaternion();
-	let phase = options.skipBootstrap === true ? "anchored" : "bootstrap";
-	let isFullyAnchored = phase === "anchored";
-	let gpsPoint = options.gpsPoint;
-	let phaseEnteredAtElapsed = null;
-	let lastSampleAtElapsed = null;
-	const samples = [];
-	/**
-	* Snapshot of the previous tick's alignment matrix. `null` until the
-	* first steady-state tick in which `getAlignmentMatrix()` returned a
-	* non-null value. Used by the large-jump bypass to compare against
-	* the current tick's matrix.
-	*/
-	let prevAlignmentMatrix = null;
-	/**
-	* Returns true iff the alignment matrix has jumped by more than the
-	* configured large-jump thresholds between `prev` and `curr`. A
-	* `null` `prev` (first tick) is treated as "no jump".
-	*/
-	const detectLargeAlignmentJump = (prev, curr) => {
-		if (prev === null || curr === null) return false;
-		scratchPrevMatrix.fromArray(prev);
-		scratchCurrMatrix.fromArray(curr);
-		scratchPrevTrans.setFromMatrixPosition(scratchPrevMatrix);
-		scratchCurrTrans.setFromMatrixPosition(scratchCurrMatrix);
-		const dTrans = scratchPrevTrans.distanceTo(scratchCurrTrans);
-		const dY = Math.abs(scratchCurrTrans.y - scratchPrevTrans.y);
-		scratchPrevQuat.setFromRotationMatrix(scratchPrevMatrix);
-		scratchCurrQuat.setFromRotationMatrix(scratchCurrMatrix);
-		const dRotDeg = scratchPrevQuat.angleTo(scratchCurrQuat) * 180 / Math.PI;
-		return dTrans > LARGE_JUMP_TRANSLATION_M || dY > LARGE_JUMP_Y_M || dRotDeg > LARGE_JUMP_ROTATION_DEG;
-	};
-	const enterBootstrap = () => {
-		phase = "bootstrap";
-		isFullyAnchored = false;
-		phaseEnteredAtElapsed = null;
-		lastSampleAtElapsed = null;
-		samples.length = 0;
-		prevAlignmentMatrix = null;
-	};
-	const commitMedian = () => {
-		gpsPoint = medianPoint(samples);
-		phase = "anchored";
-		isFullyAnchored = true;
-		samples.length = 0;
-	};
-	/**
-	* Steady-state: compute the GPS-world NUE target from the stored
-	* `gpsPoint` and the current `zeroRef`, map it into `arWorldGroup`'s
-	* AR-local frame via the inverse alignment matrix, and commit it to
-	* `object3D.position` iff the (AR-local) position delta exceeds the
-	* distance-scaled threshold AND the mode gate (with optional large-jump
-	* bypass) allows it.
-	*
-	* Frame note: `arWorldGroup.matrix` IS the alignment matrix, which maps
-	* **AR-odometry NUE → GPS-world NUE**. `object3D.position` is a *local*
-	* transform in that AR-odometry frame. To make the object's *world*
-	* position equal the GPS-world `nue`, the local target must be
-	* `alignment⁻¹ · nue` — writing raw `nue` would double-apply the
-	* alignment (world = `alignment · nue`). See
-	* `gps-plus-slam/GpsPlusSlamJs_Docs/docs/2026-05-31-gps-anchor-alignment-frame-bug.md`.
-	*
-	* Returns silently on missing inputs (no `zeroRef`, or no alignment
-	* matrix yet — an AR-local object cannot be placed without knowing the
-	* AR↔NUE transform).
-	*/
-	const maybeCommitSteadyState = () => {
-		const zero = options.getGpsZeroRef();
-		if (zero === null || zero === void 0) return;
-		const currentAlignment = options.getAlignmentMatrix();
-		const largeJump = detectLargeAlignmentJump(prevAlignmentMatrix, currentAlignment);
-		prevAlignmentMatrix = currentAlignment;
-		if (currentAlignment === null || currentAlignment === void 0) return;
-		const targetAlt = "altitude" in gpsPoint && typeof gpsPoint.altitude === "number" ? gpsPoint.altitude : 0;
-		const nue = calcRelativeCoordsInMeters(zero, gpsPoint, targetAlt, 0);
-		nueToArLocal(currentAlignment, [
-			nue[0],
-			nue[1],
-			nue[2]
-		], scratchTarget);
-		options.camera.getWorldPosition(scratchCamWorld);
-		options.object3D.getWorldPosition(scratchObjWorld);
-		const scale = 1 + 10 * scratchCamWorld.distanceTo(scratchObjWorld) / 100;
-		if (options.object3D.position.distanceTo(scratchTarget) < distanceThreshold * scale) return;
-		if (mode === "snap-when-offscreen" && !largeJump) {
-			if (isObjectInCameraFrustum(options.camera, options.object3D)) return;
-		}
-		options.object3D.position.copy(scratchTarget);
-	};
-	const tick = (_dt, elapsed) => {
-		if (phase === "anchored") {
-			maybeCommitSteadyState();
-			return;
-		}
-		if (phaseEnteredAtElapsed === null) {
-			phaseEnteredAtElapsed = elapsed;
-			lastSampleAtElapsed = elapsed - 1;
-		}
-		if (elapsed - phaseEnteredAtElapsed < settlingSeconds) return;
-		if (lastSampleAtElapsed !== null && elapsed - lastSampleAtElapsed < 1) return;
-		const sample = options.getCurrentGpsPoint();
-		if (sample === null || sample === void 0) return;
-		samples.push(sample);
-		lastSampleAtElapsed = elapsed;
-		if (samples.length >= sampleCount) commitMedian();
-	};
-	const unregister = registerFrameUpdate(tick);
-	return {
-		get phase() {
-			return phase;
-		},
-		get isFullyAnchored() {
-			return isFullyAnchored;
-		},
-		get gpsPoint() {
-			return gpsPoint;
-		},
-		markMovedExternally() {
-			enterBootstrap();
-		},
-		setGpsPoint(point) {
-			gpsPoint = point;
-		},
-		dispose() {
-			unregister();
-			anchoredObjects.delete(options.object3D);
-		},
-		__tickForTests(dt, elapsed) {
-			tick(dt, elapsed);
-		}
-	};
-}
-//#endregion
-export { nueToArLocal as n, createGpsAnchor as t };

package/dist/index-pOjUCKEP.d.ts

@@ -1,24 +0,0 @@
-import * as THREE from "three";
-
-//#region ../src/visualization/frame-conversions.d.ts
-/**
- * Convert a GPS-world NUE point into the AR-local position to write into a
- * direct child of `arWorldGroup`, given the current alignment matrix.
- *
- * Computes `alignment⁻¹ · nue`. When the result is later composed back by the
- * group's matrix (the same `alignment`), the child's WORLD position equals
- * `nue` exactly.
- *
- * @param alignment - The alignment matrix as a 16-element **column-major**
- *   array (AR-odometry NUE → GPS-world NUE), e.g. from `getAlignmentMatrix()`
- *   or `THREE.Matrix4.toArray()`. Not mutated.
- * @param nue - The GPS-world NUE point `[north, up, east]` in metres. Not
- *   mutated.
- * @param out - Optional target vector to write into and return (pass a reused
- *   scratch to avoid allocation on hot paths). Defaults to a fresh
- *   `THREE.Vector3`.
- * @returns `out`, set to the AR-local position.
- */
-declare function nueToArLocal(alignment: readonly number[], nue: readonly [number, number, number], out?: THREE.Vector3): THREE.Vector3;
-//#endregion
-export { nueToArLocal as t };