react-native-rectangle-doc-scanner 0.56.0 → 0.58.0

package/dist/DocScanner.js

@@ -271,164 +271,191 @@ const DocScanner = ({ onCapture, overlayColor = '#e7a649', autoCapture = true, m
             step = 'cvtColor';
             reportStage(step);
             react_native_fast_opencv_1.OpenCV.invoke('cvtColor', mat, mat, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2GRAY);
-            // Enhanced morphological operations for noise reduction
-            const morphologyKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 7, 7);
-            step = 'getStructuringElement';
+            let bestCandidate = null;
+            const evaluateContours = (inputMat, attemptLabel) => {
+                'worklet';
+                step = `findContours_${attemptLabel}`;
+                reportStage(step);
+                const contours = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVectorOfVectors);
+                react_native_fast_opencv_1.OpenCV.invoke('findContours', inputMat, contours, react_native_fast_opencv_1.RetrievalModes.RETR_EXTERNAL, react_native_fast_opencv_1.ContourApproximationModes.CHAIN_APPROX_SIMPLE);
+                const contourVector = react_native_fast_opencv_1.OpenCV.toJSValue(contours);
+                const contourArray = Array.isArray(contourVector?.array) ? contourVector.array : [];
+                let bestLocal = null;
+                const resizedArea = width * height;
+                const originalArea = frame.width * frame.height;
+                const minEdgeThreshold = Math.max(16, Math.min(frame.width, frame.height) * 0.012);
+                for (let i = 0; i < contourArray.length; i += 1) {
+                    step = `${attemptLabel}_contour_${i}_copy`;
+                    reportStage(step);
+                    const contour = react_native_fast_opencv_1.OpenCV.copyObjectFromVector(contours, i);
+                    step = `${attemptLabel}_contour_${i}_area`;
+                    reportStage(step);
+                    const { value: rawArea } = react_native_fast_opencv_1.OpenCV.invoke('contourArea', contour, false);
+                    if (typeof rawArea !== 'number' || !isFinite(rawArea) || rawArea < 40) {
+                        continue;
+                    }
+                    const resizedAreaRatio = rawArea / resizedArea;
+                    if (resizedAreaRatio < 0.0001 || resizedAreaRatio > 0.97) {
+                        continue;
+                    }
+                    let contourToUse = contour;
+                    try {
+                        const hull = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
+                        react_native_fast_opencv_1.OpenCV.invoke('convexHull', contour, hull, false, true);
+                        contourToUse = hull;
+                    }
+                    catch (err) {
+                        if (__DEV__) {
+                            console.warn('[DocScanner] convexHull failed, using original contour');
+                        }
+                    }
+                    const { value: perimeter } = react_native_fast_opencv_1.OpenCV.invoke('arcLength', contourToUse, true);
+                    if (typeof perimeter !== 'number' || !isFinite(perimeter) || perimeter < 40) {
+                        continue;
+                    }
+                    const approx = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
+                    const epsilonValues = [
+                        0.012, 0.01, 0.008, 0.006, 0.005, 0.004, 0.0035, 0.003, 0.0025, 0.002, 0.0016, 0.0012,
+                    ];
+                    let approxArray = [];
+                    for (let attempt = 0; attempt < epsilonValues.length; attempt += 1) {
+                        const epsilon = epsilonValues[attempt] * perimeter;
+                        step = `${attemptLabel}_contour_${i}_approx_${attempt}`;
+                        reportStage(step);
+                        react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contourToUse, approx, epsilon, true);
+                        const approxValue = react_native_fast_opencv_1.OpenCV.toJSValue(approx);
+                        const candidate = Array.isArray(approxValue?.array) ? approxValue.array : [];
+                        if (candidate.length === 4) {
+                            approxArray = candidate;
+                            break;
+                        }
+                    }
+                    if (approxArray.length !== 4) {
+                        continue;
+                    }
+                    const isValidPoint = (pt) => typeof pt.x === 'number' && typeof pt.y === 'number' && isFinite(pt.x) && isFinite(pt.y);
+                    if (!approxArray.every(isValidPoint)) {
+                        continue;
+                    }
+                    const normalizedPoints = approxArray.map((pt) => ({
+                        x: pt.x / ratio,
+                        y: pt.y / ratio,
+                    }));
+                    if (!isConvexQuadrilateral(normalizedPoints)) {
+                        continue;
+                    }
+                    const sanitized = (0, quad_1.sanitizeQuad)((0, quad_1.orderQuadPoints)(normalizedPoints));
+                    if (!(0, quad_1.isValidQuad)(sanitized)) {
+                        continue;
+                    }
+                    const quadEdges = (0, quad_1.quadEdgeLengths)(sanitized);
+                    const minEdge = Math.min(...quadEdges);
+                    const maxEdge = Math.max(...quadEdges);
+                    if (!Number.isFinite(minEdge) || minEdge < minEdgeThreshold) {
+                        continue;
+                    }
+                    const aspectRatio = maxEdge / Math.max(minEdge, 1);
+                    if (!Number.isFinite(aspectRatio) || aspectRatio > 9) {
+                        continue;
+                    }
+                    const quadAreaValue = (0, quad_1.quadArea)(sanitized);
+                    const areaRatioOriginal = originalArea > 0 ? quadAreaValue / originalArea : 0;
+                    if (areaRatioOriginal < 0.00008 || areaRatioOriginal > 0.92) {
+                        continue;
+                    }
+                    if (__DEV__) {
+                        console.log('[DocScanner] candidate', attemptLabel, 'areaRatio', areaRatioOriginal);
+                    }
+                    const candidate = {
+                        quad: sanitized,
+                        area: quadAreaValue,
+                        label: attemptLabel,
+                    };
+                    if (!bestLocal || candidate.area > bestLocal.area) {
+                        bestLocal = candidate;
+                    }
+                }
+                return bestLocal;
+            };
+            const considerCandidate = (candidate) => {
+                'worklet';
+                if (!candidate) {
+                    return;
+                }
+                if (__DEV__) {
+                    console.log('[DocScanner] best so far from', candidate.label, 'area', candidate.area);
+                }
+                if (!bestCandidate || candidate.area > bestCandidate.area) {
+                    bestCandidate = candidate;
+                }
+            };
+            const ADAPTIVE_THRESH_GAUSSIAN_C = 1;
+            const THRESH_BINARY = 0;
+            const THRESH_OTSU = 8;
+            step = 'prepareMorphology';
             reportStage(step);
