react-native-image-stitcher 0.15.1 → 0.16.0

package/dist/camera/pickCaptureFormat.js

@@ -0,0 +1,85 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * pickCaptureFormat — choose the vision-camera format for the capture stream.
+ *
+ * Replaces a plain `useCameraFormat([{ videoResolution: 'max' }, …])`, which
+ * picks the device's MAX-video format and lets the PHOTO resolution ride
+ * along — on the iPhone 16 Pro ultra-wide that pairs a **48 MP** still
+ * (8064×6048) with the 4032×3024 max-video format, so a tap photo came out
+ * ~6000 px.  vision-camera 4.x exposes each format's photo/video resolution
+ * but NOT its pixel format / bit-depth, so we can't filter for 8-bit; the
+ * empirical rule is that the device's MAX 4:3 video format is 8-bit (the
+ * frame processor needs 8-bit for non-AR stitching), and lower video
+ * resolutions risk 10-bit.
+ *
+ * Strategy: among the ~4:3 formats whose photo long-edge is within
+ * `maxPhotoLongEdge`, pick the one with the HIGHEST video resolution (keeps
+ * the preview/stitch stream as sharp as possible while bounding the still),
+ * tie-breaking on higher fps, then the largest photo under the cap, then
+ * non-HDR (a hedge toward 8-bit).  If NO format fits the cap, fall back to
+ * the overall max-video format (never returns nothing for a non-empty list).
+ *
+ * Verified against the real iPhone 16 Pro ultra-wide format list (see the
+ * unit test): cap 4032 → 4032×3024 photo (12 MP) + 3264×2448 video (was
+ * 8064×6048 photo); cap 2048 → 2016×1512 photo (3 MP) + 1920×1440 video.
+ *
+ * Pure + structurally-typed (no vision-camera import) so it unit-tests in the
+ * node jest env; `CameraDeviceFormat` is structurally assignable to
+ * `FormatLike`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickCaptureFormat = pickCaptureFormat;
+const DEFAULT_MAX_PHOTO_LONG_EDGE = 4032;
+const DEFAULT_FPS_TARGET = 60;
+const longEdge = (f) => Math.max(f.photoWidth, f.photoHeight);
+const videoPixels = (f) => f.videoWidth * f.videoHeight;
+/**
+ * Pick the best capture format, or `undefined` for an empty list.
+ */
+function pickCaptureFormat(formats, opts = {}) {
+    if (!formats || formats.length === 0)
+        return undefined;
+    const aspect = opts.aspect ?? 4 / 3;
+    const tol = opts.aspectTolerance ?? 0.05;
+    const cap = opts.maxPhotoLongEdge ?? DEFAULT_MAX_PHOTO_LONG_EDGE;
+    const preferHighFps = opts.preferHighFps ?? false;
+    const fpsTarget = opts.fpsTarget ?? DEFAULT_FPS_TARGET;
+    // Treat everything at/above the target as equally smooth so resolution, not
+    // a chase for 120 fps, breaks the tie.
+    const smoothness = (f) => Math.min(f.maxFps, fpsTarget);
+    const matchesAspect = (f) => f.photoHeight > 0
+        && f.videoHeight > 0
+        && Math.abs(f.photoWidth / f.photoHeight - aspect) < tol
+        && Math.abs(f.videoWidth / f.videoHeight - aspect) < tol;
+    // Prefer 4:3 formats; if the device has none, consider all.
+    const fourThree = formats.filter(matchesAspect);
+    const base = fourThree.length > 0 ? fourThree : formats.slice();
+    // Among those within the photo cap; if none fit, fall back to all (which
+    // then resolves to the max-video format — never worse than today).
+    const withinCap = cap > 0 ? base.filter((f) => longEdge(f) <= cap) : base.slice();
+    const candidates = withinCap.length > 0 ? withinCap : base;
+    return candidates.slice().sort((a, b) => {
+        if (preferHighFps) {
+            // Smooth-preview priority: frame rate (up to the target) before video
+            // resolution.  Keeps the panorama preview at ~60 fps instead of dropping
+            // to a sharper-but-30fps format.
+            const sa = smoothness(a);
+            const sb = smoothness(b);
+            if (sb !== sa)
+                return sb - sa;
+        }
+        const va = videoPixels(a);
+        const vb = videoPixels(b);
+        if (vb !== va)
+            return vb - va; // highest video resolution first
+        if (b.maxFps !== a.maxFps)
+            return b.maxFps - a.maxFps; // then higher fps
+        if (longEdge(b) !== longEdge(a))
+            return longEdge(b) - longEdge(a); // largest photo under cap
+        // Prefer non-HDR — a hedge toward an 8-bit pixel format (the stitch
+        // frame processor needs 8-bit; vision-camera doesn't expose bit-depth).
+        return (a.supportsVideoHdr ? 1 : 0) - (b.supportsVideoHdr ? 1 : 0);
+    })[0];
+}
+//# sourceMappingURL=pickCaptureFormat.js.map

