react-native-image-stitcher 0.1.0

package/dist/camera/useVideoCapture.js

@@ -0,0 +1,151 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useVideoCapture — video recording + frame extraction API.
+ *
+ * Sibling of ``useCapture`` for the "sweep a shelf with a video" flow
+ * that feeds the stitcher.  The hook's state machine is:
+ *
+ *     idle → recording → stopping → idle  (success)
+ *     idle → recording → idle             (recording errored)
+ *     idle → recording → stopping → idle  (user cancelled)
+ *
+ * API shape — `startRecording` returns a `Promise<VideoFile>` that:
+ *   - resolves with the recorded file when the user releases the
+ *     shutter and `stopRecording()` is called (vision-camera fires
+ *     `onRecordingFinished`),
+ *   - rejects if vision-camera fires `onRecordingError` at any point
+ *     (e.g. `<Camera>` was rendered without `video={true}`, disk
+ *     full mid-recording, permission revoked).
+ *
+ * Why a single future instead of separate finished/error callbacks?
+ *   Lets host code use the natural async/await pattern.  Earlier we
+ *   used a callback + a parked resolver in the host screen; that
+ *   masked start-time errors (the resolver hung forever) and produced
+ *   confusing cascade errors when `stopRecording` ran against a
+ *   non-recording camera.
+ *
+ * Frame extraction lives behind the `extractFrames` method but is
+ * deferred to the higher-level `stitchVideo()` SDK API now — host
+ * apps shouldn't have to manage their own tmp dir.  This shim is
+ * kept for parity / future use; it currently throws.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useVideoCapture = useVideoCapture;
+const react_1 = require("react");
+function useVideoCapture() {
+    const [state, setState] = (0, react_1.useState)('idle');
+    /**
+     * The active recording's resolve/reject handles.  Set when
+     * `startRecording` is called; cleared when vision-camera fires
+     * `onRecordingFinished` / `onRecordingError`, or when the host
+     * calls `cancelRecording`.
+     *
+     * Stored in a ref (not state) because vision-camera's callbacks
+     * fire outside React's render cycle and need synchronous access
+     * to the latest handles.
+     */
+    const recordingFutureRef = (0, react_1.useRef)(null);
+    const startRecording = (0, react_1.useCallback)(async (cameraRef) => {
+        if (!cameraRef.current) {
+            throw new Error('useVideoCapture.startRecording: cameraRef is null');
+        }
+        if (recordingFutureRef.current !== null) {
+            throw new Error('useVideoCapture.startRecording: a recording is already in progress');
+        }
+        // Brief settle before kicking off a fresh recording.
+        // vision-camera's AVCaptureSession needs ~100 ms after a
+        // previous stopRecording completes before it can cleanly
+        // start a new one — without this, rapid record→stop→record
+        // cycles (typical when the user does a panorama, then another
+        // panorama right after) can crash the session.
+        await new Promise((r) => setTimeout(r, 150));
+        return new Promise((resolve, reject) => {
+            recordingFutureRef.current = { resolve, reject };
+            setState('recording');
+            cameraRef.current.startRecording({
+                onRecordingFinished: (video) => {
+                    const future = recordingFutureRef.current;
+                    recordingFutureRef.current = null;
+                    setState('idle');
+                    // If the future was cleared (cancelled), drop the file
+                    // on the floor.  vision-camera still wrote it to disk;
+                    // that's a known cleanup gap for a future iteration.
+                    future?.resolve(video);
+                },
+                onRecordingError: (err) => {
+                    const future = recordingFutureRef.current;
+                    recordingFutureRef.current = null;
+                    setState('idle');
+                    // eslint-disable-next-line no-console
+                    console.error('[useVideoCapture] recording error', err);
+                    future?.reject(err);
+                },
+            });
+        });
+    }, []);
+    const stopRecording = (0, react_1.useCallback)(async (cameraRef) => {
+        // No-op if there's nothing to stop — protects against the
+        // cascade where startRecording errored synchronously and the
+        // host's release handler still calls stop.
+        if (recordingFutureRef.current === null)
+            return;
+        if (!cameraRef.current)
+            return;
+        setState('stopping');
+        try {
+            await cameraRef.current.stopRecording();
+        }
+        catch (err) {
+            // The native call can throw "no-recording-in-progress" if
+            // the recording was already finalised by an error path.
+            // The future has its own error handling; we just absorb so
+            // the host's await doesn't see a confusing secondary error.
+            // eslint-disable-next-line no-console
+            console.warn('[useVideoCapture] stopRecording threw', err);
+        }
+    }, []);
+    const cancelRecording = (0, react_1.useCallback)(async (cameraRef) => {
+        const future = recordingFutureRef.current;
+        // Clear FIRST so the eventual onRecordingFinished/Error
+        // callback no-ops on a null ref instead of fulfilling a
+        // promise the caller has already moved past.
+        recordingFutureRef.current = null;
+        if (future) {
+            future.reject(new Error('useVideoCapture: recording cancelled'));
+        }
+        if (!cameraRef.current) {
+            setState('idle');
+            return;
+        }
+        setState('stopping');
+        try {
+            await cameraRef.current.stopRecording();
+        }
+        catch {
+            // Expected when no recording is in flight.
+        }
+        finally {
+            setState('idle');
+        }
+    }, []);
+    const extractFrames = (0, react_1.useCallback)(async (_opts) => {
+        setState('extracting');
+        try {
+            throw new Error('[react-native-image-stitcher] useVideoCapture.extractFrames is not '
+                + 'available — use `stitchVideo()` from the SDK index, which '
+                + 'combines extract + stitch in a single native call.');
+        }
+        finally {
+            setState('idle');
+        }
+    }, []);
+    return {
+        state,
+        startRecording,
+        stopRecording,
+        cancelRecording,
+        extractFrames,
+    };
+}
+//# sourceMappingURL=useVideoCapture.js.map

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * react-native-image-stitcher — public API surface.
+ *
+ * Single component (`<Camera>`) + supporting types + the two public
+ * hooks the design doc calls out (`useARSession`, `useIMUTranslationGate`).
+ * Everything else (internal sub-components, drivers, bridges) is
+ * deliberately NOT re-exported so the v0.1.0 → 1.0 stability window
+ * doesn't lock us into an inflated public surface.
+ *
+ * If you need access to something that used to be exported and isn't
+ * now, please open an issue describing the use-case before reaching
+ * into the package internals.
+ *
+ * Public/private split: this lib is the open-source foundation.  The
+ * `retailens-camera-sdk` package depends on this lib and adds
+ * RetaiLens-specific features (measurement, packet detection, etc.)
+ * on top.  Consumers wanting those features install
+ * `retailens-camera-sdk` instead.
+ */
+export { Camera, CameraError } from './camera/Camera';
+export type { CameraProps, CameraCaptureResult, CameraErrorCode, CaptureSource, CameraLens, StitchMode, Blender, SeamFinder, Warper, FramesDroppedInfo, } from './camera/Camera';
+export { useARSession, ARTrackingState } from './ar/useARSession';
+export type { UseARSessionReturn, FramePose, } from './ar/useARSession';
+export { useIMUTranslationGate } from './sensors/useIMUTranslationGate';
+export type { UseIMUTranslationGateOptions, UseIMUTranslationGateReturn, } from './sensors/useIMUTranslationGate';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,39 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * react-native-image-stitcher — public API surface.
+ *
+ * Single component (`<Camera>`) + supporting types + the two public
+ * hooks the design doc calls out (`useARSession`, `useIMUTranslationGate`).
+ * Everything else (internal sub-components, drivers, bridges) is
+ * deliberately NOT re-exported so the v0.1.0 → 1.0 stability window
+ * doesn't lock us into an inflated public surface.
+ *
+ * If you need access to something that used to be exported and isn't
+ * now, please open an issue describing the use-case before reaching
+ * into the package internals.
+ *
+ * Public/private split: this lib is the open-source foundation.  The
+ * `retailens-camera-sdk` package depends on this lib and adds
+ * RetaiLens-specific features (measurement, packet detection, etc.)
+ * on top.  Consumers wanting those features install
+ * `retailens-camera-sdk` instead.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useIMUTranslationGate = exports.ARTrackingState = exports.useARSession = exports.CameraError = exports.Camera = void 0;
+// ── The main component ────────────────────────────────────────────────────
+var Camera_1 = require("./camera/Camera");
+Object.defineProperty(exports, "Camera", { enumerable: true, get: function () { return Camera_1.Camera; } });
+Object.defineProperty(exports, "CameraError", { enumerable: true, get: function () { return Camera_1.CameraError; } });
+// ── AR foundation (public per design doc) ─────────────────────────────────
+// Hosts that want raw AR pose access (e.g., to build their own
+// measurement/detection on top) consume these directly.
+var useARSession_1 = require("./ar/useARSession");
+Object.defineProperty(exports, "useARSession", { enumerable: true, get: function () { return useARSession_1.useARSession; } });
+Object.defineProperty(exports, "ARTrackingState", { enumerable: true, get: function () { return useARSession_1.ARTrackingState; } });
+// ── IMU translation gate (public per design doc R5) ───────────────────────
+// Hosts running their own non-AR capture flow can reuse this hook to
+// get the same gating logic <Camera> uses internally.
+var useIMUTranslationGate_1 = require("./sensors/useIMUTranslationGate");
+Object.defineProperty(exports, "useIMUTranslationGate", { enumerable: true, get: function () { return useIMUTranslationGate_1.useIMUTranslationGate; } });
+//# sourceMappingURL=index.js.map

