react-native-image-stitcher 0.2.0 → 0.3.0

package/src/camera/CaptureStitchStatsToast.tsx

@@ -0,0 +1,155 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureStitchStatsToast — auto-dismissing toast that shows the
+ * batch-stitcher's leaveBiggestComponent telemetry + the resolved
+ * cv::Stitcher mode after every successful finalize.
+ *
+ * Pattern: top-center capsule, dark translucent background, dismisses
+ * itself after `dismissAfterMs` (default 4500).  Replaces the
+ * Alert.alert blocking modal that used to interrupt the next
+ * capture.  See `useStitchStatsToast` hook for the matching
+ * imperative API.
+ *
+ * Layer-2 hosts can mount this directly + pass their own message;
+ * Layer-1 `<Camera>` mounts it under `settings.debug` and feeds
+ * the formatted message from the finalize result automatically.
+ */
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+import type { IncrementalFinalizeResult } from '../stitching/incremental';
+
+export interface CaptureStitchStatsToastProps {
+  /** Toast message to show.  Pass null to hide. */
+  message: string | null;
+  /** Top inset for safe-area placement.  Toast pinned `topInset + 12`. */
+  topInset?: number;
+}
+
+export function CaptureStitchStatsToast({
+  message,
+  topInset = 0,
+}: CaptureStitchStatsToastProps): React.JSX.Element | null {
+  if (message === null) return null;
+  return (
+    <View
+      pointerEvents="none"
+      style={[
+        styles.wrap,
+        { top: topInset + 12 },
+      ]}
+    >
+      <View
+        style={styles.capsule}
+        accessibilityRole="alert"
+        accessibilityLiveRegion="polite"
+      >
+        <Text style={styles.text} numberOfLines={3}>
+          {message}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: {
+    position: 'absolute',
+    left: 24,
+    right: 24,
+    alignItems: 'center',
+    zIndex: 110,
+  },
+  capsule: {
+    paddingHorizontal: 16,
+    paddingVertical: 10,
+    borderRadius: 16,
+    backgroundColor: 'rgba(15, 23, 42, 0.92)',
+    maxWidth: '100%',
+  },
+  text: {
+    color: '#ffffff',
+    fontSize: 13,
+    fontWeight: '600',
+    textAlign: 'center',
+  },
+});
+
+
+/**
+ * Imperative API for showing transient stitch-stats toasts.
+ *
+ * Returns `{ message, showFor, showResult }`:
+ *   - `message`     — current toast text (pass to CaptureStitchStatsToast)
+ *   - `showFor`     — show an arbitrary string, auto-dismiss
+ *   - `showResult`  — format an `IncrementalFinalizeResult` into the
+ *                     standard "Stitch: N/M frames • thresh X.XX •
+ *                     N attempt(s) • mode" line and show it.  Convenience
+ *                     for hosts that just want the canonical format.
+ *
+ * Auto-clears its setTimeout on unmount so callers don't have to
+ * worry about setState-on-unmounted warnings.
+ */
+export interface UseStitchStatsToastReturn {
+  message: string | null;
+  showFor: (msg: string, ms?: number) => void;
+  showResult: (result: IncrementalFinalizeResult, ms?: number) => void;
+}
+
+const DEFAULT_DISMISS_MS = 4500;
+
+export function useStitchStatsToast(): UseStitchStatsToastReturn {
+  const [message, setMessage] = useState<string | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const showFor = useCallback((msg: string, ms = DEFAULT_DISMISS_MS) => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+    setMessage(msg);
+    timerRef.current = setTimeout(() => {
+      setMessage(null);
+      timerRef.current = null;
+    }, ms);
+  }, []);
+
+  const showResult = useCallback(
+    (result: IncrementalFinalizeResult, ms = DEFAULT_DISMISS_MS) => {
+      // Format mirrors the RetaiLens debug toast that operators
+      // already recognise.  Includes the new (audit F2g) resolved
+      // stitchMode as a fourth segment when present.
+      const requested = result.framesRequested;
+      const included = result.framesIncluded;
+      const thresh = result.finalConfidenceThresh;
+      const mode = result.stitchModeResolved;
+      // The retry-attempt count is derived deterministically from
+      // the threshold used on the successful attempt (1.0→1, 0.5→2,
+      // 0.3→3) per cpp/stitcher.cpp's retry loop.
+      const attempts =
+        typeof thresh === 'number'
+          ? thresh >= 0.99 ? 1
+          : thresh >= 0.49 ? 2
+          : thresh >= 0.29 ? 3
+          : null
+        : null;
+      const reqStr = typeof requested === 'number' ? requested : '?';
+      const incStr = typeof included === 'number' ? included : '?';
+      const threshStr =
+        typeof thresh === 'number' && thresh >= 0
+          ? thresh.toFixed(2)
+          : 'n/a';
+      const attStr = attempts !== null ? `${attempts} attempt${attempts > 1 ? 's' : ''}` : '? attempts';
+      const modeStr = mode ? ` • ${mode}` : '';
+      showFor(
+        `Stitch: ${incStr}/${reqStr} frames • thresh ${threshStr} • ${attStr}${modeStr}`,
+        ms,
+      );
+    },
+    [showFor],
+  );
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  return { message, showFor, showResult };
+}

