react-native-image-stitcher 0.15.1 → 0.16.0

package/cpp/crop_quad.cpp

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// crop_quad.cpp — OpenCV implementation of the free-quad perspective
+// crop (`cropToQuad`), the only net-new native code for item-7 of the
+// first-time-user guidance flow.
+//
+// Pairs with the EXISTING axis-aligned crop (cropToRectAtPath on iOS /
+// cropToRect on Android).  Where that crop slices a sub-rectangle out of
+// the panorama, this one takes 4 user-dragged corners (a skewed
+// quadrilateral) and perspective-rectifies them into an upright rectangle
+// — the editor in src/camera/RectCropPreview.tsx picks `cropToQuad` over
+// `cropToRect` whenever the dragged quad isn't ~axis-aligned.
+//
+// Why a separate .cpp (not folded into stitcher.cpp): the geometry core
+// (quadDstRect / isQuadAcceptable) is the OpenCV-FREE, unit-tested
+// cpp/crop_quad.hpp; this file is JUST the thin cv:: warp around it, kept
+// out of stitcher.cpp's translation unit so the test suite can link the
+// header without pulling in the whole stitch pipeline.
+//
+// Both platform bridges (iOS OpenCVStitcher.mm, Android BatchStitcher.kt)
+// duplicate this warp in their own native language today — see the
+// integrator notes in the item-7 handoff — so this file is the shared
+// C++ reference + the home of the canvasExceedsGuard wiring.  Wire it
+// into a translation unit (the pod / the JNI lib) when the native crop is
+// routed through shared C++ rather than per-platform OpenCV bindings.
+
+// OpenCV's headers redefine NO/YES on platforms whose prefix.pch already
+// has the ObjC bool macros; undef defensively (no-op off iOS).
+#ifdef NO
+#undef NO
+#endif
+#ifdef YES
+#undef YES
+#endif
+
+#include <opencv2/opencv.hpp>
+#include <opencv2/imgproc.hpp>
+
+#include <string>
+#include <vector>
+
+#include "crop_quad.hpp"
+#include "warp_guard.hpp"
+
+namespace retailens {
+
+// Result of a cropToQuad call.  `ok == false` carries a human-readable
+// `error` (the bridge maps it to NSError / Promise.reject); on success
+// `width`/`height` are the written output dimensions.
+struct CropQuadResult {
+  bool ok = false;
+  std::string error;
+  int width = 0;
+  int height = 0;
+};
+
+// Perspective-rectify the quad `q` (4 ORDERED [TL, TR, BR, BL] image-pixel
+// corners) out of the image at `inPath` into an upright w×h rectangle,
+// written to `outPath` as a JPEG at `quality` (clamped to [1, 100]).
+//
+// Guards, in order (each is a hard reject — NO partial output is written):
+//   1. inPath decodes (cv::imread non-empty).
+//   2. isQuadAcceptable — convex + min-area + within the decoded image
+//      bounds.  A degenerate / non-convex / out-of-bounds quad is rejected
+//      here, before any allocation.
+//   3. quadDstRect yields a positive w×h.
+//   4. canvasExceedsGuard(w, h) — the SAME blend-canvas guard the stitch
+//      pipeline uses.  A near-collinear quad whose averaged opposite-edge
+//      lengths still multiply to a multi-gigapixel output (e.g. a 1 px ×
+//      40000 px sliver dragged across a wide pano) can't OOM the device:
+//      the output Mat is never allocated when this fires.
+//
+// The warp itself is cv::getPerspectiveTransform(src → axis-aligned dst)
+// + cv::warpPerspective to a w×h canvas.  `outPath == inPath` is allowed
+// (overwrite in place), matching cropToRect's contract.
+CropQuadResult cropQuadToFile(const std::string& inPath,
+                              const std::string& outPath,
+                              const CropQuad& q,
+                              int quality) {
+  CropQuadResult result;
+
+  cv::Mat img = cv::imread(inPath, cv::IMREAD_COLOR);
+  if (img.empty()) {
+    result.error = "Could not decode image at " + inPath;
+    return result;
+  }
+
+  // Guard 2 — geometry: convex, non-degenerate, inside the decoded image.
+  if (!isQuadAcceptable(q, static_cast<double>(img.cols),
+                        static_cast<double>(img.rows))) {
+    result.error =
+        "Crop quad is degenerate (non-convex, zero-area, or out of bounds)";
+    return result;
+  }
+
+  // Guard 3 — positive destination size.
+  const QuadDstSize dst = quadDstRect(q);
+  if (dst.width <= 0 || dst.height <= 0) {
+    result.error = "Crop quad rectifies to a non-positive rectangle";
+    return result;
+  }
+
+  // Guard 4 — output-canvas OOM net (shared with the stitch pipeline).
+  if (canvasExceedsGuard(dst.width, dst.height)) {
+    result.error = "Crop quad output canvas exceeds the size guard (" +
+                   std::to_string(dst.width) + "x" +
+                   std::to_string(dst.height) + ")";
+    return result;
+  }
+
+  const cv::Point2f src[4] = {
+      cv::Point2f(static_cast<float>(q.tl.x), static_cast<float>(q.tl.y)),
+      cv::Point2f(static_cast<float>(q.tr.x), static_cast<float>(q.tr.y)),
+      cv::Point2f(static_cast<float>(q.br.x), static_cast<float>(q.br.y)),
+      cv::Point2f(static_cast<float>(q.bl.x), static_cast<float>(q.bl.y)),
+  };
+  const cv::Point2f dstPts[4] = {
+      cv::Point2f(0.0f, 0.0f),
+      cv::Point2f(static_cast<float>(dst.width), 0.0f),
+      cv::Point2f(static_cast<float>(dst.width),
+                  static_cast<float>(dst.height)),
+      cv::Point2f(0.0f, static_cast<float>(dst.height)),
+  };
+
+  cv::Mat warped;
+  try {
+    const cv::Mat transform = cv::getPerspectiveTransform(src, dstPts);
+    cv::warpPerspective(img, warped, transform,
+                        cv::Size(dst.width, dst.height),
+                        cv::INTER_LINEAR);
+  } catch (const cv::Exception& e) {
+    result.error = std::string("Perspective warp failed: ") + e.what();
+    return result;
+  }
+  if (warped.empty()) {
+    result.error = "Perspective warp produced an empty image";
+    return result;
+  }
+
+  int q255 = quality;
+  if (q255 < 1) q255 = 1;
+  if (q255 > 100) q255 = 100;
+  const std::vector<int> writeParams = {cv::IMWRITE_JPEG_QUALITY, q255};
+  bool wrote = false;
+  try {
+    wrote = cv::imwrite(outPath, warped, writeParams);
+  } catch (const cv::Exception& e) {
+    result.error = std::string("Could not write cropped image: ") + e.what();
+    return result;
+  }
+  if (!wrote) {
+    result.error = "Could not write cropped image to " + outPath;
+    return result;
+  }
+
+  result.ok = true;
+  result.width = warped.cols;
+  result.height = warped.rows;
+  return result;
+}
+
+}  // namespace retailens

