react-native-image-stitcher 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -16,6 +16,201 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-23
+
+### v0.4 settings revamp (F10)
+
+> [!WARNING]
+> **Breaking type change.**  The flat 45-field `PanoramaSettings`
+> interface from v0.3 has been replaced with three engine-discriminated
+> hierarchical types (`PanoramaSettings`, `SlitscanSettings`,
+> `HybridSettings`).  Consumers passing custom settings literals to
+> `<Camera>` or to a Layer 2 modal must migrate to the new shape; the
+> v0.3 type is deleted, not aliased.  The C++ engine wire format is
+> unchanged — only the JS-side type surface moved.
+>
+> **Migration guide:** [`docs/migrations/v0.3-to-v0.4-panorama-settings.md`](docs/migrations/v0.3-to-v0.4-panorama-settings.md)
+> walks through every recipe (default-only hosts, custom-literal
+> hosts, slit-scan / hybrid hosts, storage migration for persisted
+> settings).
+
+#### Why
+
+The 2026-05-22 audit (entry below in v0.3.0) traced every
+`PanoramaSettings` field's native consumer and proved the flat type
+mixed three engines' (batch-keyframe, slit-scan, hybrid) settings into
+one bag of disjoint subsets.  Hosts had no way to know at the type
+level which settings their chosen engine would even read; the modal
+exposed knobs that were silently ignored on the active engine.  The
+revamp splits the type along engine boundaries so the types match what
+each engine actually consumes.
+
+#### What changed
+
+- **New file:** `src/camera/PanoramaSettings.ts` — `CaptureBaseSettings`
+  + three top-level types (`PanoramaSettings`, `SlitscanSettings`,
+  `HybridSettings`), each with co-located `DEFAULT_*_SETTINGS`.  Sub-trees
+  group related knobs: `stitcher` / `frameSelection.flow` (panorama);
+  `painting` / `registration.ncc1d` / `registration.ncc2d.emaSmoothing` /
+  `registration.ncc2d.panAxisLock` / `plane` / `advanced` (slitscan).
+- **New file:** `src/camera/PanoramaSettingsBridge.ts` — three pure
+  adapter functions (`panoramaSettingsToNativeConfig`,
+  `slitscanSettingsToNativeConfig`, `hybridSettingsToNativeConfig`)
+  that translate the typed JS tree → the flat
+  `Record<string, primitive>` the native bridges consume.  Handles
+  presence-as-enable (`ncc1d` defined ⇒ `enable1dNcc: true` on the
+  wire) and source-conditional plane optionals.
+- **New file:** `src/camera/buildPanoramaInitialSettings.ts` — pure
+  helper that translates `<Camera>`'s `default*` props into the
+  initial `PanoramaSettings` snapshot.  Takes the device's low-mem
+  classification as an argument so the function stays pure and
+  testable.
+- **Rewritten:** `src/camera/PanoramaSettingsModal.tsx` — now consumes
+  the new `PanoramaSettings` shape.  UI sections mirror the type tree
+  (Capture source, Debug, Stitcher accordion, Frame Selection
+  accordion with nested Flow tunables).  ~600 LOC smaller than v0.3
+  because dead slit-scan / hybrid / video-recording fields are gone.
+- **Rewired:** `src/camera/Camera.tsx` — settings state uses the new
+  type; `incremental.start({ config })` now passes
+  `panoramaSettingsToNativeConfig(settings)` instead of an inline flat
+  dict.  IMU translation gate reads
+  `settings.frameSelection.flow?.maxTranslationCm`.  Debug overlay
+  reads `settings.frameSelection.mode` + `settings.stitcher.stitchMode`.
+- **Updated:** `src/index.ts` — exports the new types + adapters; drops
+  the deleted v0.3 type.
+- **Test infra:** added `jest` + `ts-jest` + `@types/jest` devDeps; new
+  `jest.config.js`, `tsconfig.test.json`, `tsconfig.build.json` (the
+  latter excludes `__tests__/` from the shipped `dist/`).  19 tests
+  across two suites cover the bridge round-trips, presence-as-enable
+  cases, plane-source variants, and prop→settings-tree translation.
+
+#### Migration table — v0.3 flat → v0.4 hierarchical
+
+For `<Camera>`-consuming hosts (the only public path that took
+`PanoramaSettings` in v0.3):
+
+| v0.3 field                       | v0.4 path                                       |
+|----------------------------------|-------------------------------------------------|
+| `captureSource`                  | `captureSource` (unchanged)                     |
+| `debug`                          | `debug` (unchanged)                             |
+| `stitchMode`                     | `stitcher.stitchMode`                           |
+| `warperType`                     | `stitcher.warperType`                           |
+| `blenderType`                    | `stitcher.blenderType`                          |
+| `seamFinderType`                 | `stitcher.seamFinderType`                       |
+| `enableMaxInscribedRectCrop`     | `stitcher.enableMaxInscribedRectCrop`           |
+| `frameSelectionMode`             | `frameSelection.mode`                           |
+| `keyframeMaxCount`               | `frameSelection.maxKeyframes`                   |
+| `keyframeOverlapThreshold`       | `frameSelection.overlapThreshold`               |
+| `flowNoveltyPercentile`          | `frameSelection.flow.noveltyPercentile`         |
+| `flowEvalEveryNFrames`           | `frameSelection.flow.evalEveryNFrames`          |
+| `flowMaxTranslationCm`           | `frameSelection.flow.maxTranslationCm`          |
+| `flowMaxCorners`                 | `frameSelection.flow.maxCorners`                |
+| `flowQualityLevel`               | `frameSelection.flow.qualityLevel`              |
+| `flowMinDistance`                | `frameSelection.flow.minDistance`               |
+
+#### Deleted from the public type surface
+
+These fields were consumed only by slit-scan or hybrid engines (or
+not consumed at all per the audit) and were dead surface on
+`<Camera>`'s batch-keyframe path:
+
+- `incrementalEngine` — `<Camera>` always uses `batch-keyframe`; the
+  knob never reached this component.  Hosts that want slit-scan or
+  hybrid build their own capture flow on `incremental.start()` and
+  pass `SlitscanSettings` / `HybridSettings` instead.
+- `useARPreview` — superseded by `captureSource` ('ar' / 'non-ar').
+- `useDetectedPlane` — superseded by `SlitscanSettings.plane.source`.
+- `planeSource`, `virtualPlaneDepthMeters`, `arkitPlaneAlignmentThreshold`,
+  `planeProjectionStyle` — slit-scan only; on `SlitscanSettings.plane.*`.
+- `slitWidthFraction`, `sliverPosition`, `firstFrameFullFrame`,
+  `paintMode` — slit-scan only; on `SlitscanSettings.painting.*`.
+- `acceptGate`, `enableTriangulation`, `enableTriAccumulator`,
+  `enable2dNcc`, `enableRansacHomography`, `nccSearchRadius1d`,
+  `nccSearchMargin2d`, `nccConfidenceThreshold2d`,
+  `enableNcc2dEmaSmoothing`, `ncc2dEmaAlpha`,
+  `enableNcc2dPanAxisLock`, `ncc2dCrossAxisLockPx` — slit-scan only;
+  on `SlitscanSettings.registration.*`.
+- `hybridProjection` — hybrid only; on `HybridSettings.projection`.
+- `maxRecordingMs`, `framesPerSecond`, `minFrames`, `maxFrames`,
+  `quality` — historical video-recording fallback fields with no
+  consumer on `<Camera>`'s batch-keyframe path.
+
+#### Latent v0.3 bug fixed in passing
+
+The v0.3 `<Camera>` accepted a `defaultCaptureSource` prop but the
+internal `buildInitialSettings` function never copied it into
+`settings.captureSource` — only into `arPreference` state.  The
+discrepancy meant the wire dict sent to native always reported
+`captureSource: 'ar'` even when the operator's effective source was
+`'non-ar'`, which silently disabled Android's `disableAngularFallback`
+opt-out (audit fix F1).  v0.4's `extractPanoramaOverrides` +
+`buildPanoramaInitialSettings` route the prop through correctly.
+Hosts using `defaultCaptureSource="non-ar"` will see native receive
+the matching value for the first time.
+
+#### Known limitation — modal Capture-source field vs. AR toggle
+
+The on-screen AR toggle button at the bottom of `<Camera>` updates
+`arPreference` state (and through it `effectiveCaptureSource`),
+which decides which preview component mounts.  The Capture-source
+segmented control inside the settings modal updates
+`settings.captureSource`, which only affects what's reported to the
+native engine via `panoramaSettingsToNativeConfig` (gates Android's
+angular-fallback opt-out per audit fix F1).  These two values can
+drift if the operator toggles the AR button without re-opening
+settings, OR flips the modal field without touching the AR button.
+The on-screen toggle is the canonical UI affordance for the live
+preview path; the modal field is best thought of as a tester escape
+hatch for the wire-format consequence.  A future cleanup is to make
+both update the same source of truth — out of scope for v0.4.
+
+#### Migration example
+
+```ts
+// Before (v0.3)
+const settings: PanoramaSettings = {
+  captureSource: 'ar',
+  stitchMode: 'auto',
+  blenderType: 'multiband',
+  flowMaxTranslationCm: 50,
+  flowNoveltyPercentile: 0.85,
+  keyframeMaxCount: 6,
+  frameSelectionMode: 'flow-based',
+  // … 40+ more fields
+};
+
+// After (v0.4)
+const settings: PanoramaSettings = {
+  captureSource: 'ar',
+  debug: false,
+  stitcher: {
+    stitchMode: 'auto',
+    warperType: 'plane',
+    blenderType: 'multiband',
+    seamFinderType: 'graphcut',
+    enableMaxInscribedRectCrop: false,
+  },
+  frameSelection: {
+    mode: 'flow-based',
+    maxKeyframes: 6,
+    overlapThreshold: 0.20,
+    flow: {
+      noveltyPercentile: 0.85,
+      evalEveryNFrames: 5,
+      maxTranslationCm: 50,
+      maxCorners: 150,
+      qualityLevel: 0.01,
+      minDistance: 10,
+    },
+  },
+};
+
+// Or just use the default:
+import { DEFAULT_PANORAMA_SETTINGS } from 'react-native-image-stitcher';
+const settings = { ...DEFAULT_PANORAMA_SETTINGS, captureSource: 'non-ar' };
+```
+
+
 ## [0.3.0] — 2026-05-23
 
 > [!IMPORTANT]

