react-native-rectangle-doc-scanner 0.44.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 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.015;
-    const MAX_ANCHOR_MISSES = 12;
+    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);
@@ -249,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';
@@ -279,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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-rectangle-doc-scanner",
-  "version": "0.44.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 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.015;
-  const MAX_ANCHOR_MISSES = 12;
+  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__) {
@@ -290,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';
@@ -324,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);