package/cpp/crop_quad.hpp

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+#include <cmath>
+#include <cstdint>
+
+// ─────────────────────────────────────────────────────────────────────
+// Free-quad crop geometry — the OpenCV-FREE, unit-testable core of the
+// item-7 draggable-corner crop (`cropToQuad`).  The actual perspective
+// warp (cv::getPerspectiveTransform + cv::warpPerspective) lives next to
+// the existing axis-aligned crop in the platform bridges; this header is
+// JUST the two pure predicates worth testing in isolation:
+//
+//   - quadDstRect(quad)       → the {w,h} of the upright destination
+//                               rectangle the quad rectifies INTO.
+//   - isQuadAcceptable(quad)  → convex + min-area + within-bounds gate
+//                               the warp must pass before allocating.
+//
+// Header-only + zero cv:: dependency on purpose — same posture as
+// warp_guard.hpp.  These are the C++ twins of the JS-side helpers in
+// src/camera/cropGeometry.ts (rectSizeForQuad / isQuadValid); the math
+// is duplicated per the repo's "duplicate stage code, DRY when proven"
+// convention so a native caller never has to round-trip through JS to
+// validate a quad.
+//
+// Corner-order contract: every function below assumes the 4 points are
+// in canonical [TL, TR, BR, BL] (clockwise from top-left) winding — the
+// order src/camera/cropGeometry.ts:orderQuadCorners produces and the
+// order RectCropResult.quad carries.  Pass un-ordered points and the
+// edge-length / convexity math is meaningless.
+// ─────────────────────────────────────────────────────────────────────
+
+namespace retailens {
+
+// A single corner in image-pixel space (origin = image top-left).
+struct QuadPoint {
+  double x = 0.0;
+  double y = 0.0;
+};
+
+// Exactly four corners, in [TL, TR, BR, BL] order.
+struct CropQuad {
+  QuadPoint tl;
+  QuadPoint tr;
+  QuadPoint br;
+  QuadPoint bl;
+};
+
+// Integer destination-rectangle size the quad rectifies into.
+struct QuadDstSize {
+  int width = 0;
+  int height = 0;
+};
+
+// Euclidean distance between two corners.
+inline double quadPointDistance(const QuadPoint& a, const QuadPoint& b) {
+  const double dx = a.x - b.x;
+  const double dy = a.y - b.y;
+  return std::sqrt(dx * dx + dy * dy);
+}
+
+// Target rectangle size for the perspective `dst` quad, derived from the
+// 4 ORDERED ([TL, TR, BR, BL]) image-pixel corners:
+//   - width  = average of the top edge (TL→TR) and bottom edge (BL→BR).
+//   - height = average of the left edge (TL→BL) and right edge (TR→BR).
+//
+// Averaging opposite edges gives a stable output size for a skewed quad
+// (each pair of opposite edges differs under perspective; the mean is the
+// least-distorting target).  Rounds to whole pixels — the warp allocates
+// an integer-sized output Mat.  Mirrors cropGeometry.ts:rectSizeForQuad
+// so iOS / Android / JS agree on the output dimensions bit-for-bit.
+//
+// A degenerate quad (all-collinear, zero-size) yields a 0×0 or 1×N size;
+// the caller GUARDS this with isQuadAcceptable + canvasExceedsGuard before
+// allocating, so this function never has to reject — it only measures.
+inline QuadDstSize quadDstRect(const CropQuad& q) {
+  const double top = quadPointDistance(q.tl, q.tr);
+  const double bottom = quadPointDistance(q.bl, q.br);
+  const double left = quadPointDistance(q.tl, q.bl);
+  const double right = quadPointDistance(q.tr, q.br);
+  QuadDstSize size;
+  size.width = static_cast<int>(std::lround((top + bottom) / 2.0));
+  size.height = static_cast<int>(std::lround((left + right) / 2.0));
+  return size;
+}
+
+// 2× the signed area of the quad via the shoelace formula.  Positive for
+// one winding, negative for the other, ~0 for a degenerate (collinear)
+// quad.  Sign is winding-dependent; callers that care about magnitude
+// (min-area) take the absolute value.
+inline double quadSignedArea2(const CropQuad& q) {
+  const QuadPoint p[4] = {q.tl, q.tr, q.br, q.bl};
+  double sum = 0.0;
+  for (int i = 0; i < 4; ++i) {
+    const QuadPoint& a = p[i];
+    const QuadPoint& b = p[(i + 1) % 4];
+    sum += a.x * b.y - b.x * a.y;
+  }
+  return sum;
+}
+
+// Convexity test: all four consecutive edge cross-products share one sign
+// (zero allowed for a straight, axis-aligned corner).  Rejects the self-
+// intersecting "bowtie" quads a free-drag editor can produce, which a
+// perspective warp can't rectify.  Winding-agnostic.  Mirrors the
+// `isConvex` helper in cropGeometry.ts.
+inline bool quadIsConvex(const CropQuad& q) {
+  const QuadPoint p[4] = {q.tl, q.tr, q.br, q.bl};
+  int sign = 0;
+  for (int i = 0; i < 4; ++i) {
+    const QuadPoint& a = p[i];
+    const QuadPoint& b = p[(i + 1) % 4];
+    const QuadPoint& c = p[(i + 2) % 4];
+    const double cross =
+        (b.x - a.x) * (c.y - b.y) - (b.y - a.y) * (c.x - b.x);
+    if (cross != 0.0) {
+      const int s = (cross > 0.0) ? 1 : -1;
+      if (sign == 0) {
+        sign = s;
+      } else if (s != sign) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+// True when the 4 ordered ([TL, TR, BR, BL]) corners form a quad the
+// perspective warp can safely rectify:
+//   1. **Convex** — no self-intersection (quadIsConvex).
+//   2. **Non-degenerate area** — |signed area| ≥ `minArea` (default 1 px²);
+//      rejects all-collinear / zero-size quads.
+//   3. **Within bounds** — every corner lies inside [0..imageW]×[0..imageH]
+//      (a half-pixel epsilon absorbs the lround in the JS letterbox
+//      inverse).  Pass imageW <= 0 OR imageH <= 0 to SKIP the bounds
+//      check (the caller doesn't know the image size yet).
+//
+// The companion to warp_guard.hpp:canvasExceedsGuard — that guards the
+// OUTPUT canvas against an OOM; this guards the INPUT quad against being
+// geometrically unwarpable.  Both must pass before warpPerspective runs.
+inline bool isQuadAcceptable(const CropQuad& q,
+                             double imageW = 0.0,
+                             double imageH = 0.0,
+                             double minArea = 1.0) {
+  if (!quadIsConvex(q)) {
+    return false;
+  }
+  if (std::fabs(quadSignedArea2(q)) < minArea * 2.0) {
+    return false;
+  }
+  if (imageW > 0.0 && imageH > 0.0) {
+    const QuadPoint p[4] = {q.tl, q.tr, q.br, q.bl};
+    const double eps = 0.5;
+    for (int i = 0; i < 4; ++i) {
+      if (p[i].x < -eps || p[i].x > imageW + eps ||
+          p[i].y < -eps || p[i].y > imageH + eps) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+}  // namespace retailens