react-native-image-stitcher 0.1.0

package/dist/stitching/incremental.js

@@ -0,0 +1,133 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Incremental panorama-stitching native module bindings.
+ *
+ * See docs/site-content/design/2026-04-30-realtime-incremental-stitching.md
+ * for the architectural rationale.  This file is the type-safe JS
+ * wrapper around the RN bridge; `useIncrementalStitcher` is the hook
+ * host code consumes; `IncrementalStitcherView` renders the live
+ * panorama preview.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncrementalOutcome = void 0;
+exports.getIncrementalNativeModule = getIncrementalNativeModule;
+exports.incrementalStitcherIsAvailable = incrementalStitcherIsAvailable;
+exports.cleanupOldKeyframes = cleanupOldKeyframes;
+exports.subscribeIncrementalState = subscribeIncrementalState;
+const react_native_1 = require("react-native");
+/**
+ * Per-frame outcome returned by the engine.  Mirrors the iOS
+ * `RLISFrameOutcome` enum and the Android equivalent — numeric
+ * values are kept identical so the JS layer doesn't branch on
+ * platform.
+ */
+var IncrementalOutcome;
+(function (IncrementalOutcome) {
+    /** High-confidence accept — silent UX. */
+    IncrementalOutcome[IncrementalOutcome["AcceptedHigh"] = 0] = "AcceptedHigh";
+    /** Accept with marginal confidence — show subtle yellow ring. */
+    IncrementalOutcome[IncrementalOutcome["AcceptedMedium"] = 1] = "AcceptedMedium";
+    /** Frame too close to the previous accepted — wait for more pan. */
+    IncrementalOutcome[IncrementalOutcome["SkippedTooClose"] = 2] = "SkippedTooClose";
+    /** Frame too far past the overlap window — show "slow down" hint. */
+    IncrementalOutcome[IncrementalOutcome["RejectedTooFar"] = 3] = "RejectedTooFar";
+    /** Too few feature matches — show "scene too uniform" hint. */
+    IncrementalOutcome[IncrementalOutcome["RejectedSceneUniform"] = 4] = "RejectedSceneUniform";
+    /** RANSAC failed or homography degenerate — show "alignment lost". */
+    IncrementalOutcome[IncrementalOutcome["RejectedAlignmentLost"] = 5] = "RejectedAlignmentLost";
+    /** AR tracking quality was poor — skip silently. */
+    IncrementalOutcome[IncrementalOutcome["SkippedTrackingPoor"] = 6] = "SkippedTrackingPoor";
+    /**
+     * V12.11 Step D — operator panned BACKWARDS past the running
+     * max along the pan axis.  Engine has SKIPPED the paste; host
+     * should auto-finalize the capture (the most useful pano is
+     * what we have so far at the high-water mark).  Emitted by
+     * the rectilinear engine only — cylindrical engines tolerate
+     * reverse motion via their warp pipeline.
+     */
+    IncrementalOutcome[IncrementalOutcome["RejectedReverseDirection"] = 7] = "RejectedReverseDirection";
+    /**
+     * V16 — pose-driven keyframe gate rejected the frame because it
+     * overlapped >= (1 − overlapThreshold) with the last accepted
+     * keyframe.  Host should keep showing the same status — user is
+     * mid-pan between two natural keyframe boundaries.  No UX hint
+     * needed (this is the expected behaviour 90% of the time when
+     * pose-based selection is on).
+     */
+    IncrementalOutcome[IncrementalOutcome["SkippedKeyframeOverlap"] = 8] = "SkippedKeyframeOverlap";
+    /**
+     * V16 — pose-driven keyframe gate rejected the frame because the
+     * capture has hit `keyframeMaxCount` (default 6).  Host should
+     * auto-finalize since no more frames will be accepted.
+     */
+    IncrementalOutcome[IncrementalOutcome["SkippedKeyframeMaxReached"] = 9] = "SkippedKeyframeMaxReached";
+})(IncrementalOutcome || (exports.IncrementalOutcome = IncrementalOutcome = {}));
+/**
+ * Lazy-resolve the native module.  Returns null on platforms that
+ * don't have it registered yet (e.g. older builds without the new
+ * native code).  Callers fall back to the batch stitcher in that
+ * case.
+ */
+function getIncrementalNativeModule() {
+    const m = react_native_1.NativeModules['IncrementalStitcher'];
+    if (!m || typeof m !== 'object')
+        return null;
+    // The cast is safe — RN runtime sees only `Function` for each
+    // method but TypeScript's structural type system is happy with
+    // a record of any-callable.
+    return m;
+}
+/**
+ * Whether the native incremental stitcher is registered and ready.
+ * Equivalent to `getIncrementalNativeModule() !== null`; provided
+ * as a convenience export so host code reads cleanly.
+ */
+function incrementalStitcherIsAvailable() {
+    return getIncrementalNativeModule() !== null;
+}
+/**
+ * 2026-05-18 (Iss 3) — host-callable helper to clean up old
+ * keyframe sessions.  Wraps the native `cleanupKeyframes` with a
+ * sensible default (24 hours) and a noop fallback when the native
+ * method isn't implemented (older SDK builds).
+ *
+ * Typical use: call this in App.tsx's mount effect or from a
+ * background-task hook so storage stays bounded between captures.
+ *
+ * Resolves with the count of sessions deleted + bytes freed so the
+ * host can log / surface a "cleaned up X MB" message.  Never
+ * rejects — filesystem failures (including ENOENT on the captures
+ * dir) resolve as `{ sessionsDeleted: 0, bytesFreed: 0 }`.
+ */
+async function cleanupOldKeyframes(options) {
+    const native = getIncrementalNativeModule();
+    if (!native?.cleanupKeyframes) {
+        return { sessionsDeleted: 0, bytesFreed: 0 };
+    }
+    try {
+        const olderThanMs = options?.olderThanMs ?? 24 * 3600 * 1000;
+        return await native.cleanupKeyframes({ olderThanMs });
+    }
+    catch {
+        return { sessionsDeleted: 0, bytesFreed: 0 };
+    }
+}
+/**
+ * Subscribe to per-frame state updates emitted by the native engine.
+ * The returned `EmitterSubscription` MUST be removed when no longer
+ * needed (`subscription.remove()`); leaks here cause memory growth
+ * across captures.
+ */
+function subscribeIncrementalState(listener) {
+    const native = getIncrementalNativeModule();
+    if (!native)
+        return null;
+    // Cast through the structural NativeModule type — the bridge
+    // module IS an RCTEventEmitter at runtime, which exposes
+    // addListener/removeListeners as part of the contract.  TS just
+    // can't see the iOS side's class hierarchy.
+    const emitter = new react_native_1.NativeEventEmitter(react_native_1.NativeModules.IncrementalStitcher);
+    return emitter.addListener('IncrementalStateUpdate', listener);
+}
+//# sourceMappingURL=incremental.js.map

