react-native-image-stitcher 0.5.0 → 0.6.0

package/dist/stitching/useIncrementalJSDriver.js

@@ -1,220 +0,0 @@
-"use strict";
-// SPDX-License-Identifier: Apache-2.0
-/**
- * useIncrementalJSDriver — vision-camera + gyro frame driver for
- * the incremental panorama engine, used in non-AR captures on both
- * iOS and Android.
- *
- * History: previously called `useIncrementalAndroidDriver` because
- * it was Android-only.  As of 2026-05-17 (Issue #2), the native
- * `processFrameAtPath` entry point exists on both platforms and the
- * hook drives non-AR on iOS too; renamed 2026-05-19 to reflect
- * that.
- *
- * Why this exists
- *   In AR captures the engine consumes frames from the ARSession
- *   stream natively (60 Hz pose + image delivery, zero JS
- *   involvement once started).  In NON-AR captures there is no AR
- *   session — vision-camera owns the camera — so the engine needs
- *   another frame source.  This hook fills the gap:
- *
- *     - vision-camera keeps the camera viewport
- *     - `takeSnapshot()` runs at ~250 ms intervals during press-hold
- *     - `react-native-sensors` gyroscope is integrated to estimate
- *       cumulative yaw/pitch (drives the FoV-overlap gate)
- *     - Each snapshot path + integrated pose is fed to
- *       `IncrementalStitcher.processFrameAtPath()`
- *
- * Trade-off vs the AR path
- *   Gyro integration drifts ~1–2° per minute.  Acceptable for the
- *   typical 5–15 s shelf pan; not great for ambitious 360° captures.
- *   Snapshot rate is ~4 Hz (vs 60 Hz in AR mode).  Pose drives
- *   frame-selection only — the actual image alignment is feature-
- *   matched + RANSAC-fit, so quality of the panorama itself isn't
- *   bounded by gyro accuracy.
- *
- * Lifecycle
- *   `start({ cameraRef })` enables the loop; `stop()` tears down.
- *   Both should be called by the host's hold-start / hold-complete
- *   handlers.  Safe to call on either platform; the hook only
- *   activates inside the start/stop block.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.useIncrementalJSDriver = useIncrementalJSDriver;
-const react_1 = require("react");
-const react_native_1 = require("react-native");
-const react_native_sensors_1 = require("react-native-sensors");
-// One-shot deprecation flag — module-scoped so multiple host
-// instances of the hook all share the same gate and we only emit
-// the warning the first time anyone calls .start() in this
-// process.
-let deprecationWarningEmitted = false;
-function getNativeIncremental() {
-    const m = react_native_1.NativeModules['IncrementalStitcher'];
-    if (!m || typeof m !== 'object')
-        return null;
-    return m;
-}
-function useIncrementalJSDriver(options = {}) {
-    const { snapshotIntervalMs = 250, gyroIntervalMs = 33, fovHorizDegrees = 65, fovVertDegrees = 50, } = options;
-    const intervalRef = (0, react_1.useRef)(null);
-    const gyroSubRef = (0, react_1.useRef)(null);
-    const cameraRef = (0, react_1.useRef)(null);
-    // Integrated pose accumulators, in radians.  Reset on each
-    // start() call.  Y-axis = horizontal pan (yaw), X-axis = vertical
-    // pan (pitch).  Sign convention matches ARKit: counter-clockwise
-    // from above is positive yaw.
-    const yawRef = (0, react_1.useRef)(0);
-    const pitchRef = (0, react_1.useRef)(0);
-    const lastGyroAtRef = (0, react_1.useRef)(null);
-    // Single in-flight guard so we don't pile up overlapping snapshot
-    // promises on slow devices — if last snapshot hasn't finished
-    // when the next interval fires, skip.
-    const snapshotInFlightRef = (0, react_1.useRef)(false);
-    // Module-level "is the driver active right now" — exposed to the
-    // host because the hook itself doesn't trigger re-renders.
-    const isRunningRef = (0, react_1.useRef)(false);
-    const stop = (0, react_1.useCallback)(() => {
-        if (intervalRef.current) {
-            clearInterval(intervalRef.current);
-            intervalRef.current = null;
-        }
-        if (gyroSubRef.current) {
-            gyroSubRef.current.unsubscribe();
-            gyroSubRef.current = null;
-        }
-        cameraRef.current = null;
-        isRunningRef.current = false;
-    }, []);
-    const start = (0, react_1.useCallback)((cameraRefArg) => {
-        // 2026-05-17 (Issue #2) — removed the Android-only platform
-        // guard.  iOS now also exposes `processFrameAtPath` (see the
-        // Swift bridge), so the same driver feeds both platforms in
-        // non-AR mode.
-        if (isRunningRef.current)
-            return;
-        // F8.5 — one-shot deprecation warning.  v0.5.0 introduced
-        // `useFrameProcessorDriver` (vision-camera producer-thread
-        // path, native frame rate, no JPEG round-trip).  The legacy
-        // takeSnapshot path stays available for one minor cycle to
-        // give hosts time to migrate, then is removed in v0.6.
-        if (!deprecationWarningEmitted) {
-            deprecationWarningEmitted = true;
-            // eslint-disable-next-line no-console
-            console.warn('[react-native-image-stitcher] `useIncrementalJSDriver` '
-                + 'is DEPRECATED as of v0.5.0 and will be REMOVED in '
-                + 'v0.6.0.  Migrate to `useFrameProcessorDriver` (or '
-                + 'simply let `<Camera>` use its default driver — no host '
-                + 'code change needed).  Opt-out via the `legacyDriver` '
-                + 'prop on `<Camera>` if you need to stay on the legacy '
-                + 'path temporarily.');
-        }
-        const native = getNativeIncremental();
-        if (!native)
-            return;
-        cameraRef.current = cameraRefArg;
-        yawRef.current = 0;
-        pitchRef.current = 0;
-        lastGyroAtRef.current = null;
-        snapshotInFlightRef.current = false;
-        isRunningRef.current = true;
-        // Gyro integration.  Each sample carries angular velocity in
-        // rad/s; multiply by elapsed time to accumulate angular
-        // displacement.  Note: the gyro axes are device-local; we use
-        // y for yaw and x for pitch on a device held in portrait.
-        // Landscape would swap, but the FoV-overlap gate is dominant-
-        // axis based on the .mm side, so the convention matters less
-        // than consistency.
-        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, gyroIntervalMs);
-        gyroSubRef.current = react_native_sensors_1.gyroscope.subscribe({
-            next: ({ x, y }) => {
-                const now = Date.now();
-                if (lastGyroAtRef.current === null) {
-                    lastGyroAtRef.current = now;
-                    return;
-                }
-                const dt = (now - lastGyroAtRef.current) / 1000.0;
-                lastGyroAtRef.current = now;
-                yawRef.current += y * dt;
-                pitchRef.current += x * dt;
-            },
-            error: (err) => {
-                // eslint-disable-next-line no-console
-                console.warn('[useIncrementalJSDriver] gyro error', err);
-            },
-        });
-        // Snapshot loop.
-        const tick = async () => {
-            if (snapshotInFlightRef.current)
-                return;
-            const cam = cameraRef.current?.current;
-            if (!cam)
-                return;
-            snapshotInFlightRef.current = true;
-            try {
-                const snap = await cam.takeSnapshot({ quality: 70 });
-                if (!snap?.path)
-                    return;
-                // Synthesise a quaternion from integrated yaw + pitch.
-                // Yaw rotates about world Y (gravity), pitch about world X
-                // (perpendicular to gravity in the device's frame).
-                // Combined as q = q_yaw · q_pitch.
-                const halfYaw = yawRef.current / 2;
-                const halfPitch = pitchRef.current / 2;
-                const cy_ = Math.cos(halfYaw);
-                const sy_ = Math.sin(halfYaw);
-                const cp = Math.cos(halfPitch);
-                const sp = Math.sin(halfPitch);
-                // q_yaw   = (0, sy, 0, cy)
-                // q_pitch = (sp, 0, 0, cp)
-                // q = q_yaw * q_pitch:
-                const qx = cy_ * sp;
-                const qy = sy_ * cp;
-                const qz = -sy_ * sp;
-                const qw = cy_ * cp;
-                // Vision-camera v4 doesn't expose camera intrinsics on
-                // Android, so we estimate fx/fy from the snapshot's pixel
-                // dimensions + assumed FoV.  cx/cy at image centre.  This
-                // is approximate; the proper Android live path is the
-                // ARCameraView, where ARCore gives us the real intrinsics.
-                const w = snap.width ?? 1920;
-                const h = snap.height ?? 1440;
-                const fx = w / (2.0 * Math.tan(((fovHorizDegrees * Math.PI) / 180) / 2));
-                const fy = h / (2.0 * Math.tan(((fovVertDegrees * Math.PI) / 180) / 2));
-                const cx = w / 2;
-                const cy = h / 2;
-                await native.processFrameAtPath({
-                    path: snap.path,
-                    yaw: yawRef.current,
-                    pitch: pitchRef.current,
-                    fovHorizDegrees,
-                    fovVertDegrees,
-                    trackingPoor: false,
-                    qx, qy, qz, qw,
-                    fx, fy, cx, cy,
-                    imageWidth: w, imageHeight: h,
-                });
-            }
-            catch (err) {
-                // Swallow per-frame errors so the loop keeps running.
-                // eslint-disable-next-line no-console
-                console.warn('[useIncrementalJSDriver] processFrame failed', err);
-            }
-            finally {
-                snapshotInFlightRef.current = false;
-            }
-        };
-        // Kick off an immediate first frame so the engine doesn't sit
-        // idle for the first interval period.
-        tick();
-        intervalRef.current = setInterval(tick, snapshotIntervalMs);
-    }, [snapshotIntervalMs, gyroIntervalMs, fovHorizDegrees, fovVertDegrees]);
-    return {
-        start,
-        stop,
-        get isRunning() {
-            return isRunningRef.current;
-        },
-    };
-}
-//# sourceMappingURL=useIncrementalJSDriver.js.map

package/src/stitching/useIncrementalJSDriver.ts

@@ -1,297 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * useIncrementalJSDriver — vision-camera + gyro frame driver for
- * the incremental panorama engine, used in non-AR captures on both
- * iOS and Android.
- *
- * History: previously called `useIncrementalAndroidDriver` because
- * it was Android-only.  As of 2026-05-17 (Issue #2), the native
- * `processFrameAtPath` entry point exists on both platforms and the
- * hook drives non-AR on iOS too; renamed 2026-05-19 to reflect
- * that.
- *
- * Why this exists
- *   In AR captures the engine consumes frames from the ARSession
- *   stream natively (60 Hz pose + image delivery, zero JS
- *   involvement once started).  In NON-AR captures there is no AR
- *   session — vision-camera owns the camera — so the engine needs
- *   another frame source.  This hook fills the gap:
- *
- *     - vision-camera keeps the camera viewport
- *     - `takeSnapshot()` runs at ~250 ms intervals during press-hold
- *     - `react-native-sensors` gyroscope is integrated to estimate
- *       cumulative yaw/pitch (drives the FoV-overlap gate)
- *     - Each snapshot path + integrated pose is fed to
- *       `IncrementalStitcher.processFrameAtPath()`
- *
- * Trade-off vs the AR path
- *   Gyro integration drifts ~1–2° per minute.  Acceptable for the
- *   typical 5–15 s shelf pan; not great for ambitious 360° captures.
- *   Snapshot rate is ~4 Hz (vs 60 Hz in AR mode).  Pose drives
- *   frame-selection only — the actual image alignment is feature-
- *   matched + RANSAC-fit, so quality of the panorama itself isn't
- *   bounded by gyro accuracy.
- *
- * Lifecycle
- *   `start({ cameraRef })` enables the loop; `stop()` tears down.
- *   Both should be called by the host's hold-start / hold-complete
- *   handlers.  Safe to call on either platform; the hook only
- *   activates inside the start/stop block.
- */
-
-import { useCallback, useRef } from 'react';
-import { NativeModules } from 'react-native';
-import {
-  gyroscope,
-  setUpdateIntervalForType,
-  SensorTypes,
-} from 'react-native-sensors';
-import type { Subscription } from 'rxjs';
-import type { Camera } from 'react-native-vision-camera';
-
-// One-shot deprecation flag — module-scoped so multiple host
-// instances of the hook all share the same gate and we only emit
-// the warning the first time anyone calls .start() in this
-// process.
-let deprecationWarningEmitted = false;
-
-
-export interface UseIncrementalJSDriverOptions {
-  /**
-   * Snapshot interval in ms.  Default 250 (≈ 4 Hz).  Lower = more
-   * candidate frames + more disk I/O.  Don't go below 200 — vision-
-   * camera's snapshot pipeline can't keep up reliably below that.
-   */
-  snapshotIntervalMs?: number;
-  /**
-   * Gyro sample rate in ms (~30 Hz default matches the existing
-   * `PanoramaGuidance` cadence).  Used for pose integration only —
-   * not the snapshot rate.
-   */
-  gyroIntervalMs?: number;
-  /**
-   * Approximate horizontal FoV of the device camera.  Drives the
-   * overlap-percent calculation in the native engine.  Default 65°
-   * is a reasonable mid-tier smartphone average.
-   */
-  fovHorizDegrees?: number;
-  /**
-   * Approximate vertical FoV of the device camera.  Default 50° for
-   * typical 4:3 phone cameras.  When ARCore-driven path is in use
-   * the engine receives both FoVs straight from intrinsics; the
-   * gyro driver is a fallback so the defaults are good enough.
-   */
-  fovVertDegrees?: number;
-}
-
-
-export interface IncrementalJSDriverHandle {
-  start: (cameraRef: React.RefObject<Camera | null>) => void;
-  stop: () => void;
-  isRunning: boolean;
-}
-
-
-interface NativeProcessFrame {
-  processFrameAtPath(options: {
-    path: string;
-    yaw: number;
-    pitch: number;
-    fovHorizDegrees: number;
-    fovVertDegrees: number;
-    trackingPoor: boolean;
-    /** Quaternion (x, y, z, w) — pose-driven path. */
-    qx: number; qy: number; qz: number; qw: number;
-    /** Sensor-resolution intrinsics. */
-    fx: number; fy: number; cx: number; cy: number;
-    imageWidth: number;
-    imageHeight: number;
-  }): Promise<unknown>;
-}
-
-
-function getNativeIncremental(): NativeProcessFrame | null {
-  const m = (NativeModules as Record<string, unknown>)['IncrementalStitcher'];
-  if (!m || typeof m !== 'object') return null;
-  return m as NativeProcessFrame;
-}
-
-
-export function useIncrementalJSDriver(
-  options: UseIncrementalJSDriverOptions = {},
-): IncrementalJSDriverHandle {
-  const {
-    snapshotIntervalMs = 250,
-    gyroIntervalMs = 33,
-    fovHorizDegrees = 65,
-    fovVertDegrees = 50,
-  } = options;
-
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
-  const gyroSubRef = useRef<Subscription | null>(null);
-  const cameraRef = useRef<React.RefObject<Camera | null> | null>(null);
-  // Integrated pose accumulators, in radians.  Reset on each
-  // start() call.  Y-axis = horizontal pan (yaw), X-axis = vertical
-  // pan (pitch).  Sign convention matches ARKit: counter-clockwise
-  // from above is positive yaw.
-  const yawRef = useRef(0);
-  const pitchRef = useRef(0);
-  const lastGyroAtRef = useRef<number | null>(null);
-  // Single in-flight guard so we don't pile up overlapping snapshot
-  // promises on slow devices — if last snapshot hasn't finished
-  // when the next interval fires, skip.
-  const snapshotInFlightRef = useRef(false);
-  // Module-level "is the driver active right now" — exposed to the
-  // host because the hook itself doesn't trigger re-renders.
-  const isRunningRef = useRef(false);
-
-  const stop = useCallback(() => {
-    if (intervalRef.current) {
-      clearInterval(intervalRef.current);
-      intervalRef.current = null;
-    }
-    if (gyroSubRef.current) {
-      gyroSubRef.current.unsubscribe();
-      gyroSubRef.current = null;
-    }
-    cameraRef.current = null;
-    isRunningRef.current = false;
-  }, []);
-
-  const start = useCallback(
-    (cameraRefArg: React.RefObject<Camera | null>) => {
-      // 2026-05-17 (Issue #2) — removed the Android-only platform
-      // guard.  iOS now also exposes `processFrameAtPath` (see the
-      // Swift bridge), so the same driver feeds both platforms in
-      // non-AR mode.
-      if (isRunningRef.current) return;
-      // F8.5 — one-shot deprecation warning.  v0.5.0 introduced
-      // `useFrameProcessorDriver` (vision-camera producer-thread
-      // path, native frame rate, no JPEG round-trip).  The legacy
-      // takeSnapshot path stays available for one minor cycle to
-      // give hosts time to migrate, then is removed in v0.6.
-      if (!deprecationWarningEmitted) {
-        deprecationWarningEmitted = true;
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[react-native-image-stitcher] `useIncrementalJSDriver` '
-          + 'is DEPRECATED as of v0.5.0 and will be REMOVED in '
-          + 'v0.6.0.  Migrate to `useFrameProcessorDriver` (or '
-          + 'simply let `<Camera>` use its default driver — no host '
-          + 'code change needed).  Opt-out via the `legacyDriver` '
-          + 'prop on `<Camera>` if you need to stay on the legacy '
-          + 'path temporarily.',
-        );
-      }
-      const native = getNativeIncremental();
-      if (!native) return;
-
-      cameraRef.current = cameraRefArg;
-      yawRef.current = 0;
-      pitchRef.current = 0;
-      lastGyroAtRef.current = null;
-      snapshotInFlightRef.current = false;
-      isRunningRef.current = true;
-
-      // Gyro integration.  Each sample carries angular velocity in
-      // rad/s; multiply by elapsed time to accumulate angular
-      // displacement.  Note: the gyro axes are device-local; we use
-      // y for yaw and x for pitch on a device held in portrait.
-      // Landscape would swap, but the FoV-overlap gate is dominant-
-      // axis based on the .mm side, so the convention matters less
-      // than consistency.
-      setUpdateIntervalForType(SensorTypes.gyroscope, gyroIntervalMs);
-      gyroSubRef.current = gyroscope.subscribe({
-        next: ({ x, y }) => {
-          const now = Date.now();
-          if (lastGyroAtRef.current === null) {
-            lastGyroAtRef.current = now;
-            return;
-          }
-          const dt = (now - lastGyroAtRef.current) / 1000.0;
-          lastGyroAtRef.current = now;
-          yawRef.current += y * dt;
-          pitchRef.current += x * dt;
-        },
-        error: (err) => {
-          // eslint-disable-next-line no-console
-          console.warn('[useIncrementalJSDriver] gyro error', err);
-        },
-      });
-
-      // Snapshot loop.
-      const tick = async () => {
-        if (snapshotInFlightRef.current) return;
-        const cam = cameraRef.current?.current;
-        if (!cam) return;
-        snapshotInFlightRef.current = true;
-        try {
-          const snap = await cam.takeSnapshot({ quality: 70 });
-          if (!snap?.path) return;
-          // Synthesise a quaternion from integrated yaw + pitch.
-          // Yaw rotates about world Y (gravity), pitch about world X
-          // (perpendicular to gravity in the device's frame).
-          // Combined as q = q_yaw · q_pitch.
-          const halfYaw = yawRef.current / 2;
-          const halfPitch = pitchRef.current / 2;
-          const cy_ = Math.cos(halfYaw);
-          const sy_ = Math.sin(halfYaw);
-          const cp = Math.cos(halfPitch);
-          const sp = Math.sin(halfPitch);
-          // q_yaw   = (0, sy, 0, cy)
-          // q_pitch = (sp, 0, 0, cp)
-          // q = q_yaw * q_pitch:
-          const qx = cy_ * sp;
-          const qy = sy_ * cp;
-          const qz = -sy_ * sp;
-          const qw = cy_ * cp;
-
-          // Vision-camera v4 doesn't expose camera intrinsics on
-          // Android, so we estimate fx/fy from the snapshot's pixel
-          // dimensions + assumed FoV.  cx/cy at image centre.  This
-          // is approximate; the proper Android live path is the
-          // ARCameraView, where ARCore gives us the real intrinsics.
-          const w = snap.width ?? 1920;
-          const h = snap.height ?? 1440;
-          const fx = w / (2.0 * Math.tan(((fovHorizDegrees * Math.PI) / 180) / 2));
-          const fy = h / (2.0 * Math.tan(((fovVertDegrees * Math.PI) / 180) / 2));
-          const cx = w / 2;
-          const cy = h / 2;
-
-          await native.processFrameAtPath({
-            path: snap.path,
-            yaw: yawRef.current,
-            pitch: pitchRef.current,
-            fovHorizDegrees,
-            fovVertDegrees,
-            trackingPoor: false,
-            qx, qy, qz, qw,
-            fx, fy, cx, cy,
-            imageWidth: w, imageHeight: h,
-          });
-        } catch (err) {
-          // Swallow per-frame errors so the loop keeps running.
-          // eslint-disable-next-line no-console
-          console.warn(
-            '[useIncrementalJSDriver] processFrame failed', err,
-          );
-        } finally {
-          snapshotInFlightRef.current = false;
-        }
-      };
-      // Kick off an immediate first frame so the engine doesn't sit
-      // idle for the first interval period.
-      tick();
-      intervalRef.current = setInterval(tick, snapshotIntervalMs);
-    },
-    [snapshotIntervalMs, gyroIntervalMs, fovHorizDegrees, fovVertDegrees],
-  );
-
-  return {
-    start,
-    stop,
-    get isRunning(): boolean {
-      return isRunningRef.current;
-    },
-  };
-}