package/dist/quality/normaliseOrientation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * normaliseOrientation — bake EXIF rotation into a JPEG's pixels.
+ *
+ * vision-camera writes photos with the camera sensor's native
+ * landscape pixels and an EXIF Orientation tag describing how to
+ * rotate them for display.  Most consumers (iOS UIImage, RN's
+ * `<Image>`) honour the tag — but enough don't (Sentry breadcrumbs,
+ * share sheets, the cv::Stitcher itself, third-party image
+ * pipelines) that "what's on disk" diverges from "what the user
+ * sees" unless we eagerly normalise.
+ *
+ * This helper round-trips the file through the SDK's native
+ * stitcher module, which decodes the JPEG with EXIF rotation
+ * applied and re-encodes a clean JPEG with no orientation
+ * metadata.  Idempotent on already-normalised files.
+ */
+export interface NormaliseOrientationResult {
+    /** Image width in pixels AFTER rotation has been applied. */
+    width: number;
+    /** Image height in pixels AFTER rotation. */
+    height: number;
+}
+/**
+ * Bake the EXIF rotation of `imagePath` into pixels in-place.
+ *
+ * Returns the post-rotation dimensions so the caller can update
+ * its own width/height fields.  No-op on platforms that don't
+ * have the native module yet (Android until Phase 3) — falls back
+ * to the input shape so callers don't have to special-case
+ * platform availability.
+ */
+export declare function normaliseOrientation(imagePath: string, fallback?: {
+    width: number;
+    height: number;
+}): Promise<NormaliseOrientationResult>;
+//# sourceMappingURL=normaliseOrientation.d.ts.map