+            const morphologyKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
             const element = react_native_fast_opencv_1.OpenCV.invoke('getStructuringElement', react_native_fast_opencv_1.MorphShapes.MORPH_RECT, morphologyKernel);
-            step = 'morphologyEx';
-            reportStage(step);
-            // MORPH_CLOSE to fill small holes in edges
-            react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', mat, mat, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, element);
-            // MORPH_OPEN to remove small noise
-            react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', mat, mat, react_native_fast_opencv_1.MorphTypes.MORPH_OPEN, element);
-            // Bilateral filter for edge-preserving smoothing (better quality than Gaussian)
+            const blurKernelSize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
+            // Edge-preserving smoothing for noisy frames
             step = 'bilateralFilter';
             reportStage(step);
+            let filteredMat = mat;
             try {
                 const tempMat = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat);
                 react_native_fast_opencv_1.OpenCV.invoke('bilateralFilter', mat, tempMat, 9, 75, 75);
-                mat = tempMat;
+                filteredMat = tempMat;
             }
             catch (error) {
                 if (__DEV__) {
                     console.warn('[DocScanner] bilateralFilter unavailable, falling back to GaussianBlur', error);
                 }
-                step = 'gaussianBlurFallback';
-                reportStage(step);
-                const blurKernel = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
-                react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', mat, mat, blurKernel, 0);
             }
-            step = 'Canny';
-            reportStage(step);
-            // Configurable Canny parameters for adaptive edge detection
-            react_native_fast_opencv_1.OpenCV.invoke('Canny', mat, mat, CANNY_LOW, CANNY_HIGH);
-            step = 'createContours';
+            step = 'gaussianBlur';
             reportStage(step);
-            const contours = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVectorOfVectors);
-            react_native_fast_opencv_1.OpenCV.invoke('findContours', mat, contours, react_native_fast_opencv_1.RetrievalModes.RETR_EXTERNAL, react_native_fast_opencv_1.ContourApproximationModes.CHAIN_APPROX_SIMPLE);
-            let best = null;
-            let maxArea = 0;
-            const frameArea = width * height;
-            step = 'toJSValue';
+            react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', filteredMat, filteredMat, blurKernelSize, 0);
+            step = 'morphologyClose';
             reportStage(step);
