gps-plus-slam-app-framework 1.3.0 → 1.4.0

package/dist/qr-pose-aggregation-CFlmLm6w.d.ts

@@ -0,0 +1,90 @@
+import { i as Pose } from "./qr-pose-Bt2reSw7.js";
+import { Quaternion } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-pose-aggregation.d.ts
+/** Default inlier half-angle (deg) — start ~12°, confirm on device. */
+declare const DEFAULT_ROTATION_INLIER_ANGLE_DEG = 12;
+interface AverageRotationOptions {
+  /**
+   * Reject samples whose geodesic angle to the reference exceeds this many
+   * degrees. Default {@link DEFAULT_ROTATION_INLIER_ANGLE_DEG}.
+   */
+  inlierAngleDeg?: number;
+  /**
+   * Provisional reference rotation for the first inlier pass. When omitted, a
+   * robust reference is chosen by MODE-FINDING (the sample with the most other
+   * samples within the inlier threshold — the densest cluster). This matters:
+   * the naive "use the latest sample" breaks exactly when the latest frame is
+   * the bad one, which is the whole reason for this filter.
+   */
+  reference?: Quaternion;
+}
+interface AverageRotationResult {
+  /** Robust mean rotation, a unit quaternion `[x,y,z,w]` (canonicalized w ≥ 0). */
+  quat: Quaternion;
+  /** How many samples lie within the inlier threshold of the final mean. */
+  inlierCount: number;
+  /** Max geodesic angle (deg) among the inliers to the final mean — the spread. */
+  maxAngleDeg: number;
+}
+/**
+ * Robust mean of a set of rotations (Option R1). Picks a reference (mode-finding,
+ * or `options.reference`), rejects samples beyond the angular threshold, averages
+ * the inliers, then does ONE refit pass against the provisional mean. Returns
+ * `null` for an empty input.
+ */
+declare function averageRotation(quats: readonly Quaternion[], options?: AverageRotationOptions): AverageRotationResult | null;
+interface AggregateQrPoseResult {
+  /** Filtered pose: per-axis median position + robust mean rotation. */
+  pose: Pose;
+  /** Max absolute per-axis deviation from the median position (meters). */
+  translationSpreadM: number;
+  /** Max geodesic angle among rotation inliers to the mean (degrees). */
+  rotationSpreadDeg: number;
+  /** Rotation inlier count (≤ pose count). */
+  inlierCount: number;
+}
+/**
+ * Aggregate a window of raw poses into one filtered pose + the spreads the
+ * stability gate consumes. Returns `null` for an empty window.
+ */
+declare function aggregateQrPose(poses: readonly Pose[], options?: AverageRotationOptions): AggregateQrPoseResult | null;
+/**
+ * Where the pose-stability gate sits for one marker, mirroring the size
+ * lifecycle (`QrSizeStatus`):
+ * - `unknown` — no observations yet.
+ * - `measuring` — observations accumulating but not enough / not converged.
+ * - `stable` — ≥ `minObservations` AND both spreads below threshold; the pose
+ *   may now drive the high-weight vote / the smooth overlay.
+ */
+type QrPoseStabilityStatus = 'unknown' | 'measuring' | 'stable';
+interface QrPoseStabilityOptions extends AverageRotationOptions {
+  /** Sliding-window size: aggregate only the last `window` poses. Default 8. */
+  window?: number;
+  /** Minimum observations before the gate can be `stable`. Default 5. */
+  minObservations?: number;
+  /** Max translation spread (m) allowed for `stable`. Default 0.03. */
+  maxTranslationSpreadM?: number;
+  /** Max rotation spread (deg) allowed for `stable`. Default 5. */
+  maxRotationSpreadDeg?: number;
+}
+interface QrPoseStability {
+  status: QrPoseStabilityStatus;
+  /** The filtered pose (present once there is ≥1 observation), else `null`. */
+  pose: Pose | null;
+  translationSpreadM: number;
+  rotationSpreadDeg: number;
+  inlierCount: number;
+  /** Observations actually aggregated (≤ `window`). */
+  sampleCount: number;
+}
+/**
+ * Evaluate the pose-stability lifecycle over the last `window` of `poses`
+ * (oldest→newest). The returned `pose` is the filtered aggregate whenever there
+ * is data, but it is only the gate's responsibility (`status === 'stable'`) to
+ * decide when a consumer may TRUST it for the vote — `selectStableQrPose` reads
+ * the pose only in the `stable` state.
+ */
+declare function evaluateQrPoseStability(poses: readonly Pose[], options?: QrPoseStabilityOptions): QrPoseStability;
+//#endregion
+export { QrPoseStability as a, aggregateQrPose as c, DEFAULT_ROTATION_INLIER_ANGLE_DEG as i, averageRotation as l, AverageRotationOptions as n, QrPoseStabilityOptions as o, AverageRotationResult as r, QrPoseStabilityStatus as s, AggregateQrPoseResult as t, evaluateQrPoseStability as u };

