react-native-image-stitcher 0.1.0

package/src/camera/ViewportCropOverlay.tsx

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ViewportCropOverlay — V12.12.
+ *
+ * Translucent dim bars on the camera preview's PAN-AXIS edges
+ * showing where the panorama engine's source-crop is.  Earlier
+ * versions (V12.11 Step B) put the bars on JS-top/bottom because
+ * the engine clipped the long sensor axis (perpendicular to pan
+ * in landscape, along pan in portrait) — that produced visible
+ * bars on the user-LEFT/RIGHT in landscape, which is the WRONG
+ * place: those edges aren't what the engine clips.
+ *
+ * V12.12: engine now clips ALONG the pan axis.  In sensor-native
+ * coords:
+ *   • landscape capture (vertical pan): clip = sensor Y (rows).
+ *     User perceives this as TOP and BOTTOM of their landscape view.
+ *   • portrait capture (horizontal pan): clip = sensor X (cols).
+ *     User perceives this as LEFT and RIGHT of their portrait view.
+ *
+ * In JS coords (the host app is portrait-locked):
+ *   • portrait device: user-left/right == JS-left/right.  Bars on
+ *                       JS-left/right.
+ *   • landscape device: user-top/bottom == JS-left/right (because
+ *                       the user's vertical maps to JS-horizontal
+ *                       under portrait-lock).  Bars on JS-left/right.
+ *
+ * So in BOTH device orientations the bars sit at JS-left and JS-right.
+ * **No orientation detection needed in this component.**  The
+ * engine has already arranged for the clip to manifest at the same
+ * JS edges regardless of physical device orientation.
+ *
+ * Bar width = `(1 - panFraction) / 2` of the JS-horizontal extent.
+ * For the default `kPanAxisFractionRect = 0.70` engine constant,
+ * each bar is 15 % wide — visibly substantial, matching what the
+ * engine clips out per frame.
+ */
+
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+
+export interface ViewportCropOverlayProps {
+  /**
+   * Fraction of the PAN axis the engine keeps per frame, in (0, 1].
+   * E.g. 0.70 for the V12.12 rectilinear engine's
+   * `kPanAxisFractionRect`.  Values ≥ 1 hide the overlay (no clip).
+   */
+  panFraction: number;
+}
+
+
+export function ViewportCropOverlay({
+  panFraction,
+}: ViewportCropOverlayProps): React.JSX.Element | null {
+  if (panFraction >= 1) return null;
+
+  // (1 - panFraction) / 2 of the JS-horizontal extent on each side.
+  const barPercent = `${((1 - panFraction) / 2) * 100}%` as const;
+
+  return (
+    <View pointerEvents="none" style={styles.root}>
+      <View style={[styles.bar, { left: 0, top: 0, bottom: 0, width: barPercent }]} />
+      <View style={[styles.bar, { right: 0, top: 0, bottom: 0, width: barPercent }]} />
+    </View>
+  );
+}
+
+
+const styles = StyleSheet.create({
+  root: {
+    ...StyleSheet.absoluteFillObject,
+  },
+  // Dim bars: translucent black overlay so the underlying camera
+  // preview is still visible (the user gets spatial context for
+  // what's about to leave the frame), but darkened enough to read
+  // as "this is OUTSIDE the capture region."
+  bar: {
+    position: 'absolute',
+    backgroundColor: 'rgba(0, 0, 0, 0.55)',
+  },
+});

package/src/camera/useCapture.ts

