react-native-image-stitcher 0.14.2 → 0.15.0

package/ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift

@@ -145,19 +145,16 @@ public final class IncrementalStitcherBridge: RCTEventEmitter {
                captureOrientation,
                Int32(rotation),
                String(describing: options["captureOrientation"]))
-        // V15 — engine selection.  Three modes:
-        //   'hybrid'           — planar projection + feature matching
-        //   'slitscan-rotate'  — V13.0a + 1D NCC for rotation wobble
-        //   'slitscan-both'    — DEFAULT — V13.0a + no gate + feather
-        //                         blend; iterate via per-stage toggles
-        //                         in the config dict.
-        // Backward compat: 'firstwins-rectilinear' → 'slitscan-rotate'.
-        // Legacy 'firstwins' / 'firstwins-zoomed' / 'slitscan' fall
-        // back to 'slitscan-both' with a deprecation warning.
-        let engineMode = (options["engine"] as? String) ?? "slitscan-both"
+        // Engine selection.  The live incremental engines (hybrid,
+        // slitscan-*, and the legacy firstwins* aliases) were archived
+        // in the 2026-06 batch-keyframe cleanup — the SDK now ships
+        // only 'batch-keyframe'.  Any other value is still accepted for
+        // backward compatibility but falls back to batch-keyframe with
+        // a deprecation log inside IncrementalStitcher.start().
+        let engineMode = (options["engine"] as? String) ?? "batch-keyframe"
 
-        // V15 — per-stage config overrides.  All optional; missing
-        // fields use mode defaults from +[RLISStitcherConfig configForMode:].
+        // Per-stage config overrides.  All optional; keys not consumed
+        // by the batch-keyframe pipeline are ignored.
         let configOverrides = options["config"] as? [String: Any] ?? [:]
 
         IncrementalStitcher.shared.start(

package/ios/Sources/RNImageStitcher/KeyframeGate.swift

@@ -145,6 +145,20 @@ final class KeyframeGate {
         }
     }
 
+    /// Wall-clock keyframe-interval budget, in MILLISECONDS.  When > 0,
+    /// the gate force-accepts a frame once the elapsed time since the
+    /// last accepted keyframe exceeds this value — even when novelty <
+    /// overlapThreshold.  Unlike `flowMaxTranslationCm` this applies to
+    /// BOTH the Pose and Flow strategies, and is passed STRAIGHT
+    /// THROUGH to the bridge (the unit is already what C++ expects — no
+    /// cm→m style conversion).  Default 2000 ms; 0 = disabled.  The C++
+    /// setter clamps to ≥ 0.
+    var maxKeyframeIntervalMs: Double = 2000.0 {
+        didSet {
+            bridge.setMaxKeyframeIntervalMs(maxKeyframeIntervalMs)
+        }
+    }
+
     /// V16 — percentile used to aggregate the tracked features'
     /// absolute displacements into a per-axis novelty estimate.
     /// Default 0.85.  Pre-V16 used median (0.50); the higher

package/ios/Sources/RNImageStitcher/KeyframeGateBridge.h

@@ -72,6 +72,13 @@ NS_SWIFT_NAME(KeyframeGateBridge)
 /// translation overflow even when novelty < threshold; 0 disables.
 /// See KeyframeGate.swift for the operator-facing description.
 - (void)setFlowMaxTranslationM:(double)metres;
+/// Wall-clock keyframe-interval budget (milliseconds).  Set > 0 to
+/// force-accept a frame when the elapsed time since the last accepted
+/// keyframe exceeds this value (applies to BOTH Pose and Flow
+/// strategies); 0 disables.  Passed straight through (no unit
+/// conversion).  See KeyframeGate.swift for the operator-facing
+/// description.
+- (void)setMaxKeyframeIntervalMs:(double)ms;
 /// V16 — novelty aggregation percentile [0.5, 0.99].  Default 0.85.
 /// See KeyframeGate.swift for the operator-facing description.
 - (void)setFlowNoveltyPercentile:(double)percentile;

package/ios/Sources/RNImageStitcher/KeyframeGateBridge.mm

@@ -41,6 +41,8 @@ static NSString *kReasonStringFor(retailens::KeyframeGateDecisionReason r) {
         case R::RejectOverlapTooHighFlow:    return @"overlap-too-high (flow)";
         // V16 — translation-budget force-accept
         case R::AcceptFlowTranslation:       return @"ok-flow-translation";
+        // Wall-clock keyframe-interval force-accept (Pose + Flow)
+        case R::AcceptTimeInterval:          return @"ok-time-interval";
     }
     return @"unknown";
 }
