react-native-image-stitcher 0.15.0 → 0.15.2

package/CHANGELOG.md

@@ -16,6 +16,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.2] — 2026-06-11
+
+### Fixed
+
+- **Sharp non-AR camera preview (WYSIWYG follow-up).**  The v0.15.1
+  letterbox pinned the vision-camera format by aspect ratio only, so
+  `useCameraFormat` could settle on a degenerate 4:3 format — observed as
+  a 192×144 video stream on the iPhone 16 Pro — rendering the preview as
+  upscaled mush behind a full-resolution capture.  The format filter now
+  also requests `{ videoResolution: 'max' }`, so among 4:3 formats the
+  highest-resolution one is chosen: a sharp preview plus full-res frames
+  into the non-AR stitcher, with aspect kept as the top-priority filter so
+  4:3 capture parity holds.  A bounded target (e.g. 1920×1440) is
+  deliberately avoided — the nearest such format on the iPhone 16 Pro is
+  10-bit-only (`x420`/`x422`), which the frame processor's 8-bit
+  `420v`/`420f` pipeline rejects with `device/pixel-format-not-supported`;
+  vision-camera exposes no per-format pixel formats to JS, so `'max'`
+  (empirically the device's 8-bit full-res format) is the robust choice.
+  Tap-to-photo stills are capped at ~12 MP (`photoResolution: 4032×3024`,
+  lowest priority) so the iPhone 16 Pro's max-video format doesn't default
+  to a 24 MP still — the panorama path uses the video stream, not
+  `takePhoto`, so the cap costs nothing there.
+
+## [0.15.1] — 2026-06-08
+
+### Fixed
+
+- **Camera preview now matches capture FOV on all paths (letterbox WYSIWYG).**
+  The preview and captured photo now share the same field of view regardless of
+  the container size the host app uses.  Black letterbox bars fill any extra
+  space rather than cropping or stretching the camera feed.
+  - *VisionCamera path:* `CameraView` measures its rendered bounds via
+    `onLayout`, pins the format to 4:3 with `useCameraFormat`, then sizes the
+    `<Camera>` component to the largest axis-aligned box that fits the container
+    while preserving the format aspect ratio.
+  - *ARCore path (Android):* `RNSARCameraView` now selects a camera config
+    whose image aspect and texture aspect match within 2% (`selectMatchingCameraConfig`).
+    On devices (e.g. Galaxy A35) where no 4:3 matched config exists, the best
+    available 16:9 config is chosen — both preview and capture are 16:9.
+    The GL renderer letterboxes the camera texture inside the GL surface using
+    `setDisplayGeometry` + `glViewport`, centred on a black-cleared surface.
+  - *ARKit path (iOS):* `RNSARCameraView.layoutSubviews()` reads
+    `imageResolution` from the ARKit session and centres the scene view inside
+    the container bounds using the same aspect-correct letterbox calculation.
+
+- **ARCore CPU image resolution upgraded automatically.**  `selectMatchingCameraConfig`
+  prefers the highest-resolution matched config, so CPU image captures used for
+  stitching are now at full sensor resolution (1920×1080 on the Galaxy A35,
+  up from 640×480) with no API change required.
+
+### Changed
+
+- **`defaultCaptureSource` changed from `'ar'` to `'non-ar'`.**  AR mode is now
+  opt-in.  Host apps that want AR must pass `defaultCaptureSource="ar"` or
+  implement a toggle; the plain camera path is the default.
+
 ## [0.15.0] — 2026-06-07
 
 ### Breaking — only `batch-keyframe` remains; host-worklet / frame-stream hooks removed

package/android/src/main/java/io/imagestitcher/rn/RNSARCameraView.kt

@@ -58,6 +58,13 @@ class RNSARCameraView @JvmOverloads constructor(
     defStyle: Int = 0,
 ) : FrameLayout(context, attrs, defStyle), GLSurfaceView.Renderer {
 
+    // Raw camera sensor aspect ratio (W÷H, always > 1 for landscape sensors).
+    // Initialised to 4:3 — a safe fallback for the first layout pass before
+    // the session is attached.  Updated from session.cameraConfig once the
+    // session is available; many Android ARCore devices use 16:9 configs
+    // (e.g. Pixel phones), so reading it dynamically is important here.
+    private var cameraAspect: Float = 4f / 3f
+
     private val glView: GLSurfaceView = GLSurfaceView(context).also { v ->
         v.preserveEGLContextOnPause = true
         v.setEGLContextClientVersion(2)
@@ -123,6 +130,10 @@ class RNSARCameraView @JvmOverloads constructor(
     }
 
     init {
+        // Black background avoids a flash before the GL surface starts
+        // clearing itself black each frame (the GL-level letterbox draws
+        // the bars; this is just belt-and-suspenders for the first frame).
+        setBackgroundColor(android.graphics.Color.BLACK)
         addView(
             glView,
             LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT),
@@ -163,6 +174,26 @@ class RNSARCameraView @JvmOverloads constructor(
             } catch (e: CameraNotAvailableException) {
                 Log.w(TAG, "session.resume on attach: $e")
             }
+            // Read the actual camera image dimensions from the ARCore
+            // session config so the GL-level letterbox can size its box.
+            // cameraConfig is stable after session creation; on Pixel and
+            // some other Android devices the default config is 16:9, not
+            // 4:3, so we must read dynamically rather than hard-code.
+            try {
+                val size = session.cameraConfig.imageSize
+                if (size.width > 0 && size.height > 0) {
+                    cameraAspect = size.width.toFloat() / size.height.toFloat()
+                    Log.i(TAG, "cameraConfig imageSize: ${size.width}×${size.height} → cameraAspect=$cameraAspect")
+                    // Invalidate the cached display geometry so the next
+                    // onDrawFrame re-pushes it with the now-known camera
+                    // aspect.  The GL-level letterbox recomputes the box
+                    // every frame — no view resize needed.
+                    lastGeomW = -1
+                    lastGeomH = -1
+                }
+            } catch (t: Throwable) {
+                Log.w(TAG, "cameraConfig not yet available in onAttach; will use $cameraAspect fallback: ${t.message}")
+            }
         } else {
             Log.w(
                 TAG,
@@ -222,6 +253,54 @@ class RNSARCameraView @JvmOverloads constructor(
         ingestActive = active
     }
 
+    // ── GL-level letterbox ─────────────────────────────────────────
+    //
+    // The [glView] stays full-screen (MATCH_PARENT); we letterbox at the
+    // GL layer instead of resizing the SurfaceView.  Resizing the view
+    // does NOT work for ARCore: its BackgroundRenderer maps the camera
+    // texture with `Frame.transformCoordinates2d`, which uses the
+    // session's *display geometry* — not the view bounds.  A resized view
+    // therefore still rendered the full-screen (centre-cropped) camera,
+    // merely clipped to the smaller view → a cropped scene with one
+    // visible bar (the other hidden behind the capture controls).
+    //
+    // The correct fix is pure GL + ARCore geometry, applied per frame:
+    //   1. clear the WHOLE surface to black  → the letterbox bars,
+    //   2. setDisplayGeometry to the BOX size → ARCore's UV transform
+    //      fills the box aspect; when box aspect == camera aspect there
+    //      is nothing to crop, so the full FOV shows,
+    //   3. glViewport to the centred box      → camera draws only there.
+
+    /** Last display geometry pushed to ARCore; only re-push on change. */
+    private var lastGeomW: Int = -1
+    private var lastGeomH: Int = -1
+    private var lastGeomRotation: Int = -1
+
+    /**
+     * The centred letterbox rect [x, y, w, h] inside the full GL surface
+     * that preserves the camera's content aspect ratio.  The sensor is
+     * landscape (e.g. 640×480, 4:3); in portrait the on-screen content
+     * aspect is the inverse, so [cameraAspect] is inverted when the
+     * surface is taller than wide.  Falls back to the full surface until
+     * the surface has been measured.
+     */
+    private fun letterboxBox(): IntArray {
+        val sw = surfaceWidth
+        val sh = surfaceHeight
+        if (sw <= 0 || sh <= 0 || cameraAspect <= 0f) return intArrayOf(0, 0, sw, sh)
+        val contentAspect = if (sh > sw) 1f / cameraAspect else cameraAspect
+        val surfaceAspect = sw.toFloat() / sh.toFloat()
+        return if (surfaceAspect > contentAspect) {
+            // Surface wider than content — vertical bars left/right.
+            val w = (sh * contentAspect).toInt()
+            intArrayOf((sw - w) / 2, 0, w, sh)
+        } else {
+            // Surface taller than content — horizontal bars top/bottom.
+            val h = (sw / contentAspect).toInt()
+            intArrayOf(0, (sh - h) / 2, sw, h)
+        }
+    }
+
     // ── GLSurfaceView.Renderer ─────────────────────────────────────
 
     override fun onSurfaceCreated(gl: GL10?, config: EGLConfig?) {
@@ -238,6 +317,10 @@ class RNSARCameraView @JvmOverloads constructor(
     }
 
     override fun onDrawFrame(gl: GL10?) {
+        // Step 1 — paint the WHOLE surface black.  This is the letterbox:
+        // anything outside the camera box below stays black.
+        GLES20.glViewport(0, 0, surfaceWidth, surfaceHeight)
+        GLES20.glClearColor(0f, 0f, 0f, 1f)
         GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT or GLES20.GL_DEPTH_BUFFER_BIT)
 
         val session = sessionRef.get() ?: run {
@@ -251,10 +334,14 @@ class RNSARCameraView @JvmOverloads constructor(
         if (!sessionTextureBound) {
             backgroundRenderer.bindToSession(session)
             sessionTextureBound = true
-            // Ensure ARCore knows the surface geometry.
-            applyDisplayGeometry()
         }
 
+        // Step 2 — keep ARCore's display geometry equal to the letterbox
+        // box (not the full surface) so its UV transform fills the box
+        // aspect with the full camera FOV (no centre-crop).  Cheap: only
+        // calls setDisplayGeometry when the box actually changes.
+        applyDisplayGeometry()
+
         val frame = try {
             session.update()
         } catch (e: SessionPausedException) {
@@ -264,6 +351,11 @@ class RNSARCameraView @JvmOverloads constructor(
             return
         }
 
+        // Step 3 — confine the camera draw to the centred box; the black
+        // cleared in step 1 remains as the bars around it.
+        val box = letterboxBox()
+        GLES20.glViewport(box[0], box[1], box[2], box[3])
+
         // Draw the camera background regardless of tracking state —
         // gives the user something to look at while AR initialises.
         backgroundRenderer.draw(frame)
@@ -615,11 +707,28 @@ class RNSARCameraView @JvmOverloads constructor(
             ?.defaultDisplay
             ?.rotation
             ?: Surface.ROTATION_0
-        if (rotation != lastDisplayRotation
-            || surfaceWidth > 0 || surfaceHeight > 0
-        ) {
-            session.setDisplayGeometry(rotation, surfaceWidth, surfaceHeight)
-            lastDisplayRotation = rotation
+        // Keep lastDisplayRotation current regardless — the JPEG encode
+        // path (forwardToIncremental → encodeJpegFromNV21) reads it for
+        // the EXIF orientation tag.
+        lastDisplayRotation = rotation
+
+        val box = letterboxBox()
+        val bw = box[2]
+        val bh = box[3]
+        if (bw <= 0 || bh <= 0) return
+        // Feed ARCore the BOX dimensions (not the full surface) so its UV
+        // transform fills the box aspect — the full camera FOV with no
+        // centre-crop.  Only push on change to avoid per-frame churn.
+        if (rotation != lastGeomRotation || bw != lastGeomW || bh != lastGeomH) {
+            session.setDisplayGeometry(rotation, bw, bh)
+            lastGeomRotation = rotation
+            lastGeomW = bw
+            lastGeomH = bh
+            Log.d(
+                TAG,
+                "setDisplayGeometry(box): rotation=$rotation box=${bw}×${bh} "
+                    + "surface=${surfaceWidth}×${surfaceHeight} cameraAspect=$cameraAspect",
+            )
         }
     }
 

package/android/src/main/java/io/imagestitcher/rn/RNSARSession.kt

@@ -11,6 +11,8 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReactContextBaseJavaModule
 import com.facebook.react.bridge.ReactMethod
 import com.google.ar.core.ArCoreApk
+import com.google.ar.core.CameraConfig
+import com.google.ar.core.CameraConfigFilter
 import com.google.ar.core.Config
 import com.google.ar.core.Plane
 import com.google.ar.core.Pose
@@ -164,6 +166,7 @@ class RNSARSession(reactContext: ReactApplicationContext)
 
             val session = sessionRef.get() ?: Session(reactApplicationContext).also {
                 sessionRef.set(it)
+                selectMatchingCameraConfig(it)
             }
             val config = Config(session).apply {
                 // Smoothed depth is the ARCore equivalent of iOS
@@ -322,6 +325,7 @@ class RNSARSession(reactContext: ReactApplicationContext)
 
             val session = Session(reactApplicationContext).also {
                 sessionRef.set(it)
+                selectMatchingCameraConfig(it)
             }
             val config = Config(session).apply {
                 if (session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)) {
@@ -832,6 +836,51 @@ class RNSARSession(reactContext: ReactApplicationContext)
         poseLogLock.write { poseLog.clear() }
     }
 
+    /**
+     * Pick an ARCore camera config whose CPU image and GPU texture share
+     * the same aspect ratio, so the preview (texture) and the captured /
+     * stitched frames (acquireCameraImage) cover the SAME field of view.
+     *
+     * ARCore's default often pairs a 16:9 GPU texture with a 4:3 CPU
+     * image (e.g. 1920x1080 texture + 640x480 image on the Galaxy A35):
+     * the texture is then missing ~12 deg of vertical sensor FOV the
+     * image has, so the preview can never match the photo.  Choosing a
+     * config where the two aspects match (preferring 4:3 for max FOV,
+     * then the highest image resolution) makes preview == capture by
+     * construction -- and usually raises the stitched-frame / photo
+     * resolution above 640x480 as a bonus.
+     *
+     * Must be called on a freshly-created, un-resumed session (ARCore
+     * requires the session paused for setCameraConfig).  Best-effort: on
+     * any failure we keep ARCore's default config.
+     */
+    private fun selectMatchingCameraConfig(session: Session) {
+        try {
+            val configs = session.getSupportedCameraConfigs(CameraConfigFilter(session))
+            if (configs.isEmpty()) return
+            fun aspect(s: android.util.Size): Float = s.width.toFloat() / s.height.toFloat()
+
+            val matched = configs.filter {
+                kotlin.math.abs(aspect(it.imageSize) - aspect(it.textureSize)) < 0.02f
+            }
+            val pool = if (matched.isNotEmpty()) matched else configs
+            val chosen = pool.sortedWith(
+                compareBy<CameraConfig> { kotlin.math.abs(aspect(it.imageSize) - 4f / 3f) }
+                    .thenByDescending { it.imageSize.width * it.imageSize.height },
+            ).firstOrNull() ?: return
+            session.setCameraConfig(chosen)
+            Log.i(
+                TAG,
+                "selectMatchingCameraConfig: chose image=" +
+                    "${chosen.imageSize.width}x${chosen.imageSize.height} texture=" +
+                    "${chosen.textureSize.width}x${chosen.textureSize.height} " +
+                    "(from ${configs.size} configs, ${matched.size} aspect-matched)",
+            )
+        } catch (t: Throwable) {
+            Log.w(TAG, "selectMatchingCameraConfig failed; keeping default config: ${t.message}")
+        }
+    }
+
     companion object {
         // Mirrors RNSARTrackingState on iOS for cross-platform
         // identical JS behaviour.

package/dist/camera/Camera.js

@@ -281,7 +281,7 @@ function extractPanoramaOverrides(props) {
  * The public `<Camera>` component.
  */
 function Camera(props) {
-    const { defaultCaptureSource = 'ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
+    const { defaultCaptureSource = 'non-ar', defaultLens = '1x', captureSources = 'both', enablePhotoMode = true, enablePanoramaMode = true, showSettingsButton = false, style, outputDir, onCapture, onCaptureSourceChange, onLensChange, onFramesDropped, onError, onCaptureAbandoned, flash: controlledFlash, onFlashChange, showFlashButton = true, headerTitle, onHeaderBack, headerBackLabel, headerGuidance, headerColors, thumbnails, thumbnailsMin, thumbnailsMax, onThumbnailPress, capturePreview, capturePreviewActions, onCapturePreviewClose, frameProcessor: hostFrameProcessor, engine = 'batch-keyframe', } = props;
     // v0.13.2 — capture-source constraint (default 'both').  Derives which
     // sources are permitted; `captureSources` overrides any conflicting
     // `defaultCaptureSource`.  Used to constrain the initial AR preference

package/dist/camera/CameraView.js

@@ -92,12 +92,111 @@ exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash
     // Internal ref so we can both attach to <Camera> and forward outward.
     const innerRef = (0, react_1.useRef)(null);
     (0, react_1.useImperativeHandle)(ref, () => innerRef.current);
+    // ── 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.
+    //
+    // Resolution preference matters too: filtering on aspect ALONE lets
+    // vision-camera settle on whatever 4:3 format sorts first — observed as
+    // a 192×144 VIDEO stream on the iPhone 16 Pro (the photo still uses the
+    // format's full-res photo dims, so you'd get a sharp capture behind a
+    // mush preview).  So we also request the highest video resolution.
+    //
+    // Why `'max'` and not a bounded target like 1920×1440?  We tried the
+    // bounded target and it FAILED on the iPhone 16 Pro: the nearest
+    // 1920×1440 format is a 10-bit format (pixel formats x420 / x422 only —
+    // and it is NOT flagged HDR, so the `videoHdr` filter can't dodge it).
+    // The frame processor + the stitcher's CV pipeline need 8-bit
+    // `420v`/`420f`, so vision-camera raises
+    // `device/pixel-format-not-supported` and silently falls back to a
+    // default pixel format — breaking non-AR stitching.  vision-camera does
+    // NOT expose a format's supported pixel formats to JS (no
+    // `pixelFormats` field; `FormatFilter` has no pixel-format key), so we
+    // can't select an 8-bit format by inspection.  Empirically the device's
+    // MAX 4:3 video format is 8-bit (420v/420f) on the iPhone 16 Pro, and
+    // Android formats are near-universally 8-bit YUV_420_888, so `'max'` is
+    // the robust choice: a sharp preview on a frame-processor-compatible
+    // pipeline.  Trade-off: the max format tends to run at 30 fps (fine for
+    // hold-to-pan) and feeds full-res frames to the non-AR gate — if that
+    // ever shows up as dropped frames we can downscale for the gate
+    // 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 = (0, react_native_vision_camera_1.useCameraFormat)(device ?? undefined, [
+        { photoAspectRatio: 4 / 3 },
+        { videoAspectRatio: 4 / 3 },
+        { videoResolution: 'max' },
+        { photoResolution: { width: 4032, height: 3024 } },
+    ]);
+    // 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] = (0, react_1.useState)(null);
+    const onRootLayout = (0, react_1.useCallback)((e) => {
+        const { width, height } = e.nativeEvent.layout;
+        setSize((prev) => prev && prev.w === width && prev.h === height
+            ? prev
+            : { w: width, h: height });
+    }, []);
     if (!device) {
         return (react_1.default.createElement(react_native_1.View, { style: [styles.placeholder, style], accessibilityLabel: "Camera initialising" },
             react_1.default.createElement(react_native_1.Text, { style: styles.placeholderText }, "Initialising camera\u2026")));
     }
-    return (react_1.default.createElement(react_native_1.View, { style: [styles.root, style] },
-        react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: innerRef, style: react_native_1.StyleSheet.absoluteFill, device: device, isActive: isActive, photo: true, video: video, ...(zoom != null ? { zoom } : {}), 
+    // 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;
+    if (size == null || size.w === 0 || size.h === 0) {
+        cameraStyle = react_native_1.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 (react_1.default.createElement(react_native_1.View, { style: [styles.root, style], onLayout: onRootLayout },
+        react_1.default.createElement(react_native_vision_camera_1.Camera, { ref: innerRef, 
+            // 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: true, video: video, 
+            // Pin preview + photo to the same 4:3 format (WYSIWYG capture).
+            format: format, ...(zoom != null ? { zoom } : {}), 
             // Bake the device orientation into the captured pixels.
             // Without this, vision-camera writes the file in the camera
             // sensor's native landscape and relies on EXIF metadata to
@@ -107,7 +206,26 @@ exports.CameraView = (0, react_1.forwardRef)(function CameraView({ device, flash
             // `outputOrientation="device"` rotates the pixels to match
             // how the user is holding the phone, so the saved JPEG is
             // "what you see is what was taken".
-            outputOrientation: "device", torch: flash === 'on' ? 'on' : 'off', onError: handleVcError, ...cameraProps }),
+            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 }),
         guidance ? (react_1.default.createElement(react_native_1.View, { style: styles.guidance, pointerEvents: "none", accessible: true, accessibilityRole: "text" },
             react_1.default.createElement(react_native_1.Text, { style: styles.guidanceText, numberOfLines: 2 }, guidance))) : null));
 });
@@ -115,6 +233,16 @@ const styles = react_native_1.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/ios/Sources/RNImageStitcher/RNSARCameraView.swift

@@ -54,7 +54,10 @@ public final class RNSARCameraView: UIView {
 
     private func setupView() {
         arSCNView = ARSCNView(frame: bounds)
-        arSCNView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        // Do NOT set autoresizingMask — we manage the ARSCNView frame
+        // manually in layoutSubviews() to achieve letterboxing.
+        // autoresizingMask would fight that and re-expand the view to
+        // fill our bounds on every Auto Layout pass.
 
         // Bind to the singleton's session.  This is the critical
         // line — without it, ARSCNView would try to create its own
@@ -71,18 +74,84 @@ public final class RNSARCameraView: UIView {
         arSCNView.showsStatistics = false
         arSCNView.automaticallyUpdatesLighting = false
 
-        // Black background while ARKit is initialising so the user
-        // sees a clean frame instead of whatever was there before.
+        // Black background: fills the letterbox bars (the areas of
+        // this view outside ARSCNView's letterboxed sub-rect).
         backgroundColor = .black
         addSubview(arSCNView)
     }
 
     public override func layoutSubviews() {
         super.layoutSubviews()
-        // RN's flexbox can re-bound this view at any time; keep the
-        // ARSCNView locked to our bounds.  autoresizingMask handles
-        // most cases but isn't always enough on rotation transitions.
-        arSCNView.frame = bounds
+        // Letterbox the ARSCNView to show the full camera FOV.
+        //
+        // ARSCNView's internal renderer always uses resizeAspectFill
+        // (fills its view, crops if aspect ratios differ).  If we give
+        // it our full bounds (portrait 9:21) and the camera image is
+        // effectively portrait 3:4 (4:3 sensor rotated for device
+        // orientation), it crops ~19% off each horizontal edge —
+        // exactly the "viewport ≠ captured frame" bug.
+        //
+        // Fix: set ARSCNView's frame to the largest rect inside our
+        // bounds that has the camera's content aspect ratio.  When
+        // ARSCNView fills a same-AR sub-rect, there is nothing to crop
+        // and the user sees the full captured scene.  The parent view's
+        // black background fills the remainder.
+        arSCNView.frame = letterboxedFrame()
+    }
+
+    /// Returns the largest `CGRect` inside `bounds` that matches the
+    /// camera's content aspect ratio (accounting for device orientation),
+    /// centred within `bounds`.
+    private func letterboxedFrame() -> CGRect {
+        let aspect = cameraContentAspect()
+        let bw = bounds.width
+        let bh = bounds.height
+        guard bw > 0, bh > 0, aspect > 0 else { return bounds }
+
+        // Try fitting by width first; if height overflows, fit by height.
+        let hByWidth = bw / aspect
+        if hByWidth <= bh {
+            // Content fits within height — horizontal bars top+bottom.
+            let y = (bh - hByWidth) / 2
+            return CGRect(x: 0, y: y, width: bw, height: hByWidth)
+        } else {
+            // Vertical bars left+right.
+            let wByHeight = bh * aspect
+            let x = (bw - wByHeight) / 2
+            return CGRect(x: x, y: 0, width: wByHeight, height: bh)
+        }
+    }
+
+    /// Camera content aspect ratio (W÷H) in the current device orientation.
+    ///
+    /// The ARKit sensor is physically landscape (e.g. 1920 × 1440, aspect 4/3).
+    /// When the device is portrait the ARSCNView displays the scene rotated,
+    /// so the effective content aspect is 3/4.  We invert accordingly so the
+    /// letterboxed frame always reflects what the user is actually looking at.
+    ///
+    /// Source priority:
+    ///   1. `currentFrame.camera.imageResolution` — live, most accurate.
+    ///   2. Active session config's `videoFormat.imageResolution` — stable
+    ///      after `arSession.run(…)` and before the first frame.
+    ///   3. 4:3 hardcoded fallback — correct for every iPhone ARKit camera.
+    private func cameraContentAspect() -> CGFloat {
+        let rawResolution: CGSize? = {
+            if let res = RNSARSession.shared.arSession.currentFrame?.camera.imageResolution {
+                return CGSize(width: res.width, height: res.height)
+            }
+            if let fmt = (RNSARSession.shared.arSession.configuration as? ARWorldTrackingConfiguration)?.videoFormat {
+                return CGSize(width: fmt.imageResolution.width, height: fmt.imageResolution.height)
+            }
+            return nil
+        }()
+
+        // Raw sensor aspect (always landscape > 1 for iPhone cameras).
+        let sensorAspect: CGFloat = rawResolution.map { $0.width / $0.height } ?? (4.0 / 3.0)
+
+        // In portrait mode (view taller than wide) the displayed scene
+        // is effectively portrait → invert the sensor aspect.
+        let deviceIsPortrait = bounds.height > bounds.width
+        return deviceIsPortrait ? (1.0 / sensorAspect) : sensorAspect
     }
 
     public override func didMoveToWindow() {
@@ -99,6 +168,12 @@ public final class RNSARCameraView: UIView {
             if !RNSARSession.shared.isRunning {
                 RNSARSession.shared.start()
             }
+            // Re-layout after session start: the configuration's
+            // videoFormat (and shortly after, currentFrame) are now
+            // available for a more accurate aspect ratio.  On iOS all
+            // ARKit cameras are 4:3 so this is a no-op in practice,
+            // but it keeps the code correct for future configs.
+            setNeedsLayout()
         } else {
             // Removed from window — stop the session.  Don't clear
             // the pose log here; the host explicitly clears between

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-image-stitcher",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Pose-aware panorama capture + stitching for React Native. One <Camera> component, both tap-to-photo and hold-to-pan modes, both AR-backed and IMU-fallback capture paths.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/camera/Camera.tsx

@@ -899,7 +899,7 @@ function extractPanoramaOverrides(props: CameraProps): PanoramaPropOverrides {
  */
 export function Camera(props: CameraProps): React.JSX.Element {
   const {
-    defaultCaptureSource = 'ar',
+    defaultCaptureSource = 'non-ar',
     defaultLens = '1x',
     captureSources = 'both',
     enablePhotoMode = true,

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,77 @@ 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.
+  //
+  // Resolution preference matters too: filtering on aspect ALONE lets
+  // vision-camera settle on whatever 4:3 format sorts first — observed as
+  // a 192×144 VIDEO stream on the iPhone 16 Pro (the photo still uses the
+  // format's full-res photo dims, so you'd get a sharp capture behind a
+  // mush preview).  So we also request the highest video resolution.
+  //
+  // Why `'max'` and not a bounded target like 1920×1440?  We tried the
+  // bounded target and it FAILED on the iPhone 16 Pro: the nearest
+  // 1920×1440 format is a 10-bit format (pixel formats x420 / x422 only —
+  // and it is NOT flagged HDR, so the `videoHdr` filter can't dodge it).
+  // The frame processor + the stitcher's CV pipeline need 8-bit
+  // `420v`/`420f`, so vision-camera raises
+  // `device/pixel-format-not-supported` and silently falls back to a
+  // default pixel format — breaking non-AR stitching.  vision-camera does
+  // NOT expose a format's supported pixel formats to JS (no
+  // `pixelFormats` field; `FormatFilter` has no pixel-format key), so we
+  // can't select an 8-bit format by inspection.  Empirically the device's
+  // MAX 4:3 video format is 8-bit (420v/420f) on the iPhone 16 Pro, and
+  // Android formats are near-universally 8-bit YUV_420_888, so `'max'` is
+  // the robust choice: a sharp preview on a frame-processor-compatible
+  // pipeline.  Trade-off: the max format tends to run at 30 fps (fine for
+  // hold-to-pan) and feeds full-res frames to the non-AR gate — if that
+  // ever shows up as dropped frames we can downscale for the gate
+  // 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 } },
+  ]);
+
+  // 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 +232,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 +287,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 +326,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,