react-native-rectangle-doc-scanner 0.39.0 → 0.40.0

package/dist/DocScanner.js

@@ -42,6 +42,7 @@ const react_native_worklets_core_1 = require("react-native-worklets-core");
 const react_native_fast_opencv_1 = require("react-native-fast-opencv");
 const overlay_1 = require("./utils/overlay");
 const stability_1 = require("./utils/stability");
+const quad_1 = require("./utils/quad");
 const isConvexQuadrilateral = (points) => {
     'worklet';
     try {
@@ -93,50 +94,52 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
     }, [requestPermission]);
     const lastQuadRef = (0, react_1.useRef)(null);
     const smoothingBufferRef = (0, react_1.useRef)([]);
+    const anchorQuadRef = (0, react_1.useRef)(null);
+    const missingFrameCountRef = (0, react_1.useRef)(0);
+    const MAX_HISTORY = 5;
+    const SNAP_DISTANCE = 5; // pixels; keep corners locked when movement is tiny
+    const BLEND_DISTANCE = 20; // pixels; softly ease between similar shapes
+    const BLEND_ALPHA = 0.35;
     const updateQuad = (0, react_native_worklets_core_1.useRunOnJS)((value) => {
         if (__DEV__) {
             console.log('[DocScanner] quad', value);
         }
-        // Add to smoothing buffer
-        smoothingBufferRef.current.push(value);
-        // Keep only last 3 frames for smoothing
-        if (smoothingBufferRef.current.length > 3) {
-            smoothingBufferRef.current.shift();
-        }
-        // If we have a valid quad, smooth it
-        if (value && value.length === 4) {
-            // Average with previous frames if available
-            if (smoothingBufferRef.current.length >= 2) {
-                const validQuads = smoothingBufferRef.current.filter(q => q !== null && q.length === 4);
-                if (validQuads.length >= 2) {
-                    // Average the positions
-                    const smoothed = value.map((_, idx) => {
-                        let sumX = 0;
-                        let sumY = 0;
-                        validQuads.forEach(quad => {
-                            sumX += quad[idx].x;
-                            sumY += quad[idx].y;
-                        });
-                        return {
-                            x: sumX / validQuads.length,
-                            y: sumY / validQuads.length,
-                        };
-                    });
-                    lastQuadRef.current = smoothed;
-                    setQuad(smoothed);
-                    return;
-                }
+        if (!(0, quad_1.isValidQuad)(value)) {
+            missingFrameCountRef.current += 1;
+            if (lastQuadRef.current && missingFrameCountRef.current <= 2) {
+                setQuad(lastQuadRef.current);
+                return;
             }
-            lastQuadRef.current = value;
-            setQuad(value);
+            smoothingBufferRef.current = [];
+            anchorQuadRef.current = null;
+            lastQuadRef.current = null;
+            setQuad(null);
+            return;
         }
-        else if (lastQuadRef.current) {
-            // Keep showing last quad for 1 frame to reduce flickering
-            setQuad(lastQuadRef.current);
+        missingFrameCountRef.current = 0;
+        const ordered = (0, quad_1.orderQuadPoints)(value);
+        const sanitized = (0, quad_1.sanitizeQuad)(ordered);
+        smoothingBufferRef.current.push(sanitized);
+        if (smoothingBufferRef.current.length > MAX_HISTORY) {
+            smoothingBufferRef.current.shift();
         }
-        else {
-            setQuad(null);
+        const history = smoothingBufferRef.current;
+        const hasHistory = history.length >= 2;
+        let candidate = hasHistory ? (0, quad_1.averageQuad)(history) : sanitized;
+        const anchor = anchorQuadRef.current;
+        if (anchor && (0, quad_1.isValidQuad)(anchor)) {
+            const delta = (0, quad_1.quadDistance)(candidate, anchor);
+            if (delta <= SNAP_DISTANCE) {
+                candidate = anchor;
+            }
+            else if (delta <= BLEND_DISTANCE) {
+                candidate = (0, quad_1.blendQuads)(anchor, candidate, BLEND_ALPHA);
+            }
         }
+        candidate = (0, quad_1.orderQuadPoints)(candidate);
+        anchorQuadRef.current = candidate;
+        lastQuadRef.current = candidate;
+        setQuad(candidate);
     }, []);
     const reportError = (0, react_native_worklets_core_1.useRunOnJS)((step, error) => {
         const message = error instanceof Error ? error.message : `${error}`;

package/dist/utils/quad.d.ts

@@ -0,0 +1,8 @@
+import type { Point } from '../types';
+export declare const isValidPoint: (point: Point | null | undefined) => point is Point;
+export declare const isValidQuad: (quad: Point[] | null | undefined) => quad is Point[];
+export declare const orderQuadPoints: (quad: Point[]) => Point[];
+export declare const quadDistance: (a: Point[], b: Point[]) => number;
+export declare const averageQuad: (quads: Point[][]) => Point[];
+export declare const blendQuads: (base: Point[], target: Point[], alpha: number) => Point[];
+export declare const sanitizeQuad: (quad: Point[]) => Point[];

package/dist/utils/quad.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeQuad = exports.blendQuads = exports.averageQuad = exports.quadDistance = exports.orderQuadPoints = exports.isValidQuad = exports.isValidPoint = void 0;
+const POINT_EPSILON = 1e-3;
+const isFiniteNumber = (value) => Number.isFinite(value) && !Number.isNaN(value);
+const isValidPoint = (point) => {
+    if (!point) {
+        return false;
+    }
+    if (!isFiniteNumber(point.x) || !isFiniteNumber(point.y)) {
+        return false;
+    }
+    if (Math.abs(point.x) > 1_000_000 || Math.abs(point.y) > 1_000_000) {
+        return false;
+    }
+    return true;
+};
+exports.isValidPoint = isValidPoint;
+const isValidQuad = (quad) => {
+    return Array.isArray(quad) && quad.length === 4 && quad.every(exports.isValidPoint);
+};
+exports.isValidQuad = isValidQuad;
+const clonePoint = (point) => ({ x: point.x, y: point.y });
+const orderQuadPoints = (quad) => {
+    const centroid = quad.reduce((acc, point) => ({ x: acc.x + point.x / quad.length, y: acc.y + point.y / quad.length }), { x: 0, y: 0 });
+    const sorted = quad
+        .slice()
+        .map(clonePoint)
+        .sort((a, b) => {
+        const angleA = Math.atan2(a.y - centroid.y, a.x - centroid.x);
+        const angleB = Math.atan2(b.y - centroid.y, b.x - centroid.x);
+        return angleA - angleB;
+    });
+    const topLeftIndex = sorted.reduce((selectedIndex, point, index) => {
+        const currentScore = point.x + point.y;
+        const selectedPoint = sorted[selectedIndex];
+        const selectedScore = selectedPoint.x + selectedPoint.y;
+        if (currentScore < selectedScore - POINT_EPSILON) {
+            return index;
+        }
+        return selectedIndex;
+    }, 0);
+    return [...sorted.slice(topLeftIndex), ...sorted.slice(0, topLeftIndex)];
+};
+exports.orderQuadPoints = orderQuadPoints;
+const quadDistance = (a, b) => {
+    if (!(0, exports.isValidQuad)(a) || !(0, exports.isValidQuad)(b)) {
+        return Number.POSITIVE_INFINITY;
+    }
+    let total = 0;
+    for (let i = 0; i < 4; i += 1) {
+        total += Math.hypot(a[i].x - b[i].x, a[i].y - b[i].y);
+    }
+    return total / 4;
+};
+exports.quadDistance = quadDistance;
+const averageQuad = (quads) => {
+    if (!Array.isArray(quads) || quads.length === 0) {
+        throw new Error('Cannot average empty quad array');
+    }
+    const accum = quads[0].map(() => ({ x: 0, y: 0 }));
+    quads.forEach((quad) => {
+        quad.forEach((point, index) => {
+            accum[index].x += point.x;
+            accum[index].y += point.y;
+        });
+    });
+    return accum.map((point) => ({ x: point.x / quads.length, y: point.y / quads.length }));
+};
+exports.averageQuad = averageQuad;
+const blendQuads = (base, target, alpha) => {
+    if (alpha <= 0) {
+        return base.map(clonePoint);
+    }
+    if (alpha >= 1) {
+        return target.map(clonePoint);
+    }
+    return base.map((point, index) => ({
+        x: point.x * (1 - alpha) + target[index].x * alpha,
+        y: point.y * (1 - alpha) + target[index].y * alpha,
+    }));
+};
+exports.blendQuads = blendQuads;
+const sanitizeQuad = (quad) => {
+    if (!(0, exports.isValidQuad)(quad)) {
+        throw new Error('Cannot sanitise invalid quad');
+    }
+    return quad.map((point) => ({
+        x: Number.isFinite(point.x) ? point.x : 0,
+        y: Number.isFinite(point.y) ? point.y : 0,
+    }));
+};
+exports.sanitizeQuad = sanitizeQuad;

package/dist/utils/stability.js

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkStability = checkStability;
+const quad_1 = require("./quad");
 let last = null;
 let stable = 0;
+const STABILITY_DISTANCE = 8;
 function checkStability(current) {
-    if (!current) {
+    if (!(0, quad_1.isValidQuad)(current)) {
         stable = 0;
         last = null;
         return 0;
@@ -14,8 +16,8 @@ function checkStability(current) {
         stable = 1;
         return stable;
     }
-    const diff = Math.hypot(avg(current.map((p) => p.x)) - avg(last.map((p) => p.x)), avg(current.map((p) => p.y)) - avg(last.map((p) => p.y)));
-    if (diff < 10) {
+    const diff = (0, quad_1.quadDistance)(current, last);
+    if (diff < STABILITY_DISTANCE) {
         stable++;
     }
     else {
@@ -24,4 +26,3 @@ function checkStability(current) {
     last = current;
     return stable;
 }
-const avg = (arr) => arr.reduce((a, b) => a + b, 0) / arr.length;

package/package.json

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

package/src/DocScanner.tsx

@@ -14,6 +14,7 @@ import {
 } from 'react-native-fast-opencv';
 import { Overlay } from './utils/overlay';
 import { checkStability } from './utils/stability';
+import { averageQuad, blendQuads, isValidQuad, orderQuadPoints, quadDistance, sanitizeQuad } from './utils/quad';
 import type { Point } from './types';
 
 const isConvexQuadrilateral = (points: Point[]) => {
@@ -97,56 +98,64 @@ export const DocScanner: React.FC<Props> = ({
   }, [requestPermission]);
 
   const lastQuadRef = useRef<Point[] | null>(null);
-  const smoothingBufferRef = useRef<(Point[] | null)[]>([]);
+  const smoothingBufferRef = useRef<Point[][]>([]);
+  const anchorQuadRef = useRef<Point[] | null>(null);
+  const missingFrameCountRef = useRef(0);
+
+  const MAX_HISTORY = 5;
+  const SNAP_DISTANCE = 5; // pixels; keep corners locked when movement is tiny
+  const BLEND_DISTANCE = 20; // pixels; softly ease between similar shapes
+  const BLEND_ALPHA = 0.35;
 
   const updateQuad = useRunOnJS((value: Point[] | null) => {
     if (__DEV__) {
       console.log('[DocScanner] quad', value);
     }
 
-    // Add to smoothing buffer
-    smoothingBufferRef.current.push(value);
+    if (!isValidQuad(value)) {
+      missingFrameCountRef.current += 1;
+
+      if (lastQuadRef.current && missingFrameCountRef.current <= 2) {
+        setQuad(lastQuadRef.current);
+        return;
+      }
+
+      smoothingBufferRef.current = [];
+      anchorQuadRef.current = null;
+      lastQuadRef.current = null;
+      setQuad(null);
+      return;
+    }
+
+    missingFrameCountRef.current = 0;
 
-    // Keep only last 3 frames for smoothing
-    if (smoothingBufferRef.current.length > 3) {
+    const ordered = orderQuadPoints(value);
+    const sanitized = sanitizeQuad(ordered);
+
+    smoothingBufferRef.current.push(sanitized);
+    if (smoothingBufferRef.current.length > MAX_HISTORY) {
       smoothingBufferRef.current.shift();
     }
 
-    // If we have a valid quad, smooth it
-    if (value && value.length === 4) {
-      // Average with previous frames if available
-      if (smoothingBufferRef.current.length >= 2) {
-        const validQuads = smoothingBufferRef.current.filter(q => q !== null && q.length === 4) as Point[][];
-
-        if (validQuads.length >= 2) {
-          // Average the positions
-          const smoothed: Point[] = value.map((_, idx) => {
-            let sumX = 0;
-            let sumY = 0;
-            validQuads.forEach(quad => {
-              sumX += quad[idx].x;
-              sumY += quad[idx].y;
-            });
-            return {
-              x: sumX / validQuads.length,
-              y: sumY / validQuads.length,
-            };
-          });
-
-          lastQuadRef.current = smoothed;
-          setQuad(smoothed);
-          return;
-        }
-      }
+    const history = smoothingBufferRef.current;
+    const hasHistory = history.length >= 2;
+    let candidate = hasHistory ? averageQuad(history) : sanitized;
 
-      lastQuadRef.current = value;
-      setQuad(value);
-    } else if (lastQuadRef.current) {
-      // Keep showing last quad for 1 frame to reduce flickering
-      setQuad(lastQuadRef.current);
-    } else {
-      setQuad(null);
+    const anchor = anchorQuadRef.current;
+    if (anchor && isValidQuad(anchor)) {
+      const delta = quadDistance(candidate, anchor);
+
+      if (delta <= SNAP_DISTANCE) {
+        candidate = anchor;
+      } else if (delta <= BLEND_DISTANCE) {
+        candidate = blendQuads(anchor, candidate, BLEND_ALPHA);
+      }
     }
+
+    candidate = orderQuadPoints(candidate);
+    anchorQuadRef.current = candidate;
+    lastQuadRef.current = candidate;
+    setQuad(candidate);
   }, []);
 
   const reportError = useRunOnJS((step: string, error: unknown) => {

package/src/utils/quad.ts

@@ -0,0 +1,111 @@
+import type { Point } from '../types';
+
+const POINT_EPSILON = 1e-3;
+
+const isFiniteNumber = (value: number): boolean => Number.isFinite(value) && !Number.isNaN(value);
+
+export const isValidPoint = (point: Point | null | undefined): point is Point => {
+  if (!point) {
+    return false;
+  }
+
+  if (!isFiniteNumber(point.x) || !isFiniteNumber(point.y)) {
+    return false;
+  }
+
+  if (Math.abs(point.x) > 1_000_000 || Math.abs(point.y) > 1_000_000) {
+    return false;
+  }
+
+  return true;
+};
+
+export const isValidQuad = (quad: Point[] | null | undefined): quad is Point[] => {
+  return Array.isArray(quad) && quad.length === 4 && quad.every(isValidPoint);
+};
+
+const clonePoint = (point: Point): Point => ({ x: point.x, y: point.y });
+
+export const orderQuadPoints = (quad: Point[]): Point[] => {
+  const centroid = quad.reduce(
+    (acc, point) => ({ x: acc.x + point.x / quad.length, y: acc.y + point.y / quad.length }),
+    { x: 0, y: 0 },
+  );
+
+  const sorted = quad
+    .slice()
+    .map(clonePoint)
+    .sort((a, b) => {
+      const angleA = Math.atan2(a.y - centroid.y, a.x - centroid.x);
+      const angleB = Math.atan2(b.y - centroid.y, b.x - centroid.x);
+      return angleA - angleB;
+    });
+
+  const topLeftIndex = sorted.reduce((selectedIndex, point, index) => {
+    const currentScore = point.x + point.y;
+    const selectedPoint = sorted[selectedIndex];
+    const selectedScore = selectedPoint.x + selectedPoint.y;
+    if (currentScore < selectedScore - POINT_EPSILON) {
+      return index;
+    }
+    return selectedIndex;
+  }, 0);
+
+  return [...sorted.slice(topLeftIndex), ...sorted.slice(0, topLeftIndex)];
+};
+
+export const quadDistance = (a: Point[], b: Point[]): number => {
+  if (!isValidQuad(a) || !isValidQuad(b)) {
+    return Number.POSITIVE_INFINITY;
+  }
+
+  let total = 0;
+  for (let i = 0; i < 4; i += 1) {
+    total += Math.hypot(a[i].x - b[i].x, a[i].y - b[i].y);
+  }
+
+  return total / 4;
+};
+
+export const averageQuad = (quads: Point[][]): Point[] => {
+  if (!Array.isArray(quads) || quads.length === 0) {
+    throw new Error('Cannot average empty quad array');
+  }
+
+  const accum: Point[] = quads[0].map(() => ({ x: 0, y: 0 }));
+
+  quads.forEach((quad) => {
+    quad.forEach((point, index) => {
+      accum[index].x += point.x;
+      accum[index].y += point.y;
+    });
+  });
+
+  return accum.map((point) => ({ x: point.x / quads.length, y: point.y / quads.length }));
+};
+
+export const blendQuads = (base: Point[], target: Point[], alpha: number): Point[] => {
+  if (alpha <= 0) {
+    return base.map(clonePoint);
+  }
+
+  if (alpha >= 1) {
+    return target.map(clonePoint);
+  }
+
+  return base.map((point, index) => ({
+    x: point.x * (1 - alpha) + target[index].x * alpha,
+    y: point.y * (1 - alpha) + target[index].y * alpha,
+  }));
+};
+
+export const sanitizeQuad = (quad: Point[]): Point[] => {
+  if (!isValidQuad(quad)) {
+    throw new Error('Cannot sanitise invalid quad');
+  }
+
+  return quad.map((point) => ({
+    x: Number.isFinite(point.x) ? point.x : 0,
+    y: Number.isFinite(point.y) ? point.y : 0,
+  }));
+};

package/src/utils/stability.ts

@@ -1,10 +1,13 @@
 import type { Point } from '../types';
+import { isValidQuad, quadDistance } from './quad';
 
 let last: Point[] | null = null;
 let stable = 0;
 
+const STABILITY_DISTANCE = 8;
+
 export function checkStability(current: Point[] | null): number {
-  if (!current) {
+  if (!isValidQuad(current)) {
     stable = 0;
     last = null;
     return 0;
@@ -16,12 +19,9 @@ export function checkStability(current: Point[] | null): number {
     return stable;
   }
 
-  const diff = Math.hypot(
-    avg(current.map((p) => p.x)) - avg(last.map((p) => p.x)),
-    avg(current.map((p) => p.y)) - avg(last.map((p) => p.y))
-  );
+  const diff = quadDistance(current, last);
 
-  if (diff < 10) {
+  if (diff < STABILITY_DISTANCE) {
     stable++;
   } else {
     stable = 0;
@@ -30,5 +30,3 @@ export function checkStability(current: Point[] | null): number {
   last = current;
   return stable;
 }
-
-const avg = (arr: number[]) => arr.reduce((a, b) => a + b, 0) / arr.length;