package/dist/quality/normaliseOrientation.js

@@ -0,0 +1,62 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * normaliseOrientation — bake EXIF rotation into a JPEG's pixels.
+ *
+ * vision-camera writes photos with the camera sensor's native
+ * landscape pixels and an EXIF Orientation tag describing how to
+ * rotate them for display.  Most consumers (iOS UIImage, RN's
+ * `<Image>`) honour the tag — but enough don't (Sentry breadcrumbs,
+ * share sheets, the cv::Stitcher itself, third-party image
+ * pipelines) that "what's on disk" diverges from "what the user
+ * sees" unless we eagerly normalise.
+ *
+ * This helper round-trips the file through the SDK's native
+ * stitcher module, which decodes the JPEG with EXIF rotation
+ * applied and re-encodes a clean JPEG with no orientation
+ * metadata.  Idempotent on already-normalised files.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normaliseOrientation = normaliseOrientation;
+const react_native_1 = require("react-native");
+/**
+ * Bake the EXIF rotation of `imagePath` into pixels in-place.
+ *
+ * Returns the post-rotation dimensions so the caller can update
+ * its own width/height fields.  No-op on platforms that don't
+ * have the native module yet (Android until Phase 3) — falls back
+ * to the input shape so callers don't have to special-case
+ * platform availability.
+ */
+async function normaliseOrientation(imagePath, fallback) {
+    const native = react_native_1.NativeModules['BatchStitcher'];
+    const fn = native
+        && typeof native === 'object'
+        && typeof native.normaliseOrientation === 'function'
+        ? native.normaliseOrientation
+        : null;
+    if (!fn) {
+        // Native module not registered (typically Android in current
+        // builds).  Skip normalisation and report the caller's
+        // fallback dimensions if provided, otherwise zeroes — keeps
+        // the API total without forcing every caller to wrap a
+        // try/catch.
+        if (fallback)
+            return fallback;
+        // eslint-disable-next-line no-console
+        console.warn(`[capture-sdk] normaliseOrientation: native module not available on ${react_native_1.Platform.OS}.  `
+            + 'Photo orientation may render incorrectly until the native module is registered.');
+        return { width: 0, height: 0 };
+    }
+    try {
+        return await fn({ imagePath });
+    }
+    catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn('[capture-sdk] normaliseOrientation failed', err);
+        if (fallback)
+            return fallback;
+        throw err;
+    }
+}
+//# sourceMappingURL=normaliseOrientation.js.map

