react-native-image-stitcher 0.1.0

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

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+/**
+ * Kotlin facade over the shared C++ KeyframeGate (in
+ * retailens-capture-sdk/cpp/keyframe_gate.{hpp,cpp}).
+ *
+ * Architecture parity with iOS:
+ *   iOS uses an Obj-C++ bridge (KeyframeGateBridge.mm) to wrap the
+ *   same C++ class.  This Kotlin class is the Android equivalent —
+ *   thin facade, JNI plumbing, identical public surface.  Both
+ *   platforms call into the same C++ algorithm, so panorama
+ *   composition decisions are bit-identical across platforms (the
+ *   whole point of the P3 work).
+ *
+ * Lifecycle:
+ *   Each instance owns one C++ KeyframeGate via a `Long` opaque
+ *   handle.  Caller MUST call [close] before the instance is GC'd,
+ *   otherwise we leak a small heap allocation per gate-instance.
+ *   Practice on Android: KeyframeGate is held by
+ *   IncrementalStitcher as a member; we add cleanup hook
+ *   in `onCatalystInstanceDestroy()` so the JNI native heap stays
+ *   bounded across RN reloads.
+ *
+ * Threading:
+ *   The underlying C++ class is NOT thread-safe.  Caller MUST
+ *   serialise — typically via the engine's workScope serial
+ *   dispatcher.  Same contract the iOS side has.
+ *
+ * Reason-string parity:
+ *   The JS layer reads `decision.reason` for telemetry; that string
+ *   value MUST match iOS byte-for-byte or the UI pill drifts
+ *   silently.  The mapping is centralised in [reasonFromCode] —
+ *   1:1 with `KeyframeGateBridge.mm::kReasonStringFor` on iOS.
+ *   Drift here is a parity bug.
+ */
+internal class KeyframeGate : AutoCloseable {
+
+    private val nativeHandle: Long = nativeCreate()
+
+    @Volatile private var closed: Boolean = false
+
+    override fun close() {
+        if (!closed) {
+            closed = true
+            nativeDestroy(nativeHandle)
+        }
+    }
+
+    // Defensive net for missed close() calls.  Kotlin/JVM finalizers
+    // are unreliable but better than nothing — they prevent a slow
+    // native-heap leak in pathological "module rebuilt many times
+    // without explicit cleanup" cases.  Always prefer explicit close().
+    @Suppress("DEPRECATION")
+    protected fun finalize() {
+        close()
+    }
+
+    // ── Settings ────────────────────────────────────────────────
+
+    var enabled: Boolean
+        get() = nativeIsEnabled(nativeHandle)
+        set(value) = nativeSetEnabled(nativeHandle, value)
+
+    /// Required new-content fraction (0…1).  Default 0.4.  No getter
+    /// — the C++ side has no read accessor (Swift side never needed
+    /// to read this back either).  Stored locally for diagnostic
+    /// readbacks; written into C++ via setter.
+    var overlapThreshold: Double = 0.4
+        set(value) {
+            field = value
+            nativeSetOverlapThreshold(nativeHandle, value)
+        }
+
+    var maxCount: Int
+        get() = nativeGetMaxCount(nativeHandle)
+        set(value) = nativeSetMaxCount(nativeHandle, value)
+
+    /// One-shot write-only trigger.  Setting `true` arms the next
+    /// evaluate() to force-accept; the trigger is consumed inside
+    /// the C++ gate.  Reading always returns false (matches the
+    /// iOS Swift facade's behaviour).
+    var forceAcceptNext: Boolean
+        get() = false
+        set(value) {
+            if (value) nativeMarkNextFrameAsLast(nativeHandle)
+        }
+
+    /// 2026-05-14 — disable the angular-delta fallback.  See C++
+    /// `setDisableAngularFallback` doc for the full rationale.  In
+    /// short: set this to `true` in non-AR mode (captureSource ∈
+    /// {wide, ultrawide}) where pose data isn't available — the
+    /// gate's angular calculation would otherwise produce nonsense.
+    /// Default `false` (back-compat — AR mode uses the fallback).
+    /// Write-only; no read accessor on the C++ side.
+    var disableAngularFallback: Boolean = false
+        set(value) {
+            field = value
+            nativeSetDisableAngularFallback(nativeHandle, value)
+        }
+
+    /// 2026-05-14 — Flow strategy: novelty aggregation percentile
+    /// (same knob iOS exposes via setFlowNoveltyPercentile).  C++
+    /// clamps to [0.5, 0.99].  Stored locally for diagnostic
+    /// readback; the C++ side has no getter.
+    var flowNoveltyPercentile: Double = 0.85
+        set(value) {
+            field = value
+            nativeSetFlowNoveltyPercentile(nativeHandle, value)
+        }
+
+    /// 2026-05-14 — Flow strategy: max translation in METRES between
+    /// consecutive accepted keyframes before force-acceptance.  Same
+    /// knob iOS exposes via setFlowMaxTranslationM.  In non-AR mode
+    /// the JS host computes translation from react-native-sensors
+    /// IMU integration and pushes it through this setter so the
+    /// translation-budget logic in C++ kicks in even without ARKit/
+    /// ARCore pose.  0.0 (default) = disabled.
+    var flowMaxTranslationM: Double = 0.0
+        set(value) {
+            field = value
+            nativeSetFlowMaxTranslationM(nativeHandle, value)
+        }
+
+    // ── Read-only state ─────────────────────────────────────────
+
+    val acceptedCount: Int get() = nativeGetAcceptedCount(nativeHandle)
+
+    // ── Lifecycle ───────────────────────────────────────────────
+
+    fun reset() {
+        nativeReset(nativeHandle)
+        // Re-apply locally-stored settings the C++ doesn't track for
+        // readback.  (Currently just overlapThreshold.)  Matches the
+        // iOS facade's reset() which re-writes overlapThreshold too.
+        nativeSetOverlapThreshold(nativeHandle, overlapThreshold)
+    }
+
+    // ── Evaluation ──────────────────────────────────────────────
+
+    /**
+     * Decide whether to accept this ARCore frame as a keyframe.
+     *
+     * @param pose Camera pose + intrinsics for this frame.
+     * @param latchedPlaneMatrix Column-major 4×4 plane transform
+     *   (16 floats).  Pass null for the angular-delta fallback path
+     *   (when no plane is latched).  Format MUST match what ARCore's
+     *   `Pose.toMatrix(out, offset)` produces — column-major, same
+     *   layout as iOS simd_float4x4.
+     */
+    fun evaluate(
+        pose: RNSARFramePose,
+        latchedPlaneMatrix: FloatArray?,
+    ): KeyframeGateDecision {
+        val result = nativeEvaluate(
+            nativeHandle,
+            pose.tx.toFloat(), pose.ty.toFloat(), pose.tz.toFloat(),
+            pose.qx.toFloat(), pose.qy.toFloat(), pose.qz.toFloat(), pose.qw.toFloat(),
+            pose.fx.toFloat(), pose.fy.toFloat(), pose.cx.toFloat(), pose.cy.toFloat(),
+            pose.imageWidth, pose.imageHeight,
+            latchedPlaneMatrix,
+        )
+        // result layout (matches keyframe_gate_jni.cpp::nativeEvaluate):
+        //   [0] accept (1.0 / 0.0)
+        //   [1] reasonCode (int)
+        //   [2] newContentFraction (-1.0 when not computed)
+        //   [3] acceptedCount (int)
+        //   [4] maxCount (int)
+        return KeyframeGateDecision(
+            accept = result[0] >= 0.5,
+            reason = reasonFromCode(result[1].toInt()),
+            newContentFraction = result[2],
+            acceptedCount = result[3].toInt(),
+            maxCount = result[4].toInt(),
+        )
+    }
+
+    // ── JNI thunks ──────────────────────────────────────────────
+
+    private external fun nativeCreate(): Long
+    private external fun nativeDestroy(handle: Long)
+    private external fun nativeSetEnabled(handle: Long, enabled: Boolean)
+    private external fun nativeSetOverlapThreshold(handle: Long, t: Double)
+    private external fun nativeSetMaxCount(handle: Long, n: Int)
+    private external fun nativeMarkNextFrameAsLast(handle: Long)
+    private external fun nativeReset(handle: Long)
+    private external fun nativeGetAcceptedCount(handle: Long): Int
+    private external fun nativeGetMaxCount(handle: Long): Int
+    private external fun nativeIsEnabled(handle: Long): Boolean
+    // 2026-05-14 — new setters for the non-AR mode plumbing + the
+    // setFlowNoveltyPercentile / setFlowMaxTranslationM iOS-parity
+    // setters (Android JNI was a P3-followup until 2026-05-14).
+    private external fun nativeSetDisableAngularFallback(handle: Long, disabled: Boolean)
+    private external fun nativeSetFlowNoveltyPercentile(handle: Long, percentile: Double)
+    private external fun nativeSetFlowMaxTranslationM(handle: Long, metres: Double)
+    private external fun nativeEvaluate(
+        handle: Long,
+        tx: Float, ty: Float, tz: Float,
+        qx: Float, qy: Float, qz: Float, qw: Float,
+        fx: Float, fy: Float, cx: Float, cy: Float,
+        imageWidth: Int, imageHeight: Int,
+        plane16: FloatArray?,
+    ): DoubleArray
+
+    companion object {
+        init {
+            // libimage_stitcher.so contains both the OpenCV stitcher
+            // shim AND the C++ KeyframeGate + JNI bindings (single .so
+            // keeps APK lean and avoids a second System.loadLibrary).
+            System.loadLibrary("image_stitcher")
+        }
+
+        /**
+         * Map C++ `KeyframeGateDecisionReason` enum int → telemetry
+         * string.  MUST stay byte-for-byte identical to iOS' mapping
+         * in `KeyframeGateBridge.mm::kReasonStringFor`.  JS reads
+         * `decision.reason` and surfaces it directly to the UI pill
+         * (live frame strip "keyframe rejected: max-reached" etc.),
+         * so drift across platforms is a parity bug.
+         */
+        private fun reasonFromCode(code: Int): String = when (code) {
+            0 -> "gate-disabled"
+            1 -> "force-last"
+            2 -> "first-anchored-on-plane"
+            3 -> "first-no-plane"
+            4 -> "ok"
+            5 -> "ok-angular"
+            6 -> "projection-degenerate"
+            7 -> "current-area-zero"
+            8 -> "no-pose-yet"
+            9 -> "max-reached"
+            10 -> "overlap-too-high"
+            11 -> "overlap-too-high (angular)"
+            else -> "unknown($code)"
+        }
+    }
+}
+
+/**
+ * Result of a single [KeyframeGate.evaluate] call.  Layout mirrors
+ * iOS `KeyframeGateDecision` exactly so JS-side telemetry handlers
+ * don't branch on platform.
+ */
+internal data class KeyframeGateDecision(
+    /// Caller checks this first — `true` means ingest the frame.
+    val accept: Boolean,
+    /// Telemetry string ("ok" / "max-reached" / "overlap-too-high" / etc).
+    val reason: String,
+    /// Computed [0, 1] new-content fraction, or -1.0 if not computed
+    /// (gate disabled, force-first/last, no plane available).
+    val newContentFraction: Double,
+    /// Keyframes accepted so far (includes this one if accept=true).
+    val acceptedCount: Int,
+    /// Cap for this capture (0 if gate disabled).
+    val maxCount: Int,
+)

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

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableNativeMap
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import org.opencv.core.Core
+import org.opencv.core.CvType
+import org.opencv.core.Mat
+import org.opencv.core.MatOfDouble
+import org.opencv.imgcodecs.Imgcodecs
+import org.opencv.imgproc.Imgproc
+
+/**
+ * Android twin of the iOS QualityChecker (`RNImageStitcherQualityChecker` native module).
+ *
+ * Algorithm:
+ *   - Blur score: variance of the Laplacian of the grayscale image.
+ *     Higher = sharper.  Threshold (passed by host) typically 100.
+ *   - Brightness score: mean luminance of the grayscale image, in
+ *     [0..1].  Threshold range typically [0.2, 0.8].
+ *
+ * Same surface as the iOS module:
+ *   runQualityCheck({ imagePath, blurThreshold, brightnessLow,
+ *                     brightnessHigh })
+ *     → { passed, blurScore, brightnessScore, issues: [] }
+ *
+ * OpenCV is initialised lazily on first call.  The init is fast
+ * (no native loader prompts in OpenCV 4.x) and the result is
+ * cached.
+ */
+class QualityChecker(reactContext: ReactApplicationContext)
+    : ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String = "RNImageStitcherQualityChecker"
+
+    @ReactMethod
+    fun runQualityCheck(options: ReadableMap, promise: Promise) {
+        val imagePath = options.getString("imagePath")
+            ?: return promise.reject("invalid-options", "imagePath required")
+        val blurThreshold =
+            if (options.hasKey("blurThreshold")) options.getDouble("blurThreshold") else 100.0
+        val brightnessLow =
+            if (options.hasKey("brightnessLow")) options.getDouble("brightnessLow") else 0.2
+        val brightnessHigh =
+            if (options.hasKey("brightnessHigh")) options.getDouble("brightnessHigh") else 0.8
+
+        // Run on background coroutine — image decode + Laplacian
+        // takes ~30-80 ms on a midrange phone, enough to drop a
+        // frame on the JS thread.
+        CoroutineScope(Dispatchers.Default).launch {
+            try {
+                ensureOpenCv()
+                val cleaned = stripFileScheme(imagePath)
+                val src = Imgcodecs.imread(cleaned, Imgcodecs.IMREAD_COLOR)
+                if (src.empty()) {
+                    promise.reject(
+                        "read-failed",
+                        "Could not decode image at $imagePath",
+                    )
+                    return@launch
+                }
+
+                val gray = Mat()
+                Imgproc.cvtColor(src, gray, Imgproc.COLOR_BGR2GRAY)
+
+                // Laplacian variance — same algorithm as iOS.
+                val lap = Mat()
+                Imgproc.Laplacian(gray, lap, CvType.CV_64F)
+                val mean = MatOfDouble()
+                val stddev = MatOfDouble()
+                Core.meanStdDev(lap, mean, stddev)
+                val blurScore = stddev.toArray()[0].let { it * it }
+
+                // Mean luminance, normalised to 0..1.
+                val meanBrightness = Core.mean(gray).`val`[0] / 255.0
+
+                val issues = mutableListOf<Map<String, String>>()
+                if (blurScore < blurThreshold) {
+                    issues.add(mapOf(
+                        "type" to "blur",
+                        "message" to "Image is too blurry (score $blurScore < $blurThreshold)",
+                        "severity" to "error",
+                    ))
+                }
+                if (meanBrightness < brightnessLow) {
+                    issues.add(mapOf(
+                        "type" to "brightness_low",
+                        "message" to "Image is too dark",
+                        "severity" to "warning",
+                    ))
+                } else if (meanBrightness > brightnessHigh) {
+                    issues.add(mapOf(
+                        "type" to "brightness_high",
+                        "message" to "Image is too bright",
+                        "severity" to "warning",
+                    ))
+                }
+
+                val passed = issues.none { it["severity"] == "error" }
+
+                val result = WritableNativeMap().apply {
+                    putBoolean("passed", passed)
+                    putDouble("blurScore", blurScore)
+                    putDouble("brightnessScore", meanBrightness)
+                    val issuesArray = com.facebook.react.bridge.WritableNativeArray()
+                    for (issue in issues) {
+                        val m = WritableNativeMap()
+                        m.putString("type", issue["type"])
+                        m.putString("message", issue["message"])
+                        m.putString("severity", issue["severity"])
+                        issuesArray.pushMap(m)
+                    }
+                    putArray("issues", issuesArray)
+                }
+
+                src.release()
+                gray.release()
+                lap.release()
+                mean.release()
+                stddev.release()
+
+                promise.resolve(result)
+            } catch (t: Throwable) {
+                promise.reject("quality-check-failed", t.message, t)
+            }
+        }
+    }
+
+    private fun ensureOpenCv() {
+        if (!opencvInitialised) {
+            // Load the prebuilt OpenCV native lib directly from
+            // the APK's lib/<ABI>/ folder.  We deliberately avoid
+            // OpenCV's `OpenCVLoader.initDebug()` because the rest
+            // of `org.opencv.android.*` (AsyncServiceHelper,
+            // StaticHelper, BaseLoaderCallback, etc.) is the
+            // legacy "OpenCV Manager service" code path that
+            // depends on a deprecated AIDL interface and an
+            // auto-generated R class — both excluded from our
+            // build.  System.loadLibrary is the same final call
+            // those helpers make under the hood.
+            try {
+                System.loadLibrary("opencv_java4")
+                opencvInitialised = true
+            } catch (e: UnsatisfiedLinkError) {
+                throw IllegalStateException(
+                    "OpenCV native library 'opencv_java4' failed to load",
+                    e,
+                )
+            }
+        }
+    }
+
+    companion object {
+        @Volatile
+        private var opencvInitialised: Boolean = false
+
+        internal fun stripFileScheme(path: String): String =
+            if (path.startsWith("file://")) path.removePrefix("file://") else path
+    }
+}

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

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+/**
+ * ReactPackage that registers the SDK's two native modules with
+ * the host app.  Picked up by RN autolinking via the package's
+ * sourceDir entry in `react-native.config.js`.
+ *
+ * Modules registered:
+ *   - QualityChecker: blur + brightness scoring
+ *   - BatchStitcher:       stitch / stitchVideo / normaliseImage
+ *
+ * The Android JS surface mirrors iOS exactly so any code using
+ * `NativeModules.RNImageStitcherQualityChecker.runQualityCheck(...)` or
+ * `NativeModules.BatchStitcher.stitch(...)` works the same on
+ * both platforms — no conditional branching needed in the SDK's
+ * JS layer.
+ */
+class RNImageStitcherPackage : ReactPackage {
+    override fun createNativeModules(
+        reactContext: ReactApplicationContext,
+    ): List<NativeModule> = listOf(
+        QualityChecker(reactContext),
+        BatchStitcher(reactContext),
+        RNSARSession(reactContext),
+        IncrementalStitcher(reactContext),
+    )
+
+    override fun createViewManagers(
+        reactContext: ReactApplicationContext,
+    ): List<ViewManager<*, *>> = listOf(
+        RNSARCameraViewManager(),
+    )
+}