react-native-image-stitcher 0.14.2 → 0.15.1

package/src/camera/selectCaptureDevice.ts

@@ -47,7 +47,11 @@ export interface DeviceLike {
 export type CaptureDeviceMode =
   /** One multi-cam device spans wide + ultra-wide; switch lenses via zoom. */
   | 'multicam'
-  /** Separate standalone wide + ultra-wide devices; switch by remounting. */
+  /**
+   * Ultra-wide reached by remounting a dedicated ultra-wide device on 0.5x
+   * (the 1x primary may be a multi-cam *or* a standalone wide).  Used when
+   * no multi-cam device can reach the ultra-wide by zoom.
+   */
   | 'standalone-uw'
   /** No ultra-wide anywhere; wide-angle only (no 0.5× chip). */
   | 'wide-only';
@@ -71,6 +75,16 @@ export interface CaptureDeviceSelection<D extends DeviceLike = DeviceLike> {
 const hasLens = (d: DeviceLike, lens: LensType) =>
   d.physicalDevices.includes(lens);
 
+/**
+ * Max `minZoom` a multi-cam device may report and still count as able to
+ * reach the ultra-wide *by zoom*.  Real ultra-wides sit at ~0.5-0.65x, so a
+ * logical device whose zoom range genuinely extends to the ultra-wide reports
+ * `minZoom <= ~0.65`.  A device that only *lists* the ultra-wide (a separate
+ * physical camera on Android/Camera2, not a zoom target) reports
+ * `minZoom = 1.0`.  0.7 cleanly separates the two.
+ */
+const UW_ZOOM_REACH_MAX = 0.7;
+
 /**
  * Choose the back-camera device(s) for capture.
  *
@@ -107,7 +121,13 @@ export function selectCaptureDevice<D extends DeviceLike>(
     (d) =>
       d.isMultiCam &&
       hasLens(d, 'wide-angle-camera') &&
-      hasLens(d, 'ultra-wide-angle-camera'),
+      hasLens(d, 'ultra-wide-angle-camera') &&
+      // Must reach the ultra-wide by zoom.  On iOS the virtual device's zoom
+      // range spans it (minZoom ~0.5); on Android a logical device often
+      // *lists* the ultra-wide while its zoom range starts at 1.0 (separate
+      // physical camera, not a zoom target).  If it can't zoom there, it
+      // does NOT qualify -- we fall through to the device-swap path below.
+      d.minZoom <= UW_ZOOM_REACH_MAX,
   );
   if (multicamCandidates.length > 0) {
     const device = multicamCandidates.reduce((best, d) => {
@@ -135,9 +155,14 @@ export function selectCaptureDevice<D extends DeviceLike>(
   //
   // Prefer a torch-bearing wide-angle device as the `1×`/primary mount.
   const wideDevices = back.filter((d) => hasLens(d, 'wide-angle-camera'));
+  // A *true* standalone ultra-wide (its own id, NOT a multi-cam grouping).
+  // We deliberately do NOT fall back to a multi-cam device: mounting a
+  // logical multi-cam yields its WIDE member, not the ultra-wide, so a
+  // "swap" to it would silently show the wrong FOV.  If the only ultra-wide
+  // lives inside a non-zoomable multi-cam device, it is undeliverable and we
+  // hide the chooser (wide-only) below.
   const ultraWide =
     back.find((d) => !d.isMultiCam && hasLens(d, 'ultra-wide-angle-camera')) ??
-    back.find((d) => hasLens(d, 'ultra-wide-angle-camera')) ??
     null;
 
   if (wideDevices.length > 0 && ultraWide != null) {

package/src/camera/useCapture.ts

@@ -25,7 +25,7 @@
  * still use the SDK's quality + stitching modules.
  */
 
-import { useCallback, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
   Camera,
   useCameraDevice,
@@ -309,6 +309,49 @@ export function useCapture(options: UseCaptureOptions = {}): UseCaptureReturn {
     activeZoom = undefined;
   }
 
+  // v0.15 diagnostic (dev-only) — for the "0.5× pill shows but tapping
+  // doesn't switch the camera" report on Android (Samsung).  Logs the
+  // resolved capture mode + the mounted device's zoom range so logcat
+  // reveals whether `minZoom` actually reaches the ultra-wide.  On
+  // Camera2 the logical multi-camera's zoom range usually starts at 1.0
+  // (the ultra-wide is a separate physical id, not a zoom target), so a
+  // zoom-based 0.5× switch is a silent no-op.
+  useEffect(() => {
+    if (!__DEV__) return;
+    const summarise = (d: DeviceLike | null) =>
+      d
+        ? {
+            id: d.id,
+            physical: d.physicalDevices,
+            isMultiCam: d.isMultiCam,
+            minZoom: d.minZoom,
+            neutralZoom: d.neutralZoom,
+            maxZoom: d.maxZoom,
+            hasTorch: d.hasTorch,
+          }
+        : null;
+    const back = (allDevices as unknown as DeviceLike[]).filter(
+      (d) => d.position === 'back',
+    );
+    // eslint-disable-next-line no-console
+    console.log(
+      '[rnimagestitcher] lens-select ' +
+        JSON.stringify({
+          lens: lens ?? null,
+          mode: selection.mode,
+          has0_5x: selection.has0_5x,
+          activeZoom: activeZoom ?? null,
+          selected: summarise(selection.device),
+          ultraWide: summarise(selection.ultraWideDevice),
+          // Full back-camera enumeration — reveals whether a multicam
+          // device merely *lists* the ultra-wide while its zoom range
+          // can't reach it (minZoom ~1.0), and whether a STANDALONE
+          // ultra-wide device exists for the standalone-uw fallback.
+          allBack: back.map(summarise),
+        }),
+    );
+  }, [allDevices, selection, lens, activeZoom]);
+
   // Enumerate ALL physical lens types available on the chosen
   // position so the host can decide whether to render a switcher.
   // Vision-camera's `useCameraDevices()` returns CameraDevice[]; each

package/src/index.ts

@@ -39,6 +39,12 @@ export type {
   FramesDroppedInfo,
 } from './camera/Camera';
 
+// Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
+// their onError handler to surface actionable guidance ("pan more slowly",
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.
+export { userFacingStitchError } from './camera/cameraErrorMessages';
+export type { UserFacingStitchError } from './camera/cameraErrorMessages';
+
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
 // ─────────────────────────────────────────────────────────────────────
@@ -128,8 +134,6 @@ export type { PanoramaSettingsModalProps } from './camera/PanoramaSettingsModal'
 export {
   DEFAULT_PANORAMA_SETTINGS,
   DEFAULT_FLOW_GATE_SETTINGS,
-  DEFAULT_SLITSCAN_SETTINGS,
-  DEFAULT_HYBRID_SETTINGS,
 } from './camera/PanoramaSettings';
 export type {
   CaptureBaseSettings,
@@ -137,14 +141,6 @@ export type {
   BatchStitcherSettings,
   FrameSelectionSettings,
   FlowGateSettings,
-  SlitscanSettings,
-  SlitscanPaintingSettings,
-  SlitscanRegistrationSettings,
-  SlitscanAdvancedSettings,
-  Ncc1dSettings,
-  Ncc2dSettings,
-  PlaneProjectionSettings,
-  HybridSettings,
 } from './camera/PanoramaSettings';
 
 // Settings → native config adapters.  Layer 2 hosts building their
@@ -153,8 +149,6 @@ export type {
 // the single source of truth for the JS↔native wire format.
 export {
   panoramaSettingsToNativeConfig,
-  slitscanSettingsToNativeConfig,
-  hybridSettingsToNativeConfig,
 } from './camera/PanoramaSettingsBridge';
 export type { NativeConfigDict } from './camera/PanoramaSettingsBridge';
 export { ViewportCropOverlay } from './camera/ViewportCropOverlay';
@@ -206,34 +200,11 @@ export type {
   StitcherFrameProcessor,
   ARAnchor,
 } from './stitching/StitcherFrame';
-// v0.8.0 Phase 4a — public host-worklet hook.  Hosts that want a
-// per-frame callback (OCR overlay, packet detection, ML inference)
-// use this to attach a `'worklet'`-prefixed function that fires
-// on the camera producer thread.  Non-AR mode is fully wired
-// today via vision-camera passthrough; AR-mode dispatch is
-// API-stable but registration-only until Phase 4b lands the
-// cross-runtime handoff (the AR runtime iterating the registry).
-// See the hook's docstring + StitcherFrame.ts for the contract.
-export { useFrameProcessor } from './stitching/useFrameProcessor';
-// v0.9.0 Layer 2 — `useThrottledFrameProcessor`.  Throttle gate over
-// `useFrameProcessor` for sub-frame-rate worklet-native processing
-// (native OCR via Vision.framework / ML Kit, TFLite ML detection,
-// LiDAR depth).  The worklet runtime has direct access to
-// `frame.toArrayBuffer()` / `frame.arDepth`; bridge small payloads
-// (bboxes, depth-derived metrics) to JS via `runOnJS`.  For JS-thread
-// JPEG consumers (file-path OCR libs, cloud upload, thumbnail UI),
-// prefer `useFrameStream` (Layer 3, ships in the same release).
-export { useThrottledFrameProcessor } from './stitching/useThrottledFrameProcessor';
-export type { ThrottledFrameProcessorOptions } from './types';
-// v0.9.0 Layer 3 — `useFrameStream`.  JS-thread sampled-frame
-// stream over Layer 1 (`save_frame_as_jpeg` vc plugin) + Layer 2
-// (`useThrottledFrameProcessor`).  Use for JS-thread consumers:
-// file-path OCR libs (RN modules), cloud upload, thumbnail UI.
-// For worklet-native processing (Vision/ML Kit as vc plugins,
-// TFLite ML, LiDAR depth), prefer `useThrottledFrameProcessor`
-// (Layer 2) — lower latency, no JPEG roundtrip.
-export { useFrameStream } from './stitching/useFrameStream';
-export type { FrameStreamOptions, SampledFrame } from './types';
+// NOTE: the host-worklet / frame-stream hooks `useFrameProcessor`,
+// `useThrottledFrameProcessor` and `useFrameStream` (v0.8–v0.9) were
+// archived in the batch-keyframe cleanup — they drove the third-party
+// `__stitcherProxy` observer API, not batch-keyframe capture. Source is
+// preserved under archive/src/stitching/ to build on later.
 // vision-camera Frame Processor driver for non-AR captures.  As
 // of v0.6 the only non-AR driver exported (the legacy
 // `useIncrementalJSDriver` was removed; was deprecated in v0.5).

package/src/stitching/incremental.ts

@@ -422,9 +422,9 @@ export interface IncrementalStartOptions {
    * 'slitscan' fall back to 'slitscan-both' with a deprecation warning
    * in the native log.
    */
-  engine?: 'hybrid' | 'slitscan-rotate' | 'slitscan-both' | 'batch-keyframe' |
-           // Deprecated — kept for type-compat during the V14 → V15 transition:
-           'firstwins' | 'firstwins-zoomed' | 'firstwins-rectilinear' | 'slitscan';
+  // Only 'batch-keyframe' remains; the live engines were archived in the
+  // batch-keyframe cleanup (see archive/).
+  engine?: 'batch-keyframe';
   /**
    * V15 — per-stage correction config overrides.  Mode-driven defaults
    * are applied first (see RLISStitcherConfig +configForMode:); fields
@@ -441,143 +441,6 @@ export interface IncrementalStartOptions {
  * fields optional (omit to accept the engine-mode default).
  */
 export interface StitcherConfig {
-  // Slit shaping (slit-scan engine only)
-  /** Fraction of pan-axis the rectilinear slit retains per frame.
-   *  Range 0.10 – 0.70, default 0.30 in V15 slit-scan modes. */
-  kPanAxisFractionRect: number;
-  /** Minimum pan-axis advance (px) before a frame is accepted.
-   *  0 = accept on every consumeFrame (Apple-dense slit-scan, V15
-   *  default).  50 = V13.0g default. */
-  kMinAcceptDeltaPx: number;
-
-  // Per-stage correction toggles
-  /** V13.0e+ ORB triangulation + median-Z parallax correction. */
-  enableTriangulation: boolean;
-  /** V13.0g per-accept incremental Δt accumulator on top of triangulation. */
-  enableTriAccumulator: boolean;
-  /** V15 1D NCC perpendicular-axis wobble correction (slitscan-rotate
-   *  default).  Independent of the other correction stages. */
-  enable1dNcc: boolean;
-  /** 1D NCC search radius in pixels (5 – 60). */
-  nccSearchRadius1d: number;
-  /** V13.0g 2D NCC fine-alignment after triangulation. */
-  enable2dNcc: boolean;
-  /** V14.0a RANSAC homography per slit + cv::warpPerspective.  When
-   *  enabled and successful, supersedes the rectangular paste path. */
-  enableRansacHomography: boolean;
-
-  // Paint mode (slit-scan engine only)
-  /** 'FirstPaintedWins' protects already-painted pixels (V13.0e+
-   *  default).  'FeatherBlend' alpha-blends new content into already-
-   *  painted overlap pixels (V13.0d-style; V15 slitscan-both default). */
-  paintMode: 'FirstPaintedWins' | 'FeatherBlend';
-
-  // Hybrid engine
-  /** 'Cylindrical' (V12.x – V14.0a behaviour) or 'Planar' (V15 default;
-   *  cv::detail::PlaneWarper).  Planar is well-behaved for pans <60°. */
-  hybridProjection: 'Cylindrical' | 'Planar';
-
-  /** V15.0c — where on the camera frame the per-accept sliver is taken.
-   *  'Center' (V13.x default), 'Bottom' (leading edge for top-to-bottom
-   *  pan), or 'Top' (leading edge for bottom-to-top pan). */
-  sliverPosition: 'Center' | 'Bottom' | 'Top';
-
-  /** V15.0c — when true, the FIRST accepted frame paints the entire
-   *  camera frame at canvas (0, 0); subsequent frames still use the
-   *  configured sliver clip.  Default false; set true when sliverPosition
-   *  is Bottom/Top so the canvas is anchored with full-frame content. */
-  firstFrameFullFrame: boolean;
-
-  /** **DEPRECATED in V15.0d** — use `planeSource` instead.
-   *
-   *  V15.0b boolean toggle for the plane-projected stitch path.
-   *  Kept for backward compat: when `planeSource` is left at its
-   *  default (Disabled), `useDetectedPlane = true` upgrades it to
-   *  ARKitDetected.  New callers should set `planeSource` directly. */
-  useDetectedPlane: boolean;
-
-  /** V15.0d — source of the plane used by the V15.0b plane-projected
-   *  stitch path.
-   *
-   *  - 'Disabled' (default): no plane projection; slit-scan path runs.
-   *  - 'ARKitDetected': use ARKit's first vertical plane that aligns
-   *    with the camera's view direction (filter threshold:
-   *    `arkitPlaneAlignmentThreshold`).  Falls back to slit-scan
-   *    silently when no aligned plane is found.
-   *  - 'Virtual': synthesize a plane at first frame: origin =
-   *    camera_pos + `virtualPlaneDepthMeters` × camera_forward;
-   *    normal = -camera_forward.  Always works; no ARKit dependency.
-   *
-   *  Field testing showed ARKit plane detection often picks the WRONG
-   *  surface (side wall, doorframe) — Virtual mode is the safer
-   *  default for arbitrary scenes.  ARKitDetected wins when ARKit
-   *  finds the correct fixture face. */
-  planeSource: 'Disabled' | 'ARKitDetected' | 'Virtual';
-
-  /** V15.0d — depth (metres) at which the synthetic plane is placed
-   *  in front of the camera when `planeSource = Virtual`.  Set to
-   *  the user's typical scan distance.  Range 0.3 – 5.0 m.  Default
-   *  1.5 m. */
-  virtualPlaneDepthMeters: number;
-
-  /** V15.0d — minimum dot product between an ARKit-detected plane's
-   *  surface normal and the camera's facing direction for the plane
-   *  to be accepted (when `planeSource = ARKitDetected`).  1.0 =
-   *  plane perfectly facing camera; 0.0 = plane edge-on; negative
-   *  = facing away.  Range 0.0 – 1.0.  Default 0.6 (≈53° max angle
-   *  off-camera). */
-  arkitPlaneAlignmentThreshold: number;
-
-  /** V15.0g — how the plane-projection helper renders each frame onto
-   *  the canvas.  Affects ARKitDetected and Virtual modes; ignored
-   *  when planeSource = Disabled.
-   *
-   *  - 'Trapezoidal' (V15.0b legacy): geometrically-correct 3D
-   *    raycast.  Each camera pixel maps to its plane intersection.
-   *    Result is a trapezoid that grows distorted with tilt
-   *    (cooler-bottom-2.3×-wider-than-top problem).
-   *  - 'Rectified' (V15.0g default): camera frame pasted as a clean
-   *    rectangle around its plane-projected anchor.  Eliminates the
-   *    tilt-induced trapezoidal distortion at the cost of strict 3D-
-   *    correctness — the camera's per-pixel perspective stays inside
-   *    the rectangle but doesn't reconcile across tilts. */
-  planeProjectionStyle: 'Trapezoidal' | 'Rectified';
-
-  /** V15.0d — 2D NCC search half-window in pixels.  Was hardcoded
-   *  ±12 in V15.0c.4.  Smaller = less wandering on repetitive
-   *  textures (peg holes, slatted panels), but easier to miss the
-   *  true overlap when pose noise is high.  Range 4 – 30.  Default
-   *  12. */
-  nccSearchMargin2d: number;
-
-  /** V15.0d — 2D NCC confidence threshold below which the correction
-   *  is rejected.  Was hardcoded 0.75 in V15.0c.4.  Higher = stricter,
-   *  fewer false matches on repetitive textures, but more frames
-   *  where NCC silently doesn't fire.  Range 0.30 – 0.99.  Default
-   *  0.75. */
-  nccConfidenceThreshold2d: number;
-
-  /** V15.0d (1B) — exponential-moving-average smoothing on 2D NCC
-   *  corrections.  When enabled, the applied correction is
-   *  `α × current + (1−α) × prev` instead of just `current`.  Damps
-   *  single-frame snaps to spurious peaks.  Default false. */
-  enableNcc2dEmaSmoothing: boolean;
-
-  /** V15.0d — EMA weight on the CURRENT-frame NCC correction
-   *  (1 − α weight on the previous correction).  Range 0.05 – 0.95.
-   *  Default 0.4 (60% prev / 40% current — heavy damping). */
-  ncc2dEmaAlpha: number;
-
-  /** V15.0d (1C) — pan-axis-aware 2D NCC.  When enabled, the cross-
-   *  axis (perpendicular to pan) NCC correction is clamped tighter
-   *  than the pan-axis (since 1D NCC + pose already handle cross-
-   *  axis wobble).  Default false. */
-  enableNcc2dPanAxisLock: boolean;
-
-  /** V15.0d — cross-axis clamp (pixels) for the pan-axis-aware mode.
-   *  Range 0 – 30.  Default 5. */
-  ncc2dCrossAxisLockPx: number;
-
   // Frame selection (V16)
 
   /** V16 — how the engine decides which ARFrames to ingest.

package/src/stitching/stitchVideo.ts

@@ -76,32 +76,6 @@ export interface StitchVideoOptions {
    *     Right choice on low-RAM devices or with `feather`.
    */
   seamFinderType?: 'graphcut' | 'skip';
-  /**
-   * Phase 5: pose-driven stitching.  When present and non-empty,
-   * the native stitcher skips features → matching → BundleAdjuster
-   * and builds cv::detail::CameraParams directly from each pose's
-   * intrinsics + quaternion.  Each entry has the shape returned
-   * by `NativeModules.RNSARSession.snapshotPoseLog()`:
-   *
-   *   { tx, ty, tz, qx, qy, qz, qw,
-   *     fx, fy, cx, cy,
-   *     imageWidth, imageHeight,
-   *     timestampMs, trackingState }
-   *
-   * Frames whose closest pose is beyond a 100 ms tolerance are
-   * dropped before stitching; if fewer than 2 remain the call
-   * rejects with `opencv-failed-1032` so the host can fall back
-   * to the feature-matched path (re-call `stitchVideo` without
-   * `poses`).
-   */
-  poses?: Array<{
-    tx: number; ty: number; tz: number;
-    qx: number; qy: number; qz: number; qw: number;
-    fx: number; fy: number; cx: number; cy: number;
-    imageWidth: number; imageHeight: number;
-    timestampMs: number;
-    trackingState: number;
-  }>;
 }
 
 

package/src/types.ts

@@ -56,101 +56,6 @@ export interface DeviceMetadata {
 // `Camera.tsx` adapts this into the public `CameraCaptureResult` (a
 // discriminated union of photo + panorama) before emitting `onCapture`.
 
-/**
- * v0.9.0 Layer 3 — one sampled frame delivered by `useFrameStream`
- * to the JS-thread handler.
- *
- * The JPEG file at `jpegPath` is the stream's own copy.  Hosts that
- * need long-term retention MUST copy the file synchronously inside
- * the handler — the same path may be overwritten by a subsequent
- * sample (slot reuse — see the hook's docstring for the rotation
- * policy).
- */
-export interface SampledFrame {
-  /** Absolute filesystem path to the JPEG.  No `file://` prefix. */
-  jpegPath: string;
-
-  /**
-   * Pose at sample time.  `translation` is `undefined` in non-AR
-   * mode (gyro provides rotation only; no spatial anchor).
-   */
-  pose: {
-    rotation: [number, number, number, number];
-    translation?: [number, number, number];
-  };
-
-  /** Frame timestamp (ms; per the v0.8.0 StitcherFrame contract). */
-  timestamp: number;
-
-  /** JPEG width / height in pixels. */
-  width: number;
-  height: number;
-}
-
-/**
- * v0.9.0 Layer 3 — options for `useFrameStream`.
- *
- * For worklet-native processing without JPEG roundtrip (OCR via
- * Vision/ML Kit, TFLite ML, LiDAR depth), use
- * `useThrottledFrameProcessor` (Layer 2) instead.
- */
-export interface FrameStreamOptions {
-  /**
-   * Target sampling rate in Hertz.  Clamped to `[0.5, 10]`.  The
-   * Layer 2 throttle gate enforces the rate inside the worklet;
-   * ticks too close together are dropped silently.
-   *
-   * Clamp upper bound (10 Hz) is intentionally lower than Layer 2's
-   * (30 Hz) — beyond 10 Hz the per-frame JPEG encode + JS-bridge
-   * cost dominates the wall-clock budget.  Hosts that need higher
-   * rates should be on Layer 2 with their own JPEG encoder call
-   * (or no JPEG at all).
-   */
-  sampleHz: number;
-
-  /**
-   * JPEG quality (0-100).  Default 75.  Clamped silently to
-   * `[1, 100]` by the underlying `save_frame_as_jpeg` native plugin.
-   */
-  quality?: number;
-
-  /**
-   * Directory to write JPEG files into.  Defaults to a per-app
-   * `<cache>/rnis-frame-stream/` subdirectory.  The directory is
-   * `mkdir -p`'d on first use; hosts that supply an existing
-   * absolute path are responsible for its lifecycle.
-   */
-  outputDir?: string;
-}
-
-/**
- * v0.9.0 Layer 2 — options for `useThrottledFrameProcessor`.
- *
- * Wraps v0.8.0's `useFrameProcessor` with a monotonic-time throttle
- * gate so the supplied worklet fires at most `sampleHz` times per
- * second.  Use for sub-frame-rate worklet-native processing — native
- * OCR (Vision.framework / ML Kit), TFLite ML detection, LiDAR depth
- * processing — where the bbox / depth payloads are small enough to
- * bridge to JS via `runOnJS`.
- *
- * For JS-thread JPEG consumers (file-path OCR libraries, cloud
- * upload, thumbnail UI), use `useFrameStream` (Layer 3) instead.
- */
-export interface ThrottledFrameProcessorOptions {
-  /**
-   * Target sampling rate in Hertz.  Clamped to `[0.5, 30]`.  Inside
-   * the worklet a monotonic-time gate enforces the rate; ticks too
-   * close together are silently dropped.
-   *
-   * The clamp upper bound (30 Hz) sits at typical AR rates on
-   * mid-range Android devices — beyond that, the host should just
-   * use `useFrameProcessor` directly (no throttle).  The clamp
-   * lower bound (0.5 Hz) prevents accidentally-zero-divide values
-   * + matches `useFrameStream`'s convention.
-   */
-  sampleHz: number;
-}
-
 export interface CaptureResult {
   /** Unique device-generated UUID */
   deviceUuid: string;