react-native-image-stitcher 0.15.2 → 0.16.0

package/src/camera/CameraView.tsx

@@ -23,6 +23,7 @@ import React, {
   forwardRef,
   useCallback,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
 } from 'react';
@@ -35,11 +36,22 @@ import {
 } from 'react-native';
 import {
   Camera,
-  useCameraFormat,
   type CameraDevice,
   type CameraProps,
 } from 'react-native-vision-camera';
 
+import { pickCaptureFormat } from './pickCaptureFormat';
+
+
+/**
+ * Cap on the chosen capture format's PHOTO long edge (px).  4032 ≈ 12 MP at
+ * 4:3 ("4K"-ish), matching the 1× lens, so the ultra-wide stops producing a
+ * 48 MP / ~6000 px still.  Set to 2016 for "2K" (~3 MP).  `0` reverts to pure
+ * max-video.  TODO(v0.16): expose as a `<Camera photoMaxLongEdge>` prop once
+ * the 0.5× panorama 8-bit check passes on-device.
+ */
+const PHOTO_LONG_EDGE_CAP = 4032;
+
 
 export interface CameraViewProps {
   /** Output of ``useCapture().device``.  If null, a placeholder is shown. */
@@ -190,21 +202,39 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
   // natively while keeping full-res keyframes.  Aspect stays the
   // top-priority filter, so 4:3 WYSIWYG parity holds on every device.
   //
-  // Still resolution is capped at ~12 MP.  The max-video 4:3 format pairs
-  // with a 24 MP photo (5712×4284) on the iPhone 16 Pro by default — 2×
-  // the file size + per-capture memory for no benefit on the panorama
-  // path (which uses the VIDEO stream, not takePhoto).  `photoResolution`
-  // is the LOWEST-priority filter, so it only breaks ties between equal
-  // max-video formats (e.g. the 12 MP-photo vs 24 MP-photo variants that
-  // share the same 4032×3024 video) — it never trades preview/stitch
-  // sharpness for a smaller still.  4032×3024 = 12 MP at 4:3; nearest-
-  // match keeps stills near there on any device.
-  const format = useCameraFormat(device ?? undefined, [
-    { photoAspectRatio: 4 / 3 },
-    { videoAspectRatio: 4 / 3 },
-    { videoResolution: 'max' },
-    { photoResolution: { width: 4032, height: 3024 } },
-  ]);
+  // Still resolution: a plain `videoResolution:'max'` filter (what we used
+  // before) maximises VIDEO and lets the PHOTO ride along — on the iPhone 16
+  // Pro ULTRA-WIDE that pairs a 48 MP still (8064×6048) with the max-video
+  // format, so a tap photo came out ~6000 px.  `pickCaptureFormat` instead
+  // picks the SHARPEST-video 4:3 format whose photo is within
+  // PHOTO_LONG_EDGE_CAP (verified on-device: the ultra-wide then chooses
+  // 3264×2448 video + 12 MP photo — still a crisp preview, no 48 MP still).
+  // The cap is on the PHOTO; video stays as high as the cap allows, so the
+  // 8-bit/sharp-preview rationale above still holds.
+  //
+  // preferHighFps: a panorama preview must stay SMOOTH while panning.  Video-
+  // resolution-first would pick the 3264×2448 **@30 fps** format over the
+  // 1920×1440 **@60 fps** one — visibly jittery.  Keyframes are clamped to
+  // 640/1280 px before stitching, so the extra video resolution buys nothing
+  // here; a 60 fps stream just looks right.  We opt the panorama camera in.
+  const format = useMemo(
+    () =>
+      pickCaptureFormat(device?.formats ?? [], {
+        maxPhotoLongEdge: PHOTO_LONG_EDGE_CAP,
+        aspect: 4 / 3,
+        preferHighFps: true,
+      }),
+    [device],
+  );
+
+  // Pin the session frame rate to the format's max, capped at 60.  Picking a
+  // 60 fps-capable format is necessary but NOT sufficient — without an explicit
+  // `fps`, vision-camera can leave the session at a lower default, which is the
+  // jitter the user saw.  min(maxFps, 60) is always within the format's range.
+  const fps = useMemo(
+    () => (format ? Math.min(format.maxFps ?? 30, 60) : undefined),
+    [format],
+  );
 
   // 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
@@ -275,6 +305,8 @@ export const CameraView = forwardRef<Camera | null, CameraViewProps>(function Ca
         video={video}
         // Pin preview + photo to the same 4:3 format (WYSIWYG capture).
         format={format}
+        // Run the session at the format's fps (≤60) for a smooth pan preview.
+        {...(fps != null ? { fps } : {})}
         // v0.13.2 — multi-cam lens switch via zoom (undefined = default).
         {...(zoom != null ? { zoom } : {})}
         // Bake the device orientation into the captured pixels.

package/src/camera/CaptureCountdownOverlay.tsx

@@ -0,0 +1,272 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureCountdownOverlay — the blinking auto-stop countdown shown at the
+ * user-perceived TOP-LEFT during an in-progress panorama capture (item 5
+ * of the first-time-user GUIDANCE flow).
+ *
+ *   ┌──────────────────────────────────────────────────┐
+ *   │  ● 9                                              │ ← top-left, blinks
+ *   │                                                   │
+ *   │            (camera preview / pan in progress)     │
+ *   │                                                   │
+ *   └──────────────────────────────────────────────────┘
+ *
+ * Why this exists
+ *   The capture auto-finalizes after a fixed window (the parent owns the
+ *   real timer — see Camera's `countdownSecondsFrom`).  Without a visible
+ *   counter the auto-stop feels abrupt ("why did it stop?").  A calm
+ *   blinking "● N" tells the user how many seconds of pan they have left.
+ *
+ * What it does
+ *   - Renders an amber glow dot + a white tabular-nums integer
+ *     (`secondsRemaining`, computed by the parent) using the shared
+ *     {@link GUIDANCE_COUNTDOWN} design tokens.
+ *   - Pins itself to the user-perceived top-left corner across all four
+ *     device orientations.  The app layout is portrait-locked, so — like
+ *     {@link CaptureStatusOverlay} / {@link PanoramaGuidance} — we anchor
+ *     to the matching layout corner and apply a rotation transform so the
+ *     number reads upright in the user's hold.
+ *   - Blinks the WHOLE timer (dot + number) between
+ *     `GUIDANCE_COUNTDOWN.blinkMinOpacity` and `blinkMaxOpacity` over
+ *     `blinkPeriodMs` with an ease-in-out loop on the native driver.
+ *
+ * The displayed number is COSMETIC only — the parent owns the auth­oritative
+ * auto-stop timer and computes `secondsRemaining`.  This component never
+ * fires a stop; it purely visualises the remaining time, so a dropped frame
+ * or a re-render hiccup can never desync from (or pre-empt) the real timer.
+ *
+ * Pure-presentational and `pointerEvents="none"`: it never steals taps from
+ * the camera / shutter beneath it, and renders nothing when `!visible` so
+ * the host can mount it unconditionally without layout shifts.
+ */
+
+import React, { useEffect, useRef } from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { GUIDANCE_COUNTDOWN, GUIDANCE_TOKENS } from './guidanceTokens';
+import { type DeviceOrientation } from './useDeviceOrientation';
+
+
+export interface CaptureCountdownOverlayProps {
+  /**
+   * Show / hide.  Driven by the host while a capture is in progress
+   * (typically `statusPhase === 'recording'`).  Renders nothing when
+   * false so the host can mount it unconditionally.
+   */
+  visible: boolean;
+  /**
+   * Whole seconds of capture remaining, as computed by the parent's
+   * authoritative timer (Camera's `countdownSecondsFrom`).  Displayed
+   * verbatim via `Math.max(0, Math.round(...))` so a fractional or
+   * transiently-negative value never renders as "-0" or "3.0".
+   *
+   * COSMETIC ONLY — this component does not own the auto-stop.
+   */
+  secondsRemaining: number;
+  /**
+   * Physical device orientation (typically from `useDeviceOrientation`).
+   * Drives the corner anchoring + rotation so the number sits at the
+   * user-perceived top-left and reads upright.
+   */
+  orientation: DeviceOrientation;
+  /** Outer style passthrough. */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+export function CaptureCountdownOverlay({
+  visible,
+  secondsRemaining,
+  orientation,
+  style,
+}: CaptureCountdownOverlayProps): React.JSX.Element | null {
+  // Single Animated.Value looping min→max→min drives the whole-timer
+  // blink.  Cheap (no JS listeners, native driver) and only spins up
+  // while visible; torn down on hide so the loop isn't running the
+  // rest of the time the screen is up.
+  const blink = useRef(
+    new Animated.Value(GUIDANCE_COUNTDOWN.blinkMaxOpacity),
+  ).current;
+
+  useEffect(() => {
+    if (!visible) {
+      // Reset to fully-opaque so the next show starts bright rather
+      // than mid-fade.
+      blink.setValue(GUIDANCE_COUNTDOWN.blinkMaxOpacity);
+      return;
+    }
+    // Symmetric fade down + back up, so a full min→max→min cycle takes
+    // `blinkPeriodMs` (each half-leg is half the period).
+    const halfPeriod = GUIDANCE_COUNTDOWN.blinkPeriodMs / 2;
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(blink, {
+          toValue: GUIDANCE_COUNTDOWN.blinkMinOpacity,
+          duration: halfPeriod,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+        Animated.timing(blink, {
+          toValue: GUIDANCE_COUNTDOWN.blinkMaxOpacity,
+          duration: halfPeriod,
+          easing: Easing.inOut(Easing.ease),
+          useNativeDriver: true,
+        }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [visible, blink]);
+
+  if (!visible) return null;
+
+  // Clamp to a non-negative integer.  The parent's timer may briefly
+  // report a fractional or sub-zero value at the auto-stop boundary;
+  // we never want to render "-1" or "2.4".
+  const displaySeconds = Math.max(0, Math.round(secondsRemaining));
+
+  const cornerStyle = countdownStyleForOrientation(orientation);
+
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[styles.root, cornerStyle, { opacity: blink }, style]}
+      accessibilityRole="timer"
+      accessibilityLiveRegion="polite"
+      accessibilityLabel={`${displaySeconds} seconds remaining`}
+    >
+      <View style={styles.dot} />
+      <Text style={styles.number} numberOfLines={1} allowFontScaling={false}>
+        {displaySeconds}
+      </Text>
+    </Animated.View>
+  );
+}
+
+
+/**
+ * Style placing the countdown at the user-perceived TOP-LEFT corner with
+ * the number reading upright in the user's hold, inset by
+ * `GUIDANCE_COUNTDOWN.inset` from that corner.
+ *
+ * Mirrors the corner-anchor + percentage-translate self-centering of
+ * {@link CaptureStatusOverlay}'s `bannerStyleForOrientation`, but anchored
+ * to the user's top-LEFT instead of top-center.  For each orientation we
+ * anchor the row to the layout corner that maps to the user's top-left,
+ * then rotate the row about its center so it reads upright:
+ *
+ *   portrait              → layout top-left,     0°
+ *   landscape-left        → layout bottom-left, +90°
+ *   landscape-right       → layout top-right,   -90°
+ *   portrait-upside-down  → layout bottom-right, 180°
+ *
+ * The `translate('±50%')` pair pins the row's CENTER a fixed `inset`
+ * from the chosen corner so the post-rotation top-left edge lands at
+ * `inset` regardless of the row's own width/height — the same trick the
+ * banner uses to stay corner-aligned without measuring its content.
+ */
+function countdownStyleForOrientation(
+  orientation: DeviceOrientation,
+): ViewStyle {
+  const { inset } = GUIDANCE_COUNTDOWN;
+  switch (orientation) {
+    case 'landscape-left':
+      // Device held so user-top runs along the layout LEFT edge; the
+      // user's top-left maps to the layout BOTTOM-left.  +90° makes the
+      // row read upright.
+      return {
+        position: 'absolute',
+        bottom: inset,
+        left: inset,
+        transform: [
+          { translateX: '50%' },
+          { translateY: '-50%' },
+          { rotate: '90deg' },
+        ],
+      };
+    case 'landscape-right':
+      // User-top runs along the layout RIGHT edge; user's top-left maps
+      // to the layout TOP-right.  -90° makes the row read upright.
+      return {
+        position: 'absolute',
+        top: inset,
+        right: inset,
+        transform: [
+          { translateX: '-50%' },
+          { translateY: '50%' },
+          { rotate: '-90deg' },
+        ],
+      };
+    case 'portrait-upside-down':
+      // User-top-left maps to the layout BOTTOM-right; 180° flips the row.
+      return {
+        position: 'absolute',
+        bottom: inset,
+        right: inset,
+        transform: [
+          { translateX: '-50%' },
+          { translateY: '-50%' },
+          { rotate: '180deg' },
+        ],
+      };
+    case 'portrait':
+    default:
+      return {
+        position: 'absolute',
+        top: inset,
+        left: inset,
+        transform: [
+          { translateX: '50%' },
+          { translateY: '50%' },
+        ],
+      };
+  }
+}
+
+
+const styles = StyleSheet.create({
+  root: {
+    // position: 'absolute' is re-applied by countdownStyleForOrientation
+    // alongside the corner offsets + transform; kept here too so the row
+    // lays out as a self-sized box even before the orientation style
+    // merges in.
+    position: 'absolute',
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  dot: {
+    width: GUIDANCE_COUNTDOWN.dotSize,
+    height: GUIDANCE_COUNTDOWN.dotSize,
+    borderRadius: GUIDANCE_COUNTDOWN.dotSize / 2,
+    backgroundColor: GUIDANCE_TOKENS.amber,
+    marginRight: GUIDANCE_COUNTDOWN.dotGap,
+    // Amber glow around the dot.  iOS honours all four shadow props;
+    // Android renders the glow via `elevation` (set below) since RN
+    // ignores view shadowColor there.
+    shadowColor: GUIDANCE_COUNTDOWN.dotGlow,
+    shadowOpacity: 1,
+    shadowRadius: GUIDANCE_COUNTDOWN.dotSize,
+    shadowOffset: { width: 0, height: 0 },
+    elevation: 6,
+  },
+  number: {
+    color: GUIDANCE_TOKENS.white,
+    fontSize: GUIDANCE_COUNTDOWN.fontSize,
+    fontWeight: GUIDANCE_COUNTDOWN.fontWeight,
+    // Tabular figures keep the glyph box a fixed width so the number
+    // doesn't jitter horizontally as it ticks 9→8→…→0.
+    fontVariant: ['tabular-nums'],
+    // Drop shadow for legibility over a bright/busy preview.
+    textShadowColor: GUIDANCE_TOKENS.scrim,
+    textShadowOffset: { width: 0, height: 1 },
+    textShadowRadius: 3,
+  },
+});

package/src/camera/CaptureFrameCounterOverlay.tsx

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * CaptureFrameCounterOverlay — a live "k / n" keyframe counter shown at the
+ * user-perceived TOP-CENTRE during a panorama capture.
+ *
+ *   ┌──────────────────────────────────────────────────┐
+ *   │                     ● 3 / 6                       │ ← top-centre
+ *   │                                                   │
+ *   │            (camera preview / pan in progress)     │
+ *   └──────────────────────────────────────────────────┘
+ *
+ * Replaces the time countdown (item 5) as the primary capture HUD: instead
+ * of "seconds left" it shows how many keyframes have been captured out of
+ * the configured maximum, so the user can see the capture filling up and
+ * understand WHY it auto-finalizes at the cap (the parent stops + stitches
+ * when `framesCaptured` reaches `framesMax`).
+ *
+ * Pure-presentational + `pointerEvents="none"` (never steals taps); renders
+ * nothing when `!visible` so the host can mount it unconditionally.  Pins
+ * itself to the user-perceived TOP-CENTRE across all four orientations: the
+ * app is typically portrait-locked, so we anchor the pill to the layout edge
+ * that maps to the user's top and counter-rotate it to read upright (same
+ * idea as CaptureCountdownOverlay, but centre-anchored instead of corner).
+ */
+
+import React from 'react';
+import {
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { GUIDANCE_COUNTDOWN, GUIDANCE_PILL, GUIDANCE_TOKENS } from './guidanceTokens';
+import { type DeviceOrientation } from './useDeviceOrientation';
+
+
+export interface CaptureFrameCounterOverlayProps {
+  /** Show / hide.  Driven by the host while a capture is recording. */
+  visible: boolean;
+  /** Keyframes accepted so far this capture (the engine's live count). */
+  framesCaptured: number;
+  /** Configured keyframe cap — the capture auto-finalizes when reached. */
+  framesMax: number;
+  /** Physical device orientation (from `useDeviceOrientation`). */
+  orientation: DeviceOrientation;
+  /** Outer style passthrough. */
+  style?: StyleProp<ViewStyle>;
+}
+
+
+export function CaptureFrameCounterOverlay({
+  visible,
+  framesCaptured,
+  framesMax,
+  orientation,
+  style,
+}: CaptureFrameCounterOverlayProps): React.JSX.Element | null {
+  if (!visible || framesMax <= 0) return null;
+
+  // Clamp the displayed numerator into [0, framesMax] — the engine can
+  // briefly report the cap-th accept before the parent finalizes.
+  const k = Math.max(0, Math.min(framesCaptured, framesMax));
+
+  const { container, rotate } = topCenterForOrientation(
+    orientation,
+    GUIDANCE_COUNTDOWN.inset,
+  );
+
+  return (
+    <View
+      pointerEvents="none"
+      style={[styles.layer, container, style]}
+    >
+      <View style={[styles.pill, { transform: [{ rotate }] }]}>
+        <View style={styles.dot} />
+        <Text style={styles.text} allowFontScaling={false} numberOfLines={1}>
+          <Text style={styles.count}>{k}</Text>
+          <Text style={styles.slash}> / {framesMax}</Text>
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+
+/**
+ * Flex alignment that pins content to the user-perceived TOP-CENTRE for a
+ * given device hold, plus the rotation that makes it read upright:
+ *
+ *   portrait              → layout top edge,    centred, 0°
+ *   landscape-left        → layout left edge,   centred, +90°
+ *   landscape-right       → layout right edge,  centred, -90°
+ *   portrait-upside-down  → layout bottom edge, centred, 180°
+ *
+ * `inset` is the distance from the user's top edge (larger values push the
+ * content further down the screen) — exported so other top-anchored overlays
+ * (e.g. the too-fast pill) can stack BELOW the counter by passing a bigger
+ * inset, and stay correctly placed + upright in every orientation.
+ */
+export function topCenterForOrientation(
+  orientation: DeviceOrientation,
+  inset: number,
+): { container: ViewStyle; rotate: string } {
+  switch (orientation) {
+    case 'landscape-left':
+      return {
+        container: {
+          justifyContent: 'center',
+          alignItems: 'flex-start',
+          paddingLeft: inset,
+        },
+        rotate: '90deg',
+      };
+    case 'landscape-right':
+      return {
+        container: {
+          justifyContent: 'center',
+          alignItems: 'flex-end',
+          paddingRight: inset,
+        },
+        rotate: '-90deg',
+      };
+    case 'portrait-upside-down':
+      return {
+        container: {
+          justifyContent: 'flex-end',
+          alignItems: 'center',
+          paddingBottom: inset,
+        },
+        rotate: '180deg',
+      };
+    case 'portrait':
+    default:
+      return {
+        container: {
+          justifyContent: 'flex-start',
+          alignItems: 'center',
+          paddingTop: inset,
+        },
+        rotate: '0deg',
+      };
+  }
+}
+
+
+const styles = StyleSheet.create({
+  // Full-screen, non-interactive layer; the per-orientation flex alignment
+  // places the pill on the correct edge, centred along it.
+  layer: { ...StyleSheet.absoluteFillObject },
+  pill: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: GUIDANCE_PILL.paddingVertical,
+    paddingHorizontal: GUIDANCE_PILL.paddingHorizontal,
+    borderRadius: GUIDANCE_PILL.borderRadius,
+    backgroundColor: GUIDANCE_TOKENS.scrim,
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: GUIDANCE_TOKENS.hairline,
+  },
+  dot: {
+    width: GUIDANCE_PILL.dotSize,
+    height: GUIDANCE_PILL.dotSize,
+    borderRadius: GUIDANCE_PILL.dotSize / 2,
+    backgroundColor: GUIDANCE_TOKENS.amber,
+    marginRight: GUIDANCE_PILL.dotGap,
+  },
+  text: {
+    // Tabular figures keep the counter from jittering as k ticks up.
+    fontVariant: ['tabular-nums'],
+  },
+  count: {
+    color: GUIDANCE_TOKENS.white,
+    fontSize: 17,
+    fontWeight: '700',
+  },
+  slash: {
+    color: GUIDANCE_TOKENS.amber,
+    fontSize: 15,
+    fontWeight: '600',
+  },
+});

package/src/camera/CaptureMemoryPill.tsx

@@ -18,7 +18,13 @@
  */
 
 import React, { useEffect, useState } from 'react';
-import { StyleSheet, Text, View } from 'react-native';
+import {
+  StyleSheet,
+  Text,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
 
 import { getIncrementalNativeModule } from '../stitching/incremental';
 
@@ -29,11 +35,19 @@ export interface CaptureMemoryPillProps {
    *  for no visible benefit; higher loses correlation with capture
    *  activity. */
   pollIntervalMs?: number;
+  /**
+   * Optional position override.  When supplied it REPLACES the default
+   * top-right anchor (`top: topInset + 56, right: 12`), so the pill can be
+   * reused on other screens (e.g. the crop/preview surface) without colliding
+   * with their own corner UI.  Pass the full absolute position you want.
+   */
+  style?: StyleProp<ViewStyle>;
 }
 
 export function CaptureMemoryPill({
   topInset = 0,
   pollIntervalMs = 500,
+  style,
 }: CaptureMemoryPillProps): React.JSX.Element | null {
   const [memMB, setMemMB] = useState<number | null>(null);
 
@@ -69,7 +83,8 @@ export function CaptureMemoryPill({
       pointerEvents="none"
       style={[
         styles.container,
-        { top: topInset + 56, backgroundColor: bg },
+        { backgroundColor: bg },
+        style ?? { top: topInset + 56, right: 12 },
       ]}
       accessibilityRole="alert"
     >
@@ -81,7 +96,6 @@ export function CaptureMemoryPill({
 const styles = StyleSheet.create({
   container: {
     position: 'absolute',
-    right: 12,
     paddingHorizontal: 10,
     paddingVertical: 5,
     borderRadius: 999,

package/src/camera/CapturePreview.tsx

@@ -35,6 +35,8 @@ import {
   View,
 } from 'react-native';
 
+import { DISPLAY_DECODE_IMAGE_PROPS } from './displayDecodeImageProps';
+
 
 export type CapturePreviewActionVariant =
   | 'primary'
@@ -158,6 +160,9 @@ export function CapturePreview({
             source={{ uri: imageUri }}
             style={[styles.image, { aspectRatio }]}
             resizeMode="contain"
+            // OOM fix — decode at display size, not full panorama res
+            // (see DISPLAY_DECODE_IMAGE_PROPS for the native-heap rationale).
+            {...DISPLAY_DECODE_IMAGE_PROPS}
             accessibilityIgnoresInvertColors
           />
         </Pressable>