react-native-image-stitcher 0.10.0 → 0.11.1

package/dist/stitching/useFrameProcessorDriver.js

@@ -6,317 +6,99 @@
  * from v0.6 onward (replaced the deprecated `useIncrementalJSDriver`
  * hook, which was removed in v0.6).
  *
- * Why this exists (vs the pre-v0.6 JS-driver predecessor)
- *
- *   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
- *     3. JPEG decode + cv::Mat alloc inside the engine
- *
- *   Per-frame round-trip ~80 ms means ~4 Hz max throughput, and
- *   ~80 ms latency between "this is the moment to accept" and "this
- *   frame is in the engine".  Both numbers caused operator-felt lag
- *   on long shelf pans.
- *
- *   This hook uses vision-camera's Frame Processor instead.  The
- *   worklet runs on the camera producer thread at the native frame
- *   rate (30 fps on iOS).  Each frame goes through a JSI plugin
- *   (`cv_flow_gate_process_frame`) directly into
- *   `IncrementalStitcher.consumeFrame` — the SAME entry point AR
- *   mode uses, with the engine's existing KeyframeGate making the
- *   accept/reject decision.  Rejected frames cost ~3–8 ms; accepted
- *   frames take the same deep-copy + workQueue path AR mode takes.
- *
- *   Net wins: no JPEG round-trip on rejected frames, no disk thrash
- *   during recording, lower latency to accept, full 30 fps gate
- *   evaluation budget.
- *
- * Pose synthesis
- *
- *   Non-AR mode has no ARKit pose.  We integrate the gyroscope on
- *   the JS thread (`react-native-sensors`), accumulate yaw + pitch,
- *   and publish them via Reanimated `useSharedValue` so the worklet
- *   can read them WITHOUT a thread hop.  Translation is reported as
- *   zero (no IMU translation; this is a known limitation we share
- *   with the legacy driver — drift ~1–2°/min over a 30 s capture is
- *   below the gate's overlap threshold and rarely matters).
- *
- *   Quaternion synthesis (q = q_yaw * q_pitch * q_roll, Tait-Bryan
- *   YPR order to match the legacy driver's body-frame intent):
- *     q_yaw   = (0, sin(yaw/2), 0, cos(yaw/2))
- *     q_pitch = (sin(pitch/2), 0, 0, cos(pitch/2))
- *     q_roll  = (0, 0, sin(roll/2), cos(roll/2))
- *
- *   Expanded (cy, sy = cos/sin(yaw/2); analogous for cp/sp, cr/sr):
- *     qx = cy*sp*cr + sy*cp*sr
- *     qy = sy*cp*cr - cy*sp*sr
- *     qz = cy*cp*sr - sy*sp*cr
- *     qw = cy*cp*cr + sy*sp*sr
- *
- *   When roll=0 this collapses to the 2-axis form
- *   `(cy*sp, sy*cp, -sy*sp, cy*cp)` the legacy driver used, so
- *   captures held perfectly level produce identical poses to the
- *   pre-roll behaviour.
- *
- *   Intrinsics are synthesised from the actual frame dimensions
- *   (`frame.width`, `frame.height`) plus the host-provided
- *   horizontal/vertical FoV defaults.  The stitcher derives its FoV-
- *   overlap window from these, so the assumed FoV matters for the
- *   gate's overlap math but not for the panorama itself (the
- *   stitcher feature-matches + RANSACs the final alignment).
- *
- * Throttling
- *
- *   `evalEveryNFrames` controls how often the worklet calls the
- *   plugin.  Default 1 (every frame).  Set higher to amortise the
- *   plugin call + consumeFrame's gate evaluation across multiple
- *   producer-thread frames on lower-end devices.  Independent of —
- *   and stacks on top of — the stitcher's own internal
- *   `flowEvalEveryNFrames` (see `KeyframeGate.swift`); both
- *   throttles can be active simultaneously and the effective cadence
- *   is `evalEveryNFrames * flowEvalEveryNFrames`.
- *
- * Lifecycle
- *
- *   `start()` subscribes to the gyro and resets pose accumulators.
- *   `stop()` unsubscribes and resets.  The returned `frameProcessor`
- *   is meant to be passed to `<Camera frameProcessor={...} />` —
- *   it's stable as long as the plugin reference and the FoV props
- *   haven't changed.  Returns `null` when the plugin isn't loaded
- *   yet; pass `null`-or-fallback to the Camera in that case.
- *
- * Pairing with `IncrementalStitcher.start({frameSourceMode})`
- *
- *   The plugin's per-frame call into `consumeFrameFromPlugin` is
- *   gated by `IncrementalStitcher.frameProcessorIngestEnabled`,
- *   which is TRUE only when the stitcher was started with
- *   `frameSourceMode === 'frameProcessor'`.  Hosts MUST call
- *   `incrementalStitcher.start({ frameSourceMode: 'frameProcessor',
- *   ... })` to actually get frames into the engine — otherwise the
- *   worklet runs to completion but the wrapper drops the call.
- *   `Camera.tsx` does this wiring automatically when the host opts
- *   into this driver.
+ * v0.11.0 — refactored to a thin wrapper around `useStitcherWorklet`.
+ * The plugin acquisition + shared-value declarations + gyro
+ * subscription + worklet body all live in `useStitcherWorklet` now;
+ * this hook just binds the returned worklet via vision-camera's
+ * `useFrameProcessor` and exposes the legacy `start` / `stop` /
+ * `isRunning` API for backwards compatibility with v0.10.x.
+ *
+ * ## Why the v0.11.0 split
+ *
+ * vision-camera v4 allows ONE frame processor per `<Camera>` mount.
+ * Pre-v0.11.0, hosts that wanted to compose their own worklet with
+ * the lib's first-party stitching couldn't — passing a host
+ * `frameProcessor` REPLACED the lib's processor.  v0.11.0 closes
+ * this gap by exposing the worklet body via `useStitcherWorklet`
+ * so hosts can write:
+ *
+ *   const stitcher = useStitcherWorklet();
+ *   const fp = useFrameProcessor((frame) => {
+ *     'worklet';
+ *     hostPreLogic(frame);
+ *     stitcher.call(frame);   // ← first-party stitching
+ *     hostPostLogic(frame);
+ *   }, [stitcher.call]);
+ *
+ * `useFrameProcessorDriver` keeps the legacy default-integration
+ * shape (start / stop / isRunning) for the `<Camera>` component's
+ * built-in non-AR path and for any host still using the v0.10.x API
+ * directly.  No behavioural change for those callers.
+ *
+ * ## start / stop behaviour
+ *
+ *   - `start()` calls `stitcher.reset()` to zero the accumulated
+ *     pose (preserves the pre-v0.11.0 "each capture starts with
+ *     pose = (0, 0, 0)" contract).
+ *   - `stop()` also resets the pose (idempotent; matches the
+ *     pre-v0.11.0 stop() side effect of zeroing yaw / pitch / roll).
+ *   - The gyro subscription itself is owned by `useStitcherWorklet`
+ *     and runs for the lifetime of the hook.  In the default
+ *     `<Camera>` integration this means gyro is on while the camera
+ *     screen is mounted — same practical scope as pre-v0.11.0 in
+ *     all observed host integrations (capture screens mount
+ *     `<Camera>` for the duration of capture; idle screens don't).
+ *
+ * ## Pose synthesis / intrinsics / throttling
+ *
+ * Owned by `useStitcherWorklet`.  See that file's header for the
+ * quaternion math, FoV-to-intrinsics derivation, throttle gate, and
+ * pairing-with-IncrementalStitcher.start docs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useFrameProcessorDriver = useFrameProcessorDriver;
 const react_1 = require("react");
-const react_native_sensors_1 = require("react-native-sensors");
-// Reanimated's `useSharedValue` is the documented vision-camera
-// idiom, but it's a heavy peer dep.  `react-native-worklets-core`
-// (already a transitive dep via vision-camera v4 on RN 0.84) exposes
-// the same API surface (a `value` getter/setter readable from
-// worklets and the JS thread) and is sufficient for our use.
-const react_native_worklets_core_1 = require("react-native-worklets-core");
 const react_native_vision_camera_1 = require("react-native-vision-camera");
+const useStitcherWorklet_1 = require("./useStitcherWorklet");
 function useFrameProcessorDriver(options = {}) {
-    const { gyroIntervalMs = 33, fovHorizDegrees = 65, fovVertDegrees = 50, evalEveryNFrames = 1, } = options;
-    // ── Plugin acquisition ──────────────────────────────────────────
-    //
-    // `initFrameProcessorPlugin` can return `undefined` if called
-    // before vision-camera's plugin registry has finished initialising
-    // (race observed in F8.1.a).  We retry on a fixed timer instead of
-    // firing on every render — the earlier render-driven pattern
-    // (adversarial-review H3) re-invoked `initFrameProcessorPlugin`
-    // 60+ times per second during recording, and the vision-camera
-    // contract for repeated lookups is undocumented.
-    //
-    // Pattern: mount-once useEffect, try synchronously, fall back to a
-    // 16-ms retry timer until success or unmount.
-    const [plugin, setPlugin] = (0, react_1.useState)(null);
-    (0, react_1.useEffect)(() => {
-        let cancelled = false;
-        let timerId = null;
-        const tryAcquire = () => {
-            if (cancelled)
-                return;
-            const p = react_native_vision_camera_1.VisionCameraProxy.initFrameProcessorPlugin('cv_flow_gate_process_frame', {});
-            if (p != null) {
-                setPlugin(p);
-                return;
-            }
-            // ~one display-frame retry — matches the F8.1.a observation
-            // that the registry becomes ready by the next render tick.
-            timerId = setTimeout(tryAcquire, 16);
-        };
-        tryAcquire();
-        return () => {
-            cancelled = true;
-            if (timerId != null)
-                clearTimeout(timerId);
-        };
-        // Empty deps on purpose — runs ONCE on mount.  Re-acquiring on
-        // re-render would race with worklet binding.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
-    // ── Shared values (worklet ↔ JS thread) ─────────────────────────
-    //
-    // Reanimated guarantees coherent reads from the producer thread.
-    // We write yaw/pitch on the JS thread (gyro callbacks); the worklet
-    // reads them every frame.  No round-trip cost — these are mapped
-    // into the worklet's runtime by the Reanimated bridge.
-    //
-    // FoV-derived values (the "half-angle tangent reciprocal"
-    // f-numerators) are pre-computed on the JS thread + published via
-    // shared values so the worklet's dependency array shrinks to just
-    // `[plugin]`.  Earlier draft baked `fovHorizDegrees` /
-    // `fovVertDegrees` into the closure → worklet re-serialised on
-    // every host re-render that changed the prop refs (adversarial-
-    // review M1).
-    const sharedYaw = (0, react_native_worklets_core_1.useSharedValue)(0);
-    const sharedPitch = (0, react_native_worklets_core_1.useSharedValue)(0);
-    // F8.3-followup-roll — integrate gyroscope Z (out-of-screen for a
-    // portrait device) to track wrist-twist roll.  Field captures with
-    // casual hand-hold rarely stay perfectly level; without this the
-    // pose stream lies and the cv::Stitcher's intrinsic estimator may
-    // pick a worse projection mode.
-    const sharedRoll = (0, react_native_worklets_core_1.useSharedValue)(0);
-    const sharedFrameCounter = (0, react_native_worklets_core_1.useSharedValue)(0);
-    const sharedEvalEveryN = (0, react_native_worklets_core_1.useSharedValue)(Math.max(1, evalEveryNFrames));
-    const sharedFxNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2)));
-    const sharedFyNumerator = (0, react_native_worklets_core_1.useSharedValue)(1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2)));
-    // Keep prop-derived shared values in sync.  Cheap re-renders;
-    // these don't trigger worklet rebuild.
-    (0, react_1.useEffect)(() => {
-        sharedEvalEveryN.value = Math.max(1, evalEveryNFrames);
-    }, [evalEveryNFrames, sharedEvalEveryN]);
-    (0, react_1.useEffect)(() => {
-        sharedFxNumerator.value =
-            1.0 / (2.0 * Math.tan((fovHorizDegrees * Math.PI / 180) / 2));
-    }, [fovHorizDegrees, sharedFxNumerator]);
-    (0, react_1.useEffect)(() => {
-        sharedFyNumerator.value =
-            1.0 / (2.0 * Math.tan((fovVertDegrees * Math.PI / 180) / 2));
-    }, [fovVertDegrees, sharedFyNumerator]);
-    // ── Lifecycle state (JS thread only) ────────────────────────────
-    const gyroSubRef = (0, react_1.useRef)(null);
-    const lastGyroAtRef = (0, react_1.useRef)(null);
+    // v0.11.0 — delegate plugin / shared values / gyro / worklet body
+    // to `useStitcherWorklet`.  This hook is now a thin wrapper that
+    // binds the returned worklet via `useFrameProcessor` and exposes
+    // the legacy lifecycle API.
+    const stitcher = (0, useStitcherWorklet_1.useStitcherWorklet)(options);
     const isRunningRef = (0, react_1.useRef)(false);
-    const stop = (0, react_1.useCallback)(() => {
-        if (gyroSubRef.current) {
-            gyroSubRef.current.unsubscribe();
-            gyroSubRef.current = null;
-        }
-        isRunningRef.current = false;
-        sharedYaw.value = 0;
-        sharedPitch.value = 0;
-        sharedRoll.value = 0;
-        sharedFrameCounter.value = 0;
-        lastGyroAtRef.current = null;
-    }, [sharedYaw, sharedPitch, sharedRoll, sharedFrameCounter]);
     const start = (0, react_1.useCallback)(() => {
         if (isRunningRef.current)
             return;
-        sharedYaw.value = 0;
-        sharedPitch.value = 0;
-        sharedRoll.value = 0;
-        sharedFrameCounter.value = 0;
-        lastGyroAtRef.current = null;
+        stitcher.reset();
         isRunningRef.current = true;
-        // Gyro integration.  Each sample carries angular velocity in
-        // rad/s; multiply by dt to accumulate displacement.  Axes for a
-        // device held portrait:
-        //   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)
-        // 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.
-        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, gyroIntervalMs);
-        gyroSubRef.current = react_native_sensors_1.gyroscope.subscribe({
-            next: ({ x, y, z }) => {
-                const now = Date.now();
-                if (lastGyroAtRef.current === null) {
-                    lastGyroAtRef.current = now;
-                    return;
-                }
-                const dt = (now - lastGyroAtRef.current) / 1000.0;
-                lastGyroAtRef.current = now;
-                sharedYaw.value += y * dt;
-                sharedPitch.value += x * dt;
-                sharedRoll.value += z * dt;
-            },
-            error: (err) => {
-                // eslint-disable-next-line no-console
-                console.warn('[useFrameProcessorDriver] gyro error', err);
-            },
-        });
-    }, [gyroIntervalMs, sharedYaw, sharedPitch, sharedRoll, sharedFrameCounter]);
-    // ── Worklet ─────────────────────────────────────────────────────
+    }, [stitcher]);
+    const stop = (0, react_1.useCallback)(() => {
+        if (!isRunningRef.current)
+            return;
+        stitcher.reset();
+        isRunningRef.current = false;
+    }, [stitcher]);
+    // ── Worklet binding ─────────────────────────────────────────────
     //
