react-native-image-stitcher 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -16,6 +16,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] — 2026-05-23
+
+### Fixed
+- **ARCore Image hold time** (PR #15) — `forwardToIncremental` on
+  Android now packs the ARCore `Image` payload synchronously and
+  closes the image immediately, rather than holding it across the JNI
+  hand-off.  Eliminates the "ImageReader: maxImages exceeded" backlog
+  that throttled non-keyframe processing on the A35 at high pan
+  rates.
+
+### Tooling
+- **Example app Metro port pinned to 8082** (cherry-pick from
+  `feature/f8-frame-processor-yuv`).  Mirrored across
+  `example/metro.config.js`, `example/package.json` scripts,
+  `example/ios/RNImageStitcherExample/AppDelegate.swift`, and
+  `example/android/gradle.properties` to keep CLI builds, IDE
+  builds, and Gradle invocations consistent on machines where 8081
+  is already taken.
+
+### Internal
+- Lockfile sync after the v0.4.0 version bump (Podfile.lock spec
+  checksum + npm prune of transitive deps that had drifted from
+  branch experimentation).  No impact on consumers — example-app
+  tooling only.
+
 ## [0.4.0] — 2026-05-23
 
 ### v0.4 settings revamp (F10)

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

@@ -428,133 +428,146 @@ class RNSARCameraView @JvmOverloads constructor(
             }
             return
         }