package/src/camera/PanoramaSettingsModal.tsx

@@ -323,11 +323,12 @@ export interface PanoramaSettings {
    *     PlaneWarper.  Canvas size bounded by sum of frame areas.
    *     Slight quality drop on pure rotations but works for them too.
    *
-   * iOS NOTE: as of 2026-05-14 the iOS stitcher uses a hand-rolled
-   * PANORAMA-style pipeline (OpenCVStitcher.mm:600+) regardless of
-   * this setting.  Setting is passed through to iOS but ignored.
-   * Android honours it via image_stitcher_jni.cpp.  Bridging iOS is
-   * a follow-up.
+   * Both platforms honour this as of 2026-05-22 (audit F2).  Android
+   * routes through `image_stitcher_jni.cpp` → `cpp/stitcher.cpp`;
+   * iOS routes through `OpenCVStitcher.stitchFramePaths(stitchMode:)`
+   * → `cpp/stitcher.cpp`.  Both 'auto' resolutions use the same
+   * translation/rotation ratio heuristic
+   * (`resolveStitchModeAuto` on each side).
    */
   stitchMode: 'auto' | 'panorama' | 'scans';
 }

package/src/index.ts

@@ -85,6 +85,25 @@ export { CapturePreview } from './camera/CapturePreview';
 export type { CapturePreviewAction } from './camera/CapturePreview';
 export { CaptureStatusOverlay } from './camera/CaptureStatusOverlay';
 export type { CaptureStatusPhase } from './camera/CaptureStatusOverlay';
+export { CaptureDebugOverlay } from './camera/CaptureDebugOverlay';
+export type { CaptureDebugOverlayProps } from './camera/CaptureDebugOverlay';
+// 2026-05-22 (audit F9) — composable debug pills.  Layer-1 <Camera>
+// mounts all of them automatically when settings.debug is on;
+// Layer-2 hosts compose their own debug surface from these primitives.
+export { CaptureMemoryPill } from './camera/CaptureMemoryPill';
+export type { CaptureMemoryPillProps } from './camera/CaptureMemoryPill';
+export { CaptureKeyframePill } from './camera/CaptureKeyframePill';
+export type { CaptureKeyframePillProps } from './camera/CaptureKeyframePill';
+export { CaptureOrientationPill } from './camera/CaptureOrientationPill';
+export type { CaptureOrientationPillProps } from './camera/CaptureOrientationPill';
+export {
+  CaptureStitchStatsToast,
+  useStitchStatsToast,
+} from './camera/CaptureStitchStatsToast';
+export type {
+  CaptureStitchStatsToastProps,
+  UseStitchStatsToastReturn,
+} from './camera/CaptureStitchStatsToast';
 export { CaptureThumbnailStrip } from './camera/CaptureThumbnailStrip';
 export type { CaptureThumbnailItem } from './camera/CaptureThumbnailStrip';
 export { IncrementalPanGuide } from './camera/IncrementalPanGuide';

package/src/sensors/useIMUTranslationGate.ts

@@ -116,6 +116,32 @@ export interface UseIMUTranslationGateReturn {
    * benefits from continuous history across anchors.
    */
   resetAnchor: () => void;
+  /**
+   * 2026-05-22 (audit follow-up) — read the latest integrated
+   * translation magnitude in METRES.  Useful for debug overlays
+   * that want to surface "how much translation has the operator
+   * accumulated since the last keyframe accept" so they can sanity-
+   * check whether the budget is going to fire.  Cheap: returns the
+   * ref value, no React state subscription (the integrator runs at
+   * 50 Hz and we don't want to force a re-render every sample).
+   * Callers that want a live UI value should poll on an interval
+   * or use a frame-driven re-render trigger.
+   */
+  getTranslationMetres: () => number;
+  /**
+   * 2026-05-22 (audit F2f) — cumulative |segment displacement|
+   * across the entire capture, in METRES.  Includes:
+   *   (a) magnitudes banked at every prior anchor reset (whether
+   *       triggered by IMU budget auto-rearm or by host-side
+   *       resetAnchor on a non-IMU frame accept), PLUS
+   *   (b) the magnitude of the current (unfinished) segment.
+   *
+   * This is the right input for the stitchMode auto-resolver in
+   * non-AR mode — it captures total operator travel regardless of
+   * which gate accepted intermediate frames.  Resets to 0 only on
+   * subscription start (new capture).
+   */
+  getTotalAbsMetres: () => number;
 }
 
 
