react-native-image-stitcher 0.16.0 → 0.16.2

package/src/camera/RectCropPreview.tsx

@@ -44,7 +44,6 @@ import React, {
   useState,
 } from 'react';
 import {
-  ActivityIndicator,
   Image,
   Modal,
   PanResponder,
@@ -110,29 +109,6 @@ export interface RectCropPreviewProps {
   imageWidth: number;
   /** Intrinsic pixel height of `imageUri`. */
   imageHeight: number;
-  /**
-   * DEBUG A/B harness — file:// URI of the SAME capture stitched by the
-   * OPPOSITE pipeline (manual cv::detail + plane).  When set, a toggle appears
-   * that flips the displayed panorama between the primary (high-level +
-   * spherical) and this one, for on-device comparison on a single capture.
-   * Its dimensions are read at runtime via `Image.getSize`.  When the manual
-   * output is showing, the crop quad is hidden and the accept button emits
-   * THIS uri (so you can pick the better pipeline per capture).
-   */
-  altImageUri?: string;
-  /**
-   * 2026-06-15 — ON-DEMAND alt (high-level) stitch.  The PRIMARY image is the
-   * MANUAL pipeline (the default output); this callback re-stitches the SAME
-   * captured keyframes via cv::Stitcher and resolves with a file:// uri (or
-   * null on failure).  It runs only the FIRST time the user taps the
-   * "High-level" tab — nothing is computed unless asked for.  When provided (or
-   * `altImageUri` is), the A/B toggle appears.
-   *
-   * Resolves with the high-level output's file:// `uri` AND its OWN
-   * DEV-overlay `debugInfo` recipe (so the params pill can switch to the
-   * high-level recipe while that tab is viewed), or `null` on failure.
-   */
-  onRequestAlt?: () => Promise<{ uri: string; debugInfo: string } | null>;
   /** Show / hide the editor. */
   visible: boolean;
   /**
@@ -176,9 +152,9 @@ export interface RectCropPreviewProps {
   copy?: Partial<GuidanceCopy>;
   /**
    * Safe-area insets (px).  The editor is a full-screen Modal, so the host
-   * passes `insets.top`/`insets.bottom` to keep the top toolbar (A/B toggle,
-   * warnings) clear of the notch/Dynamic Island and the bottom button bar
-   * clear of the home indicator.  Default 0.
+   * passes `insets.top`/`insets.bottom` to keep the top toolbar (warnings)
+   * clear of the notch/Dynamic Island and the bottom button bar clear of the
+   * home indicator.  Default 0.
    */
   topInset?: number;
   bottomInset?: number;
@@ -244,7 +220,6 @@ export function RectCropPreview(
     imageUri,
     imageWidth,
     imageHeight,
-    altImageUri,
     visible,
     onConfirm,
     onUseOriginal,
@@ -256,63 +231,11 @@ export function RectCropPreview(
     topInset = 0,
     bottomInset = 0,
     debugInfo,
-    onRequestAlt,
     showMemoryPill,
   } = props;
 
   const resolvedCopy = useMemo(() => mergeGuidanceCopy(copy), [copy]);
 
-  // ── A/B comparison — the PRIMARY (imageUri) is the MANUAL pipeline (the
-  // default output).  The alt is HIGH-LEVEL cv::Stitcher, produced either
-  // EAGERLY (`altImageUri`, legacy) or ON DEMAND (`onRequestAlt`, re-stitched
-  // the first time the user opens the high-level tab).  `altSize` is fetched
-  // once the alt uri exists; when the alt is showing we use its dims for the
-  // contain-fit and hide the crop quad.
-  const [showingAlt, setShowingAlt] = useState(false);
-  const [lazyAltUri, setLazyAltUri] = useState<string | null>(null);
-  // The high-level (alt) stitch's OWN DEV-overlay recipe, resolved alongside
-  // its uri from `onRequestAlt`.  Shown in the params pill in place of the
-  // manual primary's `debugInfo` while the high-level tab is being viewed.
-  const [lazyAltDebugInfo, setLazyAltDebugInfo] = useState<string | null>(null);
-  const [altLoading, setAltLoading] = useState(false);
-  const [altFailed, setAltFailed] = useState(false);
-  const altUri = altImageUri ?? lazyAltUri ?? null;
-  const altOffered = !!altImageUri || !!onRequestAlt;
-  const [altSize, setAltSize] = useState<{ w: number; h: number } | null>(null);
-  React.useEffect(() => {
-    if (!altUri) {
-      setAltSize(null);
-      return;
-    }
-    Image.getSize(
-      altUri,
-      (w, h) => setAltSize({ w, h }),
-      () => setAltSize(null),
-    );
-  }, [altUri]);
-  // Switch to the high-level (alt) view; compute it lazily on first request.
-  const showHighLevel = React.useCallback(() => {
-    setShowingAlt(true);
-    if (altUri || altLoading || !onRequestAlt) return;
-    setAltFailed(false);
-    setAltLoading(true);
-    onRequestAlt()
-      .then((result) => {
-        if (result) {
-          setLazyAltUri(result.uri);
-          setLazyAltDebugInfo(result.debugInfo);
-        } else {
-          setAltFailed(true);
-        }
-      })
-      .catch(() => setAltFailed(true))
-      .finally(() => setAltLoading(false));
-  }, [altUri, altLoading, onRequestAlt]);
-  const showAlt = showingAlt && !!altUri && !!altSize;
-  const activeUri = showAlt ? (altUri as string) : imageUri;
-  const activeW = showAlt ? (altSize as { w: number }).w : imageWidth;
-  const activeH = showAlt ? (altSize as { h: number }).h : imageHeight;
-
   // The 4 corners live in IMAGE-PIXEL space (the source of truth) so they
   // survive layout-box changes (rotation, keyboard) without drift.  We map
   // to screen for rendering and back on every drag via cropGeometry.
@@ -429,19 +352,18 @@ export function RectCropPreview(
   let screenCorners: Point[] | null = null;
 
   if (box) {
-    const fit = containFit(box, activeW, activeH);
+    const fit = containFit(box, imageWidth, imageHeight);
     if (fit) {
       imageBox = {
         left: fit.offX,
         top: fit.offY,
-        width: activeW * fit.scale,
-        height: activeH * fit.scale,
+        width: imageWidth * fit.scale,
+        height: imageHeight * fit.scale,
       };
-      // Quad corners only apply to the primary (croppable) image — hidden
-      // while the alt (manual) output is shown for comparison.
-      screenCorners = showAlt
-        ? null
-        : imageQuad.map((p) => imageToScreen(p, box, imageWidth, imageHeight));
+      // Quad corners only apply in crop mode.
+      screenCorners = showCropControls
+        ? imageQuad.map((p) => imageToScreen(p, box, imageWidth, imageHeight))
+        : null;
     }
   }
 
@@ -476,41 +398,28 @@ export function RectCropPreview(
     >
       <View style={[styles.root, { paddingTop: topInset }]}>
         {/* Live memory-footprint pill (host gates on settings.debug).  Top-LEFT
-            so it clears the top-right stitch-params pill; watch it spike when
-            the high-level re-stitch fires. */}
+            so it clears the top-right stitch-params pill. */}
         {showMemoryPill ? (
           <CaptureMemoryPill
             style={{
               position: 'absolute',
-              top: topInset + (altOffered ? 76 : 8),
+              top: topInset + 8,
               left: 12,
               zIndex: 21,
             }}
           />
         ) : null}
 
-        {/* DEV stitch-params overlay (host gates on __DEV__).  Top-right pill;
-            pushed below the A/B bar when that's present so they don't overlap.
-            A/B-AWARE: while the user is viewing the on-demand high-level tab and
-            its recipe is known, show the HIGH-LEVEL recipe (pipe=highlevel;…)
-            instead of the manual primary's `debugInfo` — otherwise the pill
-            would misleadingly claim the manual recipe for a high-level output. */}
-        {(() => {
-          const pillText =
-            showAlt && lazyAltDebugInfo ? lazyAltDebugInfo : debugInfo;
-          return pillText ? (
-            <View
-              style={[
-                styles.debugPill,
-                { top: topInset + (altImageUri && altSize ? 76 : 8) },
-              ]}
-              pointerEvents="none"
-              accessibilityRole="text"
-            >
-              <Text style={styles.debugPillText}>{pillText}</Text>
-            </View>
-          ) : null;
-        })()}
+        {/* DEV stitch-params overlay (host gates on __DEV__).  Top-right pill. */}
+        {debugInfo ? (
+          <View
+            style={[styles.debugPill, { top: topInset + 8 }]}
+            pointerEvents="none"
+            accessibilityRole="text"
+          >
+            <Text style={styles.debugPillText}>{debugInfo}</Text>
+          </View>
+        ) : null}
 
         {/* Non-fatal warning banner (e.g. "<70 % of frames used"), shown
             ABOVE the image so the user sees it before accepting a crop. */}
@@ -524,61 +433,18 @@ export function RectCropPreview(
           </View>
         )}
 
-        {/* A/B comparison.  Primary = MANUAL (the default output); the
-            HIGH-LEVEL segment re-stitches the same keyframes ON DEMAND the
-            first time it's tapped (spinner while it runs, then it caches). */}
-        {altOffered && (
-          <View style={styles.abBar}>
-            <Text style={styles.abBarLabel}>
-              {altLoading
-                ? 'Stitching high-level… (manual shown meanwhile)'
-                : altFailed
-                  ? 'High-level stitch failed — showing manual'
-                  : 'Viewing the highlighted pipeline — tap to switch:'}
-            </Text>
-            <View style={styles.abSegments}>
-              <Pressable
-                style={[styles.abSeg, !showAlt && styles.abSegActive]}
-                onPress={() => setShowingAlt(false)}
-                accessibilityRole="button"
-                accessibilityState={{ selected: !showAlt }}
-                accessibilityLabel="View manual pipeline (default)"
-              >
-                <Text style={[styles.abSegText, !showAlt && styles.abSegTextActive]}>
-                  Manual
-                </Text>
-              </Pressable>
-              <Pressable
-                style={[styles.abSeg, showAlt && styles.abSegActive]}
-                onPress={showHighLevel}
-                accessibilityRole="button"
-                accessibilityState={{ selected: showAlt, busy: altLoading }}
-                accessibilityLabel="View high-level pipeline (computed on demand)"
-              >
-                {altLoading ? (
-                  <ActivityIndicator size="small" color="#fff" />
-                ) : (
-                  <Text style={[styles.abSegText, showAlt && styles.abSegTextActive]}>
-                    High-level
-                  </Text>
-                )}
-              </Pressable>
-            </View>
-          </View>
-        )}
-
         <View style={styles.canvas} onLayout={onLayout}>
           {imageBox && (
             <Image
-              source={{ uri: activeUri }}
+              source={{ uri: imageUri }}
               style={[styles.image, imageBox]}
               resizeMode="stretch"
             />
           )}
 
-          {/* Crop affordances — quad edges + draggable handles — only in
-              crop mode on the PRIMARY image (hidden while comparing the alt). */}
-          {showCropControls && !showAlt && (
+          {/* Crop affordances — quad edges + draggable handles — only in crop
+              mode (hidden in preview-only mode). */}
+          {showCropControls && (
             <>
               {/* Quad edges (non-interactive). */}
               {edges.map((e, i) => (
@@ -626,9 +492,9 @@ export function RectCropPreview(
               <Text style={styles.btnText}>{resolvedCopy.cropRetake}</Text>
             </Pressable>
             {/* Crop mode only — "Use original" emits the stitch un-cropped.
-                Hidden in preview-only mode and while comparing the alt (the
-                primary button below is the accept action there). */}
-            {showCropControls && !showAlt && (
+                Hidden in preview-only mode (Confirm below is the accept action
+                there). */}
+            {showCropControls && (
               <Pressable
                 style={({ pressed }) => [styles.btn, pressed && styles.btnPressed]}
                 onPress={() => onUseOriginal()}
@@ -638,37 +504,26 @@ export function RectCropPreview(
                 <Text style={styles.btnText}>{resolvedCopy.cropUseOriginal}</Text>
               </Pressable>
             )}
-            {/* Primary action — "Use this" emits the SHOWN (alt) pipeline's
-                output; otherwise "Crop" applies the quad (crop mode) or
-                "Confirm" accepts the primary as-is (preview-only mode). */}
+            {/* Primary action — "Crop" applies the quad (crop mode) or "Confirm"
+                accepts the image as-is (preview-only mode). */}
             <Pressable
               style={({ pressed }) => [
                 styles.btn,
                 styles.primary,
                 pressed && styles.btnPressed,
               ]}
-              onPress={
-                showAlt
-                  ? () => onUseOriginal(activeUri)
-                  : showCropControls
-                    ? handleConfirm
-                    : () => onUseOriginal()
-              }
+              onPress={showCropControls ? handleConfirm : () => onUseOriginal()}
               accessibilityRole="button"
               accessibilityLabel={
-                showAlt
-                  ? 'Use this output'
-                  : showCropControls
-                    ? resolvedCopy.cropConfirm
-                    : resolvedCopy.previewConfirm
+                showCropControls
+                  ? resolvedCopy.cropConfirm
+                  : resolvedCopy.previewConfirm
               }
             >
               <Text style={styles.btnText}>
-                {showAlt
-                  ? 'Use this'
-                  : showCropControls
-                    ? resolvedCopy.cropConfirm
-                    : resolvedCopy.previewConfirm}
+                {showCropControls
+                  ? resolvedCopy.cropConfirm
+                  : resolvedCopy.previewConfirm}
               </Text>
             </Pressable>
           </View>
@@ -745,43 +600,6 @@ const styles = StyleSheet.create({
     fontSize: 13,
     fontWeight: '600',
   },
-  abBar: {
-    backgroundColor: '#1a1a1a',
-    paddingVertical: 10,
-    paddingHorizontal: 12,
-    borderBottomWidth: StyleSheet.hairlineWidth,
-    borderBottomColor: '#333',
-  },
-  abBarLabel: {
-    color: '#aaa',
-    fontSize: 11,
-    fontWeight: '600',
-    textAlign: 'center',
-    marginBottom: 8,
-  },
-  abSegments: {
-    flexDirection: 'row',
-    alignSelf: 'center',
-    backgroundColor: '#000',
-    borderRadius: 9,
-    padding: 3,
-  },
-  abSeg: {
-    paddingVertical: 7,
-    paddingHorizontal: 22,
-    borderRadius: 7,
-  },
-  abSegActive: {
-    backgroundColor: '#0A84FF',
-  },
-  abSegText: {
-    color: '#9aa',
-    fontSize: 14,
-    fontWeight: '700',
-  },
-  abSegTextActive: {
-    color: '#fff',
-  },
   canvas: { flex: 1 },
   image: { position: 'absolute' },
   edge: {

package/src/stitching/incremental.ts

@@ -682,6 +682,23 @@ export interface IncrementalFinalizeResult {
    * on the just-completed capture.
    */
   stitchModeResolved?: 'panorama' | 'scans';
+  /**
+   * 2026-06-15 (DEV) — gyro rotation magnitude of the capture, in RADIANS
+   * (angle between the first and last accepted keyframe camera-forward vectors).
+   * Surfaced so a dev tool can display it and tune the panorama-vs-SCANS
+   * rotation threshold from real captures. `0` when there is no pose-derived
+   * rotation signal (non-AR with no poses) — not necessarily "no rotation".
+   */
+  rRadians?: number;
+  /**
+   * 2026-06-16 (DEV) — translation magnitude (metres) and the auto decision
+   * ratio (`tScore/(tScore+rScore)`, `>=0.55` → SCANS) that drove the
+   * panorama-vs-SCANS choice. Surfaced alongside `rRadians` so a dev tool can
+   * display the full decision inputs and tune the threshold from real captures.
+   * `0` when there is no motion signal (non-AR with no poses / no movement).
+   */
+  tMeters?: number;
+  decisionRatio?: number;
   /**
    * 2026-06-14 (DEV overlay) — a semicolon-separated `key=value` trace of the
    * stitcher's RUNTIME choices for this output, e.g.
@@ -897,6 +914,14 @@ interface NativeIncrementalModule {
      * are zero, matching legacy behaviour.
      */
     imuTranslationMetres?: number;
+    /**
+     * 2026-06-16 — the explicit lens the user selected (`'1x'` | `'0.5x'`).
+     * The reliable zoom signal for the high-level warper tree: `'0.5x'`
+     * (ultra-wide) → spherical warper.  Replaces deriving zoom from the
+     * intrinsics FOV (unreliable on multi-cam 0.5x / non-AR fx=0).  Omitted →
+     * treated as `'1x'`.
+     */
+    lens?: string;
   }): Promise<IncrementalFinalizeResult>;
   cancel(): Promise<{ ok: true }>;
   getState(): Promise<IncrementalState | null>;
@@ -922,6 +947,10 @@ interface NativeIncrementalModule {
    *  one-true-number for "how close are we to OOM?".  Returns -1
    *  on task_info failure (very rare).  Resolves immediately. */
   getMemoryFootprintMB(): Promise<number>;
+  /** 2026-06-16 — total physical RAM in MB.  Lets the DEV memory pill derive
+   *  RAM-aware pressure bands instead of iPhone-fixed thresholds.  -1 on
+   *  failure.  Resolves immediately. */
+  getDeviceTotalRamMB?(): Promise<number>;
   /**
    * 2026-05-16 — realtime+batch fusion API foundation.  Run the
    * shared C++ `cv::Stitcher` pipeline over a caller-supplied list

package/src/stitching/useIncrementalStitcher.ts

@@ -85,6 +85,12 @@ export interface UseIncrementalStitcherReturn {
      * translation magnitude and prefers that).
      */
     imuTranslationMetres?: number,
+    /**
+     * 2026-06-16 — the EXPLICIT lens the user selected (`'1x'` | `'0.5x'`).
+     * The reliable zoom signal for the high-level warper tree (`'0.5x'`
+     * ultra-wide → spherical).  Omit ⇒ treated as `'1x'`.
+     */
+    lens?: string,
   ) => Promise<IncrementalFinalizeResult>;
   /** Abort the capture without producing output. */
   cancel: () => Promise<void>;
@@ -198,6 +204,7 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
       quality = 90,
       captureOrientation?: string,
       imuTranslationMetres?: number,
+      lens?: string,
     ): Promise<IncrementalFinalizeResult> => {
       if (!native) {
         throw new Error('useIncrementalStitcher: native module unavailable');
@@ -216,6 +223,12 @@ export function useIncrementalStitcher(): UseIncrementalStitcherReturn {
         // 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),
+        // 2026-06-16 — the EXPLICIT lens the user selected ('1x' | '0.5x').
+        // This is the reliable zoom signal for the high-level warper tree
+        // (0.5x ultra-wide → spherical); deriving zoom from intrinsics FOV was
+        // unreliable (multi-cam 0.5x reaches the ultra-wide by zoom without
+        // changing the reported fx, and the non-AR path may supply fx=0).
+        lens,
       });
       setIsRunning(false);
       // Clear React state on finalize so the next start doesn't

package/android/src/main/java/io/imagestitcher/rn/TransferredNV21.kt

@@ -1,100 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-package io.imagestitcher.rn
-
-/**
- * v0.10.0 (audit #4A) — single-use NV21 byte-array handle that
- * enforces the engine's pixel-data ownership contract at runtime.
- *
- * ## Why this exists
- *
- * `IncrementalStitcher.ingestFromARCameraView` accepts an
- * `nv21PixelData` parameter that the engine retains for ~50 ms
- * after the producer thread returns (until the `workScope`
- * coroutine consumes it).  The documented contract is
- * "callers MUST treat the array as transferred — do not mutate it
- * or return it to a buffer pool after calling this method."
- *
- * The v0.10.0 audit (`docs/plans/handoff/2026-05-26-autonomous-run-handoff.md`
- * finding #4A) noted this is by-convention only.  The current AR
- * caller (`RNSARCameraView`) passes the same `packed.nv21` array
- * as BOTH `grayData` (consumed synchronously inside the gate)
- * AND `nv21PixelData` (consumed asynchronously).  Today no race
- * because the sync read finishes before the async coroutine reads,
- * but a future refactor that reorders consumption would silently
- * corrupt frames.
- *
- * Wrapping the bytes in `TransferredNV21` turns the documentation
- * contract into a runtime contract: callers can only extract the
- * bytes once via `takeOnce()`; the second call throws.  The
- * misuse is caught at the call site, not at the engine.
- *
- * ## Cost
- *
- * Construction: tens of ns (one heap allocation for the wrapper +
- * one volatile write of the bytes reference).  `takeOnce()`: tens
- * of ns (one synchronized read + one null-out).  Negligible vs the
- * underlying NV21 array's KB-scale memory footprint and the
- * ms-scale frame-processing cost — but not a free pointer hop.
- *
- * ## Thread-safety
- *
- * `takeOnce()` and `available` are `synchronized` on the wrapper
- * itself.  Producers should still extract on a single thread (the
- * frame producer); the synchronization defends against the
- * pathological case where two threads race to extract.
- */
-class TransferredNV21(bytes: ByteArray) {
-    init {
-        // Empty arrays would propagate as "0 bytes of pixel data with
-        // a non-zero width/height" downstream and crash inside the
-        // C++ ingest with a far less actionable error.  Catch at
-        // construction.  Critic-finding [MAJOR][B].
-        require(bytes.isNotEmpty()) {
-            "TransferredNV21 requires a non-empty byte array " +
-                "(received zero-length)"
-        }
-    }
-
-    @Volatile
-    private var bytes: ByteArray? = bytes
-
-    /**
-     * Take the wrapped bytes.  Throws on second call.
-     *
-     * Consumers should call this exactly once — typically once per
-     * frame, on the producer thread, immediately before handing
-     * the bytes to the async work queue:
-     *
-     * ```kotlin
-     * val pixelBytes: ByteArray? = if (hasPixelData) nv21PixelData!!.takeOnce() else null
-     * workScope.launch {
-     *     // pixelBytes is captured by value; no race.
-     *     engine.addFramePixelData(nv21 = pixelBytes!!, ...)
-     * }
-     * ```
-     *
-     * Concurrency note: `@Volatile` on the bytes field plus the
-     * `synchronized(this)` block here together guarantee both
-     * visibility AND atomicity across threads.  The `@Volatile` is
-     * defensive for any future non-synchronized read; today every
-     * accessor goes through the synchronized block.
-     */
-    fun takeOnce(): ByteArray = synchronized(this) {
-        val b = bytes ?: error(
-            "TransferredNV21.takeOnce() called twice — bytes already transferred. " +
-                "Check that you're not passing the same TransferredNV21 instance to " +
-                "two consumers (e.g., a sync gate-eval call AND an async workScope.launch)."
-        )
-        bytes = null
-        b
-    }
-
-    // Note: an `available` property was considered and removed in
-    // pre-merge review (critic-finding [MAJOR][B]).  Any
-    // `if (handle.available) handle.takeOnce()` pattern is
-    // inherently TOCTOU-racy — another thread could win the
-    // takeOnce() between the check and the use.  Consumers should
-    // call `takeOnce()` directly and catch the `IllegalStateException`
-    // if they need recovery semantics.  No internal caller used
-    // `available`; YAGNI removed it.
-}