react-native-image-stitcher 0.5.0 → 0.6.0

package/src/camera/Camera.tsx

@@ -89,7 +89,6 @@ import {
   subscribeIncrementalState,
   type IncrementalState,
 } from '../stitching/incremental';
-import { useIncrementalJSDriver } from '../stitching/useIncrementalJSDriver';
 import { useFrameProcessorDriver } from '../stitching/useFrameProcessorDriver';
 import { useIncrementalStitcher } from '../stitching/useIncrementalStitcher';
 import { useIMUTranslationGate } from '../sensors/useIMUTranslationGate';
@@ -235,6 +234,29 @@ export interface CameraProps {
   showSettingsButton?: boolean;
   style?: StyleProp<ViewStyle>;
 
+  /**
+   * Which incremental stitcher engine to drive.  Default
+   * `'batch-keyframe'` — collects accepted JPEGs and runs
+   * `cv::Stitcher` once at finalize time.  This is the v0.4+
+   * production default and what the v0.5 Frame Processor migration
+   * exercises.
+   *
+   * Switch to a live engine (`'firstwins-rectilinear'` or
+   * `'hybrid'`) for low-latency in-flight stitching.  Live engines
+   * exercise the F8.6 pixel-buffer ingest path (skipping the JPEG
+   * encode/decode round-trip; ~30–50 ms saved per accept) when the
+   * Frame Processor driver is active.
+   *
+   * See `docs/f8-frame-processor-plan.md` and the v0.5.0
+   * CHANGELOG for the trade-offs between batch-keyframe and live
+   * engines.
+   */
+  engine?: 'batch-keyframe'
+    | 'hybrid'
+    | 'slitscan-rotate' | 'slitscan-both'
+    | 'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear'
+    | 'slitscan';
+
   /**
    * Optional destination directory for captures.  When set, the lib
    * lands tap-photos at `${outputDir}/photo-${ts}.jpg` and panoramas
@@ -280,37 +302,20 @@ export interface CameraProps {
    * Introduced for F8 (FrameProcessor port) — see
    * `docs/f8-frame-processor-plan.md`.
    *
-   * As of v0.5 (F8.3) this prop is **deprecated for the standard
-   * non-AR capture flow**: the SDK now installs its own frame
-   * processor via `useFrameProcessorDriver` that pipes pixel
-   * buffers into the incremental stitcher with synthesised pose.
-   * Setting this prop in the default mode will be IGNORED with a
-   * one-time console.warn — supplying your own worklet would race
-   * with the SDK's pixel-buffer feed.
+   * The SDK installs its own frame processor via
+   * `useFrameProcessorDriver`.  Setting this prop is ignored with
+   * a one-time `console.warn` — supplying a host worklet would
+   * race with the SDK's pixel-buffer feed.  Either remove the prop
+   * or fork the SDK if you genuinely need a custom worklet.
    *
-   * Three coexistence rules:
-   *   * Default (modern non-AR): SDK owns the worklet, this prop
-   *     is ignored.
-   *   * `legacyDriver={true}`: SDK uses the old `useIncrementalJSDriver`
-   *     (takeSnapshot path).  Honoured for diagnostics or as an
-   *     escape hatch.
-   *   * AR mode: vision-camera Camera isn't mounted, this prop is
-   *     irrelevant.
-   */
-  frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
-
-  /**
-   * Opt back into the legacy `useIncrementalJSDriver` for non-AR
-   * captures (the v0.4 path: `takeSnapshot` → JPEG → cache file →
-   * `IncrementalStitcher.processFrameAtPath`).
+   * AR mode is irrelevant: vision-camera's Camera isn't mounted.
    *
-   * Default `false` (use the new `useFrameProcessorDriver`, which
-   * runs the gate on the camera producer thread at native frame
-   * rate via a vision-camera Frame Processor plugin).  The legacy
-   * path will be removed in v0.6 — set this only if you hit a
-   * specific issue with the new driver and need to ship a fix.
+   * (v0.5 had a `legacyDriver` escape hatch that routed back to
+   * `useIncrementalJSDriver`.  That hook + prop were removed in
+   * v0.6 per the deprecation timeline announced in the v0.5.0
+   * CHANGELOG.)
    */
-  legacyDriver?: boolean;
+  frameProcessor?: ReadonlyFrameProcessor | DrawableFrameProcessor;
 }
 
 
