react-native-image-stitcher 0.2.1 → 0.4.0

package/src/camera/lowMemDevice.ts

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * lowMemDevice — shared helpers around the iOS BatchStitcher
+ * `physicalMemoryBytes` constant.
+ *
+ * Two consumers (Camera.tsx's `useState` initialiser + the modal's
+ * device-mem debug line) had near-identical implementations of the
+ * same "read physical memory from NativeModules, classify as
+ * low-mem" logic.  The F10 Phase 2 review (N2) flagged this as a
+ * drift hazard — exactly the kind of subtle duplication that audit
+ * fix F1 chased on the native side.
+ *
+ * Layered for testability:
+ *
+ *   - `isBelowMemThreshold(bytes)` is pure (in: number, out:
+ *     boolean) — unit-testable.
+ *   - `getPhysicalMemoryBytes()` reads the RN bridge module — must
+ *     run on a real device.
+ *   - `isLowMemDevice()` composes the two for the common case.
+ *
+ * The 2 GB threshold corresponds to iPhone X / 8 Plus / iPhone 6s
+ * era devices; below that, multiband blend + graphcut seam-finder
+ * peak memory risks the jetsam threshold mid-stitch.  Static value
+ * (no runtime config); revisit if the SDK ever targets a wider
+ * device range.
+ */
+import { NativeModules } from 'react-native';
+
+
+/** 2 GB in bytes — the cutoff below which `<Camera>` falls back
+ *  to the feather+skip blender/seam combo for safer peak memory. */
+export const LOW_MEM_THRESHOLD_BYTES = 2 * 1024 * 1024 * 1024;
+
+
+/**
+ * Pure classifier.  Returns `true` when `bytes` is a positive
+ * number strictly below the threshold.  Zero / NaN / undefined-shaped
+ * inputs return `false` — the safe choice when the native bridge
+ * hasn't surfaced the value (assume the device has enough memory
+ * for the higher-quality combo; the operator can still flip
+ * blender / seamFinder in the modal).
+ */
+export function isBelowMemThreshold(bytes: number): boolean {
+  return Number.isFinite(bytes)
+    && bytes > 0
+    && bytes < LOW_MEM_THRESHOLD_BYTES;
+}
+
+
+/**
+ * Read the device's physical memory from the native bridge.
+ * Returns 0 when the bridge isn't loaded or the constant is missing
+ * — caller should treat 0 as "unknown".
+ */
+export function getPhysicalMemoryBytes(): number {
+  const m = (NativeModules as Record<string, unknown>).BatchStitcher;
+  const bytes =
+    m && typeof m === 'object'
+      ? (m as { physicalMemoryBytes?: number }).physicalMemoryBytes
+      : undefined;
+  return typeof bytes === 'number' ? bytes : 0;
+}
+
+
+/**
+ * Composed `getPhysicalMemoryBytes()` + `isBelowMemThreshold()`.
+ * Convenience for the common consumer pattern.
+ */
+export function isLowMemDevice(): boolean {
+  return isBelowMemThreshold(getPhysicalMemoryBytes());
+}

package/src/index.ts

@@ -85,16 +85,74 @@ 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';
 export { PanoramaBandOverlay } from './camera/PanoramaBandOverlay';
 export { PanoramaGuidance } from './camera/PanoramaGuidance';
+// Settings modal — the modal is in `PanoramaSettingsModal.tsx`, but
+// the type tree + defaults + JS↔native bridge live in dedicated
+// files since v0.4 (F10).  The modal is now a thin presentational
+// component over the typed structure.
+export { PanoramaSettingsModal } from './camera/PanoramaSettingsModal';
+export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal';
+
+// Settings types — the v0.4 engine-discriminated structures.  Three
+// disjoint top-level types (one per stitching engine), each composed
+// of named sub-trees the corresponding native engine actually reads.
+// See `./camera/PanoramaSettings.ts` for the rationale and the
+// field-by-field native-consumer references.
 export {
-  PanoramaSettingsModal,
   DEFAULT_PANORAMA_SETTINGS,
-} from './camera/PanoramaSettingsModal';
-export type { PanoramaSettings } from './camera/PanoramaSettingsModal';
+  DEFAULT_FLOW_GATE_SETTINGS,
+  DEFAULT_SLITSCAN_SETTINGS,
+  DEFAULT_HYBRID_SETTINGS,
+} from './camera/PanoramaSettings';
+export type {
+  CaptureBaseSettings,
+  PanoramaSettings,
+  BatchStitcherSettings,
+  FrameSelectionSettings,
+  FlowGateSettings,
+  SlitscanSettings,
+  SlitscanPaintingSettings,
+  SlitscanRegistrationSettings,
+  SlitscanAdvancedSettings,
+  Ncc1dSettings,
+  Ncc2dSettings,
+  PlaneProjectionSettings,
+  HybridSettings,
+} from './camera/PanoramaSettings';
+
+// Settings → native config adapters.  Layer 2 hosts building their
+// own capture flow on top of `incremental.start()` should always
+// pass the result of the matching adapter as `config`; the bridge is
+// the single source of truth for the JS↔native wire format.
+export {
+  panoramaSettingsToNativeConfig,
+  slitscanSettingsToNativeConfig,
+  hybridSettingsToNativeConfig,
+} from './camera/PanoramaSettingsBridge';
+export type { NativeConfigDict } from './camera/PanoramaSettingsBridge';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
 
 // ── Capture hooks ─────────────────────────────────────────────────────

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