react-native-image-stitcher 0.5.1 → 0.7.0

package/src/stitching/useKeyframeStream.ts

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { useEffect } from 'react';
+
+import {
+  subscribeIncrementalState,
+  type AcceptedKeyframe,
+  type IncrementalState,
+} from './incremental';
+
+/**
+ * v0.7.0 — Tier 1: subscribe to accepted-keyframe events while a
+ * panorama is in progress.
+ *
+ * Fires once per keyframe accepted by the stitching engine — typically
+ * 4-6 times per panorama, NOT per camera frame.  Use for low-frequency
+ * per-keyframe host work such as OCR on the saved JPEG, packet
+ * detection, server-side analysis, or analytics.
+ *
+ * For mid-frequency frame access (sampled stream), see `useFrameStream`
+ * (v0.9.0+).  For per-frame worklet access (~30 Hz), see
+ * `useFrameProcessor` (v0.8.0+).
+ *
+ * ## Engine-mode caveat (v0.7.0)
+ *
+ * Only the `batch-keyframe` engine emits these events.  Live engines
+ * (`firstwins-rectilinear`, `hybrid`, `slitscan-*`) paint into a live
+ * canvas instead of saving per-accept JPEGs, and do not surface accept
+ * events through this channel — the hook silently does not fire when
+ * such an engine is active.  A v0.7.1 follow-up may add live-engine
+ * accept emit if a real consumer needs it.
+ *
+ * ## Payload
+ *
+ * The handler receives an {@link AcceptedKeyframe}:
+ *
+ *   - `jpegPath`: absolute filesystem path, no `file://` prefix.  The
+ *     JPEG is the engine's own copy under the active capture's session
+ *     directory.  It persists for the lifetime of the panorama and is
+ *     cleaned up automatically when the panorama finalises or is
+ *     abandoned (or via explicit `cleanupOldKeyframes`).  Copy
+ *     synchronously inside the handler if long-term retention is
+ *     needed.
+ *   - `pose`: rotation quaternion (always present) + optional
+ *     translation vector (populated in AR mode; undefined in non-AR).
+ *   - `timestamp`: milliseconds since the Unix epoch.
+ *   - `index`: zero-based keyframe position in the current panorama.
+ *
+ * ## Lifecycle
+ *
+ * Re-subscribes on `handler` identity changes.  Wrap the handler in
+ * `useCallback` if it closes over state or props you don't want to
+ * trigger re-subscription on every render.
+ *
+ * Async handlers are fire-and-forget.  Rejected promises are caught
+ * and logged via `console.error`; no backpressure on the native side.
+ * Host code wanting to serialise work across keyframes should manage
+ * that itself (e.g., push into a queue + worker).
+ *
+ * ## Example
+ *
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { useKeyframeStream } from 'react-native-image-stitcher';
+ *
+ * function OcrPlugin() {
+ *   useKeyframeStream(
+ *     useCallback(async (kf) => {
+ *       const text = await runOCR(kf.jpegPath);
+ *       console.log(`Keyframe ${kf.index} pose=${kf.pose.rotation}:`, text);
+ *     }, []),
+ *   );
+ *   return null;
+ * }
+ * ```
+ */
+export function useKeyframeStream(
+  handler: (keyframe: AcceptedKeyframe) => void | Promise<void>,
+): void {
+  useEffect(() => {
+    const sub = subscribeIncrementalState((state: IncrementalState) => {
+      // The `batch-keyframe` engine emits four optional fields together
+      // on accept events.  Non-accept emits (snapshot updates,
+      // refinement progress, live-engine state ticks, etc.) leave
+      // `batchKeyframeThumbnailPath` undefined — that's our
+      // accept-event sentinel.
+      const jpegPath = state.batchKeyframeThumbnailPath;
+      const index = state.batchKeyframeIndex;
+      if (jpegPath === undefined || index === undefined) {
+        return;
+      }
+
+      // `batchKeyframePose` + `batchKeyframeAcceptedAtMs` are
+      // populated alongside the path + index by the post-v0.7.0
+      // native emit.  Defensive defaults guard against a host
+      // running on a slightly-older native binary (e.g., during a
+      // partial upgrade) — identity quaternion + `Date.now()`.
+      // Published v0.7.0 native always populates both.
+      const pose = state.batchKeyframePose ?? {
+        rotation: [0, 0, 0, 1] as [number, number, number, number],
+      };
+      const timestamp = state.batchKeyframeAcceptedAtMs ?? Date.now();
+
+      const keyframe: AcceptedKeyframe = {
+        jpegPath,
+        pose,
+        timestamp,
+        index,
+      };
+
+      // Fire-and-forget.  Async handler rejections are surfaced via
+      // console.error so they don't disappear into the void.
+      const result = handler(keyframe);
+      if (result && typeof (result as Promise<void>).catch === 'function') {
+        (result as Promise<void>).catch((err) => {
+          // eslint-disable-next-line no-console
+          console.error('[useKeyframeStream] handler threw:', err);
+        });
+      }
+    });
+    // `subscribeIncrementalState` returns null when the native module
+    // isn't linked (Expo Go, unit tests without the bridge, etc.).
+    // In that case we have nothing to clean up.
+    if (sub === null) return;
+    return () => sub.remove();
+  }, [handler]);
+}

package/dist/stitching/useIncrementalJSDriver.d.ts

@@ -1,74 +0,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 type { Camera } from 'react-native-vision-camera';
-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;
-}
-export declare function useIncrementalJSDriver(options?: UseIncrementalJSDriverOptions): IncrementalJSDriverHandle;
-//# sourceMappingURL=useIncrementalJSDriver.d.ts.map

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