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

package/dist/index.d.ts

@@ -20,6 +20,8 @@ export declare class DocumentScanner {
      * 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

@@ -46,7 +46,17 @@ class DocumentScanner {
         ];
         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;
@@ -85,11 +95,13 @@ class DocumentScanner {
             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);
+            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
@@ -100,75 +112,89 @@ class DocumentScanner {
             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 trên ảnh đã dilate
+            // 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', dilated, 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 = [];
-            const imgArea = targetWidth * targetHeight;
-            // Diện tích tối thiểu 15% (gốc andrewdcampbell dùng 25%, ta dùng 15% linh hoạt hơn)
-            const MIN_AREA_RATIO = 0.15;
+            // 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;
-                if (area > (imgArea * MIN_AREA_RATIO)) {
-                    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);
-            // Thu thập TẤT CẢ candidates hợp lệ, chọn tốt nhất (không dừng sớm)
+            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 maxChecks = Math.min(contourMetrics.length, 5);
-            for (let i = 0; i < maxChecks; i++) {
-                const metric = contourMetrics[i];
+            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;
-                // Vòng lặp epsilon (2%→10%, bước 1%) – tìm tứ giác 4 đỉnh
-                for (let ep = 0.02; ep <= 0.1; ep += 0.01) {
+                // 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);
-                    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)
-                                continue;
-                            const pts = approxJS.array;
-                            const sorted = this.sortCorners([...pts]);
-                            const angleRange = this.getAngleRange(sorted);
-                            // Validate: dải góc nội < 40° (loại hình thoi/bình hành méo)
-                            if (angleRange < 40) {
-                                // Ưu tiên: lớn nhất + vuông nhất
-                                if (metric.area > bestArea || (metric.area === bestArea && angleRange < bestAngleRange)) {
-                                    bestPoly = pts;
-                                    bestArea = metric.area;
-                                    bestAngleRange = angleRange;
-                                }
-                                break; // Đã tìm quad tốt cho contour này, sang contour tiếp
+                    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) { }
                     }
                 }
+                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 7: Trả về góc, phóng trả tỷ lệ kích thước gốc
+            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 = bestPoly.map(p => ({
@@ -177,11 +203,43 @@ class DocumentScanner {
                 }));
                 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.17",
+    "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

@@ -59,6 +59,16 @@ export class DocumentScanner {
         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;
@@ -105,10 +115,12 @@ export class DocumentScanner {
             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);
+            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: Canny (0, 84) – ngưỡng thấp theo andrewdcampbell
@@ -121,85 +133,107 @@ export class DocumentScanner {
             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 trên ảnh đã dilate
+            // 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', dilated, 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 = [];
-            const imgArea = targetWidth * targetHeight;
-            // Diện tích tối thiểu 15% (gốc andrewdcampbell dùng 25%, ta dùng 15% linh hoạt hơn)
-            const MIN_AREA_RATIO = 0.15;
+            // 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;
-                if (area > (imgArea * MIN_AREA_RATIO)) {
-                    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);
+
+            console.log(`[DocDetect] top5 areas: ${top5.map(m => m.area.toFixed(0)).join(', ')} | imgArea=${imgArea.toFixed(0)}`);
 
-            contourMetrics.sort((a, b) => b.area - a.area);
+            // 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;
 
-            // Thu thập TẤT CẢ candidates hợp lệ, chọn tốt nhất (không dừng sớm)
             let bestPoly: Point[] | undefined = undefined;
             let bestArea = 0;
             let bestAngleRange = 999;
+            const debugCandidates: string[] = [];
 
-            const maxChecks = Math.min(contourMetrics.length, 5);
-            for (let i = 0; i < maxChecks; i++) {
-                const metric = contourMetrics[i];
+            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;
+                // 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;
 
-                // Vòng lặp epsilon (2%→10%, bước 1%) – tìm tứ giác 4 đỉnh
-                for (let ep = 0.02; ep <= 0.1; ep += 0.01) {
+                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);
-
-                    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) continue;
-
-                            const pts = approxJS.array as Point[];
-                            const sorted = this.sortCorners([...pts]);
-                            const angleRange = this.getAngleRange(sorted);
-
-                            // Validate: dải góc nội < 40° (loại hình thoi/bình hành méo)
-                            if (angleRange < 40) {
-                                // Ưu tiên: lớn nhất + vuông nhất
-                                if (metric.area > bestArea || (metric.area === bestArea && angleRange < bestAngleRange)) {
-                                    bestPoly = pts;
-                                    bestArea = metric.area;
-                                    bestAngleRange = angleRange;
-                                }
-                                break; // Đã tìm quad tốt cho contour này, sang contour tiếp
+                    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;
+                        }
                     }
                 }
+
+                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 7: Trả về góc, phóng trả tỷ lệ kích thước gốc
+            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 = bestPoly.map(p => ({
@@ -208,10 +242,45 @@ export class DocumentScanner {
                 }));
                 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();
         }