@hoshomoh/react-native-document-scanner 1.2.0

package/ios/DocumentScannerManager.swift

@@ -0,0 +1,148 @@
+import Foundation
+import VisionKit
+import React
+
+/**
+ The core native implementation of the Document Scanner.
+
+ This class handles:
+ 1. Interfacing with `VNDocumentCameraViewController`.
+ 2. Managing the scanning session lifecycle.
+ 3. Delegating processing to `ImageProcessor`.
+ */
+@objc(DocumentScannerManager)
+@available(iOS 13.0, *)
+public class DocumentScannerManager: NSObject, VNDocumentCameraViewControllerDelegate {
+
+  private var resolve: RCTPromiseResolveBlock?
+  private var reject: RCTPromiseRejectBlock?
+  private var scanOptions: [String: Any]?
+
+  /* ----------------------------------------------------------------------- */
+  /* Scan Operations                                                         */
+  /* ----------------------------------------------------------------------- */
+
+  @objc
+  public func scanDocuments(_ options: NSDictionary?, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    self.resolve = resolve
+    self.reject = reject
+    self.scanOptions = options as? [String: Any]
+
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      guard VNDocumentCameraViewController.isSupported else {
+        self.rejectError(.notSupported)
+        return
+      }
+
+      let scannerViewController = VNDocumentCameraViewController()
+      scannerViewController.delegate = self
+      scannerViewController.modalPresentationStyle = .fullScreen
+
+      if let topController = self.getTopMostViewController() {
+        topController.present(scannerViewController, animated: true, completion: nil)
+      } else {
+        self.rejectError(.operationFailed("Could not find top view controller."))
+      }
+    }
+  }
+
+  /* ----------------------------------------------------------------------- */
+  /* Process Operations                                                      */
+  /* ----------------------------------------------------------------------- */
+  @objc
+  public func processDocuments(_ options: NSDictionary, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    self.resolve = resolve
+    self.reject = reject
+
+    Task(priority: .userInitiated) { [weak self] in
+      guard let self = self else { return }
+
+      guard let opts = ProcessOptions(from: options as? [String: Any]) else {
+        self.rejectError(.configurationError("Missing 'images' array in options"))
+        return
+      }
+
+      /* Load images from sources */
+      let images = opts.images.compactMap { ImageUtil.loadImage(from: $0) }
+
+      if images.isEmpty {
+        self.rejectError(.configurationError("Could not load any valid images"))
+        return
+      }
+
+      /* Process all images — async, never blocks the UI thread */
+      let results = await ImageProcessor.processAll(images, options: opts)
+
+      self.resolve?(results.map { $0.dictionary })
+      self.cleanup()
+    }
+  }
+
+  /* ----------------------------------------------------------------------- */
+  /* VNDocumentCameraViewControllerDelegate                                  */
+  /* ----------------------------------------------------------------------- */
+
+  public func documentCameraViewController(_ controller: VNDocumentCameraViewController, didFinishWith scan: VNDocumentCameraScan) {
+    controller.dismiss(animated: true) { [weak self] in
+      self?.processScan(scan)
+    }
+  }
+
+  public func documentCameraViewControllerDidCancel(_ controller: VNDocumentCameraViewController) {
+    controller.dismiss(animated: true) { [weak self] in
+      self?.rejectError(.canceled)
+    }
+  }
+
+  public func documentCameraViewController(_ controller: VNDocumentCameraViewController, didFailWithError error: Error) {
+    controller.dismiss(animated: true) { [weak self] in
+      self?.rejectError(.operationFailed(error.localizedDescription))
+    }
+  }
+
+  /* ----------------------------------------------------------------------- */
+  /* Private Helpers                                                         */
+  /* ----------------------------------------------------------------------- */
+
+  private func processScan(_ scan: VNDocumentCameraScan) {
+    Task(priority: .userInitiated) { [weak self] in
+      guard let self = self else { return }
+
+      let opts = ScanOptions(from: self.scanOptions, fallbackPageCount: scan.pageCount)
+      let pageLimit = opts.maxPageCount == 0 ? scan.pageCount : min(scan.pageCount, opts.maxPageCount)
+
+      /* Collect images from scan */
+      var images: [UIImage] = []
+      for i in 0..<pageLimit {
+        images.append(scan.imageOfPage(at: i))
+      }
+
+      /* Process all images — async, never blocks the UI thread */
+      let results = await ImageProcessor.processAll(images, options: opts)
+
+      self.resolve?(results.map { $0.dictionary })
+      self.cleanup()
+    }
+  }
+
+  private func getTopMostViewController() -> UIViewController? {
+    if #available(iOS 13.0, *) {
+        return UIApplication.shared.windows.first { $0.isKeyWindow }?.rootViewController
+    } else {
+        return UIApplication.shared.keyWindow?.rootViewController
+    }
+  }
+
+  private func rejectError(_ error: ScannerError) {
+      self.reject?("error", error.localizedDescription, error)
+      self.cleanup()
+  }
+
+  private func cleanup() {
+    self.resolve = nil
+    self.reject = nil
+    self.scanOptions = nil
+  }
+}

