react-native-image-stitcher 0.16.1 → 0.16.2

package/CHANGELOG.md

@@ -14,6 +14,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > during 0.x are bumped to a new MINOR (e.g., 0.1 → 0.2), and the
 > upgrade path is documented in this CHANGELOG.
 
+## [0.16.2] — 2026-06-17
+
+### Added — reuse the bundled OpenCV from your host app's native code (Android)
+
+A host app's own native (C++/NDK) code can now reuse the **same** custom
+OpenCV this library bundles (4.10.0, arm64-v8a) — **including `cv::Stitcher`**
+— with no second copy of `libopencv_java4.so` in the APK.
+
+The Android build now publishes the location of its vendored OpenCV SDK via
+`rootProject.ext.rnisOpenCVDir` (and `rnisOpenCVAndroidSdkDir`). A consumer
+points its `externalNativeBuild` at `-DOpenCV_DIR=${rootProject.ext.rnisOpenCVDir}`,
+calls `find_package(OpenCV)`, and links the shared `opencv_java` (core /
+imgproc / calib3d / … resolved at runtime from the already-shipped `.so`)
+plus the whole-archived static `opencv_stitching` (`cv::Stitcher`). A
+build-verified consumer ships in the example app
+(`example/android/app/src/main/cpp/`).
+
+This is additive — no public API or runtime-behaviour change. AGP
+`prefabPublishing` was evaluated and is unworkable for prebuilt OpenCV
+(prefab only exports libraries the module itself builds), so OpenCV's own
+first-class CMake package is used instead. iOS reuse (the vendored
+`opencv2.xcframework`) is unchanged.
+
+### Docs
+
+Documentation site refreshed: an easier **Getting started**, a complete
+**`<Camera>` API** reference (every prop, the v0.16 guidance params —
+`rectCrop` / `showPreview` / `panMode` / `panGuidance` / `maxPanDurationMs` /
+`panTooFastThreshold` / `lateralBudgetCm` / `guidanceCopy` — and the
+`stitcher` / `frameSelection` settings-JSON tables), a fully-loaded
+**Complete example**, the v0.16 **Capture result & errors** union, and new
+**Sharing OpenCV** / **Bring your own OpenCV** guides.
+
 ## [0.16.1] — 2026-06-16
 
 ### Changed — high-level `cv::Stitcher` is now the default pipeline

package/README.md

@@ -29,8 +29,8 @@ Peer dependencies (the host app provides these):
   "react": ">=18.0.0",
   "react-native": ">=0.72.0",
   "react-native-vision-camera": ">=4.7.0",
+  "react-native-worklets-core": ">=1.3.0",
   "react-native-sensors": ">=7.0.0",
-  "expo-sensors": ">=14.0.0",
   "react-native-safe-area-context": ">=4.0.0"
 }
 ```
@@ -71,50 +71,32 @@ cd android && ./gradlew :app:assembleDebug   # Android
 > See [Orientation support](#orientation-support) for the full story
 > (landscape *is* supported on iOS if you need it).
 
-The minimum: resolve camera permission, then mount `<Camera>` with an
-`onCapture` handler.
+The minimum: mount `<Camera>` with an `onCapture` handler. It fires once
+per capture attempt — gate on `result.ok` before reading the output.
 
 ```tsx
