rn-opencv-doc-perspective-correction 1.0.1

package/README.md

@@ -0,0 +1,107 @@
+# rn-opencv-doc-perspective-correction
+
+Thư viện React Native chuyên biệt cho **Page Corner Detection** và **Perspective Correction** — chạy hoàn toàn offline (on-device) thông qua `react-native-fast-opencv` và OpenCV C++ JSI.
+
+## Tính năng
+- **Page Corner Detection:** Tự động nhận diện 4 góc của tờ giấy/tài liệu trong ảnh bất kỳ.
+- **Perspective Correction:** Bóp phẳng ảnh nghiêng dựa trên 4 góc nhận diện, xuất ra ảnh tài liệu chữ nhật hoàn hảo.
+
+## Cài đặt
+
+Thư viện này là wrapper của `react-native-fast-opencv`. Đảm bảo peer dependency đã được cài trong dự án chính.
+
+```bash
+# Cài thư viện (local development)
+npm install react-native-fast-opencv
+npm install file:../rn-opencv-doc-perspective-correction
+```
+
+Hoặc thêm trực tiếp vào `package.json`:
+```json
+{
+  "dependencies": {
+    "rn-opencv-doc-perspective-correction": "file:../rn-opencv-doc-perspective-correction",
+    "react-native-fast-opencv": "^0.4.8"
+  }
+}
+```
+
+## Cách sử dụng
+
+### Luồng hoàn chỉnh (Auto-detect + Warp)
+
+```typescript
+import { DocumentScanner } from 'rn-opencv-doc-perspective-correction';
+import RNFS from 'react-native-fs';
+
+// 1. Đọc ảnh thành Base64
+const imageBase64 = await RNFS.readFile('/path/to/image.jpg', 'base64');
+
+// 2. Auto-detect 4 góc giấy
+const corners = DocumentScanner.detectPageCorners(imageBase64);
+
+if (corners) {
+  console.log('Tìm thấy góc:', corners);
+  // corners = [
+  //   { x: 45,  y: 120 },  // Top-Left
+  //   { x: 940, y: 100 },  // Top-Right
+  //   { x: 960, y: 1280 }, // Bottom-Right
+  //   { x: 30,  y: 1300 }, // Bottom-Left
+  // ]
+
+  // 3. Bóp phẳng ảnh theo 4 góc tìm được (hoặc góc sau khi user chỉnh tay)
+  const scannedBase64 = DocumentScanner.applyPerspectiveCorrection(imageBase64, corners);
+
+  if (scannedBase64) {
+    // 4. Lưu lại file kết quả
+    await RNFS.writeFile('/path/to/scanned.jpg', scannedBase64, 'base64');
+  }
+}
+```
+
+### Kết hợp với UI tuỳ chỉnh (Bán tự động)
+
+```typescript
+import { DocumentScanner, Point } from 'rn-opencv-doc-perspective-correction';
+
+// i. Máy đoán góc trước
+const autoCorners = DocumentScanner.detectPageCorners(imageBase64);
+
+// ii. Hiển thị ảnh + 4 nút draggable tại vị trí autoCorners (ví dụ dùng rn-image-crop-skew)
+//     Người dùng có thể kéo thả để tinh chỉnh
+
+// iii. Sau khi người dùng ấn Done, lấy finalCorners từ UI component
+const finalCorners: Point[] = getFinalCornersFromUI();
+
+// iv. Warp với góc đã tinh chỉnh
+const result = DocumentScanner.applyPerspectiveCorrection(imageBase64, finalCorners);
+```
+
+## Thuật toán OpenCV bên dưới
+
+### Phase 1 — Detect Corners:
+```
+Input Image
+  → cvtColor (BGR2GRAY)
+  → GaussianBlur (5x5 kernel)
+  → Canny Edge Detection (threshold: 75, 200)
+  → findContours (RETR_LIST, CHAIN_APPROX_SIMPLE)
+  → Lọc contour diện tích lớn nhất có đúng 4 đỉnh (approxPolyDP)
+  → Sắp xếp 4 góc theo hướng kim đồng hồ (TL → TR → BR → BL)
+```
+
+### Phase 2 — Perspective Correction:
+```
+[4 góc nguồn] + Input Image
+  → Tính maxWidth & maxHeight bằng khoảng cách Euclidean
+  → Tạo srcPoints (góc nghiêng gốc) và dstPoints (hình chữ nhật phẳng)
+  → getPerspectiveTransform → Ma trận biến dạng
+  → warpPerspective → Ảnh đã phẳng
+  → toBase64 → Output
+```
+
+## Lưu ý quan trọng
+
+- Hàm **`OpenCV.clearBuffers()`** được gọi tự động trong `finally` block của mỗi hàm để giải phóng bộ nhớ C++ JSI, tránh memory leak.
+- Kết quả `detectPageCorners` trả về **`undefined`** nếu không tìm thấy vật thể 4 góc rõ ràng — trong trường hợp đó, bạn nên yêu cầu User chỉnh tay.
+- Nên dùng ảnh **độ phân giải vừa phải** (1000-2000px) để thuật toán hoạt động chính xác nhất. Ảnh quá nhỏ sẽ mất chi tiết viền; ảnh quá lớn sẽ tốn RAM.

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export type Point = {
+    x: number;
+    y: number;
+};
+export declare class DocumentScanner {
+    /**
+     * Tính khoảng cách Euclidean giữa 2 điểm
+     */
+    private static getDistance;
+    /**
+     * Sắp xếp 4 điểm thành chuỗi TL, TR, BR, BL
+     */
+    private static sortCorners;
+    /**
+     * Bước 1: Page Corner Detection (Auto-detect góc tài liệu)
+     */
+    static detectPageCorners(imageBase64: string): Point[] | undefined;
+    /**
+     * Bước 2: Perspective Correction
+     */
+    static applyPerspectiveCorrection(imageBase64: string, corners: Point[]): string | undefined;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentScanner = void 0;
+// @ts-nocheck
+const react_native_fast_opencv_1 = require("react-native-fast-opencv");
+class DocumentScanner {
+    /**
+     * Tính khoảng cách Euclidean giữa 2 điểm
+     */
+    static getDistance(p1, p2) {
+        return Math.sqrt(Math.pow(p1.x - p2.x, 2) + Math.pow(p1.y - p2.y, 2));
+    }
+    /**
+     * Sắp xếp 4 điểm thành chuỗi TL, TR, BR, BL
+     */
+    static sortCorners(corners) {
+        if (corners.length !== 4)
+            return corners;
+        const center = corners.reduce((acc, cur) => ({ x: acc.x + cur.x / 4, y: acc.y + cur.y / 4 }), { x: 0, y: 0 });
+        return corners.sort((a, b) => {
+            const angleA = Math.atan2(a.y - center.y, a.x - center.x);
+            const angleB = Math.atan2(b.y - center.y, b.x - center.x);
+            return angleA - angleB;
+        });
+    }
+    /**
+     * Bước 1: Page Corner Detection (Auto-detect góc tài liệu)
+     */
+    static detectPageCorners(imageBase64) {
+        let src = null;
+        let gray = null;
+        let blurred = null;
+        let edges = null;
+        let contoursObj = null;
+        let hierarchyObj = null;
+        try {
+            src = react_native_fast_opencv_1.OpenCV.invoke('Mat', react_native_fast_opencv_1.OpenCV.base64ToMat(imageBase64));
+            gray = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+            blurred = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+            edges = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+            react_native_fast_opencv_1.OpenCV.invoke('cvtColor', src, gray, 6); // 6 is BGR2GRAY
+            const ksize = react_native_fast_opencv_1.OpenCV.createObject('Size', 5, 5);
+            react_native_fast_opencv_1.OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
+            react_native_fast_opencv_1.OpenCV.invoke('Canny', blurred, edges, 75, 200, 3, false);
+            contoursObj = react_native_fast_opencv_1.OpenCV.createObject('MatVector');
+            hierarchyObj = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+            react_native_fast_opencv_1.OpenCV.invoke('findContours', edges, contoursObj, hierarchyObj, 1, 2);
+            const contoursSize = react_native_fast_opencv_1.OpenCV.invoke('size', contoursObj) || 0;
+            let maxArea = 0;
+            let largestPoly = undefined;
+            for (let i = 0; i < contoursSize; i++) {
+                const contour = react_native_fast_opencv_1.OpenCV.invoke('get', contoursObj, i);
+                const area = react_native_fast_opencv_1.OpenCV.invoke('contourArea', contour);
+                if (area > maxArea) {
+                    const peri = react_native_fast_opencv_1.OpenCV.invoke('arcLength', contour, true);
+                    const approx = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+                    react_native_fast_opencv_1.OpenCV.invoke('approxPolyDP', contour, approx, 0.02 * peri, true);
+                    const vertices = react_native_fast_opencv_1.OpenCV.invoke('rows', approx);
+                    if (vertices === 4) {
+                        maxArea = area;
+                        const points = [];
+                        for (let v = 0; v < 4; v++) {
+                            try {
+                                const pt = react_native_fast_opencv_1.OpenCV.invoke('row', approx, v);
+                                if (pt && typeof pt === 'object' && 'x' in pt)
+                                    points.push(pt);
+                            }
+                            catch (err) { }
+                        }
+                        if (points.length === 4)
+                            largestPoly = points;
+                    }
+                }
+            }
+            if (largestPoly && largestPoly.length === 4) {
+                return this.sortCorners(largestPoly);
+            }
+            return undefined;
+        }
+        catch (e) {
+            console.error('Lỗi khi dò tìm góc tài liệu (OpenCV):', e);
+            return undefined;
+        }
+        finally {
+            react_native_fast_opencv_1.OpenCV.clearBuffers();
+        }
+    }
+    /**
+     * Bước 2: Perspective Correction
+     */
+    static applyPerspectiveCorrection(imageBase64, corners) {
+        let src = null;
+        let dst = null;
+        try {
+            if (!corners || corners.length !== 4)
+                throw new Error("Cần truyền vào đúng 4 điểm góc.");
+            const sortedCorners = this.sortCorners([...corners]);
+            const [tl, tr, br, bl] = sortedCorners;
+            const widthA = this.getDistance(br, bl);
+            const widthB = this.getDistance(tr, tl);
+            const maxWidth = Math.max(Math.round(widthA), Math.round(widthB));
+            const heightA = this.getDistance(tr, br);
+            const heightB = this.getDistance(tl, bl);
+            const maxHeight = Math.max(Math.round(heightA), Math.round(heightB));
+            if (maxWidth === 0 || maxHeight === 0)
+                return undefined;
+            src = react_native_fast_opencv_1.OpenCV.invoke('Mat', react_native_fast_opencv_1.OpenCV.base64ToMat(imageBase64));
+            dst = react_native_fast_opencv_1.OpenCV.invoke('Mat');
+            const srcPoints = react_native_fast_opencv_1.OpenCV.createObject('Point2fVector', tl.x, tl.y, tr.x, tr.y, br.x, br.y, bl.x, bl.y);
+            const dstPoints = react_native_fast_opencv_1.OpenCV.createObject('Point2fVector', 0, 0, maxWidth - 1, 0, maxWidth - 1, maxHeight - 1, 0, maxHeight - 1);
+            const perspectiveMatrix = react_native_fast_opencv_1.OpenCV.invoke('getPerspectiveTransform', srcPoints, dstPoints);
+            const size = react_native_fast_opencv_1.OpenCV.createObject('Size', maxWidth, maxHeight);
+            react_native_fast_opencv_1.OpenCV.invoke('warpPerspective', src, dst, perspectiveMatrix, size);
+            return react_native_fast_opencv_1.OpenCV.invoke('toBase64', dst);
+        }
+        catch (e) {
+            console.error('Lỗi khi bóp phối cảnh tài liệu (OpenCV):', e);
+            return undefined;
+        }
+        finally {
+            react_native_fast_opencv_1.OpenCV.clearBuffers();
+        }
+    }
+}
+exports.DocumentScanner = DocumentScanner;

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "rn-opencv-doc-perspective-correction",
+    "version": "1.0.1",
+    "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",
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist"
+    },
+    "keywords": [
+        "react-native",
+        "opencv",
+        "document-scanner",
+        "perspective-correction"
+    ],
+    "author": "",
+    "license": "MIT",
+    "peerDependencies": {
+        "react": "*",
+        "react-native": "*",
+        "react-native-fast-opencv": "*"
+    },
+    "devDependencies": {
+        "typescript": "^5.0.0"
+    }
+}

