react-native-image-stitcher 0.15.2 → 0.16.0

package/dist/camera/PanoramaSettings.js

@@ -77,8 +77,21 @@ exports.DEFAULT_PANORAMA_SETTINGS = {
     captureSource: 'ar',
     debug: false,
     stitcher: {
-        stitchMode: 'auto',
-        warperType: 'plane',
+        // v0.16 — PANORAMA by default (was 'auto').  The auto-resolver's SCANS
+        // branch leans on double-integrated IMU translation, which is unreliable
+        // during rotation (gravity leakage inflates the translation estimate); in
+        // practice rotational pans are the common case and resolve to panorama
+        // anyway.  Defaulting to panorama is the robust choice — host apps that
+        // genuinely capture flat documents/walls can still opt into 'auto' or
+        // 'scans' via the ⚙️ panel or the `defaultStitchMode` / `stitcher` props.
+        stitchMode: 'panorama',
+        // v0.16 — SPHERICAL by default (bounds both axes; the proven-robust wide/
+        // vertical-pan projection).  This is now the single source of truth — the
+        // native side no longer hardcodes a warper, so the ⚙️ panel + the host's
+        // `defaultWarper` prop actually take effect.  Note: choosing `plane` here
+        // re-arms the dynamic plane→spherical fallback/divergence switch in the
+        // manual pipeline (it only fires when warperType != spherical).
+        warperType: 'spherical',
         blenderType: 'multiband',
         seamFinderType: 'graphcut',
         // v0.15 — inscribed-rect crop is OFF by default (bbox crop keeps all
@@ -89,9 +102,17 @@ exports.DEFAULT_PANORAMA_SETTINGS = {
     },
     frameSelection: {
         mode: 'flow-based',
-        maxKeyframes: 6,
-        overlapThreshold: 0.20,
-        maxKeyframeIntervalMs: 2000,
+        // v0.16 — denser keyframes by default: a 15% novelty gate, up to 8 frames,
+        // plus a 1.5 s time-budget force-accept (so a slow/static pan still lands a
+        // keyframe every 1.5 s even when novelty is low).  With 8 frames this bounds
+        // a static/slow capture to ~8×1.5 ≈ 12 s before the keyframe-count
+        // auto-finalize.  More overlap between consecutive keyframes ⇒ stronger
+        // feature matching ⇒ more robust registration.  Memory-checked: 8 frames fit
+        // the BATCH held-set cap on both platforms.  Overlap selectable in the
+        // settings panel {10,15,20,30}% (native clamp floor 10%); cap clamps [3,10].
+        maxKeyframes: 8,
+        overlapThreshold: 0.15,
+        maxKeyframeIntervalMs: 1500,
         flow: exports.DEFAULT_FLOW_GATE_SETTINGS,
     },
 };

package/dist/camera/PanoramaSettingsModal.js

@@ -182,17 +182,17 @@ function PanoramaSettingsModal({ visible, settings, onChange, onClose, }) {
                         react_1.default.createElement(SectionHeader, { title: "Max keyframes per capture" }),
                         react_1.default.createElement(SegmentedControl, { options: ['3', '4', '5', '6', '8', '10'], value: String(settings.frameSelection.maxKeyframes), onChange: (v) => updateFrameSelection({
                                 maxKeyframes: parseInt(v, 10),
-                            }), caption: "Hard cap on accepted keyframes; native clamps to [3, 10].  6 (default) matches Samsung Pano's behaviour and is the sweet spot for cv::Stitcher BA convergence." }),
+                            }), caption: "Hard cap on accepted keyframes; native clamps to [3, 10].  8 (default) is the sweet spot for cv::detail BA convergence while giving the 15%-overlap + 1 s time gate room to land frames." }),
                         react_1.default.createElement(SectionHeader, { title: "Overlap threshold (new content per keyframe)" }),