@@ -122,6 +124,10 @@ static NSString *kReasonStringFor(retailens::KeyframeGateDecisionReason r) {
     _gate.setFlowMaxTranslationM(metres);
 }
 
+- (void)setMaxKeyframeIntervalMs:(double)ms {
+    _gate.setMaxKeyframeIntervalMs(ms);
+}
+
 - (void)setFlowNoveltyPercentile:(double)percentile {
     _gate.setFlowNoveltyPercentile(percentile);
 }

package/ios/Sources/RNImageStitcher/OpenCVKeyframeCollector.h

@@ -3,7 +3,7 @@
 // OpenCVKeyframeCollector — V16 Phase 1 helper that accumulates the
 // AR-keyframe-gate's accepted CVPixelBuffers as on-disk JPEGs while
 // the user pans, then hands the path list off to OpenCVStitcher's
-// `stitchKeyframePaths:withPoses:` on shutter release.
+// `stitchFramePaths:` on shutter release.
 //
 // Why a separate class:
 //   - CVPixelBuffer → cv::Mat → cv::imwrite has to live in ObjC++ /
@@ -25,7 +25,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 /// Each saved keyframe ends up with a JPEG path + the index it was
 /// saved at + the on-disk size.  Returned from `saveKeyframe:…` so
-/// the host can build the path/pose list for `stitchKeyframePaths:`.
+/// the host can build the path/pose list for `stitchFramePaths:`.
 @interface OpenCVKeyframeRecord : NSObject
 @property (nonatomic, copy, readonly) NSString *path;
 @property (nonatomic, assign, readonly) NSInteger index;

package/ios/Sources/RNImageStitcher/OpenCVKeyframeCollector.mm