@@ -586,7 +591,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onFramesDropped,
     onError,
     frameProcessor: hostFrameProcessor,
-    legacyDriver = false,
+    engine = 'batch-keyframe',
   } = props;
 
   const insets = useSafeAreaInsets();
@@ -766,63 +771,49 @@ export function Camera(props: CameraProps): React.JSX.Element {
     },
   });
 
-  // JS-driver for non-AR captures (iOS + Android).  In AR mode the
-  // engine consumes frames from the ARSession stream natively, so this
-  // hook stays idle.
+  // Frame Processor driver for non-AR captures (iOS + Android).
+  // In AR mode the engine consumes frames from the ARSession stream
+  // natively, so this hook stays idle.
   //
   // IMPORTANT: start()/stop() are called imperatively from the hold
   // handlers below — NOT from a useEffect driven by statusPhase.  The
   // hook returns a fresh object identity on every render, and during
   // a recording the engine emits IncrementalStateUpdate events that
-  // cause re-renders multiple times per second.  An effect with
-  // `jsDriver` in its deps would teardown + restart the driver on
-  // every event, resetting the gyro accumulator (yaw/pitch) to zero
-  // each cycle and nulling the cameraRef during the brief gap.  The
-  // user-visible symptom was "only the first keyframe is accepted,
-  // every subsequent snapshot sees pose=(0,0) and is rejected as a
-  // duplicate of the first".  Matching AuditCaptureScreen's proven
-  // imperative pattern (start on hold-start, stop on hold-end) avoids
-  // the re-render churn entirely.
-  const jsDriver = useIncrementalJSDriver();
-  // F8.3 — vision-camera Frame Processor variant.  Always
-  // instantiated so we don't have conditional hook calls; only one
-  // of the two drivers actually .start()s per capture.  Stop() on
-  // an idle driver is a no-op.
+  // cause re-renders multiple times per second.  An effect with the
+  // driver in its deps would teardown + restart on every event,
+  // resetting the gyro accumulator (yaw/pitch) to zero each cycle.
+  // User-visible symptom: "only the first keyframe is accepted, every
+  // subsequent ingest sees pose=(0,0) and is rejected as a duplicate".
+  // The imperative pattern (start on hold-start, stop on hold-end)
+  // avoids the re-render churn entirely.
   const fpDriver = useFrameProcessorDriver();
-  // Safety: ensure both drivers are stopped if the component unmounts
-  // mid-recording.  Empty deps so this only fires on unmount.
+  // Safety: stop the driver if the component unmounts mid-recording.
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  useEffect(() => () => { jsDriver.stop(); fpDriver.stop(); }, []);
-
-  // F8.3 — one-shot deprecation warning when the host supplies their
-  // own `frameProcessor` while running in the default (Frame
-  // Processor driver) mode.  Two worklets racing on the same
-  // producer thread would corrupt the engine's workQueue ordering;
-  // the SDK's own worklet wins and the host's is ignored.  Hosts
-  // that *need* a custom worklet must opt into `legacyDriver={true}`
-  // (which switches off the SDK's worklet entirely).
+  useEffect(() => () => { fpDriver.stop(); }, []);
+
+  // One-shot deprecation warning when the host supplies their own
+  // `frameProcessor` prop.  Two worklets racing on the same
+  // producer thread would corrupt the engine's workQueue ordering,
+  // so the SDK's own worklet wins and the host's is silently
+  // ignored.  (v0.5 had a `legacyDriver` opt-out for hosts that
+  // wanted to route around the SDK driver; that was removed in
+  // v0.6 along with `useIncrementalJSDriver`.)
   const hostFrameProcessorIgnoredWarnedRef = useRef(false);
   if (
     hostFrameProcessor != null
-    && !legacyDriver
     && !hostFrameProcessorIgnoredWarnedRef.current
   ) {
     hostFrameProcessorIgnoredWarnedRef.current = true;
     // eslint-disable-next-line no-console
     console.warn(
       '[react-native-image-stitcher] The `frameProcessor` prop on '
-      + '<Camera> is ignored when the default driver is active '
-      + '(legacyDriver=false).  Either remove the prop or set '
-      + 'legacyDriver={true} to opt into the legacy path.',
+      + '<Camera> is ignored — the SDK installs its own worklet '
+      + 'via useFrameProcessorDriver.  Remove the prop, or fork '
+      + 'the SDK if you genuinely need a custom worklet.',
     );
   }