@@ -0,0 +1,279 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useCapture — React hook that encapsulates the camera capture state
+ * machine so host apps get a drop-in replacement for the ad-hoc
+ * vision-camera wiring they used to have inline on each screen.
+ *
+ * Responsibilities:
+ *   - Holds the Camera ref for ``takePhoto``.
+ *   - Tracks the device permission state and exposes a request helper.
+ *   - Manages torch / flash state + a toggle helper.
+ *   - Wraps takePhoto with a single-flight guard so a double-tap on
+ *     the shutter button doesn't spawn two captures in parallel.
+ *   - Runs an optional JS-side quality check on the captured image
+ *     before resolving; the host app sees the QualityReport on the
+ *     returned CaptureResult.
+ *
+ * Non-goals:
+ *   - This hook does NOT persist captures.  Host apps hand the
+ *     returned CaptureResult to their own storage layer (WatermelonDB
+ *     insert, Redux dispatch, whatever).
+ *   - Video recording lives in useVideoCapture (TODO).
+ *
+ * The public API is designed to be minimal and replaceable: host apps
+ * that prefer the raw vision-camera API can opt out of this hook and
+ * still use the SDK's quality + stitching modules.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react';
+import {
+  Camera,
+  useCameraDevice,
+  useCameraDevices,
+  useCameraPermission,
+  type PhotoFile,
+  type PhysicalCameraDeviceType,
+  type TakePhotoOptions,
+} from 'react-native-vision-camera';
+
+import { runQualityCheck } from '../quality/runQualityCheck';
+import { normaliseOrientation } from '../quality/normaliseOrientation';
+import type {
+  CaptureResult,
+  QualityReport,
+  QualityThresholds,
+} from '../types';
+
+
+/**
+ * Hook input.  Everything optional; sensible defaults are applied
+ * so simple call-sites can write ``useCapture()`` and get a usable
+ * back-camera pipeline with ``flash=off`` and no quality checking.
+ */
+export interface UseCaptureOptions {
+  /** 'back' | 'front' — defaults to 'back' (shelf photos). */
+  cameraPosition?: 'back' | 'front';
+  /** Quality check toggle + thresholds. */
+  enableQualityChecks?: boolean;
+  qualityThresholds?: QualityThresholds;
+  /**
+   * Extra TakePhotoOptions to pass through to vision-camera.
+   * The SDK merges these with its defaults; host-supplied values win.
+   */
+  takePhotoOptions?: TakePhotoOptions;
+  /**
+   * 2026-05-14 — preferred physical-lens type for the chosen
+   * `cameraPosition`.  Maps to vision-camera's `physicalDevices`
+   * filter on `useCameraDevice`.
+   *
+   *   undefined (default) — use vision-camera's selection algorithm,
+   *                         which picks the device that combines
+   *                         the most lenses (typically the "main"
+   *                         multi-lens virtual camera).  Existing
+   *                         behaviour; backwards-compatible.
+   *   'wide-angle-camera' — 1× physical lens (the standard rear
+   *                         camera most users think of as "the
+   *                         camera").
+   *   'ultra-wide-angle-camera' — 0.5× ultra-wide lens (only on
+   *                         devices with one; Samsung A35 has one;
+   *                         iPhone 11 Pro and later have one).
+   *   'telephoto-camera'  — 2× / 3× telephoto if the device has
+   *                         one.  Rare on field-rep deployments;
+   *                         exposed for symmetry.
+   *
+   * When the preferred type isn't available on the device, the
+   * hook falls back to vision-camera's default selection (i.e.,
+   * behaves as if `preferredPhysicalDevice` was undefined).  The
+   * returned `availablePhysicalDevices` exposes what the device
+   * actually offers so the host can render an appropriate switcher.
+   */
+  preferredPhysicalDevice?: PhysicalCameraDeviceType;
+}
+
+
+/**
+ * Hook output.  Intentionally flat so destructuring a subset is
+ * cheap and the API doesn't force callers to drill into nested
+ * objects for common concerns.
+ */
+export interface UseCaptureReturn {
+  /** Pass to <CameraView ref={ref} /> (or the raw Camera directly). */
+  cameraRef: React.RefObject<Camera | null>;
+  /** The currently selected device — null while vision-camera hasn't picked one. */
+  device: ReturnType<typeof useCameraDevice>;
+  /** True once the user has granted camera permission. */
+  hasPermission: boolean;
+  /** Trigger the system permission sheet.  Resolves to the new state. */
+  requestPermission: () => Promise<boolean>;
+  /** Current flash mode — controlled from host code. */
+  flash: 'off' | 'on';
+  toggleFlash: () => void;
+  /** True while takePhoto is in flight.  Use to disable the shutter button. */
+  isCapturing: boolean;
+  /**
+   * Take a photo.  Single-flight: parallel calls return the in-flight
+   * promise.  Returns a CaptureResult (with an optional QualityReport
+   * when ``enableQualityChecks`` is on).
+   */
+  takePhoto: () => Promise<CaptureResult>;
+  /**
+   * 2026-05-14 — physical lens types available on the chosen
+   * `cameraPosition`.  Computed once at the first vision-camera
+   * device-list emission; useful for the host to decide whether to
+   * render a 0.5×/1× camera switcher chip (only show if both
+   * `wide-angle-camera` AND `ultra-wide-angle-camera` are present).
+   *
+   * Empty array on platforms that haven't enumerated devices yet
+   * (very brief — vision-camera resolves the device list at module
+   * load).  Always populated by the time the camera is mountable.
+   */
+  availablePhysicalDevices: PhysicalCameraDeviceType[];
+}
+
+
+function makeCaptureResult(
+  photo: PhotoFile,
+  qualityReport: QualityReport | undefined,
+): CaptureResult {
+  const capturedAt = new Date().toISOString();
+  return {
+    // The device UUID the host wants to identify this capture with is
+    // app-specific.  We synthesise a deterministic ish value so the
+    // host gets a placeholder; most hosts will swap it out for a uuid
+    // library (react-native-uuid or similar) before persisting.
+    deviceUuid: `${capturedAt}-${photo.path.split('/').pop() ?? 'photo'}`,
+    compressedUri: `file://${photo.path}`,
+    // vision-camera reports width/height post-orientation-correction,
+    // matching what `<Image>` renders.  Forwarding them lets the
+    // SDK's thumbnail strip / preview modal lay out at the correct
+    // aspect ratio instead of forcing square crops.
+    width: photo.width,
+    height: photo.height,
+    isStitched: false,
+    capturedAt,
+    qualityReport,
+    deviceMetadata: {
+      platform: 'ios',
+      osVersion: '',
+      deviceModel: '',
+      cameraId: '',
+      flashEnabled: false,
+    },
+  };
+}
+
+
+export function useCapture(options: UseCaptureOptions = {}): UseCaptureReturn {
+  const {
+    cameraPosition = 'back',
+    enableQualityChecks = false,
+    qualityThresholds,
+    takePhotoOptions,
+    preferredPhysicalDevice,
+  } = options;
+
+  const cameraRef = useRef<Camera | null>(null);
+
+  // 2026-05-14 — physical-lens-aware device picker.
+  //
+  // When `preferredPhysicalDevice` is supplied, ask vision-camera
+  // for a device that exposes that specific physical lens (e.g.,
+  // 'ultra-wide-angle-camera').  Falls back to the position-default
+  // when the device doesn't have that lens.  When undefined, behaves
+  // identically to the pre-2026-05-14 useCameraDevice(position) call.
+  const deviceWithPreferred = useCameraDevice(cameraPosition, {
+    physicalDevices: preferredPhysicalDevice ? [preferredPhysicalDevice] : undefined,
+  });
+  const deviceFallback = useCameraDevice(cameraPosition);
+  const device = deviceWithPreferred ?? deviceFallback;
+
+  // Enumerate ALL physical lens types available on the chosen
+  // position so the host can decide whether to render a switcher.
+  // Vision-camera's `useCameraDevices()` returns CameraDevice[]; each
+  // has `physicalDevices: PhysicalCameraDeviceType[]`.  We dedupe the
+  // union across all devices at `position` so the host sees the full
+  // set the platform exposes (some phones expose ultra-wide only via
+  // a separate logical camera, not the main one).
+  const allDevices = useCameraDevices();
+  const availablePhysicalDevices = useMemo<PhysicalCameraDeviceType[]>(() => {
+    const seen = new Set<PhysicalCameraDeviceType>();
+    for (const d of allDevices) {
+      if (d.position !== cameraPosition) continue;
+      for (const pd of d.physicalDevices ?? []) {
+        seen.add(pd);
+      }
+    }
+    return Array.from(seen);
+  }, [allDevices, cameraPosition]);
+
+  const { hasPermission, requestPermission } = useCameraPermission();
+  const [flash, setFlash] = useState<'off' | 'on'>('off');
+  const [isCapturing, setIsCapturing] = useState(false);
+  // Holds the in-flight takePhoto promise so we don't kick off a second
+  // call while the first is still settling.  Cleared in the finally.
+  const inFlightRef = useRef<Promise<CaptureResult> | null>(null);
+
+  const toggleFlash = useCallback(() => {
+    setFlash((prev) => (prev === 'off' ? 'on' : 'off'));
+  }, []);
+
+  const takePhoto = useCallback(async (): Promise<CaptureResult> => {
+    if (inFlightRef.current) {
+      return inFlightRef.current;
+    }
+    if (!cameraRef.current) {
+      throw new Error(
+        'useCapture.takePhoto: cameraRef is not yet attached. '
+        + 'Render <CameraView ref={cameraRef} /> or the raw Camera with this ref first.',
+      );
+    }
+
+    const promise = (async () => {
+      setIsCapturing(true);
+      try {
+        const photo = await cameraRef.current!.takePhoto({
+          flash,
+          ...takePhotoOptions,
+        });
+        // Bake EXIF rotation into pixels so the file on disk matches
+        // what the operator just saw on the preview, regardless of
+        // how downstream consumers handle EXIF.  Returns the
+        // post-rotation dimensions; we override the photo's
+        // width/height before constructing the CaptureResult so
+        // the SDK contract reports "what's actually saved".
+        const normalised = await normaliseOrientation(photo.path, {
+          width: photo.width,
+          height: photo.height,
+        });
+        const orientedPhoto: PhotoFile = {
+          ...photo,
+          width: normalised.width || photo.width,
+          height: normalised.height || photo.height,
+        };
+
+        let report: QualityReport | undefined;
+        if (enableQualityChecks && qualityThresholds) {
+          report = await runQualityCheck(orientedPhoto.path, qualityThresholds);
+        }
+        return makeCaptureResult(orientedPhoto, report);
+      } finally {
+        setIsCapturing(false);
+        inFlightRef.current = null;
+      }
+    })();
+    inFlightRef.current = promise;
+    return promise;
+  }, [flash, enableQualityChecks, qualityThresholds, takePhotoOptions]);
+
+  return {
+    cameraRef,
+    device,
+    hasPermission,
+    requestPermission,
+    flash,
+    toggleFlash,
+    isCapturing,
+    takePhoto,
+    availablePhysicalDevices,
+  };
+}

