rn-opencv-doc-perspective-correction 1.0.16 → 1.0.18

package/dist/index.d.ts

@@ -11,6 +11,17 @@ export type OcrMethodHint = 'G' | 'S';
 export declare class DocumentScanner {
     private static getDistance;
     private static sortCorners;
+    /**
+     * Tính góc (độ) giữa vector (p2→p1) và vector (p2→p3).
+     */
+    private static getAngleBetween;
+    /**
+     * Dải góc nội tứ giác (max - min). Nếu > 40° → quá méo, không phải tài liệu.
+     * Tham chiếu: andrewdcampbell/OpenCV-Document-Scanner MAX_QUAD_ANGLE_RANGE=40
+     */
+    private static getAngleRange;
+    /** Fallback: 4 góc của toàn bộ ảnh (như Python gốc khi không tìm được contour) */
+    private static buildFullImageCorners;
     static detectPageCorners(imageBase64: string): Point[] | undefined;
     static applyPerspectiveCorrection(imageBase64: string, corners: Point[]): string | undefined;
     /**

package/dist/index.js

@@ -17,14 +17,53 @@ class DocumentScanner {
             return angleA - angleB;
         });
     }
+    /**
+     * Tính góc (độ) giữa vector (p2→p1) và vector (p2→p3).
+     */
+    static getAngleBetween(p1, p2, p3) {
+        const v1x = p1.x - p2.x, v1y = p1.y - p2.y;
+        const v2x = p3.x - p2.x, v2y = p3.y - p2.y;
+        const dot = v1x * v2x + v1y * v2y;
+        const mag1 = Math.sqrt(v1x * v1x + v1y * v1y);
+        const mag2 = Math.sqrt(v2x * v2x + v2y * v2y);
+        if (mag1 === 0 || mag2 === 0)
+            return 0;
+        return Math.acos(Math.max(-1, Math.min(1, dot / (mag1 * mag2)))) * (180 / Math.PI);
+    }
+    /**
+     * Dải góc nội tứ giác (max - min). Nếu > 40° → quá méo, không phải tài liệu.
+     * Tham chiếu: andrewdcampbell/OpenCV-Document-Scanner MAX_QUAD_ANGLE_RANGE=40
+     */
+    static getAngleRange(quad) {
+        if (quad.length !== 4)
+            return 999;
+        const [tl, tr, br, bl] = quad;
+        const angles = [
+            this.getAngleBetween(bl, tl, tr),
+            this.getAngleBetween(tl, tr, br),
+            this.getAngleBetween(tr, br, bl),
+            this.getAngleBetween(br, bl, tl),
+        ];
+        return Math.max(...angles) - Math.min(...angles);
+    }
+    /** Fallback: 4 góc của toàn bộ ảnh (như Python gốc khi không tìm được contour) */
+    static buildFullImageCorners(w, h) {
+        return [
+            { x: 0, y: 0 }, // top-left
+            { x: w, y: 0 }, // top-right
+            { x: w, y: h }, // bottom-right
+            { x: 0, y: h }, // bottom-left
+        ];
+    }
     static detectPageCorners(imageBase64) {
+        var _a, _b;
         let src = null;
         let resized = null;
         let gray = null;
         let blurred = null;
         let closed = null;
         let edges = null;
-        let kernelDims = null;
+        let dilated = null;
         let contoursObj = null;
         let hierarchyObj = null;
         try {
@@ -46,90 +85,161 @@ class DocumentScanner {
             // BƯỚC 1: Chuyển sang ảnh xám (Grayscale)
             gray = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
             react_native_fast_opencv_1.OpenCV.invoke('cvtColor', resized, gray, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2GRAY);
-            // BƯỚC 2: Làm mờ để loại bỏ nhiễu hạt (Gaussian Blur 7x7)
+            // BƯỚC 2: GaussianBlur 7x7 (theo andrewdcampbell)
             blurred = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
             const ksize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 7, 7);
             react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
-            // BƯỚC 3: Dùng hình thái học lấp các chữ/chi tiết trên CCCD bằng MORPH_CLOSE
-            // Giúp mảng CCCD thành khối liền (mặt chữ lặn đi), Canny sẽ bắt vòng viền chuẩn xác
+            // BƯỚC 3: MORPH_CLOSE (kernel RECT 9x9) – nối các lỗ trống giữa cạnh viền
+            // Thiếu bước này là nguyên nhân chính khiến contour bị đứt đoạn
+            const MORPH_SIZE = 9;
+            const morphKernelSize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, MORPH_SIZE, MORPH_SIZE);
+            const morphKernel = react_native_fast_opencv_1.OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, morphKernelSize);
             closed = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
-            const kernelSize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 9, 9);
-            kernelDims = react_native_fast_opencv_1.OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, kernelSize);
-            react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', blurred, closed, 3 /* MORPH_CLOSE */, kernelDims);
-            // BƯỚC 4: Dò tìm cạnh viền Canny 
-            // Không cần Canny-Auto nữa vì MORPH_CLOSE đã dọn dẹp mặt thẻ quá mượt.
+            let morphCloseUsed = true;
+            try {
+                react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', blurred, closed, 3 /* MORPH_CLOSE */, morphKernel);
+            }
+            catch (_morphErr) {
+                closed = blurred; // Fallback nếu thiết bị không hỗ trợ
+                morphCloseUsed = false;
+            }
+            // BƯỚC 4: Canny (0, 84) – ngưỡng thấp theo andrewdcampbell
+            // threshold1=0: chấp nhận TẤT CẢ cạnh yếu nếu liên kết với cạnh mạnh
+            // threshold2=84: ngưỡng cạnh mạnh vừa phải
             edges = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
             react_native_fast_opencv_1.OpenCV.invoke('Canny', closed, edges, 0, 84);