-    // Memoised: rebuilt only when the plugin acquires (null → defined)
-    // or when the FoV props change (cheap math but they're in the
-    // closure so they must be in the deps).  Shared values are NOT in
-    // the deps — Reanimated wires their .value reads through the
-    // worklet's frozen runtime independently of React's render cycle.
+    // `stitcher.call` is itself a worklet (see `useStitcherWorklet`),
+    // so we just forward each frame to it.  Memoised on
+    // [stitcher.call] so the host's `<Camera>` doesn't see frame-
+    // processor identity churn on every render — only when the
+    // underlying plugin acquires (null → non-null).
     const frameProcessor = (0, react_native_vision_camera_1.useFrameProcessor)((frame) => {
         'worklet';
-        if (plugin == null)
-            return;
-        // Throttle: only every Nth frame.  Counter increments first so
-        // frame #0 is "due" (N>=1 always divides 0).  Cheaper than
-        // calling the plugin on rejected frames; saves the ~1 µs
-        // marshalling cost per skip.
-        sharedFrameCounter.value += 1;
-        const N = sharedEvalEveryN.value;
-        if (N > 1 && (sharedFrameCounter.value % N) !== 0)
-            return;
-        // Synthesise quaternion from accumulated yaw + pitch + roll.
-        // YPR Tait-Bryan order: q = q_yaw * q_pitch * q_roll.  When
-        // roll=0 this reduces to the legacy 2-axis form (cy*sp, sy*cp,
-        // -sy*sp, cy*cp), so captures held level produce identical
-        // poses to the pre-F8.3-followup-roll behaviour.  See the
-        // expanded math in the file header doc-comment.
-        const halfYaw = sharedYaw.value / 2;
-        const halfPitch = sharedPitch.value / 2;
-        const halfRoll = sharedRoll.value / 2;
-        const cy_ = Math.cos(halfYaw);
-        const sy_ = Math.sin(halfYaw);
-        const cp = Math.cos(halfPitch);
-        const sp = Math.sin(halfPitch);
-        const cr = Math.cos(halfRoll);
-        const sr = Math.sin(halfRoll);
-        const qx = cy_ * sp * cr + sy_ * cp * sr;
-        const qy = sy_ * cp * cr - cy_ * sp * sr;
-        const qz = cy_ * cp * sr - sy_ * sp * cr;
-        const qw = cy_ * cp * cr + sy_ * sp * sr;
-        // Intrinsics from FoV + actual frame dims.
-        //   fx = w * (1 / (2 * tan(fovH/2)))   (the parenthesised half
-        // is the precomputed `sharedFxNumerator` — see M1 fix).
-        const w = frame.width;
-        const h = frame.height;
-        const fx = w * sharedFxNumerator.value;
-        const fy = h * sharedFyNumerator.value;
-        plugin.call(frame, {
-            tx: 0, ty: 0, tz: 0,
-            qx, qy, qz, qw,
-            fx, fy,
-            cx: w / 2, cy: h / 2,
-            imageWidth: w, imageHeight: h,
-            timestampMs: 0,
-            // 2 == RNSARTrackingState.tracking — we always claim "good
-            // 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
-        // requires worklet rebuild.  All FoV / pose / counter / cadence
-        // values flow through stable shared-value refs that Reanimated
-        // wires through the producer-thread runtime independently of
-        // React's render cycle.  (Adversarial-review M1.)
-    }, [plugin]);
-    // ── Return handle ───────────────────────────────────────────────
-    //
-    // Returns a getter for `isRunning` so callers always see the live
-    // state (the hook itself doesn't re-render on start/stop — that's
-    // intentional, avoids stale-Camera-prop churn).
+        stitcher.call(frame);
+    }, [stitcher.call]);
+    // Match pre-v0.11.0 contract: return `null` for `frameProcessor`
+    // until the underlying JSI plugin has resolved.  `<Camera>` falls
+    // back to `undefined` in the null window so vision-camera doesn't
+    // try to bind an unready worklet.
     return (0, react_1.useMemo)(() => ({
         start,
         stop,
-        frameProcessor: plugin != null ? frameProcessor : null,
+        frameProcessor: stitcher.isReady ? frameProcessor : null,
         get isRunning() { return isRunningRef.current; },
-    }), [start, stop, plugin, frameProcessor]);
+    }), [start, stop, frameProcessor, stitcher.isReady]);
 }
 //# sourceMappingURL=useFrameProcessorDriver.js.map