package/src/camera/useDeviceOrientation.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useDeviceOrientation — physical device orientation hook.
+ *
+ * The host app is portrait-locked at the iOS app level (so the
+ * camera preview, header, controls, and thumbnails stay in their
+ * portrait positions even when the user holds the phone sideways
+ * for a vertical pan).  But text overlays — the REC banner, the
+ * pan-speed pill, the live frame strip — need to follow the
+ * physical device orientation so they stay readable in the user's
+ * hands.  RN's `useWindowDimensions` can't help with this when
+ * the app is orientation-locked: window dimensions don't change
+ * when only the device rotates.
+ *
+ * 2026-05-18 (Issue #3) — rewritten on top of `expo-sensors`
+ * `DeviceMotion` (CoreMotion-fused on iOS, SensorManager on
+ * Android).  The previous implementation used
+ * `react-native-sensors` raw accelerometer with an Android-only
+ * sign convention (`y > 0` ⇒ portrait), which silently failed on
+ * iOS — Apple's CoreMotion convention is `y < 0` ⇒ portrait
+ * because device-Y points from the phone's bottom to the top,
+ * and gravity in that frame is `-Y`.  Users on iOS saw the hook
+ * stuck at its initial value ('portrait') regardless of physical
+ * rotation, which cascaded into wrong panorama bake-rotation and
+ * a broken landscape band layout.
+ *
+ * Sign conventions used here (per platform docs):
+ *
+ *   iOS (CMDeviceMotion.accelerationIncludingGravity, reported in
+ *   m/s² in the device reference frame):
+ *     portrait              → y ≈ -9.8
+ *     portrait-upside-down  → y ≈ +9.8
+ *     landscape-left  (home indicator on user's RIGHT) → x ≈ +9.8
+ *     landscape-right (home indicator on user's LEFT)  → x ≈ -9.8
+ *
+ *   Android (Sensor.TYPE_ACCELEROMETER, reaction-force convention):
+ *     portrait              → y ≈ +9.8   ← opposite sign vs iOS
+ *     portrait-upside-down  → y ≈ -9.8
+ *     landscape-left        → x ≈ -9.8
+ *     landscape-right       → x ≈ +9.8
+ *
+ *   We flip the Android x/y to match the iOS convention before
+ *   classification so the rest of the logic stays platform-
+ *   independent.  The classification then unambiguously maps to
+ *   the user-visible `DeviceOrientation` enum.
+ */
+
+import { useEffect, useState } from 'react';
+import { DeviceMotion } from 'expo-sensors';
+import type { DeviceMotionMeasurement } from 'expo-sensors';
+
+
+export type DeviceOrientation =
+  | 'portrait'
+  | 'portrait-upside-down'
+  | 'landscape-left'
+  | 'landscape-right';
+
+
+/// Threshold (m/s²) above which gravity dominance is considered
+/// conclusive.  5 m/s² out of ~9.8 means the phone is at least ~30°
+/// tilted toward that axis — comfortable for stable orientation
+/// classification without flipping on minor wobbles.
+const DOMINANT_AXIS_THRESHOLD = 5.0;
+
+/// Sample at ~10 Hz — plenty for orientation detection (phones
+/// don't physically flip faster than this).
+const SAMPLE_INTERVAL_MS = 100;
+
+
+function classify(x: number, y: number): DeviceOrientation | null {
+  // 2026-05-18 (Issue #3 round 2) — re-derived sign convention.
+  //
+  // Through expo-sensors, BOTH platforms normalize to the iOS
+  // CoreMotion gravity-vector convention: stationary phone reports
+  // the gravity vector itself in the device frame.  Device axes:
+  // +X points from phone-left to phone-right; +Y from phone-bottom
+  // to phone-top; +Z out of the screen toward the viewer.
+  //
+  // Per-orientation gravity-vector signs in the device frame:
+  //
+  //   portrait (upright)      → y ≈ -9.8
+  //     Phone-Y points up in world; gravity is along device -Y.
+  //
+  //   portrait-upside-down    → y ≈ +9.8
+  //     Phone-Y points down in world; gravity is along device +Y.
+  //
+  //   landscape-left  (Apple: home indicator on user's RIGHT;
+  //                    phone rotated 90° CCW from portrait):
+  //     phone-X axis points from user-bottom to user-top in this
+  //     orientation, so gravity (world-down) is along device -X.
+  //     → x ≈ -9.8
+  //
+  //   landscape-right (Apple: home indicator on user's LEFT;
+  //                    phone rotated 90° CW from portrait):
+  //     phone-X axis points from user-top to user-bottom, so
+  //     gravity is along device +X.
+  //     → x ≈ +9.8
+  //
+  // The earlier implementation had an Android-specific axis flip
+  // baked in.  Removed — expo-sensors normalizes Android signs to
+  // match iOS, and the platform branch was producing wrong values
+  // (Android portrait → reported as portrait-upside-down; iOS
+  // landscape-left → reported as landscape-right).
+  if (Math.abs(y) > Math.abs(x)) {
+    if (y < -DOMINANT_AXIS_THRESHOLD) return 'portrait';
+    if (y > DOMINANT_AXIS_THRESHOLD) return 'portrait-upside-down';
+  } else {
+    if (x < -DOMINANT_AXIS_THRESHOLD) return 'landscape-left';
+    if (x > DOMINANT_AXIS_THRESHOLD) return 'landscape-right';
+  }
+  // Phone face-up or face-down (z dominates): keep the previous
+  // orientation rather than flicker.
+  return null;
+}
+
+
+export function useDeviceOrientation(): DeviceOrientation {
+  const [orientation, setOrientation] = useState<DeviceOrientation>('portrait');
+
+  useEffect(() => {
+    DeviceMotion.setUpdateInterval(SAMPLE_INTERVAL_MS);
+
+    let last: DeviceOrientation = 'portrait';
+    const sub = DeviceMotion.addListener((m: DeviceMotionMeasurement) => {
+      const g = m.accelerationIncludingGravity;
+      // First emissions can be null on cold start while CoreMotion
+      // warms up; skip until data arrives.
+      if (!g) return;
+      const next = classify(g.x, g.y);
+      if (next && next !== last) {
+        last = next;
+        setOrientation(next);
+      }
+    });
+    return () => sub.remove();
+  }, []);
+
+  return orientation;
+}