package/dist/camera/stitchDebugInfo.d.ts

@@ -0,0 +1,27 @@
+/**
+ * buildStitchDebugInfo — format the stitcher's runtime stats as a compact,
+ * multi-line string for the __DEV__-only overlay on the output preview.
+ *
+ * The operator uses this to SEE how a panorama was built — which pipeline +
+ * warper ran, whether the low-memory stream/feather fallback kicked in, the
+ * confidence score the successful attempt used, and how many keyframes
+ * survived pruning.  Purely presentational; never shown in release.
+ *
+ * Pure + structurally typed so it unit-tests in the node jest env.
+ */
+export interface StitchDebugFields {
+    /** Native `debugSummary`: `"pipe=…;warp=…;route=…;seam=…;blend=…"`. */
+    debugSummary?: string;
+    stitchModeResolved?: 'panorama' | 'scans';
+    finalConfidenceThresh?: number;
+    framesIncluded?: number;
+    framesRequested?: number;
+    width?: number;
+    height?: number;
+}
+/**
+ * Build the overlay text.  Returns `''` when nothing useful is present (so the
+ * caller can skip rendering the pill entirely).  One `key: value` per line.
+ */
+export declare function buildStitchDebugInfo(r: StitchDebugFields): string;
+//# sourceMappingURL=stitchDebugInfo.d.ts.map

package/dist/camera/stitchDebugInfo.js