package/dist/quality/runQualityCheck.d.ts

@@ -0,0 +1,41 @@
+/**
+ * runQualityCheck — public entry point for the SDK's blur + brightness
+ * quality gate.  Delegates to the native module
+ * `RNImageStitcherQualityChecker` when registered (iOS today via
+ * `ios/Sources/RNImageStitcher/QualityChecker.swift`, Android in
+ * Phase 3); falls back to a conservative pass-through shim when the
+ * native module is absent so dev / Jest runs don't crash on a missing
+ * NativeModules entry.
+ *
+ * The shim NEVER fails an image — false negatives in production are
+ * worse than missing data.  The native path is the only branch that
+ * can return `passed=false`.
+ */
+import type { QualityReport, QualityThresholds } from '../types';
+/**
+ * Numeric scores produced by the native module.  The bridge resolves
+ * with `{ blurScore, brightnessScore }` — issues are computed in JS
+ * so the same threshold logic applies on iOS + Android even if a
+ * platform's native impl evolves independently.
+ */
+interface NativeQualityScores {
+    blurScore: number;
+    brightnessScore: number;
+}
+/**
+ * Analyse an image file and return a quality report.
+ *
+ * @param imagePath Filesystem path to the image (with or without
+ *                  `file://` prefix — the native module strips it).
+ * @param thresholds Cut-offs the report scores against.
+ */
+export declare function runQualityCheck(imagePath: string, thresholds: QualityThresholds): Promise<QualityReport>;
+/**
+ * Apply thresholds to native scores → produce the report shape the JS
+ * surface promises.  Pure function so it's trivially unit-testable.
+ *
+ * Exported for tests; not part of the SDK's public API.
+ */
+export declare function scoreToReport(scores: NativeQualityScores, thresholds: QualityThresholds): QualityReport;
+export {};
+//# sourceMappingURL=runQualityCheck.d.ts.map