-        try {
-            // 2026-05-21 (v0.3) — pixel-data path.  Pre-0.3 this code
-            // unconditionally encoded the YUV camera image to JPEG and
-            // wrote it to disk for EVERY ARCore frame at ~60 Hz (~25 ms
-            // per frame of JPEG encode + disk I/O on the GL render
-            // thread), regardless of whether the C++ KeyframeGate would
-            // accept it.  Now we extract the Y plane bytes (cheap
-            // memcpy from a DirectByteBuffer), feed them to the gate
-            // for proper Flow-strategy evaluation, and defer the JPEG
-            // encode + disk write to the `onAccept` lambda so it only
-            // runs on the rare frames the gate actually keeps
-            // (typically ~6 per capture).
-            //
-            // Y-plane extraction for ARCore's YUV_420_888 format:
-            // plane[0] is the luminance channel at full resolution,
-            // pixelStride=1, rowStride may equal width OR be padded.
-            // We pass rowStride as the C++ side's `stride` so the gate
-            // skips padding correctly.
-            val yPlane = image.planes[0]
-            val yBuffer = yPlane.buffer
-            val yStride = yPlane.rowStride
-            val yWidth = image.width
-            val yHeight = image.height
-            // Copy Y bytes into a JVM-side ByteArray.  Using
-            // duplicate() so we don't mutate the original buffer's
-            // position state (ARCore may have other readers).
-            // For 1920×1080 Y plane that's ~2 MB; on Galaxy A35 the
-            // memcpy itself is < 1 ms.  JNI side pins via
-            // GetPrimitiveArrayCritical so the byte[] stays a single
-            // copy through the entire frame's lifecycle.
-            val ySize = yStride * yHeight
-            val yBytes = ByteArray(ySize)
-            yBuffer.duplicate().apply { rewind() }.get(yBytes, 0, ySize)
-
-            // Compute yaw + pitch from the ARCore quaternion using
-            // the same convention the iOS Swift side uses (camera-
-            // forward in world space).  This keeps the two platforms
-            // numerically aligned for the FoV-overlap gate.
-            val q = camera.pose.rotationQuaternion  // x, y, z, w
-            val (yaw, pitch) = quaternionYawPitch(q)
-
-            // Both FoVs + the full quaternion + intrinsics go to the
-            // engine.  V6 pose-driven path uses (qx, qy, qz, qw, fx,
-            // fy, cx, cy, w, h) to compute the geometrically-exact
-            // homography.
-            val intrinsics = camera.imageIntrinsics
-            val fx = intrinsics.focalLength[0].toDouble()
-            val fy = intrinsics.focalLength[1].toDouble()
-            val cxIntr = intrinsics.principalPoint[0].toDouble()
-            val cyIntr = intrinsics.principalPoint[1].toDouble()
-            val w = intrinsics.imageDimensions[0].toDouble()
-            val h = intrinsics.imageDimensions[1].toDouble()
-            val fovHRad = 2.0 * atan(w / (2.0 * fx))
-            val fovVRad = 2.0 * atan(h / (2.0 * fy))
-            val fovHDeg = fovHRad * 180.0 / Math.PI
-            val fovVDeg = fovVRad * 180.0 / Math.PI
-
-            // ARCore quaternion comes back in (x, y, z, w) order.
-            val qarr = camera.pose.rotationQuaternion
-            // P3-F: also extract translation so the KeyframeGate's
-            // plane-based ray-projection can compute polygon overlap.
-            // Previously these were dropped, forcing the gate into
-            // angular-fallback even when a plane was latched.
-            val tArr = camera.pose.translation
-
-            val trackingPoor = camera.trackingState != TrackingState.TRACKING
-            val module = IncrementalStitcher.bridgeInstance ?: return
-            // 2026-05-15 (B3) — pass current display rotation so the
-            // encoded JPEG gets an EXIF orientation tag.  Captured into
-            // a local val so the lambda below closes over a primitive
-            // (avoids re-reading lastDisplayRotation if it shifts
-            // between gate-evaluate and lambda invocation).
-            val rotationForEncode = if (lastDisplayRotation >= 0)
-                lastDisplayRotation else android.view.Surface.ROTATION_0
-            // 2026-05-21 (v0.3) — eager JPEG encode is only needed when
-            // the engine is in the legacy hybrid/firstwins live-engine
-            // mode (which feeds JPEG paths into addFrameAtPath every
-            // frame).  In batch-keyframe mode (the production Camera
-            // component's path), the JPEG is encoded LAZILY inside
-            // the onAccept lambda below — only on the ~6 frames per
-            // capture that the C++ KeyframeGate actually keeps.
-            val legacyJpegPath: String? = if (module.isBatchKeyframeMode) {
-                null
-            } else {
-                YuvImageConverter.encodeToJpeg(
-                    image,
-                    tmpJpegFile.absolutePath,
-                    jpegQuality = 70,
-                    displayRotation = rotationForEncode,
-                )
+
+        // 2026-05-22 (audit follow-up #19) — minimise ARCore Image
+        // hold time.
+        //
+        // Pre-#19 the Image stayed open through the entire JNI
+        // ingest call AND any subsequent JPEG encode (~25 ms in
+        // legacy hybrid mode where every frame is encoded eagerly;
+        // ~25 ms in batch-keyframe mode for the ~5/60 frames the
+        // gate accepts).  At 60 Hz ARCore that meant the Image was
+        // held 25-30 ms per frame on accepts, starving the Camera2
+        // ImageReader's circular buffer pool and risking
+        // "BufferQueue has been abandoned" stalls.
+        //
+        // The fix is mechanical: pack the YUV planes into a
+        // JVM-side NV21 byte array (~3 ms), close the Image, and
+        // run all subsequent work (JNI ingest + JPEG encode) on
+        // the copied bytes.  ARCore Camera2 buffer pool stays
+        // healthier; latency-sensitive ARCore frames flow through
+        // their fixed pool instead of waiting on our JPEG path.
+        //
+        // The packed.nv21 array's first `width*height` bytes are
+        // the Y plane (densely packed, stride = width) — these go
+        // to the C++ gate as grayscale.  The full array is the
+        // input to YuvImageConverter.encodeJpegFromNV21 if the
+        // gate accepts (or if we're in legacy eager-encode mode).
+        val packed = try {
+            YuvImageConverter.packNV21(image)
+        } finally {
+            // Close ASAP — every microsecond reduces buffer-pool
+            // pressure on Camera2.  Even if packNV21 returns null
+            // (unsupported format), we still need to close.
+            try { image.close() } catch (_: Throwable) {}
+        } ?: run {
+            if (forwardLogTick % 30 == 1) {
+                Log.w(TAG, "forwardToIncremental: packNV21 returned null (unexpected format?)")
             }
-            module.ingestFromARCameraView(
-                tx = tArr[0].toDouble(),
-                ty = tArr[1].toDouble(),
-                tz = tArr[2].toDouble(),
-                qx = qarr[0].toDouble(), qy = qarr[1].toDouble(),
-                qz = qarr[2].toDouble(), qw = qarr[3].toDouble(),
-                fx = fx, fy = fy, cx = cxIntr, cy = cyIntr,
-                imageWidth = intrinsics.imageDimensions[0],
-                imageHeight = intrinsics.imageDimensions[1],
-                yaw = yaw, pitch = pitch,
-                fovHorizDegrees = fovHDeg, fovVertDegrees = fovVDeg,
-                trackingPoor = trackingPoor,
-                grayData = yBytes,
-                grayWidth = yWidth,
-                grayHeight = yHeight,
-                grayStride = yStride,
-                legacyJpegPath = legacyJpegPath,
-                onAccept = { targetPath ->
-                    // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
-                    // accepted the frame.  The ARCore Image is still open
-                    // at this point (we haven't reached `image.close()`
-                    // in the surrounding `finally` block yet), so the
-                    // encode reads raw camera pixels directly into a
-                    // JPEG at the final persistent path — no tmp file,
-                    // no second copy.
-                    YuvImageConverter.encodeToJpeg(
-                        image,
-                        targetPath,
-                        jpegQuality = 70,
-                        displayRotation = rotationForEncode,
-                    ) != null
-                },
+            return
+        }
+
+        // Compute yaw + pitch from the ARCore quaternion using
+        // the same convention the iOS Swift side uses (camera-
+        // forward in world space).  This keeps the two platforms
+        // numerically aligned for the FoV-overlap gate.  `camera`
+        // (and `camera.pose`) remain valid after image.close() —
+        // they're ARCore Frame metadata, not pixel buffers.
+        val q = camera.pose.rotationQuaternion  // x, y, z, w
+        val (yaw, pitch) = quaternionYawPitch(q)
+
+        // Both FoVs + the full quaternion + intrinsics go to the
+        // engine.  V6 pose-driven path uses (qx, qy, qz, qw, fx,
+        // fy, cx, cy, w, h) to compute the geometrically-exact
+        // homography.
+        val intrinsics = camera.imageIntrinsics
+        val fx = intrinsics.focalLength[0].toDouble()
+        val fy = intrinsics.focalLength[1].toDouble()
+        val cxIntr = intrinsics.principalPoint[0].toDouble()
+        val cyIntr = intrinsics.principalPoint[1].toDouble()
+        val w = intrinsics.imageDimensions[0].toDouble()
+        val h = intrinsics.imageDimensions[1].toDouble()
+        val fovHRad = 2.0 * atan(w / (2.0 * fx))
+        val fovVRad = 2.0 * atan(h / (2.0 * fy))
+        val fovHDeg = fovHRad * 180.0 / Math.PI
+        val fovVDeg = fovVRad * 180.0 / Math.PI
+
+        // ARCore quaternion comes back in (x, y, z, w) order.
+        val qarr = camera.pose.rotationQuaternion
+        // P3-F: also extract translation so the KeyframeGate's
+        // plane-based ray-projection can compute polygon overlap.
+        // Previously these were dropped, forcing the gate into
+        // angular-fallback even when a plane was latched.
+        val tArr = camera.pose.translation
+
+        val trackingPoor = camera.trackingState != TrackingState.TRACKING
+        val module = IncrementalStitcher.bridgeInstance ?: return
+        // 2026-05-15 (B3) — pass current display rotation so the
+        // encoded JPEG gets an EXIF orientation tag.  Captured into
+        // a local val so the lambda below closes over a primitive
+        // (avoids re-reading lastDisplayRotation if it shifts
+        // between gate-evaluate and lambda invocation).
+        val rotationForEncode = if (lastDisplayRotation >= 0)
+            lastDisplayRotation else android.view.Surface.ROTATION_0
+
+        // 2026-05-21 (v0.3) — eager JPEG encode is only needed when
+        // the engine is in the legacy hybrid/firstwins live-engine
+        // mode (which feeds JPEG paths into addFrameAtPath every
+        // frame).  In batch-keyframe mode (the production Camera
+        // component's path), the JPEG is encoded LAZILY inside
+        // the onAccept lambda below — only on the ~6 frames per
+        // capture that the C++ KeyframeGate actually keeps.
+        //
+        // 2026-05-22 (#19) — the encode now reads from the already-
+        // packed NV21 bytes (`packed`), NOT from the live Image
+        // (which has been closed above).  Same output, no Image
+        // hold time.
+        val legacyJpegPath: String? = if (module.isBatchKeyframeMode) {
+            null
+        } else {
+            YuvImageConverter.encodeJpegFromNV21(
+                packed,
+                tmpJpegFile.absolutePath,
+                jpegQuality = 70,
+                displayRotation = rotationForEncode,
             )
-        } finally {
-            image.close()
         }
+        module.ingestFromARCameraView(
+            tx = tArr[0].toDouble(),
+            ty = tArr[1].toDouble(),
+            tz = tArr[2].toDouble(),
+            qx = qarr[0].toDouble(), qy = qarr[1].toDouble(),
+            qz = qarr[2].toDouble(), qw = qarr[3].toDouble(),
+            fx = fx, fy = fy, cx = cxIntr, cy = cyIntr,
+            imageWidth = intrinsics.imageDimensions[0],
+            imageHeight = intrinsics.imageDimensions[1],
+            yaw = yaw, pitch = pitch,
+            fovHorizDegrees = fovHDeg, fovVertDegrees = fovVDeg,
+            trackingPoor = trackingPoor,
+            // The Y plane lives at packed.nv21[0 .. width*height).
+            // C++ keyframe_gate reads `height * stride` bytes and
+            // ignores anything past that, so passing the full NV21
+            // array with `grayStride = width` reads exactly the Y
+            // plane (UV bytes at the tail are not touched).
+            grayData = packed.nv21,
+            grayWidth = packed.width,
+            grayHeight = packed.height,
+            grayStride = packed.width,
+            legacyJpegPath = legacyJpegPath,
+            onAccept = { targetPath ->
+                // Lazy JPEG encode.  Runs ONLY if the C++ KeyframeGate
+                // accepted the frame.  Encodes from the pre-packed
+                // NV21 bytes — the ARCore Image has been closed since
+                // ~25 ms ago (right after packNV21), so no
+                // Image-hold cost on this slow path.
+                YuvImageConverter.encodeJpegFromNV21(
+                    packed,
+                    targetPath,
+                    jpegQuality = 70,
+                    displayRotation = rotationForEncode,
+                ) != null
+            },
+        )
     }
 
     private fun applyDisplayGeometry() {

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

@@ -14,6 +14,25 @@ import java.io.FileOutputStream
 /**
  * Convert an ARCore `Image` (YUV_420_888) to a JPEG file on disk.
  *
+ * 2026-05-22 (audit follow-up #19) — split into two phases so callers
+ * can release the underlying ARCore `Image` ASAP:
+ *
+ *   1. `packNV21(image)`  — reads the Y/U/V planes into a contiguous
+ *      JVM-side `ByteArray` (NV21 layout).  Fast (~3 ms for 1920×1080).
+ *      The caller can close the `Image` IMMEDIATELY after this returns,
+ *      freeing the ARCore Camera2 ImageReader buffer.
+ *
+ *   2. `encodeJpegFromNV21(packed, …)` — does the slow YUV→JPEG
+ *      conversion (~10-25 ms) on the already-extracted bytes, NOT on
+ *      the Image.  Safe to run after the Image has been closed.
+ *
+ * The pre-#19 single-call `encodeToJpeg(image, …)` API is preserved as
+ * a thin wrapper for callers that don't care about Image hold time
+ * (e.g., one-shot photo capture).  Performance-critical paths
+ * (`RNSARCameraView.forwardToIncremental`, called at ~60 Hz on the
+ * GL render thread) should use the two-step API to keep Image hold
+ * times bounded by the ~3 ms pack step instead of the ~25 ms encode.
+ *
  * Why JPEG → file → re-decode by OpenCV (slightly wasteful)?
  *   The incremental engine's existing API (matching iOS') consumes
  *   image PATHS, not raw planes.  Threading raw YUV through the
@@ -22,56 +41,182 @@ import java.io.FileOutputStream
  *   next to the ~40 ms per-frame engine work — keeping the surface
  *   uniform across iOS / Android paths is worth the few-ms cost.
  *
- * `Image` ownership: caller MUST `image.close()` after this returns.
- * We don't close inside because the caller may want to inspect more
- * fields (timestamp, format) before releasing.
+ * `Image` ownership: the two-step API (`packNV21` + `encodeJpegFromNV21`)
+ * returns control to the caller after the pack step so the caller can
+ * close the Image at the right moment.  The legacy single-call
+ * `encodeToJpeg(image, …)` does NOT close the Image — caller is
+ * responsible for that.
  */
 internal object YuvImageConverter {
 
-    /// Convert + write JPEG.  Returns the path (no file:// prefix)
-    /// or null on any encode/write error (caller-decides whether to
-    /// log + drop the frame).
-    ///
-    /// 2026-05-15 (B3) — `displayRotation` parameter writes the
-    /// appropriate EXIF orientation tag so RN's Image loader (and
-    /// any other consumer that respects EXIF) displays the JPEG
-    /// upright regardless of how the device was held at capture.
-    ///
-    /// Without this, Android's image loaders display the raw sensor
-    /// pixels (typically landscape) as-is — so a portrait-held
-    /// capture's thumbnail appears sideways.  iOS's image loader
-    /// auto-respects EXIF orientation; Android's doesn't always
-    /// (depends on the loader path).  Setting the tag covers both.
-    ///
-    /// `displayRotation` should be the value returned from
-    /// `WindowManager.defaultDisplay.rotation` at capture time
-    /// (Surface.ROTATION_0/_90/_180/_270).  We assume a typical
-    /// back-camera sensor orientation of 90° — true for all
-    /// devices we ship to (Galaxy A35 verified).  Wire through
-    /// CameraCharacteristics.SENSOR_ORIENTATION in a follow-up
-    /// if we ever encounter a device that differs.
-    ///
-    /// Default `displayRotation = Surface.ROTATION_0` (portrait)
-    /// preserves the previous behaviour for legacy callsites that
-    /// haven't been updated yet.
-    fun encodeToJpeg(
-        image: Image,
+    /**
+     * Packed NV21 pixel data extracted from an ARCore `Image`.
+     * Once you hold one of these, the source `Image` can be closed —
+     * all subsequent operations work on the JVM-side byte array.
+     *
+     * NV21 layout (single contiguous byte array):
+     *   bytes [0 .. width*height)              = Y plane (luminance),
+     *                                            densely packed,
+     *                                            row stride = width
+     *   bytes [width*height .. width*height*3/2) = interleaved V-U pairs
+     *                                              at half resolution
+     *
+     * The Y plane portion can be passed directly to the C++
+     * `keyframe_gate` as grayscale pixels with `stride = width`.
+     */
+    data class PackedYuv(
+        val nv21: ByteArray,
+        val width: Int,
+        val height: Int,
+    ) {
+        /** Length of the Y plane portion (bytes [0 .. ySize)). */
+        val ySize: Int get() = width * height
+
+        // equals + hashCode override required because `nv21` is a
+        // mutable array; default `data class` equality uses reference
+        // identity for arrays, which is rarely what callers want.
+        override fun equals(other: Any?): Boolean {
+            if (this === other) return true
+            if (other !is PackedYuv) return false
+            return width == other.width
+                && height == other.height
+                && nv21.contentEquals(other.nv21)
+        }
+        override fun hashCode(): Int {
+            var result = nv21.contentHashCode()
+            result = 31 * result + width
+            result = 31 * result + height
+            return result
+        }
+    }
+
+
+    /**
+     * Pack the Y, U, V planes of a YUV_420_888 `Image` into a
+     * contiguous JVM-side NV21 byte array.  Returns null if the
+     * `Image`'s format isn't YUV_420_888 or doesn't expose 3 planes.
+     *
+     * Performance: ~3 ms for 1920×1080 on a Galaxy A35.  Dominated
+     * by the row-by-row copy through the direct ByteBuffers backing
+     * the camera planes.
+     *
+     * The Y plane is densely repacked (the source rowStride may be
+     * padded, but we discard padding on the way in so the result has
+     * `rowStride = width`).  This is what callers want — `cv::Mat`
+     * wrap on the C++ side prefers tight strides, and downstream
+     * `YuvImage.compressToJpeg` requires densely-packed input.
+     */
+    fun packNV21(image: Image): PackedYuv? {
+        if (image.format != ImageFormat.YUV_420_888) return null
+        val planes = image.planes
+        if (planes.size < 3) return null
+
+        val w = image.width
+        val h = image.height
+        val ySize = w * h
+        val uvSize = w * h / 2
+        val nv21 = ByteArray(ySize + uvSize)
+
+        // ── Y plane (luminance) ─────────────────────────────────
+        val yPlane = planes[0]
+        val yBuf = yPlane.buffer
+        val yRowStride = yPlane.rowStride
+        if (yRowStride == w) {
+            // Source already densely packed — single block copy.
+            // Use duplicate() so we don't mutate the original buffer's
+            // position state (defensive — ARCore may have other readers
+            // of the same underlying buffer, though in practice it
+            // shouldn't).
+            yBuf.duplicate().apply { rewind() }.get(nv21, 0, ySize)
+        } else {
+            // Row-by-row copy when stride > width (padded rows).
+            val dup = yBuf.duplicate()
+            var dstOffset = 0
+            var srcOffset = 0
+            for (row in 0 until h) {
+                dup.position(srcOffset)
+                dup.get(nv21, dstOffset, w)
+                dstOffset += w
+                srcOffset += yRowStride
+            }
+        }
+
+        // ── U + V planes (chroma) ───────────────────────────────
+        // YUV_420_888 has them subsampled 2:1 so each plane physically
+        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
+        // (semi-planar interleaved).  NV21 expects interleaved V-U.
+        val uPlane = planes[1]
+        val vPlane = planes[2]
+        val uBuf = uPlane.buffer
+        val vBuf = vPlane.buffer
+        val uRowStride = uPlane.rowStride
+        val uPixelStride = uPlane.pixelStride
+        val vRowStride = vPlane.rowStride
+        val vPixelStride = vPlane.pixelStride
+
+        // Fast path — most Android camera2 / ARCore producers emit
+        // semi-planar interleaved data with pixelStride=2.  In that
+        // case the V plane's underlying bytes physically interleave
+        // V-U-V-U... and copying the V plane's full byte range
+        // produces NV21 layout directly.
+        if (uPixelStride == 2 && vPixelStride == 2 &&
+            uRowStride == vRowStride && uRowStride == w) {
+            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
+            // Defensive duplicate() again — same reasoning as Y plane.
+            vBuf.duplicate().apply { rewind() }.get(nv21, ySize, vBytes)
+            return PackedYuv(nv21, w, h)
+        }
+
+        // Slow path — manual interleave for planar (pixelStride=1) or
+        // non-tight semi-planar layouts.
+        var pos = ySize
+        val rowsUv = h / 2
+        val colsUv = w / 2
+        for (row in 0 until rowsUv) {
+            for (col in 0 until colsUv) {
+                val vIdx = row * vRowStride + col * vPixelStride
+                val uIdx = row * uRowStride + col * uPixelStride
+                nv21[pos++] = vBuf.get(vIdx)
+                nv21[pos++] = uBuf.get(uIdx)
+            }
+        }
+        return PackedYuv(nv21, w, h)
+    }
+
+
+    /**
+     * Encode an already-packed NV21 buffer to a JPEG file on disk.
+     *
+     * Returns the output path on success, or null on any encode/write
+     * error (caller decides whether to log + drop the frame).
+     *
+     * `displayRotation` writes the appropriate EXIF orientation tag
+     * so consumers that respect EXIF (RN's Image loader, etc.)
+     * display the JPEG upright regardless of how the device was held
+     * at capture.  Should be the value from
+     * `WindowManager.defaultDisplay.rotation` at capture time
+     * (Surface.ROTATION_0 / _90 / _180 / _270).
+     *
+     * Sensor orientation 90° assumed (back camera) — verified on
+     * Galaxy A35.  Wire `CameraCharacteristics.SENSOR_ORIENTATION`
+     * through in a follow-up if we hit a device that differs.
+     */
+    fun encodeJpegFromNV21(
+        packed: PackedYuv,
         outputPath: String,
         jpegQuality: Int = 70,
         displayRotation: Int = Surface.ROTATION_0,
     ): String? {
-        if (image.format != ImageFormat.YUV_420_888) return null
-        val nv21 = yuv420toNV21(image) ?: return null
         val yuvImage = YuvImage(
-            nv21,
+            packed.nv21,
             ImageFormat.NV21,
-            image.width,
-            image.height,
+            packed.width,
+            packed.height,
             null,
         )
         val baos = ByteArrayOutputStream()
         val ok = yuvImage.compressToJpeg(
-            Rect(0, 0, image.width, image.height),
+            Rect(0, 0, packed.width, packed.height),
             jpegQuality.coerceIn(1, 100),
             baos,
         )
@@ -81,8 +226,9 @@ internal object YuvImageConverter {
         } catch (e: Throwable) {
             return null
         }
+
         // Write EXIF orientation tag based on display rotation.
-        // Sensor orientation 90° assumed (back camera).  The math:
+        // The math:
         //   ROTATION_0  (portrait, sensor 90° CW from screen-up)
         //     → JPEG needs 90° CW to display upright → ROTATE_90 (6)
         //   ROTATION_90 (landscape-left, sensor aligned with screen)
@@ -93,11 +239,11 @@ internal object YuvImageConverter {
         //     → 180° → ROTATE_180 (3)
         //
         // EXIF tag set EVEN when the orientation is normal — keeps
-        // every output JPEG self-describing for downstream
-        // consumers (cv::Stitcher does NOT auto-honour EXIF, see
-        // BatchStitcher.applyExifOrientation; this metadata
-        // exists primarily for the live thumbnail strip + future
-        // RN Image renderers).
+        // every output JPEG self-describing for downstream consumers.
+        // cv::Stitcher does NOT auto-honour EXIF (see
+        // BatchStitcher.applyExifOrientation); this metadata exists
+        // primarily for the live thumbnail strip + future RN Image
+        // renderers.
         val exifOrientation = when (displayRotation) {
             Surface.ROTATION_0   -> ExifInterface.ORIENTATION_ROTATE_90
             Surface.ROTATION_90  -> ExifInterface.ORIENTATION_NORMAL
@@ -114,88 +260,35 @@ internal object YuvImageConverter {
             exif.saveAttributes()
         } catch (e: Throwable) {
             // EXIF write failed — JPEG itself is still valid; just
-            // missing the orientation hint.  Caller doesn't need to
-            // know — non-fatal.
+            // missing the orientation hint.  Non-fatal; caller doesn't
+            // need to know.
         }
         return outputPath
     }
 
+
     /**
-     * Pack a YUV_420_888 `Image` into a contiguous NV21 byte array.
+     * Single-call convenience wrapper: pack the `Image` and encode
+     * to JPEG in one step.  Keeps the `Image` open through the entire
+     * ~25 ms encode — fine for one-shot photo capture, NOT
+     * recommended for the ~60 Hz `forwardToIncremental` path.  See the
+     * file-level docs for the two-step alternative.
      *
-     * The Image API exposes Y, U, V as three planes, each with its
-     * own row stride and pixel stride.  NV21 expects a single
-     * contiguous buffer with Y plane first, then interleaved VU bytes
-     * after.  The repacking handles row + pixel strides that don't
-     * match the dense layout.
+     * Caller still owns the `Image` and MUST close it afterwards;
+     * this function does not.
      */
-    private fun yuv420toNV21(image: Image): ByteArray? {
-        val w = image.width
-        val h = image.height
-        val ySize = w * h
-        val uvSize = w * h / 2
-
-        val nv21 = ByteArray(ySize + uvSize)
-        val planes = image.planes
-        if (planes.size < 3) return null
-
-        // Y plane.
-        val yPlane = planes[0]
-        val yBuf = yPlane.buffer
-        val yRowStride = yPlane.rowStride
-        if (yRowStride == w) {
-            yBuf.get(nv21, 0, ySize)
-        } else {
-            // Row-by-row copy when stride != width.
-            var dstOffset = 0
-            var srcOffset = 0
-            for (row in 0 until h) {
-                yBuf.position(srcOffset)
-                yBuf.get(nv21, dstOffset, w)
-                dstOffset += w
-                srcOffset += yRowStride
-            }
-        }
-
-        // U + V planes.  YUV_420_888 has them subsampled 2:1 so each
-        // covers (w/2) × (h/2).  Pixel stride is 1 (planar) or 2
-        // (semi-planar interleaved).  NV21 requires interleaved VU.
-        val uPlane = planes[1]
-        val vPlane = planes[2]
-        val uBuf = uPlane.buffer
-        val vBuf = vPlane.buffer
-        val uRowStride = uPlane.rowStride
-        val uPixelStride = uPlane.pixelStride
-        val vRowStride = vPlane.rowStride
-        val vPixelStride = vPlane.pixelStride
-
-        // Most camera2 / ARCore implementations on Android already
-        // produce semi-planar interleaved data with pixelStride=2.
-        // In that case Y plane + V plane (offset by 1) form NV21
-        // directly with a single block copy.  Detect + fast-path it.
-        if (uPixelStride == 2 && vPixelStride == 2 &&
-            uRowStride == vRowStride && uRowStride == w) {
-            // The V plane in NV21 layout starts at vBuf's first byte.
-            // Copy the entire V plane (which physically interleaves
-            // with U bytes since pixelStride=2 means consecutive
-            // bytes are V-U-V-U...).
-            val vBytes = vBuf.remaining().coerceAtMost(uvSize)
-            vBuf.get(nv21, ySize, vBytes)
-            return nv21
-        }
-
-        // Slow path — manual interleave.
-        var pos = ySize
-        val rowsUv = h / 2
-        val colsUv = w / 2
-        for (row in 0 until rowsUv) {
-            for (col in 0 until colsUv) {
-                val vIdx = row * vRowStride + col * vPixelStride
-                val uIdx = row * uRowStride + col * uPixelStride
-                nv21[pos++] = vBuf.get(vIdx)
-                nv21[pos++] = uBuf.get(uIdx)
-            }
-        }
-        return nv21
+    fun encodeToJpeg(
+        image: Image,
+        outputPath: String,
+        jpegQuality: Int = 70,
+        displayRotation: Int = Surface.ROTATION_0,
+    ): String? {
+        val packed = packNV21(image) ?: return null
+        return encodeJpegFromNV21(
+            packed,
+            outputPath,
+            jpegQuality = jpegQuality,
+            displayRotation = displayRotation,
+        )
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",