package/dist/qr-pose-aggregation-DXR9STHs.js

@@ -0,0 +1,200 @@
+import { quat } from "gl-matrix";
+//#region ../src/ar/qr-pose-aggregation.ts
+/**
+* QR pose aggregation — sliding-window pose stabilization
+* (docs `2026-06-16-followup-qr-pose-stabilization-sliding-window.md`).
+*
+* Pure, device-free, store-free robust aggregation of a STATIC fiducial's pose
+* across a short sliding window of detections. A QR is static in the world, so
+* the last N world poses should be (nearly) identical — disagreement is noise,
+* which robust aggregation removes. The aggregated pose is what drives the
+* high-weight GPS vote and the debug overlay, instead of a raw single-frame pose
+* whose ROTATION can swing (the on-device symptom this targets).
+*
+* Three layers, smallest first:
+* - {@link averageRotation} — Option R1: angle-thresholded inlier set + hemisphere-
+*   aligned quaternion average. The real new work; translation already had
+*   {@link medianQrPosition} but rotation had no counterpart. Quaternion double
+*   cover (`q` ≡ `−q`) is handled explicitly — the single most common bug here.
+* - {@link aggregateQrPose} — per-axis median position + R1 rotation, reporting
+*   the spreads + inlier count the stability gate needs.
+* - {@link evaluateQrPoseStability} — the `unknown → measuring → stable` lifecycle
+*   over the last `window` poses, mirroring the size lifecycle. The pose is only
+*   exposed (for the vote / overlay) once `stable`.
+*
+* Operates on plain `Pose` lists (no slice import) so BOTH the framework
+* controller and the demo controller can reuse it, and it is unit-testable
+* without a store. The slice selectors `selectStableQrPose` /
+* `selectQrPoseStability` wrap these over a marker's ring buffer.
+*
+* INVARIANT: the caller must feed RAW per-detection world poses here. Never feed
+* a previously-aggregated pose back in — the window would average its own output
+* and collapse toward whatever it first locked onto (a feedback loop that defeats
+* outlier rejection). The `qrDetected` ring buffer stores raw poses for exactly
+* this reason.
+*
+* @see ./qr-pose.ts — the `Pose` type and the (raw) pose solve this aggregates.
+* @see ../state/qr-detected-slice.ts — `selectStableQrPose` / `selectQrPoseStability`.
+*/
+const RAD2DEG = 180 / Math.PI;
+const DEG2RAD = Math.PI / 180;
+/** Default inlier half-angle (deg) — start ~12°, confirm on device. */
+const DEFAULT_ROTATION_INLIER_ANGLE_DEG = 12;
+function toGl(q) {
+	const g = quat.fromValues(q[0], q[1], q[2], q[3]);
+	return quat.normalize(g, g);
+}
+/**
+* Geodesic (shortest-arc) angle in radians between two unit quaternions.
+* Double-cover safe: uses `2·dot² − 1 = cos θ`, which is invariant to the sign
+* of either quaternion (`q` ≡ `−q`), and clamps for float error before `acos`.
+*/
+function geodesicAngleRad(a, b) {
+	const d = quat.dot(a, b);
+	const c = Math.min(1, Math.max(-1, 2 * d * d - 1));
+	return Math.acos(c);
+}
+/**
+* Average the samples within `thresholdRad` of `ref`. Each inlier is flipped
+* into `ref`'s hemisphere (sign of the dot) BEFORE the linear average so the
+* double cover cannot cancel the sum; the normalized linear average equals the
+* Markley eigenvector mean for a tight cluster and needs no eigensolver.
+* Returns `null` when no sample is within threshold.
+*/
+function meanOfInliers(samples, ref, thresholdRad) {
+	const inliers = [];
+	for (const s of samples) if (geodesicAngleRad(s, ref) <= thresholdRad) inliers.push(s);
+	if (inliers.length === 0) return null;
+	const acc = quat.fromValues(0, 0, 0, 0);
+	for (const s of inliers) {
+		const sign = quat.dot(s, ref) < 0 ? -1 : 1;
+		acc[0] += sign * s[0];
+		acc[1] += sign * s[1];
+		acc[2] += sign * s[2];
+		acc[3] += sign * s[3];
+	}
+	const mean = quat.normalize(quat.create(), acc);
+	let maxAngleRad = 0;
+	for (const s of inliers) maxAngleRad = Math.max(maxAngleRad, geodesicAngleRad(s, mean));
+	return {
+		mean,
+		inlierCount: inliers.length,
+		maxAngleRad
+	};
+}
+/**
+* Pick the densest sample as the reference: the one with the most OTHER samples
+* within the inlier threshold. For a single rigid pose, consensus-based outlier
+* rejection degenerates to this mode-finding, and it is robust to the latest
+* sample being an outlier.
+*/
+function bestReference(samples, thresholdRad) {
+	let best = samples[0];
+	let bestCount = -1;
+	for (const cand of samples) {
+		let count = 0;
+		for (const s of samples) if (geodesicAngleRad(s, cand) <= thresholdRad) count++;
+		if (count > bestCount) {
+			bestCount = count;
+			best = cand;
+		}
+	}
+	return best;
+}
+/**
+* Robust mean of a set of rotations (Option R1). Picks a reference (mode-finding,
+* or `options.reference`), rejects samples beyond the angular threshold, averages
+* the inliers, then does ONE refit pass against the provisional mean. Returns
+* `null` for an empty input.
+*/
+function averageRotation(quats, options = {}) {
+	if (quats.length === 0) return null;
+	const thresholdRad = (options.inlierAngleDeg ?? 12) * DEG2RAD;
+	const samples = quats.map(toGl);
+	const provisional = meanOfInliers(samples, options.reference ? toGl(options.reference) : bestReference(samples, thresholdRad), thresholdRad);
+	if (!provisional) return null;
+	const refined = meanOfInliers(samples, provisional.mean, thresholdRad) ?? provisional;
+	const m = refined.mean;
+	const s = m[3] < 0 ? -1 : 1;
+	return {
+		quat: [
+			s * m[0],
+			s * m[1],
+			s * m[2],
+			s * m[3]
+		],
+		inlierCount: refined.inlierCount,
+		maxAngleDeg: refined.maxAngleRad * RAD2DEG
+	};
+}
+/** Per-axis median of a numeric list (lower-middle for even n, matching
+* `medianQrPosition` in the slice so the two agree on the same data). */
+function medianOf(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	return sorted[Math.floor((sorted.length - 1) / 2)];
+}
+function medianPosition(positions) {
+	return [
+		medianOf(positions.map((p) => p[0])),
+		medianOf(positions.map((p) => p[1])),
+		medianOf(positions.map((p) => p[2]))
+	];
+}
+/** Max absolute per-axis deviation from `center` across all positions. */
+function translationSpread(positions, center) {
+	let max = 0;
+	for (const p of positions) max = Math.max(max, Math.abs(p[0] - center[0]), Math.abs(p[1] - center[1]), Math.abs(p[2] - center[2]));
+	return max;
+}
+/**
+* Aggregate a window of raw poses into one filtered pose + the spreads the
+* stability gate consumes. Returns `null` for an empty window.
+*/
+function aggregateQrPose(poses, options = {}) {
+	if (poses.length === 0) return null;
+	const positions = poses.map((p) => p.position);
+	const position = medianPosition(positions);
+	const rotation = averageRotation(poses.map((p) => p.rotation), options);
+	if (!rotation) return null;
+	return {
+		pose: {
+			position,
+			rotation: rotation.quat
+		},
+		translationSpreadM: translationSpread(positions, position),
+		rotationSpreadDeg: rotation.maxAngleDeg,
+		inlierCount: rotation.inlierCount
+	};
+}
+const UNKNOWN_STABILITY = {
+	status: "unknown",
+	pose: null,
+	translationSpreadM: 0,
+	rotationSpreadDeg: 0,
+	inlierCount: 0,
+	sampleCount: 0
+};
+/**
+* Evaluate the pose-stability lifecycle over the last `window` of `poses`
+* (oldest→newest). The returned `pose` is the filtered aggregate whenever there
+* is data, but it is only the gate's responsibility (`status === 'stable'`) to
+* decide when a consumer may TRUST it for the vote — `selectStableQrPose` reads
+* the pose only in the `stable` state.
+*/
+function evaluateQrPoseStability(poses, options = {}) {
+	const { window = 8, minObservations = 5, maxTranslationSpreadM = .03, maxRotationSpreadDeg = 5 } = options;
+	if (poses.length === 0) return { ...UNKNOWN_STABILITY };
+	const windowPoses = poses.length > window ? poses.slice(poses.length - window) : poses;
+	const agg = aggregateQrPose(windowPoses, options);
+	if (!agg) return { ...UNKNOWN_STABILITY };
+	return {
+		status: windowPoses.length >= minObservations && agg.translationSpreadM <= maxTranslationSpreadM && agg.rotationSpreadDeg <= maxRotationSpreadDeg ? "stable" : "measuring",
+		pose: agg.pose,
+		translationSpreadM: agg.translationSpreadM,
+		rotationSpreadDeg: agg.rotationSpreadDeg,
+		inlierCount: agg.inlierCount,
+		sampleCount: windowPoses.length
+	};
+}
+//#endregion
+export { evaluateQrPoseStability as i, aggregateQrPose as n, averageRotation as r, DEFAULT_ROTATION_INLIER_ANGLE_DEG as t };

