react-native-image-stitcher 0.14.2 → 0.15.1

package/src/camera/CameraView.tsx

@@ -19,10 +19,23 @@
  * UI can still use it as their building block.
  */
 
-import React, { forwardRef, useImperativeHandle, useRef } from 'react';
-import { StyleSheet, Text, View, type ViewStyle } from 'react-native';
+import React, {
+  forwardRef,
+  useCallback,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react';
+import {
+  StyleSheet,
+  Text,
+  View,
+  type LayoutChangeEvent,
+  type ViewStyle,
+} from 'react-native';
 import {
   Camera,
+  useCameraFormat,
   type CameraDevice,
   type CameraProps,
 } from 'react-native-vision-camera';
@@ -140,6 +153,39 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
   const innerRef = useRef<Camera>(null);
   useImperativeHandle(ref, () => innerRef.current as Camera);
 
+  // ── WYSIWYG letterboxing ────────────────────────────────────────
+  //
+  // Pin BOTH the photo and the preview (video) stream to a 4:3 aspect
+  // ratio so the viewport shows exactly what gets captured.  Without a
+  // pinned format, vision-camera picks the device default for each —
+  // commonly a 4:3 photo but a 16:9 preview — so the preview and the
+  // saved frame frame different scenes.  4:3 is the native still
+  // aspect on essentially every phone camera (incl. ultra-wide), so a
+  // matching format is virtually always available; `useCameraFormat`
+  // returns the closest match and never throws.
+  const format = useCameraFormat(device ?? undefined, [
+    { photoAspectRatio: 4 / 3 },
+    { videoAspectRatio: 4 / 3 },
+  ]);
+
+  // Measured size of our container, so we can size the <Camera> view to
+  // the largest box of the capture's aspect ratio that fits inside it
+  // (the rest becomes the black letterbox).  We deliberately size the
+  // VIEW rather than relying on vision-camera's `resizeMode` alone:
+  // resizeMode maps to PreviewView.ScaleType on Android, which several
+  // devices ignore under the default SurfaceView compositor — so the
+  // preview kept filling the screen.  When the view's own aspect ratio
+  // equals the feed's, there is nothing left to crop on any platform.
+  const [size, setSize] = useState<{ w: number; h: number } | null>(null);
+  const onRootLayout = useCallback((e: LayoutChangeEvent) => {
+    const { width, height } = e.nativeEvent.layout;
+    setSize((prev) =>
+      prev && prev.w === width && prev.h === height
+        ? prev
+        : { w: width, h: height },
+    );
+  }, []);
+
   if (!device) {
     return (
       <View style={[styles.placeholder, style]} accessibilityLabel="Camera initialising">
@@ -148,15 +194,49 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
     );
   }
 
+  // Capture aspect ratio (W÷H) in the sensor's native landscape
+  // orientation (so > 1).  Falls back to 4:3 until the format resolves.
+  const sensorAspect =
+    format && format.photoWidth > 0 && format.photoHeight > 0
+      ? format.photoWidth / format.photoHeight
+      : 4 / 3;
+
+  // With outputOrientation="device", a portrait device displays the
+  // scene rotated, so the on-screen content aspect is the inverse of
+  // the landscape sensor aspect.  Detect portrait from the measured
+  // container — robust across devices, split-screen and rotation.
+  const isPortrait = size != null ? size.h >= size.w : true;
+  const contentAspect = isPortrait ? 1 / sensorAspect : sensorAspect;
+
+  // Largest box of `contentAspect` that fits the container, centred by
+  // styles.root.  The remaining area is the black letterbox.  Before the
+  // first onLayout we fill the container so the camera session mounts
+  // immediately; the exact box snaps in ~1 frame later.
+  let cameraStyle: ViewStyle;
+  if (size == null || size.w === 0 || size.h === 0) {
+    cameraStyle = StyleSheet.absoluteFillObject;
+  } else {
+    const heightIfFullWidth = size.w / contentAspect;
+    cameraStyle =
+      heightIfFullWidth <= size.h
+        ? { width: size.w, height: heightIfFullWidth }
+        : { width: size.h * contentAspect, height: size.h };
+  }
+
   return (
-    <View style={[styles.root, style]}>
+    <View style={[styles.root, style]} onLayout={onRootLayout}>
       <Camera
         ref={innerRef}
-        style={StyleSheet.absoluteFill}
+        // Sized to the letterboxed box (capture aspect ratio) so the
+        // preview never crops; styles.root centres it and paints the
+        // surrounding bars black.  See the cameraStyle computation above.
+        style={cameraStyle}
         device={device}
         isActive={isActive}
         photo
         video={video}
+        // Pin preview + photo to the same 4:3 format (WYSIWYG capture).
+        format={format}
         // v0.13.2 — multi-cam lens switch via zoom (undefined = default).
         {...(zoom != null ? { zoom } : {})}
         // Bake the device orientation into the captured pixels.
@@ -169,6 +249,25 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
         // how the user is holding the phone, so the saved JPEG is
         // "what you see is what was taken".
         outputOrientation="device"
+        // Show the full camera FOV — no cropping.  'contain' maps to
+        // AVLayerVideoGravity.resizeAspect on iOS and the equivalent
+        // on Android, letterboxing the preview to the sensor's exact
+        // aspect ratio.  Without this the default 'cover' crops
+        // ~19% off each horizontal edge in portrait mode (4:3 sensor
+        // in a 9:21 viewport), so the stitcher receives frames the
+        // user never saw.  Black bars fill the remainder; backgroundColor
+        // on styles.root ensures they are always black.
+        resizeMode="contain"
+        // Android: force TextureView rendering so that FIT_CENTER
+        // (the Android equivalent of resizeMode="contain") actually
+        // produces visible letterboxing.  The default SurfaceView mode
+        // composes at the hardware layer below the View hierarchy and
+        // on many devices ignores FIT_CENTER, filling the full surface
+        // instead.  TextureView is part of the regular View hierarchy
+        // so the matrix transform for FIT_CENTER works correctly —
+        // the bars outside the letterboxed area are transparent,
+        // revealing the parent's black backgroundColor.
+        androidPreviewViewType="texture-view"
         torch={flash === 'on' ? 'on' : 'off'}
         onError={handleVcError}
         {...cameraProps}
@@ -189,6 +288,16 @@ const styles = StyleSheet.create({
   root: {
     flex: 1,
     overflow: 'hidden',
+    // Centre the letterboxed <Camera> box so the black bars are
+    // symmetric on both sides (top/bottom in portrait, left/right in
+    // landscape).
+    alignItems: 'center',
+    justifyContent: 'center',
+    // Black bars when the camera's aspect ratio doesn't fill the
+    // container (e.g. 4:3 sensor in a 9:21 portrait viewport).  Without
+    // this the bars are transparent, revealing whatever is behind the
+    // component.
+    backgroundColor: '#000',
   },
   placeholder: {
     flex: 1,

package/src/camera/CaptureStitchStatsToast.tsx

@@ -23,28 +23,47 @@ import type { IncrementalFinalizeResult } from '../stitching/incremental';
 export interface CaptureStitchStatsToastProps {
   /** Toast message to show.  Pass null to hide. */
   message: string | null;
+  /**
+   * Optional bold title rendered above the message (e.g. an action ask
+   * like "Pan more slowly").  Omit for a plain single-line toast.
+   */
+  title?: string | null;
   /** Top inset for safe-area placement.  Toast pinned `topInset + 12`. */
   topInset?: number;
+  /**
+   * Vertical placement.  'top' (default) pins it `topInset + 12` from the
+   * top; 'center' vertically centers it — more prominent, and dodges the
+   * notch / Dynamic Island entirely.
+   */
+  placement?: 'top' | 'center';
 }
 
 export function CaptureStitchStatsToast({
   message,
+  title = null,
   topInset = 0,
+  placement = 'top',
 }: CaptureStitchStatsToastProps): React.JSX.Element | null {
   if (message === null) return null;
   return (
     <View
       pointerEvents="none"
-      style={[
-        styles.wrap,
-        { top: topInset + 12 },
-      ]}
+      style={
+        placement === 'center'
+          ? styles.wrapCenter
+          : [styles.wrap, { top: topInset + 12 }]
+      }
     >
       <View
         style={styles.capsule}
         accessibilityRole="alert"
         accessibilityLiveRegion="polite"
       >
+        {title ? (
+          <Text style={styles.title} numberOfLines={2}>
+            {title}
+          </Text>
+        ) : null}
         <Text style={styles.text} numberOfLines={3}>
           {message}
         </Text>
@@ -61,6 +80,16 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     zIndex: 110,
   },
+  wrapCenter: {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    left: 24,
+    right: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+    zIndex: 110,
+  },
   capsule: {
     paddingHorizontal: 16,
     paddingVertical: 10,
@@ -68,6 +97,13 @@ const styles = StyleSheet.create({
     backgroundColor: 'rgba(15, 23, 42, 0.92)',
     maxWidth: '100%',
   },
+  title: {
+    color: '#ffffff',
+    fontSize: 14,
+    fontWeight: '700',
+    textAlign: 'center',
+    marginBottom: 3,
+  },
   text: {
     color: '#ffffff',
     fontSize: 13,
@@ -93,7 +129,9 @@ const styles = StyleSheet.create({
  */
 export interface UseStitchStatsToastReturn {
   message: string | null;
-  showFor: (msg: string, ms?: number) => void;
+  /** Optional bold title shown above `message` (pass to the toast). */
+  title: string | null;
+  showFor: (msg: string, ms?: number, title?: string) => void;
   showResult: (result: IncrementalFinalizeResult, ms?: number) => void;
 }
 
@@ -101,16 +139,22 @@ const DEFAULT_DISMISS_MS = 4500;
 
 export function useStitchStatsToast(): UseStitchStatsToastReturn {
   const [message, setMessage] = useState<string | null>(null);
+  const [title, setTitle] = useState<string | null>(null);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const showFor = useCallback((msg: string, ms = DEFAULT_DISMISS_MS) => {
-    if (timerRef.current) clearTimeout(timerRef.current);
-    setMessage(msg);
-    timerRef.current = setTimeout(() => {
-      setMessage(null);
-      timerRef.current = null;
-    }, ms);
-  }, []);
+  const showFor = useCallback(
+    (msg: string, ms = DEFAULT_DISMISS_MS, titleText?: string) => {
+      if (timerRef.current) clearTimeout(timerRef.current);
+      setTitle(titleText ?? null);
+      setMessage(msg);
+      timerRef.current = setTimeout(() => {
+        setMessage(null);
+        setTitle(null);
+        timerRef.current = null;
+      }, ms);
+    },
+    [],
+  );
 
   const showResult = useCallback(
     (result: IncrementalFinalizeResult, ms = DEFAULT_DISMISS_MS) => {
@@ -151,5 +195,5 @@ export function useStitchStatsToast(): UseStitchStatsToastReturn {
     if (timerRef.current) clearTimeout(timerRef.current);
   }, []);
 
-  return { message, showFor, showResult };
+  return { message, title, showFor, showResult };
 }

package/src/camera/PanoramaSettings.ts

@@ -203,6 +203,17 @@ export interface FrameSelectionSettings {
    */
   overlapThreshold: number;
 
+  /**
+   * Time-budget force-accept (BOTH strategies, AR + non-AR).  When > 0,
+   * the gate accepts a keyframe whenever this many milliseconds have
+   * elapsed since the last accepted keyframe — even if the novelty /
+   * overlap threshold wasn't met — so a slow or static pan never goes
+   * longer than this without a keyframe.  Counts toward `maxKeyframes`
+   * (the cap still finalises the capture).  `0` disables it.  Default
+   * `2000` (2 s).  Maps to the native gate's `setMaxKeyframeIntervalMs`.
+   */
+  maxKeyframeIntervalMs: number;
+
   /**
    * Sparse-optical-flow strategy tunables.  Consulted only when
    * `mode === 'flow-based'`; safe to omit otherwise.  Defaults
@@ -305,301 +316,17 @@ export const DEFAULT_PANORAMA_SETTINGS: PanoramaSettings = {
     warperType: 'plane',
     blenderType: 'multiband',
     seamFinderType: 'graphcut',
+    // v0.15 — inscribed-rect crop is OFF by default (bbox crop keeps all
+    // stitched content).  Opt in with `maxInscribedRectCrop={true}` (or toggle
+    // it on in settings) for a clean-cornered rectangle — but it can shrink the
+    // output a lot on lopsided / ultra-wide masks, which is why it's opt-in.
     enableMaxInscribedRectCrop: false,
   },
   frameSelection: {
     mode: 'flow-based',
     maxKeyframes: 6,
     overlapThreshold: 0.20,
+    maxKeyframeIntervalMs: 2000,
     flow: DEFAULT_FLOW_GATE_SETTINGS,
   },
 };
-
-
-// ═════════════════════════════════════════════════════════════════════
-// SlitscanSettings — Layer 2 hosts using the slit-scan engine.
-// ═════════════════════════════════════════════════════════════════════
-
-/**
- * Settings for slit-scan stitching engines (`slitscan-rotate`,
- * `slitscan-both`, `firstwins-rectilinear`).  Reached via
- * `incremental.start({ engine: '<variant>', config: { ... } })`,
- * NOT via <Camera> (which always uses batch-keyframe).  Each
- * sub-tree corresponds to a section of the native `RLISStitcherConfig`
- * the slit-scan engine reads at start.
- *
- * Field-by-field native consumer references are documented in
- * `OpenCVSlitScanStitcher.mm` / `OpenCVIncrementalStitcher.h`.
- */
-export interface SlitscanSettings extends CaptureBaseSettings {
-  /**
-   * Which slit-scan variant the engine runs.  All three share the
-   * same painting + registration + plane configuration; they differ
-   * in their internal motion model (rotation-only vs combined
-   * translation+rotation, and slit position).
-   *
-   *   • `'slitscan-rotate'`         — preferred name; rotation-only
-   *     motion model.
-   *   • `'slitscan-both'`           — combined translation + rotation
-   *     motion model.
-   *   • `'firstwins-rectilinear'`   — legacy alias of
-   *     `'slitscan-rotate'` (V13.0a naming).  Accepted natively
-   *     but new code should prefer the canonical name.
-   */
-  variant: 'slitscan-rotate' | 'slitscan-both' | 'firstwins-rectilinear';
-
-  /** Where the per-accept slit is taken from + how it's blended. */
-  painting: SlitscanPaintingSettings;
-
-  /** Frame-to-frame registration (NCC + RANSAC + triangulation). */
-  registration: SlitscanRegistrationSettings;
-
-  /** Plane projection (ARKit-detected, virtual, or disabled). */
-  plane: PlaneProjectionSettings;
-
-  /**
-   * Advanced motion-tuning knobs that the v0.3 modal never exposed.
-   * Both are read by the native side
-   * (`IncrementalStitcher.swift:1074, 1077`) and have sensible
-   * defaults; most consumers can leave this field undefined.
-   */
-  advanced?: SlitscanAdvancedSettings;
-}
-
-
-export interface SlitscanAdvancedSettings {
-  /**
-   * Fraction of the pan-axis sensor extent used to compute the
-   * per-frame slit width.  Range `[0.05, 0.90]`, default 0.70
-   * (engine internal).  Higher = wider slits = fewer accepts per
-   * pan.  Set this only if you know what the slit-scan motion
-   * model needs for your specific capture geometry.
-   * Native key: `kPanAxisFractionRect`.
-   */
-  panAxisFractionRect?: number;
-
-  /**
-   * Minimum pan-axis delta (in canvas pixels) between consecutive
-   * accepted strips.  Acts as a hard floor below which subsequent
-   * frames are rejected regardless of NCC scores.  Range
-   * `[0, 500]`, default 0 (no floor).  Native key:
-   * `kMinAcceptDeltaPx`.
-   */
-  minAcceptDeltaPx?: number;
-}
-
-
-export interface SlitscanPaintingSettings {
-  /**
-   * How new strips are blended into already-painted canvas pixels.
-   *
-   *   • `'FirstPaintedWins'` (default) — preserve the first frame's
-   *     content at any pixel; later strips don't overwrite.
-   *   • `'FeatherBlend'`               — alpha-blend new strips into
-   *     already-painted areas at slit boundaries.  Smooths visible
-   *     seams when many narrow slits stack.
-   */
-  paintMode: 'FirstPaintedWins' | 'FeatherBlend';
-
-  /**
-   * Where on the camera frame the per-accept slit is sampled from.
-   * For a typical landscape vertical pan tilting DOWN, the leading
-   * edge (new content) is at the BOTTOM of the camera frame; for
-   * upward tilt, it's at the TOP.  `'Center'` is the V13.x default.
-   */
-  sliverPosition: 'Center' | 'Bottom' | 'Top';
-
-  /**
-   * When `true`, the very first frame's FULL frame is painted onto
-   * the canvas (not just the configured slit clip).  Default
-   * `true` — gives the panorama a wider initial anchor that
-   * subsequent slits extend from.  Set false if you want strict
-   * slit-only behaviour even on the first frame.
-   */
-  firstFrameFullFrame: boolean;
-}
-
-
-export interface SlitscanRegistrationSettings {
-  /**
-   * 3D triangulation step.  Cross-references features across
-   * multiple frames to estimate scene depth.  Default `false` (off);
-   * adds latency, useful for parallax-heavy captures.
-   */
-  enableTriangulation: boolean;
-
-  /**
-   * Triangulation accumulator — when `enableTriangulation` is on,
-   * keeps a running pose graph across the whole capture.  Default
-   * `false` (off); needed for multi-shot fusion.
-   */
-  enableTriAccumulator: boolean;
-
-  /**
-   * RANSAC homography fit per pair.  Adds robustness to feature
-   * matching at the cost of a few ms per frame.  Default `false`.
-   */
-  enableRansacHomography: boolean;
-
-  /**
-   * 1D NCC strip alignment.  Present iff enabled.  Default
-   * undefined (disabled); engine uses pure feature matching.
-   */
-  ncc1d?: Ncc1dSettings;
-
-  /**
-   * 2D NCC strip alignment.  Present iff enabled.  More expensive
-   * than 1D NCC; needed for shelf-scan captures with vertical
-   * misalignment.  Default undefined (disabled).
-   */
-  ncc2d?: Ncc2dSettings;
-}
-
-
-export interface Ncc1dSettings {
-  /**
-   * Search radius in working-resolution pixels (along the pan axis).
-   * Clamped to `[5, 60]`.  Default 15 when the field is set.
-   */
-  searchRadius: number;
-}
-
-
-export interface Ncc2dSettings {
-  /**
-   * 2D search margin in pixels (rectangular region around the
-   * predicted strip position).  Clamped to `[4, 60]`.  Default 12.
-   */
-  searchMargin: number;
-
-  /**
-   * Minimum NCC score to accept a match.  Below this the engine
-   * falls back to the predicted (pose-only) position.  Clamped
-   * to `[0.30, 0.99]`.  Default 0.99 (only accept very strong
-   * matches; the canvas falls back to pose-only quickly).
-   */
-  confidenceThreshold: number;
-
-  /**
-   * EMA smoothing of the NCC-derived offset across consecutive
-   * strips.  Present iff enabled.  Default undefined.  Useful
-   * for jittery captures.
-   */
-  emaSmoothing?: { alpha: number };
-
-  /**
-   * Pan-axis-lock — when enabled, the NCC offset is constrained
-   * to the dominant pan axis (cross-axis movement bounded by
-   * `crossAxisLockPx`).  Useful when the operator's hand wobble
-   * introduces unwanted cross-axis motion.  Present iff enabled.
-   */
-  panAxisLock?: { crossAxisLockPx: number };
-}
-
-
-export interface PlaneProjectionSettings {
-  /**
-   * Where the plane the slit-scan projects onto comes from.
-   *
-   *   • `'Disabled'`       — no plane projection; engine runs
-   *                          its baseline slit-scan path.
-   *   • `'ARKitDetected'`  — use the first vertical plane that
-   *                          ARKit/ARCore finds AND whose normal
-   *                          aligns with the camera (filtered by
-   *                          `alignmentThreshold`).  Requires
-   *                          `captureSource === 'ar'`.
-   *   • `'Virtual'`        — synthesise a plane at a fixed depth
-   *                          (`virtualDepthMeters`) in front of the
-   *                          camera at first-frame pose.  No
-   *                          ARKit dependency.
-   */
-  source: 'Disabled' | 'ARKitDetected' | 'Virtual';
-
-  /**
-   * How frames are warped onto the plane.  Only consulted when
-   * `source !== 'Disabled'`.  Default `'Rectified'` for slit-scan.
-   */
-  projectionStyle?: 'Trapezoidal' | 'Rectified';
-
-  /**
-   * Depth in metres for `source === 'Virtual'`.  Range `[0.3, 5.0]`,
-   * default 1.5.  Set close to the actual shelf distance for the
-   * cleanest projection.
-   */
-  virtualDepthMeters?: number;
-
-  /**
-   * Minimum `|planeNormal · cameraForward|` for an ARKit-detected
-   * plane to be accepted (when `source === 'ARKitDetected'`).
-   * Range `[0, 1]`, default 0.6 (≈ 53° max off-axis).  Higher =
-   * stricter, only accept very-on-axis planes.
-   */
-  alignmentThreshold?: number;
-}
-
-
-export const DEFAULT_SLITSCAN_SETTINGS: SlitscanSettings = {
-  captureSource: 'ar',
-  debug: false,
-  variant: 'slitscan-rotate',
-  painting: {
-    paintMode: 'FirstPaintedWins',
-    sliverPosition: 'Bottom',
-    firstFrameFullFrame: true,
-  },
-  registration: {
-    enableTriangulation: false,
-    enableTriAccumulator: false,
-    enableRansacHomography: false,
-    // ncc1d / ncc2d omitted — both disabled by default.
-  },
-  plane: {
-    source: 'ARKitDetected',
-    projectionStyle: 'Rectified',
-    virtualDepthMeters: 1.5,
-    alignmentThreshold: 0.6,
-  },
-};
-
-
-// ═════════════════════════════════════════════════════════════════════
-// HybridSettings — RetaiLens-specific live engine.
-// ═════════════════════════════════════════════════════════════════════
-
-/**
- * Settings for the hybrid live-compositing engine
- * (`incremental.start({ engine: 'hybrid', ... })`).  Most consumers
- * won't touch this — the hybrid engine is RetaiLens-specific and
- * the public lib's batch-keyframe pipeline is a better fit for
- * general-purpose captures.  Exported here for completeness.
- *
- * Important: the hybrid engine has internal preset paths
- * (`OpenCVIncrementalStitcher.mm:139-180`) that hard-set
- * `enableTriangulation`, `enable2dNcc`, `enableRansacHomography`,
- * `planeSource = Disabled`, etc.  Code-reviewer flagged that
- * exposing those fields would be misleading — the engine clobbers
- * any overrides.  So this type is intentionally minimal: only
- * `projection` is reliably operator-tunable.  Hosts that need to
- * reach deeper-level hybrid knobs can pass a raw config dict to
- * `incremental.start()` directly (Layer 2 escape hatch).
- */
-export interface HybridSettings extends CaptureBaseSettings {
-  /**
-   * Internal projection during real-time compositing.  Independent
-   * from the panorama-stitcher's warperType (which doesn't apply
-   * to the hybrid engine — its output is the live canvas directly).
-   *
-   * Note: only effective in the rotation-only preset path (hybrid
-   * preset 1).  In the other hybrid presets the engine forces
-   * Planar internally regardless of this setting.  Native source:
-   * `OpenCVIncrementalStitcher.mm:146,161,180`.
-   */
-  projection: 'Cylindrical' | 'Planar';
-}
-
-
-export const DEFAULT_HYBRID_SETTINGS: HybridSettings = {
-  captureSource: 'ar',
-  debug: false,
-  projection: 'Planar',
-};