react-native-rectangle-doc-scanner 0.43.0 → 0.45.0

package/README.md

@@ -5,6 +5,10 @@ VisionCamera + Fast-OpenCV powered document scanner template built for React Nat
 ## Features
 - Real-time quad detection using `react-native-fast-opencv`
 - Frame processor worklet executed on the UI thread via `react-native-vision-camera`
+- High-resolution processing (1280p) for accurate corner detection
+- Advanced anchor locking system maintains corner positions during camera movement
+- Intelligent edge detection with optimized Canny parameters (50/150 thresholds)
+- Adaptive smoothing with weighted averaging across multiple frames
 - Resize plugin keeps frame processing fast on lower-end devices
 - Skia overlay visualises detected document contours
 - Stability tracker enables auto-capture once the document is steady
@@ -107,6 +111,37 @@ Passing `children` lets you render any UI on top of the camera preview, so you c
 - The internal frame processor handles document detection; do not override `frameProcessor` in `cameraProps`.
 - Adjust `minStableFrames` or tweak lighting conditions if auto capture is too sensitive or too slow.
 
+## Detection Algorithm
+
+The scanner uses a sophisticated multi-stage pipeline:
+
+1. **Pre-processing** (1280p resolution for accuracy)
+   - Converts frame to grayscale
+   - Applies morphological opening to reduce noise
+   - Gaussian blur for smoother edges
+   - Canny edge detection with 50/150 thresholds
+
+2. **Contour Detection**
+   - Finds external contours using CHAIN_APPROX_SIMPLE
+   - Applies convex hull for better corner detection
+   - Tests multiple epsilon values (0.1%-10%) for approxPolyDP
+   - Validates quadrilaterals for convexity
+
+3. **Anchor Locking System**
+   - Once corners are detected, they "snap" to stable positions
+   - Maintains lock even when camera moves (up to 200px center delta)
+   - Holds anchor for up to 20 missed detections
+   - Adaptive blending between old and new positions for smooth transitions
+   - Builds confidence over time (max 30 frames) for stronger locking
+
+4. **Quad Validation**
+   - Checks area ratio (0.02%-90% of frame)
+   - Validates minimum edge lengths
+   - Ensures reasonable aspect ratios
+   - Filters out non-convex shapes
+
+This approach ensures corners remain locked once detected, allowing you to move the camera slightly without losing the document boundary.
+
 ## Build
 ```sh
 yarn build

package/dist/DocScanner.js

@@ -100,19 +100,19 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
     const lastMeasurementRef = (0, react_1.useRef)(null);
     const frameSizeRef = (0, react_1.useRef)(null);
     const MAX_HISTORY = 5;
-    const SNAP_DISTANCE = 5; // pixels; keep corners locked when movement is tiny
-    const SNAP_CENTER_DISTANCE = 12;
-    const BLEND_DISTANCE = 65; // pixels; softly ease between similar shapes
-    const MAX_CENTER_DELTA = 85;
-    const REJECT_CENTER_DELTA = 145;
-    const MAX_AREA_SHIFT = 0.45;
-    const HISTORY_RESET_DISTANCE = 70;
-    const MIN_AREA_RATIO = 0.0035;
+    const SNAP_DISTANCE = 8; // pixels; keep corners locked when movement is tiny (increased for stronger lock)
+    const SNAP_CENTER_DISTANCE = 18;
+    const BLEND_DISTANCE = 80; // pixels; softly ease between similar shapes (increased)
+    const MAX_CENTER_DELTA = 120; // increased to allow more camera movement
+    const REJECT_CENTER_DELTA = 200; // increased to maintain lock during camera movement
+    const MAX_AREA_SHIFT = 0.55; // more tolerance for perspective changes
+    const HISTORY_RESET_DISTANCE = 90;
+    const MIN_AREA_RATIO = 0.0002;
     const MAX_AREA_RATIO = 0.9;
-    const MIN_EDGE_RATIO = 0.025;
-    const MAX_ANCHOR_MISSES = 12;
+    const MIN_EDGE_RATIO = 0.015;
+    const MAX_ANCHOR_MISSES = 20; // increased to hold anchor longer when detection temporarily fails
     const MIN_CONFIDENCE_TO_HOLD = 2;
-    const MAX_ANCHOR_CONFIDENCE = 20;
+    const MAX_ANCHOR_CONFIDENCE = 30; // increased max confidence for stronger anchoring
     const updateQuad = (0, react_native_worklets_core_1.useRunOnJS)((value) => {
         if (__DEV__) {
             console.log('[DocScanner] quad', value);
@@ -189,10 +189,13 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
             const centerDelta = Math.hypot(candidateCenter.x - anchorCenter.x, candidateCenter.y - anchorCenter.y);
             const areaShift = anchorArea > 0 ? Math.abs(anchorArea - candidateArea) / anchorArea : 0;
             if (centerDelta >= REJECT_CENTER_DELTA || areaShift > 1.2) {
-                const handled = fallbackToAnchor(true);
-                if (handled) {
-                    return;
-                }
+                smoothingBufferRef.current = [sanitized];
+                lastMeasurementRef.current = sanitized;
+                anchorQuadRef.current = candidate;
+                anchorConfidenceRef.current = 1;
+                anchorMissesRef.current = 0;
+                lastQuadRef.current = candidate;
+                setQuad(candidate);
                 return;
             }
             if (delta <= SNAP_DISTANCE && centerDelta <= SNAP_CENTER_DISTANCE && areaShift <= 0.08) {
@@ -246,8 +249,8 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
         try {
             // Report frame size for coordinate transformation
             updateFrameSize(frame.width, frame.height);
-            // Use higher resolution for better accuracy - 960p
-            const ratio = 960 / frame.width;
+            // Use higher resolution for better accuracy - 1280p for improved corner detection
+            const ratio = 1280 / frame.width;
             const width = Math.floor(frame.width * ratio);
             const height = Math.floor(frame.height * ratio);
             step = 'resize';
@@ -276,7 +279,9 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
             react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', mat, mat, gaussianKernel, 0);
             step = 'Canny';
             reportStage(step);
-            react_native_fast_opencv_1.OpenCV.invoke('Canny', mat, mat, 30, 100);
+            // Improved Canny parameters for better edge detection accuracy
+            // Lower threshold (50 -> more edges detected) and higher threshold (150 -> stronger edges kept)
+            react_native_fast_opencv_1.OpenCV.invoke('Canny', mat, mat, 50, 150);
             step = 'createContours';
             reportStage(step);
             const contours = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVectorOfVectors);
@@ -310,7 +315,7 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
                     console.log('[DocScanner] area', area, 'ratio', areaRatio);
                 }
                 // Skip if area ratio is too small or too large
-                if (areaRatio < 0.005 || areaRatio > 0.95) {
+                if (areaRatio < 0.0002 || areaRatio > 0.99) {
                     continue;
                 }
                 // Try to use convex hull for better corner detection

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-rectangle-doc-scanner",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {

package/src/DocScanner.tsx

@@ -116,19 +116,19 @@ export const DocScanner: React.FC<Props> = ({
   const frameSizeRef = useRef<{ width: number; height: number } | null>(null);
 
   const MAX_HISTORY = 5;
-  const SNAP_DISTANCE = 5; // pixels; keep corners locked when movement is tiny
-  const SNAP_CENTER_DISTANCE = 12;
-  const BLEND_DISTANCE = 65; // pixels; softly ease between similar shapes
-  const MAX_CENTER_DELTA = 85;
-  const REJECT_CENTER_DELTA = 145;
-  const MAX_AREA_SHIFT = 0.45;
-  const HISTORY_RESET_DISTANCE = 70;
-  const MIN_AREA_RATIO = 0.0035;
+  const SNAP_DISTANCE = 8; // pixels; keep corners locked when movement is tiny (increased for stronger lock)
+  const SNAP_CENTER_DISTANCE = 18;
+  const BLEND_DISTANCE = 80; // pixels; softly ease between similar shapes (increased)
+  const MAX_CENTER_DELTA = 120; // increased to allow more camera movement
+  const REJECT_CENTER_DELTA = 200; // increased to maintain lock during camera movement
+  const MAX_AREA_SHIFT = 0.55; // more tolerance for perspective changes
+  const HISTORY_RESET_DISTANCE = 90;
+  const MIN_AREA_RATIO = 0.0002;
   const MAX_AREA_RATIO = 0.9;
-  const MIN_EDGE_RATIO = 0.025;
-  const MAX_ANCHOR_MISSES = 12;
+  const MIN_EDGE_RATIO = 0.015;
+  const MAX_ANCHOR_MISSES = 20; // increased to hold anchor longer when detection temporarily fails
   const MIN_CONFIDENCE_TO_HOLD = 2;
-  const MAX_ANCHOR_CONFIDENCE = 20;
+  const MAX_ANCHOR_CONFIDENCE = 30; // increased max confidence for stronger anchoring
 
   const updateQuad = useRunOnJS((value: Point[] | null) => {
     if (__DEV__) {
@@ -224,10 +224,13 @@ export const DocScanner: React.FC<Props> = ({
       const areaShift = anchorArea > 0 ? Math.abs(anchorArea - candidateArea) / anchorArea : 0;
 
       if (centerDelta >= REJECT_CENTER_DELTA || areaShift > 1.2) {
-        const handled = fallbackToAnchor(true);
-        if (handled) {
-          return;
-        }
+        smoothingBufferRef.current = [sanitized];
+        lastMeasurementRef.current = sanitized;
+        anchorQuadRef.current = candidate;
+        anchorConfidenceRef.current = 1;
+        anchorMissesRef.current = 0;
+        lastQuadRef.current = candidate;
+        setQuad(candidate);
         return;
       }
 
@@ -287,8 +290,8 @@ export const DocScanner: React.FC<Props> = ({
       // Report frame size for coordinate transformation
       updateFrameSize(frame.width, frame.height);
 
-      // Use higher resolution for better accuracy - 960p
-      const ratio = 960 / frame.width;
+      // Use higher resolution for better accuracy - 1280p for improved corner detection
+      const ratio = 1280 / frame.width;
       const width = Math.floor(frame.width * ratio);
       const height = Math.floor(frame.height * ratio);
       step = 'resize';
@@ -321,7 +324,9 @@ export const DocScanner: React.FC<Props> = ({
       OpenCV.invoke('GaussianBlur', mat, mat, gaussianKernel, 0);
       step = 'Canny';
       reportStage(step);
-      OpenCV.invoke('Canny', mat, mat, 30, 100);
+      // Improved Canny parameters for better edge detection accuracy
+      // Lower threshold (50 -> more edges detected) and higher threshold (150 -> stronger edges kept)
+      OpenCV.invoke('Canny', mat, mat, 50, 150);
 
       step = 'createContours';
       reportStage(step);
@@ -365,7 +370,7 @@ export const DocScanner: React.FC<Props> = ({
         }
 
         // Skip if area ratio is too small or too large
-        if (areaRatio < 0.005 || areaRatio > 0.95) {
+        if (areaRatio < 0.0002 || areaRatio > 0.99) {
           continue;
         }