package/dist/camera/Camera.js

@@ -90,7 +90,10 @@ const CaptureKeyframePill_1 = require("./CaptureKeyframePill");
 const CaptureOrientationPill_1 = require("./CaptureOrientationPill");
 const CaptureStitchStatsToast_1 = require("./CaptureStitchStatsToast");
 const PanoramaBandOverlay_1 = require("./PanoramaBandOverlay");
+const PanoramaSettingsBridge_1 = require("./PanoramaSettingsBridge");
 const PanoramaSettingsModal_1 = require("./PanoramaSettingsModal");
+const buildPanoramaInitialSettings_1 = require("./buildPanoramaInitialSettings");
+const lowMemDevice_1 = require("./lowMemDevice");
 const useCapture_1 = require("./useCapture");
 const useDeviceOrientation_1 = require("./useDeviceOrientation");
 const incremental_1 = require("../stitching/incremental");
@@ -228,32 +231,31 @@ function deriveEffectiveCaptureSource(arPreference, lens, isARSupportedOnDevice)
     return arPreference ? 'ar' : 'non-ar';
 }
 /**
- * Apply per-prop defaults to build the initial settings snapshot.
- * The settings live in component state from there; the prop values
- * never re-flow.
+ * Pluck the props that influence the initial PanoramaSettings tree.
+ * Kept inline (vs. a wide structural type) so future Camera prop
+ * additions don't accidentally widen the settings-translation
+ * surface — the pure builder in `./buildPanoramaInitialSettings.ts`
+ * has the canonical interface; this just forwards the relevant
+ * fields.
  *
- * Note: the `default*ResolMP` props don't have a home on PanoramaSettings
- * yet — they're accepted on the prop interface for forward compatibility
- * but ignored here.  Wiring is a follow-up once PanoramaSettings is
- * extended.
+ * The `default*ResolMP` props on `CameraProps` are documented as
+ * forward-looking no-ops; the new PanoramaSettings tree has no home
+ * for them yet (the v0.3 audit found cv::Stitcher's resol knobs
+ * aren't reached by either platform's bridge).  They're accepted on
+ * the prop interface for API stability and ignored here.
  */