-                        react_1.default.createElement(SegmentedControl, { options: ['20%', '30%', '40%', '50%', '60%'], value: `${Math.round(settings.frameSelection.overlapThreshold * 100)}%`, onChange: (v) => updateFrameSelection({
+                        react_1.default.createElement(SegmentedControl, { options: ['10%', '15%', '20%', '30%'], value: `${Math.round(settings.frameSelection.overlapThreshold * 100)}%`, onChange: (v) => updateFrameSelection({
                                 overlapThreshold: parseInt(v, 10) / 100,
-                            }), caption: "Required NEW-content fraction.  20% (default): generous, ~5\u20136 keyframes for a 90\u00B0 pan.  Native clamps to [10%, 80%]." }),
+                            }), caption: "Required NEW-content fraction (lower = denser keyframes, more overlap).  15% (default): ~7\u20139 keyframes for a 90\u00B0 pan.  10% is the native clamp floor." }),
                         react_1.default.createElement(SectionHeader, { title: "Keyframe interval (time-budget force-accept)" }),
                         react_1.default.createElement(SegmentedControl, { options: ['off', '1s', '2s', '3s', '5s'], value: settings.frameSelection.maxKeyframeIntervalMs === 0
                                 ? 'off'
                                 : `${settings.frameSelection.maxKeyframeIntervalMs / 1000}s`, onChange: (v) => updateFrameSelection({
                                 maxKeyframeIntervalMs: v === 'off' ? 0 : parseInt(v, 10) * 1000,
-                            }), caption: "Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  2s (default).  Applies to AR + non-AR." }),
+                            }), caption: "Force-accept a keyframe at least this often even if novelty is low, so slow / static pans don't leave gaps.  Counts toward the keyframe cap.  off = disabled.  1s (default).  Applies to AR + non-AR." }),
                         showFlowTunables && (react_1.default.createElement(react_native_1.View, { style: styles.nested },
                             react_1.default.createElement(react_native_1.Text, { style: styles.nestedLabel }, "Flow tuning"),
                             react_1.default.createElement(SectionHeader, { title: "Max corners (Shi-Tomasi)" }),

package/dist/camera/RectCropPreview.d.ts

@@ -0,0 +1,161 @@
+/**
+ * RectCropPreview — item-7 of the first-time-user guidance flow: the
+ * post-capture crop editor.
+ *
+ * Shows the full stitched result image (contain-fit, letterboxed) with a
+ * 4-corner quad overlay.  Each corner is INDEPENDENTLY draggable in
+ * on-screen coords via RN-core `PanResponder` (deliberately NO
+ * react-native-gesture-handler dependency — this library ships zero extra
+ * native deps for guidance).  Corner positions are mapped to image-pixel
+ * space through the pure `cropGeometry` letterbox transform.
+ *
+ * ## What it surfaces (and what it does NOT do)
+ *
+ * This component is presentation + gesture only.  On confirm it computes
+ * the 4 image-pixel corners and hands them to `onConfirm` — it does NOT
+ * call any native crop.  The PARENT decides between the cheap axis-aligned
+ * `cropToRect` (when the quad is ~rectangular) and the perspective
+ * `cropToQuad`, using the `perspective` flag in the result:
+ *
+ *   onConfirm({ quad, perspective: perspectiveCorrect && !isAxisAligned })
+ *
+ * Promoted + extended from `example/InscribedRectDebug.tsx`, which already
+ * did the image-px ↔ on-screen contain-fit mapping, a rect overlay, and
+ * the in-place native crop.  This version replaces the single computed
+ * inscribed rect with a user-draggable free quad and the perspective
+ * decision; the letterbox math now lives in the shared `cropGeometry`
+ * module.  Styling is carried over from InscribedRectDebug.
+ *
+ * ## Seeding
+ *
+ * The initial quad comes from `initialRect` (image-pixel coords) when the
+ * host passes one — `<Camera>` passes the panorama's MAX-INSCRIBED rectangle
+ * (the tightest clean rectangle with no black corners; item 2) so the editor
+ * opens on a sensible crop the user drags to taste.  With no `initialRect`
+ * (native inscribed-rect unavailable) it falls back to an 8 %-inset
+ * rectangle.  "Reset" returns to whichever seed was used.
+ */
+import React from 'react';
+import { type GuidanceCopy } from './cameraGuidanceCopy';
+import { type Quad } from './cropGeometry';
+/** Image-pixel rectangle, used for the optional `initialRect` seed. */
+export interface ImageRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** What the host receives when the user taps Crop. */
+export interface RectCropResult {
+    /**
+     * The 4 chosen corners in IMAGE-PIXEL space, canonically ordered
+     * [TL, TR, BR, BL].  The host feeds these to the native crop.
+     */
+    quad: Quad;
+    /**
+     * `true` → the host should perspective-rectify (`cropToQuad`): the user
+     * picked a non-rectangular quad and `perspectiveCorrect` is enabled.
+     * `false` → the host can use the cheap axis-aligned `cropToRect` (the
+     * quad is ~rectangular, or perspective correction is disabled).
+     */
+    perspective: boolean;
+}
+export interface RectCropPreviewProps {
+    /** file:// URI of the full result image to crop. */
+    imageUri: string;
+    /** Intrinsic pixel width of `imageUri`. */
+    imageWidth: number;
+    /** Intrinsic pixel height of `imageUri`. */
+    imageHeight: number;
+    /**
+     * DEBUG A/B harness — file:// URI of the SAME capture stitched by the
+     * OPPOSITE pipeline (manual cv::detail + plane).  When set, a toggle appears
+     * that flips the displayed panorama between the primary (high-level +
+     * spherical) and this one, for on-device comparison on a single capture.
+     * Its dimensions are read at runtime via `Image.getSize`.  When the manual
+     * output is showing, the crop quad is hidden and the accept button emits
+     * THIS uri (so you can pick the better pipeline per capture).
+     */
+    altImageUri?: string;
+    /**
+     * 2026-06-15 — ON-DEMAND alt (high-level) stitch.  The PRIMARY image is the
+     * MANUAL pipeline (the default output); this callback re-stitches the SAME
+     * captured keyframes via cv::Stitcher and resolves with a file:// uri (or
+     * null on failure).  It runs only the FIRST time the user taps the
+     * "High-level" tab — nothing is computed unless asked for.  When provided (or
+     * `altImageUri` is), the A/B toggle appears.
+     *
+     * Resolves with the high-level output's file:// `uri` AND its OWN
+     * DEV-overlay `debugInfo` recipe (so the params pill can switch to the
+     * high-level recipe while that tab is viewed), or `null` on failure.
+     */
+    onRequestAlt?: () => Promise<{
+        uri: string;
+        debugInfo: string;
+    } | null>;
+    /** Show / hide the editor. */
+    visible: boolean;
+    /**
+     * Tapped on "Crop".  Receives the ordered image-pixel quad + the
+     * perspective decision; the host performs the actual native crop.
+     */
+    onConfirm: (result: RectCropResult) => void;
+    /**
+     * Tapped on "Use original" (or hardware back / dismiss) — emit the stitch
+     * un-cropped.  Also called when the user collapses the quad to something
+     * un-warpable, so a degenerate quad never reaches the native crop.
+     */
+    onUseOriginal: (uri?: string) => void;
+    /**
+     * Tapped on "Retake" — discard this capture entirely and return to the
+     * camera.  No result is emitted (the host clears the editor + lets the
+     * user capture again).
+     */
+    onRetake: () => void;
+    /**
+     * Optional non-fatal warning messages (e.g. "<70 % of frames used") shown
+     * as a banner across the top of the editor so the user sees them before
+     * accepting a crop.  Empty / undefined → no banner.
+     */
+    warnings?: string[];
+    /**
+     * Crop mode vs preview-only mode.  `true` (default) shows the draggable
+     * quad + corner handles + the [Retake][Use original][Crop] bar — the full
+     * crop editor.  `false` hides the quad and all crop affordances, showing
+     * just the stitched image with a [Retake][Confirm] bar — a plain preview
+     * (`<Camera showPreview>` without `rectCrop`).  Confirm emits the image
+     * un-cropped (same as "Use original").
+     */
+    showCropControls?: boolean;
+    /**
+     * Optional image-pixel seed rect for the draggable quad.  Defaults to
+     * an 8 %-inset rectangle of the full image.  Ignored in preview-only mode.
+     */
+    initialRect?: ImageRect;
+    /** Copy overrides (cropConfirm / cropReset). Falls back to defaults. */
+    copy?: Partial<GuidanceCopy>;
+    /**
+     * Safe-area insets (px).  The editor is a full-screen Modal, so the host
+     * passes `insets.top`/`insets.bottom` to keep the top toolbar (A/B toggle,
+     * warnings) clear of the notch/Dynamic Island and the bottom button bar
+     * clear of the home indicator.  Default 0.
+     */
+    topInset?: number;
+    bottomInset?: number;
+    /**
+     * 2026-06-14 (DEV overlay) — optional multi-line debug text describing how
+     * this output was stitched (pipeline / warper / route / seam / blend / score
+     * / frames / size).  When non-empty, rendered as a small monospace pill in
+     * the top-right corner.  The host gates this on `__DEV__`; this component
+     * just renders whatever non-empty string it's given.
+     */
+    debugInfo?: string;
+    /**
+     * 2026-06-15 — show the live memory-footprint pill (polled native RSS,
+     * green/amber/red) on the preview too, so the operator can watch the spike
+     * when the on-demand high-level re-stitch fires.  Host gates on settings.debug.
+     */
+    showMemoryPill?: boolean;
+}
+export declare function RectCropPreview(props: RectCropPreviewProps): React.JSX.Element;
+//# sourceMappingURL=RectCropPreview.d.ts.map