package/src/index.ts

@@ -0,0 +1,150 @@
+// @ts-nocheck
+import { OpenCV, OpenCVMat } from 'react-native-fast-opencv';
+
+export type Point = { x: number; y: number };
+
+export class DocumentScanner {
+    /**
+     * Tính khoảng cách Euclidean giữa 2 điểm
+     */
+    private static getDistance(p1: Point, p2: Point) {
+        return Math.sqrt(Math.pow(p1.x - p2.x, 2) + Math.pow(p1.y - p2.y, 2));
+    }
+
+    /**
+     * Sắp xếp 4 điểm thành chuỗi TL, TR, BR, BL
+     */
+    private static sortCorners(corners: Point[]): Point[] {
+        if (corners.length !== 4) return corners;
+
+        const center = corners.reduce(
+            (acc, cur) => ({ x: acc.x + cur.x / 4, y: acc.y + cur.y / 4 }),
+            { x: 0, y: 0 }
+        );
+
+        return corners.sort((a, b) => {
+            const angleA = Math.atan2(a.y - center.y, a.x - center.x);
+            const angleB = Math.atan2(b.y - center.y, b.x - center.x);
+            return angleA - angleB;
+        });
+    }
+
+    /**
+     * Bước 1: Page Corner Detection (Auto-detect góc tài liệu)
+     */
+    public static detectPageCorners(imageBase64: string): Point[] | undefined {
+        let src: OpenCVMat | null = null;
+        let gray: OpenCVMat | null = null;
+        let blurred: OpenCVMat | null = null;
+        let edges: OpenCVMat | null = null;
+        let contoursObj: any = null;
+        let hierarchyObj: any = null;
+
+        try {
+            src = OpenCV.invoke('Mat', OpenCV.base64ToMat(imageBase64));
+            gray = OpenCV.invoke('Mat');
+            blurred = OpenCV.invoke('Mat');
+            edges = OpenCV.invoke('Mat');
+
+            OpenCV.invoke('cvtColor', src, gray, 6); // 6 is BGR2GRAY
+
+            const ksize = OpenCV.createObject('Size', 5, 5);
+            OpenCV.invoke('GaussianBlur', gray, blurred, ksize, 0);
+
+            OpenCV.invoke('Canny', blurred, edges, 75, 200, 3, false);
+
+            contoursObj = OpenCV.createObject('MatVector');
+            hierarchyObj = OpenCV.invoke('Mat');
+
+            OpenCV.invoke('findContours', edges, contoursObj, hierarchyObj, 1, 2);
+
+            const contoursSize = OpenCV.invoke('size', contoursObj) || 0;
+            let maxArea = 0;
+            let largestPoly: Point[] | undefined = undefined;
+
+            for (let i = 0; i < contoursSize; i++) {
+                const contour = OpenCV.invoke('get', contoursObj, i);
+                const area = OpenCV.invoke('contourArea', contour);
+
+                if (area > maxArea) {
+                    const peri = OpenCV.invoke('arcLength', contour, true);
+                    const approx = OpenCV.invoke('Mat');
+                    OpenCV.invoke('approxPolyDP', contour, approx, 0.02 * peri, true);
+
+                    const vertices = OpenCV.invoke('rows', approx);
+                    if (vertices === 4) {
+                        maxArea = area;
+
+                        const points: Point[] = [];
+                        for (let v = 0; v < 4; v++) {
+                            try {
+                                const pt = OpenCV.invoke('row', approx, v);
+                                if (pt && typeof pt === 'object' && 'x' in pt) points.push(pt as Point);
+                            } catch (err) { }
+                        }
+                        if (points.length === 4) largestPoly = points;
+                    }
+                }
+            }
+
+            if (largestPoly && largestPoly.length === 4) {
+                return this.sortCorners(largestPoly);
+            }
+            return undefined;
+        } catch (e) {
+            console.error('Lỗi khi dò tìm góc tài liệu (OpenCV):', e);
+            return undefined;
+        } finally {
+            OpenCV.clearBuffers();
+        }
+    }
+
+    /**
+     * Bước 2: Perspective Correction
+     */
+    public static applyPerspectiveCorrection(imageBase64: string, corners: Point[]): string | undefined {
+        let src: OpenCVMat | null = null;
+        let dst: OpenCVMat | null = null;
+
+        try {
+            if (!corners || corners.length !== 4) throw new Error("Cần truyền vào đúng 4 điểm góc.");
+
+            const sortedCorners = this.sortCorners([...corners]);
+            const [tl, tr, br, bl] = sortedCorners;
+
+            const widthA = this.getDistance(br, bl);
+            const widthB = this.getDistance(tr, tl);
+            const maxWidth = Math.max(Math.round(widthA), Math.round(widthB));
+
+            const heightA = this.getDistance(tr, br);
+            const heightB = this.getDistance(tl, bl);
+            const maxHeight = Math.max(Math.round(heightA), Math.round(heightB));
+
+            if (maxWidth === 0 || maxHeight === 0) return undefined;
+
+            src = OpenCV.invoke('Mat', OpenCV.base64ToMat(imageBase64));
+            dst = OpenCV.invoke('Mat');
+
+            const srcPoints = OpenCV.createObject('Point2fVector', tl.x, tl.y, tr.x, tr.y, br.x, br.y, bl.x, bl.y);
+            const dstPoints = OpenCV.createObject(
+                'Point2fVector',
+                0, 0,
+                maxWidth - 1, 0,
+                maxWidth - 1, maxHeight - 1,
+                0, maxHeight - 1
+            );
+
+            const perspectiveMatrix = OpenCV.invoke('getPerspectiveTransform', srcPoints, dstPoints);
+
+            const size = OpenCV.createObject('Size', maxWidth, maxHeight);
+            OpenCV.invoke('warpPerspective', src, dst, perspectiveMatrix, size);
+
+            return OpenCV.invoke('toBase64', dst);
+        } catch (e) {
+            console.error('Lỗi khi bóp phối cảnh tài liệu (OpenCV):', e);
+            return undefined;
+        } finally {
+            OpenCV.clearBuffers();
+        }
+    }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "compilerOptions": {
+        "target": "es2015",
+        "module": "commonjs",
+        "declaration": true,
+        "outDir": "./dist",
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true
+    },
+    "include": [
+        "src"
+    ]
+}