@@ -144,12 +170,27 @@ export function useIMUTranslationGate({
   // All running-integrator state lives in a single ref so the
   // subscription callback can update it without forcing a re-render
   // every frame (50 Hz worth of re-renders would tank performance).
+  //
+  // 2026-05-22 (audit F2f) — `totalAbsMetres` is a separate, never-
+  // reset-within-capture accumulator of the |segment displacement|
+  // that's banked each time the current segment ends (either by
+  // auto-rearm on budget fire, or by host-side `resetAnchor` on a
+  // non-IMU frame accept).  This decouples the display-side
+  // segment integrator (`posX`, resets on every accept) from the
+  // measurement-side cumulative translation (`totalAbsMetres`,
+  // resets only on subscription start).  Pre-F2f the cumulative
+  // translation was reconstructed as `fires × budget + |residual|`
+  // — that undercounted whenever a non-IMU accept reset the
+  // integrator before the budget threshold was reached.
   const stateRef = useRef({
     posX: 0,
     velX: 0,
     /// NaN sentinel for "uninitialised"; first sample seeds it.
     gravityX: NaN,
     fired: false,
+    /// Cumulative |segment displacement| banked across all anchor
+    /// resets in this capture.  Reset only on subscription start.
+    totalAbsMetres: 0,
   });
 
   // Latest onBudgetExceeded callback in a ref so callers can pass
@@ -160,6 +201,13 @@ export function useIMUTranslationGate({
 
   const resetAnchor = useCallback(() => {
     const s = stateRef.current;
+    // 2026-05-22 (audit F2f) — bank current segment magnitude into
+    // the cumulative accumulator BEFORE zeroing.  This preserves
+    // total translation across non-IMU-driven anchor resets (e.g.
+    // when a flow-novelty accept arrives at 5 cm — short of the
+    // IMU budget — we want the 5 cm to count toward the
+    // auto-resolver's total, not be lost).
+    s.totalAbsMetres += Math.abs(s.posX);
     s.posX = 0;
     s.velX = 0;
     s.fired = false;
@@ -169,6 +217,41 @@ export function useIMUTranslationGate({
   useEffect(() => {
     if (!enabled) return;
 
+    // 2026-05-22 (audit follow-up) — reset ALL integrator state when
+    // the subscription is (re)established, not just on the host's
+    // resetAnchor() call.  Two reasons:
+    //
+    // 1. Race with statusPhase update: handleHoldStart sets
+    //    `statusPhase='recording'` synchronously, which flips
+    //    `enabled` and re-runs this effect immediately.  Samples
+    //    start arriving before the awaited `incremental.start()`
+    //    returns + the host gets a chance to call `resetAnchor()`.
+    //    During that window `posX` accumulates drift, and the
+    //    operator sees a non-zero starting `imuΔ` in the debug
+    //    overlay.
+    //
+    // 2. Stale gravity bias: `gravityX` was intentionally preserved
+    //    across `resetAnchor` calls to keep IIR history.  But
+    //    between captures the phone might be at a different
+    //    orientation; the stale gravity estimate biases `linX` for
+    //    the ~200ms IIR convergence window, and that bias compounds
+    //    into `posX` each capture.  Forcing NaN here makes the
+    //    first sample re-seed gravity cleanly — costs us one
+    //    sample of accuracy but eliminates the cross-capture drift.
+    //
+    // The host's `resetAnchor()` remains as the in-capture reset
+    // (called after each force-accept fire, etc).
+    {
+      const s = stateRef.current;
+      s.posX = 0;
+      s.velX = 0;
+      s.fired = false;
+      s.gravityX = NaN;
+      // 2026-05-22 (audit F2f) — new subscription = new capture =
+      // zero the cumulative accumulator too.
+      s.totalAbsMetres = 0;
+    }
+
     setUpdateIntervalForType(SensorTypes.accelerometer, sampleIntervalMs);
     const scale = Platform.OS === 'ios' ? G_TO_MPS2 : 1;
     const dt = sampleIntervalMs / 1000.0;
@@ -196,13 +279,41 @@ export function useIMUTranslationGate({
       s.posX += s.velX * dt;
 
       if (!s.fired && Math.abs(s.posX) > budgetMeters) {
+        // Fire the callback (host-side force-accept hook).
         s.fired = true;
         onExceededRef.current();
+        // 2026-05-22 (audit follow-up) — auto-rearm the integrator
+        // so the gate fires EVERY `budgetMeters` of translation, not
+        // just once per capture.  Pre-audit behaviour was "fire once,
+        // wait for host to call resetAnchor()" — but Camera.tsx only
+        // calls resetAnchor at the start of a capture, so the gate
+        // latched after the first force-accept and never re-fired,
+        // even though the operator kept translating further (user
+        // observation: 8cm fires once, then 16cm/24cm/… don't
+        // re-trigger).
+        //
+        // 2026-05-22 (audit F2f) — bank the segment magnitude into
+        // the cumulative accumulator BEFORE zeroing (matches the
+        // resetAnchor path for symmetry — both paths represent
+        // anchor transitions, just driven by different triggers).
+        s.totalAbsMetres += Math.abs(s.posX);
+        s.posX = 0;
+        s.velX = 0;
+        s.fired = false;
       }
     });
 
     return () => sub.unsubscribe();
   }, [enabled, budgetMeters, sampleIntervalMs]);
 
-  return { resetAnchor };
+  const getTranslationMetres = useCallback(() => {
+    return stateRef.current.posX;
+  }, []);
+
+  const getTotalAbsMetres = useCallback(() => {
+    const s = stateRef.current;
+    return s.totalAbsMetres + Math.abs(s.posX);
+  }, []);
+
+  return { resetAnchor, getTranslationMetres, getTotalAbsMetres };
 }

package/src/stitching/incremental.ts

@@ -678,6 +678,21 @@ export interface IncrementalFinalizeResult {
   framesIncluded?: number;
   framesDropped?: number;
   finalConfidenceThresh?: number;
+  /**
+   * 2026-05-22 (audit F2g) — which cv::Stitcher pipeline the batch
+   * finalize actually ran, after the engine's `auto` resolution
+   * heuristic (or the operator's explicit choice).  Values: `'panorama'`
+   * (rotation-only, ORB + BundleAdjusterRay + SphericalWarper) or
+   * `'scans'` (translational, affine + BundleAdjusterAffine +
+   * PlaneWarper).  Undefined on non-batch engines (hybrid/slit-scan)
+   * which don't go through cv::Stitcher at finalize.
+   *
+   * Host code can surface this on the output preview (e.g. a small
+   * pill labelled "scans" / "panorama") and in the debug toast to
+   * help operators understand what choice the auto-resolver made
+   * on the just-completed capture.
+   */
+  stitchModeResolved?: 'panorama' | 'scans';
 }
 
 
@@ -838,6 +853,16 @@ interface NativeIncrementalModule {
      * legacy start-time behaviour.
      */
     captureOrientation?: string;
+    /**
+     * 2026-05-22 (audit F2b) — JS-measured cumulative IMU translation
+     * magnitude in METRES.  Used by the auto-resolver in non-AR mode
+     * where the engine has no pose-driven translation source.  In AR
+     * mode native uses pose-derived translation and ignores this
+     * signal.  Defaults to 0 (back-compat) — auto-resolver always
+     * picks `panorama` when both pose-derived and IMU translation
+     * are zero, matching legacy behaviour.
+     */
+    imuTranslationMetres?: number;
   }): Promise<IncrementalFinalizeResult>;
   cancel(): Promise<{ ok: true }>;
   getState(): Promise<IncrementalState | null>;

package/src/stitching/useIncrementalStitcher.ts

@@ -74,6 +74,17 @@ export interface UseIncrementalStitcherReturn {
     outputPath?: string,
     quality?: number,
     captureOrientation?: string,
+    /**
+     * 2026-05-22 (audit F2b) — measured cumulative translation
+     * magnitude in METRES from the JS-side IMU translation gate.
+     * Used by the auto-resolver in non-AR mode where the engine has
+     * no pose-driven translation source — without this signal the
+     * auto-resolver always picks `panorama` even for shelf scans.
+     * Omit (or pass 0) when no IMU translation data is available
+     * (e.g. in AR mode the native side has its own pose-driven
+     * translation magnitude and prefers that).
+     */
+    imuTranslationMetres?: number,
   ) => Promise<IncrementalFinalizeResult>;
   /** Abort the capture without producing output. */
   cancel: () => Promise<void>;
@@ -186,6 +197,7 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
       outputPath?: string,
       quality = 90,
       captureOrientation?: string,
+      imuTranslationMetres?: number,
     ): Promise<IncrementalFinalizeResult> => {
       if (!native) {
         throw new Error('useIncrementalStitcher: native module unavailable');
@@ -198,6 +210,12 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
         // instead of the start-time snapshot.  Undefined = keep
         // legacy start-time behaviour.
         captureOrientation,
+        // 2026-05-22 (audit F2b) — fold JS-side IMU translation into
+        // the native auto-resolver.  In non-AR mode this is the only
+        // translation signal the resolver has (the JS-driver path
+        // doesn't carry tx/ty/tz, so pose-derived translation is 0).
+        // Native side treats it as a magnitude (always ≥ 0).
+        imuTranslationMetres: Math.max(0, imuTranslationMetres ?? 0),
       });
       setIsRunning(false);
       // Clear React state on finalize so the next start doesn't