@@ -174,7 +174,7 @@ static BOOL WriteJPEGWithEXIF(const cv::Mat &bgr,
 
   // Rotate to caller-requested orientation.  The JPEGs are saved in
   // the orientation the stitcher expects (user-pan orientation), so
-  // OpenCVStitcher.stitchKeyframePaths can read them with no further
+  // OpenCVStitcher.stitchFramePaths can read them with no further
   // rotation work.
   cv::Mat rotated;
   if (rotationDegrees == 90) {
@@ -236,8 +236,8 @@ static BOOL WriteJPEGWithEXIF(const cv::Mat &bgr,
 
 // ── CVPixelBuffer → cv::Mat (BGR) ──────────────────────────────────
 //
-// Mirrors `OpenCVIncrementalStitcher.convertPixelBuffer:toMat:` but
-// kept inline here so this file is self-contained.  Supports the two
+// Self-contained CVPixelBuffer → cv::Mat conversion (the
+// OpenCVIncrementalStitcher it once mirrored is now archived).  Supports the two
 // pixel formats ARFrame.capturedImage uses on iOS (NV12 by default;
 // BGRA when the AR session is configured for it).  Lock-once, copy
 // out, unlock — buffer lifetime ends with the caller's accept frame.

package/ios/Sources/RNImageStitcher/OpenCVStitcher.h

@@ -52,7 +52,7 @@ extern NSString *const RNImageStitcherErrorDomain;
                     framesIncluded:(NSInteger)framesIncluded
              finalConfidenceThresh:(double)finalConfidenceThresh NS_DESIGNATED_INITIALIZER;
 /// Convenience initializer for paths that don't carry C+D retry
-/// telemetry (e.g. stitchVideoAtPath / stitchKeyframePaths).  Sets
+/// telemetry (e.g. stitchVideoAtPath / stitchFramePaths).  Sets
 /// the telemetry fields to sentinel values (-1) so JS callers can
 /// detect "no retry data available" cleanly.
 - (instancetype)initWithOutputPath:(NSString *)outputPath
@@ -152,65 +152,6 @@ extern NSString *const RNImageStitcherErrorDomain;
                                        seamFinderType:(nullable NSString *)seamFinderType
                                                 error:(NSError **)error;
 
-/// Phase 5: pose-driven stitch.  Same end-to-end shape as
-/// `stitchVideoAtPath` but consumes pre-computed camera poses
-/// (from ARKit/ARCore via RNSARSession) and skips the
-/// brittle features → matching → BundleAdjuster steps.  Internally:
-///
-///   1. Extract maxFrames evenly-spaced frames from the video.
-///   2. Compute each frame's timestamp (fraction × totalSeconds).
-///   3. Match each frame to the nearest pose in `poses` (within
-///      a 100 ms tolerance).
-///   4. Build cv::detail::CameraParams directly from the pose's
-///      quaternion + intrinsics — flips coordinate conventions
-///      between ARKit (Y-up, -Z forward) and OpenCV (Y-down,
-///      +Z forward).
-///   5. Hand cameras to the existing warp + seam + blend pipeline.
-///
-/// `poses` is an NSArray of NSDictionary; each entry has the keys
-/// matching `RNSARFramePose.asDictionary()`:
-///   tx, ty, tz, qx, qy, qz, qw, fx, fy, cx, cy,
-///   imageWidth, imageHeight, timestampMs, trackingState
-/// Frames whose closest pose is missing or beyond tolerance fall
-/// back to the feature-matched path frame-by-frame (degraded but
-/// functional).  When ALL poses are missing the method returns
-/// the same NSError code (1030) so the host can opt to retry via
-/// the non-pose path.
-+ (nullable RNStitchResult *)stitchVideoAtPath:(NSString *)videoPath
-                                           outputPath:(NSString *)outputPath
-                                            maxFrames:(NSInteger)maxFrames
-                                          jpegQuality:(NSInteger)quality
-                                           warperType:(nullable NSString *)warperType
-                                          blenderType:(nullable NSString *)blenderType
-                                       seamFinderType:(nullable NSString *)seamFinderType
-                                                poses:(NSArray<NSDictionary *> *)poses
-                                                error:(NSError **)error;
-
-/// V16 Phase 1: pose-driven stitch over an explicit list of frame
-/// paths.  Sibling of `stitchVideoAtPath:withPoses:` — same compose
-/// stage, but the caller supplies frames as already-on-disk JPEGs
-/// + a 1:1 pose array, so the video extraction + timestamp matching
-/// steps are skipped entirely.
-///
-/// This is the hot path for the "batch-on-AR-keyframes" flow: the
-/// Swift `KeyframeGate` accepts ≤6 frames per capture, each saved
-/// to disk with a known pose; on shutter release we feed those
-/// straight into the same `BundleAdjuster + GraphCutSeamFinder +
-/// MultiBandBlender` pipeline that the video-driven path uses.
-///
-/// `framePaths.count` MUST equal `poses.count` (1:1 mapping; any
-/// downstream filtering happens inside this method).  `framePaths`
-/// must be at least 2 entries.  Pose dictionaries follow the same
-/// shape as `RNSARFramePose.asDictionary()`.
-+ (nullable RNStitchResult *)stitchKeyframePaths:(NSArray<NSString *> *)framePaths
-                                            outputPath:(NSString *)outputPath
-                                           jpegQuality:(NSInteger)quality
-                                            warperType:(nullable NSString *)warperType
-                                           blenderType:(nullable NSString *)blenderType
-                                        seamFinderType:(nullable NSString *)seamFinderType
-                                                 poses:(NSArray<NSDictionary *> *)poses
-                                                 error:(NSError **)error;
-
 /// Normalise the EXIF orientation of `imagePath` in place.
 ///
 /// vision-camera writes photos with the camera-sensor's native
@@ -234,6 +175,33 @@ extern NSString *const RNImageStitcherErrorDomain;
 + (nullable NSDictionary<NSString *, NSNumber *> *)normaliseImageAtPath:(NSString *)imagePath
                                                                   error:(NSError **)error;
 
+/// v0.15 debug — compute the max-inscribed rectangle of the non-black
+/// region of the JPEG at `imagePath` WITHOUT modifying the file.
+/// Returns `{ x, y, width, height, imageWidth, imageHeight }` so the JS
+/// debug harness can overlay the rect on the full image.  Reuses the
+/// same `MaxInscribedRectFromMask` the production crop uses.
++ (nullable NSDictionary<NSString *, NSNumber *> *)computeInscribedRectAtPath:(NSString *)imagePath
+                                                                       error:(NSError **)error;
+
+/// v0.15 debug — crop the JPEG at `imagePath` to the given rectangle
+/// (clamped to image bounds), re-encode at `quality`, overwrite in
+/// place.  Returns the final `{ width, height }`.
++ (nullable NSDictionary<NSString *, NSNumber *> *)cropToRectAtPath:(NSString *)imagePath
+                                                                 x:(NSInteger)x
+                                                                 y:(NSInteger)y
+                                                             width:(NSInteger)width
+                                                            height:(NSInteger)height
+                                                           quality:(NSInteger)quality
+                                                             error:(NSError **)error;
+
+/// v0.15 debug — write a red-tinted overlay JPEG (excluded / sub-threshold
+/// pixels rendered red) next to `imagePath` (suffix ".mask.jpg") so the
+/// harness can show WHY the inscribed rect lands where it does. Returns
+/// `{ maskPath, width, height, excludedPercent }`.
++ (nullable NSDictionary *)debugMaskOverlayAtPath:(NSString *)imagePath
+                                        threshold:(NSInteger)threshold
+                                            error:(NSError **)error;
+
 @end
 
 NS_ASSUME_NONNULL_END