react-native-image-stitcher 0.15.1 → 0.16.0

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

@@ -14,6 +14,7 @@ import org.opencv.core.Core
 import org.opencv.core.CvType
 import org.opencv.core.Mat
 import org.opencv.core.MatOfInt
+import org.opencv.core.MatOfPoint2f
 import org.opencv.core.Point
 import org.opencv.core.Rect
 import org.opencv.core.Scalar
@@ -108,8 +109,27 @@ class BatchStitcher(reactContext: ReactApplicationContext)
         // SCANS canvas size is bounded by sum-of-frames; PANORAMA
         // can diverge to multi-GB on translation-heavy input).
         stitchMode: String,
+        // 2026-06-15 — pipeline picker (mirrors iOS' OpenCVStitcher
+        // `useManualPipeline:` param).  true → the MANUAL cv::detail
+        // pipeline (graphcut + multiband + the full memory-guard set;
+        // the default for batch capture).  false → stock high-level
+        // cv::Stitcher (the on-demand HIGH-LEVEL preview tab driven by
+        // refinePanorama).  Appended LAST to match the JNI C signature
+        // in image_stitcher_jni.cpp — order/count/type must line up
+        // exactly or it's an UnsatisfiedLinkError at runtime.
+        useManualPipeline: Boolean,
     ): IntArray
 
+    // 2026-06-15 — getter for the last successful stitch's debugSummary
+    // (pipe/warp/route/seam/blend).  The jintArray return of
+    // nativeStitchFramePaths can't carry a string; this fetches the value the
+    // JNI stashed.  Called by stitchSync right after a successful stitch.
+    private external fun nativeLastDebugSummary(): String
+
+    /** debugSummary of the most recent stitchSync() (empty if none/failed). */
+    internal var lastDebugSummary: String = ""
+        private set
+
     // ── Stitch frames → panorama ─────────────────────────────────
 
     @ReactMethod
@@ -180,6 +200,9 @@ class BatchStitcher(reactContext: ReactApplicationContext)
                     seamEstimationResolMP,
                     compositingResolMP,
                     stitchMode,
+                    // Direct @ReactMethod batch stitch → MANUAL pipeline
+                    // (the memory-safe default; mirrors iOS).
+                    true,
                 )
                 val duration = System.currentTimeMillis() - start
                 // 2026-05-15 (D) — dims layout from native JNI:
@@ -378,6 +401,121 @@ class BatchStitcher(reactContext: ReactApplicationContext)
         }
     }
 
