react-native-rectangle-doc-scanner 0.39.0 → 0.41.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,102 @@ 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 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 MAX_AREA_SHIFT = 0.45;
+    const HISTORY_RESET_DISTANCE = 70;
+    const MIN_AREA_RATIO = 0.0035;
+    const MAX_AREA_RATIO = 0.9;
+    const MIN_EDGE_RATIO = 0.025;
     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 (!(0, quad_1.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;
         }
-        // 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;
-                }
+        missingFrameCountRef.current = 0;
+        const ordered = (0, quad_1.orderQuadPoints)(value);
+        const sanitized = (0, quad_1.sanitizeQuad)(ordered);
+        const frameSize = frameSizeRef.current;
+        const frameArea = frameSize ? frameSize.width * frameSize.height : null;
+        const area = (0, quad_1.quadArea)(sanitized);
+        const edges = (0, quad_1.quadEdgeLengths)(sanitized);
+        const minEdge = Math.min(...edges);
+        const maxEdge = Math.max(...edges);
+        const aspectRatio = maxEdge > 0 ? maxEdge / Math.max(minEdge, 1) : 0;
+        const minEdgeThreshold = frameSize
+            ? Math.max(14, Math.min(frameSize.width, frameSize.height) * MIN_EDGE_RATIO)
+            : 14;
+        const areaTooSmall = frameArea ? area < frameArea * MIN_AREA_RATIO : area === 0;
+        const areaTooLarge = frameArea ? area > frameArea * MAX_AREA_RATIO : false;
+        const edgesTooShort = minEdge < minEdgeThreshold;
+        const aspectTooExtreme = aspectRatio > 7;
+        if (areaTooSmall || areaTooLarge || edgesTooShort || aspectTooExtreme) {
+            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);
+        const lastMeasurement = lastMeasurementRef.current;
+        if (lastMeasurement && (0, quad_1.quadDistance)(lastMeasurement, sanitized) > HISTORY_RESET_DISTANCE) {
+            smoothingBufferRef.current = [];
         }