package/ios/Errors.swift

@@ -0,0 +1,33 @@
+import Foundation
+
+/**
+ * Custom error types for the Document Scanner.
+ * Used for communicating structured failure states back to the React Native bridge.
+ */
+enum ScannerError: Error {
+    /// Device hardware or OS version is unsupported.
+    case notSupported
+    /// Invalid configuration or missing options.
+    case configurationError(String)
+    /// A runtime failure occurred during processing.
+    case operationFailed(String)
+    /// The user cancelled the scanning process.
+    case canceled
+}
+
+extension ScannerError: LocalizedError {
+    var errorDescription: String? {
+        switch self {
+        case .notSupported:
+            return "Device does not support document scanning."
+        case .configurationError(let msg):
+            return "Configuration Error: \(msg)"
+        case .operationFailed(let msg):
+            return "Operation Failed: \(msg)"
+        case .canceled:
+            return "User canceled the scan."
+        }
+    }
+}
+
+

package/ios/ImageProcessor.swift

@@ -0,0 +1,78 @@
+import Foundation
+import UIKit
+
+/**
+ Centralized image processing pipeline.
+ Shared by scanDocuments and processDocuments to avoid code duplication.
+ */
+public class ImageProcessor {
+
+    /**
+     Processes a single image through the full pipeline.
+     - Parameters:
+       - image: The UIImage to process.
+       - options: Processing configuration (BaseOptions).
+     - Returns: A ScanResult containing the processed data.
+     */
+    public static func process(_ image: UIImage, options: BaseOptions) async -> ScanResult {
+        /* 1. Apply Filter */
+        let filteredImage = ImageUtil.applyFilter(image, filterType: options.filter) ?? image
+
+        /* 2. Save to File */
+        var uri: String?
+        do {
+            uri = try ImageUtil.saveImage(filteredImage, quality: options.quality, format: options.format)
+        } catch {
+            Logger.error("Error saving image: \(error.localizedDescription)")
+        }
+
+        /* 3. Generate Base64 (if requested) */
+        var base64: String?
+        if options.includeBase64 {
+            base64 = ImageUtil.base64(from: filteredImage, format: options.format, quality: options.quality)
+        }
+
+        /* 4. Perform OCR (if requested) — awaited to keep heavy work off the UI thread */
+        var text: String?
+        var blocks: [TextBlock]?
+        if options.includeText {
+            if let ocrResult = await TextRecognizer.recognizeText(from: filteredImage, version: options.textVersion) {
+                text = ocrResult.text
+                blocks = ocrResult.blocks
+            }
+        }
+
+        /* 5. Build Metadata */
+        let ocrEngine = options.includeText ? TextRecognizer.engineName(for: options.textVersion) : "none"
+        let metadata = ScanMetadata(
+            platform: "ios",
+            textVersion: options.textVersion,
+            filter: options.filter,
+            ocrEngine: ocrEngine
+        )
+
+        /* 6. Build Result */
+        return ResponseUtil.buildResult(
+            uri: uri,
+            base64: base64,
+            text: text,
+            blocks: blocks,
+            metadata: metadata
+        )
+    }
+
+    /**
+     Processes an array of images sequentially.
+     - Parameters:
+       - images: Array of UIImage objects.
+       - options: Processing configuration.
+     - Returns: Array of ScanResult.
+     */
+    public static func processAll(_ images: [UIImage], options: BaseOptions) async -> [ScanResult] {
+        var results: [ScanResult] = []
+        for image in images {
+            results.append(await process(image, options: options))
+        }
+        return results
+    }
+}

package/ios/ImageUtil.swift