+    /**
+     * item-7 — free-quad perspective crop (iOS `cropToQuadAtPath` parity).
+     *
+     * `options` carries `imagePath` + the 4 IMAGE-PIXEL corners as a flat
+     * `quad` array of 8 numbers `[tlX,tlY,trX,trY,brX,brY,blX,blY]`
+     * (ordered TL→TR→BR→BL by the JS editor's `orderQuadCorners`) +
+     * optional `quality` (default 90).  Rectifies the quadrilateral to an
+     * upright rectangle (Imgproc.getPerspectiveTransform +
+     * Imgproc.warpPerspective), overwrites in place, resolves
+     * `{ width, height }`.  Mirrors `cropToRect`; the JS editor chooses
+     * this when the dragged quad isn't ~axis-aligned.
+     *
+     * The destination size (averaged opposite edges) + the convex /
+     * min-area / in-bounds gate + the output-canvas OOM guard are
+     * Kotlin ports of cpp/crop_quad.hpp (quadDstRect / isQuadAcceptable)
+     * and cpp/warp_guard.hpp (canvasExceedsGuard), kept in sync with iOS
+     * per the same "duplicate stage code" convention `cropToRect` follows.
+     */
+    @ReactMethod
+    fun cropToQuad(options: ReadableMap, promise: Promise) {
+        val imagePath = options.getString("imagePath")
+            ?: return promise.reject("invalid-options", "imagePath required")
+        val quadArr = options.getArray("quad")
+        if (quadArr == null || quadArr.size() != 8) {
+            return promise.reject(
+                "invalid-options",
+                "quad must be an array of 8 numbers [tlX,tlY,trX,trY,brX,brY,blX,blY]",
+            )
+        }
+        val p = DoubleArray(8) { quadArr.getDouble(it) }
+        val quality =
+            (if (options.hasKey("quality") && !options.isNull("quality")) {
+                options.getInt("quality")
+            } else {
+                90
+            }).coerceIn(1, 100)
+        CoroutineScope(Dispatchers.Default).launch {
+            val toRelease = mutableListOf<Mat>()
+            try {
+                ensureOpenCv()
+                val cleaned = stripFileScheme(imagePath)
+                if (!File(cleaned).exists()) {
+                    promise.reject("read-failed", "Image not found: $imagePath")
+                    return@launch
+                }
+                val img = Imgcodecs.imread(cleaned, Imgcodecs.IMREAD_COLOR)
+                toRelease += img
+                if (img.empty()) {
+                    promise.reject("read-failed", "Could not decode $imagePath")
+                    return@launch
+                }
+
+                // Geometry gate — convex, non-degenerate, inside the image.
+                if (!isQuadAcceptableForCrop(p, img.cols().toDouble(), img.rows().toDouble())) {
+                    promise.reject(
+                        "crop-to-quad-failed",
+                        "Crop quad is degenerate (non-convex, zero-area, or out of bounds)",
+                    )
+                    return@launch
+                }
+                // Destination size = avg of opposite edge lengths (rounded).
+                val dstW = Math.round((quadEdge(p, 0, 1) + quadEdge(p, 3, 2)) / 2.0).toInt()
+                val dstH = Math.round((quadEdge(p, 0, 3) + quadEdge(p, 1, 2)) / 2.0).toInt()
+                // Output-canvas OOM net — same 50 MP guard the stitch uses.
+                if (dstW <= 0 || dstH <= 0 || canvasExceedsGuard(dstW.toLong(), dstH.toLong())) {
+                    promise.reject(
+                        "crop-to-quad-failed",
+                        "Crop quad output canvas is degenerate or exceeds the size guard (${dstW}x${dstH})",
+                    )
+                    return@launch
+                }
+
+                val src = MatOfPoint2f(
+                    Point(p[0], p[1]),  // TL
+                    Point(p[2], p[3]),  // TR
+                    Point(p[4], p[5]),  // BR
+                    Point(p[6], p[7]),  // BL
+                )
+                toRelease += src
+                val dst = MatOfPoint2f(
+                    Point(0.0, 0.0),
+                    Point(dstW.toDouble(), 0.0),
+                    Point(dstW.toDouble(), dstH.toDouble()),
+                    Point(0.0, dstH.toDouble()),
+                )
+                toRelease += dst
+                val transform = Imgproc.getPerspectiveTransform(src, dst)
+                toRelease += transform
+                val warped = Mat()
+                toRelease += warped
+                Imgproc.warpPerspective(
+                    img, warped, transform, Size(dstW.toDouble(), dstH.toDouble()),
+                    Imgproc.INTER_LINEAR,
+                )
+                if (warped.empty()) {
+                    promise.reject("crop-to-quad-failed", "Perspective warp produced an empty image")
+                    return@launch
+                }
+                val params = MatOfInt(Imgcodecs.IMWRITE_JPEG_QUALITY, quality)
+                if (!Imgcodecs.imwrite(cleaned, warped, params)) {
+                    promise.reject("write-failed", "Could not rewrite $imagePath")
+                    return@launch
+                }
+                promise.resolve(WritableNativeMap().apply {
+                    putInt("width", warped.cols())
+                    putInt("height", warped.rows())
+                })
+            } catch (t: Throwable) {
+                promise.reject("crop-to-quad-failed", t.message, t)
+            } finally {
+                toRelease.forEach { it.release() }
+            }
+        }
+    }
+
     /** Red-tint the dropped pixels; writes `<path>.mask.jpg`. Resolves `{ maskPath, width, height, excludedPercent }`. */
     @ReactMethod
     fun debugMaskOverlay(options: ReadableMap, promise: Promise) {
@@ -546,6 +684,79 @@ class BatchStitcher(reactContext: ReactApplicationContext)
         return intArrayOf(bx, by, bw, bh)
     }
 