package/dist/stitching/stitchFrames.d.ts

@@ -0,0 +1,55 @@
+/**
+ * stitchFrames — video / frame stitching API.
+ *
+ * Implementation status (Phase 2 of #8):
+ *   - iOS: Swift native module that vendors upstream OpenCV's iOS
+ *     framework and calls `cv::Stitcher::SCANS` mode (designed for
+ *     translational shelf captures).  Lives in
+ *     `retailens-capture-sdk/ios/Sources/RNImageStitcher/`.
+ *   - Android: deferred to Phase 3 — same OpenCV surface, different
+ *     build (NDK + Gradle).  Until that lands, Android calls hit the
+ *     `StitchNotImplementedError` path below.
+ *
+ * Why fail loudly instead of falling back to JS?
+ *   The cloud-sync pipeline depends on a stitched panorama being
+ *   present.  Silently producing a broken or single-frame "panorama"
+ *   would corrupt downstream SOS computation.  Hard-failing here lets
+ *   the host app surface the unsupported-platform error to the user
+ *   immediately rather than discovering it on the server hours later.
+ */
+export interface StitchFramesOptions {
+    /**
+     * Absolute paths to the input image files in capture order.
+     * Must share a camera + focal length (we don't blend across sources).
+     */
+    framePaths: string[];
+    /**
+     * Output path for the stitched image (JPEG).  Host app chooses the
+     * location (tmp vs. cache vs. Documents).
+     */
+    outputPath: string;
+    /** JPEG quality [0-100].  Default 85. */
+    quality?: number;
+}
+export interface StitchFramesResult {
+    /** Absolute path to the stitched image on disk. */
+    outputPath: string;
+    /** Pixel dimensions of the stitched image. */
+    width: number;
+    height: number;
+    /** Wall-clock ms the stitcher took (host apps log this for perf tracking). */
+    durationMs: number;
+}
+/**
+ * Stitch ``framePaths`` into a single panoramic image.
+ *
+ * Throws ``StitchNotImplementedError`` until the native module ships.
+ * Callers should catch that specific error and fall back gracefully
+ * (e.g. surface a "single-frame mode only" banner in the UI).
+ */
+export declare function stitchFrames(options: StitchFramesOptions): Promise<StitchFramesResult>;
+export declare class StitchNotImplementedError extends Error {
+    readonly code = "STITCH_NOT_IMPLEMENTED";
+    constructor(message: string);
+}
+//# sourceMappingURL=stitchFrames.d.ts.map

