react-native-image-stitcher 0.11.1 → 0.12.0

package/dist/camera/useOrientationDrift.js

@@ -0,0 +1,120 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useOrientationDrift — detects mid-capture device rotation.
+ *
+ * Pairs with `useDeviceOrientation()` to surface the case where the
+ * user rotates the device *during* an active capture.  The
+ * incremental stitching engine supports both portrait (Mode B,
+ * horizontal pan) and landscape (Mode A, vertical pan) capture
+ * modes as first-class — but mixing them mid-capture produces
+ * malformed output ("cross-mode capture is best-effort," per
+ * `incremental.ts:373-403`).  Hosts that want to protect against
+ * this use this hook + `OrientationDriftModal` together: the
+ * `<Camera>` flagship component auto-abandons capture the instant
+ * `drifted === true` (PR-2 wiring); the modal surfaces an
+ * explanatory popup to the user.
+ *
+ * ## API contract
+ *
+ * Pass `active` true while a capture is in flight, false otherwise.
+ * Returns:
+ *
+ *   - `captureOrientation` — the orientation snapshotted at the
+ *     moment `active` transitioned false → true.  `undefined` when
+ *     `active` is false.
+ *   - `currentOrientation` — live orientation from
+ *     `useDeviceOrientation()`.  Always defined (defaults to
+ *     `'portrait'` until the accelerometer's first sample).
+ *   - `drifted` — `true` IFF `active` is currently true AND
+ *     `currentOrientation !== captureOrientation` at some point
+ *     since the snapshot.  **Latching** — once true, stays true
+ *     until `active` flips back to false.  This is intentional:
+ *     after detection, callers should auto-abandon the capture
+ *     (engine `stop()`); allowing the flag to clear before then
+ *     would mask the drift if the user rotated back to the
+ *     original orientation between the detection tick and the
+ *     callers' abandonment effect.
+ *
+ * ## Semantics by transition
+ *
+ *   - `active` false → true:  snapshot `currentOrientation`;
+ *     reset `drifted` to false.
+ *   - `active` true (steady):  if `currentOrientation !==
+ *     captureOrientation` at any point, latch `drifted = true`.
+ *   - `active` true → false:  clear snapshot; reset `drifted`.
+ *
+ * ## Why a separate hook (rather than inlining in `<Camera>`)
+ *
+ * Hosts using the Layer-2 building blocks (`CameraView` directly,
+ * custom capture UX) can reuse this hook without mounting the
+ * full `<Camera>` flagship.  Same composition pattern as
+ * `useIMUTranslationGate` and `useKeyframeStream`.
+ *
+ * ## Testing
+ *
+ * The pure state-transition function `_computeDriftStateForTests`
+ * is exported separately so jest can exercise all 5 transition
+ * cases without booting a React render.  The hook itself is a
+ * thin wrapper around it (verified via on-device manual flow in
+ * the v0.12 verification checklist).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._computeDriftStateForTests = _computeDriftStateForTests;
+exports.useOrientationDrift = useOrientationDrift;
+const react_1 = require("react");
+const useDeviceOrientation_1 = require("./useDeviceOrientation");
+const INITIAL_STATE = {
+    captureOrientation: undefined,
+    drifted: false,
+};
+/**
+ * Pure state-transition function for the drift detector.  Exported
+ * with a `_` prefix to signal "internal — not part of the public
+ * API."  Jest uses this directly so tests don't need a React
+ * renderer (the lib's jest config is pure-data / no RN preset).
+ *
+ * Given the previous state + the current `active` flag + the
+ * current device orientation, returns the new state.  Idempotent
+ * when nothing changed (returns the same object reference) so
+ * downstream `useState(setState)` calls become no-ops.
+ */
+function _computeDriftStateForTests(prev, active, currentOrientation) {
+    if (!active) {
+        // active is false (or just transitioned to false).  Clear the
+        // snapshot + drift flag.  Idempotent when already cleared.
+        if (prev.captureOrientation === undefined && !prev.drifted) {
+            return prev;
+        }
+        return INITIAL_STATE;
+    }
+    // active is true.
+    if (prev.captureOrientation === undefined) {
+        // false → true transition.  Snapshot the current orientation.
+        // drifted starts false because, by definition, the current
+        // orientation matches itself.
+        return { captureOrientation: currentOrientation, drifted: false };
+    }
+    // active is steady true.  Check for drift.  Latching: once
+    // drifted is true, never set it back to false until active
+    // flips (handled above).
+    if (!prev.drifted && currentOrientation !== prev.captureOrientation) {
+        return { captureOrientation: prev.captureOrientation, drifted: true };
+    }
+    // No transition + no new drift.  Return prev to avoid an
+    // unnecessary state update + re-render.
+    return prev;
+}
+function useOrientationDrift(active) {
+    const currentOrientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
+    const [state, setState] = (0, react_1.useState)(INITIAL_STATE);
+    (0, react_1.useEffect)(() => {
+        setState((prev) => _computeDriftStateForTests(prev, active, currentOrientation));
+    }, [active, currentOrientation]);
+    return {
+        drifted: state.drifted,
+        captureOrientation: state.captureOrientation,
+        currentOrientation,
+    };
+}
+//# sourceMappingURL=useOrientationDrift.js.map

package/dist/index.d.ts

@@ -61,6 +61,11 @@ export { useCapture } from './camera/useCapture';
 export type { TakePhotoCallOptions } from './camera/useCapture';
 export { useVideoCapture } from './camera/useVideoCapture';
 export { useDeviceOrientation } from './camera/useDeviceOrientation';
+export type { DeviceOrientation } from './camera/useDeviceOrientation';
+export { useOrientationDrift } from './camera/useOrientationDrift';
+export type { UseOrientationDriftReturn } from './camera/useOrientationDrift';
+export { OrientationDriftModal } from './camera/OrientationDriftModal';
+export type { OrientationDriftModalProps } from './camera/OrientationDriftModal';
 export { IncrementalOutcome, incrementalStitcherIsAvailable, subscribeIncrementalState, getIncrementalNativeModule, cleanupOldKeyframes, } from './stitching/incremental';
 export type { IncrementalState, AcceptedKeyframe } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';

package/dist/index.js

@@ -22,7 +22,7 @@
  * adds RetaiLens-specific features on top.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+exports.stitchVideo = exports.useStitcherWorklet = exports.useFrameProcessorDriver = exports.useFrameStream = exports.useThrottledFrameProcessor = exports.useFrameProcessor = exports.useKeyframeStream = exports.useIncrementalStitcher = exports.cleanupOldKeyframes = exports.getIncrementalNativeModule = exports.subscribeIncrementalState = exports.incrementalStitcherIsAvailable = exports.IncrementalOutcome = exports.OrientationDriftModal = exports.useOrientationDrift = exports.useDeviceOrientation = exports.useVideoCapture = exports.useCapture = exports.ViewportCropOverlay = exports.hybridSettingsToNativeConfig = exports.slitscanSettingsToNativeConfig = exports.panoramaSettingsToNativeConfig = exports.DEFAULT_HYBRID_SETTINGS = exports.DEFAULT_SLITSCAN_SETTINGS = exports.DEFAULT_FLOW_GATE_SETTINGS = exports.DEFAULT_PANORAMA_SETTINGS = exports.PanoramaSettingsModal = exports.PanoramaGuidance = exports.PanoramaBandOverlay = exports.IncrementalPanGuide = exports.CaptureThumbnailStrip = exports.useStitchStatsToast = exports.CaptureStitchStatsToast = exports.CaptureOrientationPill = exports.CaptureKeyframePill = exports.CaptureMemoryPill = exports.CaptureDebugOverlay = exports.CaptureStatusOverlay = exports.CapturePreview = exports.CaptureControlsBar = exports.CaptureHeader = exports.CameraView = exports.ARCameraView = exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
 // ─────────────────────────────────────────────────────────────────────
 // Layer 1 — the high-level <Camera> component
 // ─────────────────────────────────────────────────────────────────────
@@ -126,6 +126,17 @@ var useVideoCapture_1 = require("./camera/useVideoCapture");
 Object.defineProperty(exports, "useVideoCapture", { enumerable: true, get: function () { return useVideoCapture_1.useVideoCapture; } });
 var useDeviceOrientation_1 = require("./camera/useDeviceOrientation");
 Object.defineProperty(exports, "useDeviceOrientation", { enumerable: true, get: function () { return useDeviceOrientation_1.useDeviceOrientation; } });
+// v0.12.0 — orientation-aware Camera (R2-lite).  `useOrientationDrift`
+// snapshots the device orientation at capture start and latches a
+// `drifted` flag if the user rotates mid-capture.  Pairs with
+// `OrientationDriftModal` for the auto-abandon UX flow.  The
+// flagship `<Camera>` component wires both internally (PR-2);
+// Layer-2 hosts using `CameraView` directly can compose the pair
+// manually (see the modal's docstring for the integration pattern).
+var useOrientationDrift_1 = require("./camera/useOrientationDrift");
+Object.defineProperty(exports, "useOrientationDrift", { enumerable: true, get: function () { return useOrientationDrift_1.useOrientationDrift; } });
+var OrientationDriftModal_1 = require("./camera/OrientationDriftModal");
+Object.defineProperty(exports, "OrientationDriftModal", { enumerable: true, get: function () { return OrientationDriftModal_1.OrientationDriftModal; } });
 // ── Incremental stitching engine ──────────────────────────────────────
 // JS bindings around the native `IncrementalStitcher` module.  Use
 // these when you need finer control than <Camera>'s built-in

package/dist/stitching/incremental.d.ts

@@ -127,9 +127,11 @@ export interface IncrementalState {
      * at the FIRST-FRAME determination thereafter.
      *
      * **This is the single source of truth for orientation across
-     * the SDK + host.**  JS-side hooks (e.g. `useDeviceOrientation`,
-     * `useWindowDimensions`) are unreliable when iOS interface-
-     * orientation lock is on; pose-derived detection is.  UI
+     * the SDK + host.**  Pose-derived detection is preferred over
+     * JS-side hooks because it works identically regardless of host
+     * configuration — `useWindowDimensions` reports JS-portrait when
+     * the host is portrait-locked (even with the device in landscape),
+     * while pose data reflects what the camera actually saw.  UI
      * components that need to know orientation (band overlay, dim
      * bars, pan guide) MUST consume `state.isLandscape` rather
      * than re-detecting.

package/ios/Sources/RNImageStitcher/ARSessionBridge.swift

@@ -99,9 +99,15 @@ public final class RNSARSessionBridge: NSObject {
     ) {
         let path = (options["path"] as? String) ?? ""
         let quality = (options["quality"] as? Int) ?? 90
+        // v0.12.0 — host passes the actual device orientation so
+        // the saved JPEG matches the user's view.  Defaults to
+        // "portrait" if absent, preserving pre-v0.12 behavior for
+        // any caller that hasn't been updated.
+        let orientation = (options["orientation"] as? String) ?? "portrait"
         RNSARSession.shared.takePhoto(
             toPath: path,
-            quality: quality
+            quality: quality,
+            orientation: orientation
         ) { result, error in
             if let error = error {
                 rejecter("ar-photo-failed", error.localizedDescription, error)

package/ios/Sources/RNImageStitcher/OpenCVIncrementalStitcher.h

@@ -100,9 +100,10 @@ typedef NS_ENUM(NSInteger, RLISFrameOutcome) {
 /// JS side reads this from `IncrementalState.isLandscape` to drive
 /// orientation-aware UI (band overlay, dim bars).  This is the
 /// single source of truth for orientation across the SDK + host —
-/// the V12.6 fix established that JS-side orientation hooks are
-/// unreliable under iOS interface-orientation lock; pose detection
-/// is.
+/// pose-derived detection (V12.6) is preferred because it works
+/// regardless of host orientation config (portrait-locked hosts
+/// suppress framebuffer rotation, so `useWindowDimensions` lies
+/// about the physical hold; pose data doesn't).
 @property (nonatomic, readonly) BOOL isLandscape;
 
 /// V12.14.9 — running max paint position along the pan axis, in

package/ios/Sources/RNImageStitcher/OpenCVIncrementalStitcher.mm

@@ -305,13 +305,15 @@ constexpr double kRansacReprojThresh = 5.0;
         _frameRotationDegrees = frameRotationDegrees;
         // V12.6 Step C: _isLandscape is no longer derived from the
         // JS-passed frameRotationDegrees.  V12.5 telemetry proved
-        // JS was sending the wrong value when iOS orientation-lock
-        // suppressed the rotation event (always reported portrait
-        // even in landscape).  We now detect at first-frame init
-        // from R_panToCam directly — see the cylindricalWarp's
-        // first-frame branch.  Default false here is just a safe
-        // initialiser; it WILL be overwritten before any warping
-        // happens.
+        // JS was sending the wrong value under portrait-locked
+        // hosts (the lock suppresses RN's rotation event so
+        // `useWindowDimensions` always reported portrait even in
+        // landscape).  We now detect at first-frame init from
+        // R_panToCam directly — see the cylindricalWarp's
+        // first-frame branch.  Pose-derived detection works for
+        // both portrait-locked and non-locked R2-lite hosts.
+        // Default false here is just a safe initialiser; it WILL
+        // be overwritten before any warping happens.
         _isLandscape = NO;
         // Default compose dims preserve the 4:3 sensor aspect
         // (1920x1440 → 960x720 at scale 0.5).  Always landscape

package/ios/Sources/RNImageStitcher/RNSARSession.swift

@@ -813,6 +813,7 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
     @objc public func takePhoto(
         toPath rawPath: String,
         quality: Int,
+        orientation: String,
         completion: @escaping ([String: Any]?, NSError?) -> Void
     ) {
         let resolvedPath: String
@@ -835,14 +836,52 @@ public final class RNSARSession: NSObject, ARSessionDelegate {
         }
         let pixelBuffer = frame.capturedImage
 
-        // ARKit's capturedImage is in landscape sensor orientation
-        // regardless of how the device is held.  Rotate to portrait
-        // (the way the user is holding the phone for shelf audits)
-        // by applying a 90° clockwise CIImage orientation.  Without
-        // this, photos appear sideways in any consumer that doesn't
-        // honour EXIF (RN's <Image>, the OpenCV stitcher).
+        // v0.12.0 — Pre-v0.12 this method hardcoded `.right` (90° CW)
+        // to rotate-to-portrait, assuming the user always held the
+        // phone in portrait.  Under R2-lite the device can be in
+        // any orientation, so we pick the CIImage orientation per
+        // the JS-supplied `orientation` arg (from
+        // `useDeviceOrientation()`).
+        //
+        // Empirical mapping (on-device test 2026-05-28):
+        //   portrait              → .right  (90° CW — preserved from pre-v0.12)
+        //   landscape-left        → .up     (sensor matches device tilt; no rotation)
+        //   landscape-right       → .down   (180° — sensor opposite of device tilt)
+        //   portrait-upside-down  → .left   (90° CCW)
+        //
+        // The landscape mapping (landscape-left → .up) was determined
+        // empirically and is the opposite of what Apple's ARKit
+        // pixel-buffer-orientation docs would imply.  Likely because
+        // `useDeviceOrientation()` reports `landscape-left` via the
+        // `UIDeviceOrientation` convention (home indicator on user-
+        // right) while iOS's sensor-native orientation matches that
+        // tilt direction directly.  Without this fix, AR-mode single
+        // photos in landscape come out upside-down.
+        // v0.12.0 — Pre-v0.12 this method hardcoded `.right` (90° CW)
+        // to rotate-to-portrait, assuming the user always held the
+        // phone in portrait.  Under R2-lite the device can be in
+        // any orientation, so we pick the CIImage orientation per
+        // the JS-supplied `orientation` arg (from
+        // `useDeviceOrientation()`).
+        //
+        // Empirical mapping (on-device test 2026-05-28):
+        //   portrait              → .right  (90° CW — preserved from pre-v0.12)
+        //   landscape-left        → .up     (sensor matches device tilt; no rotation)
+        //   landscape-right       → .down   (180° — sensor opposite of device tilt)
+        //   portrait-upside-down  → .left   (90° CCW)
+        //
+        // The landscape mapping (landscape-left → .up) was determined
+        // empirically; the user reported AR landscape photos came out
+        // upside-down with .down and correctly upright with .up.
+        let exifOrientation: CGImagePropertyOrientation
+        switch orientation {
+        case "landscape-left":        exifOrientation = .up
+        case "landscape-right":       exifOrientation = .down
+        case "portrait-upside-down":  exifOrientation = .left
+        default:                       exifOrientation = .right  // portrait + unknown
+        }
         let ciImage = CIImage(cvPixelBuffer: pixelBuffer)
-            .oriented(.right)
+            .oriented(exifOrientation)
         let context = CIContext(options: nil)
         guard let cgImage = context.createCGImage(
             ciImage,

package/package.json

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

package/src/camera/ARCameraView.tsx

@@ -84,7 +84,23 @@ export interface ARCameraViewHandle {
    * isMirrored, isRawPhoto }`).  Native generates a temp path —
    * caller does NOT need to construct one.
    */
-  takePhoto: (options?: { quality?: number }) => Promise<{
+  takePhoto: (options?: {
+    quality?: number;
+    /**
+     * v0.12.0 — device orientation at capture time, used to bake
+     * correct rotation into the saved JPEG.  Pass the value from
+     * `useDeviceOrientation()`.  Defaults to `'portrait'` on the
+     * native side if omitted (preserves pre-v0.12 behavior).
+     * Without this, AR-mode photos taken in landscape come out
+     * sideways because the native side previously hardcoded the
+     * rotate-to-portrait assumption.
+     */
+    orientation?:
+      | 'portrait'
+      | 'portrait-upside-down'
+      | 'landscape-left'
+      | 'landscape-right';
+  }) => Promise<{
     path: string;
     width: number;
     height: number;
@@ -149,6 +165,7 @@ export const ARCameraView = forwardRef<ARCameraViewHandle, ARCameraViewProps>(
         return native.takePhoto({
           path: '',
           quality: options.quality ?? 90,
+          orientation: options.orientation ?? 'portrait',
         });
       },
       startRecording: (options) => {