+    // ── item-7 free-quad crop geometry (ports of cpp/crop_quad.hpp +
+    //    cpp/warp_guard.hpp; kept in sync with iOS cropToQuad) ───────
+
+    /**
+     * Euclidean length of the edge between corners `i` and `j` in the flat
+     * `[x0,y0,x1,y1,...]` quad array `p` (corner k = (p[2k], p[2k+1])).
+     */
+    private fun quadEdge(p: DoubleArray, i: Int, j: Int): Double {
+        val dx = p[2 * i] - p[2 * j]
+        val dy = p[2 * i + 1] - p[2 * j + 1]
+        return Math.hypot(dx, dy)
+    }
+
+    /**
+     * Port of cpp/crop_quad.hpp:isQuadAcceptable for the flat 8-number
+     * quad `p` ([tlX,tlY,trX,trY,brX,brY,blX,blY]).  True when the quad is
+     * convex, has |area| ≥ `minArea` px², and every corner lies inside
+     * `[0..imageW]×[0..imageH]` (½-px epsilon).  Mirrors the iOS gate so
+     * both platforms reject the same degenerate quads.
+     */
+    private fun isQuadAcceptableForCrop(
+        p: DoubleArray,
+        imageW: Double,
+        imageH: Double,
+        minArea: Double = 1.0,
+    ): Boolean {
+        // Convexity — all consecutive edge cross-products share one sign.
+        var sign = 0
+        for (i in 0 until 4) {
+            val ax = p[2 * i]; val ay = p[2 * i + 1]
+            val bx = p[2 * ((i + 1) % 4)]; val by = p[2 * ((i + 1) % 4) + 1]
+            val cx = p[2 * ((i + 2) % 4)]; val cy = p[2 * ((i + 2) % 4) + 1]
+            val cross = (bx - ax) * (cy - by) - (by - ay) * (cx - bx)
+            if (cross != 0.0) {
+                val s = if (cross > 0.0) 1 else -1
+                if (sign == 0) sign = s else if (s != sign) return false
+            }
+        }
+        // Min-area via the shoelace formula (|2A| ≥ 2·minArea).
+        var area2 = 0.0
+        for (i in 0 until 4) {
+            val ax = p[2 * i]; val ay = p[2 * i + 1]
+            val bx = p[2 * ((i + 1) % 4)]; val by = p[2 * ((i + 1) % 4) + 1]
+            area2 += ax * by - bx * ay
+        }
+        if (Math.abs(area2) < minArea * 2.0) return false
+        // In-bounds — every corner inside the decoded image (½-px slop).
+        if (imageW > 0.0 && imageH > 0.0) {
+            val eps = 0.5
+            for (i in 0 until 4) {
+                val x = p[2 * i]; val y = p[2 * i + 1]
+                if (x < -eps || x > imageW + eps || y < -eps || y > imageH + eps) return false
+            }
+        }
+        return true
+    }
+
+    /**
+     * Port of cpp/warp_guard.hpp:canvasExceedsGuard — true when a
+     * `width`×`height` output canvas is degenerate (non-positive) or
+     * strictly larger than `maxPixels` (default 50 MP, boundary inclusive).
+     * int64 area math matches the C++ so the same quads are rejected.
+     */
+    private fun canvasExceedsGuard(
+        width: Long,
+        height: Long,
+        maxPixels: Long = 50L * 1000L * 1000L,
+    ): Boolean {
+        if (width <= 0 || height <= 0) return true
+        if (width > 3_000_000_000L || height > 3_000_000_000L) return true
+        return width * height > maxPixels
+    }
+
     // ── Internals ────────────────────────────────────────────────
 
     /**
@@ -623,9 +834,15 @@ class BatchStitcher(reactContext: ReactApplicationContext)
         // translation captures safely (PANORAMA on translation can
         // diverge → multi-GB canvas → lmkd kill).
         stitchMode: String = "scans",
+        // 2026-06-15 — pipeline picker (mirrors iOS' OpenCVStitcher
+        // `useManualPipeline:`).  Defaults to true (MANUAL) so the
+        // batch-keyframe finalize orchestrator gets the memory-safe
+        // manual path without re-stating it.  The refine/high-level
+        // path passes false to drive the stock cv::Stitcher pipeline.
+        useManualPipeline: Boolean = true,
     ): IntArray {
         ensureNativeStitcher()
-        return nativeStitchFramePaths(
+        val dims = nativeStitchFramePaths(
             framePaths,
             outputPath,
             jpegQuality,
@@ -638,7 +855,12 @@ class BatchStitcher(reactContext: ReactApplicationContext)
             seamEstimationResolMP,
             compositingResolMP,
             stitchMode,
+            useManualPipeline,
         )
+        // Capture the run's debugSummary (pipe/warp/route/seam/blend) for the
+        // DEV overlay; best-effort so a getter hiccup never fails the stitch.
+        lastDebugSummary = try { nativeLastDebugSummary() } catch (_: Throwable) { "" }
+        return dims
     }
 
     /**

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

@@ -420,7 +420,7 @@ class IncrementalStitcher(
             // stalled scan still advances).  iOS parity:
             // IncrementalStitcher.swift maxKeyframeIntervalMs block.
             val maxKfIntervalMs = configOverrides
-                ?.getDoubleOrDefault("maxKeyframeIntervalMs", 2000.0) ?: 2000.0
+                ?.getDoubleOrDefault("maxKeyframeIntervalMs", 1500.0) ?: 1500.0
             keyframeGate.maxKeyframeIntervalMs = maxKfIntervalMs.coerceAtLeast(0.0)
             // 2026-05-22 (audit F5) — flow-strategy Shi-Tomasi
             // tunables.  Pre-audit, Android had no JNI for these
@@ -748,6 +748,30 @@ class IncrementalStitcher(
                     // resolved cv::Stitcher mode so JS can surface it
                     // on the output preview + debug toast.
                     map.putString("stitchModeResolved", stitchModeResolved)
+                    // 2026-06-15 (iOS parity) — the exact keyframe JPEG
+                    // paths used for this stitch, so JS can re-stitch
+                    // them ON DEMAND via refinePanorama (the high-level
+                    // preview tab) without enumerating the session dir.
+                    // Camera.tsx gates that tab on this array being
+                    // present, so without it the tab never appears on
+                    // Android (the bug this fixes).  Mirrors iOS'
+                    // FinalizePayload "batchKeyframePaths": payload.paths.
+                    val keyframePathsArray = Arguments.createArray()
+                    keyframePathsSnapshot.forEach { keyframePathsArray.pushString(it) }
+                    map.putArray("batchKeyframePaths", keyframePathsArray)
+                    // The orientation THIS stitch baked into the output.
+                    // The on-demand high-level re-stitch MUST pass the
+                    // same value back through refinePanorama or the
+                    // output comes out in raw sensor landscape (sideways)
+                    // — refinePanorama otherwise defaults to "portrait"
+                    // (no bake-rotation).  Mirrors iOS' FinalizePayload
+                    // "captureOrientation": payload.captureOrientation.
+                    map.putString("captureOrientation", captureOrientationSnapshot)
+                    // 2026-06-15 — DEV overlay parity with iOS: the stitcher's
+                    // runtime recipe (pipe/warp/route/seam/blend) so the Android
+                    // pill shows the same detail, not just mode/score/frames.
+                    val dbg = stitcher.lastDebugSummary
+                    if (dbg.isNotEmpty()) map.putString("debugSummary", dbg)
                 } else {
                     // The live engines (hybrid + firstwins/slit) and their
                     // auto-refine hook were archived in the 2026-06 batch-
@@ -1493,6 +1517,15 @@ class IncrementalStitcher(
             config?.getBooleanOrDefault("useInscribedRectCrop", false) ?: false
         val stitchMode = (config?.getString("stitchMode") ?: "auto")
             .let { if (it in setOf("auto", "panorama", "scans")) it else "auto" }
+        // 2026-06-15 — pipeline is caller-selectable (mirrors iOS'
+        // refinePanorama `refineManual`).  The on-demand HIGH-LEVEL
+        // preview tab (Camera.tsx requestHighLevelAlt) calls
+        // refinePanorama with useManualPipeline:false to re-stitch the
+        // captured keyframes via stock cv::Stitcher.  Default false
+        // (high-level) preserves the refine path's historical
+        // cv::Stitcher behaviour.
+        val useManualPipeline =
+            config?.getBooleanOrDefault("useManualPipeline", false) ?: false
         val jpegQuality = max(1, min(100,
             config?.getIntOrDefault("jpegQuality", 90) ?: 90))
 
@@ -1538,9 +1571,18 @@ class IncrementalStitcher(
                     warperType,
                     blenderType,
                     seamFinderType,
+                    // captureOrientation flows through so the high-level
+                    // re-stitch bakes the SAME rotation the capture used
+                    // — without it the output is sideways (raw sensor
+                    // landscape).  The high-level tab passes back the
+                    // orientation the finalize emitted.
                     captureOrientation,
                     useInscribedRectCrop,
                     stitchMode = effectiveMode,
+                    // false = stock high-level cv::Stitcher (the on-demand
+                    // HIGH-LEVEL preview tab); true would force the manual
+                    // pipeline.  Sourced from the JS config above.
+                    useManualPipeline = useManualPipeline,
                 )
                 // Stitch returned — BatchStitcher writes the JPEG
                 // synchronously, so "writing" reflects the final
@@ -1568,6 +1610,10 @@ class IncrementalStitcher(
                     putInt("framesIncluded", framesIncluded)
                     putInt("framesDropped", framesRequested - framesIncluded)
                     putDouble("finalConfidenceThresh", finalConfidenceThresh)
+                    // DEV overlay — the high-level re-stitch's recipe so the
+                    // pill shows pipe/warp/route/seam/blend on the high-level tab.
+                    val dbg = stitcher.lastDebugSummary
+                    if (dbg.isNotEmpty()) putString("debugSummary", dbg)
                 }
                 emitRefineProgress(
                     stage = "done",
@@ -1649,39 +1695,38 @@ class IncrementalStitcher(
      * via `task_info(TASK_VM_INFO)` — see
      * `IncrementalStitcherBridge.swift:231-259`).
      *
-     * Returns the **total PSS** (proportional set size) of this
-     * process in MB.  PSS is the metric Android's Low-Memory-Killer
-     * (`lmkd`) ranks against, so it's the right one-true-number for
-     * the on-screen memory pill: it's "how close are we to being
-     * killed by the system?".
+     * Returns the process **RSS** (resident set size) in MB, read from
+     * `/proc/self/statm` (resident-pages × page-size).  RSS is what the shared
+     * C++ `[memstat]` lines report (`rss_mb()` reads the same `/proc`), so the
+     * pill and the stitch logs show the SAME number — handy when correlating a
+     * spike with a logcat trace.
      *
-     * Total PSS = USS (private) + sum(shared / refcount).  Read via
-     * `ActivityManager.getProcessMemoryInfo()`, which is the same API
-     * Android Studio's profiler uses.  Granularity is 1 KB; we
-     * divide by 1024 to MB so the JS side displays a number directly
-     * comparable to the iOS phys_footprint value.
+     * Why not `ActivityManager.getProcessMemoryInfo().totalPss`?  It's
+     * RATE-LIMITED on Android 8+ (returns a cached value when polled often), so
+     * at the pill's 500 ms cadence it froze at the launch-time reading and never
+     * moved.  `/proc/self/statm` is a single unthrottled read.
      *
-     * Returns -1.0 on failure (very rare — `getProcessMemoryInfo()`
-     * is generally infallible since Android 5.0 because PSS is read
-     * from `/proc/self/smaps` synchronously on the calling thread).
+     * Returns -1.0 on failure (very rare — `/proc/self/statm` is always present
+     * and cheap to read on the calling thread).
      */
     @ReactMethod
     fun getMemoryFootprintMB(promise: Promise) {
         try {
-            val am = reactContext.getSystemService(ActivityManager::class.java)
-            if (am == null) {
-                promise.resolve(-1.0)
-                return
-            }
-            val pid = android.os.Process.myPid()
-            val infos = am.getProcessMemoryInfo(intArrayOf(pid))
-            if (infos == null || infos.isEmpty()) {
-                promise.resolve(-1.0)
-                return
-            }
-            // totalPss is in KB.  Divide by 1024 → MB.  Use Double so
-            // the JS overlay can render fractional MB if it wants.
-            val mb = infos[0].totalPss.toDouble() / 1024.0
+            // Read RSS from /proc/self/statm (field[1] = resident pages).  This
+            // is UNTHROTTLED and matches the C++ [memstat] rss_mb() in logcat, so
+            // the pill tracks the same number I read from the stitch logs.
+            //
+            // 2026-06-15 — was ActivityManager.getProcessMemoryInfo().totalPss,
+            // which is RATE-LIMITED on Android 8+: polled frequently (the pill
+            // ticks every 500 ms) it returns a CACHED value, so the pill froze at
+            // its launch-time reading (~310 MB) and never showed the stitch spike.
+            val fields = java.io.File("/proc/self/statm")
+                .readText().trim().split(' ')
+            val residentPages = fields[1].toLong()
+            val pageSize =
+                android.system.Os.sysconf(android.system.OsConstants._SC_PAGESIZE)
+            val mb = residentPages.toDouble() * pageSize.toDouble() /
+                (1024.0 * 1024.0)
             promise.resolve(mb)
         } catch (t: Throwable) {
             android.util.Log.w(
@@ -1935,15 +1980,27 @@ class IncrementalStitcher(
         if (denom <= 1e-9) return "panorama"  // no motion either way
         val ratio = tScore / denom
 
+        // 2026-06-15 — LOW-ROTATION GUARD.  The gyro rotation (rRadians) is
+        // trustworthy; the IMU translation (tMeters, in non-AR) is NOT — a
+        // continuous rotation leaks gravity into the double-integrated accel and
+        // inflates it, which can falsely push `ratio` over 0.55 → SCANS, whose
+        // affine warper can't represent the rotation.  So when the gyro shows a
+        // clear pan (> ~20°) with only modest translation, force PANORAMA
+        // regardless of the (possibly-inflated) translation.  Genuine shelf
+        // scans (low rotation, large real translation) skip this and still
+        // reach SCANS via the ratio.  (Conservative: keeps the tMeters cap so a
+        // genuine large-translation capture isn't forced to PANORAMA.)
+        val lowRotationGuard = rRadians > 0.35 && tMeters < 0.25
+        val mode = if (!lowRotationGuard && ratio >= 0.55) "scans" else "panorama"
         android.util.Log.i(
             "IncrementalStitcher",
             "stitch-mode auto: tPose=${"%.3f".format(tPose)}m " +
                 "tImu=${"%.3f".format(imuTranslationMetres)}m " +
                 "r=${"%.3f".format(rRadians)}rad " +
                 "ratio=${"%.3f".format(ratio)} " +
-                "→ ${if (ratio >= 0.55) "scans" else "panorama"}",
+                "rotGuard=$lowRotationGuard → $mode",
         )
-        return if (ratio >= 0.55) "scans" else "panorama"
+        return mode
     }
 
     /**

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

@@ -151,7 +151,7 @@ internal class KeyframeGate : AutoCloseable {
     /// initializer below does NOT fire this setter, so the caller
     /// (IncrementalStitcher.kt) writes it explicitly at capture start
     /// to push the value into C++ (same contract as the iOS facade).
-    var maxKeyframeIntervalMs: Double = 2000.0
+    var maxKeyframeIntervalMs: Double = 1500.0
         set(value) {
             field = value
             nativeSetMaxKeyframeIntervalMs(nativeHandle, value)

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

@@ -860,21 +860,27 @@ class RNSARSession(reactContext: ReactApplicationContext)
             if (configs.isEmpty()) return
             fun aspect(s: android.util.Size): Float = s.width.toFloat() / s.height.toFloat()
 
-            val matched = configs.filter {
-                kotlin.math.abs(aspect(it.imageSize) - aspect(it.textureSize)) < 0.02f
-            }
-            val pool = if (matched.isNotEmpty()) matched else configs
-            val chosen = pool.sortedWith(
+            // Option B (max FOV + bounded memory): prefer the 4:3-aspect
+            // IMAGE for full vertical sensor FOV, regardless of texture aspect
+            // (the A35 only pairs its 4:3 image with a 16:9 texture, so an
+            // aspect-MATCH filter would force 16:9 and lose that FOV).  Among
+            // 4:3 images prefer the SMALLEST resolution — the keyframe is
+            // downscaled to AR_KEYFRAME_MAX_LONG_EDGE anyway, so smallest is
+            // closest to that budget + cheapest.  Device-agnostic: any
+            // device's 4:3 image is chosen, then normalised by the downscale
+            // guard in YuvImageConverter.  Trade-off: the 16:9 preview texture
+            // shows less than the 4:3 capture (accepted for max FOV).
+            val chosen = configs.sortedWith(
                 compareBy<CameraConfig> { kotlin.math.abs(aspect(it.imageSize) - 4f / 3f) }
-                    .thenByDescending { it.imageSize.width * it.imageSize.height },
+                    .thenBy { it.imageSize.width * it.imageSize.height },
             ).firstOrNull() ?: return
             session.setCameraConfig(chosen)
             Log.i(
                 TAG,
-                "selectMatchingCameraConfig: chose image=" +
+                "selectMatchingCameraConfig: chose 4:3-pref image=" +
                     "${chosen.imageSize.width}x${chosen.imageSize.height} texture=" +
                     "${chosen.textureSize.width}x${chosen.textureSize.height} " +
-                    "(from ${configs.size} configs, ${matched.size} aspect-matched)",
+                    "(from ${configs.size} configs)",
             )
         } catch (t: Throwable) {
             Log.w(TAG, "selectMatchingCameraConfig failed; keeping default config: ${t.message}")

package/android/src/main/java/io/imagestitcher/rn/ar/YuvImageConverter.kt

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 package io.imagestitcher.rn.ar
 
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
 import android.graphics.ImageFormat
 import android.graphics.Rect
 import android.graphics.YuvImage
@@ -10,6 +12,14 @@ import androidx.exifinterface.media.ExifInterface
 import java.io.ByteArrayOutputStream
 import java.io.File
 import java.io.FileOutputStream
+import kotlin.math.max
+import kotlin.math.roundToInt
+
+/** AR keyframe long-edge budget (px).  Every device's acquired AR frame is
+ *  downscaled to this before the keyframe JPEG is written, so the stitch
+ *  held-set (and thus memory) is consistent across devices regardless of
+ *  their ARCore 4:3 image resolution.  Matches the non-AR keyframe size. */
+private const val AR_KEYFRAME_MAX_LONG_EDGE = 640
 
 /**
  * Convert an ARCore `Image` (YUV_420_888) to a JPEG file on disk.
@@ -221,8 +231,36 @@ internal object YuvImageConverter {
             baos,
         )
         if (!ok) return null
+        // AR keyframe downscale guard — normalise the long edge to
+        // AR_KEYFRAME_MAX_LONG_EDGE so every device (whatever its ARCore 4:3
+        // image resolution) writes the same ~0.3 MP keyframe -> consistent
+        // stitch memory cross-device.  Only the SAVED keyframe is scaled; the
+        // C++ keyframe gate already ran on the full-res Y plane upstream.
+        var jpegBytes = baos.toByteArray()
+        if (max(packed.width, packed.height) > AR_KEYFRAME_MAX_LONG_EDGE) {
+            val src = BitmapFactory.decodeByteArray(jpegBytes, 0, jpegBytes.size)
+            if (src != null) {
+                val scale =
+                    AR_KEYFRAME_MAX_LONG_EDGE.toFloat() / max(src.width, src.height)
+                val dst = Bitmap.createScaledBitmap(
+                    src,
+                    (src.width * scale).roundToInt().coerceAtLeast(1),
+                    (src.height * scale).roundToInt().coerceAtLeast(1),
+                    true,
+                )
+                val baos2 = ByteArrayOutputStream()
+                dst.compress(
+                    Bitmap.CompressFormat.JPEG,
+                    jpegQuality.coerceIn(1, 100),
+                    baos2,
+                )
+                jpegBytes = baos2.toByteArray()
+                if (dst !== src) dst.recycle()
+                src.recycle()
+            }
+        }
         try {
-            FileOutputStream(File(outputPath)).use { it.write(baos.toByteArray()) }
+            FileOutputStream(File(outputPath)).use { it.write(jpegBytes) }
         } catch (e: Throwable) {
             return null
         }