react-native-image-stitcher 0.14.1 → 0.15.0

package/ios/Sources/RNImageStitcher/OpenCVIncrementalStitcher.mm

@@ -1,1328 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// OpenCVIncrementalStitcher.mm
-//
-// See OpenCVIncrementalStitcher.h for the API contract.
-//
-// Algorithm summary (per addPixelBuffer call):
-//   1. Lock + read NV12 planes from CVPixelBuffer
-//   2. Convert + downscale to compose-size BGR cv::Mat
-//   3. Pose-delta gate: skip if overlap > maxOverlap or < minOverlap
-//   4. ORB.detectAndCompute (1000 features cap)
-//   5. BFMatcher.knnMatch + Lowe's ratio test (0.75)
-//   6. cv::findHomography(src=newPts, dst=lastPts, RANSAC, 5.0)
-//   7. Inlier ratio + match count + det(H) → confidence
-//   8. Compose worldH = lastFrameToWorldH * H_newToLast
-//   9. warpPerspective + distance-transform feather blend onto canvas
-//   10. Update state: lastFrameToWorldH, lastDescriptors, lastKeypoints,
-//       lastAcceptedYaw/Pitch, acceptedCount++
-//
-// What this file deliberately does NOT do:
-//   - Bundle adjustment.  We accumulate pair-wise homography only;
-//     drift is accepted as the trade for live preview + Android parity
-//     (the Android prebuilt OpenCV ships without `cv::Stitcher`'s BA
-//     helpers).  Long-pan drift is documented as future work in the
-//     design doc's open questions.
-//   - Multi-band blending.  Same Android-parity reason.  Distance-
-//     transform feather over a 20px band gives clean-enough seams for
-//     live preview; a final-pass MultiBand is possible at finalize
-//     time on iOS only if drift becomes the dominant artefact.
-//   - Exposure compensation.  Auto-exposure on the camera handles
-//     gross brightness changes; the feather hides residual mismatches.
-
-// OpenCV's stitching headers contain `enum { NO, ... }` and `enum { YES, ... }`
-// declarations.  Objective-C's `<objc/objc.h>` (transitively imported by every
-// Cocoapods prefix.pch) #defines `NO` and `YES` as boolean macros — by the
-// time OpenCV's enums are parsed, the preprocessor has already eaten those
-// identifiers and the build dies with "expected identifier".  Undef both
-// BEFORE importing opencv2/*; restore after.  Same pattern as OpenCVStitcher.mm.
-#ifdef NO
-#undef NO
-#endif
-#ifdef YES
-#undef YES
-#endif
-
-#import <opencv2/opencv.hpp>
-#import <opencv2/core.hpp>
-#import <opencv2/imgproc.hpp>
-#import <opencv2/imgcodecs.hpp>
-#import <opencv2/features2d.hpp>
-#import <opencv2/calib3d.hpp>
-#import <opencv2/stitching/detail/warpers.hpp>  // V14.0pre — cv::detail::CylindricalWarper
-
-#import <vector>
-#import <chrono>
-
-#define NO  ((BOOL)0)
-#define YES ((BOOL)1)
-
-#import "OpenCVIncrementalStitcher.h"
-
-#import <UIKit/UIKit.h>
-
-NSString *const RNImageStitcherIncrementalErrorDomain =
-    @"RNImageStitcherIncrementalErrorDomain";
-
-// ── Private telemetry result class ──────────────────────────────────
-
-@interface RLISFrameTelemetry ()
-@property (nonatomic, readwrite) RLISFrameOutcome outcome;
-@property (nonatomic, readwrite) double overlapPercent;
-@property (nonatomic, readwrite) NSInteger matchCount;
-@property (nonatomic, readwrite) double inlierRatio;
-@property (nonatomic, readwrite) double confidence;
-@property (nonatomic, readwrite) double processingMs;
-@property (nonatomic, readwrite) BOOL isLandscape;
-// V12.14.9 — see header doc for `paintedExtent` / `panExtent` semantics.
-@property (nonatomic, readwrite) NSInteger paintedExtent;
-@property (nonatomic, readwrite) NSInteger panExtent;
-@end
-
-@implementation RLISFrameTelemetry
-@end
-
-@interface RLISSnapshot ()
-@property (nonatomic, copy, readwrite) NSString *panoramaPath;
-@property (nonatomic, readwrite) NSInteger width;
-@property (nonatomic, readwrite) NSInteger height;
-@property (nonatomic, readwrite) NSInteger acceptedCount;
-@end
-
-@implementation RLISSnapshot
-@end
-
-
-// ── V15 — RLISStitcherConfig ────────────────────────────────────────
-
-@implementation RLISStitcherConfig
-
-+ (instancetype)configForMode:(NSString *)mode {
-    RLISStitcherConfig *c = [[RLISStitcherConfig alloc] init];
-
-    NSString *m = mode ?: @"slitscan-both";
-    // Backward-compat translation.
-    if ([m isEqualToString:@"firstwins-rectilinear"]) {
-        m = @"slitscan-rotate";
-    } else if ([m isEqualToString:@"firstwins"] ||
-               [m isEqualToString:@"firstwins-zoomed"]) {
-        NSLog(@"[V15-config] DEPRECATED engine mode '%@' — falling "
-              @"back to 'slitscan-both'", mode);
-        m = @"slitscan-both";
-    }
-
-    // V15.0d — defaults shared by all engine modes for the new knobs.
-    // Set before the per-mode overrides so per-mode only overrides
-    // the fields that genuinely differ from this baseline.
-    c.nccSearchMargin2d              = 12;     // was hardcoded V15.0c.4
-    // V15.0i.1 — default raised to 0.99.  At 0.75 the NCC was applying
-    // corrections on weak matches in plane-projected mode (Ram observed
-    // mid-capture wobble).  0.99 means we only apply corrections on
-    // near-perfect overlap matches; ambiguous matches are skipped.
-    c.nccConfidenceThreshold2d       = 0.99;
-    c.enableNcc2dEmaSmoothing        = NO;     // 1B opt-in
-    c.ncc2dEmaAlpha                  = 0.4;    // 60% prev / 40% current
-    c.enableNcc2dPanAxisLock         = NO;     // 1C opt-in
-    c.ncc2dCrossAxisLockPx           = 5;
-    c.planeSource                    = RLISPlaneSourceDisabled;
-    c.virtualPlaneDepthMeters        = 1.5;
-    c.arkitPlaneAlignmentThreshold   = 0.6;    // ~53° max off-camera
-    // V15.0g — Rectified is the default since Trapezoidal's
-    // tilt-induced distortion was the field-blocker on V15.0e/f.
-    // Operators can flip back to Trapezoidal for A/B comparison.
-    c.planeProjectionStyle           = RLISPlaneProjectionStyleRectified;
-
-    if ([m isEqualToString:@"hybrid"]) {
-        // n/a slit-shaping; hybrid uses whole-frame projection.
-        c.kPanAxisFractionRect       = 0.30;  // unused for hybrid
-        c.kMinAcceptDeltaPx          = 50;
-        c.enableTriangulation        = NO;
-        c.enableTriAccumulator       = NO;
-        c.enable1dNcc                = NO;
-        c.nccSearchRadius1d          = 15;
-        c.enable2dNcc                = NO;
-        c.enableRansacHomography     = NO;
-        c.paintMode                  = RLISPaintModeFeatherBlend;  // V12.x feather
-        c.hybridProjection           = RLISHybridProjectionPlanar;  // V15: planar default
-        c.useDetectedPlane           = NO;
-        c.sliverPosition             = RLISSliverPositionCenter;
-        c.firstFrameFullFrame        = NO;
-    } else if ([m isEqualToString:@"slitscan-rotate"]) {
-        // V13.0a baseline + 1D NCC.  No tri, no 2D NCC, no homography.
-        c.kPanAxisFractionRect       = 0.30;
-        c.kMinAcceptDeltaPx          = 0;     // accept on every frame
-        c.enableTriangulation        = NO;
-        c.enableTriAccumulator       = NO;
-        c.enable1dNcc                = YES;   // wobble correction
-        c.nccSearchRadius1d          = 15;
-        c.enable2dNcc                = NO;
-        c.enableRansacHomography     = NO;
-        c.paintMode                  = RLISPaintModeFirstPaintedWins;
-        c.hybridProjection           = RLISHybridProjectionPlanar;  // unused
-        c.useDetectedPlane           = NO;
-        c.sliverPosition             = RLISSliverPositionCenter;
-        c.firstFrameFullFrame        = NO;
-    } else {
-        // slitscan-both (V15.0c default).  V13.0a baseline + no gate +
-        // first-painted-wins (Ram observation: feather often introduces
-        // ghosting; first-painted-wins is consistently the best for our
-        // typical retail fixture pans).  Iterate via settings UI:
-        // enable tri / 2D NCC / RANSAC as needed.
-        c.kPanAxisFractionRect       = 0.30;
-        c.kMinAcceptDeltaPx          = 0;     // accept on every frame
-        c.enableTriangulation        = NO;
-        c.enableTriAccumulator       = NO;
-        c.enable1dNcc                = NO;
-        c.nccSearchRadius1d          = 15;
-        c.enable2dNcc                = NO;
-        c.enableRansacHomography     = NO;
-        c.paintMode                  = RLISPaintModeFirstPaintedWins;  // V15.0c default
-        c.hybridProjection           = RLISHybridProjectionPlanar;  // unused
-        c.useDetectedPlane           = NO;
-        c.sliverPosition             = RLISSliverPositionCenter;
-        c.firstFrameFullFrame        = NO;
-    }
-
-    return c;
-}
-
-@end
-
-
-// ── Acceptance thresholds ───────────────────────────────────────────
-//
-// All values empirical seeds from the design doc.  Documented here
-// alongside the code so a tuning pass during field testing can adjust
-// them without hunting through the .h.
-
-namespace {
-
-// FoV gate window — slightly more permissive than the design doc's
-// 30-50% sweet spot to handle pose noise + slow pans without
-// rejecting valid candidates.
-constexpr double kMinOverlapPct = 10.0;   // below this → moved too far
-constexpr double kMaxOverlapPct = 75.0;   // above this → too close, wait
-// Match-quality gates — relaxed from the design doc seeds because
-// shelf scenes with light textures (white walls behind shelves,
-// uniform packaging) produce fewer matches than the 80-feature
-// "ideal".  Field tuning in v3.
-constexpr int kMinMatchesAccept = 10;
-constexpr double kMinInlierRatioAccept = 0.18;
-constexpr double kHighConfidenceMatches = 60;
-constexpr double kHighConfidenceInlierRatio = 0.55;
-constexpr int kOrbMaxFeatures = 1000;
-constexpr float kLoweRatio = 0.75f;
-constexpr double kRansacReprojThresh = 5.0;
-// Similarity (4-DOF: scale, rotation, tx, ty) keeps the determinant
-// equal to scale².  Tight bounds reject degenerate fits aggressively
-// while leaving slack for the natural ~0.9-1.1 scale that hand-held
-// pans introduce (parallax + lens distortion residuals).
-// V11 Gap #30: deleted dead kHomDetMin/kHomDetMax — pose-driven path
-// doesn't fit a homography, so the determinant bounds were dead.
-
-}  // namespace
-
-// ── Engine impl ─────────────────────────────────────────────────────
-
-@implementation OpenCVIncrementalStitcher {
-    NSInteger _composeWidth;
-    NSInteger _composeHeight;
-    NSInteger _canvasWidth;
-    NSInteger _canvasHeight;
-    NSInteger _featherPx;
-    NSInteger _frameRotationDegrees;
-    /// V12.3 orientation-aware cylinder axis.  Derived from
-    /// frameRotationDegrees: 0/180 → landscape (axis = pan_X,
-    /// transverse cylinder; pan direction is vertical world); 90/270 →
-    /// portrait (axis = pan_Y, vertical-axis cylinder; pan direction
-    /// is horizontal world).  Apple's pano follows the same rule:
-    /// pan along the device's longer side, projection wraps around
-    /// the shorter side.
-    BOOL _isLandscape;
-
-    cv::Mat _canvas;       // CV_8UC3 BGR — the running panorama
-    cv::Mat _canvasMask;   // CV_8UC1 — 255 where canvas has been written
-
-    /// V9 pose-driven state — hand-rolled cylindrical projection.
-    /// Replaces v7's planar `H = K · R · K⁻¹` with cylindrical
-    /// remap into a gravity-aligned panorama frame.  The panorama
-    /// frame is defined at first-frame time:
-    ///   +Y = world-gravity-up (cylinder axis is vertical)
-    ///   +Z = horizontal projection of first camera's forward
-    ///        (theta=0 sits at first frame's centre; no wraparound)
-    ///   +X = +Y × +Z (right-handed)
-    /// This avoids the v8 bug where cv::detail::CylindricalWarper
-    /// placed the cylinder seam directly in front of the camera.
-    cv::Mat _firstRotationArkit;  // 3x3 CV_64F, ARKit camera-to-world
-    cv::Mat _K_compose;           // 3x3 CV_64F, intrinsics scaled to compose dims
-    cv::Mat _M_arkitToCv;         // diag(1, -1, -1) basis flip
-    cv::Mat _T_canvas;            // (legacy from v7; unused in v9)
-    cv::Mat _R_panToWorld;        // 3x3 CV_64F, panorama-to-world (cached at first frame)
-    double  _focalCompose;        // cylinder radius in compose pixels
-    int     _canvasOriginCylX;    // canvas (0,0) in cylindrical pixel space (origin offset)
-    int     _canvasOriginCylY;
-    /// V11 Gap #5: last-accepted rotation matrix (ARKit cam-to-world).
-    /// The pose-delta gate computes the relative rotation between
-    /// frames in SENSOR FRAME (axes fixed to the device hardware),
-    /// not in world frame.  World-frame yaw/pitch were being compared
-    /// against camera-frame FoV, which broke landscape pitch pans
-    /// (the dominant pan axis is rotation about world-Y, but in
-    /// landscape the sensor sees that as pitch-equivalent motion).
-    cv::Mat _lastAcceptedR;
-
-    double _lastAcceptedYaw;
-    double _lastAcceptedPitch;
-    bool _hasFirstFrame;
-
-    NSInteger _accepted;
-    /// Monotonic snapshot sequence — used to mint a unique path per
-    /// live snapshot.  RN's <Image> caches `file://` URIs by path
-    /// alone and ignores cache-bust query strings, so writing to the
-    /// SAME path each accept made the live preview show the FIRST
-    /// frame forever.  Bumping the path each snapshot side-steps
-    /// the cache.
-    NSInteger _snapshotSeq;
-
-    /// V15 — runtime config controlling projection (cylindrical vs
-    /// planar) and other hybrid-specific knobs.  Set via -setConfig:
-    /// after init; defaults to hybrid factory config (planar) if
-    /// never set.
-    RLISStitcherConfig *_config;
-}
-
-- (instancetype)initWithComposeWidth:(NSInteger)composeWidth
-                       composeHeight:(NSInteger)composeHeight
-                         canvasWidth:(NSInteger)canvasWidth
-                        canvasHeight:(NSInteger)canvasHeight
-                         featherPx:(NSInteger)featherPx
-              frameRotationDegrees:(NSInteger)frameRotationDegrees
-{
-    if (self = [super init]) {
-        // V7: frameRotationDegrees is now an OUTPUT-ONLY rotation —
-        // it's applied at snapshot/finalize time to orient the saved
-        // JPEG for display.  The compute pipeline always works in
-        // sensor-native landscape compose space.
-        _frameRotationDegrees = frameRotationDegrees;
-        // V12.6 Step C: _isLandscape is no longer derived from the
-        // JS-passed frameRotationDegrees.  V12.5 telemetry proved
-        // JS was sending the wrong value under portrait-locked
-        // hosts (the lock suppresses RN's rotation event so
-        // `useWindowDimensions` always reported portrait even in
-        // landscape).  We now detect at first-frame init from
-        // R_panToCam directly — see the cylindricalWarp's
-        // first-frame branch.  Pose-derived detection works for
-        // both portrait-locked and non-locked R2-lite hosts.
-        // Default false here is just a safe initialiser; it WILL
-        // be overwritten before any warping happens.
-        _isLandscape = NO;
-        // Default compose dims preserve the 4:3 sensor aspect
-        // (1920x1440 → 960x720 at scale 0.5).  Always landscape
-        // because we no longer rotate input; the canvas geometry
-        // matches the sensor's pixel-shift direction for either
-        // yaw or pitch pan, in either device orientation.
-        _composeWidth  = composeWidth  > 0 ? composeWidth  : 960;
-        _composeHeight = composeHeight > 0 ? composeHeight : 720;
-        // Canvas: wide-landscape because for the typical shelf-scan
-        // use case (portrait phone, left-right yaw pan), the sensor
-        // sees content shifting along its X axis (the wide 1920
-        // axis).  Canvas-X covers ~3 frame-widths of pan; canvas-Y
-        // covers one frame plus pitch-wobble headroom.
-        // V11 Gap #4: square canvas so EITHER pan axis fits.  The
-        // primary use case (top-to-bottom landscape pan) needs canvas-Y
-        // ≥ 3000 px to cover ~90° pitch at typical compose focal — the
-        // earlier 2200 px clipped the pan after 4-5 frames.  5000² is
-        // ~88 MB (canvas + mask), comfortable on iPhone 13+ where the
-        // app is targeted.  Real auto-grow is deferred — flat over-
-        // allocation is simpler and works for both use cases.
-        _canvasWidth   = canvasWidth   > 0 ? canvasWidth   : 5000;
-        _canvasHeight  = canvasHeight  > 0 ? canvasHeight  : 5000;
-        _featherPx     = featherPx     > 0 ? featherPx     : 20;
-
-        // ARKit camera frame (Y-up, -Z forward) → OpenCV camera frame
-        // (Y-down, +Z forward).  Pre-multiplying ARKit-rotation by
-        // M (and post-multiplying by M, since M is its own inverse)
-        // converts the rotation into OpenCV camera-frame conventions
-        // before we plug it into the pinhole projection K.
-        _M_arkitToCv = (cv::Mat_<double>(3, 3) <<
-            1, 0, 0,
-            0, -1, 0,
-            0, 0, -1);
-
-        // V15 — default config (hybrid mode → planar projection).
-        // Caller should override via -setConfig: after init.
-        _config = [RLISStitcherConfig configForMode:@"hybrid"];
-
-        [self reset];
-    }
-    return self;
-}
-
-- (void)setConfig:(RLISStitcherConfig *)config {
-    if (config == nil) return;
-    _config = config;
-    NSLog(@"[V15-config] hybrid config applied: hybridProjection=%@",
-          _config.hybridProjection == RLISHybridProjectionPlanar
-              ? @"Planar" : @"Cylindrical");
-}
-
-- (void)reset {
-    _canvas = cv::Mat::zeros((int)_canvasHeight, (int)_canvasWidth, CV_8UC3);
-    _canvasMask = cv::Mat::zeros((int)_canvasHeight, (int)_canvasWidth, CV_8UC1);
-    _firstRotationArkit = cv::Mat();
-    _K_compose = cv::Mat();
-    _T_canvas = cv::Mat::eye(3, 3, CV_64F);
-    _lastAcceptedYaw = 0.0;
-    _lastAcceptedPitch = 0.0;
-    _lastAcceptedR = cv::Mat();  // V11 Gap #5: clear sensor-frame gate state
-    _hasFirstFrame = false;
-    _accepted = 0;
-    _snapshotSeq = 0;
-}
-
-- (NSInteger)acceptedCount { return _accepted; }
-
-// ── Public: ingestPixelBuffer (V6 pose-driven) ─────────────────────
-
-- (RLISFrameTelemetry *)ingestPixelBuffer:(CVPixelBufferRef)pixelBuffer
-                                       qx:(double)qx
-                                       qy:(double)qy
-                                       qz:(double)qz
-                                       qw:(double)qw
-                                       tx:(double)tx
-                                       ty:(double)ty
-                                       tz:(double)tz
-                                       fx:(double)fx
-                                       fy:(double)fy
-                                       cx:(double)cx
-                                       cy:(double)cy
-                              imageWidth:(NSInteger)imageWidth
-                             imageHeight:(NSInteger)imageHeight
-                                      yaw:(double)yaw
-                                    pitch:(double)pitch
-                          fovHorizDegrees:(double)fovHorizDegrees
-                           fovVertDegrees:(double)fovVertDegrees
-                             trackingPoor:(BOOL)trackingPoor
-{
-    // V13.0e — hybrid engine accepts tx/ty/tz for API symmetry with the
-    // slit-scan engine but does not (yet) use them.  The Samsung-style
-    // hybrid path's robustness comes from feature-matching its overlap
-    // each frame; pose translation correction layered on top would be
-    // redundant.  Suppress unused-warning explicitly so the call stays
-    // semantically tied to the slit engine.
-    (void)tx; (void)ty; (void)tz;
-
-    auto t0 = std::chrono::steady_clock::now();
-
-    RLISFrameTelemetry *tele = [[RLISFrameTelemetry alloc] init];
-    tele.overlapPercent = -1;
-
-    if (trackingPoor) {
-        tele.outcome = RLISFrameOutcomeSkippedTrackingPoor;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-
-    cv::Mat frameBGR;
-    if (![self convertPixelBuffer:pixelBuffer toMat:frameBGR]) {
-        tele.outcome = RLISFrameOutcomeSkippedTrackingPoor;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-
-    // Build R_new (3x3, ARKit-camera-to-world rotation) from the
-    // quaternion.
-    cv::Mat R_new = quaternionToRotationMat(qx, qy, qz, qw);
-
-    // First frame: place at canvas centre, store the reference pose
-    // and intrinsics, accept unconditionally.  All subsequent frames
-    // compute their pose-driven homography RELATIVE to this first
-    // frame.
-    if (!_hasFirstFrame) {
-        _firstRotationArkit = R_new.clone();
-        // V11 Gap #1: per-axis intrinsics scaling (was averaging into
-        // a single scalar — silently distorts whenever compose dims
-        // ratio ≠ sensor dims ratio).  K_compose = diag(sx,sy,1)·K.
-        double sx = (double)frameBGR.cols / std::max((NSInteger)1, imageWidth);
-        double sy = (double)frameBGR.rows / std::max((NSInteger)1, imageHeight);
-        _K_compose = (cv::Mat_<double>(3, 3) <<
-                      fx * sx, 0,       cx * sx,
-                      0,       fy * sy, cy * sy,
-                      0,       0,       1);
-        // V11 Gap #2: cylinder radius = geometric mean of compose
-        // focals.  Was just `fx * s`, which made canvas h-spacing
-        // inconsistent with theta-spacing for any anisotropic-pixel
-        // intrinsic.
-        _focalCompose = std::sqrt((fx * sx) * (fy * sy));
-
-        // V9: build the panorama-to-world rotation from the first
-        // ARKit pose.  Panorama +Z = horizontal projection of first-
-        // camera forward.  For PORTRAIT (cylinder axis = vertical):
-        // panorama +Y = world up.  For LANDSCAPE (cylinder axis =
-        // horizontal pan rotation axis): V14.0pre — panorama +Y =
-        // first-camera +X (sensor X = phone long edge in landscape =
-        // pan rotation axis).  This makes pano-Y the actual rotation
-        // axis, eliminating the V12.x landscape-projection roll-
-        // sensitivity bug (see 2026-05-07-v14-stitcher-plan.md).
-        cv::Mat fwdArkitCam = (cv::Mat_<double>(3, 1) << 0, 0, -1);
-        cv::Mat fwdWorld = _firstRotationArkit * fwdArkitCam;
-        double fwx = fwdWorld.at<double>(0);
-        double fwz = fwdWorld.at<double>(2);
-        double horiz = std::sqrt(fwx * fwx + fwz * fwz);
-        // V11 Gap #3: reject if camera looking nearly vertical.  The
-        // panorama frame needs a horizontal +Z anchor; if camera
-        // forward is gravity-aligned, the horizontal projection is
-        // degenerate.
-        if (horiz < 0.1) {
-            tele.outcome = RLISFrameOutcomeRejectedAlignmentLost;
-            tele.processingMs = msSince(t0);
-            return tele;
-        }
-        double pzx = fwx / horiz;
-        double pzz = fwz / horiz;
-
-        // V14.0pre — orientation detection BEFORE _R_panToWorld
-        // construction (was V12.6 detection done AFTER, using
-        // R_panToCam_first which itself depended on _R_panToWorld —
-        // chicken-and-egg).
-        //
-        // V14.0pre.1 — comparison INVERTED after V14.0pre field test
-        // showed it firing backwards.  Hardware geometry: the phone's
-        // sensor-Y axis (cam-Y) is along the SHORT edge of the phone.
-        // In LANDSCAPE the phone is held long-edge horizontal, so
-        // cam-Y points UP in the user's view (= along world-up =
-        // gravity).  In PORTRAIT it points sideways (horizontal).
-        // V14.0pre had max(|X|,|Z|) > |Y| firing as "landscape" — that
-        // pattern actually identifies PORTRAIT.  Field log showed
-        // |camY.worldY|=0.937 (clearly landscape) firing isLandscape=0.
-        // Inverted comparison matches V12.6 slit-scan detection's
-        // direction (absR11 > absR01).
-        cv::Mat camYInWorld = _firstRotationArkit *
-            (cv::Mat_<double>(3, 1) << 0, 1, 0);
-        const double absCamYInWorldX = std::fabs(camYInWorld.at<double>(0));
-        const double absCamYInWorldY = std::fabs(camYInWorld.at<double>(1));
-        const double absCamYInWorldZ = std::fabs(camYInWorld.at<double>(2));
-        _isLandscape = (absCamYInWorldY
-                        > std::max(absCamYInWorldX, absCamYInWorldZ));
-        NSLog(@"[V14.0pre-orient] engine=hybrid isLandscape=%d "
-              @"|camY.worldX|=%.4f |camY.worldY|=%.4f |camY.worldZ|=%.4f",
-              (int)_isLandscape, absCamYInWorldX, absCamYInWorldY,
-              absCamYInWorldZ);
-
-        if (_isLandscape) {
-            // V14.0pre LANDSCAPE: pano-Y = first-cam +X axis (the pan
-            // rotation axis for vertical pan).  Cylinder axis = pano-Y
-            // = cam-X → roll around cam-Z just slides pixels along
-            // theta with no asymmetric distortion.  Pano-Z = horizontal
-            // projection of first-cam forward (already computed above).
-            // Pano-X = pano-Y × pano-Z (right-handed completion;
-            // approximately gravity-up for level first frame).
-            //
-            // pano-Y = R_first · (1,0,0)  (cam-X in world coords)
-            cv::Mat camXInWorld = _firstRotationArkit *
-                (cv::Mat_<double>(3, 1) << 1, 0, 0);
-            const double pyx = camXInWorld.at<double>(0);
-            const double pyy = camXInWorld.at<double>(1);
-            const double pyz = camXInWorld.at<double>(2);
-            // pano-Z = (pzx, 0, pzz) by construction above.
-            // pano-X = pano-Y × pano-Z; with pano-Z having zero Y comp:
-            //   px.x = pyy*pzz - pyz*0   = pyy*pzz
-            //   px.y = pyz*pzx - pyx*pzz
-            //   px.z = pyx*0   - pyy*pzx = -pyy*pzx
-            const double pxx = pyy * pzz;
-            const double pxy = pyz * pzx - pyx * pzz;
-            const double pxz = -pyy * pzx;
-            // Columns of _R_panToWorld are pano-X, pano-Y, pano-Z.
-            _R_panToWorld = (cv::Mat_<double>(3, 3) <<
-                pxx,  pyx,  pzx,
-                pxy,  pyy,  0.0,
-                pxz,  pyz,  pzz);
-        } else {
-            // PORTRAIT (unchanged from V9): pano-Y = world up.
-            // pano-X = pano-Y × pano-Z = (0,1,0) × (pzx,0,pzz) = (pzz, 0, -pzx)
-            _R_panToWorld = (cv::Mat_<double>(3, 3) <<
-                pzz,   0, pzx,
-                0,     1, 0,
-                -pzx,  0, pzz);
-        }
-
-        // V14.0pre — sanity check the constructed pano frame is
-        // orthonormal (det ≈ 1, R · R^T ≈ I).  Logs once per capture
-        // (first-frame).  If det ≈ -1 or off-diagonals are large, the
-        // pano-X cross-product computation has a sign or transcription
-        // bug — fix BEFORE proceeding.
-        const double pano_det = cv::determinant(_R_panToWorld);
-        cv::Mat pano_RRT = _R_panToWorld * _R_panToWorld.t();
-        NSLog(@"[V14.0pre-pano] det=%.4f I[0,0]=%.4f I[1,1]=%.4f I[2,2]=%.4f "
-              @"I[0,1]=%.4f I[0,2]=%.4f I[1,2]=%.4f",
-              pano_det,
-              pano_RRT.at<double>(0,0), pano_RRT.at<double>(1,1),
-              pano_RRT.at<double>(2,2), pano_RRT.at<double>(0,1),
-              pano_RRT.at<double>(0,2), pano_RRT.at<double>(1,2));
-
-        // Place first frame onto canvas via cylindrical warp.  R for
-        // the warp is panorama→camera in OpenCV cam frame; for the
-        // first frame this is approximately identity (camera-forward
-        // = panorama +Z).  The cylindrical warp gives us a warped
-        // image + a corner in cylindrical-pixel (theta, h)·f space.
-        cv::Mat warpedFirst, warpedFirstMask;
-        cv::Point firstCornerCyl =
-            [self cylindricalWarp:frameBGR rArkit:R_new
-                            outImage:warpedFirst outMask:warpedFirstMask];
-
-        // Anchor the first frame at canvas centre.
-        int dstX = (int)(_canvas.cols - warpedFirst.cols) / 2;
-        int dstY = (int)(_canvas.rows - warpedFirst.rows) / 2;
-        cv::Rect roi(dstX, dstY, warpedFirst.cols, warpedFirst.rows);
-        roi &= cv::Rect(0, 0, _canvas.cols, _canvas.rows);
-        cv::Rect srcRoi(0, 0, roi.width, roi.height);
-        warpedFirst(srcRoi).copyTo(_canvas(roi), warpedFirstMask(srcRoi));
-        warpedFirstMask(srcRoi).copyTo(_canvasMask(roi),
-                                        warpedFirstMask(srcRoi));
-
-        // Track the cylindrical pixel that lives at canvas (0, 0).
-        // Subsequent frames' cylindrical corners → canvas position
-        // by subtracting this origin.
-        _canvasOriginCylX = firstCornerCyl.x - dstX;
-        _canvasOriginCylY = firstCornerCyl.y - dstY;
-
-        _lastAcceptedYaw = yaw;
-        _lastAcceptedPitch = pitch;
-        _lastAcceptedR = R_new.clone();
-        _hasFirstFrame = true;
-        _accepted = 1;
-        tele.outcome = RLISFrameOutcomeAcceptedHigh;
-        tele.confidence = 1.0;
-        tele.overlapPercent = 0;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-
-    // V11 Gap #5: pose-delta gate in SENSOR FRAME.
-    //
-    // Compute the relative rotation between the last-accepted frame
-    // and this frame, expressed in the previous frame's CAMERA-LOCAL
-    // axes (these are fixed to the device sensor hardware regardless
-    // of how the user is holding the phone).
-    //
-    //   R_relative_in_prev_cam = R_prev⁻¹ · R_new   (column-vector convention)
-    //
-    // For ARKit camera axes (+X right, +Y up, −Z forward):
-    //   rotation about sensor +Y → scene shifts horizontally on screen
-    //                              → compare against fovH
-    //   rotation about sensor +X → scene shifts vertically on screen
-    //                              → compare against fovV
-    //
-    // For small-angle rotations (typical accept window 5-25°),
-    // cv::Rodrigues' axis-angle vector ≈ (rotX, rotY, rotZ) with
-    // each component being the rotation about that sensor axis.
-    cv::Mat R_relSensor = _lastAcceptedR.t() * R_new;
-    cv::Mat rvec;
-    cv::Rodrigues(R_relSensor, rvec);
-    double sensorRotX = std::fabs(rvec.at<double>(0));
-    double sensorRotY = std::fabs(rvec.at<double>(1));
-    double overlap = computeOverlapPctSensor(
-        sensorRotX,
-        sensorRotY,
-        fovHorizDegrees,
-        fovVertDegrees
-    );
-    tele.overlapPercent = overlap;
-
-    if (overlap > kMaxOverlapPct) {
-        tele.outcome = RLISFrameOutcomeSkippedTooClose;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-    if (overlap < kMinOverlapPct) {
-        tele.outcome = RLISFrameOutcomeRejectedTooFar;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-
-    // V12.2 cylindrical warp (with V12 mirror fix) + feather blend.
-    cv::Mat warpedNew, warpedNewMask;
-    cv::Point newCornerCyl =
-        [self cylindricalWarp:frameBGR rArkit:R_new
-                       outImage:warpedNew outMask:warpedNewMask];
-    if (warpedNew.empty()) {
-        tele.outcome = RLISFrameOutcomeRejectedAlignmentLost;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-
-    // Map cylindrical-pixel corner to canvas-pixel corner.
-    cv::Point newCornerCanvas(newCornerCyl.x - _canvasOriginCylX,
-                              newCornerCyl.y - _canvasOriginCylY);
-
-    // V9b: optical-flow refinement.  ARKit pose accuracy is ~1-2°,
-    // which translates to ~25-50 px residual misalignment at typical
-    // focal lengths.  KLT flow on a sparse grid in the overlap
-    // region recovers sub-pixel accuracy without needing the full
-    // ORB+RANSAC machinery from the v1-v3 path.  The result is a
-    // single (dx, dy) translation applied to the canvas placement.
-    cv::Point2f shift = [self refineWithOpticalFlow:warpedNew
-                                          newMask:warpedNewMask
-                                     canvasOrigin:newCornerCanvas];
-    newCornerCanvas.x += (int)std::round(shift.x);
-    newCornerCanvas.y += (int)std::round(shift.y);
-
-    cv::Rect dstRoi(newCornerCanvas.x, newCornerCanvas.y,
-                    warpedNew.cols, warpedNew.rows);
-    cv::Rect canvasBounds(0, 0, _canvas.cols, _canvas.rows);
-    cv::Rect dstClipped = dstRoi & canvasBounds;
-    if (dstClipped.width <= 0 || dstClipped.height <= 0) {
-        tele.outcome = RLISFrameOutcomeRejectedAlignmentLost;
-        tele.processingMs = msSince(t0);
-        return tele;
-    }
-    cv::Rect srcRoi(dstClipped.x - dstRoi.x, dstClipped.y - dstRoi.y,
-                    dstClipped.width, dstClipped.height);
-
-    [self featherBlendWarped:warpedNew(srcRoi)
-                         mask:warpedNewMask(srcRoi)
-                  intoCanvas:_canvas(dstClipped)
-                  canvasMask:_canvasMask(dstClipped)];
-
-    _lastAcceptedYaw = yaw;
-    _lastAcceptedPitch = pitch;
-    _lastAcceptedR = R_new.clone();  // V11 Gap #5: sensor-frame gate state
-    _accepted += 1;
-
-    // Pose-driven path is geometrically exact when ARKit tracking is
-    // good (which we already gated on `trackingPoor`).  Confidence
-    // is a function of the FoV-overlap quality: high near 50%, lower
-    // at the edges of the [10, 75]% acceptance window.
-    double midOverlap = 0.5 * (kMinOverlapPct + kMaxOverlapPct);
-    double overlapDistance = std::fabs(overlap - midOverlap)
-                              / (kMaxOverlapPct - midOverlap);
-    double confidence = std::max(0.0, 1.0 - overlapDistance);
-    tele.confidence = confidence;
-    tele.matchCount = -1;       // not applicable in pose-driven path
-    tele.inlierRatio = -1;
-    tele.outcome = (confidence >= 0.6)
-                    ? RLISFrameOutcomeAcceptedHigh
-                    : RLISFrameOutcomeAcceptedMedium;
-    tele.processingMs = msSince(t0);
-    return tele;
-}
-
-// ── Snapshot / finalize ─────────────────────────────────────────────
-
-- (nullable RLISSnapshot *)snapshotWithJpegQuality:(NSInteger)quality
-                                              error:(NSError **)error
-{
-    _snapshotSeq += 1;
-    return [self writeSnapshotToPath:[self currentSnapshotPath]
-                          jpegQuality:quality
-                            tightCrop:YES
-                    applyExposureComp:NO
-                                error:error];
-}
-
-- (nullable RLISSnapshot *)finalizeAtPath:(NSString *)outputPath
-                              jpegQuality:(NSInteger)quality
-                                    error:(NSError **)error
-{
-    // Final output: bounding-box crop + CLAHE.  Runs off the AR
-    // delegate thread because the Swift wrapper dispatches finalize
-    // on workQueue.  V12 Gap #2: dropped the O(W·H) inscribed-rect
-    // search — it produced a far thinner output than the actual
-    // painted region for any non-rectangular pan footprint, and the
-    // mask edges are clean (no per-pixel artefacts to crop away).
-    RLISSnapshot *snap = [self writeSnapshotToPath:outputPath
-                                       jpegQuality:quality
-                                         tightCrop:YES
-                                 applyExposureComp:YES
-                                             error:error];
-    [self reset];
-    return snap;
-}
-
-- (NSString *)currentSnapshotPath {
-    // Cycle through 4 filenames so RN's image cache sees a new URI
-    // on every snapshot but tmp dir doesn't grow unbounded over a
-    // long pan.  4 is enough to outpace RN's most aggressive
-    // image cache lifetimes; the OS reclaims tmp at app launch
-    // anyway.
-    NSString *tmpDir = NSTemporaryDirectory();
-    NSInteger slot = _snapshotSeq % 4;
-    NSString *filename = [NSString stringWithFormat:@"rlis-live-%ld.jpg", (long)slot];
-    return [tmpDir stringByAppendingPathComponent:filename];
-}
-
-- (nullable RLISSnapshot *)writeSnapshotToPath:(NSString *)outputPath
-                                   jpegQuality:(NSInteger)quality
-                                     tightCrop:(BOOL)tightCrop
-                             applyExposureComp:(BOOL)applyExposureComp
-                                         error:(NSError **)error
-{
-    if (_accepted == 0) {
-        if (error) {
-            *error = [NSError errorWithDomain:RNImageStitcherIncrementalErrorDomain
-                                         code:1
-                                     userInfo:@{NSLocalizedDescriptionKey:
-                                       @"No frames have been accepted yet."}];
-        }
-        return nil;
-    }
-
-    cv::Rect cropRect(0, 0, _canvas.cols, _canvas.rows);
-    if (tightCrop) {
-        cv::Rect bbox = cv::boundingRect(_canvasMask);
-        if (bbox.width > 0 && bbox.height > 0) {
-            cropRect = bbox;
-        }
-    }
-    cv::Mat cropped = _canvas(cropRect).clone();
-
-    // V11 Gap #14: NO output rotation needed.
-    //
-    // The earlier (v7) sensor-native canvas needed a gravity-derived
-    // rotation because the canvas was the camera buffer's pixel
-    // layout — buffer-Y was image-down for portrait, image-right for
-    // landscape, etc.  V8+ switched to a panorama-frame canvas
-    // (gravity-up = +panorama-Y; the warp Y-flip puts world-up at
-    // image-top by construction).  V12 briefly tried spherical but
-    // V12.2 reverted to cylindrical — the gravity-alignment guarantee
-    // is the same.  The canvas IS already correctly oriented for
-    // any device hold.
-    cv::Mat out = cropped;
-
-    if (applyExposureComp && !out.empty()) {
-        // CLAHE on the L channel of Lab.  Preserves colour, evens
-        // out luminance variation across the panorama.  Conservative
-        // clipLimit=2.0 — enough to even out auto-exposure bands,
-        // not so much that it crushes highlight/shadow detail.
-        cv::Mat lab;
-        cv::cvtColor(out, lab, cv::COLOR_BGR2Lab);
-        std::vector<cv::Mat> labChannels(3);
-        cv::split(lab, labChannels);
-        cv::Ptr<cv::CLAHE> clahe = cv::createCLAHE(2.0, cv::Size(8, 8));
-        clahe->apply(labChannels[0], labChannels[0]);
-        cv::merge(labChannels, lab);
-        cv::cvtColor(lab, out, cv::COLOR_Lab2BGR);
-    }
-
-    int q = (int)std::clamp((long long)quality, 0LL, 100LL);
-    std::vector<int> params = {cv::IMWRITE_JPEG_QUALITY, q};
-    NSString *cleanPath = [outputPath hasPrefix:@"file://"]
-        ? [outputPath substringFromIndex:7]
-        : outputPath;
-    bool ok = cv::imwrite(std::string([cleanPath UTF8String]), out, params);
-    NSLog(@"[RLIS-PIP] imwrite path=%@ size=%dx%d quality=%d ok=%d",
-          cleanPath, out.cols, out.rows, q, (int)ok);
-    if (!ok) {
-        if (error) {
-            *error = [NSError errorWithDomain:RNImageStitcherIncrementalErrorDomain
-                                         code:2
-                                     userInfo:@{NSLocalizedDescriptionKey:
-                                       [NSString stringWithFormat:
-                                        @"Failed to write JPEG to %@", outputPath]}];
-        }
-        return nil;
-    }
-
-    RLISSnapshot *snap = [[RLISSnapshot alloc] init];
-    snap.panoramaPath = cleanPath;
-    snap.width = out.cols;
-    snap.height = out.rows;
-    snap.acceptedCount = _accepted;
-    return snap;
-}
-
-// ── Internals ───────────────────────────────────────────────────────
-
-static double msSince(std::chrono::steady_clock::time_point t0) {
-    auto dt = std::chrono::steady_clock::now() - t0;
-    return std::chrono::duration_cast<std::chrono::microseconds>(dt).count() / 1000.0;
-}
-
-/// Quaternion (x, y, z, w) → 3x3 rotation matrix (CV_64F).
-/// Defensive: normalises if the input isn't unit-length.
-static cv::Mat quaternionToRotationMat(double qx, double qy, double qz, double qw) {
-    double n = std::sqrt(qx*qx + qy*qy + qz*qz + qw*qw);
-    if (n > 1e-9) { qx /= n; qy /= n; qz /= n; qw /= n; }
-    return (cv::Mat_<double>(3, 3) <<
-        1 - 2*(qy*qy + qz*qz), 2*(qx*qy - qw*qz),     2*(qx*qz + qw*qy),
-        2*(qx*qy + qw*qz),     1 - 2*(qx*qx + qz*qz), 2*(qy*qz - qw*qx),
-        2*(qx*qz - qw*qy),     2*(qy*qz + qw*qx),     1 - 2*(qx*qx + qy*qy));
-}
-
-// `sensorRotationMatrix` was removed in V7 — the rotation chain it
-// powered is no longer in the homography path.  See the v7 commit
-// for the architectural fix that replaced it with sensor-native
-// compute + output-only rotation.
-
-/// Compute fractional overlap between consecutive frames assuming the
-/// camera is rotated about its centre by (deltaYaw, deltaPitch) in
-/// radians.  Output is in percent.  We take the dominant axis (the
-/// one with larger angular delta) as the pan axis — overlap on that
-/// axis is what determines whether the frames have moved enough.
-/// V11 Gap #5: sensor-frame gate.
-///
-/// Inputs are absolute rotation magnitudes (radians) about the
-/// sensor's +X and +Y axes — these axes are FIXED to the device
-/// hardware regardless of how the operator is holding the phone.
-///
-///   sensorRotXRad: rotation about sensor +X → vertical scene shift
-///                  → compare against fovV (sensor's vertical FoV)
-///   sensorRotYRad: rotation about sensor +Y → horizontal scene shift
-///                  → compare against fovH (sensor's horizontal FoV)
-///
-/// The "dominant axis = pan direction" heuristic still applies — pick
-/// whichever rotation is larger and use the matching FoV to compute
-/// the per-axis overlap.  Output is overlap percent [0, 100].
-static double computeOverlapPctSensor(double sensorRotXRad,
-                                      double sensorRotYRad,
-                                      double fovHorizDegrees,
-                                      double fovVertDegrees)
-{
-    double fovH = fovHorizDegrees * M_PI / 180.0;
-    double fovV = fovVertDegrees * M_PI / 180.0;
-    if (fovH <= 1e-6) fovH = 65.0 * M_PI / 180.0;
-    if (fovV <= 1e-6) fovV = 50.0 * M_PI / 180.0;
-
-    double overlap;
-    if (sensorRotYRad >= sensorRotXRad) {
-        overlap = 1.0 - sensorRotYRad / fovH;
-    } else {
-        overlap = 1.0 - sensorRotXRad / fovV;
-    }
-    return std::clamp(overlap, 0.0, 1.0) * 100.0;
-}
-
-- (BOOL)convertPixelBuffer:(CVPixelBufferRef)pixelBuffer toMat:(cv::Mat &)outBGR {
-    if (pixelBuffer == NULL) return NO;
-    OSType pf = CVPixelBufferGetPixelFormatType(pixelBuffer);
-
-    CVReturn lockResult = CVPixelBufferLockBaseAddress(pixelBuffer,
-                                                        kCVPixelBufferLock_ReadOnly);
-    if (lockResult != kCVReturnSuccess) return NO;
-
-    cv::Mat frame;
-    BOOL ok = NO;
-
-    if (pf == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange ||
-        pf == kCVPixelFormatType_420YpCbCr8BiPlanarVideoRange) {
-        // ARKit's NV12 — Y plane in plane 0, interleaved CbCr in plane 1.
-        // OpenCV exposes a direct NV12 → BGR conversion.
-        size_t w = CVPixelBufferGetWidth(pixelBuffer);
-        size_t h = CVPixelBufferGetHeight(pixelBuffer);
-        size_t yStride = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 0);
-        size_t cStride = CVPixelBufferGetBytesPerRowOfPlane(pixelBuffer, 1);
-        uint8_t *yPlane = (uint8_t *)CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 0);
-        uint8_t *cPlane = (uint8_t *)CVPixelBufferGetBaseAddressOfPlane(pixelBuffer, 1);
-
-        // Build a contiguous YUV buffer expected by cvtColorTwoPlane.
-        // OpenCV provides cvtColorTwoPlane which takes Y and UV planes
-        // separately — perfect for NV12 with potentially-different
-        // strides between planes.
-        cv::Mat yMat((int)h, (int)w, CV_8UC1, yPlane, yStride);
-        cv::Mat cMat((int)h / 2, (int)w / 2, CV_8UC2, cPlane, cStride);
-        int code = (pf == kCVPixelFormatType_420YpCbCr8BiPlanarFullRange)
-            ? cv::COLOR_YUV2BGR_NV12 : cv::COLOR_YUV2BGR_NV12;
-        cv::cvtColorTwoPlane(yMat, cMat, frame, code);
-        ok = YES;
-    } else if (pf == kCVPixelFormatType_32BGRA) {
-        size_t w = CVPixelBufferGetWidth(pixelBuffer);
-        size_t h = CVPixelBufferGetHeight(pixelBuffer);
-        size_t stride = CVPixelBufferGetBytesPerRow(pixelBuffer);
-        uint8_t *base = (uint8_t *)CVPixelBufferGetBaseAddress(pixelBuffer);
-        cv::Mat bgra((int)h, (int)w, CV_8UC4, base, stride);
-        cv::cvtColor(bgra, frame, cv::COLOR_BGRA2BGR);
-        ok = YES;
-    }
-    CVPixelBufferUnlockBaseAddress(pixelBuffer, kCVPixelBufferLock_ReadOnly);
-    if (!ok) return NO;
-
-    // V7: NO input rotation.  ARKit delivers sensor-native landscape
-    // pixels and we keep them that way through the entire compute
-    // pipeline.  This is the architectural fix that resolves the
-    // v6 rotation-vs-canvas mismatch — we no longer need an `R2S`
-    // chain in the homography to undo a rotation we shouldn't have
-    // applied in the first place.
-    //
-    // The sensor's native orientation is what the ARKit pose +
-    // intrinsics describe.  Working directly in that frame keeps
-    // `H = K · R_rel · K⁻¹` clean and bug-free.  Output rotation
-    // for display happens AT SNAPSHOT/FINALIZE time only.
-    //
-    // Uniform-scale downsample preserves the 4:3 sensor aspect ratio
-    // (no non-uniform stretch).  Picks whichever dimension hits the
-    // compose budget first; the other comes out proportional.
-    double scale = std::min(
-        (double)_composeWidth  / (double)frame.cols,
-        (double)_composeHeight / (double)frame.rows
-    );
-    if (scale > 1.0) scale = 1.0;  // never upscale
-    int outW = std::max(1, (int)std::round(frame.cols * scale));
-    int outH = std::max(1, (int)std::round(frame.rows * scale));
-    cv::Size target(outW, outH);
-    if (frame.cols == outW && frame.rows == outH) {
-        outBGR = frame;
-    } else {
-        cv::resize(frame, outBGR, target, 0, 0, cv::INTER_AREA);
-    }
-    return YES;
-}
-
-// `placeFirstFrame` was removed in v6 — the first-frame logic is now
-// inlined in `ingestPixelBuffer:` so the engine can capture the
-// reference pose + intrinsics in the same place it positions the
-// frame on the canvas.
-
-/// V12.2 hand-rolled CYLINDRICAL projection (with V12 mirror fix
-/// kept).  V12 had tried spherical to handle extreme pitch, but
-/// spherical bulges both axes and made every level frame look
-/// fisheye.  Reverted to cylindrical here; pitch-axis flexibility
-/// will come from making the cylinder axis orientation-aware
-/// (Step 3) rather than from changing the projection itself.
-///
-/// Cylinder parameterised by:
-///   theta = horizontal angle around panorama-Y, atan2(-wx, wz)
-///                       (the −wx is the V12 mirror fix —
-///                       panorama-X is "user's left" in our
-///                       right-handed setup, so we flip X before
-///                       atan2 to put user's-right at canvas-right)
-///   h     = wy / sqrt(wx² + wz²)         (height up the cylinder)
-///   pixel = (focal · theta, -focal · h)
-///                       (the −h is the Y-flip — panorama +Y is
-///                       gravity-up, image +Y is image-down)
-///
-/// Inverse map:
-///   theta = canvas_x / focal
-///   h     = -canvas_y / focal
-///   ray   = (-sin(theta), h, cos(theta))
-///
-/// Vertical lines (perpendicular to the cylinder axis) stay
-/// straight in the projection — that's why cylindrical produces a
-/// natural-looking panorama for level scenes.  Pitch close to ±90°
-/// (looking straight up/down) makes h = wy/sqrt(wx²+wz²) blow up
-/// and the bbox grows unbounded; the canvas-x2 sanity check rejects
-/// those frames.
-///
-/// Returns the bbox's top-left in cylindrical-pixel coords; the
-/// caller adds the canvas origin offset to land it on the canvas.
-- (cv::Point)cylindricalWarp:(const cv::Mat &)src
-                       rArkit:(const cv::Mat &)rArkit
-                     outImage:(cv::Mat &)outImage
-                      outMask:(cv::Mat &)outMask
-{
-    if (_R_panToWorld.empty() || _focalCompose <= 0) {
-        outImage = cv::Mat();
-        outMask = cv::Mat();
-        return cv::Point(0, 0);
-    }
-
-    // V14.0pre — cv::detail::CylindricalWarper does the projection.
-    // R = camera-to-panorama rotation in OpenCV camera frame.  K is
-    // intrinsics in CV_32F (warper requires float).  Cylinder radius
-    // = focal length.
-    //
-    // Replaces ~240 lines of hand-rolled per-corner forward projection
-    // + bbox computation + inverse-map remap.  Same K + R inputs, same
-    // cv::Point corner output (top-left of warped image in cylindrical-
-    // pixel space).  Battle-tested edge handling, antialiased remap.
-    cv::Mat R_panToCam = _M_arkitToCv * rArkit.t() * _R_panToWorld;
-    cv::Mat R_camToPan = R_panToCam.t();
-
-    cv::Mat K32, R32;
-    _K_compose.convertTo(K32, CV_32F);
-    R_camToPan.convertTo(R32, CV_32F);
-
-    // V15 — projection selectable via _config.hybridProjection.
-    // Default is Planar (cv::detail::PlaneWarper) for V15 hybrid mode,
-    // because cylindrical projection has the V12.x roll-asymmetry bug
-    // that's been documented in the V14 spec.  Planar is well-behaved
-    // for pans <60°, which is the typical retail use case.
-    cv::Point corner;
-    cv::Mat whiteFrame(src.size(), CV_8UC1, cv::Scalar(255));
-
-    if (_config.hybridProjection == RLISHybridProjectionPlanar) {
-        cv::detail::PlaneWarper warper((float)_focalCompose);
-        corner = warper.warp(src, K32, R32,
-                             cv::INTER_LINEAR,
-                             cv::BORDER_REFLECT,
-                             outImage);
-        warper.warp(whiteFrame, K32, R32,
-                    cv::INTER_NEAREST,
-                    cv::BORDER_CONSTANT,
-                    outMask);
-    } else {
-        cv::detail::CylindricalWarper warper((float)_focalCompose);
-        corner = warper.warp(src, K32, R32,
-                             cv::INTER_LINEAR,
-                             cv::BORDER_REFLECT,
-                             outImage);
-        warper.warp(whiteFrame, K32, R32,
-                    cv::INTER_NEAREST,
-                    cv::BORDER_CONSTANT,
-                    outMask);
-    }
-
-    static bool _v14LoggedFirstWarp = false;
-    if (!_v14LoggedFirstWarp) {
-        _v14LoggedFirstWarp = true;
-        NSLog(@"[V15-warp] hybrid projection=%@ corner=(%d,%d) outSize=%dx%d focal=%.1f",
-              _config.hybridProjection == RLISHybridProjectionPlanar
-                  ? @"Planar" : @"Cylindrical",
-              corner.x, corner.y, outImage.cols, outImage.rows, _focalCompose);
-        NSLog(@"[V14.0pre-warp] OpenCV CylindricalWarper "
-              @"corner=(%d,%d) outSize=%dx%d focal=%.1f",
-              corner.x, corner.y, outImage.cols, outImage.rows,
-              _focalCompose);
-    }
-
-    return corner;
-}
-
-/// V9b KLT optical flow refinement.  Computes a residual translation
-/// (dx, dy) the new warped frame should be shifted by to align
-/// pixel-perfectly with the existing canvas in their overlap region.
-///
-/// Algorithm:
-///   1. Compute the overlap rect between warpedNew (placed at
-///      canvasOrigin) and the existing canvas mask.
-///   2. Convert both regions to grayscale.
-///   3. `cv::goodFeaturesToTrack` on the canvas overlap: find ~50
-///      strong corners.
-///   4. `cv::calcOpticalFlowPyrLK` to track those corners into the
-///      warped overlap.
-///   5. Median (dx, dy) over inlier tracks = residual shift.
-///
-/// Returns (0, 0) if not enough tracks, or if the shift exceeds a
-/// sanity threshold (likely a bad frame, don't bias the placement).
-- (cv::Point2f)refineWithOpticalFlow:(const cv::Mat &)warpedNew
-                              newMask:(const cv::Mat &)warpedNewMask
-                         canvasOrigin:(cv::Point)canvasOrigin
-{
-    if (_accepted == 0) return cv::Point2f(0, 0);
-
-    // Compute overlap rect (canvas coords).
-    cv::Rect newRect(canvasOrigin.x, canvasOrigin.y,
-                     warpedNew.cols, warpedNew.rows);
-    cv::Rect canvasBounds(0, 0, _canvas.cols, _canvas.rows);
-    cv::Rect newOnCanvas = newRect & canvasBounds;
-    if (newOnCanvas.width < 16 || newOnCanvas.height < 16) {
-        return cv::Point2f(0, 0);
-    }
-
-    cv::Mat canvasOverlap = _canvas(newOnCanvas);
-    cv::Mat canvasMaskOverlap = _canvasMask(newOnCanvas);
-    cv::Mat warpedOverlap = warpedNew(cv::Rect(
-        newOnCanvas.x - newRect.x, newOnCanvas.y - newRect.y,
-        newOnCanvas.width, newOnCanvas.height));
-    cv::Mat warpedMaskOverlap = warpedNewMask(cv::Rect(
-        newOnCanvas.x - newRect.x, newOnCanvas.y - newRect.y,
-        newOnCanvas.width, newOnCanvas.height));
-
-    // Both regions need pixels — bail if either side is mostly empty.
-    int canvasFilled = cv::countNonZero(canvasMaskOverlap);
-    int warpedFilled = cv::countNonZero(warpedMaskOverlap);
-    int totalPx = newOnCanvas.width * newOnCanvas.height;
-    if (canvasFilled < totalPx / 4 || warpedFilled < totalPx / 4) {
-        return cv::Point2f(0, 0);
-    }
-
-    cv::Mat canvasGray, warpedGray;
-    cv::cvtColor(canvasOverlap, canvasGray, cv::COLOR_BGR2GRAY);
-    cv::cvtColor(warpedOverlap, warpedGray, cv::COLOR_BGR2GRAY);
-
-    // Find strong corners in canvas, restricted to the overlap mask.
-    std::vector<cv::Point2f> canvasPts;
-    cv::Mat featureMask;
-    cv::bitwise_and(canvasMaskOverlap, warpedMaskOverlap, featureMask);
-    cv::goodFeaturesToTrack(canvasGray, canvasPts, /*maxCorners=*/64,
-                             /*qualityLevel=*/0.01, /*minDistance=*/10,
-                             featureMask, /*blockSize=*/3, false, 0.04);
-    if (canvasPts.size() < 8) return cv::Point2f(0, 0);
-
-    // Forward track: canvas → warped.
-    std::vector<cv::Point2f> warpedPts;
-    std::vector<uchar> statusFwd;
-    std::vector<float> errFwd;
-    cv::calcOpticalFlowPyrLK(canvasGray, warpedGray,
-                              canvasPts, warpedPts, statusFwd, errFwd,
-                              cv::Size(21, 21), 3,
-                              cv::TermCriteria(
-                                  cv::TermCriteria::COUNT
-                                      | cv::TermCriteria::EPS,
-                                  20, 0.03));
-
-    // V11 Gap #9: forward-backward bidirectional check.  Track the
-    // forward-tracked points BACK into the canvas frame; reject any
-    // point whose round-trip error exceeds 1 px.  Status flag and
-    // patch-error threshold catch obvious failures, but trackers
-    // can drift inside the search window without flipping status —
-    // FB error is the standard reliability gate (every production
-    // OF aligner uses it).
-    std::vector<cv::Point2f> canvasPtsRev;
-    std::vector<uchar> statusBwd;
-    std::vector<float> errBwd;
-    cv::calcOpticalFlowPyrLK(warpedGray, canvasGray,
-                              warpedPts, canvasPtsRev, statusBwd, errBwd,
-                              cv::Size(21, 21), 3,
-                              cv::TermCriteria(
-                                  cv::TermCriteria::COUNT
-                                      | cv::TermCriteria::EPS,
-                                  20, 0.03));
-
-    // Build the inlier set: forward + backward both succeeded, FB
-    // error < 1 px, displacement in plausible range.
-    std::vector<cv::Point2f> goodCanvas, goodWarped;
-    goodCanvas.reserve(canvasPts.size());
-    goodWarped.reserve(canvasPts.size());
-    for (size_t i = 0; i < canvasPts.size(); i++) {
-        if (!statusFwd[i] || !statusBwd[i]) continue;
-        if (errFwd[i] > 30.0f || errBwd[i] > 30.0f) continue;
-        float fbDx = canvasPtsRev[i].x - canvasPts[i].x;
-        float fbDy = canvasPtsRev[i].y - canvasPts[i].y;
-        if (fbDx*fbDx + fbDy*fbDy > 1.0f) continue;  // > 1 px FB error
-        float dx = warpedPts[i].x - canvasPts[i].x;
-        float dy = warpedPts[i].y - canvasPts[i].y;
-        if (std::fabs(dx) > 30.0f || std::fabs(dy) > 30.0f) continue;
-        goodCanvas.push_back(canvasPts[i]);
-        goodWarped.push_back(warpedPts[i]);
-    }
-    if (goodCanvas.size() < 6) return cv::Point2f(0, 0);
-
-    // V11 Gap #10: 2-D RANSAC translation fit (instead of per-axis
-    // independent median, which can pick a (dx, dy) that no single
-    // point voted for — an issue in multi-modal flow scenes like a
-    // shelf with a moving customer).
-    //
-    // `estimateAffinePartial2D` fits a 2.5-DoF (rotation + uniform
-    // scale + translation) similarity transform with RANSAC.  We
-    // use only the translation component; the rotation/scale fall-
-    // out shouldn't be applied (cylindrical warp already handled
-    // those — OF is only correcting residual translation).
-    std::vector<uchar> ransacInliers;
-    cv::Mat affine = cv::estimateAffinePartial2D(
-        goodCanvas, goodWarped, ransacInliers, cv::RANSAC,
-        /*ransacReprojThreshold=*/3.0,
-        /*maxIters=*/2000,
-        /*confidence=*/0.99,
-        /*refineIters=*/10);
-    if (affine.empty()) return cv::Point2f(0, 0);
-    // Inlier ratio sanity check.
-    int inlierCount = cv::countNonZero(ransacInliers);
-    if (inlierCount < 6 || inlierCount * 2 < (int)goodCanvas.size()) {
-        return cv::Point2f(0, 0);
-    }
-    float medDx = (float)affine.at<double>(0, 2);
-    float medDy = (float)affine.at<double>(1, 2);
-
-    // The track tells us "to align canvas pixels with warped pixels,
-    // shift WARPED by (-medDx, -medDy)".  We shift the placement
-    // of warped on canvas by the opposite to compensate.
-    return cv::Point2f(-medDx, -medDy);
-}
-
-/// V11 Gap #11: NARROW-band feather blend.  Earlier versions used
-/// `alpha = distNew / (distNew + distCanvas)` over the FULL overlap,
-/// which smears every pixel of disagreement across the entire
-/// overlap region — the textbook ghosting source called out by
-/// Brown-Lowe 2007.  At the typical ARKit ~1-2° pose error + KLT-
-/// refined ~5 px residual, full-overlap feather creates visible
-/// double-image.
-///
-/// Narrow-band approach: define the SEAM as `distNew == distCanvas`
-/// (the locus of equal-distance-from-each-frame's-edge points).
-/// Within `kSeamBandPx` of the seam, smoothly transition alpha 0→1.
-/// Outside the band, alpha is binary (0 or 1).  Each pixel comes
-/// from EXACTLY ONE frame, except in the small seam band — so any
-/// per-pixel misalignment can't produce ghosts.
-- (void)featherBlendWarped:(cv::Mat)warped
-                       mask:(cv::Mat)warpedMask
-                intoCanvas:(cv::Mat)canvasRoi
-                canvasMask:(cv::Mat)canvasMaskRoi
-{
-    // V11 Gap #13: per-pair gain compensation BEFORE blending.
-    // Frames captured 200ms apart often differ in luminance by
-    // 5-15% due to auto-exposure drift; without compensation the
-    // panorama shows visible vertical/horizontal banding at every
-    // seam.  Apply a per-channel mean ratio (canvas / warped)
-    // computed on the overlap region.  Conservative bounds to
-    // avoid amplifying noise.
-    cv::Mat warpedAdj;
-    cv::Mat overlapMask;
-    cv::bitwise_and(canvasMaskRoi, warpedMask, overlapMask);
-    int overlapPx = cv::countNonZero(overlapMask);
-    if (overlapPx > 100) {
-        cv::Scalar canvasMean = cv::mean(canvasRoi, overlapMask);
-        cv::Scalar warpedMean = cv::mean(warped, overlapMask);
-        double gainB = (warpedMean[0] > 1.0) ? (canvasMean[0] / warpedMean[0]) : 1.0;
-        double gainG = (warpedMean[1] > 1.0) ? (canvasMean[1] / warpedMean[1]) : 1.0;
-        double gainR = (warpedMean[2] > 1.0) ? (canvasMean[2] / warpedMean[2]) : 1.0;
-        // Clamp gains to ±25% to avoid blowing out highlights or
-        // crushing shadows on a single noisy mean estimate.
-        gainB = std::clamp(gainB, 0.75, 1.25);
-        gainG = std::clamp(gainG, 0.75, 1.25);
-        gainR = std::clamp(gainR, 0.75, 1.25);
-        cv::Mat warpedF;
-        warped.convertTo(warpedF, CV_32FC3);
-        std::vector<cv::Mat> ch(3);
-        cv::split(warpedF, ch);
-        ch[0] *= gainB;
-        ch[1] *= gainG;
-        ch[2] *= gainR;
-        cv::merge(ch, warpedF);
-        warpedF.convertTo(warpedAdj, CV_8UC3);
-    } else {
-        warpedAdj = warped;
-    }
-
-    cv::Mat distNew, distCanvas;
-    cv::distanceTransform(warpedMask, distNew, cv::DIST_L2, 3);
-    cv::distanceTransform(canvasMaskRoi, distCanvas, cv::DIST_L2, 3);
-
-    // Signed distance from seam: positive = "new wins side", negative
-    // = "canvas wins side".  Pixels >= +bandHalf use new (alpha=1),
-    // pixels <= -bandHalf use canvas (alpha=0), in-between band gets
-    // a smooth ramp.
-    constexpr float kSeamBandPx = 5.0f;
-    cv::Mat signedDist = distNew - distCanvas;
-    cv::Mat alpha;
-    // alpha = clamp((signedDist + bandHalf) / band, 0, 1)
-    signedDist.convertTo(alpha, CV_32F,
-                          1.0 / (2.0 * kSeamBandPx),
-                          0.5);
-    cv::min(alpha, 1.0f, alpha);
-    cv::max(alpha, 0.0f, alpha);
-
-    // First-touch regions: alpha=1 unconditionally (canvas was empty
-    // here, new frame is the only source).
-    cv::Mat noPrior;
-    cv::compare(canvasMaskRoi, 0, noPrior, cv::CMP_EQ);
-    alpha.setTo(1.0f, noPrior);
-
-    // Outside-of-new regions: keep canvas (alpha=0).
-    cv::Mat noNew;
-    cv::compare(warpedMask, 0, noNew, cv::CMP_EQ);
-    alpha.setTo(0.0f, noNew);
-
-    // Per-channel blend.
-    cv::Mat alpha3, invAlpha3;
-    cv::Mat ch[] = {alpha, alpha, alpha};
-    cv::merge(ch, 3, alpha3);
-    invAlpha3 = cv::Scalar(1, 1, 1) - alpha3;
-
-    cv::Mat warpedF, canvasF;
-    warpedAdj.convertTo(warpedF, CV_32FC3);  // V11 Gap #13: use gain-corrected
-    canvasRoi.convertTo(canvasF, CV_32FC3);
-    cv::Mat blendedF = warpedF.mul(alpha3) + canvasF.mul(invAlpha3);
-    cv::Mat blended8;
-    blendedF.convertTo(blended8, CV_8UC3);
-
-    // Write back: only where the union mask has content.
-    cv::Mat unionMask;
-    cv::bitwise_or(warpedMask, canvasMaskRoi, unionMask);
-    blended8.copyTo(canvasRoi, unionMask);
-    cv::bitwise_or(canvasMaskRoi, warpedMask, canvasMaskRoi);
-}
-
-// V11 Gap #21: deleted ~85 lines of dead `warpAndBlend` (legacy v7
-// planar warp + Gaussian-blurred binary alpha-blend).  Was never
-// called after v9 switched to cylindricalWarp + featherBlendWarped.
-
-@end