react-native-image-stitcher 0.1.0

package/android/build.gradle

@@ -0,0 +1,224 @@
+// SPDX-FileCopyrightText: 2026 Tiger Analytics
+// SPDX-License-Identifier: Apache-2.0
+//
+// Gradle module for the Android side of react-native-image-stitcher.
+//
+// What lives here:
+//   - QualityChecker.kt — Laplacian-variance blur scoring
+//     and mean-luminance brightness scoring via OpenCV.  Mirror of
+//     the iOS Phase 1 implementation (which used vImage + vDSP).
+//   - Stitcher.kt — extractFrames + stitchFrames +
+//     stitchVideo + normaliseImage, mirroring the iOS Phase 2 / 2.5
+//     ObjC++ surface.
+//   - RNImageStitcherPackage.kt — ReactPackage that surfaces the
+//     two RN modules to the host app via Android autolinking.
+//
+// OpenCV vendor:
+//   We use the `quickbirdstudios/opencv-android` Maven artifact
+//   because it ships a clean AAR with the standard
+//   `org.opencv.*` Java packages, including the stitching module
+//   (which `opencv-mobile` strips on iOS — same trade-off applies
+//   here).  Version pinned to 4.x to match the iOS framework.
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def reactNativeRoot = rootProject.findProperty("reactNativeRoot") ?: project.file("../../../node_modules/react-native")
+
+// ── OpenCV Android SDK download ──────────────────────────────────────
+//
+// The OpenCV custom Android SDK is delivered by the package's
+// postinstall script (`scripts/postinstall-fetch-binaries.js`).  It
+// downloads the version-matched release asset from GitHub Releases
+// and extracts it into `android/vendor/OpenCV-android-sdk/` — exactly
+// where this build.gradle (and `cpp/CMakeLists.txt`) read it from.
+//
+// We deliberately do NOT have a fallback that fetches stock OpenCV
+// from upstream: stock 4.x ships WITHOUT `BUILD_opencv_stitching=ON`,
+// so the static lib `libopencv_stitching.a` that CMake links isn't
+// in the upstream archive.  If we silently downloaded the upstream
+// release, the build would explode with a confusing CMake "static
+// archive not found" error.  Better to fail FAST here with a clear
+// message pointing at the actual cause.
+def opencvVendorDir = file("$projectDir/vendor")
+def opencvSdkDir = file("$opencvVendorDir/OpenCV-android-sdk/sdk")
+if (!opencvSdkDir.exists()) {
+    throw new GradleException(
+        "OpenCV custom SDK missing at ${opencvSdkDir.absolutePath}.\n" +
+        "Did `npm install` succeed?  The package's postinstall script\n" +
+        "(scripts/postinstall-fetch-binaries.js) downloads the binaries\n" +
+        "from GitHub Releases on install.  Recovery:\n" +
+        "  - `npm install --force` to re-run postinstall\n" +
+        "  - Or set OPENCV_BINARY_BASE_URL env var to an internal mirror\n" +
+        "  - Or run `SKIP_OPENCV_FETCH=1 npm install` and stage the SDK manually"
+    )
+}
+
+android {
+    namespace 'io.imagestitcher.rn'
+    compileSdkVersion safeExtGet('compileSdkVersion', 34)
+    // Inherit the host's NDK pin (Expo apps expose `ndkVersion` on
+    // rootProject.ext) so AGP doesn't fall back to its built-in default
+    // (which on AGP 8.6+ is 27.0.12077973, a version that's commonly
+    // half-installed on developer machines and trips [CXX1101]
+    // "source.properties missing").  27.1.12297006 is the
+    // last-known-good fallback for raw RN hosts without an Expo pin.
+    ndkVersion safeExtGet('ndkVersion', '27.1.12297006')
+
+    defaultConfig {
+        minSdkVersion safeExtGet('minSdkVersion', 24)
+        targetSdkVersion safeExtGet('targetSdkVersion', 34)
+        versionCode 1
+        versionName "0.1.0"
+
+        // ── ABI filter ───────────────────────────────────────────
+        // Only build arm64-v8a.  Our custom OpenCV is built for
+        // arm64-v8a only (matches the production Samsung physical
+        // test device and modern Android phones).  Skipping
+        // armeabi-v7a / x86_64 / x86 saves ~120 MB on the final APK
+        // and avoids "libopencv_java4.so missing for ABI X" link
+        // errors during the native build.
+        ndk {
+            abiFilters 'arm64-v8a'
+        }
+
+        // ── JNI shim (image_stitcher) build args ─────────────
+        // Hands the cpp/CMakeLists.txt the location of the vendored
+        // OpenCV (with stitching symbols) so the shim can link.
+        externalNativeBuild {
+            cmake {
+                arguments "-DOPENCV_ANDROID_SDK=${file("$projectDir/vendor/OpenCV-android-sdk").absolutePath}",
+                          "-DANDROID_STL=c++_static"
+                cppFlags "-std=c++17"
+            }
+        }
+    }
+
+    // ── JNI shim build path ─────────────────────────────────────────
+    // Gradle compiles cpp/image_stitcher_jni.cpp into
+    // libimage_stitcher.so for the ABIs filtered above.  The shim
+    // is what bridges Kotlin's `external fun nativeStitchFramePaths`
+    // to the cv::Stitcher C++ API inside our custom libopencv_java4.so.
+    externalNativeBuild {
+        cmake {
+            path file("src/main/cpp/CMakeLists.txt")
+            version "3.22.1"
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_17
+        targetCompatibility JavaVersion.VERSION_17
+    }
+
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+
+    // The hand-rolled JNI wrapper for cv::Stitcher (planned for
+    // Android stitching parity with iOS) was removed because
+    // OpenCV's prebuilt Android `libopencv_java4.so` does NOT
+    // contain `cv::Stitcher::create` symbols — the stitching
+    // module is dropped from the binary, not just from the Java
+    // bindings.  Re-enabling Android-side stitching requires
+    // building OpenCV Android from source with `BUILD_opencv_stitching=ON`,
+    // which is a hours-long build job out of scope for the SDK
+    // package itself.  See the Kotlin BatchStitcher for the
+    // current "iOS-only" stitch behaviour.
+
+    sourceSets {
+        main {
+            // OpenCV ships its Java side as plain source files (not
+            // a pre-built JAR) under sdk/java/src/, so we compile it
+            // into our own AAR alongside the Kotlin code.  The
+            // pre-built .so libraries live under sdk/native/libs/
+            // and ride along as jniLibs.
+            java.srcDirs += [
+                "$opencvSdkDir/java/src",
+            ]
+            jniLibs.srcDirs = [
+                "$opencvSdkDir/native/libs",
+            ]
+            // OpenCV references some resources (logos, drawables)
+            // from its old wrapper; pointing res at the SDK keeps
+            // them available without copying.
+            res.srcDirs += [
+                "$opencvSdkDir/java/res",
+            ]
+        }
+    }
+
+    // OpenCV's MatAt.kt uses Kotlin inline-class types (UByte etc.)
+    // that the Kotlin 1.9.x compiler bundled with our toolchain
+    // can't lower.  We don't use the typed-Mat-accessor API anyway.
+    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
+        exclude '**/MatAt.kt'
+    }
+
+    // OpenCV's `org.opencv.android.*` package is the legacy
+    // OpenCV-Manager-service support layer + the camera UI views.
+    // We don't use ANY of it (we load the .so directly via
+    // System.loadLibrary and use vision-camera for camera UI).
+    // Excluding the whole package side-steps a wave of compile
+    // errors caused by missing AIDL-generated symbols and the
+    // missing `org.opencv.R` resource class.
+    tasks.withType(JavaCompile).configureEach {
+        exclude 'org/opencv/android/**'
+        exclude 'org/opencv/engine/**'
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+        }
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+    // OpenCV Android — the QuickBird build is the most up-to-date
+    // Maven artifact with full module set (including stitching).
+    maven { url 'https://jitpack.io' }
+}
+
+dependencies {
+    // React Native — provided by the host app via gradle's
+    // "compileOnly" so we don't pull a duplicate copy when the
+    // SDK is consumed from a hosting RN app.
+    compileOnly "com.facebook.react:react-android"
+
+    // OpenCV is wired in via sourceSets above (java/src compiled
+    // alongside Kotlin, native/libs surfaced as jniLibs).  No
+    // Maven coordinate needed.
+
+    // Kotlin stdlib + coroutines for the background-queue dispatch
+    // pattern that matches the iOS DispatchQueue.global(.userInitiated).
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.9.22"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
+
+    // ExifInterface for reading rotation metadata from JPEGs taken
+    // by Android cameras (which save in sensor-native landscape
+    // with an EXIF Orientation tag, same pattern as iOS).  The
+    // androidx version supports more file types and stays
+    // up-to-date with platform changes.
+    implementation "androidx.exifinterface:exifinterface:1.3.7"
+
+    // ARCore for Phase 4 of the AR-measurement plan: 6DoF pose
+    // tracking from camera + IMU on supported Android devices.
+    // Falls back to "AR not available" when:
+    //   - Device isn't on Google's ARCore-supported list
+    //   - Google Play Services for AR isn't installed / up-to-date
+    // The sample app doesn't require AR, so the dependency adds
+    // ~2 MB to the AAR; the Play Services for AR app is downloaded
+    // on demand (~30 MB) the first time the user opens an AR
+    // capture screen on a supported device.
+    implementation "com.google.ar:core:1.45.0"
+}
+
+// Helper from the React Native gradle convention to read host-app
+// SDK versions when present, with a sane default otherwise.
+def safeExtGet(prop, fallback) {
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="io.imagestitcher.rn" />

package/android/src/main/cpp/CMakeLists.txt

@@ -0,0 +1,124 @@
+# CMakeLists.txt — builds `libimage_stitcher.so`, the JNI shim that
+# exposes our custom-built OpenCV's `cv::Stitcher` to the Kotlin SDK.
+#
+# Architecture
+# ────────────
+# OpenCV's official prebuilt Android `libopencv_java4.so` strips the
+# stitching module entirely.  When we rebuild OpenCV with
+# BUILD_opencv_stitching=ON the stitching module is COMPILED (yields a
+# static archive `libopencv_stitching.a`) but it's NOT included in the
+# fat `libopencv_java4.so` either — the fat lib only bundles modules
+# that have Java auto-bindings, and the stitching module declares only
+# `WRAP python` upstream.
+#
+# Our shim closes that gap:
+#   - libopencv_stitching.a is STATICALLY linked into our shim, so
+#     `cv::Stitcher::create()` and related code lives inside
+#     `libimage_stitcher.so`.
+#   - libopencv_java4.so is DYNAMICALLY linked, providing cv::Mat,
+#     cv::imread/imwrite, cv::features2d, cv::calib3d, cv::flann, etc.
+#     at runtime — the fat lib already exports all the C++ symbols
+#     stitching depends on.
+#
+# Net result: a ~5-10 MB self-contained JNI shim that uses the
+# already-bundled fat .so for core OpenCV.
+
+cmake_minimum_required(VERSION 3.18)
+project(image_stitcher CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# Gradle passes OPENCV_ANDROID_SDK as a CMake -D arg.  Points to the
+# directory holding `sdk/native/jni/include/`,
+# `sdk/native/libs/<ABI>/libopencv_java4.so` and
+# `sdk/native/staticlibs/<ABI>/libopencv_stitching.a`.
+if(NOT DEFINED OPENCV_ANDROID_SDK)
+    message(FATAL_ERROR
+        "OPENCV_ANDROID_SDK must be passed in by the Gradle "
+        "externalNativeBuild block.  Check the SDK's android/build.gradle.")
+endif()
+
+set(OPENCV_INCLUDE_DIR  "${OPENCV_ANDROID_SDK}/sdk/native/jni/include")
+set(OPENCV_FAT_SO       "${OPENCV_ANDROID_SDK}/sdk/native/libs/${ANDROID_ABI}/libopencv_java4.so")
+set(OPENCV_STITCHING_A  "${OPENCV_ANDROID_SDK}/sdk/native/staticlibs/${ANDROID_ABI}/libopencv_stitching.a")
+
+if(NOT EXISTS "${OPENCV_FAT_SO}")
+    message(FATAL_ERROR
+        "OpenCV fat shared lib not found at:\n  ${OPENCV_FAT_SO}\n"
+        "Run the OpenCV custom build (see scripts/build-opencv-android.sh) "
+        "and copy artifacts into vendor/OpenCV-android-sdk/.")
+endif()
+if(NOT EXISTS "${OPENCV_STITCHING_A}")
+    message(FATAL_ERROR
+        "OpenCV stitching static archive not found at:\n  ${OPENCV_STITCHING_A}\n"
+        "Was the OpenCV build compiled with BUILD_opencv_stitching=ON?")
+endif()
+
+# Import the prebuilt OpenCV fat .so (dynamic link target).
+add_library(opencv_java SHARED IMPORTED)
+set_target_properties(opencv_java PROPERTIES
+    IMPORTED_LOCATION "${OPENCV_FAT_SO}")
+
+# Import the static archive for the stitching module (static link target).
+add_library(opencv_stitching STATIC IMPORTED)
+set_target_properties(opencv_stitching PROPERTIES
+    IMPORTED_LOCATION "${OPENCV_STITCHING_A}")
+
+# ── Shared C++ port (KeyframeGate) ────────────────────────────────
+#
+# `cpp/` at the SDK root holds C++ that's compiled into BOTH the iOS
+# pod (via the podspec source globs + HEADER_SEARCH_PATHS) and the
+# Android JNI shim (here).  Same source, same algorithm, same
+# panorama output — closes the iOS↔Android parity gap that the V16
+# Phase 1 frame-counter MVP placeholder left open.
+set(SHARED_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../cpp")
+if(NOT EXISTS "${SHARED_CPP_DIR}/keyframe_gate.hpp")
+    message(FATAL_ERROR
+        "Shared C++ port missing at:\n  ${SHARED_CPP_DIR}\n"
+        "Expected react-native-image-stitcher/cpp/ — was the package layout broken?")
+endif()
+
+# ── Our shim ───────────────────────────────────────────────────────
+add_library(image_stitcher SHARED
+    image_stitcher_jni.cpp
+    keyframe_gate_jni.cpp
+    "${SHARED_CPP_DIR}/keyframe_gate.cpp"
+    # 2026-05-15 — shared stitcher.cpp, used by BOTH platforms.
+    # Owns the cv::Stitcher orchestration + C+D progressive-confidence
+    # retry + dimension/memory instrumentation.  Used to live in this
+    # file (image_stitcher_jni.cpp).  See cpp/stitcher.hpp for design
+    # rationale.
+    "${SHARED_CPP_DIR}/stitcher.cpp")
+
+target_include_directories(image_stitcher PRIVATE
+    "${OPENCV_INCLUDE_DIR}"
+    # cpp/ holds keyframe_gate.hpp + ar_frame_pose.h that the JNI
+    # bindings include without relative-path spelunking.
+    "${SHARED_CPP_DIR}")
+
+# Link order matters:
+#   1. opencv_stitching (static .a) — pulls in cv::Stitcher code
+#   2. opencv_java (dynamic .so)    — resolves cv::Mat, cv::imread,
+#                                     cv::features2d, cv::calib3d,
+#                                     cv::flann, cv::imgproc, etc. at
+#                                     runtime via the host app's
+#                                     already-loaded libopencv_java4.so
+#   3. log                          — for __android_log_print
+#
+# `-Wl,--whole-archive` around the static lib forces the linker to
+# pull in every .o file even if it can't statically prove they're
+# needed.  Without it, cv::Stitcher::create() may be eliminated as
+# dead code (it's called via the JNI dispatch which the linker can't
+# trace at static-link time).
+target_link_libraries(image_stitcher
+    -Wl,--whole-archive
+    opencv_stitching
+    -Wl,--no-whole-archive
+    opencv_java
+    log)
+
+target_compile_options(image_stitcher PRIVATE
+    -fvisibility=hidden
+    -Wno-deprecated-declarations)

package/android/src/main/cpp/image_stitcher_jni.cpp

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// image_stitcher_jni.cpp — JNI shim that marshals Java/Kotlin args
+// into the shared C++ `retailens::stitchFramePaths` function in
+// cpp/stitcher.{hpp,cpp}.
+//
+// As of 2026-05-15, the algorithm itself lives in shared C++ (used by
+// both iOS via Obj-C++ bridge + Android via this JNI shim).  This
+// file's job is now ONLY:
+//   1. Unmarshal jobjectArray → std::vector<std::string>
+//   2. Unmarshal jstring args → StitchConfig
+//   3. Plug Android's __android_log_print into the shared LogFn
+//   4. Call retailens::stitchFramePaths(...)
+//   5. Marshal StitchResult → jintArray for Kotlin
+//
+// History
+// ───────
+//
+// Before 2026-05-15 commit feature/shared-stitcher-port, this file
+// owned the algorithm directly (~600 lines, used cv::Stitcher
+// high-level API).  The iOS side owned its own ~3000-line manual
+// pipeline.  Moving both behind a shared C++ stitcher eliminates
+// the platform divergence.
+
+#include <jni.h>
+#include <android/log.h>
+#include "stitcher.hpp"
+
+#include <string>
+#include <vector>
+
+
+#define LOG_TAG "BatchStitcher.JNI"
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO,  LOG_TAG, __VA_ARGS__)
+
+
+namespace {
+
+std::string jstring_to_string(JNIEnv* env, jstring jstr) {
+    if (jstr == nullptr) return std::string();
+    const char* cstr = env->GetStringUTFChars(jstr, nullptr);
+    std::string result(cstr);
+    env->ReleaseStringUTFChars(jstr, cstr);
+    return result;
+}
+
+void throw_runtime(JNIEnv* env, const std::string& msg) {
+    LOGE("%s", msg.c_str());
+    jclass cls = env->FindClass("java/lang/RuntimeException");
+    if (cls != nullptr) {
+        env->ThrowNew(cls, msg.c_str());
+    }
+}
+
+// Bridge the shared LogFn to __android_log_print so the shared C++
+// stitcher's [stitch]/[dimstat]/[memstat] log lines flow into logcat
+// under the same LOG_TAG the previous owner used.
+void androidLogBridge(int level, const char* tag, const char* msg) {
+    int prio = (level == 2) ? ANDROID_LOG_ERROR
+             : (level == 1) ? ANDROID_LOG_WARN
+                            : ANDROID_LOG_INFO;
+    __android_log_print(prio, LOG_TAG, "%s %s", tag ? tag : "", msg ? msg : "");
+}
+
+}  // namespace
+
+
+extern "C" JNIEXPORT jintArray JNICALL
+Java_io_imagestitcher_rn_BatchStitcher_nativeStitchFramePaths(
+        JNIEnv* env,
+        jobject /*thiz*/,
+        jobjectArray framePaths,
+        jstring outputPath,
+        jint jpegQuality,
+        jstring warperType,
+        jstring blenderType,
+        jstring seamFinderType,
+        jstring captureOrientation,
+        jboolean useInscribedRectCrop,
+        jdouble registrationResolMP,
+        jdouble seamEstimationResolMP,
+        jdouble compositingResolMP,
+        jstring stitchModeStr) {
+
+    if (framePaths == nullptr) {
+        throw_runtime(env, "framePaths is null");
+        return nullptr;
+    }
+    const jsize frameCount = env->GetArrayLength(framePaths);
+    std::vector<std::string> paths;
+    paths.reserve(frameCount);
+    for (jsize i = 0; i < frameCount; ++i) {
+        jstring jPath = (jstring) env->GetObjectArrayElement(framePaths, i);
+        if (jPath == nullptr) {
+            throw_runtime(env, "framePaths[" + std::to_string(i) + "] is null");
+            return nullptr;
+        }
+        paths.push_back(jstring_to_string(env, jPath));
+        env->DeleteLocalRef(jPath);
+    }
+
+    // Build the shared StitchConfig.
+    retailens::StitchConfig cfg;
+    cfg.warperType           = jstring_to_string(env, warperType);
+    cfg.blenderType          = jstring_to_string(env, blenderType);
+    cfg.seamFinderType       = jstring_to_string(env, seamFinderType);
+    cfg.captureOrientation   = jstring_to_string(env, captureOrientation);
+    cfg.useInscribedRectCrop = useInscribedRectCrop;
+    cfg.registrationResolMP  = registrationResolMP;
+    cfg.seamEstimationResolMP = seamEstimationResolMP;
+    cfg.compositingResolMP   = compositingResolMP;
+    cfg.jpegQuality          = jpegQuality;
+    const std::string modeStr = jstring_to_string(env, stitchModeStr);
+    cfg.stitchMode = (modeStr == "panorama")
+        ? retailens::StitchMode::Panorama
+        : retailens::StitchMode::Scans;
+
+    const std::string outPath = jstring_to_string(env, outputPath);
+
+    retailens::StitchResult result = retailens::stitchFramePaths(
+        paths, outPath, cfg, &androidLogBridge);
+
+    if (!result.success) {
+        const std::string msg = "Stitch failed: " + result.errorMessage +
+            " (code=" + std::to_string(static_cast<int>(result.errorCode)) + ")";
+        throw_runtime(env, msg);
+        return nullptr;
+    }
+
+    // Return [width, height, framesRequested, framesIncluded, finalThresholdMilli]
+    // — same JNI return layout as the previous file (Kotlin already
+    // parses indices 0-4).  The threshold is multiplied by 1000 +
+    // rounded to int since IntArray can't hold doubles.
+    jintArray dims = env->NewIntArray(5);
+    jint values[5] = {
+        result.width,
+        result.height,
+        result.framesRequested,
+        result.framesIncluded,
+        static_cast<jint>(result.finalConfidenceThresh * 1000.0),
+    };
+    env->SetIntArrayRegion(dims, 0, 5, values);
+    return dims;
+}