@@ -0,0 +1,55 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * buildStitchDebugInfo — format the stitcher's runtime stats as a compact,
+ * multi-line string for the __DEV__-only overlay on the output preview.
+ *
+ * The operator uses this to SEE how a panorama was built — which pipeline +
+ * warper ran, whether the low-memory stream/feather fallback kicked in, the
+ * confidence score the successful attempt used, and how many keyframes
+ * survived pruning.  Purely presentational; never shown in release.
+ *
+ * Pure + structurally typed so it unit-tests in the node jest env.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildStitchDebugInfo = buildStitchDebugInfo;
+/**
+ * Build the overlay text.  Returns `''` when nothing useful is present (so the
+ * caller can skip rendering the pill entirely).  One `key: value` per line.
+ */
+function buildStitchDebugInfo(r) {
+    const lines = [];
+    // Expand the native summary ("pipe=manual;warp=spherical;…") into one
+    // labelled line per pair, preserving order.  Malformed pairs are skipped.
+    if (r.debugSummary) {
+        for (const pair of r.debugSummary.split(';')) {
+            const eq = pair.indexOf('=');
+            if (eq <= 0)
+                continue;
+            const key = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (key && value)
+                lines.push(`${key}: ${value}`);
+        }
+    }
+    if (r.stitchModeResolved)
+        lines.push(`mode: ${r.stitchModeResolved}`);
+    if (typeof r.finalConfidenceThresh === 'number'
+        && r.finalConfidenceThresh >= 0) {
+        lines.push(`score: ${r.finalConfidenceThresh.toFixed(2)}`);
+    }
+    if (typeof r.framesIncluded === 'number' && r.framesIncluded >= 0) {
+        const req = typeof r.framesRequested === 'number' && r.framesRequested >= 0
+            ? String(r.framesRequested)
+            : '?';
+        lines.push(`frames: ${r.framesIncluded}/${req}`);
+    }
+    if (typeof r.width === 'number'
+        && typeof r.height === 'number'
+        && r.width > 0
+        && r.height > 0) {
+        lines.push(`size: ${r.width}×${r.height}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=stitchDebugInfo.js.map

package/dist/camera/usePanMotion.d.ts

@@ -0,0 +1,250 @@
+/**
+ * usePanMotion — one sensor-fed hook that exposes the three motion
+ * signals the first-time-user GUIDANCE surfaces share, so the screen
+ * spins up ONE gyroscope + ONE accelerometer subscription instead of
+ * three independent ones.
+ *
+ * Consumers
+ *   - Item 3 (pan how-to / direction arrow) wants `resolvedAxis` to
+ *     know whether the user is panning horizontally or vertically.
+ *   - Item 4 ("Moving too fast, slow down") wants `panSpeedBucket`.
+ *   - Item 6 (lateral-drift → finalize + popup) wants `lateralCm` /
+ *     `lateralExceeded`.
+ *
+ * Why one hook (and not three components each subscribing)
+ *   `react-native-sensors` is global: every `gyroscope.subscribe` /
+ *   `accelerometer.subscribe` adds a listener to the same underlying
+ *   native sensor, and `setUpdateIntervalForType` is process-wide.
+ *   Three subscribers means three JS callbacks per native sample +
+ *   three teardown paths to get right.  Funnelling the shared signals
+ *   through one hook keeps the sensor wiring in a single place.
+ *
+ * ── Speed bucket (Item 4) ────────────────────────────────────────
+ * Reuses `PanoramaGuidance`'s gyro logic verbatim (see `bucketFor`
+ * below, lifted from that file): take the dominant rotation axis for
+ * the current pan direction and map |rad/s| onto good / warn / bad.
+ *   horizontal pan (portrait, Mode B)  → gyro Y dominates.
+ *   vertical   pan (landscape, Mode A) → gyro X dominates.
+ * Defaults 0.5 / 1.0 rad/s match `PanoramaGuidance`'s SCANS tuning.
+ *
+ * ── Lateral drift (Item 6) ───────────────────────────────────────
+ * This is the subtle part.  `useIMUTranslationGate` integrates the
+ * accelerometer along **device-X**, because in BOTH pan modes the
+ * pan axis maps to device-X (portrait: user left/right; landscape:
+ * device-X has rotated 90° into user up/down).  That gate's X
+ * integrator RESETS at every accepted keyframe (and auto-rearms on
+ * each budget fire) — see its header — because it measures
+ * translation-*along*-the-pan between keyframes.
+ *
+ * Lateral drift is the ORTHOGONAL motion: the operator sliding the
+ * phone sideways out of the pan plane.  Orthogonal to device-X is
+ * **device-Y**, in both modes.  So we integrate device-Y here.
+ *
+ * Crucially this accumulator must measure drift over the WHOLE
+ * capture, not per-keyframe — a slow continuous sideways creep would
+ * never trip a per-keyframe-reset budget.  So unlike the gate's
+ * `posX`, our `posY` resets ONLY on `active` false → true (capture
+ * start).  It is never reset by keyframe accepts (this hook doesn't
+ * even know about them).
+ *
+ * We borrow the gate's drift-mitigation recipe (per-axis IIR gravity
+ * estimate + per-sample velocity damping + iOS G→m/s² scaling) so the
+ * lateral integrator has the same noise floor characteristics.
+ *
+ * Grace window
+ *   A short slide as the operator settles their grip at capture start
+ *   shouldn't fire the "you drifted" popup.  `lateralExceeded` only
+ *   latches once the budget has been *continuously* exceeded for
+ *   `LATERAL_GRACE_MS` (default 500 ms).  A dip back under budget
+ *   resets the grace timer, so a single wobble that crosses and
+ *   immediately recrosses the threshold never latches.  Once latched
+ *   it STAYS latched until the next capture (matches Item 6's
+ *   product decision: finalize what's captured, then show the popup —
+ *   we don't un-finalize if the phone wobbles back).
+ *
+ * Performance
+ *   Gyro at ~30 Hz, accel at ~50 Hz, all integrator state in refs.
+ *   `setState` fires only on a *qualitative* change (bucket flips, or
+ *   the exceeded latch trips) — never per sample.  `lateralCm` is the
+ *   one exception consumers may want live; it's exposed via the
+ *   returned object but only re-rendered on the throttled tick (see
+ *   `LATERAL_EMIT_INTERVAL_MS`) so a debug/HUD readout updates without
+ *   a 50 Hz re-render storm.
+ */
+export type PanSpeedBucket = 'good' | 'warn' | 'bad';
+/**
+ * Pan axis in user-perceived terms:
+ *   'horizontal' → portrait, pan left↔right  (Mode B).
+ *   'vertical'   → landscape, pan up↕down     (Mode A).
+ * Same vocabulary as `PanoramaGuidance`'s `PanAxis`.
+ */
+export type PanAxis = 'horizontal' | 'vertical';
+export interface UsePanMotionOptions {
+    /**
+     * Subscribe to the sensors only while this is true.  Typically the
+     * host's `statusPhase === 'recording'`.  Teardown on inactive so
+     * the gyro/accel aren't running the rest of the time the screen is
+     * up.  The lateral accumulator zeroes on every false → true edge.
+     */
+    active: boolean;
+    /**
+     * Force the pan axis instead of auto-detecting from device
+     * orientation.  Matches `PanoramaGuidance`'s `axis` prop: hosts
+     * that lock orientation but want the user to pan the orthogonal
+     * axis pass this.  Default: auto-detect — 'horizontal' in portrait,
+     * 'vertical' in landscape.
+     */
+    axis?: PanAxis;
+    /**
+     * Gyro rate (rad/s) at/below which the pan is 'good'.  Default 0.5,
+     * same as `PanoramaGuidance`'s SCANS tuning.
+     */
+    goodMaxRadPerSec?: number;
+    /**
+     * Gyro rate (rad/s) at/below which the pan is 'warn' (above 'good').
+     * Above it is 'bad'.  Default 1.0.
+     */
+    warnMaxRadPerSec?: number;
+    /**
+     * Lateral (cross-pan) translation budget in CENTIMETRES.  Once the
+     * integrated |lateral| exceeds this for `LATERAL_GRACE_MS`,
+     * `lateralExceeded` latches true.  Default 5 cm.
+     */
+    lateralBudgetCm?: number;
+}
+export interface UsePanMotionReturn {
+    /** Qualitative pan speed for the dominant gyro axis. */
+    panSpeedBucket: PanSpeedBucket;
+    /**
+     * Signed lateral (cross-pan) translation since capture start, in
+     * centimetres.  Updates on a throttled tick (~10 Hz), not per
+     * sample.  Useful for a debug/HUD readout; the latch decision uses
+     * the un-throttled internal value.
+     */
+    lateralCm: number;
+    /**
+     * `true` once |lateralCm| has exceeded `lateralBudgetCm`
+     * continuously for the grace window.  Latching — stays true until
+     * the next capture (`active` false → true).
+     */
+    lateralExceeded: boolean;
+    /** Resolved pan axis (after auto-detect / `axis` override). */
+    resolvedAxis: PanAxis;
+}
+/**
+ * Map a signed rotation rate (rad/s) onto the qualitative speed
+ * bucket.  Pure — exported for tests.  Lifted verbatim from
+ * `PanoramaGuidance.bucketFor` so the two surfaces never diverge.
+ *
+ * Thresholds are INCLUSIVE of the lower band: `|rate| <= good` is
+ * 'good', `|rate| <= warn` is 'warn', otherwise 'bad'.
+ */
+export declare function _bucketForRate(rate: number, good: number, warn: number): PanSpeedBucket;
+/**
+ * Pick the dominant gyro axis value for a pan direction.  Mirrors
+ * `PanoramaGuidance`'s `resolvedAxis === 'horizontal' ? y : x`:
+ *   horizontal pan (portrait)  → gyro Y dominates.
+ *   vertical   pan (landscape) → gyro X dominates.
+ * Pure — exported for tests.
+ */
+export declare function _gyroRateForAxis(axis: PanAxis, gyro: {
+    x: number;
+    y: number;
+}): number;
+/**
+ * Resolve the pan axis the same way `PanoramaGuidance` does:
+ *   explicit `axis` override wins; otherwise portrait → 'horizontal',
+ *   landscape → 'vertical'.  Pure — exported for tests.
+ */
+export declare function _resolvePanAxis(orientation: 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right', override?: PanAxis): PanAxis;
+/**
+ * Internal lateral-integrator state.  One device axis (device-Y, the
+ * cross-pan axis) integrated to a position, with the same IIR-gravity
+ * + velocity-damping recipe as `useIMUTranslationGate`'s X gate.
+ *
+ * Unlike that gate, `pos` is NEVER reset by keyframe accepts — only by
+ * `resetLateralState` at capture start — so it accumulates total
+ * cross-pan drift across the whole capture.
+ */
+export interface LateralState {
+    /** Integrated cross-pan position, METRES. */
+    pos: number;
+    /** Integrated cross-pan velocity, m/s. */
+    vel: number;
+    /** IIR-estimated gravity component on the cross-pan axis (m/s²). */
+    gravity: number;
+    /**
+     * `true` once the latch has tripped; stays true for the capture.
+     * Mirrors `useIMUTranslationGate`'s `fired`, but here it never
+     * auto-rearms (drift is a one-shot finalize, not a re-trigger).
+     */
+    exceeded: boolean;
+    /**
+     * Timestamp (ms, performance.now-style) at which |pos| first went
+     * over budget in the current continuous over-budget run, or `null`
+     * if currently under budget.  Drives the grace window.
+     */
+    overBudgetSinceMs: number | null;
+}
+/**
+ * Result of one grace-window latch evaluation: the (possibly latched)
+ * exceeded flag + the (possibly cleared/started) continuous-over-budget
+ * timer.  See `_evalGraceLatch`.
+ */
+export interface GraceLatchResult {
+    exceeded: boolean;
+    overBudgetSinceMs: number | null;
+}
+/**
+ * Pure grace-window latch decision, factored out of the integrator so
+ * the debounce is testable without constructing a physical
+ * acceleration profile.  Given whether |pos| is currently over budget,
+ * the clock, and the prior latch/timer state, decide the next state:
+ *
+ *   - under budget          → clear the timer; never un-latch.
+ *   - over budget, no timer  → start the timer (note: NOT yet latched).
+ *   - over budget, timer old  → latch once `now - since >= graceMs`.
+ *   - already latched        → stays latched forever (one-shot
+ *                              finalize; see header).
+ *
+ * @param overBudget  is |pos| currently over the budget?
+ * @param nowMs       monotonic clock, ms
+ * @param prevSinceMs timestamp |pos| first went over in the current
+ *                    continuous run, or `null` if previously under
+ * @param prevExceeded already-latched flag from the prior sample
+ * @param graceMs     continuous dwell required before latching
+ */
+export declare function _evalGraceLatch(overBudget: boolean, nowMs: number, prevSinceMs: number | null, prevExceeded: boolean, graceMs: number): GraceLatchResult;
+/** A fresh integrator, as seeded at every capture start. */
+export declare function _freshLateralState(): LateralState;
+/**
+ * Reset the integrator in place for a new capture.  Zeroes position,
+ * velocity, the latch, and the grace timer, and re-arms gravity
+ * seeding.  Pure (mutates the passed object, returns it) — exported so
+ * tests can assert the "resets only at capture start" contract.
+ */
+export declare function _resetLateralState(s: LateralState): LateralState;
+/**
+ * Advance the lateral integrator by one accelerometer sample.  Pure
+ * (mutates + returns the passed state) so the integration math is
+ * unit-testable without a sensor or a React render.
+ *
+ * @param s         running integrator state (mutated in place)
+ * @param rawAxis   raw cross-pan accel reading for this sample, in the
+ *                  platform's native unit (G's on iOS, m/s² on
+ *                  Android) — caller has NOT yet applied `scale`
+ * @param scale     unit scale (G_TO_MPS2 on iOS, 1 on Android)
+ * @param dt        sample period, seconds
+ * @param budgetM   lateral budget, METRES
+ * @param graceMs   continuous-over-budget dwell before latching, ms
+ * @param nowMs     monotonic clock for this sample, ms
+ * @returns the same `s` (mutated): `pos` is the new cross-pan position
+ *          in metres; `exceeded` is the latched flag.
+ *
+ * NOTE the first call only seeds gravity and returns with `pos`
+ * unchanged (matches `useIMUTranslationGate`'s first-sample handling)
+ * — the first reading is assumed to be ~stationary at capture start.
+ */
+export declare function _integrateLateralSample(s: LateralState, rawAxis: number, scale: number, dt: number, budgetM: number, graceMs: number, nowMs: number): LateralState;
+export declare function usePanMotion({ active, axis, goodMaxRadPerSec, warnMaxRadPerSec, lateralBudgetCm, }: UsePanMotionOptions): UsePanMotionReturn;
+//# sourceMappingURL=usePanMotion.d.ts.map