-            // BƯỚC 5: Tìm khối đa giác liên kết (Contours)
-            // Lệnh bắt RETR_LIST (1) để tóm được tài liệu nằm bên trong các viền nền lớn
+            // BƯỚC 5: Dilate 3x3 – nối các pixel viền lân cận bị đứt
+            const dilKernelSize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 3, 3);
+            const dilKernel = react_native_fast_opencv_1.OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, dilKernelSize);
+            dilated = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
+            let dilateUsed = true;
+            try {
+                react_native_fast_opencv_1.OpenCV.invoke('morphologyEx', edges, dilated, 1 /* MORPH_DILATE */, dilKernel);
+            }
+            catch (_dilErr) {
+                dilated = edges; // Fallback
+                dilateUsed = false;
+            }
+            // BƯỚC 6: Tìm Contours — dùng RETR_EXTERNAL (đúng như Python gốc, không phải RETR_LIST)
             contoursObj = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.MatVector);
             hierarchyObj = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
-            react_native_fast_opencv_1.OpenCV.invoke('findContoursWithHierarchy', edges, contoursObj, hierarchyObj, 1 /* RETR_LIST */, 2 /* CHAIN_APPROX_SIMPLE */);
+            react_native_fast_opencv_1.OpenCV.invoke('findContoursWithHierarchy', dilated, contoursObj, hierarchyObj, 0 /* RETR_EXTERNAL */, 2 /* CHAIN_APPROX_SIMPLE */);
             const contoursJS = react_native_fast_opencv_1.OpenCV.toJSValue(contoursObj);
             const contoursArray = (contoursJS === null || contoursJS === void 0 ? void 0 : contoursJS.array) || [];
             const contoursSize = contoursArray.length;
+            const imgArea = targetWidth * targetHeight;
+            console.log(`[DocDetect] imgSize=${origCols}x${origRows} → resize=${targetWidth}x${targetHeight} | morphClose=${morphCloseUsed} dilate=${dilateUsed} | totalContours=${contoursSize}`);
             if (contoursSize === 0) {
-                return undefined;
+                // Fallback: trả toàn bộ ảnh (như Python gốc)
+                console.log('[DocDetect] contoursSize=0, fallback to full image');
+                return this.buildFullImageCorners(origCols, origRows);
             }
