rn-opencv-doc-perspective-correction 1.0.11 → 1.0.13

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export declare class DocumentScanner {
      *
      * - Nếu corners phát hiện thành công → crop vùng tài liệu và phân tích vùng đó
      * - Nếu không có corners (phát hiện thất bại) → phân tích toàn bộ ảnh
-     * - Dùng không gian màu Lab, đo độ lệch chuẩn kênh a* (xanh↔đỏ) và b* (lam↔vàng)
-     * - stdA + stdB > threshold → nhiều màu sắc → 'G' (ML Kit, phù hợp thẻ, ảnh màu)
-     * - stdA + stdB ≤ threshold → ít màu sắc → 'S' (Tesseract, phù hợp giấy trắng, bản scan)
+     * - Dùng không gian màu HSV, lẩy ra mặt phẳng kênh S (Saturation - Độ bão hòa đỏ/xanh/sáng).
+     * - Cộng trung bình (Mean) và độ lệch chuẩn (Std) của S > threshold → nhiều màu sắc → 'G' (ML Kit, thẻ)
+     * - Thuật toán cũ dùng Lab thất bại do mặt phẳng màu trên nền CCCD không đủ kéo độ lệch lên quá ngưỡng.
      *
      * @param imageBase64 Ảnh gốc base64 JPEG
      * @param corners 4 góc tài liệu đã phát hiện (tuỳ chọn)

package/dist/index.js

@@ -29,40 +29,84 @@ class DocumentScanner {
             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);
             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);
             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);
+            // BƯỚC 1: Chuyển sang ảnh xám (Grayscale)
             react_native_fast_opencv_1.OpenCV.invoke('cvtColor', src, gray, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2GRAY);
+            // BƯỚC 2: Làm mờ để loại bỏ nhiễu hạt nhỏ (Gaussian Blur)
             const ksize = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Size, 5, 5);
             react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
-            // THRESH_BINARY + THRESH_OTSU = 8
-            react_native_fast_opencv_1.OpenCV.invoke('threshold', blurred, edges, 0, 255, 8);
+            // BƯỚC 3: Đo sáng môi trường để thiết lập Canny thông minh (Auto-Canny)
+            // Lợi dụng Otsu Threshold để dò ra "Ngưỡng sáng sinh thái" của bức ảnh đó
+            const dummyEdges = 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 otsuResult = react_native_fast_opencv_1.OpenCV.invoke('threshold', blurred, dummyEdges, 0, 255, 8 /* THRESH_BINARY | THRESH_OTSU */);
+            // Xử lý cẩn thận kiểu dữ liệu trả về từ Bridge (Primitive vs Object)
+            let highThresh = 200;
+            if (otsuResult !== undefined && otsuResult !== null) {
+                highThresh = typeof otsuResult === 'number' ? otsuResult : (otsuResult.value || 200);
+            }
+            let lowThresh = highThresh * 0.5;
+            // BƯỚC 4: Dò tìm cạnh viền Canny với cảm biến tự động
+            react_native_fast_opencv_1.OpenCV.invoke('Canny', blurred, edges, lowThresh, highThresh);
+            // BƯỚC 5: Liền sẹo nét viền (Morphology Dilate)
+            // Giúp nối liền các đứt gãy do bóng đổ chia cắt nét viền
+            const dilatedEdges = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8U);
+            try {
+                const emptyKernel = 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('dilate', edges, dilatedEdges, emptyKernel);
+            }
+            catch (dilateErr) {
+                react_native_fast_opencv_1.OpenCV.invoke('copyTo', edges, dilatedEdges); // Fallback an toàn nếu dilate tàng hình fail
+            }
+            // BƯỚC 6: Tìm khối đa giác liên kết (Contours)
             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, 0 /* RETR_EXTERNAL */, 2 /* CHAIN_APPROX_SIMPLE */);
+            // BẮT BUỘC DÙNG RETR_EXTERNAL để ngăn OOM (Out of Memory):
+            // Canny làm lộ ra TẤT CẢ mép bao gồm cả hàng trăm chữ cái trên CCCD.
+            // Nếu dùng RETR_LIST, JS Bridge sẽ phải vòng lặp cấp phát 5000 Mats gây Crash App ngay lập tức!
+            // RETR_EXTERNAL với Canny sẽ chỉ bắt Vòng khép kín ngoài cùng (Chính xác là mép CCCD).
+            react_native_fast_opencv_1.OpenCV.invoke('findContoursWithHierarchy', dilatedEdges, 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;
             if (contoursSize === 0) {
                 return undefined;
             }
+            // Thu thập và đo đạc diện tích
             let contourMetrics = [];
             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 bé (5000 là khoảng diện tích tối thiểu cho giấy tờ)
                 if (area > 5000) {
                     contourMetrics.push({ index: i, area, contour });
                 }
             }
