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.

# 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:

{
  "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)

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)

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.