react-native-image-stitcher 0.1.0

package/src/camera/useVideoCapture.ts

@@ -0,0 +1,236 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useVideoCapture — video recording + frame extraction API.
+ *
+ * Sibling of ``useCapture`` for the "sweep a shelf with a video" flow
+ * that feeds the stitcher.  The hook's state machine is:
+ *
+ *     idle → recording → stopping → idle  (success)
+ *     idle → recording → idle             (recording errored)
+ *     idle → recording → stopping → idle  (user cancelled)
+ *
+ * API shape — `startRecording` returns a `Promise<VideoFile>` that:
+ *   - resolves with the recorded file when the user releases the
+ *     shutter and `stopRecording()` is called (vision-camera fires
+ *     `onRecordingFinished`),
+ *   - rejects if vision-camera fires `onRecordingError` at any point
+ *     (e.g. `<Camera>` was rendered without `video={true}`, disk
+ *     full mid-recording, permission revoked).
+ *
+ * Why a single future instead of separate finished/error callbacks?
+ *   Lets host code use the natural async/await pattern.  Earlier we
+ *   used a callback + a parked resolver in the host screen; that
+ *   masked start-time errors (the resolver hung forever) and produced
+ *   confusing cascade errors when `stopRecording` ran against a
+ *   non-recording camera.
+ *
+ * Frame extraction lives behind the `extractFrames` method but is
+ * deferred to the higher-level `stitchVideo()` SDK API now — host
+ * apps shouldn't have to manage their own tmp dir.  This shim is
+ * kept for parity / future use; it currently throws.
+ */
+
+import { useCallback, useRef, useState } from 'react';
+import { Camera, type VideoFile } from 'react-native-vision-camera';
+
+
+export type VideoCaptureState =
+  | 'idle'
+  | 'recording'
+  | 'stopping'
+  | 'extracting';
+
+
+export interface UseVideoCaptureReturn {
+  state: VideoCaptureState;
+  /**
+   * Begin recording on the given camera ref.  Returns a Promise that
+   * resolves with the resulting `VideoFile` once `stopRecording()`
+   * has been called and vision-camera writes the file to disk, or
+   * rejects on any recording error.
+   *
+   * Callers who only need fire-and-forget can ignore the returned
+   * promise; the hook still tracks state internally.
+   */
+  startRecording: (
+    cameraRef: React.RefObject<Camera | null>,
+  ) => Promise<VideoFile>;
+  /**
+   * Tell vision-camera to stop the active recording.  If no recording
+   * is in progress (e.g. it errored at start) this is a safe no-op.
+   * The recorded file flows back through the promise returned by
+   * `startRecording`, NOT through this method's return.
+   */
+  stopRecording: (
+    cameraRef: React.RefObject<Camera | null>,
+  ) => Promise<void>;
+  /**
+   * Cancel the active recording without delivering the file.  The
+   * promise from `startRecording` will reject with a cancellation
+   * error so awaiters unblock instead of receiving a stale file.
+   */
+  cancelRecording: (
+    cameraRef: React.RefObject<Camera | null>,
+  ) => Promise<void>;
+  /**
+   * Decode an mp4 into N evenly-spaced still frames, written to
+   * ``outputDir``.  Throws NOT_IMPLEMENTED — call `stitchVideo` from
+   * the SDK index instead, which combines extract + stitch in one
+   * native bridge call so the JS thread never has to round-trip
+   * frame paths.
+   */
+  extractFrames: (opts: ExtractFramesOptions) => Promise<ExtractFramesResult>;
+}
+
+
+export interface ExtractFramesOptions {
+  videoPath: string;
+  outputDir: string;
+  frameCount: number;
+  /** JPEG quality [0-100]. Defaults to 85. */
+  quality?: number;
+}
+
+
+export interface ExtractFramesResult {
+  framePaths: string[];
+  durationMs: number;
+}
+
+
+export function useVideoCapture(): UseVideoCaptureReturn {
+  const [state, setState] = useState<VideoCaptureState>('idle');
+
+  /**
+   * The active recording's resolve/reject handles.  Set when
+   * `startRecording` is called; cleared when vision-camera fires
+   * `onRecordingFinished` / `onRecordingError`, or when the host
+   * calls `cancelRecording`.
+   *
+   * Stored in a ref (not state) because vision-camera's callbacks
+   * fire outside React's render cycle and need synchronous access
+   * to the latest handles.
+   */
+  const recordingFutureRef = useRef<{
+    resolve: (video: VideoFile) => void;
+    reject: (err: unknown) => void;
+  } | null>(null);
+
+  const startRecording = useCallback(
+    async (cameraRef: React.RefObject<Camera | null>): Promise<VideoFile> => {
+      if (!cameraRef.current) {
+        throw new Error('useVideoCapture.startRecording: cameraRef is null');
+      }
+      if (recordingFutureRef.current !== null) {
+        throw new Error(
+          'useVideoCapture.startRecording: a recording is already in progress',
+        );
+      }
+
+      // Brief settle before kicking off a fresh recording.
+      // vision-camera's AVCaptureSession needs ~100 ms after a
+      // previous stopRecording completes before it can cleanly
+      // start a new one — without this, rapid record→stop→record
+      // cycles (typical when the user does a panorama, then another
+      // panorama right after) can crash the session.
+      await new Promise<void>((r) => setTimeout(r, 150));
+
+      return new Promise<VideoFile>((resolve, reject) => {
+        recordingFutureRef.current = { resolve, reject };
+        setState('recording');
+        cameraRef.current!.startRecording({
+          onRecordingFinished: (video) => {
+            const future = recordingFutureRef.current;
+            recordingFutureRef.current = null;
+            setState('idle');
+            // If the future was cleared (cancelled), drop the file
+            // on the floor.  vision-camera still wrote it to disk;
+            // that's a known cleanup gap for a future iteration.
+            future?.resolve(video);
+          },
+          onRecordingError: (err) => {
+            const future = recordingFutureRef.current;
+            recordingFutureRef.current = null;
+            setState('idle');
+            // eslint-disable-next-line no-console
+            console.error('[useVideoCapture] recording error', err);
+            future?.reject(err);
+          },
+        });
+      });
+    },
+    [],
+  );
+
+  const stopRecording = useCallback(
+    async (cameraRef: React.RefObject<Camera | null>): Promise<void> => {
+      // No-op if there's nothing to stop — protects against the
+      // cascade where startRecording errored synchronously and the
+      // host's release handler still calls stop.
+      if (recordingFutureRef.current === null) return;
+      if (!cameraRef.current) return;
+      setState('stopping');
+      try {
+        await cameraRef.current.stopRecording();
+      } catch (err) {
+        // The native call can throw "no-recording-in-progress" if
+        // the recording was already finalised by an error path.
+        // The future has its own error handling; we just absorb so
+        // the host's await doesn't see a confusing secondary error.
+        // eslint-disable-next-line no-console
+        console.warn('[useVideoCapture] stopRecording threw', err);
+      }
+    },
+    [],
+  );
+
+  const cancelRecording = useCallback(
+    async (cameraRef: React.RefObject<Camera | null>): Promise<void> => {
+      const future = recordingFutureRef.current;
+      // Clear FIRST so the eventual onRecordingFinished/Error
+      // callback no-ops on a null ref instead of fulfilling a
+      // promise the caller has already moved past.
+      recordingFutureRef.current = null;
+      if (future) {
+        future.reject(new Error('useVideoCapture: recording cancelled'));
+      }
+      if (!cameraRef.current) {
+        setState('idle');
+        return;
+      }
+      setState('stopping');
+      try {
+        await cameraRef.current.stopRecording();
+      } catch {
+        // Expected when no recording is in flight.
+      } finally {
+        setState('idle');
+      }
+    },
+    [],
+  );
+
+  const extractFrames = useCallback(
+    async (_opts: ExtractFramesOptions): Promise<ExtractFramesResult> => {
+      setState('extracting');
+      try {
+        throw new Error(
+          '[react-native-image-stitcher] useVideoCapture.extractFrames is not '
+          + 'available — use `stitchVideo()` from the SDK index, which '
+          + 'combines extract + stitch in a single native call.',
+        );
+      } finally {
+        setState('idle');
+      }
+    },
+    [],
+  );
+
+  return {
+    state,
+    startRecording,
+    stopRecording,
+    cancelRecording,
+    extractFrames,
+  };
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * react-native-image-stitcher — public API surface.
+ *
+ * Single component (`<Camera>`) + supporting types + the two public
+ * hooks the design doc calls out (`useARSession`, `useIMUTranslationGate`).
+ * Everything else (internal sub-components, drivers, bridges) is
+ * deliberately NOT re-exported so the v0.1.0 → 1.0 stability window
+ * doesn't lock us into an inflated public surface.
+ *
+ * If you need access to something that used to be exported and isn't
+ * now, please open an issue describing the use-case before reaching
+ * into the package internals.
+ *
+ * Public/private split: this lib is the open-source foundation.  The
+ * `retailens-camera-sdk` package depends on this lib and adds
+ * RetaiLens-specific features (measurement, packet detection, etc.)
+ * on top.  Consumers wanting those features install
+ * `retailens-camera-sdk` instead.
+ */
+
+// ── The main component ────────────────────────────────────────────────────
+export { Camera, CameraError } from './camera/Camera';
+export type {
+  CameraProps,
+  CameraCaptureResult,
+  CameraErrorCode,
+  CaptureSource,
+  CameraLens,
+  StitchMode,
+  Blender,
+  SeamFinder,
+  Warper,
+  FramesDroppedInfo,
+} from './camera/Camera';
+
+// ── AR foundation (public per design doc) ─────────────────────────────────
+// Hosts that want raw AR pose access (e.g., to build their own
+// measurement/detection on top) consume these directly.
+export { useARSession, ARTrackingState } from './ar/useARSession';
+export type {
+  UseARSessionReturn,
+  FramePose,
+} from './ar/useARSession';
+
+// ── IMU translation gate (public per design doc R5) ───────────────────────
+// Hosts running their own non-AR capture flow can reuse this hook to
+// get the same gating logic <Camera> uses internally.
+export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
+export type {
+  UseIMUTranslationGateOptions,
+  UseIMUTranslationGateReturn,
+} from './sensors/useIMUTranslationGate';

package/src/quality/normaliseOrientation.ts

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * normaliseOrientation — bake EXIF rotation into a JPEG's pixels.
+ *
+ * vision-camera writes photos with the camera sensor's native
+ * landscape pixels and an EXIF Orientation tag describing how to
+ * rotate them for display.  Most consumers (iOS UIImage, RN's
+ * `<Image>`) honour the tag — but enough don't (Sentry breadcrumbs,
+ * share sheets, the cv::Stitcher itself, third-party image
+ * pipelines) that "what's on disk" diverges from "what the user
+ * sees" unless we eagerly normalise.
+ *
+ * This helper round-trips the file through the SDK's native
+ * stitcher module, which decodes the JPEG with EXIF rotation
+ * applied and re-encodes a clean JPEG with no orientation
+ * metadata.  Idempotent on already-normalised files.
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+
+export interface NormaliseOrientationResult {
+  /** Image width in pixels AFTER rotation has been applied. */
+  width: number;
+  /** Image height in pixels AFTER rotation. */
+  height: number;
+}
+
+
+/**
+ * Bake the EXIF rotation of `imagePath` into pixels in-place.
+ *
+ * Returns the post-rotation dimensions so the caller can update
+ * its own width/height fields.  No-op on platforms that don't
+ * have the native module yet (Android until Phase 3) — falls back
+ * to the input shape so callers don't have to special-case
+ * platform availability.
+ */
+export async function normaliseOrientation(
+  imagePath: string,
+  fallback?: { width: number; height: number },
+): Promise<NormaliseOrientationResult> {
+  const native: unknown =
+    (NativeModules as Record<string, unknown>)['BatchStitcher'];
+  const fn =
+    native
+    && typeof native === 'object'
+    && typeof (native as { normaliseOrientation?: unknown }).normaliseOrientation === 'function'
+      ? (native as {
+          normaliseOrientation: (
+            o: { imagePath: string },
+          ) => Promise<NormaliseOrientationResult>;
+        }).normaliseOrientation
+      : null;
+
+  if (!fn) {
+    // Native module not registered (typically Android in current
+    // builds).  Skip normalisation and report the caller's
+    // fallback dimensions if provided, otherwise zeroes — keeps
+    // the API total without forcing every caller to wrap a
+    // try/catch.
+    if (fallback) return fallback;
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[capture-sdk] normaliseOrientation: native module not available on ${Platform.OS}.  `
+      + 'Photo orientation may render incorrectly until the native module is registered.',
+    );
+    return { width: 0, height: 0 };
+  }
+
+  try {
+    return await fn({ imagePath });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn('[capture-sdk] normaliseOrientation failed', err);
+    if (fallback) return fallback;
+    throw err;
+  }
+}

package/src/quality/runQualityCheck.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * runQualityCheck — public entry point for the SDK's blur + brightness
+ * quality gate.  Delegates to the native module
+ * `RNImageStitcherQualityChecker` when registered (iOS today via
+ * `ios/Sources/RNImageStitcher/QualityChecker.swift`, Android in
+ * Phase 3); falls back to a conservative pass-through shim when the
+ * native module is absent so dev / Jest runs don't crash on a missing
+ * NativeModules entry.
+ *
+ * The shim NEVER fails an image — false negatives in production are
+ * worse than missing data.  The native path is the only branch that
+ * can return `passed=false`.
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+import type { QualityIssue, QualityReport, QualityThresholds } from '../types';
+
+
+let warnedOnce = false;
+
+
+/**
+ * Numeric scores produced by the native module.  The bridge resolves
+ * with `{ blurScore, brightnessScore }` — issues are computed in JS
+ * so the same threshold logic applies on iOS + Android even if a
+ * platform's native impl evolves independently.
+ */
+interface NativeQualityScores {
+  blurScore: number;
+  brightnessScore: number;
+}
+
+
+/**
+ * Analyse an image file and return a quality report.
+ *
+ * @param imagePath Filesystem path to the image (with or without
+ *                  `file://` prefix — the native module strips it).
+ * @param thresholds Cut-offs the report scores against.
+ */
+export async function runQualityCheck(
+  imagePath: string,
+  thresholds: QualityThresholds,
+): Promise<QualityReport> {
+  const native = (NativeModules as Record<string, unknown>)['RNImageStitcherQualityChecker'];
+
+  // Native path: registered + has the bridged `measure` method.
+  if (
+    native
+    && typeof native === 'object'
+    && typeof (native as { measure?: unknown }).measure === 'function'
+  ) {
+    const scores: NativeQualityScores =
+      await (native as { measure: (path: string) => Promise<NativeQualityScores> })
+        .measure(imagePath);
+    return scoreToReport(scores, thresholds);
+  }
+
+  // Shim fallback — never reached when the SDK's native module is linked
+  // into the host app correctly.  Surfaces a one-time warning in dev so
+  // misconfiguration is loud rather than silent.
+  if (!warnedOnce && __DEV__) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[react-native-image-stitcher] QualityChecker native module not '
+      + `found on ${Platform.OS}; falling back to optimistic shim.  Check `
+      + 'autolinking + a clean `pod install` (iOS) / `gradle clean` (Android).',
+    );
+    warnedOnce = true;
+  }
+  void thresholds;
+  return {
+    passed: true,
+    blurScore: Number.POSITIVE_INFINITY,
+    brightnessScore: 128,
+    issues: [],
+  };
+}
+
+
+/**
+ * Apply thresholds to native scores → produce the report shape the JS
+ * surface promises.  Pure function so it's trivially unit-testable.
+ *
+ * Exported for tests; not part of the SDK's public API.
+ */
+export function scoreToReport(
+  scores: NativeQualityScores,
+  thresholds: QualityThresholds,
+): QualityReport {
+  const issues: QualityIssue[] = [];
+
+  if (scores.blurScore < thresholds.minBlurScore) {
+    issues.push({
+      type: 'blur',
+      message:
+        `Image is too blurry (Laplacian variance ${scores.blurScore.toFixed(1)} `
+        + `< ${thresholds.minBlurScore}). Hold the camera steady and retry.`,
+      severity: 'error',
+    });
+  }
+  if (scores.brightnessScore < thresholds.minBrightness) {
+    issues.push({
+      type: 'brightness_low',
+      message:
+        `Image is too dark (mean luminance ${scores.brightnessScore.toFixed(0)} `
+        + `< ${thresholds.minBrightness}). Add light or move closer to a lit area.`,
+      severity: 'warning',
+    });
+  } else if (scores.brightnessScore > thresholds.maxBrightness) {
+    issues.push({
+      type: 'brightness_high',
+      message:
+        `Image is overexposed (mean luminance ${scores.brightnessScore.toFixed(0)} `
+        + `> ${thresholds.maxBrightness}). Reduce light or move out of direct sunlight.`,
+      severity: 'warning',
+    });
+  }
+
+  return {
+    // `passed` is the strict gate — only `error`-severity issues block.
+    // Brightness warnings are advisory; SOS is still computable from a
+    // dim or bright photo, but a blurry one isn't.
+    passed: issues.every((i) => i.severity !== 'error'),
+    blurScore: scores.blurScore,
+    brightnessScore: scores.brightnessScore,
+    issues,
+  };
+}