package/dist/qr-size-depth-context-onu36E9s.d.ts

@@ -0,0 +1,13 @@
+import { i as DepthSample } from "./ar-types-BckI1E-O.js";
+import { n as QrSizeDepthContext } from "./qr-size-measurer-D7739ZpB.js";
+
+//#region ../src/ar/qr-size-depth-context.d.ts
+/**
+ * Build a {@link QrSizeDepthContext} from one depth sample, or `null` when it has
+ * no projection matrix / a singular one (the unprojector cannot be built). The
+ * grid lookup is **bilinear** (depth varies smoothly across a small QR face,
+ * rather than snapping to one nearest node). Best-effort — never throws.
+ */
+declare function createQrSizeDepthContext(sample: DepthSample): QrSizeDepthContext | null;
+//#endregion
+export { createQrSizeDepthContext as t };

package/dist/qr-size-measurer-D7739ZpB.d.ts

@@ -0,0 +1,165 @@
+import { r as DepthPoint } from "./ar-types-BckI1E-O.js";
+import { t as DepthUnprojector } from "./depth-unprojection-CK3b9htH.js";
+import { r as Point2 } from "./qr-pose-Bt2reSw7.js";
+import { Vector3 } from "gps-plus-slam-js";
+
+//#region ../src/ar/qr-size-from-depth.d.ts
+/** Where the size lifecycle currently sits for one marker (Note 3 / Note 4). */
+type QrSizeStatus = /** No size authored and none measured yet — size-dependent features blocked. */'unknown' /** Measurements are accumulating but the estimate has not converged. */ | 'measuring' /** A reliably-estimated (or authored) size — size-dependent features unlock. */ | 'estimated';
+/** Per-marker physical-size estimate (drives the Note 3 size lifecycle). */
+interface QrSizeEstimate {
+  status: QrSizeStatus;
+  /** Running median side length, meters, or `null` while unknown. */
+  estimateM: number | null;
+  /** How many accepted samples back the estimate. */
+  sampleCount: number;
+  /**
+   * Robust confidence half-width of the estimate, meters (`1.4826·MAD/√N`), so
+   * it TIGHTENS as samples accumulate (WS-B) — not the raw max−min. 0 when <2
+   * samples. The HUD renders this as the shrinking `±mm`.
+   */
+  spreadM: number;
+}
+/** One per-observation size read from a single detection's depth samples. */
+interface QrSizeObservation {
+  /** Median of the 4 unprojected edge lengths, meters. */
+  sizeM: number;
+  /** Consistency score in [0,1]; 1 = a perfect planar square facing the camera. */
+  quality: number;
+}
+/**
+ * Estimate a QR's physical side length from one detection's depth samples.
+ *
+ * @param corners - the 4 corner depth samples, ordered TL, TR, BR, BL (matching
+ *   `buildObjectPoints` / the detector corner-order normalization).
+ * @param interiorSamples - a few interior depth samples (may be empty); used
+ *   only to strengthen the planarity check against corner edge depth-bleed.
+ * @param unprojector - built once per depth sample via `createDepthUnprojector`.
+ * @returns `{ sizeM, quality }`, or `null` when a corner cannot be unprojected
+ *   or the quad is degenerate (collinear / zero-area).
+ */
+declare function estimateQrSizeFromDepth(corners: readonly [DepthPoint, DepthPoint, DepthPoint, DepthPoint], interiorSamples: readonly DepthPoint[], unprojector: DepthUnprojector): QrSizeObservation | null;
+interface QrSizeAccumulatorOptions {
+  /** Minimum observation quality to ACCEPT a sample. Default 0.8. */
+  qualityThreshold?: number;
+  /** Accepted samples required before the estimate can be `estimated`. Default 8. */
+  minSamples?: number;
+  /**
+   * Max confidence half-width (`spreadM`, m) allowed for the `estimated` status.
+   * Default 0.01. `spreadM` is a robust standard-error (`1.4826·MAD/√N`) that
+   * TIGHTENS as samples accumulate — not the raw max−min — so it converges
+   * instead of being pinned by one early stray.
+   */
+  maxSpreadM?: number;
+  /**
+   * Optional cap on retained accepted sizes. **Default: unbounded** (lifelong
+   * refinement — WS-B). The QR's physical size never changes, so keeping the
+   * full session history lets the robust median tighten the longer the QR is
+   * seen. Set a finite cap only if memory/perf demands a bounded window; the
+   * estimate then becomes a sliding-window median again.
+   */
+  maxSamples?: number;
+}
+interface QrSizeAccumulator {
+  /**
+   * Offer one observation (or `null` for a failed read). Low-quality / null
+   * observations are ignored. Returns the updated {@link QrSizeEstimate}.
+   */
+  add(observation: QrSizeObservation | null): QrSizeEstimate;
+  /** The current estimate without adding a sample. */
+  current(): QrSizeEstimate;
+  /** Drop all samples back to `unknown`. */
+  reset(): void;
+}
+declare function createQrSizeAccumulator(options?: QrSizeAccumulatorOptions): QrSizeAccumulator;
+//#endregion
+//#region ../src/ar/qr-size-measurer.d.ts
+/**
+ * Robustness knobs for the depth-at-corners stage (on top of the accumulator
+ * options). QR corners sit on a high-contrast print boundary where the coarse
+ * WebXR depth grid often has no near reading; these let a measurement still
+ * succeed instead of returning `null` every frame.
+ */
+interface QrSizeMeasurerOptions extends QrSizeAccumulatorOptions {
+  /**
+   * Points-per-side of the interior depth lattice sampled across the QR quad for
+   * the PRIMARY dense plane-fit estimate (WS-A). `latticeSize × latticeSize`
+   * points are sampled strictly inside the quad; reads with no depth are
+   * skipped. Default `7` (≤49 reads). Set to a small value (or rely on the
+   * corner fallback) to disable dense sampling. See {@link estimateQrSizeFromDepthDense}.
+   */
+  latticeSize?: number;
+  /**
+   * When a corner pixel has no depth, retry at points inset toward the centroid
+   * by these fractions (in order) and borrow the first valid depth — keeping the
+   * TRUE corner screen position so the measured size is not shrunk. Default
+   * `[0.12, 0.25]`. Set to `[]` to disable inset fallback. Used by the corner-
+   * based FALLBACK estimate (when the interior lattice is too sparse for a fit).
+   */
+  cornerInsetFractions?: number[];
+  /**
+   * Max corners whose depth may be reconstructed by a planar fit through the
+   * other three when still missing after the inset fallback. Default `1`
+   * (tolerate one un-sampleable corner); `0` disables reconstruction. Used by
+   * the corner-based FALLBACK estimate.
+   */
+  maxReconstructedCorners?: number;
+}
+/** The per-frame depth access the measurer needs (a subset of the demo's `DepthContext`). */
+interface QrSizeDepthContext {
+  /** Depth (m) at a normalized screen point, or `null` if unavailable there. */
+  depthAt: (screenX: number, screenY: number) => number | null;
+  /** Unprojector for the current depth sample (`createDepthUnprojector`). */
+  unprojector: DepthUnprojector;
+}
+/** Minimal frame dimensions needed to normalize pixel corners to screen coords. */
+interface ImageSize {
+  width: number;
+  height: number;
+}
+/** One measurement: the accumulated estimate plus the raw depth samples used. */
+interface QrSizeMeasurement {
+  /** The per-marker running estimate AFTER folding in this observation. */
+  estimate: QrSizeEstimate;
+  /**
+   * The 4 corner depth samples (detector order, normalized screen coords),
+   * best-effort. `null` when corner depth could not be sampled (e.g. a small QR
+   * whose corners fall between depth nodes) but the dense interior fit still
+   * produced an estimate — the dense path does not need corner depths.
+   */
+  cornerSamples: [DepthPoint, DepthPoint, DepthPoint, DepthPoint] | null;
+  /**
+   * The interior depth reads used for the estimate: the dense lattice on the
+   * primary path, or the single centroid sample on the corner-based fallback
+   * (may be empty).
+   */
+  interiorSamples: DepthPoint[];
+}
+interface QrSizeMeasurer {
+  /**
+   * Measure one detection's size from depth and fold it into the per-`text`
+   * accumulator. The PRIMARY path is the dense plane fit (WS-A): sample an
+   * interior lattice, fit the QR plane, recover the corners by ray-plane
+   * intersection. When the lattice is too sparse for a fit it FALLS BACK to the
+   * corner-based estimate (corner depths + inset/reconstruct robustness).
+   *
+   * Returns `null` only when neither path can run — `corners.length !== 4`, or
+   * the interior lattice yields too few reads AND the corner depths cannot be
+   * sampled (≥2 corners missing). A degenerate quad does not throw: the (null)
+   * observation is simply not accumulated and the prior estimate stands.
+   */
+  measure(text: string, corners: readonly Point2[], image: ImageSize, ctx: QrSizeDepthContext): QrSizeMeasurement | null;
+  /** Current estimate for a marker without adding a sample. */
+  current(text: string): QrSizeEstimate;
+  /** Drop one marker's samples (`text` given) or all of them. */
+  reset(text?: string): void;
+}
+/**
+ * Create a size measurer. Accumulator `options` (quality threshold, min samples,
+ * spread, cap) are forwarded to every per-marker {@link createQrSizeAccumulator};
+ * the depth-at-corners knobs ({@link QrSizeMeasurerOptions.cornerInsetFractions},
+ * {@link QrSizeMeasurerOptions.maxReconstructedCorners}) tune corner sampling.
+ */
+declare function createQrSizeMeasurer(options?: QrSizeMeasurerOptions): QrSizeMeasurer;
+//#endregion
+export { QrSizeMeasurerOptions as a, QrSizeAccumulatorOptions as c, QrSizeStatus as d, createQrSizeAccumulator as f, QrSizeMeasurer as i, QrSizeEstimate as l, QrSizeDepthContext as n, createQrSizeMeasurer as o, estimateQrSizeFromDepth as p, QrSizeMeasurement as r, QrSizeAccumulator as s, ImageSize as t, QrSizeObservation as u };