package/dist/stitching/stitchFrames.js

@@ -0,0 +1,56 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * stitchFrames — video / frame stitching API.
+ *
+ * Implementation status (Phase 2 of #8):
+ *   - iOS: Swift native module that vendors upstream OpenCV's iOS
+ *     framework and calls `cv::Stitcher::SCANS` mode (designed for
+ *     translational shelf captures).  Lives in
+ *     `retailens-capture-sdk/ios/Sources/RNImageStitcher/`.
+ *   - Android: deferred to Phase 3 — same OpenCV surface, different
+ *     build (NDK + Gradle).  Until that lands, Android calls hit the
+ *     `StitchNotImplementedError` path below.
+ *
+ * Why fail loudly instead of falling back to JS?
+ *   The cloud-sync pipeline depends on a stitched panorama being
+ *   present.  Silently producing a broken or single-frame "panorama"
+ *   would corrupt downstream SOS computation.  Hard-failing here lets
+ *   the host app surface the unsupported-platform error to the user
+ *   immediately rather than discovering it on the server hours later.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StitchNotImplementedError = void 0;
+exports.stitchFrames = stitchFrames;
+const react_native_1 = require("react-native");
+/**
+ * Stitch ``framePaths`` into a single panoramic image.
+ *
+ * Throws ``StitchNotImplementedError`` until the native module ships.
+ * Callers should catch that specific error and fall back gracefully
+ * (e.g. surface a "single-frame mode only" banner in the UI).
+ */
+async function stitchFrames(options) {
+    // Look for the native module by its canonical name so we can flip
+    // this function to "implemented" simply by registering the module
+    // in AppDelegate / MainApplication.
+    const native = react_native_1.NativeModules['BatchStitcher'];
+    if (native && typeof native === 'object' && 'stitch' in native) {
+        const fn = native.stitch;
+        return fn(options);
+    }
+    throw new StitchNotImplementedError(`stitchFrames is not yet implemented on ${react_native_1.Platform.OS}. `
+        + 'The react-native-image-stitcher native stitcher module is expected '
+        + 'but not registered — the JS shim is throwing by design so the '
+        + 'host app can fall back to single-frame mode rather than ship '
+        + 'broken panoramas.');
+}
+class StitchNotImplementedError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'STITCH_NOT_IMPLEMENTED';
+        this.name = 'StitchNotImplementedError';
+    }
+}
+exports.StitchNotImplementedError = StitchNotImplementedError;
+//# sourceMappingURL=stitchFrames.js.map