-import {
-  Camera,
-  type CameraCaptureResult,
-  type CameraError,
-} from 'react-native-image-stitcher';
+import { Camera, type CameraCaptureResult } from 'react-native-image-stitcher';
 
 export function CaptureScreen() {
-  const handleCapture = (result: CameraCaptureResult) => {
-    // `onCapture` fires on success AND failure — gate on `ok` first.
-    if (!result.ok) {
-      console.warn('capture failed:', result.error.code, result.error.message);
-      return;
-    }
-    // Non-fatal quality signals (e.g. <70% of frames used). Always present.
-    if (result.warnings.length > 0) {
-      console.warn('warnings:', result.warnings.map((w) => w.code));
-    }
-    if (result.type === 'photo') {
-      console.log('Photo:', result.uri, result.width, result.height);
-    } else {
-      console.log(
-        'Panorama:',
-        result.uri,
-        `${result.framesIncluded}/${result.framesRequested} frames`,
-        `stitched as ${result.stitchModeResolved ?? 'n/a'}`,
-      );
-    }
-  };
-
   return (
     <Camera
-      onCapture={handleCapture}
-      // onError still fires on failure too (an unchanged mirror of the
-      // ok:false result above).
-      onError={(err: CameraError) => console.warn(err.code, err.message)}
+      onCapture={(result: CameraCaptureResult) => {
+        if (!result.ok) {
+          console.warn('capture failed:', result.error.code);
+          return;
+        }
+        // result.type is 'photo' or 'panorama'; both carry uri/width/height.
+        console.log(result.type, result.uri, result.width, result.height);
+      }}
     />
   );
 }
 ```
 
+> **Camera permission is the host's job.** The SDK never requests it for
+> you — resolve it (e.g. with vision-camera's `useCameraPermission`)
+> before mounting `<Camera>`.
+
 ### A complete capture screen
 
 A realistic screen: requests permission up front, shows a capture

package/android/build.gradle

@@ -112,6 +112,40 @@ android {
         prefab true
     }
 
+    // ── Host OpenCV reuse: why NOT prefab publishing ─────────────────
+    //
+    // Goal: let a HOST app's own native (C++/NDK) code reuse the SAME
+    // custom OpenCV (4.10.0, arm64-v8a) this AAR already bundles — both
+    // libopencv_java4.so (cv::Mat, imgproc, features2d, calib3d, flann,
+    // photo, video …) AND cv::Stitcher (which lives in the static
+    // archive libopencv_stitching.a, NOT in the fat .so).
+    //
+    // We evaluated AGP `prefabPublishing` first (the idiomatic AAR way)
+    // and it CANNOT carry this OpenCV.  Empirically verified: AGP's
+    // prefab modules only export libraries the module's own
+    // externalNativeBuild PRODUCES (here: just `image_stitcher`).  A
+    // prebuilt jniLib (.so) or a prebuilt static archive (.a) is not an
+    // accepted prefab `libraryName` — the configure fails with
+    // `[CXX1404] did not find implicitly required targets`.  So neither
+    // libopencv_java4.so nor libopencv_stitching.a can ride a prefab.
+    //
+    // Instead we expose the bundled OpenCV's OWN first-class CMake
+    // package — which already defines every module (incl. opencv_stitching
+    // as a STATIC IMPORTED target and opencv_java as a SHARED IMPORTED
+    // target) — to consumers via a rootProject ext property.  A host
+    // points its externalNativeBuild at `-DOpenCV_DIR=<that dir>`, does
+    // `find_package(OpenCV REQUIRED)`, then links the SHARED `opencv_java`
+    // (cv::Mat & friends resolved at runtime from the AAR's already-shipped
+    // libopencv_java4.so — NO second copy) plus the whole-archived STATIC
+    // `opencv_stitching` (cv::Stitcher, a small private copy since it isn't
+    // in the fat .so).  This is the idiomatic Android OpenCV-consumption
+    // path.  See example/android/app for the working consumer.
+    //
+    // Set unconditionally at configure time so it's readable from the
+    // host app module regardless of project evaluation order.
+    rootProject.ext.rnisOpenCVAndroidSdkDir = "$opencvSdkDir/native"
+    rootProject.ext.rnisOpenCVDir = "$opencvSdkDir/native/jni"
+
     // ── JNI shim build path ─────────────────────────────────────────
     // Gradle compiles cpp/image_stitcher_jni.cpp into
     // libimage_stitcher.so for the ABIs filtered above.  The shim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.16.1",
+  "version": "0.16.2",
   "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",