@@ -0,0 +1,279 @@
+import Foundation
+import UIKit
+import CoreImage
+
+/**
+ Utility class for image operations.
+ Handles filtering, encoding, and file system operations.
+ */
+public class ImageUtil {
+    
+    /* ----------------------------------------------------------------------- */
+    /* Loading                                                                 */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Loads a UIImage from a source string.
+     - Parameter source: Can be a file URI, data URI, or raw base64 string.
+     - Returns: The loaded UIImage, or nil if loading fails.
+     */
+    public static func loadImage(from source: String) -> UIImage? {
+        /* File URL (file:// or absolute path) */
+        if source.hasPrefix("file://") || source.hasPrefix("/") {
+            let path = source.hasPrefix("file://") ? String(source.dropFirst(7)) : source
+            return UIImage(contentsOfFile: path)
+        }
+        
+        /* Data URI (e.g., data:image/png;base64,...) */
+        if source.hasPrefix("data:") {
+            if let commaIndex = source.firstIndex(of: ",") {
+                let base64String = String(source[source.index(after: commaIndex)...])
+                if let data = Data(base64Encoded: base64String) {
+                    return UIImage(data: data)
+                }
+            }
+            return nil
+        }
+        
+        /* Raw base64 string */
+        if let data = Data(base64Encoded: source) {
+            return UIImage(data: data)
+        }
+        
+        Logger.warn("Could not load image from source: \(source.prefix(50))...")
+        return nil
+    }
+    
+    /* ----------------------------------------------------------------------- */
+    /* Filtering                                                               */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Applies a CoreImage filter to the image.
+     - Parameters:
+       - image: The input UIImage.
+       - filterType: The filter name ('grayscale', 'monochrome', 'denoise', 'sharpen', 'ocrOptimized').
+     - Returns: The filtered UIImage, or nil if filtering fails.
+     */
+    public static func applyFilter(_ image: UIImage, filterType: String) -> UIImage? {
+        if filterType == "color" { return image }
+        
+        guard let ciImage = CIImage(image: image) else { return nil }
+        
+        let outputImage: CIImage?
+        
+        switch filterType {
+        case "grayscale":
+            outputImage = applyGrayscale(ciImage)
+        case "monochrome":
+            outputImage = applyMonochrome(ciImage)
+        case "denoise":
+            outputImage = applyDenoise(ciImage)
+        case "sharpen":
+            outputImage = applySharpen(ciImage)
+        case "ocrOptimized":
+            outputImage = applyOcrOptimizedPipeline(ciImage)
+        default:
+            return image
+        }
+        
+        guard let finalCIImage = outputImage else { return nil }
+        
+        let context = CIContext(options: nil)
+        if let cgImage = context.createCGImage(finalCIImage, from: finalCIImage.extent) {
+            return UIImage(cgImage: cgImage, scale: image.scale, orientation: image.imageOrientation)
+        }
+        
+        return nil
+    }
+    
+    /* ----------------------------------------------------------------------- */
+    /* Filter Helpers                                                          */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Applies a grayscale filter using CIPhotoEffectMono.
+     Desaturates the image while preserving luminance values.
+     
+     - Parameter input: The source CIImage to filter.
+     - Returns: The grayscale CIImage, or nil if the filter is unavailable.
+     */
+    private static func applyGrayscale(_ input: CIImage) -> CIImage? {
+        guard let filter = CIFilter(name: "CIPhotoEffectMono") else { return nil }
+        filter.setValue(input, forKey: kCIInputImageKey)
+        return filter.outputImage
+    }
+    
+    /**
+     Applies a high-contrast monochrome filter using CIPhotoEffectNoir.
+     Creates a dramatic black & white effect ideal for document scanning.
+     
+     - Parameter input: The source CIImage to filter.
+     - Returns: The monochrome CIImage, or nil if the filter is unavailable.
+     */
+    private static func applyMonochrome(_ input: CIImage) -> CIImage? {
+        guard let filter = CIFilter(name: "CIPhotoEffectNoir") else { return nil }
+        filter.setValue(input, forKey: kCIInputImageKey)
+        return filter.outputImage
+    }
+    
+    /**
+     Applies noise reduction using CINoiseReduction.
+     Reduces speckle noise in images captured in low-light or with high ISO.
+     Useful for improving OCR accuracy on noisy photographs.
+     
+     - Parameter input: The source CIImage to filter.
+     - Returns: The denoised CIImage, or nil if the filter is unavailable.
+     - Note: Uses inputNoiseLevel=0.02 and inputSharpness=0.4 for balanced results.
+     */
+    private static func applyDenoise(_ input: CIImage) -> CIImage? {
+        guard let filter = CIFilter(name: "CINoiseReduction") else { return nil }
+        filter.setValue(input, forKey: kCIInputImageKey)
+        filter.setValue(0.02, forKey: "inputNoiseLevel")
+        filter.setValue(0.4, forKey: "inputSharpness")
+        return filter.outputImage
+    }
+    
+    /**
+     Applies luminance-based sharpening using CISharpenLuminance.
+     Enhances edge clarity without amplifying color artifacts.
+     Improves OCR accuracy on blurry or soft-focused text.
+     
+     - Parameter input: The source CIImage to filter.
+     - Returns: The sharpened CIImage, or nil if the filter is unavailable.
+     - Note: Uses sharpness=0.8 for noticeable but not over-aggressive enhancement.
+     */
+    private static func applySharpen(_ input: CIImage) -> CIImage? {
+        guard let filter = CIFilter(name: "CISharpenLuminance") else { return nil }
+        filter.setValue(input, forKey: kCIInputImageKey)
+        filter.setValue(0.8, forKey: kCIInputSharpnessKey)
+        return filter.outputImage
+    }
+    
+    /**
+     Applies the full OCR optimization pipeline: denoise → sharpen → monochrome.
+     
+     This is the recommended filter for maximum text recognition accuracy:
+     1. **Denoise**: Removes noise that would otherwise be amplified by sharpening.
+     2. **Sharpen**: Enhances edge clarity for better character recognition.
+     3. **Monochrome**: High-contrast B&W improves OCR engine performance.
+     
+     - Parameter input: The source CIImage to process.
+     - Returns: The fully processed CIImage, or the input if any step fails.
+     */
+    private static func applyOcrOptimizedPipeline(_ input: CIImage) -> CIImage? {
+        var processed = input
+        
+        // Step 1: Denoise
+        if let denoised = applyDenoise(processed) { processed = denoised }
+        
+        // Step 2: Sharpen
+        if let sharpened = applySharpen(processed) { processed = sharpened }
+        
+        // Step 3: Monochrome (high contrast B&W)
+        if let mono = applyMonochrome(processed) { processed = mono }
+        
+        return processed
+    }
+    
+    /* ----------------------------------------------------------------------- */
+    /* Encoding                                                                */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Converts an image to Base64 string.
+     - Parameters:
+       - image: The image to encode.
+       - format: "jpg" or "png".
+       - quality: Compression quality for JPEG.
+     - Returns: Base64 encoded string, or nil if encoding fails.
+     */
+    public static func base64(from image: UIImage, format: String, quality: CGFloat) -> String? {
+        let data = imageData(from: image, format: format, quality: quality)
+        return data?.base64EncodedString()
+    }
+    
+    /* ----------------------------------------------------------------------- */
+    /* File Operations                                                         */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Generates a unique file path in the temporary directory.
+     - Parameter format: The file extension (e.g., "jpg", "png").
+     - Returns: A unique URL.
+     */
+    public static func createTempFileURL(format: String) -> URL {
+        let fileManager = FileManager.default
+        let tempDir = fileManager.temporaryDirectory
+        let uuid = UUID().uuidString
+        let fileName = "\(uuid).\(format)"
+        return tempDir.appendingPathComponent(fileName)
+    }
+    
+    /**
+     Saves a UIImage to the file system.
+     - Parameters:
+       - image: The image to save.
+       - quality: Compression quality (0.0 - 1.0).
+       - format: "jpg" or "png".
+     - Returns: The absolute path string of the saved file.
+     */
+    public static func saveImage(_ image: UIImage, quality: CGFloat, format: String) throws -> String {
+        let fileURL = createTempFileURL(format: format)
+        
+        guard let data = imageData(from: image, format: format, quality: quality) else {
+            throw ScannerError.operationFailed("Could not generate data for image.")
+        }
+        
+        do {
+            try data.write(to: fileURL)
+            return fileURL.absoluteString
+        } catch {
+            throw ScannerError.operationFailed(error.localizedDescription)
+        }
+    }
+    
+    /* ----------------------------------------------------------------------- */
+    /* Private Helpers                                                         */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Converts a UIImage to Data in the specified format.
+     - Parameters:
+       - image: The image to convert.
+       - format: "jpg" or "png".
+       - quality: Compression quality for JPEG.
+     - Returns: Image data, or nil if conversion fails.
+     */
+    private static func imageData(from image: UIImage, format: String, quality: CGFloat) -> Data? {
+        if format == "png" {
+            return image.pngData()
+        } else {
+            /* Strip alpha before JPEG encoding to avoid AlphaPremulLast warnings.
+               JPEG has no alpha channel, so composite onto white first. */
+            return renderOpaque(image).jpegData(compressionQuality: quality)
+        }
+    }
+
+    /**
+     Renders a UIImage into an opaque RGB context, compositing onto white.
+     Used to strip the alpha channel before JPEG encoding.
+     - Parameter image: The source image (may have alpha).
+     - Returns: An opaque UIImage with no alpha channel.
+     */
+    private static func renderOpaque(_ image: UIImage) -> UIImage {
+        /* If already opaque, skip the redraw entirely. */
+        if let cgImage = image.cgImage {
+            let alpha = cgImage.alphaInfo
+            if alpha == .none || alpha == .noneSkipFirst || alpha == .noneSkipLast {
+                return image
+            }
+        }
+        let rendererFormat = UIGraphicsImageRendererFormat()
+        rendererFormat.scale = image.scale
+        rendererFormat.opaque = true
+        return UIGraphicsImageRenderer(size: image.size, format: rendererFormat).image { _ in
+            image.draw(in: CGRect(origin: .zero, size: image.size))
+        }
+    }
+}

