react-native-image-stitcher 0.4.1 → 0.5.1

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

@@ -36,6 +36,7 @@ import org.opencv.features2d.ORB
 import org.opencv.imgcodecs.Imgcodecs
 import org.opencv.imgproc.Imgproc
 import java.io.File
+import io.imagestitcher.rn.ar.YuvImageConverter
 import java.util.concurrent.atomic.AtomicBoolean
 
 /**
@@ -76,6 +77,13 @@ class IncrementalStitcher(
     private val reactContext: ReactApplicationContext,
 ) : ReactContextBaseJavaModule(reactContext) {
 
+    // F8.4 note: the static singleton accessor for cross-thread
+    // lookup (used by `CvFlowGateFrameProcessor` running on vision-
+    // camera's producer thread) is the existing `bridgeInstance`
+    // companion field below — same pattern that `RNSARCameraView`
+    // uses to call back into the bridge.  No new companion object
+    // needed.
+
     override fun getName(): String = "IncrementalStitcher"
 
     /// Required by RCTEventEmitter contract.  No-op on Android because
@@ -217,6 +225,26 @@ class IncrementalStitcher(
     private var consumeFrameCounter: Long = 0L
 
     private val isRunning = AtomicBoolean(false)
+
+    /// F8.4 — gate for `consumeFrameFromPlugin` (the vision-camera
+    /// Frame Processor producer-thread entry point on Android).
+    /// TRUE only when the current capture was started with
+    /// `frameSourceMode == "frameProcessor"`.  In other modes
+    /// (especially the legacy `"jsDriver"` path that feeds via
+    /// `processFrameAtPath`), the plugin would double-feed the
+    /// engine — bytes from the producer thread + JPEG paths from
+    /// the JS interval, racing on the same workScope serial
+    /// dispatcher — so we drop the producer-thread call.
+    ///
+    /// AtomicBoolean: producer thread reads lock-free, JS thread
+    /// (start/cancel/finalize) writes via `set()`/`compareAndSet()`.
+    /// Mirror of iOS' `frameProcessorIngestEnabled` ivar.
+    private val frameProcessorIngestEnabled = AtomicBoolean(false)
+
+    /// F8.6 perf-diagnostic — one-shot guard so the "live-engine
+    /// route" log fires exactly once per capture session.  Reset
+    /// in start().
+    private val f8_6_routeLoggedThisCapture = AtomicBoolean(false)
     /// Critic #5 fix: serial dispatcher so concurrent
     /// processFrameAtPath() calls can't race on the engine's canvas.
     /// `limitedParallelism(1)` guarantees one-at-a-time execution
@@ -301,6 +329,18 @@ class IncrementalStitcher(
         }
         try {
             ensureOpenCv()
+            // F8.4 — frameSourceMode honoured on Android.  Pre-F8.4,
+            // Android ignored this option (only iOS interpreted it).
+            // Now `"frameProcessor"` unlocks `consumeFrameFromPlugin`'s
+            // producer-thread ingest path; everything else (the
+            // implicit default + the legacy `"jsDriver"`) keeps the
+            // ingest path dormant so the existing `processFrameAtPath`
+            // / ARCore paths run unmodified.
+            val frameSourceMode = options.getString("frameSourceMode") ?: "jsDriver"
+            frameProcessorIngestEnabled.set(frameSourceMode == "frameProcessor")
+            // F8.6 perf-diagnostic — re-arm the route log for the
+            // new capture.
+            f8_6_routeLoggedThisCapture.set(false)
             val rotation = options.getIntOrDefault("frameRotationDegrees", 90)
             val composeW = options.getIntOrDefault("composeWidth",  960)
             val composeH = options.getIntOrDefault("composeHeight", 720)
@@ -548,6 +588,7 @@ class IncrementalStitcher(
             promise.resolve(map)
         } catch (t: Throwable) {
             isRunning.set(false)
+            frameProcessorIngestEnabled.set(false)  // F8.4 — symmetric clear on error path
             promise.reject("incremental-start-failed", t.message, t)
         }
     }
@@ -935,6 +976,7 @@ class IncrementalStitcher(
         // bail at the re-check (see processFrameAtPath above).
         // Matches iOS V12.1 fix.
         isRunning.set(false)
+        frameProcessorIngestEnabled.set(false)  // F8.4 — cut producer-thread ingest at finalize
 
         // V16 batch-keyframe finalize: snapshot the keyframe state
         // synchronously under the same "stop ingestion before
@@ -1133,6 +1175,7 @@ class IncrementalStitcher(
         // iOS V12.1 cancel path.
         arCameraViewRef?.setIncrementalIngestionActive(false)
         isRunning.set(false)
+        frameProcessorIngestEnabled.set(false)  // F8.4 — cut producer-thread ingest at cancel
         val hybrid = engine
         val firstwins = firstwinsEngine
         engine = null
@@ -1227,6 +1270,24 @@ class IncrementalStitcher(
         // can check `isBatchKeyframeMode` to elide the per-frame
         // JPEG encode for the batch path.
         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: the engine retains a reference to `nv21PixelData`
+        // until `workScope`'s coroutine consumes it (~50 ms later).
+        // Callers MUST treat the array as transferred — do not
+        // mutate it or return it to a buffer pool after calling
+        // this method.  If a caller needs to recycle the buffer,
+        // pass `.copyOf()` (currently no caller does — the F8.4
+        // Frame Processor plugin allocates a fresh array per frame).
+        nv21PixelData: ByteArray? = null,
+        nv21PixelWidth: Int = 0,
+        nv21PixelHeight: Int = 0,
     ) {
         // ── V16 batch-keyframe: AR-driven path ─────────────────────
         //
@@ -1404,46 +1465,280 @@ class IncrementalStitcher(
         // we only get here when batchKeyframeMode == false.  Caller
         // (RNSARCameraView) was expected to supply legacyJpegPath in
         // that case — defensively drop the frame if it didn't.
-        val path = legacyJpegPath ?: run {
+        // F8.6 — prefer the pixel-data path when the caller supplied
+        // NV21 bytes (Frame Processor / refactored ARCore path),
+        // otherwise fall back to legacyJpegPath (un-migrated ARCore
+        // path).  At least one of them must be present; drop the
+        // frame defensively otherwise.
+        val hasPixelData = nv21PixelData != null
+            && nv21PixelWidth > 0
+            && nv21PixelHeight > 0
+        // F8.6 perf-diagnostic — log route choice once per capture
+        // so logcat shows whether the new pixel-data path is
+        // actually getting exercised.  Throttled to first-hit per
+        // capture (counter resets in start()/cancel()).
+        if (!f8_6_routeLoggedThisCapture.getAndSet(true)) {
+            android.util.Log.i(
+                "F8.6-route",
+                "ingestFromARCameraView live-engine route: "
+                + if (hasPixelData) "pixel-data (F8.6, no JPEG round-trip)"
+                  else "jpeg-path (legacy, JPEG decode round-trip)",
+            )
+        }
+        val path = if (hasPixelData) null else legacyJpegPath ?: run {
             android.util.Log.w(
                 "IncrementalStitcher",
                 "ingestFromARCameraView legacy: batchKeyframeMode=false " +
-                    "but legacyJpegPath is null — dropping frame.  " +
-                    "Caller should have encoded a JPEG when " +
+                    "but both legacyJpegPath and nv21PixelData are null — " +
+                    "dropping frame.  Caller should have encoded a JPEG " +
+                    "OR supplied NV21 pixel data when " +
                     "isBatchKeyframeMode == false.",
             )
             return
         }
         workScope.launch {
             val state: WritableMap? = if (firstwins != null) {
-                val tele = firstwins.addFrameAtPath(
-                    path = path,
-                    qx = qx, qy = qy, qz = qz, qw = qw,
-                    fx = fx, fy = fy, cx = cx, cy = cy,
-                    imageWidth = imageWidth, imageHeight = imageHeight,
-                    yaw = yaw, pitch = pitch,
-                    fovHorizDegrees = fovHorizDegrees,
-                    fovVertDegrees = fovVertDegrees,
-                    trackingPoor = trackingPoor,
-                )
+                val tele = if (hasPixelData) {
+                    firstwins.addFramePixelData(
+                        nv21 = nv21PixelData!!,
+                        nv21Width = nv21PixelWidth,
+                        nv21Height = nv21PixelHeight,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                } else {
+                    firstwins.addFrameAtPath(
+                        path = path!!,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                }
                 firstwins.snapshotIfDue(tele)
             } else {
-                val tele = hybrid!!.addFrameAtPath(
-                    path = path,
-                    qx = qx, qy = qy, qz = qz, qw = qw,
-                    fx = fx, fy = fy, cx = cx, cy = cy,
-                    imageWidth = imageWidth, imageHeight = imageHeight,
-                    yaw = yaw, pitch = pitch,
-                    fovHorizDegrees = fovHorizDegrees,
-                    fovVertDegrees = fovVertDegrees,
-                    trackingPoor = trackingPoor,
-                )
+                val tele = if (hasPixelData) {
+                    hybrid!!.addFramePixelData(
+                        nv21 = nv21PixelData!!,
+                        nv21Width = nv21PixelWidth,
+                        nv21Height = nv21PixelHeight,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                } else {
+                    hybrid!!.addFrameAtPath(
+                        path = path!!,
+                        qx = qx, qy = qy, qz = qz, qw = qw,
+                        fx = fx, fy = fy, cx = cx, cy = cy,
+                        imageWidth = imageWidth, imageHeight = imageHeight,
+                        yaw = yaw, pitch = pitch,
+                        fovHorizDegrees = fovHorizDegrees,
+                        fovVertDegrees = fovVertDegrees,
+                        trackingPoor = trackingPoor,
+                    )
+                }
                 hybrid.snapshotIfDue(tele)
             }
             emitState(state)
         }
     }
 
+    // ─── F8.4 — Frame Processor entry point ──────────────────────
+    //
+    // `consumeFrameFromPlugin` is the producer-thread ingress for
+    // the vision-camera Frame Processor plugin
+    // (`CvFlowGateFrameProcessor`).  It takes a live
+    // `android.media.Image` (held open by vision-camera for the
+    // duration of the plugin callback) plus pose primitives, and
+    // delegates to the existing `ingestFromARCameraView` after
+    // extracting the Y plane bytes and wiring an inline JPEG
+    // encoder for the on-accept lambda.
+    //
+    // ## Why this lives here (not on the plugin class)
+    //
+    // The plugin needs zero knowledge of the engine's internals
+    // (batchKeyframeMode, eval-throttling, plane-latching, etc.)
+    // — that's all in `ingestFromARCameraView`.  Mirroring iOS'
+    // `consumeFrameFromPlugin`, the wrapper just maps the public
+    // primitive contract to the existing engine entry point.
+    //
+    // ## Why pass `Image` (not just the Y bytes)
+    //
+    // The engine's `ingestFromARCameraView` uses Y-only for the
+    // keyframe gate.  But when the gate ACCEPTS, the host (us) is
+    // responsible for encoding the accepted frame as JPEG before
+    // `ingestFromARCameraView` returns.  YuvImage / NV21 needs the
+    // full Y + interleaved VU planes, so we keep the Image
+    // reachable through the lambda.  Image's lifetime is bounded
+    // by the plugin callback's return — vision-camera closes the
+    // ImageProxy automatically — so the encode MUST be synchronous.
+    //
+    // ## Threading
+    //
+    // Called on vision-camera's frame-processor thread (a single-
+    // thread executor).  `frameProcessorIngestEnabled` is read
+    // lock-free via AtomicBoolean.  `ingestFromARCameraView`
+    // dispatches the heavy engine work to `workScope` (serial),
+    // so producer-thread blocking is bounded to the synchronous
+    // gate evaluation + (on accept) JPEG encode — typically
+    // 5–10 ms reject, 30–50 ms accept on a mid-tier device.
+    fun consumeFrameFromPlugin(
+        image: android.media.Image,
+        tx: Double, ty: Double, tz: Double,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        timestampMs: Double,
+        trackingStateRaw: Int,
+        // F8.4-Android-c rotation fix: how many degrees the sensor
+        // data needs to be rotated CW to display upright.  Comes
+        // from vision-camera's `Frame.imageProxy.imageInfo.rotationDegrees`.
+        // Typically 90 for a portrait-held back camera on Samsung
+        // devices (sensor mounted 90° rotated from screen-up).
+        sensorRotationDegrees: Int,
+    ) {
+        // F8.4 — drop the call unless this capture was started in
+        // frameProcessor mode.  Otherwise the plugin would double-
+        // feed the engine alongside the legacy jsDriver /
+        // processFrameAtPath path.  See the flag's declaration
+        // for the full reasoning.  Mirrors iOS H1.
+        if (!frameProcessorIngestEnabled.get()) return
+
+        // F8.6 — pack the full NV21 (Y + interleaved VU) once,
+        // then reuse it for BOTH the gate's Y-plane read AND the
+        // live engine's pixel-data ingest.  Previously the plugin
+        // only extracted Y; the live engine then had to JPEG-decode
+        // a separately-encoded path to recover BGR colour.  Now we
+        // skip both round-trips: the packed NV21 → BGR cvtColor
+        // inside `addFramePixelData` produces the BGR Mat directly.
+        //
+        // YuvImageConverter.packNV21 is stride-aware and densely
+        // repacks Y (so the gate's `grayStride = grayWidth = width`
+        // works), then interleaves VU per the standard NV21 layout
+        // [Y...][VU...].  Returns null only on degenerate Images
+        // (closed mid-callback or non-YUV format).
+        val packed = io.imagestitcher.rn.ar.YuvImageConverter.packNV21(image)
+            ?: return
+        val width = packed.width
+        val height = packed.height
+        val nv21Bytes = packed.nv21
+        // The gate reads `grayHeight` rows of `grayWidth` pixels
+        // at stride=width starting from offset 0.  That's exactly
+        // the Y plane region of nv21Bytes — the gate naturally
+        // stops before the UV bytes start.  No need to slice into
+        // a separate ByteArray.
+        val yBytes = nv21Bytes
+        val yRowStride = width
+
+        // Compute derived params expected by the existing ingest
+        // API.  Quaternion-to-yaw/pitch follows the same convention
+        // useFrameProcessorDriver synthesises on JS (q_yaw * q_pitch).
+        //
+        //   yaw   = atan2(2(qw*qy + qx*qz), 1 - 2(qy² + qz²))
+        //   pitch = asin(clamp(2(qw*qx - qz*qy), -1, 1))
+        val yaw = kotlin.math.atan2(
+            2.0 * (qw * qy + qx * qz),
+            1.0 - 2.0 * (qy * qy + qz * qz),
+        )
+        val pitch = kotlin.math.asin(
+            (2.0 * (qw * qx - qz * qy)).coerceIn(-1.0, 1.0),
+        )
+
+        // FoV from intrinsics + dims.  fx == 0 is the "JS didn't
+        // supply" signal (the iOS wrapper has the same default);
+        // fall back to a 65°×50° estimate so the engine doesn't
+        // see NaN.
+        val fovHorizDegrees = if (fx > 0.0)
+            2.0 * kotlin.math.atan(width.toDouble() / (2.0 * fx)) * 180.0 / Math.PI
+        else 65.0
+        val fovVertDegrees = if (fy > 0.0)
+            2.0 * kotlin.math.atan(height.toDouble() / (2.0 * fy)) * 180.0 / Math.PI
+        else 50.0
+
+        // `2` == `.tracking` per the iOS RNSARTrackingState enum.
+        // Anything else maps to trackingPoor=true, routing the
+        // frame through the engine's degraded-tracking branches
+        // (failing closed; symmetric with iOS C2).
+        val trackingPoor = trackingStateRaw != 2
+
+        ingestFromARCameraView(
+            tx = tx, ty = ty, tz = tz,
+            qx = qx, qy = qy, qz = qz, qw = qw,
+            fx = fx, fy = fy, cx = cx, cy = cy,
+            imageWidth = width, imageHeight = height,
+            yaw = yaw, pitch = pitch,
+            fovHorizDegrees = fovHorizDegrees,
+            fovVertDegrees = fovVertDegrees,
+            trackingPoor = trackingPoor,
+            grayData = yBytes,
+            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`).
+            nv21PixelData = nv21Bytes,
+            nv21PixelWidth = width,
+            nv21PixelHeight = height,
+            onAccept = { targetPath ->
+                // Synchronous JPEG encode via the existing
+                // YuvImageConverter (also used by RNSARCameraView's
+                // ARCore path).  Reuses the NV21 already packed at
+                // the top of `consumeFrameFromPlugin` — F8.6 saves
+                // a duplicate packNV21 call here (the previous
+                // version repacked the live `image` inside the
+                // lambda).
+                //
+                // EXIF rotation is BAKED-AS-METADATA, not pixel-
+                // rotated.  cv::imread in the stitcher ignores EXIF
+                // by default (see BatchStitcher.applyExifOrientation),
+                // so the engine's stored `frameRotationDegrees` still
+                // governs how the cv::Mat is interpreted downstream.
+                // No double-rotation.
+                //
+                // Returning `true` tells the engine the keyframe was
+                // persisted; `false` tells it to drop the accept.
+                try {
+                    val displayRotation = when (sensorRotationDegrees) {
+                        0   -> android.view.Surface.ROTATION_90
+                        90  -> android.view.Surface.ROTATION_0
+                        180 -> android.view.Surface.ROTATION_270
+                        270 -> android.view.Surface.ROTATION_180
+                        else -> android.view.Surface.ROTATION_0
+                    }
+                    val outPath = YuvImageConverter.encodeJpegFromNV21(
+                        packed,
+                        targetPath,
+                        jpegQuality = 80,
+                        displayRotation = displayRotation,
+                    )
+                    outPath != null
+                } catch (e: Throwable) {
+                    android.util.Log.w(
+                        "IncrementalStitcher",
+                        "consumeFrameFromPlugin: JPEG encode failed for $targetPath: ${e.javaClass.simpleName}: ${e.message}",
+                        e,
+                    )
+                    false
+                }
+            },
+        )
+    }
+
     @ReactMethod
     fun getState(promise: Promise) {
         val state = firstwinsEngine?.lastState ?: engine?.lastState
@@ -1944,6 +2239,12 @@ class IncrementalStitcher(
             // Ignore — not critical at teardown.
         }
         captureSessionDir = null
+        // F8.4 — release the static back-pointer so the Frame
+        // Processor plugin sees a clean nil after bridge teardown.
+        // A new bridge will set it again via the init block.
+        if (bridgeInstance === this) {
+            bridgeInstance = null
+        }
         super.onCatalystInstanceDestroy()
     }
 
@@ -2334,7 +2635,114 @@ internal class IncrementalEngine(
         // See iOS' equivalent fix for the architectural rationale.
         val frame = downsampleToCompose(srcRaw)
         if (frame !== srcRaw) srcRaw.release()
+        val tele = addFrameMat(
+            frame,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+        f8_6_logPerf("hybrid/jpeg", t0, tele.outcome)
+        return tele
+    }
+
+    /**
+     * F8.6 — pixel-data twin of [addFrameAtPath].  Accepts the
+     * camera frame as an NV21 byte buffer instead of a JPEG file
+     * path; skips the JPEG decode round-trip.  See
+     * `IncrementalFirstwinsEngine.addFramePixelData` for the
+     * sibling implementation rationale.
+     */
+    fun addFramePixelData(
+        nv21: ByteArray,
+        nv21Width: Int,
+        nv21Height: Int,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        fovHorizDegrees: Double, fovVertDegrees: Double,
+        trackingPoor: Boolean,
+    ): FrameTelemetry {
+        val t0 = System.nanoTime()
+        if (trackingPoor) {
+            return FrameTelemetry(
+                FrameOutcome.SkippedTrackingPoor, -1.0, 0, 0.0, 0.0,
+                msSince(t0),
+            )
+        }
+        // F8.6 IS-1 — length guard; see
+        // `IncrementalFirstwinsEngine.addFramePixelData` for the
+        // failure-mode rationale.
+        val expectedBytes = nv21Width * nv21Height * 3 / 2
+        require(nv21.size >= expectedBytes) {
+            "addFramePixelData: nv21 buffer too small " +
+                "(${nv21.size} bytes < $expectedBytes for " +
+                "${nv21Width}x${nv21Height})"
+        }
+        val yuv = Mat(nv21Height + nv21Height / 2, nv21Width, CvType.CV_8UC1)
+        yuv.put(0, 0, nv21)
+        val srcRaw = Mat()
+        Imgproc.cvtColor(yuv, srcRaw, Imgproc.COLOR_YUV2BGR_NV21)
+        yuv.release()
+        if (srcRaw.empty()) {
+            return FrameTelemetry(
+                FrameOutcome.SkippedTrackingPoor, -1.0, 0, 0.0, 0.0,
+                msSince(t0),
+            )
+        }
+        val frame = downsampleToCompose(srcRaw)
+        if (frame !== srcRaw) srcRaw.release()
+        val tele = addFrameMat(
+            frame,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+        f8_6_logPerf("hybrid/pixel", t0, tele.outcome)
+        return tele
+    }
 
+    /**
+     * F8.6 perf-diagnostic counter (mirror of the firstwins one).
+     * Remove after v0.5.1 ships and the numbers are baked in.
+     */
+    @Volatile private var f8_6_perfCallCounter: Long = 0L
+    private fun f8_6_logPerf(
+        path: String,
+        t0Nanos: Long,
+        outcome: FrameOutcome,
+    ) {
+        val n = ++f8_6_perfCallCounter
+        if (n == 1L || n % 5L == 0L) {
+            android.util.Log.i(
+                "F8.6-perf",
+                "$path took ${msSince(t0Nanos)}ms outcome=$outcome (call #$n)",
+            )
+        }
+    }
+
+    /**
+     * F8.6 — the body extracted from [addFrameAtPath].  Takes a
+     * BGR `Mat` (already downsampled to compose dims) and runs the
+     * pose-driven homography paste pipeline.  Behaviour is
+     * identical to the pre-F8.6 `addFrameAtPath` — the body is a
+     * verbatim move.
+     */
+    private fun addFrameMat(
+        frame: Mat,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        fovHorizDegrees: Double, fovVertDegrees: Double,
+        t0: Long,
+    ): FrameTelemetry {
         // Build R_new from quaternion.
         val rNew = quaternionToRotationMat(qx, qy, qz, qw)
 

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

@@ -5,6 +5,7 @@ import com.facebook.react.ReactPackage
 import com.facebook.react.bridge.NativeModule
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.uimanager.ViewManager
+import com.mrousavy.camera.frameprocessors.FrameProcessorPluginRegistry
 
 /**
  * ReactPackage that registers the SDK's two native modules with
@@ -22,15 +23,72 @@ import com.facebook.react.uimanager.ViewManager
  * JS layer.
  */
 class RNImageStitcherPackage : ReactPackage {
+
+    companion object {
+        @Volatile
+        private var fpPluginRegistered = false
+
+        /**
+         * F8.4 — register the vision-camera Frame Processor plugin.
+         * Called lazily from `createNativeModules` (which fires
+         * AFTER the React bridge has booted, side-stepping the
+         * bridgeless TurboModule init race we'd hit if we did this
+         * in a class-level static initialiser).
+         *
+         * No-op when vision-camera isn't on the runtime classpath
+         * (the SDK doesn't hard-depend on it — consumers that don't
+         * use `<Camera>` don't pay the dep).  Catches
+         * `NoClassDefFoundError` defensively because the runtime
+         * classpath is what matters, not the compile-time one.
+         *
+         * Idempotent: guarded by `fpPluginRegistered` so a host
+         * with multiple React instances doesn't double-register
+         * (would throw "name already exists" from the registry).
+         */
+        @JvmStatic
+        @Synchronized
+        fun ensureFrameProcessorPluginRegistered() {
+            if (fpPluginRegistered) return
+            try {
+                FrameProcessorPluginRegistry.addFrameProcessorPlugin(
+                    "cv_flow_gate_process_frame",
+                ) { proxy, options ->
+                    CvFlowGateFrameProcessor(proxy, options)
+                }
+                fpPluginRegistered = true
+            } catch (e: NoClassDefFoundError) {
+                android.util.Log.i(
+                    "RNImageStitcherPackage",
+                    "vision-camera FrameProcessorPluginRegistry not on classpath — "
+                    + "skipping cv_flow_gate_process_frame plugin registration "
+                    + "(host app doesn't appear to use Frame Processors).",
+                )
+                fpPluginRegistered = true  // don't retry every package init
+            } catch (e: Throwable) {
+                android.util.Log.w(
+                    "RNImageStitcherPackage",
+                    "Failed to register cv_flow_gate_process_frame plugin: ${e.message}",
+                )
+                fpPluginRegistered = true
+            }
+        }
+    }
+
     override fun createNativeModules(
         reactContext: ReactApplicationContext,
-    ): List<NativeModule> = listOf(
-        QualityChecker(reactContext),
-        BatchStitcher(reactContext),
-        RNSARSession(reactContext),
-        IncrementalStitcher(reactContext),
-        FileBridge(reactContext),
-    )
+    ): List<NativeModule> {
+        // F8.4 — register the Frame Processor plugin here, after the
+        // bridge is fully booted.  See `ensureFrameProcessorPluginRegistered`
+        // for the rationale (vs. a class-load-time static init).
+        ensureFrameProcessorPluginRegistered()
+        return listOf(
+            QualityChecker(reactContext),
+            BatchStitcher(reactContext),
+            RNSARSession(reactContext),
+            IncrementalStitcher(reactContext),
+            FileBridge(reactContext),
+        )
+    }
 
     override fun createViewManagers(
         reactContext: ReactApplicationContext,