+            // Sắp xếp diện tích lớn nhất lên đầu (Ưu tiên thẻ bài đang chiếm lớn nhất khung hình)
             contourMetrics.sort((a, b) => b.area - a.area);
             let largestPoly = undefined;
-            for (let i = 0; i < contourMetrics.length; i++) {
+            // BƯỚC 7: Thẩm định hình học
+            // Quét qua max 5 contour lớn nhất để tiết kiệm thao tác mảng
+            const maxChecks = Math.min(contourMetrics.length, 5);
+            for (let i = 0; i < maxChecks; i++) {
                 const metric = contourMetrics[i];
                 const contour = metric.contour;
                 const periObj = react_native_fast_opencv_1.OpenCV.invoke('arcLength', contour, true);
-                const peri = periObj ? periObj.value : 0;
+                const peri = periObj ? (periObj.value || 0) : 0;
                 const approx = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.PointVector);
+                // Tính nội suy đa giác (Epsilon = 2% của chu vi)
                 react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contour, approx, 0.02 * peri, true);
                 const approxJS = react_native_fast_opencv_1.OpenCV.toJSValue(approx);
+                // Nếu quy chiếu thành công ra đúng 4 góc
                 if (approxJS && approxJS.array && approxJS.array.length === 4) {
+                    // Thẩm định: Phải là đa giác lồi Convex (Loại bóng râm)
+                    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;
+                        }
+                    }
+                    catch (convexErr) { }
                     largestPoly = approxJS.array;
                     break;
                 }