-  // The Frame Processor worklet actually bound to vision-camera's
-  // Camera.  Resolution order:
-  //   1. Legacy mode: honor the host's prop (or null).
-  //   2. Modern mode: SDK driver's worklet, regardless of host's prop.
-  const effectiveFrameProcessor = legacyDriver
-    ? (hostFrameProcessor ?? null)
-    : fpDriver.frameProcessor;
+  // The Frame Processor worklet bound to vision-camera's Camera.
+  const effectiveFrameProcessor = fpDriver.frameProcessor;
 
   // ── Subscribe to engine state for live keyframe thumbs ──────────
   useEffect(() => {
@@ -879,17 +870,17 @@ export function Camera(props: CameraProps): React.JSX.Element {
     const accepted = incrementalState?.acceptedCount ?? 0;
     if (accepted > lastAcceptedCountRef.current) {
       lastAcceptedCountRef.current = accepted;
-      // F8.3 review-of-review (M3 revert): originally gated this to
-      // `legacyDriver` because the Frame Processor driver doesn't
-      // consult `imuGate` for its own pose synthesis.  That ignored a
-      // load-bearing side effect: `imuGate.resetAnchor()` bounds the
-      // IIR-integrator drift window per-accept, and
-      // `imuGate.getTotalAbsMetres()` is read at finalize time
-      // (Camera.tsx:1097) as `imuTranslationMetres` into the native
+      // F8.3 review-of-review (M3 revert): an earlier draft gated
+      // this on the pre-v0.6 `legacyDriver` prop because the Frame
+      // Processor driver doesn't consult `imuGate` for its own pose
+      // synthesis.  That ignored a load-bearing side effect:
+      // `imuGate.resetAnchor()` bounds the IIR-integrator drift
+      // window per-accept, and `imuGate.getTotalAbsMetres()` is read
+      // at finalize time as `imuTranslationMetres` into the native
       // stitchMode auto-resolver (PANORAMA vs SCANS).  Without the
       // per-accept reset, long FP-driver captures let IIR drift
-      // compound → inflated metres → biased toward SCANS.  Keep the
-      // reset firing for ALL non-AR modes.
+      // compound → inflated metres → biased toward SCANS.  Now fires
+      // for ALL non-AR captures (the only non-AR driver post-v0.6).
       if (isNonAR) {
         imuGate.resetAnchor();
       }
@@ -1020,18 +1011,16 @@ export function Camera(props: CameraProps): React.JSX.Element {
         snapshotEveryNAccepts: 1,
         frameRotationDegrees: orientationRotation,
         captureOrientation: deviceOrientation,
-        // F8.3 — non-AR captures pick between the new Frame Processor
-        // driver (default) and the legacy JS-snapshot driver (opt-in
-        // via `legacyDriver={true}`).  AR captures always use the
-        // ARSession-driven path.
-        frameSourceMode: isNonAR
-          ? (legacyDriver ? 'jsDriver' : 'frameProcessor')
-          : 'arSession',
+        // Non-AR captures use the Frame Processor driver
+        // (vision-camera producer-thread worklet → cv_flow_gate
+        // plugin → IncrementalStitcher.consumeFrame).  AR captures
+        // use the ARSession-driven path.
+        frameSourceMode: isNonAR ? 'frameProcessor' : 'arSession',
         composeWidth: 1920,
         composeHeight: 1080,
         canvasWidth: 5000,
         canvasHeight: 5000,
-        engine: 'batch-keyframe',
+        engine,
         config: panoramaSettingsToNativeConfig({
           ...settings,
           captureSource: effectiveCaptureSource,
@@ -1042,21 +1031,13 @@ export function Camera(props: CameraProps): React.JSX.Element {
       // matching comment on the per-accept reset useEffect above).
       // Keep firing it on every capture start, not just legacy mode.
       imuGate.resetAnchor();
-      // Start the non-AR frame source.  AR mode feeds natively from
-      // ARSession so both drivers stay idle in that path.
-      //   * Default: Frame Processor driver — worklet runs on the
-      //     producer thread, plugin calls `consumeFrameFromPlugin`
-      //     directly.  No camera ref needed (vision-camera owns it).
-      //   * Legacy: JS driver — `takeSnapshot` + `processFrameAtPath`
-      //     via the cameraRef.
-      // Imperative-pattern rationale: see the useIncrementalJSDriver
-      // comment above re. why this isn't a useEffect.
+      // Start the Frame Processor driver for non-AR captures.  AR
+      // mode feeds natively from ARSession so the driver stays idle.
+      // Imperative pattern (vs useEffect) because the driver's start
+      // resets pose accumulators that should only fire at the
+      // hold-start moment, not on every re-render.
       if (isNonAR) {
-        if (legacyDriver) {
-          jsDriver.start(visionCameraRef);
-        } else {
-          fpDriver.start();
-        }
+        fpDriver.start();
       }
     } catch (err) {
       setStatusPhase('idle');
@@ -1076,9 +1057,8 @@ export function Camera(props: CameraProps): React.JSX.Element {
     settings,
     effectiveCaptureSource,
     imuGate,
-    jsDriver,
     fpDriver,
-    legacyDriver,
+    engine,
     onError,
   ]);
 
@@ -1087,10 +1067,7 @@ export function Camera(props: CameraProps): React.JSX.Element {
     setStatusPhase('stitching');
     // Stop pumping new frames before finalizing so the engine isn't
     // racing the final cv::Stitcher pass against late-arriving
-    // keyframes.  Both stop() calls are no-ops when the
-    // corresponding driver wasn't started (AR mode, or the inactive
-    // driver in non-AR mode).
-    jsDriver.stop();
+    // keyframes.  No-op in AR mode (the driver was never started).
     fpDriver.stop();
     try {
       // Compose the panorama output path: host-controlled if
@@ -1168,7 +1145,6 @@ export function Camera(props: CameraProps): React.JSX.Element {
     onFramesDropped,
     onError,
     recordingStartedAt,
-    jsDriver,
     fpDriver,
     // F10 Phase 2 review N1 — these four were missing pre-fix.  The
     // callback reads `settings.debug` (to gate the stitchToast),

package/src/index.ts

@@ -177,14 +177,9 @@ export {
 } from './stitching/incremental';
 export type { IncrementalState } from './stitching/incremental';
 export { useIncrementalStitcher } from './stitching/useIncrementalStitcher';
-export { useIncrementalJSDriver } from './stitching/useIncrementalJSDriver';
-export type {
-  UseIncrementalJSDriverOptions,
-  IncrementalJSDriverHandle,
-} from './stitching/useIncrementalJSDriver';
-// F8.3 — vision-camera Frame Processor variant of the non-AR
-// driver.  Preferred over `useIncrementalJSDriver` in v0.5+; the
-// JS driver stays exported as a deprecated fallback until v0.6.
+// vision-camera Frame Processor driver for non-AR captures.  As
+// of v0.6 the only non-AR driver exported (the legacy
+// `useIncrementalJSDriver` was removed; was deprecated in v0.5).
 export { useFrameProcessorDriver } from './stitching/useFrameProcessorDriver';
 export type {
   UseFrameProcessorDriverOptions,

package/src/stitching/incremental.ts

@@ -200,23 +200,22 @@ export interface IncrementalStartOptions {
    *     bridge.start() requires `RNSARSession.start()` to
    *     have already been called.
    *
-   *   - 'jsDriver' — engine skips AR-session registration; JS
-   *     feeds frames via `processFrameAtPath`.  Use in iOS non-AR
-   *     captures (vision-camera + gyro).  No AR session required.
-   *     LEGACY; deprecated in v0.5, removed in v0.6.
-   *
    *   - 'frameProcessor' (F8.3 iOS / F8.4 Android, v0.5+) — engine
    *     flips on `frameProcessorIngestEnabled` so the vision-camera
    *     Frame Processor plugin (`cv_flow_gate_process_frame`) can
    *     feed pixel data directly into the engine's gate path.  iOS
    *     passes the `CVPixelBuffer` straight to `consumeFrame`;
-   *     Android extracts the Y plane to a ByteArray and encodes
-   *     accepted frames to JPEG inline (the platform-specific
-   *     engine-input divergence is tracked as F8.6).  Use in non-AR
-   *     captures driven by `useFrameProcessorDriver`.  Pairs with
-   *     `Camera`'s default driver mode.
+   *     Android extracts the Y plane to a ByteArray and (since
+   *     F8.6, v0.5.1) routes live-engine ingest through
+   *     `addFramePixelData` without a JPEG round-trip.  Use in
+   *     non-AR captures driven by `useFrameProcessorDriver`.  Pairs
+   *     with `Camera`'s default driver mode.
+   *
+   * `'jsDriver'` was removed in v0.6 (deprecated in v0.5).  Hosts
+   * that used it should switch to `useFrameProcessorDriver` (or
+   * just let `<Camera>` use its default).
    */
-  frameSourceMode?: 'arSession' | 'jsDriver' | 'frameProcessor';
+  frameSourceMode?: 'arSession' | 'frameProcessor';
   /** Compose-resolution width in pixels (default 720 for portrait, 960 for landscape). */
   composeWidth?: number;
   /** Compose-resolution height in pixels (default 960 for portrait, 720 for landscape). */

package/src/stitching/useFrameProcessorDriver.ts

@@ -1,14 +1,15 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * useFrameProcessorDriver — vision-camera Frame Processor + gyro
- * driver for the incremental panorama engine.  Replaces
- * `useIncrementalJSDriver` in non-AR captures.
+ * driver for the incremental panorama engine.  Sole non-AR driver
+ * from v0.6 onward (replaced the deprecated `useIncrementalJSDriver`
+ * hook, which was removed in v0.6).
  *
- * Why this exists (vs the JS-driver predecessor)
+ * Why this exists (vs the pre-v0.6 JS-driver predecessor)
  *
- *   The JS driver takes a JPEG snapshot every ~250 ms and feeds the
- *   path to `IncrementalStitcher.processFrameAtPath`.  That path
- *   has three costs:
+ *   The old JS driver took a JPEG snapshot every ~250 ms and fed the
+ *   path to `IncrementalStitcher.processFrameAtPath` (both removed in
+ *   v0.6).  That path had three costs:
  *
  *     1. JPEG encode (`takeSnapshot` ≈ 30–80 ms on iPhone 16 Pro)
  *     2. Disk write of the JPEG
@@ -303,9 +304,9 @@ export function useFrameProcessorDriver(
     //   y = horizontal pan (yaw, about world-Y)
     //   x = vertical tilt (pitch, about world-X)
     //   z = wrist-twist roll (about world-Z, normal to the screen)
-    // Signs match the legacy `useIncrementalJSDriver` for x/y; z
-    // follows the same right-hand-rule convention.  If field
-    // captures show inverted roll, flip the sign on `z * dt` below.
+    // Right-hand-rule convention throughout — same signs the pre-v0.6
+    // `useIncrementalJSDriver` produced.  If field captures show
+    // inverted roll, flip the sign on `z * dt` below.
     setUpdateIntervalForType(SensorTypes.gyroscope, gyroIntervalMs);
     gyroSubRef.current = gyroscope.subscribe({
       next: ({ x, y, z }) => {
@@ -382,8 +383,8 @@ export function useFrameProcessorDriver(
       imageWidth: w, imageHeight: h,
       timestampMs: 0,
       // 2 == RNSARTrackingState.tracking — we always claim "good
-      // tracking" because there's no ARKit signal to differentiate
-      // (matches legacy useIncrementalJSDriver semantics).
+      // tracking" because there's no ARKit signal to differentiate.
+      // (Same contract as the pre-v0.6 useIncrementalJSDriver.)
       trackingStateRaw: 2,
     });
     // Deps array intentionally minimal: only `plugin` actually

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