package/dist/stitching/useStitcherWorklet.d.ts

@@ -0,0 +1,185 @@
+/**
+ * useStitcherWorklet — exposes the lib's first-party stitching as a
+ * callable worklet function for host-composed Frame Processors.
+ *
+ * v0.11.0 — closes the v0.8.0 Phase 5 either-or constraint by letting
+ * hosts COMPOSE: write ONE `useFrameProcessor` worklet body that calls
+ * BOTH your custom logic AND the lib's first-party stitching, instead
+ * of one displacing the other.  See `docs/host-app-integration.md`
+ * § Tier 3 composition for the pattern.
+ *
+ * ## Why this is a separate hook
+ *
+ * vision-camera v4 lets a `<Camera>` mount accept exactly ONE frame
+ * processor.  Pre-v0.11.0, hosts that passed a `frameProcessor` prop
+ * to the lib's `<Camera>` REPLACED the lib's first-party stitching
+ * processor in non-AR mode.  Composing required hand-writing both
+ * worklet bodies in the host's processor.  v0.11.0 extracts the
+ * lib's worklet body into this hook so hosts can compose with a
+ * single call:
+ *
+ *   const stitcher = useStitcherWorklet();
+ *   const fp = useFrameProcessor((frame) => {
+ *     'worklet';
+ *     hostPreLogic(frame);
+ *     stitcher.call(frame);   // ← lib's first-party stitching
+ *     hostPostLogic(frame);
+ *   }, [stitcher.call]);
+ *   return <Camera frameProcessor={fp} ... />;
+ *
+ * AR mode is unaffected — the AR-session dispatch path (v0.8.0 Phase
+ * 4b.i / 4b.iii) already composes natively.
+ *
+ * ## What this owns
+ *
+ *   - vc Frame Processor plugin acquisition for
+ *     `cv_flow_gate_process_frame` (the same plugin the legacy
+ *     `useFrameProcessorDriver` used; reentrant by construction).
+ *   - Shared values backing pose (yaw / pitch / roll), throttle
+ *     counter, every-N gate, and FoV-derived intrinsics scalars.
+ *   - Gyro subscription on the JS thread (always-on between mount
+ *     and unmount; subscription cost is tiny).
+ *   - The worklet body itself: throttle → pose synthesis →
+ *     `plugin.call(frame, params)`.
+ *
+ * ## Lifecycle
+ *
+ *   - Gyro auto-subscribes on mount, auto-unsubscribes on unmount.
+ *     Composed hosts get pose tracking for free.
+ *   - `reset()` zeros the accumulated yaw / pitch / roll between
+ *     captures.  `useFrameProcessorDriver` calls this on `start()` to
+ *     preserve pre-v0.11.0 per-capture pose-reset behaviour;
+ *     composed hosts should call it at the start of each capture too
+ *     (otherwise pose drifts across captures).
+ *
+ * ## Behaviour delta from pre-v0.11.0
+ *
+ *   Before: `useFrameProcessorDriver.start()` subscribed the gyro;
+ *   `stop()` unsubscribed.  The subscription was tied to the
+ *   capture lifecycle.
+ *
+ *   After: the gyro is subscribed for the lifetime of this hook
+ *   (i.e., as long as the component using it is mounted).  In the
+ *   default `<Camera>` integration the hook mounts when the camera
+ *   screen mounts, so the practical effect is the same; in
+ *   custom-composed integrations the host controls mount/unmount
+ *   by mounting/unmounting the component that calls
+ *   `useStitcherWorklet`.  The battery delta is small: gyroscope
+ *   sampling at 33ms costs ≪1% CPU on every Android/iOS device
+ *   the lib supports.
+ *
+ *   `pose reset` semantics are preserved via the new explicit
+ *   `reset()` method.  Hosts that previously relied on `start()`
+ *   to zero pose now call `stitcher.reset()` at the capture start.
+ *
+ * ## Pose synthesis (verbatim from `useFrameProcessorDriver`)
+ *
+ *   Quaternion: q = q_yaw * q_pitch * q_roll (Tait-Bryan YPR, body
+ *   frame).  Expanded:
+ *     qx = cy*sp*cr + sy*cp*sr
+ *     qy = sy*cp*cr - cy*sp*sr
+ *     qz = cy*cp*sr - sy*sp*cr
+ *     qw = cy*cp*cr + sy*sp*sr
+ *
+ *   When roll=0 this collapses to the legacy 2-axis form so captures
+ *   held level produce bit-identical poses to the pre-v0.6 driver
+ *   (and bit-identical to v0.10.x's `useFrameProcessorDriver`).
+ *
+ * ## Throttling (verbatim)
+ *
+ *   `evalEveryNFrames` controls how often the worklet calls the
+ *   plugin.  Default 1.  Independent of — and stacks on top of —
+ *   the stitcher's own internal `flowEvalEveryNFrames` in
+ *   `KeyframeGate.swift`; effective cadence is the product.
+ *
+ * ## Pairing with `IncrementalStitcher.start`
+ *
+ *   The plugin's per-frame call into `consumeFrameFromPlugin` is
+ *   gated by `IncrementalStitcher.frameProcessorIngestEnabled`,
+ *   which is TRUE only when the stitcher was started with
+ *   `frameSourceMode === 'frameProcessor'`.  Hosts MUST call
+ *   `incrementalStitcher.start({ frameSourceMode: 'frameProcessor',
+ *   ... })` to actually get frames into the engine — otherwise the
+ *   worklet runs to completion but the wrapper drops the call.
+ *   `Camera.tsx` does this wiring automatically when the host opts
+ *   into the lib's `useFrameProcessorDriver`.  Hosts that compose
+ *   their own worklet via this hook must do the wiring themselves.
+ */
+import type { Frame } from 'react-native-vision-camera';
+import type { StitcherFrame } from './StitcherFrame';
+/**
+ * Frames the lib's stitching worklet accepts.  Accepting either a
+ * vc `Frame` (what the host's `useFrameProcessor` body sees) or the
+ * lib's `StitcherFrame` (what the lib's `useFrameProcessor` body
+ * sees) keeps the same `useStitcherWorklet` usable from both kinds
+ * of host worklet bodies without a cast on the call site.  The
+ * worklet only reads `width` / `height`; the rest of the frame
+ * object is forwarded verbatim to the native plugin.
+ */
+export type StitcherWorkletInput = Frame | StitcherFrame;
+export interface UseStitcherWorkletOptions {
+    /**
+     * Gyro sample interval in ms (~30 Hz default).  Drives the JS-
+     * thread pose integration loop; not the producer-thread plugin
+     * call rate.
+     */
+    gyroIntervalMs?: number;
+    /**
+     * Approximate horizontal FoV of the device camera, used to
+     * synthesise `fx` from frame width.  Default 65° matches a typical
+     * mid-tier smartphone main camera.
+     */
+    fovHorizDegrees?: number;
+    /**
+     * Approximate vertical FoV of the device camera, used to
+     * synthesise `fy` from frame height.  Default 50° matches a typical
+     * 4:3 phone camera in landscape; for 16:9 portrait you probably
+     * want ~75°.
+     */
+    fovVertDegrees?: number;
+    /**
+     * Evaluate the plugin every Nth producer-thread frame.  Default 1
+     * (every frame).
+     */
+    evalEveryNFrames?: number;
+}
+export interface StitcherWorkletHandle {
+    /**
+     * Worklet function: pass a `StitcherFrame` to perform one frame of
+     * the lib's first-party stitching (throttle + pose synthesis +
+     * native plugin call).  Safe to call from inside another
+     * `'worklet'`-prefixed function (this is the canonical
+     * composition pattern).
+     *
+     * The returned function reference is stable across re-renders as
+     * long as the plugin reference doesn't change (which happens at
+     * most once — at the moment the JSI plugin finishes
+     * registering).  Include `stitcher.call` in your `useFrameProcessor`
+     * deps so the host worklet rebuilds when the plugin acquires.
+     *
+     * Safe to invoke before the plugin is ready: the worklet
+     * internally short-circuits (the frame is silently skipped).
+     * Hosts that want to display a "stitcher initialising…" UI can
+     * read `isReady` to gate their own behaviour.
+     */
+    call: (frame: StitcherWorkletInput) => void;
+    /**
+     * Zero accumulated yaw / pitch / roll.  Call at the start of each
+     * capture so the pose stream starts from `(0, 0, 0)` instead of
+     * carrying drift from the previous capture or from idle time
+     * between captures.  Idempotent; safe to call from JS.
+     */
+    reset: () => void;
+    /**
+     * `true` once the JSI Frame Processor plugin
+     * (`cv_flow_gate_process_frame`) has resolved.  Before this flips
+     * `true`, `call(frame)` is a no-op (the plugin reference is
+     * `null`).  Hosts integrating via `useFrameProcessorDriver` use
+     * this to decide whether to render the frame-processor at all —
+     * the driver returns `null` for `frameProcessor` until ready, so
+     * `<Camera>` falls back gracefully.
+     */
+    isReady: boolean;
+}
+export declare function useStitcherWorklet(options?: UseStitcherWorkletOptions): StitcherWorkletHandle;
+//# sourceMappingURL=useStitcherWorklet.d.ts.map