package/dist/stitching/stitchVideo.d.ts

@@ -0,0 +1,119 @@
+/**
+ * stitchVideo — end-to-end "video → panorama" API.
+ *
+ * The host app records video while the user holds the shutter; on
+ * release we hand the video file path to this function and it
+ * returns a single stitched panoramic JPEG.  Internally:
+ *
+ *   1. Native side extracts N evenly-spaced frames from the video
+ *      (AVAssetImageGenerator on iOS, MediaMetadataRetriever on
+ *      Android once Phase 3 lands).
+ *   2. Native side feeds the frames into `cv::Stitcher::SCANS`.
+ *   3. Frames are deleted; only the final panorama remains.
+ *
+ * The single bridge call keeps the JS thread out of the
+ * extract→stitch dance entirely; nothing has to round-trip frame
+ * paths back to JS just to hand them to a sibling native call.
+ */
+import type { StitchFramesResult } from './stitchFrames';
+export interface StitchVideoOptions {
+    /**
+     * Absolute path to the recorded video file.  Accepts paths with
+     * or without the `file://` prefix — the native module strips it.
+     */
+    videoPath: string;
+    /**
+     * Where the resulting panoramic JPEG should be written.
+     */
+    outputPath: string;
+    /**
+     * Number of frames to sample from the video.  Default 10 — the
+     * empirical sweet spot for shelf scans on iPhone hardware: enough
+     * overlap that homography stays robust, few enough that stitching
+     * stays under 4 seconds.  Increase only if the user pans further
+     * than ~1 m of shelf in a single hold.
+     */
+    maxFrames?: number;
+    /**
+     * JPEG quality [0..100].  Applied to BOTH the intermediate frames
+     * (extracted from video) AND the final panorama.  Default 85.
+     */
+    quality?: number;
+    /**
+     * Projection used during the warp step.  See native side for
+     * details.  Default `'plane'` — straight verticals/horizontals,
+     * good for shelf scans + close-up subjects.  Hourglass shape on
+     * partial arcs is handled by the rectangular-crop step.
+     *   - `'plane'`: flat projection.  Best for ≤30° pans.
+     *   - `'cylindrical'`: handles rotational mid-arc pans.
+     *   - `'spherical'`: full 90°+ panoramic captures.
+     */
+    warperType?: 'plane' | 'cylindrical' | 'spherical';
+    /**
+     * Blending strategy across stitched seams.
+     *   - `'multiband'` (default): high-quality seams when alignment
+     *     is good; can produce visible halos when adjacent frames
+     *     have inconsistent exposure.
+     *   - `'feather'`: simple alpha-weighted blend; faster + no
+     *     halo artifacts; slightly more visible seam edge.
+     */
+    blenderType?: 'multiband' | 'feather';
+    /**
+     * Seam finding strategy.
+     *   - `'graphcut'` (default): cv::detail::GraphCutSeamFinder
+     *     finds optimal cuts before blending — pairs beautifully
+     *     with `multiband`, but holds all warped frames in memory
+     *     simultaneously (higher peak).
+     *   - `'skip'`: streams warp+feed in a single pass, never
+     *     holding more than one warped frame.  Lower peak memory.
+     *     Right choice on low-RAM devices or with `feather`.
+     */
+    seamFinderType?: 'graphcut' | 'skip';
+    /**
+     * Phase 5: pose-driven stitching.  When present and non-empty,
+     * the native stitcher skips features → matching → BundleAdjuster
+     * and builds cv::detail::CameraParams directly from each pose's
+     * intrinsics + quaternion.  Each entry has the shape returned
+     * by `NativeModules.RNSARSession.snapshotPoseLog()`:
+     *
+     *   { tx, ty, tz, qx, qy, qz, qw,
+     *     fx, fy, cx, cy,
+     *     imageWidth, imageHeight,
+     *     timestampMs, trackingState }
+     *
+     * Frames whose closest pose is beyond a 100 ms tolerance are
+     * dropped before stitching; if fewer than 2 remain the call
+     * rejects with `opencv-failed-1032` so the host can fall back
+     * to the feature-matched path (re-call `stitchVideo` without
+     * `poses`).
+     */
+    poses?: Array<{
+        tx: number;
+        ty: number;
+        tz: number;
+        qx: number;
+        qy: number;
+        qz: number;
+        qw: number;
+        fx: number;
+        fy: number;
+        cx: number;
+        cy: number;
+        imageWidth: number;
+        imageHeight: number;
+        timestampMs: number;
+        trackingState: number;
+    }>;
+}
+/**
+ * Stitch a recorded video file into a single panoramic JPEG.
+ *
+ * Throws `StitchNotImplementedError` on platforms where the native
+ * stitcher hasn't shipped yet (Android until Phase 3).  Throws an
+ * Error with a code-like message on stitcher failures the JS layer
+ * may want to recover from (see `StitcherError` cases on the native
+ * side: `insufficient-frames`, `read-failed`, `write-failed`,
+ * `opencv-failed-<code>`).
+ */
+export declare function stitchVideo(options: StitchVideoOptions): Promise<StitchFramesResult>;
+//# sourceMappingURL=stitchVideo.d.ts.map

