react-native-image-stitcher 0.16.0 → 0.16.2

package/src/camera/Camera.tsx

@@ -223,6 +223,19 @@ export type CameraCaptureResult =
        * cv::Stitcher at finalize).
        */
       stitchModeResolved?: 'panorama' | 'scans';
+      /**
+       * 2026-06-15 (DEV) — gyro rotation magnitude of the capture, in radians.
+       * Shown on the dev preview so the panorama-vs-SCANS rotation threshold can
+       * be tuned. `0` = no pose-derived rotation signal (non-AR with no poses).
+       */
+      rRadians?: number;
+      /**
+       * 2026-06-16 (DEV) — translation magnitude (m) + auto decision ratio
+       * (`>=0.55` → SCANS) that drove panorama-vs-SCANS. Shown on the dev
+       * readout alongside `rRadians` to tune the threshold from real captures.
+       */
+      tMeters?: number;
+      decisionRatio?: number;
       /**
        * 2026-06-14 (DEV overlay) — semicolon-separated `key=value` trace of the
        * stitcher's runtime choices (pipe/warp/route/seam/blend) for this
@@ -1251,64 +1264,6 @@ export function Camera(props: CameraProps): React.JSX.Element {
     warnings: CaptureWarning[];
   } | null>(null);
 
-  // 2026-06-15 — ON-DEMAND high-level preview.  Manual is the default/eager
-  // output; when the user switches to the "high-level" tab in the preview we
-  // re-stitch the SAME captured keyframes through stock cv::Stitcher via
-  // `refinePanorama` (useManualPipeline:false).  Resolves with the high-level
-  // JPEG's file:// uri AND its OWN DEV-overlay recipe (so the preview pill shows
-  // the high-level recipe — pipe=highlevel;… — while that tab is viewed, not the
-  // manual primary's recipe), or null when unavailable (no keyframe paths —
-  // e.g. Android — or the stitch failed).  Computed lazily so it costs nothing
-  // unless the user actually asks for it.
-  const requestHighLevelAlt = useCallback(async (): Promise<{
-    uri: string;
-    debugInfo: string;
-  } | null> => {
-    const pending = cropPending;
-    const kf = pending?.captureResultObj.keyframePaths;
-    if (!pending || !kf || kf.length < 2) return null;
-    const native = getIncrementalNativeModule();
-    if (!native) return null;
-    const outputPath = `${toBareFilePath(pending.uri).replace(/\.jpg$/i, '')}-highlevel.jpg`;
-    try {
-      const r = await native.refinePanorama({
-        framePaths: kf,
-        outputPath,
-        config: {
-          useManualPipeline: false,
-          warperType: 'spherical',
-          stitchMode: 'panorama',
-          // Match the manual output's rotation — without this the high-level
-          // re-stitch bakes "portrait" (no rotation) and comes out sideways.
-          captureOrientation: pending.captureResultObj.captureOrientation as
-            | 'portrait'
-            | 'portrait-upside-down'
-            | 'landscape-left'
-            | 'landscape-right'
-            | undefined,
-        },
-      });
-      // Plain file:// uri — the path is unique per capture and computed once, so
-      // no cache-bust here (the accept handler adds one when emitting).  The
-      // DEV pill text is the HIGH-LEVEL stitch's own recipe (only the fields
-      // IncrementalRefineResult carries; buildStitchDebugInfo tolerates the rest
-      // being absent).
-      return {
-        uri: toFileUri(r.panoramaPath),
-        debugInfo: buildStitchDebugInfo({
-          debugSummary: r.debugSummary,
-          finalConfidenceThresh: r.finalConfidenceThresh,
-          framesIncluded: r.framesIncluded,
-          framesRequested: r.framesRequested,
-          width: r.width,
-          height: r.height,
-        }),
-      };
-    } catch {
-      return null;
-    }
-  }, [cropPending]);
-
   // 2026-05-22 (audit F9 + F3) — debug stitch-stats toast.  Hook
   // exposes an imperative API; we fire `showResult(finalizeResult)`
   // on every successful finalize when settings.debug is on (gated
@@ -2086,6 +2041,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
         90, // default JPEG quality
         deviceOrientation,
         imuTotalTranslationM,
+        lens, // 2026-06-16 — explicit '1x'|'0.5x' for the high-level warper tree
       );
       if (
         typeof result.framesRequested === 'number'
@@ -2125,6 +2081,9 @@ export function Camera(props: CameraProps): React.JSX.Element {
         finalConfidenceThresh: result.finalConfidenceThresh ?? -1,
         durationMs: Date.now() - (recordingStartedAt ?? Date.now()),
         stitchModeResolved: result.stitchModeResolved,
+        rRadians: result.rRadians,
+        tMeters: result.tMeters,
+        decisionRatio: result.decisionRatio,
         debugSummary: result.debugSummary,
         keyframePaths: result.batchKeyframePaths,
         captureOrientation: result.captureOrientation,
@@ -2228,6 +2187,10 @@ export function Camera(props: CameraProps): React.JSX.Element {
     isNonAR,
     imuGate,
     stitchToast,
+    // 2026-06-16 — the finalize passes `lens` (the high-level warper tree's zoom
+    // signal); without it here the closure would send a STALE lens if the user
+    // switched 1x↔0.5x after this callback was last memoized.
+    lens,
     // feature/pano-ux-guidance — the release also tears down the
     // pan-duration timer + a pending rotate-gate, and decides whether to
     // route the result through the crop editor.
@@ -2864,18 +2827,6 @@ export function Camera(props: CameraProps): React.JSX.Element {
         imageUri={cropPending?.uri ?? ''}
         imageWidth={cropPending?.width ?? 0}
         imageHeight={cropPending?.height ?? 0}
-        // 2026-06-15 — manual is the default/eager output.  The high-level tab
-        // is ON DEMAND: RectCropPreview calls onRequestAlt() (which re-stitches
-        // the captured keyframes via cv::Stitcher) only when the user switches
-        // to it.  DEBUG-ONLY: it's a pipeline-comparison tool (dev-jargon
-        // "Manual"/"High-level" labels), gated behind `settings.debug` like the
-        // rest of the diagnostic UI.  Also requires keyframePaths, so it only
-        // appears where it can run (iOS); Android returns no paths → no tab.
-        onRequestAlt={
-          settings.debug && cropPending?.captureResultObj.keyframePaths?.length
-            ? requestHighLevelAlt
-            : undefined
-        }
         initialRect={cropPending?.initialRect}
         warnings={cropPending?.warnings.map((w) => w.message) ?? []}
         showCropControls={rectCrop}

package/src/camera/CaptureFrameCounterOverlay.tsx

@@ -36,6 +36,14 @@ import { GUIDANCE_COUNTDOWN, GUIDANCE_PILL, GUIDANCE_TOKENS } from './guidanceTo
 import { type DeviceOrientation } from './useDeviceOrientation';
 
 
+/**
+ * Extra distance (px) to drop the counter from the user-top in landscape so it
+ * clears the pan how-to coach-mark's bouncing arrow.  Landscape only; portrait
+ * is unaffected.  72 px (the symmetric lift) over-cleared, so this is smaller.
+ */
+const COUNTER_LANDSCAPE_EXTRA_INSET = 40;
+
+
 export interface CaptureFrameCounterOverlayProps {
   /** Show / hide.  Driven by the host while a capture is recording. */
   visible: boolean;
@@ -63,9 +71,15 @@ export function CaptureFrameCounterOverlay({
   // briefly report the cap-th accept before the parent finalizes.
   const k = Math.max(0, Math.min(framesCaptured, framesMax));
 
+  // 2026-06-16 — in LANDSCAPE, push the counter further from the user-top so it
+  // clears the pan how-to coach-mark's bouncing amber arrow, which sits near the
+  // top there and otherwise overlaps it.  Portrait keeps the standard inset.
+  // Tune COUNTER_LANDSCAPE_EXTRA_INSET if the gap is too small / too large.
+  const isLandscape =
+    orientation === 'landscape-left' || orientation === 'landscape-right';
   const { container, rotate } = topCenterForOrientation(
     orientation,
-    GUIDANCE_COUNTDOWN.inset,
+    GUIDANCE_COUNTDOWN.inset + (isLandscape ? COUNTER_LANDSCAPE_EXTRA_INSET : 0),
   );
 
   return (

package/src/camera/CaptureMemoryPill.tsx

@@ -3,15 +3,23 @@
  * CaptureMemoryPill — top-right diagnostic pill showing native
  * process memory footprint in MB, polled at 500 ms.
  *
- * Color-coded against the iPhone 16 Pro per-process jetsam limit:
+ * Color-coded against the device's per-process memory budget, which is read
+ * once at mount via `getDeviceTotalRamMB()` (RAM-aware):
  *
- *   - green  <1500 MB   (comfortable)
- *   - amber  1500–2200  (approaching pressure)
- *   - red    >2200      (close to limit — capture may be killed)
+ *   budget = max(RAM × 0.42, 900 MB)   (mirrors warp_guard.hpp
+ *                                        perProcessMemoryBudgetMB)
+ *   - green  < 55 % of budget   (comfortable)
+ *   - amber  55–70 % of budget   (approaching pressure)
+ *   - red    > 70 % of budget    (close to limit — capture may be killed)
  *
- * Backed by the existing `getMemoryFootprintMB()` native module
- * (iOS: `task_info phys_footprint`, Android: `Debug.MemoryInfo
- * getTotalPss * 1024`).  Returns -1 if the native call fails.
+ * Why RAM-aware: the old fixed 1500/2200 MB thresholds were tuned for the
+ * iPhone 16 Pro and NEVER tripped on a 4 GB Android phone that jetsams ~1.3 GB
+ * (false comfort exactly where OOM happens).  Falls back to 1500/2200 if the
+ * RAM read is unavailable.
+ *
+ * Backed by the `getMemoryFootprintMB()` native module (iOS: `task_info`
+ * `phys_footprint`; Android: `/proc/self/statm` RSS — the SAME number the C++
+ * `[memstat]` logs report).  Returns -1 if the native call fails.
  *
  * Mount this pill inside a `settings.debug`-gated branch — it
  * polls native every 500 ms and is unwanted in production builds.
@@ -50,11 +58,21 @@ export function CaptureMemoryPill({
   style,
 }: CaptureMemoryPillProps): React.JSX.Element | null {
   const [memMB, setMemMB] = useState<number | null>(null);
+  // Device total RAM (MB), read once — drives the RAM-aware pressure bands.
+  const [ramMB, setRamMB] = useState<number | null>(null);
 
   useEffect(() => {
     const native = getIncrementalNativeModule();
     if (!native?.getMemoryFootprintMB) return undefined;
     let cancelled = false;
+    // One-time RAM read for the bands (optional native method — older bridges
+    // without it just keep the fixed-threshold fallback).
+    native
+      .getDeviceTotalRamMB?.()
+      .then((r) => {
+        if (!cancelled && r > 0) setRamMB(r);
+      })
+      .catch(() => {});
     const tick = async () => {
       try {
         const mb = await native.getMemoryFootprintMB();
@@ -73,9 +91,15 @@ export function CaptureMemoryPill({
 
   if (memMB === null || memMB < 0) return null;
 
+  // RAM-aware bands: budget = max(RAM × 0.42, 900) (mirrors warp_guard.hpp
+  // perProcessMemoryBudgetMB); amber at 55 %, red at 70 %.  Fall back to the
+  // iPhone-tuned fixed thresholds when RAM is unknown.
+  const budget = ramMB != null ? Math.max(ramMB * 0.42, 900) : null;
+  const redAt = budget != null ? budget * 0.7 : 2200;
+  const amberAt = budget != null ? budget * 0.55 : 1500;
   const bg =
-    memMB > 2200 ? 'rgba(239, 68, 68, 0.92)'    // red
-    : memMB > 1500 ? 'rgba(245, 158, 11, 0.92)' // amber
+    memMB > redAt ? 'rgba(239, 68, 68, 0.92)'    // red
+    : memMB > amberAt ? 'rgba(245, 158, 11, 0.92)' // amber
     : 'rgba(34, 197, 94, 0.92)';                // green
 
   return (

package/src/camera/PanoramaBandOverlay.tsx

@@ -361,7 +361,7 @@ function layoutFor(
 }
 
 
-export function PanoramaBandOverlay({
+function PanoramaBandOverlayImpl({
   state,
   frameUris,
   captureOrientation,
@@ -585,6 +585,14 @@ export function PanoramaBandOverlay({
   );
 }
 
+// 2026-06-16 (audit #7) — memoized.  This is the lone ~6 Hz consumer that mounts
+// in PRODUCTION (the debug pills are settings.debug-gated), and most engine ticks
+// are REJECTED frames that don't change its visible inputs (frameUris /
+// acceptedCount / orientation).  React.memo skips the re-render on those, so the
+// ~6×/sec engine emits no longer re-render this overlay's subtree on the hot
+// capture path (battery/heat on long captures).
+export const PanoramaBandOverlay = React.memo(PanoramaBandOverlayImpl);
+
 
 const styles = StyleSheet.create({
   // Properties common to every layout — uniform border-radius so the

package/src/camera/PanoramaSettings.ts

@@ -314,21 +314,19 @@ export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
   captureSource: 'ar',
   debug: false,
   stitcher: {
-    // v0.16 — PANORAMA by default (was 'auto').  The auto-resolver's SCANS
-    // branch leans on double-integrated IMU translation, which is unreliable
-    // during rotation (gravity leakage inflates the translation estimate); in
-    // practice rotational pans are the common case and resolve to panorama
-    // anyway.  Defaulting to panorama is the robust choice — host apps that
-    // genuinely capture flat documents/walls can still opt into 'auto' or
-    // 'scans' via the ⚙️ panel or the `defaultStitchMode` / `stitcher` props.
-    stitchMode: 'panorama',
-    // v0.16 — SPHERICAL by default (bounds both axes; the proven-robust wide/
-    // vertical-pan projection).  This is now the single source of truth — the
-    // native side no longer hardcodes a warper, so the ⚙️ panel + the host's
-    // `defaultWarper` prop actually take effect.  Note: choosing `plane` here
-    // re-arms the dynamic plane→spherical fallback/divergence switch in the
-    // manual pipeline (it only fires when warperType != spherical).
-    warperType: 'spherical',
+    // v0.16 — AUTO by default.  Reverted from the brief 'panorama' default after
+    // on-device comparison (matches the v0.15.2 behaviour, which produced better
+    // results for these captures).  The auto-resolver now carries the
+    // low-rotation guard (rRadians>0.35 && t<0.25 → force PANORAMA), so the old
+    // IMU-gravity-leak SCANS misclassification on rotational pans is fixed; auto
+    // can again safely pick SCANS (high-level affine) for genuine flat scans.
+    stitchMode: 'auto',
+    // v0.16 — PLANE by default.  Reverted from 'spherical' after on-device
+    // comparison (matches v0.15.2 — flatter, more natural for the common 1x
+    // pan).  Plane is unbounded, so this re-arms the manual pipeline's dynamic
+    // plane→SPHERICAL divergence/quality fallback (it fires only when
+    // warperType != 'spherical'), keeping wide/off-axis pans safe.
+    warperType: 'plane',
     blenderType: 'multiband',
     seamFinderType: 'graphcut',
     // v0.15 — inscribed-rect crop is OFF by default (bbox crop keeps all
@@ -339,16 +337,15 @@ export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
   },
   frameSelection: {
     mode: 'flow-based',
-    // v0.16 — denser keyframes by default: a 15% novelty gate, up to 8 frames,
-    // plus a 1.5 s time-budget force-accept (so a slow/static pan still lands a
-    // keyframe every 1.5 s even when novelty is low).  With 8 frames this bounds
-    // a static/slow capture to ~8×1.5 ≈ 12 s before the keyframe-count
-    // auto-finalize.  More overlap between consecutive keyframes ⇒ stronger
-    // feature matching ⇒ more robust registration.  Memory-checked: 8 frames fit
-    // the BATCH held-set cap on both platforms.  Overlap selectable in the
-    // settings panel {10,15,20,30}% (native clamp floor 10%); cap clamps [3,10].
-    maxKeyframes: 8,
-    overlapThreshold: 0.15,
+    // v0.16 — keyframe gate: a 20% novelty gate, up to 6 frames, plus a 1.5 s
+    // time-budget force-accept (so a slow/static pan still lands a keyframe every
+    // 1.5 s even when novelty is low).  These match the leaner v0.15.2 cadence (6
+    // frames / 20% overlap) — fewer, more-novel keyframes = lighter memory + less
+    // redundant overlap.  With 6 frames this bounds a static/slow capture to
+    // ~6×1.5 ≈ 9 s before the keyframe-count auto-finalize.  Overlap selectable in
+    // the settings panel {10,15,20,30}% (native clamp floor 10%); cap clamps [3,10].
+    maxKeyframes: 6,
+    overlapThreshold: 0.20,
     maxKeyframeIntervalMs: 1500,
     flow: DEFAULT_FLOW_GATE_SETTINGS,
   },