package/ios/Logger.swift

@@ -0,0 +1,43 @@
+import Foundation
+
+/**
+ A centralized logging utility for the Document Scanner.
+ Use this instead of `print` to ensure consistent formatting and easy disabling of logs in production.
+ */
+public class Logger {
+    private static let prefix = "[DocumentScanner]"
+    
+    /**
+     Logs an informational message.
+     - Parameter message: The message string.
+     */
+    public static func info(_ message: String) {
+        print("\(prefix) ℹ️ Info: \(message)")
+    }
+    
+    /**
+     Logs a warning message.
+     - Parameter message: The message string.
+     */
+    public static func warn(_ message: String) {
+        print("\(prefix) ⚠️ Warning: \(message)")
+    }
+    
+    /**
+     Logs an error message.
+     - Parameter message: The message string.
+     */
+    public static func error(_ message: String) {
+        print("\(prefix) ❌ Error: \(message)")
+    }
+    
+    /**
+     Logs a debug message.
+     - Parameter message: The message string.
+     */
+    public static func debug(_ message: String) {
+        #if DEBUG
+        print("\(prefix) 🐛 Debug: \(message)")
+        #endif
+    }
+}

package/ios/OCRConfiguration.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+/**
+ Configuration constants for the OCR engine.
+ Tuning these values affects how the `TextRecognizer` reconstructs layout from raw text blocks.
+ */
+public enum OCRConfiguration {
+  
+    /* ----------------------------------------------------------------------- */
+    /* V2 Clustering Heuristics                                                */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Height Compatibility Threshold.
+     Blocks must have similar heights to be clustered.
+     Formula: minH / maxH >= threshold
+     */
+    public static let heightCompatibilityThreshold: Double = 0.40
+    
+    /**
+     Overlap Ratio Threshold.
+     Vertical intersection divided by min height.
+     */
+    public static let overlapRatioThreshold: Double = 0.50
+    
+    /**
+     Centerline Distance Factor.
+     Max allowed vertical distance between centers as a factor of typical line height.
+     */
+    public static let centerlineDistanceFactor: Double = 0.70
+    
+    /**
+     Adaptive Cluster Growth Limits.
+     Prevents lines from becoming too tall after merging blocks.
+     */
+    public static let stackedGrowthLimit: Double = 1.2
+    public static let skewedGrowthLimit: Double = 2.0
+    
+    /* ----------------------------------------------------------------------- */
+    /* Spacing & Reconstruction                                                */
+    /* ----------------------------------------------------------------------- */
+    
+    /**
+     Adaptive Spacing Factor.
+     Gap width relative to median height to trigger extra spaces.
+     */
+    public static let adaptiveSpacingFactor: Double = 1.0
+    
+    /**
+     Space Width Factor.
+     Determines the "width" of a single space character relative to median height.
+     */
+    public static let spaceWidthFactor: Double = 0.3
+    
+    /**
+     Maximum Spaces Cap.
+     Limits the number of consecutive spaces inserted.
+     */
+    public static let maxSpaces: Int = 10
+}