package/dist/stitching/stitchVideo.js

@@ -0,0 +1,57 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * stitchVideo — end-to-end "video → panorama" API.
+ *
+ * The host app records video while the user holds the shutter; on
+ * release we hand the video file path to this function and it
+ * returns a single stitched panoramic JPEG.  Internally:
+ *
+ *   1. Native side extracts N evenly-spaced frames from the video
+ *      (AVAssetImageGenerator on iOS, MediaMetadataRetriever on
+ *      Android once Phase 3 lands).
+ *   2. Native side feeds the frames into `cv::Stitcher::SCANS`.
+ *   3. Frames are deleted; only the final panorama remains.
+ *
+ * The single bridge call keeps the JS thread out of the
+ * extract→stitch dance entirely; nothing has to round-trip frame
+ * paths back to JS just to hand them to a sibling native call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stitchVideo = stitchVideo;
+const react_native_1 = require("react-native");
+const stitchFrames_1 = require("./stitchFrames");
+/**
+ * Stitch a recorded video file into a single panoramic JPEG.
+ *
+ * Throws `StitchNotImplementedError` on platforms where the native
+ * stitcher hasn't shipped yet (Android until Phase 3).  Throws an
+ * Error with a code-like message on stitcher failures the JS layer
+ * may want to recover from (see `StitcherError` cases on the native
+ * side: `insufficient-frames`, `read-failed`, `write-failed`,
+ * `opencv-failed-<code>`).
+ */
+async function stitchVideo(options) {
+    const native = react_native_1.NativeModules['BatchStitcher'];
+    if (native
+        && typeof native === 'object'
+        && typeof native.stitchVideo === 'function') {
+        const fn = native.stitchVideo;
+        // 60-second hard deadline.  cv::Stitcher::stitch can occasionally
+        // grind for minutes inside bundle adjustment on hard inputs (low
+        // texture, extreme parallax).  A timeout converts those into a
+        // clear UI error rather than letting the stitching banner sit
+        // forever.  Real stitches finish in 2-8 seconds on iPhone with
+        // the tuned PANORAMA settings; 60 s is comfortably above that.
+        return Promise.race([
+            fn(options),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error('stitch-timeout: stitching took longer than 30 s')), 30000);
+            }),
+        ]);
+    }
+    throw new stitchFrames_1.StitchNotImplementedError(`stitchVideo is not yet implemented on ${react_native_1.Platform.OS}. `
+        + 'The react-native-image-stitcher native stitcher module is expected '
+        + 'but not registered (or the build predates Phase 2.5 of #8).');
+}
+//# sourceMappingURL=stitchVideo.js.map

package/dist/stitching/useIncrementalJSDriver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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