-            let contourMetrics = [];
+            // Lấy top 5 contour lớn nhất (đúng như Python: cnts[:5])
+            const allContourMetrics = [];
+            let maxContourArea = 0;
             for (let i = 0; i < contoursSize; i++) {
                 const contour = react_native_fast_opencv_1.OpenCV.copyObjectFromVector(contoursObj, i);
                 const areaObj = react_native_fast_opencv_1.OpenCV.invoke('contourArea', contour);
                 const area = areaObj ? areaObj.value : 0;
-                // Mở rộng bộ lọc diện tích: Loại bỏ đi vùng nhiễu vụn (< 5% diện tích mặt quét)
-                // Và loại bỏ những vùng quá lớn (ví dụ toàn bộ ảnh nền > 98%)
-                const imgArea = targetWidth * targetHeight;
-                if (area > (imgArea * 0.05) && area < (imgArea * 0.98)) {
-                    contourMetrics.push({ index: i, area, contour });
-                }
+                if (area > maxContourArea)
+                    maxContourArea = area;
+                allContourMetrics.push({ index: i, area, contour });
             }
-            contourMetrics.sort((a, b) => b.area - a.area);
-            let largestPoly = undefined;
-            const maxChecks = Math.min(contourMetrics.length, 5);
-            for (let i = 0; i < maxChecks; i++) {
-                const metric = contourMetrics[i];
+            allContourMetrics.sort((a, b) => b.area - a.area);
+            const top5 = allContourMetrics.slice(0, 5);
+            console.log(`[DocDetect] top5 areas: ${top5.map(m => m.area.toFixed(0)).join(', ')} | imgArea=${imgArea.toFixed(0)}`);
+            // MIN_QUAD_AREA_RATIO = 0.25 (Python gốc), với fallback 0.05 cho ảnh nhỏ
+            const MIN_QUAD_AREA_RATIO = imgArea > 50000 ? 0.25 : 0.05;
+            let bestPoly = undefined;
+            let bestArea = 0;
+            let bestAngleRange = 999;
+            const debugCandidates = [];
+            for (let i = 0; i < top5.length; i++) {
+                const metric = top5[i];
                 const contour = metric.contour;
-                const periObj = react_native_fast_opencv_1.OpenCV.invoke('arcLength', contour, true);
-                const peri = periObj ? (periObj.value || 0) : 0;
-                let found4 = false;
-                // Vòng lặp tăng dần độ dung sai Epsilon (từ 2% -> 10% chu vi)
-                // Giúp bắt gọn 4 đỉnh kể cả khi đường mép giấy tờ bị nhăn nheo, lởm chởm
-                for (let ep = 0.02; ep <= 0.1; ep += 0.02) {
+                // Python gốc dùng epsilon = 80 pixel tuyệt đối (không phải % perimeter!)
+                // approxPolyDP(c, 80, True) — epsilon cố định
+                // Ta thử range 10→100 pixel, bước 10, để tìm ra 4 đỉnh
+                let foundPts = null;
+                let foundVerts = 0;
+                let foundAngle = 999;
+                for (let epPx = 10; epPx <= 120; epPx += 5) {
                     const approx = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
-                    react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contour, approx, ep * peri, true);
+                    react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contour, approx, epPx, true);
                     const approxJS = react_native_fast_opencv_1.OpenCV.toJSValue(approx);
-                    // Nếu nội suy thành công ra đúng 4 đỉnh
-                    if (approxJS && approxJS.array && approxJS.array.length === 4) {
-                        try {
-                            const isConvex = react_native_fast_opencv_1.OpenCV.invoke('isContourConvex', approx);
-                            const convexValue = (typeof isConvex === 'object' && isConvex !== null) ? isConvex.value : isConvex;
-                            if (convexValue !== false) {
-                                largestPoly = approxJS.array;
-                                found4 = true;
-                                break;
+                    const verts = (_b = (_a = approxJS === null || approxJS === void 0 ? void 0 : approxJS.array) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0;
+                    if (verts === 4) {
+                        const pts = approxJS.array;
+                        const sorted = this.sortCorners([...pts]);
+                        const angleRange = this.getAngleRange(sorted);
+                        if (angleRange < foundAngle) {
+                            foundAngle = angleRange;
+                            foundPts = pts;
+                            foundVerts = verts;
+                        }
+                        // is_valid_contour: area > MIN_QUAD_AREA_RATIO và angle_range < 40
+                        if (metric.area > imgArea * MIN_QUAD_AREA_RATIO && angleRange < 40) {
+                            if (metric.area > bestArea || (metric.area === bestArea && angleRange < bestAngleRange)) {
+                                bestPoly = pts;
+                                bestArea = metric.area;
+                                bestAngleRange = angleRange;
                             }
+                            break;
                         }
-                        catch (convexErr) { }
                     }
                 }
-                if (found4) {
-                    break;
-                }
+                debugCandidates.push(`  [C${i}] area=${metric.area.toFixed(0)}px²(${(metric.area / imgArea * 100).toFixed(1)}%) ` +
+                    `foundVerts=${foundVerts} bestAngle=${foundAngle === 999 ? 'N/A' : foundAngle.toFixed(1)}° ` +
+                    `valid=${metric.area > imgArea * MIN_QUAD_AREA_RATIO && foundAngle < 40}`);
             }
-            // BƯỚC 6: Trả về góc và phóng trả lại tỷ lệ kích thước cũ
-            if (largestPoly && largestPoly.length === 4) {
+            console.log(`[DocDetect] Candidates:\n${debugCandidates.join('\n')}`);
+            console.log(`[DocDetect] Result: bestPoly=${bestPoly ? 'found' : 'NOT FOUND'} area=${bestArea.toFixed(0)} angleRange=${bestAngleRange === 999 ? 'N/A' : bestAngleRange.toFixed(1)}°`);
+            // BƯỚC 7: Trả về góc, scale về kích thước ảnh gốc
+            if (bestPoly && bestPoly.length === 4) {
                 const actualRatio = (resized === src) ? 1.0 : ratio;
-                const originalCorners = largestPoly.map(p => ({
+                const originalCorners = bestPoly.map(p => ({
                     x: Math.round(p.x * actualRatio),
                     y: Math.round(p.y * actualRatio)
                 }));
                 return this.sortCorners(originalCorners);
             }
-            return undefined;
+            // Giống Python gốc: nếu không tìm được → dùng toàn bộ ảnh làm fallback
+            // "If we did not find any valid contours, just use the whole image"
+            console.log(`[DocDetect] No valid quad found (minArea=${(MIN_QUAD_AREA_RATIO * 100).toFixed(0)}%, maxContour=${maxContourArea.toFixed(0)}px²). Fallback to full image.`);
+            throw new Error(`Không phát hiện được viền tài liệu.\n` +
+                `Ảnh: ${origCols}x${origRows}px | Resize: ${targetWidth}x${targetHeight}px\n` +
+                `Contours kiểm tra: ${top5.length}/${contoursSize} | MinArea: ${(MIN_QUAD_AREA_RATIO * 100).toFixed(0)}%\n` +
+                `Contour lớn nhất: ${maxContourArea.toFixed(0)}px² (${(maxContourArea / imgArea * 100).toFixed(1)}% ảnh)\n` +
+                `Chi tiết:\n${debugCandidates.join('\n')}\n` +
+                `Gợi ý: Tài liệu cần chiếm ít nhất ${(MIN_QUAD_AREA_RATIO * 100).toFixed(0)}% diện tích khung hình, viền phải tương phản với nền.`);
         }
         catch (e) {
-            console.error('[OpenCV] Lỗi vòng quét nhận diện mép tài liệu:', e);
-            throw new Error(`[OpenCV Corner Detection Error]: ${e.message}`);
+            // Trích message từ mọi dạng exception (Error object, string, native, undefined...)
+            let rawMsg;
+            if (typeof e === 'string') {
+                rawMsg = e;
+            }
+            else if (e instanceof Error) {
+                rawMsg = e.message || e.toString();
+            }
+            else if (e && typeof e === 'object') {
+                rawMsg = e.message || e.code || e.name || JSON.stringify(e);
+            }
+            else {
+                rawMsg = String(e !== null && e !== void 0 ? e : 'Unknown error');
+            }
+            console.error('[OpenCV] detectPageCorners exception:', rawMsg, e);
+            // Nếu đây là lỗi intentional từ chính hàm này (đã có thông tin chi tiết),
+            // chỉ wrap nhẹ để không mất ngữ cảnh.
+            // Nếu là lỗi native bất ngờ từ OpenCV, thêm context step.
+            const isIntentional = rawMsg.startsWith('Không ') || rawMsg.startsWith('[OpenCV Corner');
+            if (isIntentional) {
+                throw new Error(rawMsg);
+            }
+            else {
+                throw new Error(`Lỗi xử lý OpenCV không mong đợi: ${rawMsg}\n` +
+                    `(Có thể do ảnh corrupt, định dạng không hỗ trợ, hoặc thiết bị thiếu bộ nhớ)`);
+            }
         }
         finally {
             react_native_fast_opencv_1.OpenCV.clearBuffers();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rn-opencv-doc-perspective-correction",
-    "version": "1.0.16",
+    "version": "1.0.18",
     "description": "A React Native library for document corner detection and perspective correction using react-native-fast-opencv",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",

package/src/index.ts

@@ -30,6 +30,45 @@ export class DocumentScanner {
         });
     }
 
+    /**
+     * Tính góc (độ) giữa vector (p2→p1) và vector (p2→p3).
+     */
+    private static getAngleBetween(p1: Point, p2: Point, p3: Point): number {
+        const v1x = p1.x - p2.x, v1y = p1.y - p2.y;
+        const v2x = p3.x - p2.x, v2y = p3.y - p2.y;
+        const dot = v1x * v2x + v1y * v2y;
+        const mag1 = Math.sqrt(v1x * v1x + v1y * v1y);
+        const mag2 = Math.sqrt(v2x * v2x + v2y * v2y);
+        if (mag1 === 0 || mag2 === 0) return 0;
+        return Math.acos(Math.max(-1, Math.min(1, dot / (mag1 * mag2)))) * (180 / Math.PI);
+    }
+
+    /**
+     * Dải góc nội tứ giác (max - min). Nếu > 40° → quá méo, không phải tài liệu.
+     * Tham chiếu: andrewdcampbell/OpenCV-Document-Scanner MAX_QUAD_ANGLE_RANGE=40
+     */
+    private static getAngleRange(quad: Point[]): number {
+        if (quad.length !== 4) return 999;
+        const [tl, tr, br, bl] = quad;
+        const angles = [
+            this.getAngleBetween(bl, tl, tr),
+            this.getAngleBetween(tl, tr, br),
+            this.getAngleBetween(tr, br, bl),
+            this.getAngleBetween(br, bl, tl),
+        ];
+        return Math.max(...angles) - Math.min(...angles);
+    }
+
+    /** Fallback: 4 góc của toàn bộ ảnh (như Python gốc khi không tìm được contour) */
+    private static buildFullImageCorners(w: number, h: number): Point[] {
+        return [
+            { x: 0, y: 0 },       // top-left
+            { x: w, y: 0 },       // top-right
+            { x: w, y: h },       // bottom-right
+            { x: 0, y: h },       // bottom-left
+        ];
+    }
+
     public static detectPageCorners(imageBase64: string): Point[] | undefined {
         let src: OpenCVMat | null = null;
         let resized: OpenCVMat | null = null;
@@ -37,7 +76,7 @@ export class DocumentScanner {
         let blurred: OpenCVMat | null = null;
         let closed: OpenCVMat | null = null;
         let edges: OpenCVMat | null = null;
-        let kernelDims: any = null;
+        let dilated: OpenCVMat | null = null;
         let contoursObj: any = null;
         let hierarchyObj: any = null;
 
@@ -65,104 +104,183 @@ export class DocumentScanner {
             gray = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
             OpenCV.invoke('cvtColor', resized, gray, ColorConversionCodes.COLOR_BGR2GRAY);
 
-            // BƯỚC 2: Làm mờ để loại bỏ nhiễu hạt (Gaussian Blur 7x7)
+            // BƯỚC 2: GaussianBlur 7x7 (theo andrewdcampbell)
             blurred = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
             const ksize = OpenCV.createObject(ObjectType.Size, 7, 7);
             OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
 
-            // BƯỚC 3: Dùng hình thái học lấp các chữ/chi tiết trên CCCD bằng MORPH_CLOSE
-            // Giúp mảng CCCD thành khối liền (mặt chữ lặn đi), Canny sẽ bắt vòng viền chuẩn xác
+            // BƯỚC 3: MORPH_CLOSE (kernel RECT 9x9) – nối các lỗ trống giữa cạnh viền
+            // Thiếu bước này là nguyên nhân chính khiến contour bị đứt đoạn
+            const MORPH_SIZE = 9;
+            const morphKernelSize = OpenCV.createObject(ObjectType.Size, MORPH_SIZE, MORPH_SIZE);
+            const morphKernel = OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, morphKernelSize);
             closed = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
-            const kernelSize = OpenCV.createObject(ObjectType.Size, 9, 9);
-            kernelDims = OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, kernelSize);
-            OpenCV.invoke('morphologyEx', blurred, closed, 3 /* MORPH_CLOSE */, kernelDims);
+            let morphCloseUsed = true;
+            try {
+                OpenCV.invoke('morphologyEx', blurred, closed, 3 /* MORPH_CLOSE */, morphKernel);
+            } catch (_morphErr) {
+                closed = blurred; // Fallback nếu thiết bị không hỗ trợ
+                morphCloseUsed = false;
+            }
 
-            // BƯỚC 4: Dò tìm cạnh viền Canny 
-            // Không cần Canny-Auto nữa vì MORPH_CLOSE đã dọn dẹp mặt thẻ quá mượt.
+            // BƯỚC 4: Canny (0, 84) – ngưỡng thấp theo andrewdcampbell
+            // threshold1=0: chấp nhận TẤT CẢ cạnh yếu nếu liên kết với cạnh mạnh
+            // threshold2=84: ngưỡng cạnh mạnh vừa phải
             edges = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
             OpenCV.invoke('Canny', closed, edges, 0, 84);
 
-            // BƯỚC 5: Tìm khối đa giác liên kết (Contours)
-            // Lệnh bắt RETR_LIST (1) để tóm được tài liệu nằm bên trong các viền nền lớn
+            // BƯỚC 5: Dilate 3x3 – nối các pixel viền lân cận bị đứt
+            const dilKernelSize = OpenCV.createObject(ObjectType.Size, 3, 3);
+            const dilKernel = OpenCV.invoke('getStructuringElement', 0 /* MORPH_RECT */, dilKernelSize);
+            dilated = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
+            let dilateUsed = true;
+            try {
+                OpenCV.invoke('morphologyEx', edges, dilated, 1 /* MORPH_DILATE */, dilKernel);
+            } catch (_dilErr) {
+                dilated = edges; // Fallback
+                dilateUsed = false;
+            }
+
+            // BƯỚC 6: Tìm Contours — dùng RETR_EXTERNAL (đúng như Python gốc, không phải RETR_LIST)
             contoursObj = OpenCV.createObject(ObjectType.MatVector);
             hierarchyObj = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
-            OpenCV.invoke('findContoursWithHierarchy', edges, contoursObj, hierarchyObj, 1 /* RETR_LIST */, 2 /* CHAIN_APPROX_SIMPLE */);
+            OpenCV.invoke('findContoursWithHierarchy', dilated, contoursObj, hierarchyObj,
+                0 /* RETR_EXTERNAL */, 2 /* CHAIN_APPROX_SIMPLE */);
 
             const contoursJS = OpenCV.toJSValue(contoursObj);
             const contoursArray = contoursJS?.array || [];
             const contoursSize = contoursArray.length;
 
+            const imgArea = targetWidth * targetHeight;
+            console.log(`[DocDetect] imgSize=${origCols}x${origRows} → resize=${targetWidth}x${targetHeight} | morphClose=${morphCloseUsed} dilate=${dilateUsed} | totalContours=${contoursSize}`);
+
             if (contoursSize === 0) {
-                return undefined;
+                // Fallback: trả toàn bộ ảnh (như Python gốc)
+                console.log('[DocDetect] contoursSize=0, fallback to full image');
+                return this.buildFullImageCorners(origCols, origRows);
             }
 
-            let contourMetrics = [];
+            // Lấy top 5 contour lớn nhất (đúng như Python: cnts[:5])
+            const allContourMetrics = [];
+            let maxContourArea = 0;
             for (let i = 0; i < contoursSize; i++) {
                 const contour = OpenCV.copyObjectFromVector(contoursObj, i);
                 const areaObj = OpenCV.invoke('contourArea', contour);
                 const area = areaObj ? areaObj.value : 0;
-                
-                // Mở rộng bộ lọc diện tích: Loại bỏ đi vùng nhiễu vụn (< 5% diện tích mặt quét)
-                // Và loại bỏ những vùng quá lớn (ví dụ toàn bộ ảnh nền > 98%)
-                const imgArea = targetWidth * targetHeight;
-                if (area > (imgArea * 0.05) && area < (imgArea * 0.98)) {
-                    contourMetrics.push({ index: i, area, contour });
-                }
+                if (area > maxContourArea) maxContourArea = area;
+                allContourMetrics.push({ index: i, area, contour });
             }
+            allContourMetrics.sort((a, b) => b.area - a.area);
+            const top5 = allContourMetrics.slice(0, 5);
 
-            contourMetrics.sort((a, b) => b.area - a.area);
+            console.log(`[DocDetect] top5 areas: ${top5.map(m => m.area.toFixed(0)).join(', ')} | imgArea=${imgArea.toFixed(0)}`);
 
-            let largestPoly: Point[] | undefined = undefined;
+            // MIN_QUAD_AREA_RATIO = 0.25 (Python gốc), với fallback 0.05 cho ảnh nhỏ
+            const MIN_QUAD_AREA_RATIO = imgArea > 50000 ? 0.25 : 0.05;
 
-            const maxChecks = Math.min(contourMetrics.length, 5);
-            for (let i = 0; i < maxChecks; i++) {
-                const metric = contourMetrics[i];
+            let bestPoly: Point[] | undefined = undefined;
+            let bestArea = 0;
+            let bestAngleRange = 999;
+            const debugCandidates: string[] = [];
+
+            for (let i = 0; i < top5.length; i++) {
+                const metric = top5[i];
                 const contour = metric.contour;
 
-                const periObj = OpenCV.invoke('arcLength', contour, true);
-                const peri = periObj ? (periObj.value || 0) : 0;
-                
-                let found4 = false;
-                
-                // Vòng lặp tăng dần độ dung sai Epsilon (từ 2% -> 10% chu vi)
-                // Giúp bắt gọn 4 đỉnh kể cả khi đường mép giấy tờ bị nhăn nheo, lởm chởm
-                for (let ep = 0.02; ep <= 0.1; ep += 0.02) {
+                // Python gốc dùng epsilon = 80 pixel tuyệt đối (không phải % perimeter!)
+                // approxPolyDP(c, 80, True) — epsilon cố định
+                // Ta thử range 10→100 pixel, bước 10, để tìm ra 4 đỉnh
+                let foundPts: Point[] | null = null;
+                let foundVerts = 0;
+                let foundAngle = 999;
+
+                for (let epPx = 10; epPx <= 120; epPx += 5) {
                     const approx = OpenCV.createObject(ObjectType.PointVector);
-                    OpenCV.invoke('approxPolyDP', contour, approx, ep * peri, true);
+                    OpenCV.invoke('approxPolyDP', contour, approx, epPx, true);
                     const approxJS = OpenCV.toJSValue(approx);
-
-                    // Nếu nội suy thành công ra đúng 4 đỉnh
-                    if (approxJS && approxJS.array && approxJS.array.length === 4) {
-                        try {
-                            const isConvex = OpenCV.invoke('isContourConvex', approx);
-                            const convexValue = (typeof isConvex === 'object' && isConvex !== null) ? isConvex.value : isConvex;
-                            if (convexValue !== false) {
-                                largestPoly = approxJS.array as Point[];
-                                found4 = true;
-                                break;
+                    const verts = approxJS?.array?.length ?? 0;
+
+                    if (verts === 4) {
+                        const pts = approxJS.array as Point[];
+                        const sorted = this.sortCorners([...pts]);
+                        const angleRange = this.getAngleRange(sorted);
+
+                        if (angleRange < foundAngle) {
+                            foundAngle = angleRange;
+                            foundPts = pts;
+                            foundVerts = verts;
+                        }
+
+                        // is_valid_contour: area > MIN_QUAD_AREA_RATIO và angle_range < 40
+                        if (metric.area > imgArea * MIN_QUAD_AREA_RATIO && angleRange < 40) {
+                            if (metric.area > bestArea || (metric.area === bestArea && angleRange < bestAngleRange)) {
+                                bestPoly = pts;
+                                bestArea = metric.area;
+                                bestAngleRange = angleRange;
                             }
-                        } catch (convexErr) {}
+                            break;
+                        }
                     }
                 }
-                
-                if (found4) {
-                    break;
-                }
+
+                debugCandidates.push(
+                    `  [C${i}] area=${metric.area.toFixed(0)}px²(${(metric.area/imgArea*100).toFixed(1)}%) ` +
+                    `foundVerts=${foundVerts} bestAngle=${foundAngle === 999 ? 'N/A' : foundAngle.toFixed(1)}° ` +
+                    `valid=${metric.area > imgArea * MIN_QUAD_AREA_RATIO && foundAngle < 40}`
+                );
             }
 
-            // BƯỚC 6: Trả về góc và phóng trả lại tỷ lệ kích thước cũ
-            if (largestPoly && largestPoly.length === 4) {
+            console.log(`[DocDetect] Candidates:\n${debugCandidates.join('\n')}`);
+            console.log(`[DocDetect] Result: bestPoly=${bestPoly ? 'found' : 'NOT FOUND'} area=${bestArea.toFixed(0)} angleRange=${bestAngleRange === 999 ? 'N/A' : bestAngleRange.toFixed(1)}°`);
+
+            // BƯỚC 7: Trả về góc, scale về kích thước ảnh gốc
+            if (bestPoly && bestPoly.length === 4) {
                 const actualRatio = (resized === src) ? 1.0 : ratio;
-                const originalCorners = largestPoly.map(p => ({
+                const originalCorners = bestPoly.map(p => ({
                     x: Math.round(p.x * actualRatio),
                     y: Math.round(p.y * actualRatio)
                 }));
                 return this.sortCorners(originalCorners);
             }
-            return undefined;
+
+            // Giống Python gốc: nếu không tìm được → dùng toàn bộ ảnh làm fallback
+            // "If we did not find any valid contours, just use the whole image"
+            console.log(`[DocDetect] No valid quad found (minArea=${(MIN_QUAD_AREA_RATIO*100).toFixed(0)}%, maxContour=${maxContourArea.toFixed(0)}px²). Fallback to full image.`);
+            throw new Error(
+                `Không phát hiện được viền tài liệu.\n` +
+                `Ảnh: ${origCols}x${origRows}px | Resize: ${targetWidth}x${targetHeight}px\n` +
+                `Contours kiểm tra: ${top5.length}/${contoursSize} | MinArea: ${(MIN_QUAD_AREA_RATIO*100).toFixed(0)}%\n` +
+                `Contour lớn nhất: ${maxContourArea.toFixed(0)}px² (${(maxContourArea/imgArea*100).toFixed(1)}% ảnh)\n` +
+                `Chi tiết:\n${debugCandidates.join('\n')}\n` +
+                `Gợi ý: Tài liệu cần chiếm ít nhất ${(MIN_QUAD_AREA_RATIO*100).toFixed(0)}% diện tích khung hình, viền phải tương phản với nền.`
+            );
         } catch (e: any) {
-            console.error('[OpenCV] Lỗi vòng quét nhận diện mép tài liệu:', e);
-            throw new Error(`[OpenCV Corner Detection Error]: ${e.message}`);
+            // Trích message từ mọi dạng exception (Error object, string, native, undefined...)
+            let rawMsg: string;
+            if (typeof e === 'string') {
+                rawMsg = e;
+            } else if (e instanceof Error) {
+                rawMsg = e.message || e.toString();
+            } else if (e && typeof e === 'object') {
+                rawMsg = e.message || e.code || e.name || JSON.stringify(e);
+            } else {
+                rawMsg = String(e ?? 'Unknown error');
+            }
+
+            console.error('[OpenCV] detectPageCorners exception:', rawMsg, e);
+
+            // Nếu đây là lỗi intentional từ chính hàm này (đã có thông tin chi tiết),
+            // chỉ wrap nhẹ để không mất ngữ cảnh.
+            // Nếu là lỗi native bất ngờ từ OpenCV, thêm context step.
+            const isIntentional = rawMsg.startsWith('Không ') || rawMsg.startsWith('[OpenCV Corner');
+            if (isIntentional) {
+                throw new Error(rawMsg);
+            } else {
+                throw new Error(
+                    `Lỗi xử lý OpenCV không mong đợi: ${rawMsg}\n` +
+                    `(Có thể do ảnh corrupt, định dạng không hỗ trợ, hoặc thiết bị thiếu bộ nhớ)`
+                );
+            }
         } finally {
             OpenCV.clearBuffers();
         }