react-native-image-stitcher 0.11.0 → 0.12.0

package/src/camera/Camera.tsx

@@ -52,6 +52,7 @@ import {
   StyleSheet,
   Text,
   View,
+  useWindowDimensions,
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
@@ -82,7 +83,9 @@ import {
 } from './buildPanoramaInitialSettings';
 import { isLowMemDevice } from './lowMemDevice';
 import { useCapture } from './useCapture';
-import { useDeviceOrientation } from './useDeviceOrientation';
+import { useDeviceOrientation, type DeviceOrientation } from './useDeviceOrientation';
+import { useOrientationDrift } from './useOrientationDrift';
+import { OrientationDriftModal } from './OrientationDriftModal';
 import {
   getIncrementalNativeModule,
   incrementalStitcherIsAvailable,
@@ -293,6 +296,27 @@ export interface CameraProps {
   onFramesDropped?: (info: FramesDroppedInfo) => void;
   onError?: (err: CameraError) => void;
 
+  /**
+   * v0.12.0 — fires when the SDK auto-abandons an in-progress
+   * capture without producing output.  `reason` is a string union
+   * so future reasons (network loss, low memory, etc.) can be added
+   * without breaking the callback signature.
+   *
+   * Currently the only reason in v0.12 is `'orientation-drift'`:
+   * the user rotated the device between Mode A (landscape + vertical
+   * pan) and Mode B (portrait + horizontal pan) mid-capture.  The
+   * engine docstring at `incremental.ts:373-403` is explicit that
+   * cross-mode capture is "best-effort, not supported," so the SDK
+   * decisively cancels the capture (`incremental.cancel()`) and
+   * surfaces `OrientationDriftModal` to explain what happened.
+   *
+   * Hosts use this callback to clean up their own state (e.g., reset
+   * a wizard step, log telemetry, surface their own retry UX in
+   * addition to the SDK's built-in modal).  No `onCapture` will fire
+   * for an abandoned capture.
+   */
+  onCaptureAbandoned?: (reason: 'orientation-drift') => void;
+
   /**
    * Optional host-supplied vision-camera frame processor.
    *
@@ -656,11 +680,20 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onLensChange,
     onFramesDropped,
     onError,
+    onCaptureAbandoned,
     frameProcessor: hostFrameProcessor,
     engine = 'batch-keyframe',
   } = props;
 
   const insets = useSafeAreaInsets();
+  // v0.12.0 — JS-layout orientation independent of device-physical.
+  // `useWindowDimensions().width > height` tells us if the OS
+  // rotated the framebuffer (only happens for non-locked hosts in
+  // device-landscape).  Combined with `useDeviceOrientation()` to
+  // pick the JS edge corresponding to the home-indicator side of
+  // the device — see `homeIndicatorEdge` below.
+  const jsWindow = useWindowDimensions();
+  const jsLandscape = jsWindow.width > jsWindow.height;
 
   // ── State ───────────────────────────────────────────────────────
   const [arPreference, setArPreference] = useState(
@@ -857,6 +890,64 @@ export function Camera(props: CameraProps): React.JSX.Element {
   // eslint-disable-next-line react-hooks/exhaustive-deps
   useEffect(() => () => { fpDriver.stop(); }, []);
 
+  // ── v0.12.0 — Orientation drift detection + auto-abandon ────────
+  //
+  // The incremental engine supports both portrait (Mode B, horizontal
+  // pan) and landscape (Mode A, vertical pan) capture as first-class,
+  // but the docstring at `incremental.ts:373-403` is explicit that
+  // mixing them mid-capture is "best-effort, not supported" — the
+  // output rotation becomes ambiguous and the stitched panorama is
+  // malformed.  v0.12 protects against this by snapshotting the
+  // orientation at `start()` and auto-cancelling the capture the
+  // instant the user rotates to a different orientation mid-flight.
+  //
+  // The modal is informational only — by the time it renders, the
+  // capture is already stopped.  No Continue/Resume affordance per
+  // the engine spec.
+  const drift = useOrientationDrift(statusPhase === 'recording');
+  const [driftModalDismissed, setDriftModalDismissed] = useState(false);
+  // Reset the dismissed flag when a new capture starts (or any non-
+  // recording state) so the next drift event surfaces a fresh modal.
+  useEffect(() => {
+    if (statusPhase !== 'recording') setDriftModalDismissed(false);
+  }, [statusPhase]);
+
+  useEffect(() => {
+    if (!drift.drifted || statusPhase !== 'recording') return;
+    // Auto-abandon the in-flight capture.  Order matches handleHoldEnd's
+    // "stitch" path but skips finalize:
+    //   1. Stop pumping frames so no new keyframes arrive mid-cancel.
+    //   2. Tell the native engine to drop accumulated state
+    //      (`incremental.cancel()`).
+    //   3. Reset statusPhase back to idle.
+    //   4. Notify the host via `onCaptureAbandoned`.
+    //
+    // Wrapped in an IIFE because useEffect callbacks can't be async
+    // directly.  Errors from `incremental.cancel()` are caught + sent
+    // through `onError` — abandonment must succeed even if the engine
+    // is in a weird state.
+    void (async () => {
+      fpDriver.stop();
+      try {
+        await incremental.cancel();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        onError?.(new CameraError(
+          'PANORAMA_FINALIZE_FAILED',
+          `cancel after orientation drift failed: ${message}`,
+          err,
+        ));
+      } finally {
+        setStatusPhase('idle');
+        setRecordingStartedAt(null);
+        onCaptureAbandoned?.('orientation-drift');
+      }
+    })();
+    // Deps: re-run whenever drift latches OR recording state changes.
+    // Other deps are stable refs / setters.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [drift.drifted, statusPhase]);
+
   // v0.8.0 Phase 5 / v0.11.0 — frameProcessor prop semantics:
   //
   //   - Host supplied? → use host's processor.  The host's worklet
@@ -991,7 +1082,14 @@ export function Camera(props: CameraProps): React.JSX.Element {
         // ARCameraView writes to its own tmp location; relocate to
         // photoOutputPath via the native FileBridge so both branches
         // return paths under the same dir.
-        const photo = await arViewRef.current.takePhoto({ quality: 90 });
+        // v0.12.0 — pass deviceOrientation so the AR takePhoto's
+        // native CIImage rotation matches the user's view.  Pre-
+        // v0.12 the native side hardcoded portrait, so landscape
+        // photos came out sideways.
+        const photo = await arViewRef.current.takePhoto({
+          quality: 90,
+          orientation: deviceOrientation,
+        });
         try {
           await moveFile(photo.path, photoOutputPath);
         } catch (moveErr) {
@@ -1370,29 +1468,43 @@ export function Camera(props: CameraProps): React.JSX.Element {
       )}
 
       {/*
-        Bottom area: stacks the live-frame band ABOVE the shutter row
-        so the band is tethered to the shutter on the viewport side
-        (the operator's eye is drawn from the camera preview, down
-        the band, into the shutter — a single continuous reading
-        path).  With the SDK's orientation lock holding the UI in
-        portrait, this stack works the same regardless of how the
-        device is physically held.
+        v0.12.0 — Orientation-aware bottom controls anchored to the
+        physical home-indicator edge.  The shutter follows the home-
+        indicator regardless of host portrait-lock state:
+          - locked + any device              → JS-bottom (locked
+            framebuffer maps device-bottom to JS-bottom always)
+          - non-locked + device-portrait     → JS-bottom
+          - non-locked + device-landscape-L  → JS-right
+          - non-locked + device-landscape-R  → JS-left
+        Computed in `homeIndicatorEdge` which combines `jsLandscape`
+        (from window dims) with `deviceOrientation` (sensor).
       */}
       <View
         pointerEvents="box-none"
-        style={[styles.bottomArea, { paddingBottom: insets.bottom + 12 }]}
+        style={bottomAreaStyleForEdge(
+          homeIndicatorEdge(jsLandscape, deviceOrientation),
+          insets.bottom + 12,
+          insets.top + 12,
+        )}
       >
-        {/* Live-frame band — only visible while recording. */}
+        {/* Live-frame band — only visible while recording.  `vertical`
+            is true when the home-indicator anchor is on a side edge
+            (left or right), in which case the band is a vertical
+            column.  Otherwise it's a horizontal strip. */}
         {statusPhase === 'recording' && (
           <PanoramaBandOverlay
             state={incrementalState}
             frameUris={batchKeyframeThumbnails}
             captureOrientation={deviceOrientation}
+            vertical={isSideEdge(homeIndicatorEdge(jsLandscape, deviceOrientation))}
           />
         )}
 
-        {/* Shutter row: lens chip (left), shutter (centre), AR toggle (right). */}
-        <View style={styles.bottomBar}>
+        {/* Shutter row.  Horizontal row when home-indicator is on
+            top/bottom (lens left / shutter center / AR right);
+            vertical column when on left/right (slots stack along
+            the narrow strip).  Touch targets stay axis-aligned. */}
+        <View style={bottomBarStyleForEdge(homeIndicatorEdge(jsLandscape, deviceOrientation))}>
         <View style={styles.bottomBarLeft} />
         <View style={styles.bottomBarCenter}>
           <LensChip
@@ -1425,6 +1537,19 @@ export function Camera(props: CameraProps): React.JSX.Element {
         onChange={setSettings}
         onClose={() => setSettingsModalVisible(false)}
       />
+
+      {/* v0.12.0 — Orientation drift modal.  Shows AFTER the SDK has
+          auto-abandoned the capture (the useEffect above stops the
+          engine + transitions to idle + fires onCaptureAbandoned).
+          Modal exists purely to explain WHY the capture was
+          cancelled.  Single OK button (no Continue) per the engine
+          spec on cross-mode capture being best-effort, not supported. */}
+      <OrientationDriftModal
+        visible={drift.drifted && !driftModalDismissed}
+        captureOrientation={drift.captureOrientation}
+        currentOrientation={drift.currentOrientation}
+        onAcknowledge={() => setDriftModalDismissed(true)}
+      />
     </View>
   );
 }
@@ -1435,6 +1560,148 @@ function noop(): void {
 }
 
 
+/**
+ * v0.12.0 — JS edge corresponding to the physical home-indicator
+ * side of the device.  This is where the shutter + controls anchor
+ * to so they're always within thumb reach of the user's grip
+ * (matching iOS Camera's behaviour).
+ *
+ * Combines two signals:
+ *   - `jsLandscape`: whether the OS rotated the framebuffer.  True
+ *     only for non-locked hosts in device-landscape.
+ *   - `deviceOrient`: physical device orientation from the sensor.
+ *
+ * Truth table:
+ *   | jsLandscape | deviceOrient        | edge   |
+ *   |---           |---                  |---     |
+ *   | false        | any                 | bottom | (portrait JS coords —
+ *   |              |                     |        |  device-bottom = JS-bottom
+ *   |              |                     |        |  in both locked and
+ *   |              |                     |        |  non-locked-portrait)
+ *   | true         | landscape-left      | right  | (screen rotated, home
+ *   |              |                     |        |  indicator on user-right)
+ *   | true         | landscape-right     | left   | (mirror)
+ *
+ * Caveats:
+ *   - Non-locked + upside-down doesn't surface JS-top here because
+ *     upside-down doesn't change window dimensions; we can't
+ *     distinguish locked-portrait-with-device-flipped from
+ *     non-locked-portrait-with-screen-flipped-180°.  Defaults to
+ *     JS-bottom which matches the more common locked case.  Add
+ *     handling here when a host needs upside-down support.
+ *   - jsLandscape=true with non-landscape device shouldn't happen
+ *     in steady state — only during a transition mid-rotation.
+ *     Falls through to 'right' as a defensive default.
+ */
+type HomeIndicatorEdge = 'bottom' | 'top' | 'left' | 'right';
+
+function homeIndicatorEdge(
+  jsLandscape: boolean,
+  deviceOrient: DeviceOrientation,
+): HomeIndicatorEdge {
+  if (!jsLandscape) return 'bottom';
+  if (deviceOrient === 'landscape-left') return 'right';
+  if (deviceOrient === 'landscape-right') return 'left';
+  return 'right';
+}
+
+
+/**
+ * v0.12.0 — true when the anchor edge is on a side (left/right), so
+ * the band + shutter row need to be vertical strips.  Top/bottom
+ * anchors yield horizontal strips.
+ */
+function isSideEdge(edge: HomeIndicatorEdge): boolean {
+  return edge === 'left' || edge === 'right';
+}
+
+
+/**
+ * v0.12.0 — bottom-controls outer container positioning.  Anchors
+ * to the home-indicator JS edge with the appropriate flex direction
+ * so the band sits on the viewport side of the shutter (toward the
+ * camera preview centre).
+ */
+function bottomAreaStyleForEdge(
+  edge: HomeIndicatorEdge,
+  bottomInsetPx: number,
+  topInsetPx: number,
+): ViewStyle {
+  switch (edge) {
+    case 'bottom':
+      // Band above shutter row, both at JS-bottom.  JSX order
+      // [band, shutter] + flexDirection 'column' = band at top of
+      // stack (closer to screen centre), shutter at JS-bottom.
+      return {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        bottom: 0,
+        flexDirection: 'column',
+        alignItems: 'stretch',
+        paddingBottom: bottomInsetPx,
+      };
+    case 'top':
+      // Mirror of bottom.  column-reverse so JSX [band, shutter]
+      // renders [shutter, band] in JS, shutter at JS-top, band
+      // below it (toward screen centre).
+      return {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        top: 0,
+        flexDirection: 'column-reverse',
+        alignItems: 'stretch',
+        paddingTop: topInsetPx,
+      };
+    case 'right':
+      // Band to the left of shutter column, both at JS-right.
+      // flexDirection 'row' + JSX [band, shutter] = band at JS-left
+      // of container (screen centre side), shutter at JS-right.
+      return {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        right: 0,
+        flexDirection: 'row',
+        alignItems: 'stretch',
+        paddingRight: 12,
+      };
+    case 'left':
+      // Mirror of right.  row-reverse so JSX [band, shutter] gives
+      // band at JS-right (screen centre side), shutter at JS-left.
+      return {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        left: 0,
+        flexDirection: 'row-reverse',
+        alignItems: 'stretch',
+        paddingLeft: 12,
+      };
+  }
+}
+
+
+/**
+ * v0.12.0 — inner shutter-row flex direction.  Horizontal row for
+ * top/bottom anchors; vertical column for left/right anchors so
+ * the three slots (lens / shutter / AR) stack along the narrow
+ * side strip.  Buttons don't rotate — touch targets and text
+ * orient correctly via either (a) un-rotated framebuffer under
+ * portrait-lock or (b) OS-rotated framebuffer under non-locked.
+ */
+function bottomBarStyleForEdge(edge: HomeIndicatorEdge): ViewStyle {
+  const vertical = isSideEdge(edge);
+  return {
+    flexDirection: vertical ? 'column' : 'row',
+    paddingHorizontal: vertical ? 0 : 18,
+    paddingVertical: vertical ? 18 : 0,
+    alignItems: 'center',
+  };
+}
+
+
 const styles = StyleSheet.create({
   container: {
     flex: 1,

package/src/camera/OrientationDriftModal.tsx

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OrientationDriftModal — informational popup shown when the SDK
+ * auto-abandons an in-progress capture because the device rotated
+ * between Mode A (landscape + vertical pan) and Mode B (portrait
+ * + horizontal pan) mid-flight.
+ *
+ * ## When this modal appears
+ *
+ * In the v0.12 `<Camera>` integration, the modal is rendered while
+ * `useOrientationDrift(active).drifted === true`.  By the time the
+ * modal renders, the capture has ALREADY been stopped (the
+ * `<Camera>` component's drift effect calls the engine's `stop()`
+ * the same render).  The modal exists solely to explain to the
+ * user what happened — no "Continue" / "Resume" affordance because
+ * the engine docstring at `incremental.ts:373-403` is explicit
+ * that cross-mode capture is "best-effort, not supported" and
+ * continuing past drift produces malformed output.
+ *
+ * ## Layer-2 host usage
+ *
+ * Hosts using `CameraView` directly (rather than the flagship
+ * `<Camera>`) can compose this modal with `useOrientationDrift`
+ * for the same auto-abandon UX:
+ *
+ *   const drift = useOrientationDrift(captureActive);
+ *   useEffect(() => {
+ *     if (drift.drifted) {
+ *       // host abandons capture (engine stop + state cleanup)
+ *       stopCapture();
+ *     }
+ *   }, [drift.drifted]);
+ *
+ *   return <>
+ *     <CameraView ... />
+ *     <OrientationDriftModal
+ *       visible={drift.drifted}
+ *       captureOrientation={drift.captureOrientation}
+ *       currentOrientation={drift.currentOrientation}
+ *       onAcknowledge={dismissDriftModal}
+ *     />
+ *   </>;
+ *
+ * ## Accessibility
+ *
+ * Modal `role` defaults to RN's native dialog handling.  The OK
+ * button carries an `accessibilityRole='button'` + label.  Body
+ * text uses `accessibilityRole='text'` so the orientation summary
+ * is read by VoiceOver / TalkBack.
+ */
+
+import React from 'react';
+import { Modal, Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { type DeviceOrientation } from './useDeviceOrientation';
+
+
+export interface OrientationDriftModalProps {
+  /**
+   * Show / hide.  In the `<Camera>` integration this is driven by
+   * the latched `drifted` flag from `useOrientationDrift`.
+   */
+  visible: boolean;
+
+  /**
+   * Orientation the capture started in.  Shown in the body copy
+   * ("Capture started in PORTRAIT") so the user understands the
+   * baseline.  `undefined` is tolerated (the modal hides the line);
+   * the prop is optional only to mirror `useOrientationDrift`'s
+   * return shape (which has `undefined` when inactive).  When the
+   * modal is `visible`, drift detection means this was non-
+   * undefined at the moment the flag latched — so undefined here
+   * is unlikely in practice.
+   */
+  captureOrientation: DeviceOrientation | undefined;
+
+  /**
+   * Current device orientation.  Shown in the body copy ("now
+   * LANDSCAPE-LEFT") so the user understands what changed.
+   */
+  currentOrientation: DeviceOrientation;
+
+  /**
+   * Tapped when the user dismisses with OK.  By the time the
+   * modal renders the capture is already stopped; this callback
+   * exists only to clear the latched drift state so the next
+   * capture can start fresh.
+   */
+  onAcknowledge: () => void;
+}
+
+
+/**
+ * Pretty-print a `DeviceOrientation` for body copy.  Returns the
+ * uppercase form because the modal copy reads as "Capture started
+ * in PORTRAIT, now LANDSCAPE-LEFT" — uppercase orientations stand
+ * out from the surrounding lowercase sentence.
+ */
+function formatOrientation(o: DeviceOrientation): string {
+  switch (o) {
+    case 'portrait':
+      return 'PORTRAIT';
+    case 'portrait-upside-down':
+      return 'PORTRAIT-UPSIDE-DOWN';
+    case 'landscape-left':
+      return 'LANDSCAPE-LEFT';
+    case 'landscape-right':
+      return 'LANDSCAPE-RIGHT';
+  }
+}
+
+
+export function OrientationDriftModal(
+  props: OrientationDriftModalProps,
+): React.JSX.Element {
+  const { visible, captureOrientation, currentOrientation, onAcknowledge } = props;
+
+  return (
+    <Modal
+      visible={visible}
+      transparent
+      animationType="fade"
+      onRequestClose={onAcknowledge}
+      accessibilityLabel="Capture cancelled — orientation drift"
+      // v0.12.0 — see PanoramaSettingsModal for the same prop's
+      // rationale.  Declaring all orientations prevents iOS from
+      // force-rotating the window to portrait when this modal opens
+      // mid-rotation, which would otherwise leave the underlying
+      // <Camera>'s ARSession in a stale-orientation state on dismiss.
+      supportedOrientations={[
+        'portrait',
+        'portrait-upside-down',
+        'landscape-left',
+        'landscape-right',
+      ]}
+    >
+      <View style={styles.backdrop}>
+        <View style={styles.card}>
+          <Text style={styles.title} accessibilityRole="header">
+            Capture cancelled
+          </Text>
+
+          <Text style={styles.body} accessibilityRole="text">
+            Rotation detected mid-capture. Please hold the device
+            steady and try again.
+          </Text>
+
+          {captureOrientation !== undefined && (
+            <Text style={styles.subBody} accessibilityRole="text">
+              Capture started in {formatOrientation(captureOrientation)},
+              now {formatOrientation(currentOrientation)}.
+            </Text>
+          )}
+
+          <Pressable
+            style={({ pressed }) => [
+              styles.button,
+              pressed && styles.buttonPressed,
+            ]}
+            onPress={onAcknowledge}
+            accessibilityRole="button"
+            accessibilityLabel="OK"
+          >
+            <Text style={styles.buttonLabel}>OK</Text>
+          </Pressable>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  backdrop: {
+    flex: 1,
+    backgroundColor: 'rgba(0, 0, 0, 0.6)',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 32,
+  },
+  card: {
+    backgroundColor: '#1c1c1e',
+    borderRadius: 14,
+    paddingHorizontal: 20,
+    paddingVertical: 24,
+    width: '100%',
+    maxWidth: 340,
+  },
+  title: {
+    color: '#fff',
+    fontSize: 18,
+    fontWeight: '600',
+    marginBottom: 12,
+    textAlign: 'center',
+  },
+  body: {
+    color: '#e5e5ea',
+    fontSize: 15,
+    lineHeight: 21,
+    textAlign: 'center',
+    marginBottom: 12,
+  },
+  subBody: {
+    color: '#8e8e93',
+    fontSize: 13,
+    lineHeight: 18,
+    textAlign: 'center',
+    marginBottom: 20,
+  },
+  button: {
+    backgroundColor: '#0a84ff',
+    borderRadius: 10,
+    paddingVertical: 12,
+    alignItems: 'center',
+  },
+  buttonPressed: {
+    backgroundColor: '#0860c0',
+  },
+  buttonLabel: {
+    color: '#fff',
+    fontSize: 17,
+    fontWeight: '600',
+  },
+});