@@ -73,7 +117,7 @@ class DocumentScanner {
             return undefined;
         }
         catch (e) {
-            console.error('Lỗi khi dò tìm góc tài liệu (OpenCV):', 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}`);
         }
         finally {
@@ -162,19 +206,19 @@ class DocumentScanner {
      *
      * - Nếu corners phát hiện thành công → crop vùng tài liệu và phân tích vùng đó
      * - Nếu không có corners (phát hiện thất bại) → phân tích toàn bộ ảnh
-     * - Dùng không gian màu Lab, đo độ lệch chuẩn kênh a* (xanh↔đỏ) và b* (lam↔vàng)
-     * - stdA + stdB > threshold → nhiều màu sắc → 'G' (ML Kit, phù hợp thẻ, ảnh màu)
-     * - stdA + stdB ≤ threshold → ít màu sắc → 'S' (Tesseract, phù hợp giấy trắng, bản scan)
+     * - Dùng không gian màu HSV, lẩy ra mặt phẳng kênh S (Saturation - Độ bão hòa đỏ/xanh/sáng).
+     * - Cộng trung bình (Mean) và độ lệch chuẩn (Std) của S > threshold → nhiều màu sắc → 'G' (ML Kit, thẻ)
+     * - Thuật toán cũ dùng Lab thất bại do mặt phẳng màu trên nền CCCD không đủ kéo độ lệch lên quá ngưỡng.
      *
      * @param imageBase64 Ảnh gốc base64 JPEG
      * @param corners 4 góc tài liệu đã phát hiện (tuỳ chọn)
      * @param colorThreshold Ngưỡng phân biệt (mặc định 18.0, điều chỉnh nếu cần tinh chỉnh)
      */
     static analyzeColorComplexity(imageBase64, corners, colorThreshold = 18.0) {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b;
         let src = null;
         let roi = null;
-        let lab = null;
+        let hsv = null;
         let color3Channel = null;
         try {
             src = react_native_fast_opencv_1.OpenCV.base64ToMat(imageBase64);
@@ -227,43 +271,71 @@ class DocumentScanner {
             else {
                 color3Channel = target; // Đã là 3 kênh
             }
-            // Chuyển sang Lab (L=sáng/tối, a*=màu xanh↔đỏ, b*=màu lam↔vàng)
-            lab = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8UC3);
-            react_native_fast_opencv_1.OpenCV.invoke('cvtColor', color3Channel, lab, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2Lab);
+            // Phương án 2.3: Chuyển sang Không gian màu HSV (Hue, Saturation, Value)
+            hsv = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_8UC3);
+            react_native_fast_opencv_1.OpenCV.invoke('cvtColor', color3Channel, hsv, react_native_fast_opencv_1.ColorConversionCodes.COLOR_BGR2HSV);
             // Đo mean và stddev từng kênh
             const meanMat = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_64F);
             const stdMat = react_native_fast_opencv_1.OpenCV.createObject(react_native_fast_opencv_1.ObjectType.Mat, 0, 0, react_native_fast_opencv_1.DataTypes.CV_64F);
-            react_native_fast_opencv_1.OpenCV.invoke('meanStdDev', lab, meanMat, stdMat);
-            // Trích xuất stdDev một cách an toàn
-            const stdJS = react_native_fast_opencv_1.OpenCV.toJSValue(stdMat);
-            // react-native-fast-opencv thường chuyển `Mat` thành object JS có cấu trúc mảng 1 chiều trong prop `array` hoặc `data`
-            // hoặc trả về dưới dạng mảng lồng nhau
-            let stdA = 0;
-            let stdB = 0;
-            if (stdJS) {
-                if (Array.isArray(stdJS)) {
-                    // Nếu nó đã là array
-                    stdA = Array.isArray(stdJS[1]) ? stdJS[1][0] : (_a = stdJS[1]) !== null && _a !== void 0 ? _a : 0;
-                    stdB = Array.isArray(stdJS[2]) ? stdJS[2][0] : (_b = stdJS[2]) !== null && _b !== void 0 ? _b : 0;
-                }
-                else if (stdJS.array && Array.isArray(stdJS.array)) {
-                    stdA = (_c = stdJS.array[1]) !== null && _c !== void 0 ? _c : 0;
-                    stdB = (_d = stdJS.array[2]) !== null && _d !== void 0 ? _d : 0;
-                }
-                else if (stdJS.data && Array.isArray(stdJS.data)) {
-                    // Có một số version có định dạng `data`
-                    stdA = (_e = stdJS.data[1]) !== null && _e !== void 0 ? _e : 0;
-                    stdB = (_f = stdJS.data[2]) !== null && _f !== void 0 ? _f : 0;
+            react_native_fast_opencv_1.OpenCV.invoke('meanStdDev', hsv, meanMat, stdMat);
+            // Phương án 2.1: Hàm trích xuất mảng JS an toàn (tránh lỗi bridge trả về 0)
+            const extractValues = (jsObj) => {
+                if (!jsObj)
+                    return [0, 0, 0];
+                // JSI/C++ bridge có thể trả về TypedArray thay vì JS Array thuần
+                const isList = (obj) => Array.isArray(obj) || (obj && obj.buffer instanceof ArrayBuffer) || ArrayBuffer.isView(obj);
+                const parseList = (list) => {
+                    const result = [];
+                    // Đảm bảo lấy ít nhất 3 tham số (Hue, Saturation, Value)
+                    const len = Math.max(list.length || 0, 3);
+                    for (let i = 0; i < len; i++) {
+                        let item = list[i];
+                        if (Array.isArray(item))
+                            item = item[0];
+                        else if (item && typeof item === 'object' && 'value' in item)
+                            item = item.value;
+                        const num = Number(item);
+                        result.push(isNaN(num) ? 0 : num);
+                    }
+                    return result;
+                };
+                if (isList(jsObj))
+                    return parseList(jsObj);
+                if (jsObj.array && isList(jsObj.array))
+                    return parseList(jsObj.array);
+                if (jsObj.data && isList(jsObj.data))
+                    return parseList(jsObj.data);
+                if (jsObj.value && isList(jsObj.value))
+                    return parseList(jsObj.value);
+                // Fallback cho object có dạng Dictionary Object Array-like (vd: {'0': 15, '1': 30})
+                if (typeof jsObj === 'object') {
+                    if (jsObj[0] !== undefined || jsObj[1] !== undefined) {
+                        return parseList(jsObj);
+                    }
+                    // Quét các key để xem có chứa Array không
+                    const possibleArrayKey = Object.keys(jsObj).find(k => isList(jsObj[k]));
+                    if (possibleArrayKey)
+                        return parseList(jsObj[possibleArrayKey]);
                 }
-            }
-            const colorScore = stdA + stdB;
-            console.log(`[OCR Auto] colorScore=${colorScore.toFixed(2)} threshold=${colorThreshold} => ${colorScore > colorThreshold ? 'G (ML Kit)' : 'S (Tesseract)'}`);
-            return colorScore > colorThreshold ? 'G' : 'S';
+                console.warn('[OCR Auto HSV] extractValues không thể parse object:', JSON.stringify(jsObj));
+                return [0, 0, 0];
+            };
+            const meanArr = extractValues(react_native_fast_opencv_1.OpenCV.toJSValue(meanMat));
+            const stdArr = extractValues(react_native_fast_opencv_1.OpenCV.toJSValue(stdMat));
+            // Kênh S (Saturation) nằm ở index 1, biểu thị độ bão hòa (đậm nhạt) của màu sắc
+            const meanS = (_a = meanArr[1]) !== null && _a !== void 0 ? _a : 0;
+            const stdS = (_b = stdArr[1]) !== null && _b !== void 0 ? _b : 0;
+            // Ảnh đen trắng (Scan/Document) sẽ có Mean và Std của Saturation tiến sát về 0.
+            // CCCD hoặc thẻ màu (Ảnh ID) sẽ có các vùng màu (tóc, da, mộc đỏ) kéo Std và Mean lên cao. 
+            const colorScore = meanS + stdS;
+            // Phương án 2.2: Hạ mức Threshold phân định (CCCD Việt Nam có nền xanh/vàng lợt nên dễ bị điểm thấp nếu dùng 18.0)
+            const resolvedThreshold = colorThreshold === 18.0 ? 10.0 : colorThreshold;
+            console.log(`[OCR Auto HSV] Mean(S)=${meanS.toFixed(2)}, Std(S)=${stdS.toFixed(2)}, colorScore=${colorScore.toFixed(2)}, threshold=${resolvedThreshold} => ${colorScore > resolvedThreshold ? 'G (ML Kit)' : 'S (Tesseract)'}`);
+            return colorScore > resolvedThreshold ? 'G' : 'S';
         }
         catch (e) {
-            console.warn('[OpenCV] analyzeColorComplexity lỗi, fallback S:', e === null || e === void 0 ? void 0 : e.message);
-            // Ảnh ít màu thường dễ gây lỗi khi phân tích hơn nên ta Fallback về S
-            return 'S';
+            console.error('[OpenCV] analyzeColorComplexity lỗi:', e === null || e === void 0 ? void 0 : e.message);
+            throw new Error(`[OpenCV analyzeColorComplexity Error]: ${e === null || e === void 0 ? void 0 : e.message}`);
         }
         finally {
             react_native_fast_opencv_1.OpenCV.clearBuffers();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rn-opencv-doc-perspective-correction",
-    "version": "1.0.11",
+    "version": "1.0.13",
     "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

@@ -44,18 +44,47 @@ export class DocumentScanner {
             blurred = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
             edges = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
 
+            // BƯỚC 1: Chuyển sang ảnh xám (Grayscale)
             OpenCV.invoke('cvtColor', src, gray, ColorConversionCodes.COLOR_BGR2GRAY);
 
+            // BƯỚC 2: Làm mờ để loại bỏ nhiễu hạt nhỏ (Gaussian Blur)
             const ksize = OpenCV.createObject(ObjectType.Size, 5, 5);
             OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
 
-            // THRESH_BINARY + THRESH_OTSU = 8
-            OpenCV.invoke('threshold', blurred, edges, 0, 255, 8);
+            // BƯỚC 3: Đo sáng môi trường để thiết lập Canny thông minh (Auto-Canny)
+            // Lợi dụng Otsu Threshold để dò ra "Ngưỡng sáng sinh thái" của bức ảnh đó
+            const dummyEdges = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
+            const otsuResult = OpenCV.invoke('threshold', blurred, dummyEdges, 0, 255, 8 /* THRESH_BINARY | THRESH_OTSU */);
+            
+            // Xử lý cẩn thận kiểu dữ liệu trả về từ Bridge (Primitive vs Object)
+            let highThresh = 200;
+            if (otsuResult !== undefined && otsuResult !== null) {
+                highThresh = typeof otsuResult === 'number' ? otsuResult : (otsuResult.value || 200);
+            }
+            let lowThresh = highThresh * 0.5;
+
+            // BƯỚC 4: Dò tìm cạnh viền Canny với cảm biến tự động
+            OpenCV.invoke('Canny', blurred, edges, lowThresh, highThresh);
+
+            // BƯỚC 5: Liền sẹo nét viền (Morphology Dilate)
+            // Giúp nối liền các đứt gãy do bóng đổ chia cắt nét viền
+            const dilatedEdges = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
+            try {
+                const emptyKernel = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
+                OpenCV.invoke('dilate', edges, dilatedEdges, emptyKernel);
+            } catch (dilateErr) {
+                OpenCV.invoke('copyTo', edges, dilatedEdges); // Fallback an toàn nếu dilate tàng hình fail
+            }
 
+            // BƯỚC 6: Tìm khối đa giác liên kết (Contours)
             contoursObj = OpenCV.createObject(ObjectType.MatVector);
             hierarchyObj = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8U);
 
-            OpenCV.invoke('findContoursWithHierarchy', edges, contoursObj, hierarchyObj, 0 /* RETR_EXTERNAL */, 2 /* CHAIN_APPROX_SIMPLE */);
+            // BẮT BUỘC DÙNG RETR_EXTERNAL để ngăn OOM (Out of Memory):
+            // Canny làm lộ ra TẤT CẢ mép bao gồm cả hàng trăm chữ cái trên CCCD.
+            // Nếu dùng RETR_LIST, JS Bridge sẽ phải vòng lặp cấp phát 5000 Mats gây Crash App ngay lập tức!
+            // RETR_EXTERNAL với Canny sẽ chỉ bắt Vòng khép kín ngoài cùng (Chính xác là mép CCCD).
+            OpenCV.invoke('findContoursWithHierarchy', dilatedEdges, contoursObj, hierarchyObj, 0 /* RETR_EXTERNAL */, 2 /* CHAIN_APPROX_SIMPLE */);
 
             const contoursJS = OpenCV.toJSValue(contoursObj);
             const contoursArray = contoursJS?.array || [];
@@ -65,42 +94,63 @@ export class DocumentScanner {
                 return undefined;
             }
 
+            // Thu thập và đo đạc diện tích
             let contourMetrics = [];
             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 bé (5000 là khoảng diện tích tối thiểu cho giấy tờ)
                 if (area > 5000) {
                     contourMetrics.push({ index: i, area, contour });
                 }
             }
 
+            // Sắp xếp diện tích lớn nhất lên đầu (Ưu tiên thẻ bài đang chiếm lớn nhất khung hình)
             contourMetrics.sort((a, b) => b.area - a.area);
 
             let largestPoly: Point[] | undefined = undefined;
 
-            for (let i = 0; i < contourMetrics.length; i++) {
-                const metric = contourMetrics[i];
-                const contour = metric.contour;
-
-                const periObj = OpenCV.invoke('arcLength', contour, true);
-                const peri = periObj ? periObj.value : 0;
-                const approx = OpenCV.createObject(ObjectType.PointVector);
-                OpenCV.invoke('approxPolyDP', contour, approx, 0.02 * peri, true);
-
-                const approxJS = OpenCV.toJSValue(approx);
-                if (approxJS && approxJS.array && approxJS.array.length === 4) {
-                    largestPoly = approxJS.array as Point[];
-                    break;
+                // BƯỚC 7: Thẩm định hình học
+                // Quét qua max 5 contour lớn nhất để tiết kiệm thao tác mảng
+                const maxChecks = Math.min(contourMetrics.length, 5);
+                for (let i = 0; i < maxChecks; i++) {
+                    const metric = contourMetrics[i];
+                    const contour = metric.contour;
+    
+                    const periObj = OpenCV.invoke('arcLength', contour, true);
+                    const peri = periObj ? (periObj.value || 0) : 0;
+                    const approx = OpenCV.createObject(ObjectType.PointVector);
+                    
+                    // Tính nội suy đa giác (Epsilon = 2% của chu vi)
+                    OpenCV.invoke('approxPolyDP', contour, approx, 0.02 * peri, true);
+    
+                    const approxJS = OpenCV.toJSValue(approx);
+                    
+                    // Nếu quy chiếu thành công ra đúng 4 góc
+                    if (approxJS && approxJS.array && approxJS.array.length === 4) {
+                        
+                        // Thẩm định: Phải là đa giác lồi Convex (Loại bóng râm)
+                        try {
+                            const isConvex = OpenCV.invoke('isContourConvex', approx);
+                            const convexValue = (typeof isConvex === 'object' && isConvex !== null) ? isConvex.value : isConvex;
+                            if (convexValue === false) {
+                                continue; 
+                            }
+                        } catch (convexErr) {}
+    
+                        largestPoly = approxJS.array as Point[];
+                        break;
+                    }
                 }
-            }
 
             if (largestPoly && largestPoly.length === 4) {
                 return this.sortCorners(largestPoly);
             }
             return undefined;
         } catch (e: any) {
-            console.error('Lỗi khi dò tìm góc tài liệu (OpenCV):', 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}`);
         } finally {
             OpenCV.clearBuffers();
@@ -202,9 +252,9 @@ export class DocumentScanner {
      *
      * - Nếu corners phát hiện thành công → crop vùng tài liệu và phân tích vùng đó
      * - Nếu không có corners (phát hiện thất bại) → phân tích toàn bộ ảnh
-     * - Dùng không gian màu Lab, đo độ lệch chuẩn kênh a* (xanh↔đỏ) và b* (lam↔vàng)
-     * - stdA + stdB > threshold → nhiều màu sắc → 'G' (ML Kit, phù hợp thẻ, ảnh màu)
-     * - stdA + stdB ≤ threshold → ít màu sắc → 'S' (Tesseract, phù hợp giấy trắng, bản scan)
+     * - Dùng không gian màu HSV, lẩy ra mặt phẳng kênh S (Saturation - Độ bão hòa đỏ/xanh/sáng).
+     * - Cộng trung bình (Mean) và độ lệch chuẩn (Std) của S > threshold → nhiều màu sắc → 'G' (ML Kit, thẻ)
+     * - Thuật toán cũ dùng Lab thất bại do mặt phẳng màu trên nền CCCD không đủ kéo độ lệch lên quá ngưỡng.
      *
      * @param imageBase64 Ảnh gốc base64 JPEG
      * @param corners 4 góc tài liệu đã phát hiện (tuỳ chọn)
@@ -217,7 +267,7 @@ export class DocumentScanner {
     ): OcrMethodHint {
         let src: OpenCVMat | null = null;
         let roi: OpenCVMat | null = null;
-        let lab: OpenCVMat | null = null;
+        let hsv: OpenCVMat | null = null;
         let color3Channel: OpenCVMat | null = null;
 
         try {
@@ -273,45 +323,77 @@ export class DocumentScanner {
                 color3Channel = target; // Đã là 3 kênh
             }
 
-            // Chuyển sang Lab (L=sáng/tối, a*=màu xanh↔đỏ, b*=màu lam↔vàng)
-            lab = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8UC3);
-            OpenCV.invoke('cvtColor', color3Channel, lab, ColorConversionCodes.COLOR_BGR2Lab);
+            // Phương án 2.3: Chuyển sang Không gian màu HSV (Hue, Saturation, Value)
+            hsv = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_8UC3);
+            OpenCV.invoke('cvtColor', color3Channel, hsv, ColorConversionCodes.COLOR_BGR2HSV);
 
             // Đo mean và stddev từng kênh
             const meanMat = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_64F);
             const stdMat = OpenCV.createObject(ObjectType.Mat, 0, 0, DataTypes.CV_64F);
-            OpenCV.invoke('meanStdDev', lab, meanMat, stdMat);
-
-            // Trích xuất stdDev một cách an toàn
-            const stdJS = OpenCV.toJSValue(stdMat);
-            // react-native-fast-opencv thường chuyển `Mat` thành object JS có cấu trúc mảng 1 chiều trong prop `array` hoặc `data`
-            // hoặc trả về dưới dạng mảng lồng nhau
-            let stdA = 0;
-            let stdB = 0;
-            
-            if (stdJS) {
-                if (Array.isArray(stdJS)) {
-                    // Nếu nó đã là array
-                    stdA = Array.isArray(stdJS[1]) ? stdJS[1][0] : stdJS[1] ?? 0;
-                    stdB = Array.isArray(stdJS[2]) ? stdJS[2][0] : stdJS[2] ?? 0;
-                } else if (stdJS.array && Array.isArray(stdJS.array)) {
-                    stdA = stdJS.array[1] ?? 0;
-                    stdB = stdJS.array[2] ?? 0;
-                } else if (stdJS.data && Array.isArray(stdJS.data)) {
-                    // Có một số version có định dạng `data`
-                    stdA = stdJS.data[1] ?? 0;
-                    stdB = stdJS.data[2] ?? 0;
+            OpenCV.invoke('meanStdDev', hsv, meanMat, stdMat);
+
+            // Phương án 2.1: Hàm trích xuất mảng JS an toàn (tránh lỗi bridge trả về 0)
+            const extractValues = (jsObj: any): number[] => {
+                if (!jsObj) return [0, 0, 0];
+                
+                // JSI/C++ bridge có thể trả về TypedArray thay vì JS Array thuần
+                const isList = (obj: any): boolean => 
+                    Array.isArray(obj) || (obj && obj.buffer instanceof ArrayBuffer) || ArrayBuffer.isView(obj);
+
+                const parseList = (list: any): number[] => {
+                    const result: number[] = [];
+                    // Đảm bảo lấy ít nhất 3 tham số (Hue, Saturation, Value)
+                    const len = Math.max(list.length || 0, 3);
+                    for (let i = 0; i < len; i++) {
+                        let item = list[i];
+                        if (Array.isArray(item)) item = item[0];
+                        else if (item && typeof item === 'object' && 'value' in item) item = item.value;
+                        
+                        const num = Number(item);
+                        result.push(isNaN(num) ? 0 : num);
+                    }
+                    return result;
+                };
+
+                if (isList(jsObj)) return parseList(jsObj);
+                if (jsObj.array && isList(jsObj.array)) return parseList(jsObj.array);
+                if (jsObj.data && isList(jsObj.data)) return parseList(jsObj.data);
+                if (jsObj.value && isList(jsObj.value)) return parseList(jsObj.value);
+                
+                // Fallback cho object có dạng Dictionary Object Array-like (vd: {'0': 15, '1': 30})
+                if (typeof jsObj === 'object') {
+                    if (jsObj[0] !== undefined || jsObj[1] !== undefined) {
+                        return parseList(jsObj);
+                    }
+                    // Quét các key để xem có chứa Array không
+                    const possibleArrayKey = Object.keys(jsObj).find(k => isList(jsObj[k]));
+                    if (possibleArrayKey) return parseList(jsObj[possibleArrayKey]);
                 }
-            }
 
-            const colorScore = stdA + stdB;
-            console.log(`[OCR Auto] colorScore=${colorScore.toFixed(2)} threshold=${colorThreshold} => ${colorScore > colorThreshold ? 'G (ML Kit)' : 'S (Tesseract)'}`);
+                console.warn('[OCR Auto HSV] extractValues không thể parse object:', JSON.stringify(jsObj));
+                return [0, 0, 0];
+            };
+
+            const meanArr = extractValues(OpenCV.toJSValue(meanMat));
+            const stdArr = extractValues(OpenCV.toJSValue(stdMat));
+
+            // Kênh S (Saturation) nằm ở index 1, biểu thị độ bão hòa (đậm nhạt) của màu sắc
+            const meanS = meanArr[1] ?? 0;
+            const stdS = stdArr[1] ?? 0;
+            
+            // Ảnh đen trắng (Scan/Document) sẽ có Mean và Std của Saturation tiến sát về 0.
+            // CCCD hoặc thẻ màu (Ảnh ID) sẽ có các vùng màu (tóc, da, mộc đỏ) kéo Std và Mean lên cao. 
+            const colorScore = meanS + stdS;
+            
+            // Phương án 2.2: Hạ mức Threshold phân định (CCCD Việt Nam có nền xanh/vàng lợt nên dễ bị điểm thấp nếu dùng 18.0)
+            const resolvedThreshold = colorThreshold === 18.0 ? 10.0 : colorThreshold;
+
+            console.log(`[OCR Auto HSV] Mean(S)=${meanS.toFixed(2)}, Std(S)=${stdS.toFixed(2)}, colorScore=${colorScore.toFixed(2)}, threshold=${resolvedThreshold} => ${colorScore > resolvedThreshold ? 'G (ML Kit)' : 'S (Tesseract)'}`);
 
-            return colorScore > colorThreshold ? 'G' : 'S';
+            return colorScore > resolvedThreshold ? 'G' : 'S';
         } catch (e: any) {
-            console.warn('[OpenCV] analyzeColorComplexity lỗi, fallback S:', e?.message);
-            // Ảnh ít màu thường dễ gây lỗi khi phân tích hơn nên ta Fallback về S
-            return 'S';
+            console.error('[OpenCV] analyzeColorComplexity lỗi:', e?.message);
+            throw new Error(`[OpenCV analyzeColorComplexity Error]: ${e?.message}`);
         } finally {
             OpenCV.clearBuffers();
         }