package/dist/quality/runQualityCheck.js

@@ -0,0 +1,98 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * runQualityCheck — public entry point for the SDK's blur + brightness
+ * quality gate.  Delegates to the native module
+ * `RNImageStitcherQualityChecker` when registered (iOS today via
+ * `ios/Sources/RNImageStitcher/QualityChecker.swift`, Android in
+ * Phase 3); falls back to a conservative pass-through shim when the
+ * native module is absent so dev / Jest runs don't crash on a missing
+ * NativeModules entry.
+ *
+ * The shim NEVER fails an image — false negatives in production are
+ * worse than missing data.  The native path is the only branch that
+ * can return `passed=false`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runQualityCheck = runQualityCheck;
+exports.scoreToReport = scoreToReport;
+const react_native_1 = require("react-native");
+let warnedOnce = false;
+/**
+ * Analyse an image file and return a quality report.
+ *
+ * @param imagePath Filesystem path to the image (with or without
+ *                  `file://` prefix — the native module strips it).
+ * @param thresholds Cut-offs the report scores against.
+ */
+async function runQualityCheck(imagePath, thresholds) {
+    const native = react_native_1.NativeModules['RNImageStitcherQualityChecker'];
+    // Native path: registered + has the bridged `measure` method.
+    if (native
+        && typeof native === 'object'
+        && typeof native.measure === 'function') {
+        const scores = await native
+            .measure(imagePath);
+        return scoreToReport(scores, thresholds);
+    }
+    // Shim fallback — never reached when the SDK's native module is linked
+    // into the host app correctly.  Surfaces a one-time warning in dev so
+    // misconfiguration is loud rather than silent.
+    if (!warnedOnce && __DEV__) {
+        // eslint-disable-next-line no-console
+        console.warn('[react-native-image-stitcher] QualityChecker native module not '
+            + `found on ${react_native_1.Platform.OS}; falling back to optimistic shim.  Check `
+            + 'autolinking + a clean `pod install` (iOS) / `gradle clean` (Android).');
+        warnedOnce = true;
+    }
+    void thresholds;
+    return {
+        passed: true,
+        blurScore: Number.POSITIVE_INFINITY,
+        brightnessScore: 128,
+        issues: [],
+    };
+}
+/**
+ * Apply thresholds to native scores → produce the report shape the JS
+ * surface promises.  Pure function so it's trivially unit-testable.
+ *
+ * Exported for tests; not part of the SDK's public API.
+ */
+function scoreToReport(scores, thresholds) {
+    const issues = [];
+    if (scores.blurScore < thresholds.minBlurScore) {
+        issues.push({
+            type: 'blur',
+            message: `Image is too blurry (Laplacian variance ${scores.blurScore.toFixed(1)} `
+                + `< ${thresholds.minBlurScore}). Hold the camera steady and retry.`,
+            severity: 'error',
+        });
+    }
+    if (scores.brightnessScore < thresholds.minBrightness) {
+        issues.push({
+            type: 'brightness_low',
+            message: `Image is too dark (mean luminance ${scores.brightnessScore.toFixed(0)} `
+                + `< ${thresholds.minBrightness}). Add light or move closer to a lit area.`,
+            severity: 'warning',
+        });
+    }
+    else if (scores.brightnessScore > thresholds.maxBrightness) {
+        issues.push({
+            type: 'brightness_high',
+            message: `Image is overexposed (mean luminance ${scores.brightnessScore.toFixed(0)} `
+                + `> ${thresholds.maxBrightness}). Reduce light or move out of direct sunlight.`,
+            severity: 'warning',
+        });
+    }
+    return {
+        // `passed` is the strict gate — only `error`-severity issues block.
+        // Brightness warnings are advisory; SOS is still computable from a
+        // dim or bright photo, but a blurry one isn't.
+        passed: issues.every((i) => i.severity !== 'error'),
+        blurScore: scores.blurScore,
+        brightnessScore: scores.brightnessScore,
+        issues,
+    };
+}
+//# sourceMappingURL=runQualityCheck.js.map

