@sanctum-key/react-native-sdk 1.0.58 → 1.0.59

package/src/utils/cropByObb.ts

@@ -4,6 +4,22 @@ import * as ImageManipulator from "expo-image-manipulator";
 
 type Point = [number, number];
 
+type PixelBbox = {
+  minX: number;
+  minY: number;
+  width: number;
+  height: number;
+};
+
+type BboxOrientation = 'direct' | 'clockwise' | 'counter-clockwise' | 'upside-down';
+
+type OrientedBboxCandidate = {
+  bbox: PixelBbox;
+  orientation: BboxOrientation;
+  inFrameRatio: number;
+  score: number;
+};
+
 export const OBB_CONFIDENCE_THRESHOLD = 0.85;
 
 
@@ -84,6 +100,105 @@ function computeAabb(points: Point[]) {
   return { minX, minY, maxX, maxY, width: maxX - minX, height: maxY - minY };
 }
 
+function getInFrameRatio(bbox: PixelBbox, imageWidth: number, imageHeight: number): number {
+  const left = Math.max(0, bbox.minX);
+  const top = Math.max(0, bbox.minY);
+  const right = Math.min(imageWidth, bbox.minX + bbox.width);
+  const bottom = Math.min(imageHeight, bbox.minY + bbox.height);
+  const intersectionArea = Math.max(0, right - left) * Math.max(0, bottom - top);
+  const bboxArea = bbox.width * bbox.height;
+
+  return bboxArea > 0 ? intersectionArea / bboxArea : 0;
+}
+
+/**
+ * The API can return OBB coordinates in the camera sensor's pixel space while
+ * ImageManipulator returns an EXIF-normalized image. On phones held sideways,
+ * those spaces are 90 degrees apart. Select the representation which best fits
+ * the normalized image instead of applying the server coordinates blindly.
+ */
+function resolveBboxOrientation(
+  bbox: PixelBbox,
+  imageWidth: number,
+  imageHeight: number,
+  preferredCardOrientation: 'landscape' | 'portrait' | 'either' = 'landscape',
+): OrientedBboxCandidate {
+  const candidates: Array<{ bbox: PixelBbox; orientation: BboxOrientation; priority: number }> = [
+    {
+      bbox,
+      orientation: 'direct',
+      priority: 0.75,
+    },
+    {
+      // Source canvas is imageHeight x imageWidth and is rotated clockwise.
+      bbox: {
+        minX: imageWidth - bbox.minY - bbox.height,
+        minY: bbox.minX,
+        width: bbox.height,
+        height: bbox.width,
+      },
+      orientation: 'clockwise',
+      priority: 0,
+    },
+    {
+      // Source canvas is imageHeight x imageWidth and is rotated counter-clockwise.
+      bbox: {
+        minX: bbox.minY,
+        minY: imageHeight - bbox.minX - bbox.width,
+        width: bbox.height,
+        height: bbox.width,
+      },
+      orientation: 'counter-clockwise',
+      priority: 0,
+    },
+    {
+      bbox: {
+        minX: imageWidth - bbox.minX - bbox.width,
+        minY: imageHeight - bbox.minY - bbox.height,
+        width: bbox.width,
+        height: bbox.height,
+      },
+      orientation: 'upside-down',
+      priority: -0.25,
+    },
+  ];
+
+  const scoredCandidates = candidates.map((candidate) => {
+    const candidateBbox = candidate.bbox;
+    const inFrameRatio = getInFrameRatio(candidateBbox, imageWidth, imageHeight);
+    const centerX = candidateBbox.minX + candidateBbox.width / 2;
+    const centerY = candidateBbox.minY + candidateBbox.height / 2;
+    const normalizedCenterDistance = Math.hypot(
+      (centerX - imageWidth / 2) / Math.max(1, imageWidth / 2),
+      (centerY - imageHeight / 2) / Math.max(1, imageHeight / 2),
+    );
+    const centerScore = 1 - Math.min(1, normalizedCenterDistance);
+
+    const isLandscapeCard = candidateBbox.width >= candidateBbox.height;
+    const preferredOrientationScore = preferredCardOrientation === 'either'
+      ? 0
+      : ((preferredCardOrientation === 'landscape') === isLandscapeCard ? 1 : 0);
+    const areaRatio = (candidateBbox.width * candidateBbox.height) / Math.max(1, imageWidth * imageHeight);
+    const plausibleAreaScore = Math.min(1, areaRatio / 0.08);
+
+    return {
+      bbox: candidateBbox,
+      orientation: candidate.orientation,
+      inFrameRatio,
+      score:
+        inFrameRatio * 100
+        + centerScore * 3
+        + preferredOrientationScore * 2
+        + plausibleAreaScore
+        + candidate.priority,
+    };
+  });
+
+  return scoredCandidates.reduce((best, candidate) => (
+    candidate.score > best.score ? candidate : best
+  ));
+}
+
 async function cropWeb(uri: string, points: Point[]): Promise<string> {
   return new Promise((resolve, reject) => {
     const img = new Image();
@@ -159,7 +274,12 @@ async function normalizeOrientationAndGetDimensions(
 }
 
 
-export async function cropImageWithBBoxWithTolerance(uri: string, bbox: any, tolerance: number = 0.02): Promise<string> {
+export async function cropImageWithBBoxWithTolerance(
+  uri: string,
+  bbox: any,
+  tolerance: number = 0.02,
+  preferredCardOrientation: 'landscape' | 'portrait' | 'either' = 'landscape',
+): Promise<string> {
   return new Promise<string>((resolve) => {
     let isResolved = false;
 
@@ -195,10 +315,44 @@ export async function cropImageWithBBoxWithTolerance(uri: string, bbox: any, tol
           pixelWidth = bbox.width * actualWidth;
           pixelHeight = bbox.height * actualHeight;
         } else {
-          pixelMinX = bbox.minX;
-          pixelMinY = bbox.minY;
-          pixelWidth = bbox.width;
-          pixelHeight = bbox.height;
+          const resolvedBbox = resolveBboxOrientation(
+            {
+              minX: bbox.minX,
+              minY: bbox.minY,
+              width: bbox.width,
+              height: bbox.height,
+            },
+            actualWidth,
+            actualHeight,
+            preferredCardOrientation,
+          );
+
+          if (resolvedBbox.inFrameRatio < 0.6) {
+            if (!isResolved) {
+              isResolved = true;
+              clearTimeout(timeout);
+              console.warn('OBB does not match the normalized image bounds; returning the full image.', {
+                bbox,
+                imageSize: { width: actualWidth, height: actualHeight },
+                bestOrientation: resolvedBbox.orientation,
+                inFrameRatio: resolvedBbox.inFrameRatio,
+              });
+              resolve(normalizedUri);
+            }
+            return;
+          }
+
+          if (resolvedBbox.orientation !== 'direct') {
+            console.info('Adjusted OBB coordinates for the normalized camera orientation.', {
+              orientation: resolvedBbox.orientation,
+              imageSize: { width: actualWidth, height: actualHeight },
+            });
+          }
+
+          pixelMinX = resolvedBbox.bbox.minX;
+          pixelMinY = resolvedBbox.bbox.minY;
+          pixelWidth = resolvedBbox.bbox.width;
+          pixelHeight = resolvedBbox.bbox.height;
         }
 
         // STEP 3: Add tolerance and clamp to image bounds.
@@ -309,4 +463,4 @@ export async function cropToCenterScanArea(
       }
     })();
   });
-}
+}