-            const contourVector = react_native_fast_opencv_1.OpenCV.toJSValue(contours);
-            const contourArray = Array.isArray(contourVector?.array) ? contourVector.array : [];
-            for (let i = 0; i < contourArray.length; i += 1) {
-                step = `contour_${i}_copy`;
+            react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', filteredMat, filteredMat, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, element);
+            const baseGray = react_native_fast_opencv_1.OpenCV.invoke('clone', filteredMat);
+            const runCanny = (label, low, high) => {
+                'worklet';
+                const working = react_native_fast_opencv_1.OpenCV.invoke('clone', baseGray);
+                step = `${label}_canny`;
                 reportStage(step);
-                const contour = react_native_fast_opencv_1.OpenCV.copyObjectFromVector(contours, i);
-                // Compute absolute area first
-                step = `contour_${i}_area_abs`;
-                reportStage(step);
-                const { value: area } = react_native_fast_opencv_1.OpenCV.invoke('contourArea', contour, false);
-                // Skip extremely small contours, but keep threshold very low to allow distant documents
-                if (typeof area !== 'number' || !isFinite(area)) {
-                    continue;
-                }
-                if (area < 50) {
-                    continue;
-                }
-                step = `contour_${i}_area`; // ratio stage
+                react_native_fast_opencv_1.OpenCV.invoke('Canny', working, working, low, high);
+                react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', working, working, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, element);
+                considerCandidate(evaluateContours(working, label));
+            };
+            runCanny('canny_primary', CANNY_LOW, CANNY_HIGH);
+            runCanny('canny_soft', Math.max(8, CANNY_LOW * 0.6), CANNY_HIGH * 0.7 + CANNY_LOW * 0.2);
+            const runAdaptive = (label, blockSize, c, thresholdMode) => {
+                'worklet';
+                const working = react_native_fast_opencv_1.OpenCV.invoke('clone', baseGray);
+                step = `${label}_adaptive`;
                 reportStage(step);
-                const areaRatio = area / frameArea;
-                if (__DEV__) {
-                    console.log('[DocScanner] area', area, 'ratio', areaRatio);
-                }
-                // Skip if area ratio is too small or too large
-                if (areaRatio < 0.0002 || areaRatio > 0.99) {
-                    continue;
-                }
-                // Try to use convex hull for better corner detection
-                let contourToUse = contour;
-                try {
-                    step = `contour_${i}_convexHull`;
-                    reportStage(step);
-                    const hull = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
-                    react_native_fast_opencv_1.OpenCV.invoke('convexHull', contour, hull, false, true);
-                    contourToUse = hull;
+                if (thresholdMode === THRESH_OTSU) {
+                    react_native_fast_opencv_1.OpenCV.invoke('threshold', working, working, 0, 255, THRESH_BINARY | THRESH_OTSU);
                 }
-                catch (err) {
-                    // If convexHull fails, use original contour
-                    if (__DEV__) {
-                        console.warn('[DocScanner] convexHull failed, using original contour');
-                    }
-                }
-                step = `contour_${i}_arcLength`;
-                reportStage(step);
-                const { value: perimeter } = react_native_fast_opencv_1.OpenCV.invoke('arcLength', contourToUse, true);
-                const approx = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
-                let approxArray = [];
-                // Try more epsilon values from 0.1% to 10% for difficult shapes
-                const epsilonValues = [
-                    0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.007, 0.008, 0.009,
-                    0.01, 0.012, 0.015, 0.018, 0.02, 0.025, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1
-                ];
-                for (let attempt = 0; attempt < epsilonValues.length; attempt += 1) {
-                    const epsilon = epsilonValues[attempt] * perimeter;
-                    step = `contour_${i}_approxPolyDP_attempt_${attempt}`;
-                    reportStage(step);
-                    react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contourToUse, approx, epsilon, true);
-                    step = `contour_${i}_toJS_attempt_${attempt}`;
-                    reportStage(step);
-                    const approxValue = react_native_fast_opencv_1.OpenCV.toJSValue(approx);
-                    const candidate = Array.isArray(approxValue?.array) ? approxValue.array : [];
-                    if (__DEV__) {
-                        console.log('[DocScanner] approx length', candidate.length, 'epsilon', epsilon);
-                    }
-                    if (candidate.length === 4) {
-                        approxArray = candidate;
-                        break;
-                    }
+                else {
+                    react_native_fast_opencv_1.OpenCV.invoke('adaptiveThreshold', working, working, 255, ADAPTIVE_THRESH_GAUSSIAN_C, THRESH_BINARY, blockSize, c);
                 }
-                // Only proceed if we found exactly 4 corners
-                if (approxArray.length !== 4) {
-                    continue;
-                }
-                step = `contour_${i}_convex`;
-                reportStage(step);
-                // Validate points before processing
-                const isValidPoint = (pt) => {
-                    return typeof pt.x === 'number' && typeof pt.y === 'number' &&
-                        !isNaN(pt.x) && !isNaN(pt.y) &&
-                        isFinite(pt.x) && isFinite(pt.y);
-                };
-                if (!approxArray.every(isValidPoint)) {
-                    if (__DEV__) {
-                        console.warn('[DocScanner] invalid points in approxArray', approxArray);
-                    }
-                    continue;
-                }
-                const points = approxArray.map((pt) => ({
-                    x: pt.x / ratio,
-                    y: pt.y / ratio,
-                }));
-                // Verify the quadrilateral is convex (valid document shape)
-                try {
-                    if (!isConvexQuadrilateral(points)) {
-                        if (__DEV__) {
-                            console.log('[DocScanner] not convex, skipping:', points);
-                        }
-                        continue;
-                    }
-                }
-                catch (err) {
-                    if (__DEV__) {
-                        console.warn('[DocScanner] convex check error:', err, 'points:', points);
-                    }
-                    continue;
-                }
-                if (area > maxArea) {
-                    best = points;
-                    maxArea = area;
-                }
-            }
+                react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', working, working, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, element);
+                considerCandidate(evaluateContours(working, label));
+            };
+            runAdaptive('adaptive', 19, 7, THRESH_BINARY);
+            runAdaptive('otsu', 0, 0, THRESH_OTSU);
             step = 'clearBuffers';
             reportStage(step);
             react_native_fast_opencv_1.OpenCV.clearBuffers();
             step = 'updateQuad';
             reportStage(step);
-            updateQuad(best);
+            if (bestCandidate) {
+                updateQuad(bestCandidate.quad);
+            }
+            else {
+                updateQuad(null);
+            }
         }
         catch (error) {
             reportError(step, error);

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export type { FullDocScannerResult, FullDocScannerProps, FullDocScannerStrings,
 export type { Point, Quad, Rectangle, CapturedDocument } from './types';
 export type { DetectionConfig } from './DocScanner';
 export { quadToRectangle, rectangleToQuad, scaleCoordinates, scaleRectangle, } from './utils/coordinate';
+export { DocumentDetector } from './utils/documentDetection';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scaleRectangle = exports.scaleCoordinates = exports.rectangleToQuad = exports.quadToRectangle = exports.FullDocScanner = exports.CropEditor = exports.DocScanner = void 0;
+exports.DocumentDetector = exports.scaleRectangle = exports.scaleCoordinates = exports.rectangleToQuad = exports.quadToRectangle = exports.FullDocScanner = exports.CropEditor = exports.DocScanner = void 0;
 // Main components
 var DocScanner_1 = require("./DocScanner");
 Object.defineProperty(exports, "DocScanner", { enumerable: true, get: function () { return DocScanner_1.DocScanner; } });
@@ -14,3 +14,5 @@ Object.defineProperty(exports, "quadToRectangle", { enumerable: true, get: funct
 Object.defineProperty(exports, "rectangleToQuad", { enumerable: true, get: function () { return coordinate_1.rectangleToQuad; } });
 Object.defineProperty(exports, "scaleCoordinates", { enumerable: true, get: function () { return coordinate_1.scaleCoordinates; } });
 Object.defineProperty(exports, "scaleRectangle", { enumerable: true, get: function () { return coordinate_1.scaleRectangle; } });
+var documentDetection_1 = require("./utils/documentDetection");
+Object.defineProperty(exports, "DocumentDetector", { enumerable: true, get: function () { return documentDetection_1.DocumentDetector; } });

package/dist/utils/documentDetection.d.ts

@@ -0,0 +1,23 @@
+import type { Point } from '../types';
+type Size = {
+    width: number;
+    height: number;
+};
+type Quad = [Point, Point, Point, Point];
+/**
+ * Provides document detection utilities using react-native-fast-opencv.
+ */
+export declare class DocumentDetector {
+    private static initialized;
+    /** Initialize OpenCV runtime once */
+    static initialize(): Promise<void>;
+    /** Find document contours and return the largest quadrilateral */
+    static findDocumentContours(imagePath: string): Promise<Quad | null>;
+    /** Apply a perspective transform using detected corners */
+    static perspectiveTransform(imagePath: string, corners: Quad, outputSize?: Size): Promise<string | null>;
+    /** Detect document and apply normalization */
+    static detectAndNormalize(imagePath: string, outputSize?: Size): Promise<string | null>;
+    /** Only detect document corners without transforming */
+    static getDocumentBounds(imagePath: string): Promise<Quad | null>;
+}
+export {};

package/dist/utils/documentDetection.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentDetector = void 0;
+const react_native_fast_opencv_1 = require("react-native-fast-opencv");
+const OUTPUT_SIZE = { width: 800, height: 600 };
+const MIN_AREA = 1000;
+const GAUSSIAN_KERNEL = { width: 5, height: 5 };
+const MORPH_KERNEL = { width: 3, height: 3 };
+const ADAPTIVE_THRESH_GAUSSIAN_C = 1;
+const THRESH_BINARY = 0;
+const safeRelease = (mat) => {
+    if (mat && typeof mat.release === 'function') {
+        mat.release();
+    }
+};
+const normalizePoint = (value) => {
+    if (!value) {
+        return null;
+    }
+    if (Array.isArray(value) && value.length >= 2) {
+        const [x, y] = value;
+        const px = Number(x);
+        const py = Number(y);
+        return Number.isFinite(px) && Number.isFinite(py) ? { x: px, y: py } : null;
+    }
+    if (typeof value === 'object') {
+        const maybePoint = value;
+        const px = Number(maybePoint.x);
+        const py = Number(maybePoint.y);
+        return Number.isFinite(px) && Number.isFinite(py) ? { x: px, y: py } : null;
+    }
+    return null;
+};
+const toPointArray = (value) => {
+    if (!value) {
+        return null;
+    }
+    if (Array.isArray(value)) {
+        const points = value.map(normalizePoint).filter((point) => point !== null);
+        return points.length === value.length ? points : null;
+    }
+    if (typeof value === 'object') {
+        const mat = value;
+        const data = mat.data32F ?? mat.data64F ?? mat.data32S;
+        if (!data || data.length < 8) {
+            return null;
+        }
+        const points = [];
+        for (let i = 0; i + 1 < data.length; i += 2) {
+            const x = data[i];
+            const y = data[i + 1];
+            if (Number.isFinite(x) && Number.isFinite(y)) {
+                points.push({ x, y });
+            }
+        }
+        return points.length >= 4 ? points.slice(0, 4) : null;
+    }
+    return null;
+};
+const ensureQuad = (points) => {
+    if (!points || points.length < 4) {
+        return null;
+    }
+    const quad = [points[0], points[1], points[2], points[3]];
+    for (const point of quad) {
+        if (typeof point.x !== 'number' || typeof point.y !== 'number') {
+            return null;
+        }
+    }
+    return quad;
+};
+/**
+ * Provides document detection utilities using react-native-fast-opencv.
+ */
+class DocumentDetector {
+    static initialized = false;
+    /** Initialize OpenCV runtime once */
+    static async initialize() {
+        if (!DocumentDetector.initialized) {
+            await react_native_fast_opencv_1.OpenCV.initialize();
+            DocumentDetector.initialized = true;
+        }
+    }
+    /** Find document contours and return the largest quadrilateral */
+    static async findDocumentContours(imagePath) {
+        await DocumentDetector.initialize();
+        let image;
+        let gray;
+        let blurred;
+        let thresh;
+        let morphed;
+        let kernel;
+        try {
+            image = react_native_fast_opencv_1.OpenCV.imread(imagePath);
+            gray = react_native_fast_opencv_1.OpenCV.cvtColor(image, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2GRAY);
+            blurred = react_native_fast_opencv_1.OpenCV.GaussianBlur(gray, GAUSSIAN_KERNEL, 0);
+            thresh = react_native_fast_opencv_1.OpenCV.adaptiveThreshold(blurred, 255, ADAPTIVE_THRESH_GAUSSIAN_C, THRESH_BINARY, 11, 2);
+            kernel = react_native_fast_opencv_1.OpenCV.getStructuringElement(react_native_fast_opencv_1.MorphShapes.MORPH_RECT, MORPH_KERNEL);
+            morphed = react_native_fast_opencv_1.OpenCV.morphologyEx(thresh, react_native_fast_opencv_1.MorphTypes.MORPH_CLOSE, kernel);
+            const contours = react_native_fast_opencv_1.OpenCV.findContours(morphed, react_native_fast_opencv_1.RetrievalModes.RETR_EXTERNAL, react_native_fast_opencv_1.ContourApproximationModes.CHAIN_APPROX_SIMPLE);
+            let largestQuad = null;
+            let maxArea = 0;
+            for (const contour of contours) {
+                const area = react_native_fast_opencv_1.OpenCV.contourArea(contour);
+                if (area <= maxArea || area <= MIN_AREA) {
+                    continue;
+                }
+                const perimeter = react_native_fast_opencv_1.OpenCV.arcLength(contour, true);
+                const approx = react_native_fast_opencv_1.OpenCV.approxPolyDP(contour, 0.02 * perimeter, true);
+                const points = ensureQuad(toPointArray(approx));
+                safeRelease(approx);
+                if (!points) {
+                    continue;
+                }
+                maxArea = area;
+                largestQuad = points;
+            }
+            return largestQuad;
+        }
+        catch (error) {
+            if (__DEV__) {
+                console.error('[DocumentDetector] findDocumentContours error', error);
+            }
+            return null;
+        }
+        finally {
+            safeRelease(kernel);
+            safeRelease(morphed);
+            safeRelease(thresh);
+            safeRelease(blurred);
+            safeRelease(gray);
+            safeRelease(image);
+        }
+    }
+    /** Apply a perspective transform using detected corners */
+    static async perspectiveTransform(imagePath, corners, outputSize = OUTPUT_SIZE) {
+        await DocumentDetector.initialize();
+        let image;
+        let srcPoints;
+        let dstPoints;
+        let transformMatrix;
+        let warped;
+        try {
+            image = react_native_fast_opencv_1.OpenCV.imread(imagePath);
+            srcPoints = react_native_fast_opencv_1.OpenCV.matFromArray(4, 1, react_native_fast_opencv_1.OpenCV.CV_32FC2, [
+                corners[0].x,
+                corners[0].y,
+                corners[1].x,
+                corners[1].y,
+                corners[2].x,
+                corners[2].y,
+                corners[3].x,
+                corners[3].y,
+            ]);
+            dstPoints = react_native_fast_opencv_1.OpenCV.matFromArray(4, 1, react_native_fast_opencv_1.OpenCV.CV_32FC2, [
+                0,
+                0,
+                outputSize.width,
+                0,
+                outputSize.width,
+                outputSize.height,
+                0,
+                outputSize.height,
+            ]);
+            transformMatrix = react_native_fast_opencv_1.OpenCV.getPerspectiveTransform(srcPoints, dstPoints);
+            warped = react_native_fast_opencv_1.OpenCV.warpPerspective(image, transformMatrix, outputSize);
+            const outputPath = imagePath.replace(/\.jpg$/i, '_normalized.jpg');
+            react_native_fast_opencv_1.OpenCV.imwrite(outputPath, warped);
+            return outputPath;
+        }
+        catch (error) {
+            if (__DEV__) {
+                console.error('[DocumentDetector] perspectiveTransform error', error);
+            }
+            return null;
+        }
+        finally {
+            safeRelease(warped);
+            safeRelease(transformMatrix);
+            safeRelease(dstPoints);
+            safeRelease(srcPoints);
+            safeRelease(image);
+        }
+    }
+    /** Detect document and apply normalization */
+    static async detectAndNormalize(imagePath, outputSize) {
+        try {
+            const corners = await DocumentDetector.findDocumentContours(imagePath);
+            if (!corners) {
+                if (__DEV__) {
+                    console.log('[DocumentDetector] No document detected');
+                }
+                return null;
+            }
+            return DocumentDetector.perspectiveTransform(imagePath, corners, outputSize ?? OUTPUT_SIZE);
+        }
+        catch (error) {
+            if (__DEV__) {
+                console.error('[DocumentDetector] detectAndNormalize error', error);
+            }
+            return null;
+        }
+    }
+    /** Only detect document corners without transforming */
+    static async getDocumentBounds(imagePath) {
+        try {
+            return DocumentDetector.findDocumentContours(imagePath);
+        }
+        catch (error) {
+            if (__DEV__) {
+                console.error('[DocumentDetector] getDocumentBounds error', error);
+            }
+            return null;
+        }
+    }
+}
+exports.DocumentDetector = DocumentDetector;

package/package.json

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

package/src/DocScanner.tsx

@@ -76,6 +76,12 @@ type CameraRef = {
 
 type CameraOverrides = Omit<React.ComponentProps<typeof Camera>, 'style' | 'ref' | 'frameProcessor'>;
 
+type DetectionCandidate = {
+  quad: Point[];
+  area: number;
+  label: string;
+};
+
 /**
  * Configuration for detection quality and behavior
  */
@@ -337,189 +343,226 @@ export const DocScanner: React.FC<Props> = ({
       reportStage(step);
       OpenCV.invoke('cvtColor', mat, mat, ColorConversionCodes.COLOR_BGR2GRAY);
 
-      // Enhanced morphological operations for noise reduction
-      const morphologyKernel = OpenCV.createObject(ObjectType.Size, 7, 7);
-      step = 'getStructuringElement';
-      reportStage(step);
-      const element = OpenCV.invoke('getStructuringElement', MorphShapes.MORPH_RECT, morphologyKernel);
-      step = 'morphologyEx';
-      reportStage(step);
-      // MORPH_CLOSE to fill small holes in edges
-      OpenCV.invoke('morphologyEx', mat, mat, MorphTypes.MORPH_CLOSE, element);
-      // MORPH_OPEN to remove small noise
-      OpenCV.invoke('morphologyEx', mat, mat, MorphTypes.MORPH_OPEN, element);
+      let bestCandidate: DetectionCandidate | null = null;
 
-      // Bilateral filter for edge-preserving smoothing (better quality than Gaussian)
-      step = 'bilateralFilter';
-      reportStage(step);
-      try {
-        const tempMat = OpenCV.createObject(ObjectType.Mat);
-        OpenCV.invoke('bilateralFilter', mat, tempMat, 9, 75, 75);
-        mat = tempMat;
-      } catch (error) {
-        if (__DEV__) {
-          console.warn('[DocScanner] bilateralFilter unavailable, falling back to GaussianBlur', error);
-        }
-        step = 'gaussianBlurFallback';
+      const evaluateContours = (inputMat: unknown, attemptLabel: string): DetectionCandidate | null => {
+        'worklet';
+
+        step = `findContours_${attemptLabel}`;
         reportStage(step);
-        const blurKernel = OpenCV.createObject(ObjectType.Size, 5, 5);
-        OpenCV.invoke('GaussianBlur', mat, mat, blurKernel, 0);
-      }
+        const contours = OpenCV.createObject(ObjectType.PointVectorOfVectors);
+        OpenCV.invoke('findContours', inputMat, contours, RetrievalModes.RETR_EXTERNAL, ContourApproximationModes.CHAIN_APPROX_SIMPLE);
 
-      step = 'Canny';
-      reportStage(step);
-      // Configurable Canny parameters for adaptive edge detection
-      OpenCV.invoke('Canny', mat, mat, CANNY_LOW, CANNY_HIGH);
+        const contourVector = OpenCV.toJSValue(contours);
+        const contourArray = Array.isArray(contourVector?.array) ? contourVector.array : [];
 
-      step = 'createContours';
-      reportStage(step);
-      const contours = OpenCV.createObject(ObjectType.PointVectorOfVectors);
-      OpenCV.invoke('findContours', mat, contours, RetrievalModes.RETR_EXTERNAL, ContourApproximationModes.CHAIN_APPROX_SIMPLE);
+        let bestLocal: DetectionCandidate | null = null;
+        const resizedArea = width * height;
+        const originalArea = frame.width * frame.height;
+        const minEdgeThreshold = Math.max(16, Math.min(frame.width, frame.height) * 0.012);
 
-      let best: Point[] | null = null;
-      let maxArea = 0;
-      const frameArea = width * height;
+        for (let i = 0; i < contourArray.length; i += 1) {
+          step = `${attemptLabel}_contour_${i}_copy`;
+          reportStage(step);
+          const contour = OpenCV.copyObjectFromVector(contours, i);
 
-      step = 'toJSValue';
-      reportStage(step);
-      const contourVector = OpenCV.toJSValue(contours);
-      const contourArray = Array.isArray(contourVector?.array) ? contourVector.array : [];
+          step = `${attemptLabel}_contour_${i}_area`;
+          reportStage(step);
+          const { value: rawArea } = OpenCV.invoke('contourArea', contour, false);
+          if (typeof rawArea !== 'number' || !isFinite(rawArea) || rawArea < 40) {
+            continue;
+          }
 
-      for (let i = 0; i < contourArray.length; i += 1) {
-        step = `contour_${i}_copy`;
-        reportStage(step);
-        const contour = OpenCV.copyObjectFromVector(contours, i);
+          const resizedAreaRatio = rawArea / resizedArea;
+          if (resizedAreaRatio < 0.0001 || resizedAreaRatio > 0.97) {
+            continue;
+          }
 
-        // Compute absolute area first
-        step = `contour_${i}_area_abs`;
-        reportStage(step);
-        const { value: area } = OpenCV.invoke('contourArea', contour, false);
+          let contourToUse = contour;
+          try {
+            const hull = OpenCV.createObject(ObjectType.PointVector);
+            OpenCV.invoke('convexHull', contour, hull, false, true);
+            contourToUse = hull;
+          } catch (err) {
+            if (__DEV__) {
+              console.warn('[DocScanner] convexHull failed, using original contour');
+            }
+          }
 
-        // Skip extremely small contours, but keep threshold very low to allow distant documents
-        if (typeof area !== 'number' || !isFinite(area)) {
-          continue;
-        }
+          const { value: perimeter } = OpenCV.invoke('arcLength', contourToUse, true);
+          if (typeof perimeter !== 'number' || !isFinite(perimeter) || perimeter < 40) {
+            continue;
+          }
 
-        if (area < 50) {
-          continue;
-        }
+          const approx = OpenCV.createObject(ObjectType.PointVector);
+          const epsilonValues = [
+            0.012, 0.01, 0.008, 0.006, 0.005, 0.004, 0.0035, 0.003, 0.0025, 0.002, 0.0016, 0.0012,
+          ];
 
-        step = `contour_${i}_area`; // ratio stage
-        reportStage(step);
-        const areaRatio = area / frameArea;
+          let approxArray: Array<{ x: number; y: number }> = [];
 
-        if (__DEV__) {
-          console.log('[DocScanner] area', area, 'ratio', areaRatio);
-        }
+          for (let attempt = 0; attempt < epsilonValues.length; attempt += 1) {
+            const epsilon = epsilonValues[attempt] * perimeter;
+            step = `${attemptLabel}_contour_${i}_approx_${attempt}`;
+            reportStage(step);
+            OpenCV.invoke('approxPolyDP', contourToUse, approx, epsilon, true);
 
-        // Skip if area ratio is too small or too large
-        if (areaRatio < 0.0002 || areaRatio > 0.99) {
-          continue;
-        }
+            const approxValue = OpenCV.toJSValue(approx);
+            const candidate = Array.isArray(approxValue?.array) ? approxValue.array : [];
 
-        // Try to use convex hull for better corner detection
-        let contourToUse = contour;
-        try {
-          step = `contour_${i}_convexHull`;
-          reportStage(step);
-          const hull = OpenCV.createObject(ObjectType.PointVector);
-          OpenCV.invoke('convexHull', contour, hull, false, true);
-          contourToUse = hull;
-        } catch (err) {
-          // If convexHull fails, use original contour
-          if (__DEV__) {
-            console.warn('[DocScanner] convexHull failed, using original contour');
+            if (candidate.length === 4) {
+              approxArray = candidate as Array<{ x: number; y: number }>;
+              break;
+            }
           }
-        }
 
-        step = `contour_${i}_arcLength`;
-        reportStage(step);
-        const { value: perimeter } = OpenCV.invoke('arcLength', contourToUse, true);
-        const approx = OpenCV.createObject(ObjectType.PointVector);
+          if (approxArray.length !== 4) {
+            continue;
+          }
 
-        let approxArray: Array<{ x: number; y: number }> = [];
+          const isValidPoint = (pt: { x: number; y: number }) =>
+            typeof pt.x === 'number' && typeof pt.y === 'number' && isFinite(pt.x) && isFinite(pt.y);
 
-        // Try more epsilon values from 0.1% to 10% for difficult shapes
-        const epsilonValues = [
-          0.001, 0.002, 0.003, 0.004, 0.005, 0.006, 0.007, 0.008, 0.009,
-          0.01, 0.012, 0.015, 0.018, 0.02, 0.025, 0.03, 0.04, 0.05, 0.06, 0.07, 0.08, 0.09, 0.1
-        ];
+          if (!approxArray.every(isValidPoint)) {
+            continue;
+          }
 
-        for (let attempt = 0; attempt < epsilonValues.length; attempt += 1) {
-          const epsilon = epsilonValues[attempt] * perimeter;
-          step = `contour_${i}_approxPolyDP_attempt_${attempt}`;
-          reportStage(step);
-          OpenCV.invoke('approxPolyDP', contourToUse, approx, epsilon, true);
+          const normalizedPoints: Point[] = approxArray.map((pt) => ({
+            x: pt.x / ratio,
+            y: pt.y / ratio,
+          }));
 
-          step = `contour_${i}_toJS_attempt_${attempt}`;
-          reportStage(step);
-          const approxValue = OpenCV.toJSValue(approx);
-          const candidate = Array.isArray(approxValue?.array) ? approxValue.array : [];
+          if (!isConvexQuadrilateral(normalizedPoints)) {
+            continue;
+          }
 
-          if (__DEV__) {
-            console.log('[DocScanner] approx length', candidate.length, 'epsilon', epsilon);
+          const sanitized = sanitizeQuad(orderQuadPoints(normalizedPoints));
+          if (!isValidQuad(sanitized)) {
+            continue;
           }
 
-          if (candidate.length === 4) {
-            approxArray = candidate as Array<{ x: number; y: number }>;
-            break;
+          const quadEdges = quadEdgeLengths(sanitized);
+          const minEdge = Math.min(...quadEdges);
+          const maxEdge = Math.max(...quadEdges);
+          if (!Number.isFinite(minEdge) || minEdge < minEdgeThreshold) {
+            continue;
+          }
+          const aspectRatio = maxEdge / Math.max(minEdge, 1);
+          if (!Number.isFinite(aspectRatio) || aspectRatio > 9) {
+            continue;
           }
-        }
 
-        // Only proceed if we found exactly 4 corners
-        if (approxArray.length !== 4) {
-          continue;
-        }
+          const quadAreaValue = quadArea(sanitized);
+          const areaRatioOriginal = originalArea > 0 ? quadAreaValue / originalArea : 0;
+          if (areaRatioOriginal < 0.00008 || areaRatioOriginal > 0.92) {
+            continue;
+          }
 
-        step = `contour_${i}_convex`;
-        reportStage(step);
+          if (__DEV__) {
+            console.log('[DocScanner] candidate', attemptLabel, 'areaRatio', areaRatioOriginal);
+          }
 
-        // Validate points before processing
-        const isValidPoint = (pt: { x: number; y: number }) => {
-          return typeof pt.x === 'number' && typeof pt.y === 'number' &&
-                 !isNaN(pt.x) && !isNaN(pt.y) &&
-                 isFinite(pt.x) && isFinite(pt.y);
-        };
+          const candidate: DetectionCandidate = {
+            quad: sanitized,
+            area: quadAreaValue,
+            label: attemptLabel,
+          };
 
-        if (!approxArray.every(isValidPoint)) {
-          if (__DEV__) {
-            console.warn('[DocScanner] invalid points in approxArray', approxArray);
+          if (!bestLocal || candidate.area > bestLocal.area) {
+            bestLocal = candidate;
           }
-          continue;
         }
 
-        const points: Point[] = approxArray.map((pt: { x: number; y: number }) => ({
-          x: pt.x / ratio,
-          y: pt.y / ratio,
-        }));
+        return bestLocal;
+      };
 
-        // Verify the quadrilateral is convex (valid document shape)
-        try {
-          if (!isConvexQuadrilateral(points)) {
-            if (__DEV__) {
-              console.log('[DocScanner] not convex, skipping:', points);
-            }
-            continue;
-          }
-        } catch (err) {
-          if (__DEV__) {
-            console.warn('[DocScanner] convex check error:', err, 'points:', points);
-          }
-          continue;
+      const considerCandidate = (candidate: DetectionCandidate | null) => {
+        'worklet';
+        if (!candidate) {
+          return;
+        }
+        if (__DEV__) {
+          console.log('[DocScanner] best so far from', candidate.label, 'area', candidate.area);
+        }
+        if (!bestCandidate || candidate.area > bestCandidate.area) {
+          bestCandidate = candidate;
         }
+      };
 
-        if (area > maxArea) {
-          best = points;
-          maxArea = area;
+      const ADAPTIVE_THRESH_GAUSSIAN_C = 1;
+      const THRESH_BINARY = 0;
+      const THRESH_OTSU = 8;
+
+      step = 'prepareMorphology';
+      reportStage(step);
+      const morphologyKernel = OpenCV.createObject(ObjectType.Size, 5, 5);
+      const element = OpenCV.invoke('getStructuringElement', MorphShapes.MORPH_RECT, morphologyKernel);
+      const blurKernelSize = OpenCV.createObject(ObjectType.Size, 5, 5);
+
+      // Edge-preserving smoothing for noisy frames
+      step = 'bilateralFilter';
+      reportStage(step);
+      let filteredMat = mat;
+      try {
+        const tempMat = OpenCV.createObject(ObjectType.Mat);
+        OpenCV.invoke('bilateralFilter', mat, tempMat, 9, 75, 75);
+        filteredMat = tempMat;
+      } catch (error) {
+        if (__DEV__) {
+          console.warn('[DocScanner] bilateralFilter unavailable, falling back to GaussianBlur', error);
         }
       }
 
+      step = 'gaussianBlur';
+      reportStage(step);
+      OpenCV.invoke('GaussianBlur', filteredMat, filteredMat, blurKernelSize, 0);
+
+      step = 'morphologyClose';
+      reportStage(step);
+      OpenCV.invoke('morphologyEx', filteredMat, filteredMat, MorphTypes.MORPH_CLOSE, element);
+
+      const baseGray = OpenCV.invoke('clone', filteredMat);
+
+      const runCanny = (label: string, low: number, high: number) => {
+        'worklet';
+        const working = OpenCV.invoke('clone', baseGray);
+        step = `${label}_canny`;
+        reportStage(step);
+        OpenCV.invoke('Canny', working, working, low, high);
+        OpenCV.invoke('morphologyEx', working, working, MorphTypes.MORPH_CLOSE, element);
+        considerCandidate(evaluateContours(working, label));
+      };
+
+      runCanny('canny_primary', CANNY_LOW, CANNY_HIGH);
+      runCanny('canny_soft', Math.max(8, CANNY_LOW * 0.6), CANNY_HIGH * 0.7 + CANNY_LOW * 0.2);
+
+      const runAdaptive = (label: string, blockSize: number, c: number, thresholdMode: number) => {
+        'worklet';
+        const working = OpenCV.invoke('clone', baseGray);
+        step = `${label}_adaptive`;
+        reportStage(step);
+        if (thresholdMode === THRESH_OTSU) {
+          OpenCV.invoke('threshold', working, working, 0, 255, THRESH_BINARY | THRESH_OTSU);
+        } else {
+          OpenCV.invoke('adaptiveThreshold', working, working, 255, ADAPTIVE_THRESH_GAUSSIAN_C, THRESH_BINARY, blockSize, c);
+        }
+        OpenCV.invoke('morphologyEx', working, working, MorphTypes.MORPH_CLOSE, element);
+        considerCandidate(evaluateContours(working, label));
+      };
+
+      runAdaptive('adaptive', 19, 7, THRESH_BINARY);
+      runAdaptive('otsu', 0, 0, THRESH_OTSU);
+
       step = 'clearBuffers';
       reportStage(step);
       OpenCV.clearBuffers();
       step = 'updateQuad';
       reportStage(step);
-      updateQuad(best);
+      if (bestCandidate) {
+        updateQuad((bestCandidate as DetectionCandidate).quad);
+      } else {
+        updateQuad(null);
+      }
     } catch (error) {
       reportError(step, error);
     }

package/src/index.ts

@@ -20,3 +20,4 @@ export {
   scaleCoordinates,
   scaleRectangle,
 } from './utils/coordinate';
+export { DocumentDetector } from './utils/documentDetection';

package/src/utils/documentDetection.ts

@@ -0,0 +1,278 @@
+import {
+  OpenCV,
+  ColorConversionCodes,
+  MorphShapes,
+  MorphTypes,
+  RetrievalModes,
+  ContourApproximationModes,
+} from 'react-native-fast-opencv';
+import type { Point } from '../types';
+
+type MatLike = { release?: () => void } | null | undefined;
+
+type Size = { width: number; height: number };
+
+type Quad = [Point, Point, Point, Point];
+
+const OUTPUT_SIZE: Size = { width: 800, height: 600 };
+const MIN_AREA = 1000;
+const GAUSSIAN_KERNEL: Size = { width: 5, height: 5 };
+const MORPH_KERNEL: Size = { width: 3, height: 3 };
+const ADAPTIVE_THRESH_GAUSSIAN_C = 1;
+const THRESH_BINARY = 0;
+
+const safeRelease = (mat: MatLike) => {
+  if (mat && typeof mat.release === 'function') {
+    mat.release();
+  }
+};
+
+const normalizePoint = (value: unknown): Point | null => {
+  if (!value) {
+    return null;
+  }
+
+  if (Array.isArray(value) && value.length >= 2) {
+    const [x, y] = value;
+    const px = Number(x);
+    const py = Number(y);
+    return Number.isFinite(px) && Number.isFinite(py) ? { x: px, y: py } : null;
+  }
+
+  if (typeof value === 'object') {
+    const maybePoint = value as { x?: unknown; y?: unknown };
+    const px = Number(maybePoint.x);
+    const py = Number(maybePoint.y);
+    return Number.isFinite(px) && Number.isFinite(py) ? { x: px, y: py } : null;
+  }
+
+  return null;
+};
+
+const toPointArray = (value: unknown): Point[] | null => {
+  if (!value) {
+    return null;
+  }
+
+  if (Array.isArray(value)) {
+    const points = value.map(normalizePoint).filter((point): point is Point => point !== null);
+    return points.length === value.length ? points : null;
+  }
+
+  if (typeof value === 'object') {
+    const mat = value as { data32F?: number[]; data64F?: number[]; data32S?: number[] };
+    const data = mat.data32F ?? mat.data64F ?? mat.data32S;
+    if (!data || data.length < 8) {
+      return null;
+    }
+
+    const points: Point[] = [];
+    for (let i = 0; i + 1 < data.length; i += 2) {
+      const x = data[i];
+      const y = data[i + 1];
+      if (Number.isFinite(x) && Number.isFinite(y)) {
+        points.push({ x, y });
+      }
+    }
+
+    return points.length >= 4 ? points.slice(0, 4) : null;
+  }
+
+  return null;
+};
+
+const ensureQuad = (points: Point[] | null): Quad | null => {
+  if (!points || points.length < 4) {
+    return null;
+  }
+
+  const quad: Quad = [points[0], points[1], points[2], points[3]];
+  for (const point of quad) {
+    if (typeof point.x !== 'number' || typeof point.y !== 'number') {
+      return null;
+    }
+  }
+
+  return quad;
+};
+
+/**
+ * Provides document detection utilities using react-native-fast-opencv.
+ */
+export class DocumentDetector {
+  private static initialized = false;
+
+  /** Initialize OpenCV runtime once */
+  static async initialize(): Promise<void> {
+    if (!DocumentDetector.initialized) {
+      await OpenCV.initialize();
+      DocumentDetector.initialized = true;
+    }
+  }
+
+  /** Find document contours and return the largest quadrilateral */
+  static async findDocumentContours(imagePath: string): Promise<Quad | null> {
+    await DocumentDetector.initialize();
+
+    let image: MatLike;
+    let gray: MatLike;
+    let blurred: MatLike;
+    let thresh: MatLike;
+    let morphed: MatLike;
+    let kernel: MatLike;
+
+    try {
+      image = OpenCV.imread(imagePath);
+      gray = OpenCV.cvtColor(image, ColorConversionCodes.COLOR_BGR2GRAY);
+      blurred = OpenCV.GaussianBlur(gray, GAUSSIAN_KERNEL, 0);
+
+      thresh = OpenCV.adaptiveThreshold(
+        blurred,
+        255,
+        ADAPTIVE_THRESH_GAUSSIAN_C,
+        THRESH_BINARY,
+        11,
+        2,
+      );
+
+      kernel = OpenCV.getStructuringElement(MorphShapes.MORPH_RECT, MORPH_KERNEL);
+      morphed = OpenCV.morphologyEx(thresh, MorphTypes.MORPH_CLOSE, kernel);
+
+      const contours = OpenCV.findContours(
+        morphed,
+        RetrievalModes.RETR_EXTERNAL,
+        ContourApproximationModes.CHAIN_APPROX_SIMPLE,
+      );
+
+      let largestQuad: Quad | null = null;
+      let maxArea = 0;
+
+      for (const contour of contours) {
+        const area = OpenCV.contourArea(contour);
+        if (area <= maxArea || area <= MIN_AREA) {
+          continue;
+        }
+
+        const perimeter = OpenCV.arcLength(contour, true);
+        const approx = OpenCV.approxPolyDP(contour, 0.02 * perimeter, true);
+        const points = ensureQuad(toPointArray(approx));
+
+        safeRelease(approx as MatLike);
+
+        if (!points) {
+          continue;
+        }
+
+        maxArea = area;
+        largestQuad = points;
+      }
+
+      return largestQuad;
+    } catch (error) {
+      if (__DEV__) {
+        console.error('[DocumentDetector] findDocumentContours error', error);
+      }
+      return null;
+    } finally {
+      safeRelease(kernel);
+      safeRelease(morphed);
+      safeRelease(thresh);
+      safeRelease(blurred);
+      safeRelease(gray);
+      safeRelease(image);
+    }
+  }
+
+  /** Apply a perspective transform using detected corners */
+  static async perspectiveTransform(
+    imagePath: string,
+    corners: Quad,
+    outputSize: Size = OUTPUT_SIZE,
+  ): Promise<string | null> {
+    await DocumentDetector.initialize();
+
+    let image: MatLike;
+    let srcPoints: MatLike;
+    let dstPoints: MatLike;
+    let transformMatrix: MatLike;
+    let warped: MatLike;
+
+    try {
+      image = OpenCV.imread(imagePath);
+
+      srcPoints = OpenCV.matFromArray(4, 1, OpenCV.CV_32FC2, [
+        corners[0].x,
+        corners[0].y,
+        corners[1].x,
+        corners[1].y,
+        corners[2].x,
+        corners[2].y,
+        corners[3].x,
+        corners[3].y,
+      ]);
+
+      dstPoints = OpenCV.matFromArray(4, 1, OpenCV.CV_32FC2, [
+        0,
+        0,
+        outputSize.width,
+        0,
+        outputSize.width,
+        outputSize.height,
+        0,
+        outputSize.height,
+      ]);
+
+      transformMatrix = OpenCV.getPerspectiveTransform(srcPoints, dstPoints);
+
+      warped = OpenCV.warpPerspective(image, transformMatrix, outputSize);
+
+      const outputPath = imagePath.replace(/\.jpg$/i, '_normalized.jpg');
+      OpenCV.imwrite(outputPath, warped);
+
+      return outputPath;
+    } catch (error) {
+      if (__DEV__) {
+        console.error('[DocumentDetector] perspectiveTransform error', error);
+      }
+      return null;
+    } finally {
+      safeRelease(warped);
+      safeRelease(transformMatrix);
+      safeRelease(dstPoints);
+      safeRelease(srcPoints);
+      safeRelease(image);
+    }
+  }
+
+  /** Detect document and apply normalization */
+  static async detectAndNormalize(imagePath: string, outputSize?: Size): Promise<string | null> {
+    try {
+      const corners = await DocumentDetector.findDocumentContours(imagePath);
+      if (!corners) {
+        if (__DEV__) {
+          console.log('[DocumentDetector] No document detected');
+        }
+        return null;
+      }
+
+      return DocumentDetector.perspectiveTransform(imagePath, corners, outputSize ?? OUTPUT_SIZE);
+    } catch (error) {
+      if (__DEV__) {
+        console.error('[DocumentDetector] detectAndNormalize error', error);
+      }
+      return null;
+    }
+  }
+
+  /** Only detect document corners without transforming */
+  static async getDocumentBounds(imagePath: string): Promise<Quad | null> {
+    try {
+      return DocumentDetector.findDocumentContours(imagePath);
+    } catch (error) {
+      if (__DEV__) {
+        console.error('[DocumentDetector] getDocumentBounds error', error);
+      }
+      return null;
+    }
+  }
+}