react-native-image-stitcher 0.16.0 → 0.16.2

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

@@ -633,7 +633,8 @@ class IncrementalStitcher(
         val wasBatchKeyframe = batchKeyframeMode
         val keyframePathsSnapshot = batchKeyframePaths.toList()
         val captureOrientationSnapshot = batchCaptureOrientation
-        val warperTypeSnapshot = batchWarperType
+        // batchWarperType (settings) is superseded by the high-level warper tree
+        // (pickHighLevelWarper) below — kept as a field for back-compat, unused here.
         val blenderTypeSnapshot = batchBlenderType
         val seamFinderTypeSnapshot = batchSeamFinderType
         val useInscribedRectCropSnapshot = batchUseInscribedRectCrop
@@ -664,11 +665,31 @@ class IncrementalStitcher(
         // falls back to pose data only.  Always non-negative.
         val imuTranslationMetres = (options.getDoubleOrDefault("imuTranslationMetres", 0.0) ?: 0.0)
             .coerceAtLeast(0.0)
+        // Resolve once so the dev readout gets the SAME tMeters / ratio / rRadians
+        // that drove the decision — and gets them even when the mode was forced
+        // (informative: shows what auto WOULD have picked).
+        val autoResolution = resolveStitchModeAuto(firstPose, lastPose, imuTranslationMetres)
         val stitchModeResolved: String = when (batchStitchMode) {
             "panorama" -> "panorama"
             "scans"    -> "scans"
-            else -> resolveStitchModeAuto(firstPose, lastPose, imuTranslationMetres)
+            else -> autoResolution.mode
         }
+        // Surface the gyro rotation + translation + decision ratio for EVERY
+        // capture (the forced modes skip the auto decision, but the dev preview
+        // still reads these to tune the panorama-vs-SCANS threshold).
+        val rRadiansResolved: Double = autoResolution.rRadians
+        val tMetersResolved: Double = autoResolution.tMeters
+        val decisionRatioResolved: Double = autoResolution.ratio
+        // 2026-06-16 — HIGH-LEVEL ACROSS THE BOARD.  Pick the warper from the
+        // (motion, Mode A/B, zoom) tree and always run cv::Stitcher PANORAMA
+        // (useManualPipeline=false at the stitchSync call below).  stitchModeResolved
+        // is now only the MOTION classifier feeding the tree + the dev readout;
+        // the actual stitch mode is always panorama.  Zoom comes from the EXPLICIT
+        // lens label the user selected ('1x'|'0.5x') — the reliable signal (FOV
+        // from intrinsics was unreliable: multi-cam 0.5x doesn't change fx, and
+        // the non-AR path may supply fx=0 → FOV defaulted to 65° → never 0.5x).
+        val lensOpt = options.getString("lens") ?: "1x"
+        val highLevelWarper = pickHighLevelWarper(captureOrientationSnapshot, lensOpt)
         android.util.Log.i(
             "IncrementalStitcher",
             "finalize stitch-mode: configured=$batchStitchMode resolved=$stitchModeResolved " +
@@ -714,12 +735,13 @@ class IncrementalStitcher(
                         keyframePathsSnapshot.toTypedArray(),
                         outputPath,
                         quality,
-                        warperTypeSnapshot,
+                        highLevelWarper,                 // tree-chosen (was batchWarperType)
                         blenderTypeSnapshot,
                         seamFinderTypeSnapshot,
                         captureOrientationSnapshot,
                         useInscribedRectCropSnapshot,
-                        stitchMode = stitchModeResolved,
+                        stitchMode = "panorama",         // always high-level PANORAMA
+                        useManualPipeline = false,       // high level across the board
                     )
                     // 2026-05-15 (D) — dims layout from native JNI:
                     //   [0] width, [1] height, [2] framesRequested,
@@ -748,6 +770,11 @@ class IncrementalStitcher(
                     // resolved cv::Stitcher mode so JS can surface it
                     // on the output preview + debug toast.
                     map.putString("stitchModeResolved", stitchModeResolved)
+                    map.putDouble("rRadians", rRadiansResolved)
+                    // Dev tuning readout — translation magnitude + the auto
+                    // decision ratio that drove panorama-vs-SCANS.
+                    map.putDouble("tMeters", tMetersResolved)
+                    map.putDouble("decisionRatio", decisionRatioResolved)
                     // 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
@@ -875,36 +902,13 @@ class IncrementalStitcher(
         grayHeight: Int,
         grayStride: Int,
         onAccept: (targetPath: String) -> Boolean,
-        // 2026-05-21 (v0.3) — only required when batchKeyframeMode
-        // is false (the legacy hybrid/firstwins live-engine path,
-        // which feeds JPEG paths into addFrameAtPath for each ARCore
-        // frame).  Pass null when batchKeyframeMode is true; the
-        // batch path uses `grayData` + `onAccept` instead.  Modern
-        // callers prefer `nv21PixelData` below — `legacyJpegPath` is
-        // kept only as a defensive fallback for older call sites
-        // that have not yet been migrated.
-        legacyJpegPath: String? = null,
-        // F8.6 — pixel-data path for live engines.  When supplied
-        // (and `batchKeyframeMode == false`), takes precedence over
-        // `legacyJpegPath`: the live engine ingests via
-        // `addFramePixelData` (NV21 → BGR Mat in-process) instead of
-        // `addFrameAtPath` (JPEG decode round-trip).  Saves ~30-50 ms
-        // per accepted frame on a mid-tier device.  Pass null to use
-        // the legacy JPEG path.
-        //
-        // OWNERSHIP: wrapped in `TransferredNV21` (audit #4A,
-        // v0.10.0).  The wrapper enforces single-use: the engine
-        // calls `.takeOnce()` on the producer thread before
-        // dispatching to `workScope`; subsequent attempts to extract
-        // the bytes throw.  Callers MUST construct a fresh
-        // `TransferredNV21` per frame and MUST NOT hand the same
-        // instance to two consumers (e.g., a sync gate-eval + an
-        // async workScope.launch).  The Frame Processor plugin and
-        // the AR camera view both allocate fresh NV21 arrays per
-        // frame; the wrapper is a defensive-programming guard.
-        nv21PixelData: TransferredNV21? = null,
-        nv21PixelWidth: Int = 0,
-        nv21PixelHeight: Int = 0,
+        // 2026-06-16 (audit #8/L3) — the live-engine ingest params
+        // (legacyJpegPath / nv21PixelData / nv21PixelWidth/Height) were
+        // removed here.  The live engines were archived in 2026-06, so the
+        // only remaining path is batch-keyframe (always on), which ingests via
+        // `grayData` + `onAccept`.  The TransferredNV21 ownership wrapper had no
+        // live consumer (takeOnce() called nowhere — verified by grep) and is
+        // deleted along with these params.
     ) {
         // ── V16 batch-keyframe: AR-driven path ─────────────────────
         //
@@ -1213,21 +1217,6 @@ class IncrementalStitcher(
             grayWidth = width,
             grayHeight = height,
             grayStride = yRowStride,
-            // F8.6 — pass the already-packed NV21 so the live
-            // engine branch (hybrid / firstwins) can ingest via
-            // `addFramePixelData` instead of JPEG-decoding a
-            // separately-written path.  Batch-keyframe mode
-            // ignores these (it uses `grayData` + `onAccept`).
-            //
-            // v0.10.0 audit #4A — wrap in TransferredNV21 so the
-            // engine takes ownership exactly once on the producer
-            // thread (engine calls `.takeOnce()` before workScope).
-            // Misuse (handing this same instance to two consumers)
-            // throws at the second `.takeOnce()` site, not silently
-            // corrupting frames.
-            nv21PixelData = TransferredNV21(nv21Bytes),
-            nv21PixelWidth = width,
-            nv21PixelHeight = height,
             onAccept = { targetPath ->
                 // Synchronous JPEG encode via the existing
                 // YuvImageConverter (also used by RNSARCameraView's
@@ -1737,6 +1726,33 @@ class IncrementalStitcher(
         }
     }
 
+    /**
+     * Total physical RAM in MB.  Lets the DEV memory pill derive RAM-aware
+     * pressure bands instead of the iPhone-fixed 1500/2200 MB thresholds (which
+     * never trip on a 4 GB Android phone that jetsams ~1.3 GB — false comfort).
+     * Reads `_SC_PHYS_PAGES × _SC_PAGE_SIZE` (TOTAL + stable across runs, unlike
+     * the rate-limited ActivityManager path).  -1.0 on failure.
+     */
+    @ReactMethod
+    fun getDeviceTotalRamMB(promise: Promise) {
+        try {
+            val pages = android.system.Os.sysconf(android.system.OsConstants._SC_PHYS_PAGES)
+            val pageSize =
+                android.system.Os.sysconf(android.system.OsConstants._SC_PAGESIZE)
+            if (pages <= 0 || pageSize <= 0) {
+                promise.resolve(-1.0)
+                return
+            }
+            promise.resolve(pages.toDouble() * pageSize.toDouble() / (1024.0 * 1024.0))
+        } catch (t: Throwable) {
+            android.util.Log.w(
+                "IncrementalStitcher",
+                "getDeviceTotalRamMB: failed: ${t.message}",
+            )
+            promise.resolve(-1.0)
+        }
+    }
+
     /**
      * Release the C++ KeyframeGate heap allocation when RN tears
      * down the bridge module (e.g. on a JS reload).  Without this,
@@ -1928,6 +1944,24 @@ class IncrementalStitcher(
      *
      * Returns "panorama" or "scans" — never "auto".
      */
+    /**
+     * Result of [resolveStitchModeAuto]: the chosen mode PLUS the gyro rotation
+     * magnitude that drove the decision.  rRadians is surfaced to JS (the dev
+     * 3-tab preview shows it) so the panorama-vs-SCANS rotation threshold can be
+     * tuned from real captures.  rRadians is 0.0 only on the no-pose fallbacks
+     * (non-AR with no pose data) — there is no gyro-derived rotation to report.
+     */
+    private data class StitchModeResolution(
+        val mode: String,
+        val rRadians: Double,
+        // tMeters = translation magnitude (m) that fed the ratio; ratio = the
+        // tScore/(tScore+rScore) decision value (>=0.55 → SCANS). Surfaced to the
+        // dev readout so the panorama-vs-SCANS threshold can be tuned from real
+        // captures, alongside rRadians.
+        val tMeters: Double,
+        val ratio: Double,
+    )
+
     private fun resolveStitchModeAuto(
         firstPose: DoubleArray?,
         lastPose: DoubleArray?,
@@ -1935,14 +1969,16 @@ class IncrementalStitcher(
         // translation in METRES.  Used as a fallback when pose-derived
         // translation is 0 (non-AR mode).
         imuTranslationMetres: Double = 0.0,
-    ): String {
+    ): StitchModeResolution {
         if (firstPose == null || lastPose == null) {
             // No pose data at all — fall back on the IMU signal.  IMU
             // > 5 cm hints SCANS; everything else hints PANORAMA.
-            return if (imuTranslationMetres > 0.05) "scans" else "panorama"
+            return StitchModeResolution(
+                if (imuTranslationMetres > 0.05) "scans" else "panorama", 0.0, 0.0, 0.0)
         }
         if (firstPose.size != 7 || lastPose.size != 7) {
-            return if (imuTranslationMetres > 0.05) "scans" else "panorama"
+            return StitchModeResolution(
+                if (imuTranslationMetres > 0.05) "scans" else "panorama", 0.0, 0.0, 0.0)
         }
 
         // Translation magnitude (Euclidean, in metres) — pose-derived.
@@ -1962,11 +1998,7 @@ class IncrementalStitcher(
         // conventions; rotated by the pose quaternion gives the world-
         // frame forward direction.  Angle between the first and last
         // camera-forward vectors is the total rotation around any axis.
-        val fwdFirst = qrotForward(firstPose[3], firstPose[4], firstPose[5], firstPose[6])
-        val fwdLast = qrotForward(lastPose[3], lastPose[4], lastPose[5], lastPose[6])
-        val dot = (fwdFirst[0] * fwdLast[0] + fwdFirst[1] * fwdLast[1] + fwdFirst[2] * fwdLast[2])
-            .coerceIn(-1.0, 1.0)
-        val rRadians = kotlin.math.acos(dot)
+        val rRadians = rotationRadians(firstPose, lastPose)
 
         // Normalisation: 10 cm of translation ≈ 1 rad of rotation as
         // "equivalent magnitude" for the ratio.  Empirically: shelf
@@ -1977,7 +2009,7 @@ class IncrementalStitcher(
         val tScore = tMeters / 0.10
         val rScore = rRadians / 1.00
         val denom = tScore + rScore
-        if (denom <= 1e-9) return "panorama"  // no motion either way
+        if (denom <= 1e-9) return StitchModeResolution("panorama", rRadians, tMeters, 0.0)  // no motion
         val ratio = tScore / denom
 
         // 2026-06-15 — LOW-ROTATION GUARD.  The gyro rotation (rRadians) is
@@ -2000,7 +2032,51 @@ class IncrementalStitcher(
                 "ratio=${"%.3f".format(ratio)} " +
                 "rotGuard=$lowRotationGuard → $mode",
         )
-        return mode
+        return StitchModeResolution(mode, rRadians, tMeters, ratio)
+    }
+
+    /**
+     * 2026-06-16 — high-level warper decision tree (the pipeline is now ALWAYS
+     * high-level cv::Stitcher PANORAMA — useManualPipeline=false).  Warper is a
+     * pure function of (lens, pan direction); the rotation-vs-translation
+     * (ex-SCANS) distinction was DROPPED as redundant — at 1x the same
+     * direction-based warpers serve both, and 0.5x is always spherical.  Inputs:
+     *   orientation = capture hold ("landscape*" = Mode A vertical pan;
+     *                 "portrait*" = Mode B horizontal pan)
+     *   lens        = the EXPLICIT lens the user selected ("0.5x" ultra-wide |
+     *                 "1x" wide).  Reliable zoom signal (FOV-from-intrinsics was
+     *                 unreliable — multi-cam 0.5x reaches the ultra-wide by zoom
+     *                 without changing fx, and the non-AR path may supply fx=0).
+     *
+     *     0.5x ultra-wide          → spherical   (bounded both axes; any pan)
+     *     1x + Mode A (vertical)   → plane
+     *     1x + Mode B (horizontal) → cylindrical
+     *
+     * Quality-preferred warper; the C++ memory ladder force-falls to spherical
+     * (and downscales compositingResol) under pressure.
+     */
+    private fun pickHighLevelWarper(
+        orientation: String,
+        lens: String,
+    ): String {
+        if (lens == "0.5x") return "spherical"                // ultra-wide → always spherical
+        val verticalPanModeA = orientation.startsWith("landscape")
+        return if (verticalPanModeA) "plane" else "cylindrical"  // 1x: A→plane, B→cylindrical
+    }
+
+    /**
+     * Gyro rotation magnitude (radians) between two 7-element poses
+     * `[tx,ty,tz,qx,qy,qz,qw]` — the angle between the camera-forward vectors.
+     * Returns 0.0 if either pose is missing/malformed (non-AR with no pose).
+     * Shared by [resolveStitchModeAuto] and the finalize `rRadians` readout (DRY).
+     */
+    private fun rotationRadians(firstPose: DoubleArray?, lastPose: DoubleArray?): Double {
+        if (firstPose == null || lastPose == null) return 0.0
+        if (firstPose.size != 7 || lastPose.size != 7) return 0.0
+        val f = qrotForward(firstPose[3], firstPose[4], firstPose[5], firstPose[6])
+        val l = qrotForward(lastPose[3], lastPose[4], lastPose[5], lastPose[6])
+        val dot = (f[0] * l[0] + f[1] * l[1] + f[2] * l[2]).coerceIn(-1.0, 1.0)
+        return kotlin.math.acos(dot)
     }
 
     /**

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

@@ -612,26 +612,13 @@ class RNSARCameraView @JvmOverloads constructor(
         val rotationForEncode = if (lastDisplayRotation >= 0)
             lastDisplayRotation else android.view.Surface.ROTATION_0
 
-        // F8.6 (v0.6) — the eager JPEG encode for live-engine mode
-        // is gone.  Pass the already-packed NV21 directly via
-        // `nv21PixelData`; the engine's new `addFramePixelData`
-        // path builds the BGR cv::Mat in-process via cvtColor,
-        // skipping the JPEG decode round-trip downstream.  In
-        // batch-keyframe mode the engine ignores `nv21PixelData`
-        // (it uses `grayData` + `onAccept` lazily); no behaviour
-        // change there.
-        //
-        // (Was: eager JPEG encode for non-batch-keyframe modes,
-        //  written to `tmpJpegFile`, passed as `legacyJpegPath`.
-        //  See the v0.3 / F8.6 entries in CHANGELOG.md.)
-        //
-        // Synchronous engine ingest.  The ARCore Image ownership
-        // contract requires the engine to consume the TransferredNV21
-        // before ARCore recycles the Image, so this runs inline.  Only
-        // ingest when the host has actively engaged capture
-        // (`setIncrementalIngestionActive(true)`).  (The v0.8.0 worklet-
-        // runtime `runFirstParty` indirection + host-worklet fan-out
-        // were archived in the 2026-06 batch-keyframe cleanup.)
+        // Batch-keyframe ingest.  The gate reads the Y plane of the packed
+        // NV21 synchronously (grayData) and the lazy onAccept JPEG-encodes only
+        // accepted frames — no eager encode, no live-engine pixel-data path
+        // (the live engines + the TransferredNV21 ownership wrapper were removed
+        // in the 2026-06 cleanup; see audit #8).  Runs inline so the gate read
+        // completes before ARCore recycles the Image.  Only ingest when the host
+        // has actively engaged capture (`setIncrementalIngestionActive(true)`).
         if (ingestActive) {
         module.ingestFromARCameraView(
             tx = tArr[0].toDouble(),
@@ -654,22 +641,6 @@ class RNSARCameraView @JvmOverloads constructor(
             grayWidth = packed.width,
             grayHeight = packed.height,
             grayStride = packed.width,
-            legacyJpegPath = null,
-            // F8.6 — pixel-data path for live engines.  Batch-
-            // keyframe mode ignores these (bails earlier).
-            //
-            // v0.10.0 audit #4A — wrap `packed.nv21` in
-            // TransferredNV21 so ownership is enforced at runtime.
-            // The AR caller passes the SAME `packed.nv21` array as
-            // both `grayData` (sync, gate-eval read) and
-            // `nv21PixelData` (async, engine ingest).  Today no race
-            // because grayData is consumed inside evaluateWithFrame
-            // before workScope.launch fires; the wrapper makes a
-            // future refactor that reorders consumption fail loudly
-            // instead of silently corrupting frames.
-            nv21PixelData = TransferredNV21(packed.nv21),
-            nv21PixelWidth = packed.width,
-            nv21PixelHeight = packed.height,
             onAccept = { targetPath ->
                 // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
                 // accepted the frame.  Encodes from the pre-packed

package/cpp/keyframe_gate.cpp

@@ -356,6 +356,11 @@ struct KeyframeGate::Impl {
     // the downscale factor.  Re-set whenever prevFrameGrayWork is.
     int32_t                     prevFrameOrigWidth  = 0;
     int32_t                     prevFrameOrigHeight = 0;
+    // 2026-06-16 (audit #4) — the CURRENT frame's downscaled working image,
+    // produced by ingestWorkingFrame() (under the JNI pin) and consumed by
+    // evaluateWithWorkingMat() (after the pin is released).  Empty unless an
+    // ingest is pending.  Owned (downscaleToWorking clones / resizes).
+    cv::Mat                     pendingWorkMat;
 };
 
 // Compile-time layout check on the shared POD struct — ensures iOS
@@ -750,6 +755,45 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
     int32_t height,
     int32_t stride,
     int64_t monotonicNowMs)
+{
+    // 2026-06-16 (audit #4) — thin wrapper = ingest (reads pixels) + evaluate.
+    // Kept for iOS / non-pinned callers; the Android JNI calls the two halves
+    // separately so the heavy OpenCV runs OUTSIDE the GC-pinned critical region.
+    ingestWorkingFrame(grayData, width, height, stride);
+    return evaluateWithWorkingMat(pose, latchedPlane, width, height, monotonicNowMs);
+}
+
+void KeyframeGate::ingestWorkingFrame(
+    const uint8_t* grayData,
+    int32_t width,
+    int32_t height,
+    int32_t stride)
+{
+    Impl& s = *pImpl_;
+    s.pendingWorkMat.release();
+    // Only the Flow strategy reads pixels; disabled / force-accept / Pose ignore
+    // them (the Pose path is deliberately OpenCV-free).  For those — and for
+    // invalid input — stash nothing; evaluateWithWorkingMat short-circuits
+    // without a frame.  This is the ONLY step that touches `grayData`, so the
+    // JNI can ReleasePrimitiveArrayCritical immediately after it returns.
+    if (!s.enabled || s.forceAcceptNext || s.strategy != GateStrategy::Flow
+        || grayData == nullptr || width <= 0 || height <= 0 || stride < width) {
+        return;
+    }
+    // Non-owning view over the (pinned) bytes; downscaleToWorking returns an
+    // OWNED Mat (clone or resize output), so it stays valid after the pin drops.
+    cv::Mat currGrayFull(height, width, CV_8UC1,
+                        const_cast<uint8_t*>(grayData),
+                        static_cast<size_t>(stride));
+    s.pendingWorkMat = downscaleToWorking(currGrayFull);
+}
+
+KeyframeGateDecision KeyframeGate::evaluateWithWorkingMat(
+    const Pose& pose,
+    const PlaneTransform* latchedPlane,
+    int32_t origWidth,
+    int32_t origHeight,
+    int64_t monotonicNowMs)
 {
     Impl& s = *pImpl_;
     // Stash the monotonic stamp (see evaluate()).  The Pose-strategy
@@ -785,19 +829,14 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
         return evaluate(pose, latchedPlane, s.currentNowMs);
     }
 
-    // Flow path — wrap incoming pixel data as a non-owning cv::Mat
-    // and downscale to working resolution.  The non-owning view is
-    // SAFE because we deep-copy (via clone) before storing on Impl.
-    if (grayData == nullptr || width <= 0 || height <= 0 || stride < width) {
-        // Defensive: caller forgot to supply image data despite
-        // strategy=Flow.  Fall back to pose path so we degrade
-        // gracefully rather than crashing on a null deref.
+    // Flow path — operate on the working frame ingestWorkingFrame() stashed.
+    // Empty ⇒ ingest declined (null/invalid grayData under Flow); fall back to
+    // the pose path so we degrade gracefully rather than deref a null frame.
+    cv::Mat currGrayWork = std::move(s.pendingWorkMat);
+    s.pendingWorkMat.release();
+    if (currGrayWork.empty()) {
         return evaluate(pose, latchedPlane, s.currentNowMs);
     }
-    cv::Mat currGrayFull(height, width, CV_8UC1,
-                        const_cast<uint8_t*>(grayData),
-                        static_cast<size_t>(stride));
-    cv::Mat currGrayWork = downscaleToWorking(currGrayFull);
 
     // §4 — first-frame accept under Flow.  No prev to track against;
     // we anchor here and detect features so subsequent frames have
@@ -811,8 +850,8 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
             s.flowMinDistance);
         s.prevFrameGrayWork = currGrayWork;  // clone-owned via downscale path
         s.prevFeatures      = std::move(features);
-        s.prevFrameOrigWidth  = width;
-        s.prevFrameOrigHeight = height;
+        s.prevFrameOrigWidth  = origWidth;
+        s.prevFrameOrigHeight = origHeight;
         s.lastAcceptedPose    = pose;
         s.lastAcceptSteadyMs  = s.currentNowMs;
         s.acceptedCount       = 1;
@@ -970,8 +1009,8 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
         s.flowMinDistance);
     s.prevFrameGrayWork = currGrayWork;   // owned via downscale's clone
     s.prevFeatures      = std::move(nextFeatures);
-    s.prevFrameOrigWidth  = width;
-    s.prevFrameOrigHeight = height;
+    s.prevFrameOrigWidth  = origWidth;
+    s.prevFrameOrigHeight = origHeight;
     s.lastAcceptedPose    = pose;
     s.lastAcceptSteadyMs  = s.currentNowMs;
     s.acceptedCount      += 1;

package/cpp/keyframe_gate.hpp

@@ -248,6 +248,39 @@ public:
                                            int32_t stride,
                                            int64_t monotonicNowMs = -1);
 
+    // ── Split entry point (2026-06-16, audit #4) ──────────────────
+    //
+    // Android JNI pins the gray byte[] with GetPrimitiveArrayCritical, which
+    // blocks the GC for the pin's whole duration.  Running the heavy OpenCV
+    // (goodFeaturesToTrack / optical flow, multi-ms) inside that window stalls
+    // the frame-rate producer thread and violates the JNI no-blocking-between-
+    // critical rule.  This pair splits the work so ONLY the pinned-buffer read
+    // happens under the pin:
+    //
+    //   ingestWorkingFrame(grayData, w, h, stride)   // <- under the pin
+    //       Builds the downscaled working frame (the only step that reads the
+    //       pinned pixels) and stashes it INSIDE the gate.  Does nothing (no
+    //       pixel read) for Pose/disabled/force-accept/invalid input — those
+    //       don't need the frame.  cv::Mat is kept out of this header so the
+    //       JNI needn't link OpenCV; the frame lives on the gate's Impl.
+    //
+    //   evaluateWithWorkingMat(pose, plane, origW, origH)   // <- pin released
+    //       Runs the rest of the gate (the heavy OpenCV) on the stashed working
+    //       frame, OUTSIDE the critical section.  origW/origH are the ORIGINAL
+    //       full-res dims (the working frame is downscaled).
+    //
+    // evaluateWithFrame() above is exactly ingest+evaluate in sequence — kept
+    // for iOS and any non-pinned caller (DRY: it delegates to these two).
+    void ingestWorkingFrame(const uint8_t* grayData,
+                            int32_t width,
+                            int32_t height,
+                            int32_t stride);
+    KeyframeGateDecision evaluateWithWorkingMat(const Pose& pose,
+                                                const PlaneTransform* latchedPlane,
+                                                int32_t origWidth,
+                                                int32_t origHeight,
+                                                int64_t monotonicNowMs = -1);
+
     // ── State accessors (read-only, post-evaluate) ────────────────
     int32_t getAcceptedCount() const;
     int32_t getMaxCount() const;