react-native-image-stitcher 0.1.0

package/dist/camera/IncrementalPanGuide.js

@@ -0,0 +1,267 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * IncrementalPanGuide — V12.11 Step 2 (item 2 of the four-step
+ * preview-UX overhaul).
+ *
+ * Apple-pano-style "keep the arrow on the line" pan guide for the
+ * incremental capture flow.
+ *
+ *                  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+ *                                  ▲
+ *                                  ●     ← marker drifts perpendicular
+ *                  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ← guide line
+ *                                                                (along pan axis)
+ *                  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─
+ *
+ * The user is told (via the band overlay's caption) to pan along
+ * one axis.  This guide gives them live feedback on how WELL they
+ * are obeying that instruction:
+ *
+ *   • A solid GUIDE LINE runs along the intended pan axis (the
+ *     "ideal" pan path) across the centre of the screen.
+ *   • A circular MARKER sits on the line.  As the user tilts the
+ *     device perpendicular to the pan axis, the marker drifts
+ *     OFF the line by an amount proportional to the integrated
+ *     perpendicular rotation since capture started.
+ *   • The marker's COLOUR signals how far off they've drifted —
+ *     green (on track), amber (slight drift), red (significant
+ *     drift).  Same colour scale as PanoramaGuidance for
+ *     consistency.
+ *
+ * Why integrate perpendicular rotation rather than absolute device
+ * angle?  We don't care about the user's starting orientation (they
+ * may begin a horizontal pan with the phone tilted slightly down
+ * — that's fine).  We care about CHANGE during the pan.  So we
+ * reset the integral to 0 at `active=true` and accumulate the
+ * perpendicular gyro rate from there.  Drift over a typical 5–10 s
+ * capture is well within tolerance (a few degrees max).
+ *
+ * Why not consume ARKit pose?  Two reasons:
+ *   1. The vision-camera (non-AR) capture path doesn't have ARKit
+ *      pose at all — gyro is the only common signal.
+ *   2. We want this guide to work the SAME way regardless of
+ *      whether AR mode is on or off — gyro keeps the UX
+ *      consistent.
+ *
+ * Performance: gyro at 30 Hz, integration is two multiplies per
+ * sample, marker position update via setState.  Negligible.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IncrementalPanGuide = IncrementalPanGuide;
+const react_1 = __importStar(require("react"));
+const react_native_1 = require("react-native");
+const react_native_sensors_1 = require("react-native-sensors");
+const useDeviceOrientation_1 = require("./useDeviceOrientation");
+const COLOR_GOOD = '#34C759';
+const COLOR_WARN = '#FFCC00';
+const COLOR_BAD = '#FF3B30';
+function bucketFor(absRad, warn, bad) {
+    if (absRad <= warn)
+        return 'good';
+    if (absRad <= bad)
+        return 'warn';
+    return 'bad';
+}
+function colorFor(bucket) {
+    switch (bucket) {
+        case 'good': return COLOR_GOOD;
+        case 'warn': return COLOR_WARN;
+        case 'bad': return COLOR_BAD;
+    }
+}
+/**
+ * Pan axis vs orientation — same convention as
+ * PanoramaBandOverlay (and PanoramaGuidance):
+ *   • portrait   → pan horizontal → guide line is HORIZONTAL across
+ *                  the screen, marker drifts vertically.
+ *   • landscape  → pan vertical → guide line is VERTICAL down the
+ *                  screen, marker drifts horizontally.
+ */
+function panAxis(orientation) {
+    return orientation === 'landscape-left' || orientation === 'landscape-right'
+        ? 'vertical'
+        : 'horizontal';
+}
+function IncrementalPanGuide({ active, pixelsPerRad = 600, maxTravelPx = 80, warnRad = 0.05, // ≈ 2.9°
+badRad = 0.10, // ≈ 5.7°
+style, }) {
+    const orientation = (0, useDeviceOrientation_1.useDeviceOrientation)();
+    const axis = panAxis(orientation);
+    // Integrated PERPENDICULAR rotation since `active` flipped true.
+    // Held in a ref so per-sample updates don't re-render.  We re-
+    // render only when the displayed marker offset (rounded to int
+    // px) or colour bucket changes.
+    const perpIntegralRef = (0, react_1.useRef)(0);
+    const lastSampleTsRef = (0, react_1.useRef)(null);
+    // Displayed marker offset in px (signed; sign tells us which
+    // side of the line the user has drifted to).  Capped to
+    // ±maxTravelPx.  Rounded to int to keep React reconciliation
+    // cheap (one re-render per integer pixel of travel).
+    const [markerOffsetPx, setMarkerOffsetPx] = (0, react_1.useState)(0);
+    const [bucket, setBucket] = (0, react_1.useState)('good');
+    const lastBucketRef = (0, react_1.useRef)('good');
+    const lastOffsetRef = (0, react_1.useRef)(0);
+    (0, react_1.useEffect)(() => {
+        // Inactive: reset integral and on-screen state so the next
+        // capture starts at a clean zero.
+        if (!active) {
+            perpIntegralRef.current = 0;
+            lastSampleTsRef.current = null;
+            lastBucketRef.current = 'good';
+            lastOffsetRef.current = 0;
+            setMarkerOffsetPx(0);
+            setBucket('good');
+            return;
+        }
+        (0, react_native_sensors_1.setUpdateIntervalForType)(react_native_sensors_1.SensorTypes.gyroscope, 33);
+        let subscription = react_native_sensors_1.gyroscope.subscribe({
+            next: ({ x, y }) => {
+                // The PERPENDICULAR axis is the orthogonal one to the pan:
+                //   portrait  pans horizontally → pan axis = gyro Y →
+                //               perp axis = gyro X (pitch — head up/down).
+                //   landscape pans vertically   → pan axis = gyro X →
+                //               perp axis = gyro Y (yaw — head left/right).
+                const perpRate = axis === 'horizontal' ? x : y;
+                // Δt in seconds since the previous sample.  Use Date.now()
+                // rather than the upstream's `timestamp` field because
+                // react-native-sensors emits seconds on iOS and ms on
+                // Android — Date.now() is unambiguous and reliable enough
+                // at 30 Hz integration.
+                const nowMs = Date.now();
+                const last = lastSampleTsRef.current ?? nowMs;
+                const dt = Math.min(0.1, Math.max(0, (nowMs - last) / 1000));
+                lastSampleTsRef.current = nowMs;
+                perpIntegralRef.current += perpRate * dt;
+                // Convert integral (radians) → px offset, clamp.
+                const rawPx = perpIntegralRef.current * pixelsPerRad;
+                const clampedPx = Math.max(-maxTravelPx, Math.min(maxTravelPx, rawPx));
+                const roundedPx = Math.round(clampedPx);
+                // setState only when the rounded px changed — keeps the
+                // re-render rate to ~max(60, gyro rate) fps and usually
+                // far less since drift is gradual.
+                if (roundedPx !== lastOffsetRef.current) {
+                    lastOffsetRef.current = roundedPx;
+                    setMarkerOffsetPx(roundedPx);
+                }
+                const nextBucket = bucketFor(Math.abs(perpIntegralRef.current), warnRad, badRad);
+                if (nextBucket !== lastBucketRef.current) {
+                    lastBucketRef.current = nextBucket;
+                    setBucket(nextBucket);
+                }
+            },
+            error: (err) => {
+                // eslint-disable-next-line no-console
+                console.warn('[IncrementalPanGuide] gyroscope error', err);
+            },
+        });
+        return () => {
+            subscription?.unsubscribe();
+            subscription = null;
+        };
+    }, [active, axis, pixelsPerRad, maxTravelPx, warnRad, badRad]);
+    if (!active)
+        return null;
+    const markerColor = colorFor(bucket);
+    if (axis === 'horizontal') {
+        // Portrait: guide line spans horizontally across the centre,
+        // marker drifts vertically.  Marker is a small circle outlined
+        // in the bucket colour.
+        return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [styles.rootCentered, style] },
+            react_1.default.createElement(react_native_1.View, { style: styles.lineHorizontal }),
+            react_1.default.createElement(react_native_1.View, { style: [
+                    styles.marker,
+                    { borderColor: markerColor },
+                    // Vertical translation from the line.  Negative px =
+                    // device tilted UP from start → marker UP.
+                    { transform: [{ translateY: markerOffsetPx }] },
+                ] })));
+    }
+    // Landscape: guide line is VERTICAL down the centre, marker
+    // drifts horizontally.
+    return (react_1.default.createElement(react_native_1.View, { pointerEvents: "none", style: [styles.rootCentered, style] },
+        react_1.default.createElement(react_native_1.View, { style: styles.lineVertical }),
+        react_1.default.createElement(react_native_1.View, { style: [
+                styles.marker,
+                { borderColor: markerColor },
+                { transform: [{ translateX: markerOffsetPx }] },
+            ] })));
+}
+// Layout: position the entire guide as an absolute, full-screen
+// overlay so the line spans the camera viewport edge-to-edge.
+// The marker is rendered absolutely at the centre and translated
+// by markerOffsetPx (signed) along the perpendicular axis.
+const styles = react_native_1.StyleSheet.create({
+    rootCentered: {
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+    // Horizontal line across the screen, centred vertically.  Thin
+    // (1.5 px), white-translucent, dashed via repeating segments
+    // would be nicer but a flat translucent rectangle is sufficient
+    // for V12.11 Step 2 — leaves room for a polish pass later.
+    lineHorizontal: {
+        position: 'absolute',
+        left: 0,
+        right: 0,
+        height: 1.5,
+        backgroundColor: 'rgba(255, 255, 255, 0.55)',
+    },
+    // Vertical line down the screen, centred horizontally.
+    lineVertical: {
+        position: 'absolute',
+        top: 0,
+        bottom: 0,
+        width: 1.5,
+        backgroundColor: 'rgba(255, 255, 255, 0.55)',
+    },
+    // Marker — a 22 px ringed circle.  Filled with a translucent
+    // dark so the bucket-coloured ring reads cleanly against any
+    // camera-feed background.
+    marker: {
+        width: 22,
+        height: 22,
+        borderRadius: 11,
+        borderWidth: 3,
+        backgroundColor: 'rgba(0, 0, 0, 0.35)',
+    },
+});
+//# sourceMappingURL=IncrementalPanGuide.js.map

package/dist/camera/PanoramaBandOverlay.d.ts

@@ -0,0 +1,107 @@
+/**
+ * PanoramaBandOverlay — V16 Phase 2 (merged band + strip).
+ *
+ * SINGLE source of truth for the live "progress strip" that sits on
+ * top of the camera preview during a panorama hold.  Replaces what
+ * was previously TWO components rendered side-by-side:
+ *
+ *   1. live per-keyframe thumbnail strip — fed by accepted-frame URIs
+ *                                  (batch-keyframe engine) OR by
+ *                                  periodic vision-camera snapshots.
+ *   2. <PanoramaBandOverlay />   — a single cumulative-panorama
+ *                                  thumbnail with a "fill ratio"
+ *                                  bar growing with the pan.
+ *
+ * The split made the UI visually noisy AND made it differ between
+ * platforms when one side emitted keyframe events and the other
+ * didn't.  V16 Phase 2 collapses them into ONE component that:
+ *
+ *   • Renders a horizontally-scrolling list of per-keyframe
+ *     thumbnails when `frameUris` is non-empty (batch-keyframe
+ *     mode).  Each frame the KeyframeGate accepts shows up as a
+ *     mini-thumb.
+ *
+ *   • Falls back to a SINGLE cumulative-panorama thumbnail (the
+ *     V12.14.9 fill-ratio behaviour) when `frameUris` is empty —
+ *     i.e. the live-stitching engines that don't surface
+ *     per-keyframe paths.  This preserves the existing visual for
+ *     hybrid / firstwins / firstwins-rectilinear engines.
+ *
+ *   • Edge-pinned to the BOTTOM of the camera area in portrait, and
+ *     to the user's RIGHT in landscape (which corresponds to
+ *     JS-bottom under the app's portrait-lock).  Both anchors keep
+ *     the band out of the centre of the scene the operator is
+ *     framing.
+ *
+ *   • Trailing arrow points along the pan axis (→ in portrait, ← in
+ *     landscape-left's user perception).  Arrow always sits at the
+ *     pan-END side, so the LATEST keyframe abuts the arrow.
+ *
+ *   • Auto-scrolls a `<ScrollView>` so the latest keyframe stays
+ *     visible regardless of how many frames have been accumulated.
+ *
+ * Empty-state intentional non-design:
+ *   The KeyframeGate force-accepts the FIRST frame of every capture
+ *   (see C++ `AcceptFirstAnchoredOnPlane` / `AcceptFirstNoPlane` in
+ *   keyframe_gate.cpp).  By the time the operator's perceived "the
+ *   band appeared", we already have at least one thumb/snapshot in
+ *   flight.  We therefore don't render any "no frames yet"
+ *   placeholder — the empty period is sub-perceptual.
+ *
+ * Why this component is in react-native-image-stitcher (not host):
+ *   It's the same JSX shipped to iOS and Android.  Differences in
+ *   what shows up come only from native-emitted data
+ *   (`state.batchKeyframeThumbnailPath` / `state.panoramaPath`),
+ *   not from per-platform component code.  That's exactly the parity
+ *   property the user wants: "the UI should not differ between iOS
+ *   and Android — it's the same UI reused".
+ */
+import React from 'react';
+import type { IncrementalState } from '../stitching/incremental';
+/**
+ * 2026-05-18 (Issue #3 fix) — 4-way capture orientation classifier.
+ * Replaces the 2-way `state.isLandscape` boolean which couldn't
+ * distinguish landscape-LEFT (home button on user's right) from
+ * landscape-RIGHT (home button on user's left).  Required because
+ * the JS-coordinate mapping to user-perceived directions inverts
+ * between the two landscape rotations — `flexDirection: 'row'`
+ * gives oldest-at-user-top in landscape-LEFT but oldest-at-user-
+ * bottom in landscape-RIGHT, so we need to branch the layout.
+ */
+export type BandCaptureOrientation = 'portrait' | 'portrait-upside-down' | 'landscape-left' | 'landscape-right';
+export interface PanoramaBandOverlayProps {
+    /**
+     * Latest engine state.  Pass `useIncrementalStitcher().state`.
+     * Used for single-thumb fallback URI and fill-ratio when no
+     * per-keyframe URIs are provided.  `state.isLandscape` is now
+     * superseded by `captureOrientation` below for layout selection.
+     */
+    state: IncrementalState | null;
+    /**
+     * Optional list of per-keyframe thumbnail URIs accumulated by the
+     * host as the native batch-keyframe engine emits
+     * `batchKeyframeThumbnailPath` events.  When non-empty, the band
+     * renders these as a scrolling mini-thumb strip.  When empty or
+     * undefined, the band falls back to the single cumulative-panorama
+     * thumbnail (legacy live-engine visual).
+     *
+     * Caller should cap the list length itself if needed (e.g. the
+     * AuditCaptureScreen already trims at 24 entries).  This component
+     * applies an internal hard cap as a safety net so a runaway
+     * emission doesn't blow up the scroll view.
+     */
+    frameUris?: string[];
+    /**
+     * 2026-05-18 (Issue #3) — capture orientation passed from the host.
+     * Drives a 4-way layout switch so the band reads correctly in
+     * either landscape rotation (the 2-way `state.isLandscape` boolean
+     * collapses landscape-LEFT and landscape-RIGHT to the same render
+     * path, which inverts the user's perceived "oldest-top, grows
+     * down" intent in one of them).  Pass
+     * `panoramaSettings.captureOrientation` from the host.  Defaults
+     * to `'portrait'` when omitted (back-compat).
+     */
+    captureOrientation?: BandCaptureOrientation;
+}
+export declare function PanoramaBandOverlay({ state, frameUris, captureOrientation, }: PanoramaBandOverlayProps): React.JSX.Element | null;
+//# sourceMappingURL=PanoramaBandOverlay.d.ts.map