package/dist/sensors/useIMUTranslationGate.d.ts

@@ -0,0 +1,70 @@
+export interface UseIMUTranslationGateOptions {
+    /**
+     * Whether the gate is engaged.  Pass `false` to skip the subscription
+     * entirely — useful when the host is in AR mode (where the gate
+     * gets pose-derived translation natively).  Hot-toggleable;
+     * subscribing/unsubscribing is cheap.
+     */
+    enabled: boolean;
+    /**
+     * Translation budget in METRES along the device-X (pan) axis.
+     * When the integrated displacement magnitude exceeds this since
+     * the last accept, the hook fires `onBudgetExceeded`.  Default
+     * 0.40 m / 40 cm (80 % of the 50 cm default
+     * `flowMaxTranslationCm`).  Caller typically passes
+     * `panoramaSettings.flowMaxTranslationCm * 0.8 / 100`.
+     */
+    budgetMeters?: number;
+    /**
+     * Update interval in MILLISECONDS for the DeviceMotion sensor.
+     * Default 20 ms ≈ 50 Hz.  Lower (faster sampling) = more accurate
+     * integration; higher = lower CPU + battery.  Matches the previous
+     * raw-accel cadence so reset/integrate behaviour stays comparable.
+     */
+    sampleIntervalMs?: number;
+    /**
+     * Fired exactly once per "budget crossing" — i.e., when the
+     * running translation along device-X crosses `budgetMeters` from
+     * below.  The host is responsible for both (a) calling
+     * `IncrementalStitcher.markNextFrameAsLastKeyframe()` and
+     * (b) invoking the returned `resetAnchor()` once the next
+     * keyframe actually accepts, so the integrator restarts from zero.
+     */
+    onBudgetExceeded: () => void;
+    /**
+     * 2026-05-18 (Issue #4 investigation) — when true, log every Nth
+     * accelerometer sample (default N=20 ≈ 400 ms at 50 Hz) showing
+     * the current `acceleration.x`, accumulated `posX`, and time
+     * since anchor reset.  Helps diagnose drift behaviour vs real
+     * translation magnitude in field testing.  Defaults to false —
+     * production captures stay quiet.
+     */
+    debug?: boolean;
+}
+export interface UseIMUTranslationGateReturn {
+    /**
+     * Reset the running translation to zero.  Call this at recording
+     * start AND after each confirmed keyframe accept — the typical
+     * wiring is to subscribe to `IncrementalStateUpdate` and
+     * call `resetAnchor()` from inside the listener AND from the host's
+     * `handleHoldStart`.
+     */
+    resetAnchor: () => void;
+    /**
+     * Read the current running displacement along device-X in METRES.
+     * Returns the absolute value (sign is uninteresting — either left
+     * or right counts the same toward the budget).
+     * Useful for the on-screen debug HUD ("translation since last
+     * accept: 0.07 m").  Not exposed via state — host polls if needed.
+     */
+    getCurrentTranslationM: () => number;
+}
+/**
+ * IMU-based translation tracker — single-axis (device-X / pan axis),
+ * fused IMU via `expo-sensors` `DeviceMotion`.  See file header for
+ * algorithm + rationale.  No platform-specific code; the underlying
+ * native fusion is platform-aware (CoreMotion on iOS, fused
+ * `TYPE_LINEAR_ACCELERATION` on Android).
+ */
+export declare function useIMUTranslationGate(options: UseIMUTranslationGateOptions): UseIMUTranslationGateReturn;
+//# sourceMappingURL=useIMUTranslationGate.d.ts.map