-function buildInitialSettings(props) {
+function extractPanoramaOverrides(props) {
     return {
-        ...PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS,
-        stitchMode: props.defaultStitchMode ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.stitchMode,
-        blenderType: props.defaultBlender ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.blenderType,
-        seamFinderType: props.defaultSeamFinder ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.seamFinderType,
-        warperType: props.defaultWarper ?? PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.warperType,
-        flowNoveltyPercentile: props.defaultFlowNoveltyPercentile ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowNoveltyPercentile,
-        flowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowEvalEveryNFrames,
-        flowMaxTranslationCm: props.defaultFlowMaxTranslationCm ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm,
-        keyframeMaxCount: props.defaultKeyframeMaxCount ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeMaxCount,
-        keyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold ??
-            PanoramaSettingsModal_1.DEFAULT_PANORAMA_SETTINGS.keyframeOverlapThreshold,
+        defaultCaptureSource: props.defaultCaptureSource,
+        defaultStitchMode: props.defaultStitchMode,
+        defaultBlender: props.defaultBlender,
+        defaultSeamFinder: props.defaultSeamFinder,
+        defaultWarper: props.defaultWarper,
+        defaultFlowNoveltyPercentile: props.defaultFlowNoveltyPercentile,
+        defaultFlowEvalEveryNFrames: props.defaultFlowEvalEveryNFrames,
+        defaultFlowMaxTranslationCm: props.defaultFlowMaxTranslationCm,
+        defaultKeyframeMaxCount: props.defaultKeyframeMaxCount,
+        defaultKeyframeOverlapThreshold: props.defaultKeyframeOverlapThreshold,
     };
 }
 // `toFileUri` (used to be an inline `toFileUri` here) lives in
@@ -273,7 +275,7 @@ function Camera(props) {
     // ── State ───────────────────────────────────────────────────────
     const [arPreference, setArPreference] = (0, react_1.useState)(defaultCaptureSource === 'ar');
     const [lens, setLens] = (0, react_1.useState)(defaultLens);
-    const [settings, setSettings] = (0, react_1.useState)(() => buildInitialSettings(props));
+    const [settings, setSettings] = (0, react_1.useState)(() => (0, buildPanoramaInitialSettings_1.buildPanoramaInitialSettings)(extractPanoramaOverrides(props), (0, lowMemDevice_1.isLowMemDevice)()));
     const [settingsModalVisible, setSettingsModalVisible] = (0, react_1.useState)(false);
     const [statusPhase, setStatusPhase] = (0, react_1.useState)('idle');
     const [recordingStartedAt, setRecordingStartedAt] = (0, react_1.useState)(null);
@@ -399,11 +401,16 @@ function Camera(props) {
     // |residual|` — which undercounted any time a non-IMU accept
     // (flow novelty, force-last) reset the integrator before the
     // budget threshold was reached.
+    // The translation budget lives at `frameSelection.flow.maxTranslationCm`
+    // in the new hierarchical settings shape.  When `flow` is undefined
+    // (the consumer opted out of the flow strategy entirely), the gate
+    // stays disabled — same observable behaviour as v0.3's `0` default.
+    const flowMaxTranslationCm = settings.frameSelection.flow?.maxTranslationCm ?? 0;
     const imuGate = (0, useIMUTranslationGate_1.useIMUTranslationGate)({
         enabled: isNonAR
             && statusPhase === 'recording'
-            && settings.flowMaxTranslationCm > 0,
-        budgetMeters: Math.max(0.001, settings.flowMaxTranslationCm / 100.0),
+            && flowMaxTranslationCm > 0,
+        budgetMeters: Math.max(0.001, flowMaxTranslationCm / 100.0),
         onBudgetExceeded: () => {
             const mod = (0, incremental_1.getIncrementalNativeModule)();
             mod?.markNextFrameAsLastKeyframe?.().catch(() => undefined);
@@ -578,6 +585,25 @@ function Camera(props) {
             const orientationRotation = deviceOrientation === 'portrait' ? 90
                 : deviceOrientation === 'portrait-upside-down' ? 270
                     : 0;
+            // v0.4 — the inline-flat config dict that v0.3 maintained here
+            // moved into `panoramaSettingsToNativeConfig` (see
+            // PanoramaSettingsBridge.ts).  That adapter is the single source
+            // of truth for the JS→native wire format; both this call site
+            // AND the modal's reset-to-defaults preview agree on the same
+            // mapping.  Audit fixes F1 / F4 / F6 from v0.3 are now properties
+            // of the bridge (verified by the unit tests in
+            // src/camera/__tests__/PanoramaSettingsBridge.test.ts).
+            //
+            // 2026-05-23 — override `captureSource` with the runtime-derived
+            // `effectiveCaptureSource` (from `arPreference + lens +
+            // AR-device-support`).  Pre-this change the camera-screen AR
+            // toggle wrote ONLY to local `arPreference` state while the
+            // bridge read `settings.captureSource` — so native could think
+            // the capture was AR while the operator had toggled it off (or
+            // vice-versa).  Single source of truth now: whatever camera the
+            // operator can see is what native is told it is.  The settings
+            // modal's `captureSource` control has been removed for the same
+            // reason — see PanoramaSettingsModal.tsx for the rationale.
             await incremental.start({
                 snapshotJpegQuality: 75,
                 snapshotEveryNAccepts: 1,
@@ -589,37 +615,10 @@ function Camera(props) {
                 canvasWidth: 5000,
                 canvasHeight: 5000,
                 engine: 'batch-keyframe',
-                config: {
-                    // ── cv::Stitcher (batch finalize) ─────────────────────────
-                    stitchMode: settings.stitchMode,
-                    warperType: settings.warperType,
-                    blenderType: settings.blenderType,
-                    seamFinderType: settings.seamFinderType,
-                    enableMaxInscribedRectCrop: settings.enableMaxInscribedRectCrop,
-                    // ── KeyframeGate (per-frame selection) ────────────────────
-                    // F6 audit fix: pass settings.frameSelectionMode through
-                    // instead of hardcoding 'flow-based' (which silently made the
-                    // time-based / pose-based modal options no-ops).
-                    frameSelectionMode: settings.frameSelectionMode,
-                    keyframeMaxCount: settings.keyframeMaxCount,
-                    keyframeOverlapThreshold: settings.keyframeOverlapThreshold,
-                    // ── Flow-strategy tunables ────────────────────────────────
-                    // F4 audit fix: previously omitted, which made the modal
-                    // sliders for these three a complete no-op (only iOS native
-                    // even read them, and only when JS sent them).
-                    flowNoveltyPercentile: settings.flowNoveltyPercentile,
-                    flowEvalEveryNFrames: settings.flowEvalEveryNFrames,
-                    flowMaxTranslationCm: settings.flowMaxTranslationCm,
-                    flowMaxCorners: settings.flowMaxCorners,
-                    flowQualityLevel: settings.flowQualityLevel,
-                    flowMinDistance: settings.flowMinDistance,
-                    // ── Engine-routing flags consumed by native ───────────────
-                    // F1 audit fix: Android keyframe gate's disableAngularFallback
-                    // opt-out reads this to decide whether to skip the angular
-                    // fallback (gyro pose is too noisy for the FoV-overlap calc
-                    // in non-AR mode, causing degenerate cv::Stitcher params).
-                    captureSource: settings.captureSource,
-                },
+                config: (0, PanoramaSettingsBridge_1.panoramaSettingsToNativeConfig)({
+                    ...settings,
+                    captureSource: effectiveCaptureSource,
+                }),
             });
             imuGate.resetAnchor();
             // Start pumping vision-camera snapshots into the engine for
@@ -642,6 +641,7 @@ function Camera(props) {
         isNonAR,
         deviceOrientation,
         settings,
+        effectiveCaptureSource,
         imuGate,
         jsDriver,
         onError,
@@ -723,6 +723,18 @@ function Camera(props) {
         onError,
         recordingStartedAt,
         jsDriver,
+        // F10 Phase 2 review N1 — these four were missing pre-fix.  The
+        // callback reads `settings.debug` (to gate the stitchToast),
+        // `isNonAR` (to decide whether to read IMU totalAbs translation),
+        // `imuGate` (the read itself), and `stitchToast` (the toast hook
+        // object).  If any of those identities change between the user
+        // pressing-and-holding the shutter and the release, the stale-
+        // closure read could disagree with the actual current state.
+        // Pre-existing v0.3 bug; v0.4 was the natural time to address it.
+        settings,
+        isNonAR,
+        imuGate,
+        stitchToast,
     ]);
     // ── Lens / AR-toggle handlers ───────────────────────────────────
     const handleLensChange = (0, react_1.useCallback)((next) => {
@@ -749,7 +761,7 @@ function Camera(props) {
             react_1.default.createElement(CaptureOrientationPill_1.CaptureOrientationPill, { orientation: deviceOrientation, topInset: insets.top }),
             react_1.default.createElement(CaptureKeyframePill_1.CaptureKeyframePill, { state: incrementalState, topInset: insets.top }),
             react_1.default.createElement(CaptureMemoryPill_1.CaptureMemoryPill, { topInset: insets.top }),
-            react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelectionMode, stitchMode: settings.stitchMode }))),
+            react_1.default.createElement(CaptureDebugOverlay_1.CaptureDebugOverlay, { incrementalState: incrementalState, imuTranslationMetres: isNonAR ? imuGate.getTranslationMetres() : null, captureSource: effectiveCaptureSource, frameSelectionMode: settings.frameSelection.mode, stitchMode: settings.stitcher.stitchMode }))),
         react_1.default.createElement(CaptureStitchStatsToast_1.CaptureStitchStatsToast, { message: stitchToast.message, topInset: insets.top }),
         showSettingsButton && (react_1.default.createElement(SettingsButton, { topInset: insets.top, onPress: () => setSettingsModalVisible(true) })),
         react_1.default.createElement(react_native_1.View, { pointerEvents: "box-none", style: [styles.bottomArea, { paddingBottom: insets.bottom + 12 }] },