-        else {
-            setQuad(null);
+        lastMeasurementRef.current = sanitized;
+        smoothingBufferRef.current.push(sanitized);
+        if (smoothingBufferRef.current.length > MAX_HISTORY) {
+            smoothingBufferRef.current.shift();
+        }
+        const history = smoothingBufferRef.current;
+        const hasHistory = history.length >= 2;
+        let candidate = hasHistory ? (0, quad_1.weightedAverageQuad)(history) : sanitized;
+        const anchor = anchorQuadRef.current;
+        if (anchor && (0, quad_1.isValidQuad)(anchor)) {
+            const delta = (0, quad_1.quadDistance)(candidate, anchor);
+            const anchorCenter = (0, quad_1.quadCenter)(anchor);
+            const candidateCenter = (0, quad_1.quadCenter)(candidate);
+            const anchorArea = (0, quad_1.quadArea)(anchor);
+            const candidateArea = (0, quad_1.quadArea)(candidate);
+            const centerDelta = Math.hypot(candidateCenter.x - anchorCenter.x, candidateCenter.y - anchorCenter.y);
+            const areaShift = anchorArea > 0 ? Math.abs(anchorArea - candidateArea) / anchorArea : 0;
+            if (delta <= SNAP_DISTANCE && centerDelta <= SNAP_CENTER_DISTANCE && areaShift <= 0.08) {
+                candidate = anchor;
+            }
+            else if (delta <= BLEND_DISTANCE && centerDelta <= MAX_CENTER_DELTA && areaShift <= MAX_AREA_SHIFT) {
+                const normalizedDelta = Math.min(1, delta / BLEND_DISTANCE);
+                const adaptiveAlpha = 0.25 + normalizedDelta * 0.45; // 0.25..0.7 range
+                candidate = (0, quad_1.blendQuads)(anchor, candidate, adaptiveAlpha);
+            }
+            else {
+                smoothingBufferRef.current = [sanitized];
+            }
         }
+        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}`;
@@ -147,6 +200,7 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
     }, []);
     const [frameSize, setFrameSize] = (0, react_1.useState)(null);
     const updateFrameSize = (0, react_native_worklets_core_1.useRunOnJS)((width, height) => {
+        frameSizeRef.current = { width, height };
         setFrameSize({ width, height });
     }, []);
     const frameProcessor = (0, react_native_vision_camera_1.useFrameProcessor)((frame) => {

package/dist/utils/quad.d.ts

@@ -0,0 +1,12 @@
+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[];
+export declare const quadArea: (quad: Point[]) => number;
+export declare const quadCenter: (quad: Point[]) => Point;
+export declare const quadEdgeLengths: (quad: Point[]) => number[];
+export declare const weightedAverageQuad: (quads: Point[][]) => Point[];

package/dist/utils/quad.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.weightedAverageQuad = exports.quadEdgeLengths = exports.quadCenter = exports.quadArea = 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;
+const quadArea = (quad) => {
+    if (!(0, exports.isValidQuad)(quad)) {
+        return 0;
+    }
+    let area = 0;
+    for (let i = 0; i < 4; i += 1) {
+        const current = quad[i];
+        const next = quad[(i + 1) % 4];
+        area += current.x * next.y - next.x * current.y;
+    }
+    return Math.abs(area) / 2;
+};
+exports.quadArea = quadArea;
+const quadCenter = (quad) => {
+    if (!(0, exports.isValidQuad)(quad)) {
+        return { x: 0, y: 0 };
+    }
+    const sum = quad.reduce((acc, point) => ({ x: acc.x + point.x, y: acc.y + point.y }), { x: 0, y: 0 });
+    return {
+        x: sum.x / quad.length,
+        y: sum.y / quad.length,
+    };
+};
+exports.quadCenter = quadCenter;
+const quadEdgeLengths = (quad) => {
+    if (!(0, exports.isValidQuad)(quad)) {
+        return [0, 0, 0, 0];
+    }
+    const lengths = [];
+    for (let i = 0; i < 4; i += 1) {
+        const current = quad[i];
+        const next = quad[(i + 1) % 4];
+        lengths.push(Math.hypot(next.x - current.x, next.y - current.y));
+    }
+    return lengths;
+};
+exports.quadEdgeLengths = quadEdgeLengths;
+const weightedAverageQuad = (quads) => {
+    if (!Array.isArray(quads) || quads.length === 0) {
+        throw new Error('Cannot average empty quad array');
+    }
+    const weights = quads.map((_, index) => index + 1);
+    const totalWeight = weights.reduce((acc, weight) => acc + weight, 0);
+    const accum = quads[0].map(() => ({ x: 0, y: 0 }));
+    quads.forEach((quad, quadIndex) => {
+        quad.forEach((point, pointIndex) => {
+            accum[pointIndex].x += point.x * weights[quadIndex];
+            accum[pointIndex].y += point.y * weights[quadIndex];
+        });
+    });
+    return accum.map((point) => ({
+        x: point.x / totalWeight,
+        y: point.y / totalWeight,
+    }));
+};
+exports.weightedAverageQuad = weightedAverageQuad;

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.41.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "repository": {

package/src/DocScanner.tsx

@@ -14,6 +14,17 @@ import {
 } from 'react-native-fast-opencv';
 import { Overlay } from './utils/overlay';
 import { checkStability } from './utils/stability';
+import {
+  blendQuads,
+  isValidQuad,
+  orderQuadPoints,
+  quadArea,
+  quadCenter,
+  quadDistance,
+  quadEdgeLengths,
+  sanitizeQuad,
+  weightedAverageQuad,
+} from './utils/quad';
 import type { Point } from './types';
 
 const isConvexQuadrilateral = (points: Point[]) => {
@@ -97,56 +108,120 @@ 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 lastMeasurementRef = useRef<Point[] | null>(null);
+  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 MAX_AREA_SHIFT = 0.45;
+  const HISTORY_RESET_DISTANCE = 70;
+  const MIN_AREA_RATIO = 0.0035;
+  const MAX_AREA_RATIO = 0.9;
+  const MIN_EDGE_RATIO = 0.025;
 
   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;
 
-    // Keep only last 3 frames for smoothing
-    if (smoothingBufferRef.current.length > 3) {
-      smoothingBufferRef.current.shift();
+      if (lastQuadRef.current && missingFrameCountRef.current <= 2) {
+        setQuad(lastQuadRef.current);
+        return;
+      }
+
+      smoothingBufferRef.current = [];
+      anchorQuadRef.current = null;
+      lastQuadRef.current = null;
+      setQuad(null);
+      return;
     }
 
-    // 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;
-        }
+    missingFrameCountRef.current = 0;
+
+    const ordered = orderQuadPoints(value);
+    const sanitized = sanitizeQuad(ordered);
+
+    const frameSize = frameSizeRef.current;
+    const frameArea = frameSize ? frameSize.width * frameSize.height : null;
+    const area = quadArea(sanitized);
+    const edges = quadEdgeLengths(sanitized);
+    const minEdge = Math.min(...edges);
+    const maxEdge = Math.max(...edges);
+    const aspectRatio = maxEdge > 0 ? maxEdge / Math.max(minEdge, 1) : 0;
+
+    const minEdgeThreshold = frameSize
+      ? Math.max(14, Math.min(frameSize.width, frameSize.height) * MIN_EDGE_RATIO)
+      : 14;
+
+    const areaTooSmall = frameArea ? area < frameArea * MIN_AREA_RATIO : area === 0;
+    const areaTooLarge = frameArea ? area > frameArea * MAX_AREA_RATIO : false;
+    const edgesTooShort = minEdge < minEdgeThreshold;
+    const aspectTooExtreme = aspectRatio > 7;
+
+    if (areaTooSmall || areaTooLarge || edgesTooShort || aspectTooExtreme) {
+      missingFrameCountRef.current += 1;
+
+      if (lastQuadRef.current && missingFrameCountRef.current <= 2) {
+        setQuad(lastQuadRef.current);
+        return;
       }
 
-      lastQuadRef.current = value;
-      setQuad(value);
-    } else if (lastQuadRef.current) {
-      // Keep showing last quad for 1 frame to reduce flickering
-      setQuad(lastQuadRef.current);
-    } else {
+      smoothingBufferRef.current = [];
+      anchorQuadRef.current = null;
+      lastQuadRef.current = null;
       setQuad(null);
+      return;
+    }
+
+    const lastMeasurement = lastMeasurementRef.current;
+    if (lastMeasurement && quadDistance(lastMeasurement, sanitized) > HISTORY_RESET_DISTANCE) {
+      smoothingBufferRef.current = [];
+    }
+    lastMeasurementRef.current = sanitized;
+
+    smoothingBufferRef.current.push(sanitized);
+    if (smoothingBufferRef.current.length > MAX_HISTORY) {
+      smoothingBufferRef.current.shift();
     }
+
+    const history = smoothingBufferRef.current;
+    const hasHistory = history.length >= 2;
+    let candidate = hasHistory ? weightedAverageQuad(history) : sanitized;
+
+    const anchor = anchorQuadRef.current;
+    if (anchor && isValidQuad(anchor)) {
+      const delta = quadDistance(candidate, anchor);
+      const anchorCenter = quadCenter(anchor);
+      const candidateCenter = quadCenter(candidate);
+      const anchorArea = quadArea(anchor);
+      const candidateArea = quadArea(candidate);
+      const centerDelta = Math.hypot(candidateCenter.x - anchorCenter.x, candidateCenter.y - anchorCenter.y);
+      const areaShift = anchorArea > 0 ? Math.abs(anchorArea - candidateArea) / anchorArea : 0;
+
+      if (delta <= SNAP_DISTANCE && centerDelta <= SNAP_CENTER_DISTANCE && areaShift <= 0.08) {
+        candidate = anchor;
+      } else if (delta <= BLEND_DISTANCE && centerDelta <= MAX_CENTER_DELTA && areaShift <= MAX_AREA_SHIFT) {
+        const normalizedDelta = Math.min(1, delta / BLEND_DISTANCE);
+        const adaptiveAlpha = 0.25 + normalizedDelta * 0.45; // 0.25..0.7 range
+        candidate = blendQuads(anchor, candidate, adaptiveAlpha);
+      } else {
+        smoothingBufferRef.current = [sanitized];
+      }
+    }
+
+    candidate = orderQuadPoints(candidate);
+    anchorQuadRef.current = candidate;
+    lastQuadRef.current = candidate;
+    setQuad(candidate);
   }, []);
 
   const reportError = useRunOnJS((step: string, error: unknown) => {
@@ -160,6 +235,7 @@ export const DocScanner: React.FC<Props> = ({
 
   const [frameSize, setFrameSize] = useState<{ width: number; height: number } | null>(null);
   const updateFrameSize = useRunOnJS((width: number, height: number) => {
+    frameSizeRef.current = { width, height };
     setFrameSize({ width, height });
   }, []);
 

package/src/utils/quad.ts

@@ -0,0 +1,181 @@
+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,
+  }));
+};
+
+export const quadArea = (quad: Point[]): number => {
+  if (!isValidQuad(quad)) {
+    return 0;
+  }
+
+  let area = 0;
+  for (let i = 0; i < 4; i += 1) {
+    const current = quad[i];
+    const next = quad[(i + 1) % 4];
+    area += current.x * next.y - next.x * current.y;
+  }
+
+  return Math.abs(area) / 2;
+};
+
+export const quadCenter = (quad: Point[]): Point => {
+  if (!isValidQuad(quad)) {
+    return { x: 0, y: 0 };
+  }
+
+  const sum = quad.reduce(
+    (acc, point) => ({ x: acc.x + point.x, y: acc.y + point.y }),
+    { x: 0, y: 0 },
+  );
+
+  return {
+    x: sum.x / quad.length,
+    y: sum.y / quad.length,
+  };
+};
+
+export const quadEdgeLengths = (quad: Point[]): number[] => {
+  if (!isValidQuad(quad)) {
+    return [0, 0, 0, 0];
+  }
+
+  const lengths: number[] = [];
+
+  for (let i = 0; i < 4; i += 1) {
+    const current = quad[i];
+    const next = quad[(i + 1) % 4];
+    lengths.push(Math.hypot(next.x - current.x, next.y - current.y));
+  }
+
+  return lengths;
+};
+
+export const weightedAverageQuad = (quads: Point[][]): Point[] => {
+  if (!Array.isArray(quads) || quads.length === 0) {
+    throw new Error('Cannot average empty quad array');
+  }
+
+  const weights = quads.map((_, index) => index + 1);
+  const totalWeight = weights.reduce((acc, weight) => acc + weight, 0);
+
+  const accum: Point[] = quads[0].map(() => ({ x: 0, y: 0 }));
+
+  quads.forEach((quad, quadIndex) => {
+    quad.forEach((point, pointIndex) => {
+      accum[pointIndex].x += point.x * weights[quadIndex];
+      accum[pointIndex].y += point.y * weights[quadIndex];
+    });
+  });
+
+  return accum.map((point) => ({
+    x: point.x / totalWeight,
+    y: point.y / totalWeight,
+  }));
+};

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;