@hoshomoh/react-native-document-scanner 1.2.0

package/android/src/main/java/com/documentscanner/Options.kt

@@ -0,0 +1,109 @@
+package com.documentscanner
+
+import com.facebook.react.bridge.ReadableMap
+
+/**
+ * Reads an integer option from a ReadableMap.
+ * Uses getDouble instead of getInt because TypeScript `number` is always encoded as a
+ * JSI double — getInt can fail or return incorrect results on some RN versions.
+ */
+private fun intOption(options: ReadableMap?, key: String, fallback: Int): Int =
+    if (options?.hasKey(key) == true) options.getDouble(key).toInt() else fallback
+
+/**
+ * Base options shared by both Scan and Process operations.
+ * Allows parsing common properties from a React Native ReadableMap.
+ */
+abstract class BaseOptions(
+    val quality: Double,
+    val format: String,
+    val filter: String,
+    val includeBase64: Boolean,
+    val includeText: Boolean,
+    val textVersion: Int
+) {
+    /**
+     * Secondary constructor to parse common options from a dictionary.
+     * Delegates to the primary constructor with validated values.
+     */
+    constructor(options: ReadableMap?, defaultIncludeText: Boolean) : this(
+        quality = parseQuality(options),
+        format = parseFormat(options),
+        filter = parseFilter(options),
+        includeBase64 = parseBoolean(options, "includeBase64", false),
+        includeText = parseBoolean(options, "includeText", defaultIncludeText),
+        textVersion = parseTextVersion(options)
+    )
+
+    companion object {
+        /** Validates and returns the compression quality [0.1, 1.0]. */
+        private fun parseQuality(options: ReadableMap?): Double {
+            val value = if (options?.hasKey("quality") == true) options.getDouble("quality") else 1.0
+            return value.coerceIn(0.1, 1.0)
+        }
+
+        /** Whitelists and returns the output image format. */
+        private fun parseFormat(options: ReadableMap?): String {
+            val value = options?.getString("format") ?: "jpg"
+            return if (value == "png") "png" else "jpg"
+        }
+
+        /** Whitelists and returns the post-processing filter. */
+        private fun parseFilter(options: ReadableMap?): String {
+            val value = options?.getString("filter") ?: "color"
+            val validFilters = listOf("color", "grayscale", "monochrome", "denoise", "sharpen", "ocrOptimized")
+            return if (validFilters.contains(value)) value else "color"
+        }
+
+        /** Safely parses a boolean value with a default fallback. */
+        private fun parseBoolean(options: ReadableMap?, key: String, default: Boolean): Boolean {
+            return if (options?.hasKey(key) == true) options.getBoolean(key) else default
+        }
+
+        /** Validates and returns the OCR engine version [1, 2]. */
+        private fun parseTextVersion(options: ReadableMap?): Int {
+            val value = intOption(options, "textVersion", 2)
+            return if (value == 1) 1 else 2
+        }
+    }
+}
+
+/**
+ * Strongly-typed options for the scanDocuments() method.
+ */
+class ScanOptions(options: ReadableMap?, fallbackPageCount: Int) : BaseOptions(options, false) {
+    /** Maximum pages to scan, clamped to [0, 100]. */
+    val maxPageCount: Int = parseMaxPages(options, fallbackPageCount)
+
+    companion object {
+        fun from(options: ReadableMap?): ScanOptions = ScanOptions(options, 0)
+
+        private fun parseMaxPages(options: ReadableMap?, fallback: Int): Int =
+            intOption(options, "maxPageCount", fallback).coerceIn(0, 100)
+    }
+}
+
+/**
+ * Strongly-typed options for the processDocuments() method.
+ */
+class ProcessOptions(options: ReadableMap?) : BaseOptions(options, true) {
+    /** List of image URIs or Base64 strings to process. */
+    val images: List<String> = parseImages(options)
+
+    companion object {
+        fun from(options: ReadableMap?): ProcessOptions = ProcessOptions(options)
+
+        private fun parseImages(options: ReadableMap?): List<String> {
+            val images = mutableListOf<String>()
+            if (options?.hasKey("images") == true) {
+                val array = options.getArray("images")
+                if (array != null) {
+                    for (i in 0 until array.size()) {
+                        array.getString(i)?.let { images.add(it) }
+                    }
+                }
+            }
+            return images
+        }
+    }
+}

package/android/src/main/java/com/documentscanner/ScannerError.kt

@@ -0,0 +1,18 @@
+package com.documentscanner
+
+/**
+ * Represents structured errors returned to the React Native layer.
+ */
+sealed class ScannerError(val code: String, val message: String) {
+    /** The device hardware or OS version does not support scanning. */
+    class NotSupported : ScannerError("NOT_SUPPORTED", "Device does not support document scanning")
+    
+    /** The provided options were invalid or missing required fields. */
+    class ConfigurationError(detail: String) : ScannerError("CONFIGURATION_ERROR", "Configuration Error: $detail")
+    
+    /** A runtime error occurred during scanning or processing. */
+    class OperationFailed(detail: String) : ScannerError("OPERATION_FAILED", "Operation Failed: $detail")
+    
+    /** The user manually cancelled the scanner interface. */
+    class Canceled : ScannerError("CANCELED", "User canceled the scan")
+}

package/android/src/main/java/com/documentscanner/TextRecognizer.kt

@@ -0,0 +1,56 @@
+package com.documentscanner
+
+import android.content.Context
+import android.net.Uri
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.text.TextRecognition
+import com.google.mlkit.vision.text.latin.TextRecognizerOptions
+import kotlinx.coroutines.tasks.await
+
+/**
+ * Utility class for performing Optical Character Recognition (OCR) using ML Kit.
+ * Extracts text and bounding boxes from images.
+ *
+ * Acts as a Facade delegating to versioned implementations:
+ * - TextRecognizerV1 (Raw)
+ * - TextRecognizerV2 (Heuristic)
+ */
+class TextRecognizer {
+    companion object {
+
+        /**
+         * Processes an image and extracts text blocks based on the requested version.
+         *
+         * @param context Application context
+         * @param uri URI of the image to process from disk
+         * @param version OCR engine version (1 = Raw ML Kit, 2 = Layout Heuristics)
+         * @return WritableMap containing "text" and "blocks"
+         */
+        suspend fun processImage(context: Context, uri: Uri, version: Int): WritableMap {
+            try {
+                val image = InputImage.fromFilePath(context, uri)
+                val imagePixelWidth = image.width.toDouble()
+                val imagePixelHeight = image.height.toDouble()
+
+                val recognizer = TextRecognition.getClient(TextRecognizerOptions.DEFAULT_OPTIONS)
+                val visionText = recognizer.process(image).await()
+
+                return if (version == 1) {
+                    TextRecognizerV1.process(visionText, imagePixelWidth, imagePixelHeight)
+                } else {
+                    TextRecognizerV2.process(visionText, imagePixelWidth, imagePixelHeight)
+                }
+
+            } catch (e: Exception) {
+                e.printStackTrace()
+                Logger.error("OCR processing failed: ${e.message}", e)
+                val emptyMap = Arguments.createMap()
+                emptyMap.putString("text", "")
+                emptyMap.putArray("blocks", Arguments.createArray())
+                return emptyMap
+            }
+        }
+    }
+}

package/android/src/main/java/com/documentscanner/TextRecognizerV1.kt

@@ -0,0 +1,68 @@
+package com.documentscanner
+
+import android.graphics.Rect
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.google.mlkit.vision.text.Text
+
+/**
+ * Version 1: Raw Output (Standard ML Kit Behavior)
+ */
+class TextRecognizerV1 {
+    companion object {
+        /**
+         * Performs raw text recognition using ML Kit's default output.
+         * Returns one block per visual line (ML Kit TextLine level) for
+         * consistent cross-platform granularity with iOS V1.
+         *
+         * @param visionText The raw result from ML Kit.
+         * @param imagePixelWidth Original image width in pixels.
+         * @param imagePixelHeight Original image height in pixels.
+         * @return WritableMap with "text" and "blocks".
+         */
+        fun process(visionText: Text, imagePixelWidth: Double, imagePixelHeight: Double): WritableMap {
+            val resultMap = Arguments.createMap()
+
+            // Raw text from ML Kit
+            resultMap.putString("text", visionText.text)
+
+            // Line-level blocks — one block per ML Kit TextLine
+            val blocksArray = Arguments.createArray()
+            for (block in visionText.textBlocks) {
+                for (line in block.lines) {
+                    val blockMap = Arguments.createMap()
+                    blockMap.putString("text", line.text)
+
+                    val frameMap = Arguments.createMap()
+                    val box = line.boundingBox ?: Rect(0, 0, 0, 0)
+
+                    frameMap.putDouble("x", safeNormalize(box.left.toDouble(), imagePixelWidth))
+                    frameMap.putDouble("y", safeNormalize(box.top.toDouble(), imagePixelHeight))
+                    frameMap.putDouble("width", safeNormalize(box.width().toDouble(), imagePixelWidth))
+                    frameMap.putDouble("height", safeNormalize(box.height().toDouble(), imagePixelHeight))
+
+                    blockMap.putMap("frame", frameMap)
+
+                    // Average confidence from all elements in the line
+                    if (line.elements.isNotEmpty()) {
+                        val avgConfidence = line.elements.map { it.confidence.toDouble() }.average()
+                        blockMap.putDouble("confidence", avgConfidence)
+                    }
+
+                    blocksArray.pushMap(blockMap)
+                }
+            }
+            resultMap.putArray("blocks", blocksArray)
+
+            return resultMap
+        }
+
+        /**
+         * Safely normalizes a pixel value by dividing by the dimension.
+         * Returns 0.0 if the dimension is zero or negative to avoid divide-by-zero.
+         */
+        private fun safeNormalize(value: Double, dimension: Double): Double {
+            return if (dimension > 0) value / dimension else 0.0
+        }
+    }
+}

package/android/src/main/java/com/documentscanner/TextRecognizerV2.kt

@@ -0,0 +1,244 @@
+package com.documentscanner
+
+import android.graphics.Rect
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.google.mlkit.vision.text.Text
+import kotlin.math.abs
+import kotlin.math.max
+import kotlin.math.min
+
+/**
+ * Version 2: Heuristic Enhanced (Line Clustering for Layout Preservation)
+ */
+class TextRecognizerV2 {
+
+    /**
+     * Internal data class representing a text element with its bounding box and confidence.
+     */
+    private data class TextElement(
+        val text: String,
+        val left: Double,
+        val top: Double,
+        val width: Double,
+        val height: Double,
+        val confidence: Double
+    )
+
+    companion object {
+        /**
+         * Performs heuristic-enhanced text recognition with layout preservation.
+         * Matches horizontally aligned word-level elements into logical lines.
+         *
+         * @param visionText The raw result from ML Kit.
+         * @param imagePixelWidth Original image width in pixels.
+         * @param imagePixelHeight Original image height in pixels.
+         * @return WritableMap with "text" (structured) and "blocks" (line-level metadata).
+         */
+        fun process(visionText: Text, imagePixelWidth: Double, imagePixelHeight: Double): WritableMap {
+            val resultMap = Arguments.createMap()
+
+            // Step 1: Extract generic "TextElement" from ML Kit's word-level elements
+            val allElements = mutableListOf<TextElement>()
+
+            // Flatten to word level (line.elements) for better granular clustering
+            for (block in visionText.textBlocks) {
+                for (line in block.lines) {
+                    for (element in line.elements) {
+                        val box = element.boundingBox ?: continue
+                        allElements.add(TextElement(
+                            text = element.text,
+                            left = safeNormalize(box.left.toDouble(), imagePixelWidth),
+                            top = safeNormalize(box.top.toDouble(), imagePixelHeight),
+                            width = safeNormalize(box.width().toDouble(), imagePixelWidth),
+                            height = safeNormalize(box.height().toDouble(), imagePixelHeight),
+                            confidence = element.confidence.toDouble()
+                        ))
+                    }
+                }
+            }
+
+            // Step 2: Group elements into Lines using LineCluster Strategy
+            class LineCluster(firstElement: TextElement) {
+                val elements = mutableListOf(firstElement)
+                val heights = mutableListOf(firstElement.height)
+                val centerYs = mutableListOf(firstElement.top + firstElement.height / 2.0)
+
+                // Union Bounding Box state
+                var uLeft = firstElement.left
+                var uTop = firstElement.top
+                var uRight = firstElement.left + firstElement.width
+                var uBottom = firstElement.top + firstElement.height
+
+                fun medianHeight(): Double {
+                    if (heights.isEmpty()) return 0.0
+                    val sorted = heights.sorted()
+                    val mid = sorted.size / 2
+                    return if (sorted.size % 2 == 0) {
+                        (sorted[mid - 1] + sorted[mid]) / 2.0
+                    } else {
+                        sorted[mid]
+                    }
+                }
+
+                fun medianCenterY(): Double {
+                    if (centerYs.isEmpty()) return 0.0
+                    val sorted = centerYs.sorted()
+                    val mid = sorted.size / 2
+                    return if (sorted.size % 2 == 0) {
+                        (sorted[mid - 1] + sorted[mid]) / 2.0
+                    } else {
+                        sorted[mid]
+                    }
+                }
+
+                val height: Double get() = uBottom - uTop
+                val midY: Double get() = uTop + (height / 2.0) // retained for final cluster sort
+
+                fun add(element: TextElement) {
+                    elements.add(element)
+                    heights.add(element.height)
+                    centerYs.add(element.top + element.height / 2.0)
+
+                    // Update union box
+                    uLeft = min(uLeft, element.left)
+                    uTop = min(uTop, element.top)
+                    uRight = max(uRight, element.left + element.width)
+                    uBottom = max(uBottom, element.top + element.height)
+                }
+            }
+
+            // Sort by midY ascending (top of page first)
+            val sortedElements = allElements.sortedBy { it.top + (it.height / 2.0) }
+            val clusters = mutableListOf<LineCluster>()
+
+            for (element in sortedElements) {
+                val elHeight = element.height
+                val elMidY = element.top + (elHeight / 2.0)
+
+                var bestClusterIndex: Int? = null
+                var bestOverlapRatio = 0.0
+                var bestCenterDist = Double.MAX_VALUE
+
+                for ((index, cluster) in clusters.withIndex()) {
+
+                    // 1. Height Similarity Check — use median height, not union bbox height
+                    val clusterMedianH = cluster.medianHeight()
+                    val minH = min(clusterMedianH, elHeight)
+                    val maxH = max(clusterMedianH, elHeight)
+                    if ((minH / maxH) < OCRConfiguration.HEIGHT_COMPATIBILITY_THRESHOLD) continue
+
+                    // 2. Overlap & Centerline — use median centerY, not union bbox midY
+                    val intTop = max(cluster.uTop, element.top)
+                    val intBottom = min(cluster.uBottom, element.top + element.height)
+                    val intHeight = max(0.0, intBottom - intTop)
+
+                    val overlapRatio = intHeight / minH
+
+                    val centerDist = abs(cluster.medianCenterY() - elMidY)
+                    val typicalHeight = max(clusterMedianH, elHeight)
+
+                    val isOverlapGood = overlapRatio >= OCRConfiguration.OVERLAP_RATIO_THRESHOLD
+                    val isCenterClose = centerDist <= (OCRConfiguration.CENTERLINE_DISTANCE_FACTOR * typicalHeight)
+
+                    if (isOverlapGood || isCenterClose) {
+                        // 3. Adaptive Cluster Growth Constraint
+                        val clusterRight = cluster.uRight
+                        val elementRight = element.left + element.width
+                        val intersectX = max(0.0, min(clusterRight, elementRight) - max(cluster.uLeft, element.left))
+                        val isStacked = intersectX > 0
+
+                        val growthLimit = if (isStacked) OCRConfiguration.STACKED_GROWTH_LIMIT else OCRConfiguration.SKEWED_GROWTH_LIMIT
+
+                        val newTop = min(cluster.uTop, element.top)
+                        val newBottom = max(cluster.uBottom, element.top + element.height)
+                        val newHeight = newBottom - newTop
+
+                        if (newHeight <= (growthLimit * typicalHeight)) {
+                            if (overlapRatio > bestOverlapRatio) {
+                                bestOverlapRatio = overlapRatio
+                                bestCenterDist = centerDist
+                                bestClusterIndex = index
+                            } else if (abs(overlapRatio - bestOverlapRatio) < 0.01 && centerDist < bestCenterDist) {
+                                bestCenterDist = centerDist
+                                bestClusterIndex = index
+                            }
+                        }
+                    }
+                }
+
+                if (bestClusterIndex != null) {
+                    clusters[bestClusterIndex].add(element)
+                } else {
+                    clusters.add(LineCluster(element))
+                }
+            }
+
+            // Sort clusters top-to-bottom
+            clusters.sortBy { it.midY }
+
+            // Step 3: Reconstruct text with adaptive column spacing + build cluster-based blocks
+            val structuredText = StringBuilder()
+            val blocksArray = Arguments.createArray()
+
+            for (cluster in clusters) {
+                // Sort elements left-to-right for reading order
+                val lineElements = cluster.elements.sortedBy { it.left }
+                val medianH = cluster.medianHeight()
+
+                val lineString = StringBuilder()
+                var lastXEnd = 0.0
+
+                for ((index, element) in lineElements.withIndex()) {
+                    val xStart = element.left
+
+                    if (index > 0) {
+                        val gap = xStart - lastXEnd
+
+                        if (gap > (medianH * OCRConfiguration.ADAPTIVE_SPACING_FACTOR)) {
+                            val spaceWidth = medianH * OCRConfiguration.SPACE_WIDTH_FACTOR
+                            val spaces = max(1, (gap / spaceWidth).toInt())
+                            lineString.append(" ".repeat(min(spaces, OCRConfiguration.MAX_SPACES)))
+                        } else {
+                            lineString.append(" ")
+                        }
+                    }
+
+                    lineString.append(element.text)
+                    lastXEnd = xStart + element.width
+                }
+
+                structuredText.append(lineString).append("\n")
+
+                // Build one block per cluster (line-level, aligned with text output)
+                val blockMap = Arguments.createMap()
+                blockMap.putString("text", lineString.toString())
+
+                val frameMap = Arguments.createMap()
+                frameMap.putDouble("x", cluster.uLeft)
+                frameMap.putDouble("y", cluster.uTop)
+                frameMap.putDouble("width", cluster.uRight - cluster.uLeft)
+                frameMap.putDouble("height", cluster.uBottom - cluster.uTop)
+                blockMap.putMap("frame", frameMap)
+
+                val avgConfidence = cluster.elements.map { it.confidence }.average()
+                blockMap.putDouble("confidence", avgConfidence)
+
+                blocksArray.pushMap(blockMap)
+            }
+
+            resultMap.putString("text", structuredText.toString())
+            resultMap.putArray("blocks", blocksArray)
+
+            return resultMap
+        }
+
+        /**
+         * Safely normalizes a pixel value by dividing by the dimension.
+         * Returns 0.0 if the dimension is zero or negative to avoid divide-by-zero.
+         */
+        private fun safeNormalize(value: Double, dimension: Double): Double {
+            return if (dimension > 0) value / dimension else 0.0
+        }
+    }
+}

package/ios/DocumentScanner.h

@@ -0,0 +1,5 @@
+#import <DocumentScannerSpec/DocumentScannerSpec.h>
+
+@interface DocumentScanner : NSObject <NativeDocumentScannerSpec>
+
+@end

package/ios/DocumentScanner.mm

@@ -0,0 +1,113 @@
+#import "DocumentScanner.h"
+#import <Foundation/Foundation.h>
+
+@protocol DocumentScannerSwiftProtocol <NSObject>
+- (void)scanDocuments:(NSDictionary *)options
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject;
+- (void)processDocuments:(NSDictionary *)options
+                 resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject;
+@end
+
+@implementation DocumentScanner {
+  id _impl;
+}
+
+- (instancetype)init {
+  if (self = [super init]) {
+    Class swiftClass = NSClassFromString(@"DocumentScannerManager");
+    if (swiftClass) {
+      _impl = [[swiftClass alloc] init];
+    }
+  }
+  return self;
+}
+
+- (void)scanDocuments:(JS::NativeDocumentScanner::ScanOptions &)options
+              resolve:(RCTPromiseResolveBlock)resolve
+               reject:(RCTPromiseRejectBlock)reject {
+  NSMutableDictionary *dict = [NSMutableDictionary new];
+
+  if (options.maxPageCount().has_value()) {
+    dict[@"maxPageCount"] = @(options.maxPageCount().value());
+  }
+  if (options.quality().has_value()) {
+    dict[@"quality"] = @(options.quality().value());
+  }
+  if (options.format()) {
+    dict[@"format"] = options.format();
+  }
+  if (options.filter()) {
+    dict[@"filter"] = options.filter();
+  }
+  if (options.includeBase64().has_value()) {
+    dict[@"includeBase64"] = @(options.includeBase64().value());
+  }
+  if (options.includeText().has_value()) {
+    dict[@"includeText"] = @(options.includeText().value());
+  }
+  if (options.textVersion().has_value()) {
+    dict[@"textVersion"] = @(options.textVersion().value());
+  }
+
+  if (_impl) {
+    [(id<DocumentScannerSwiftProtocol>)_impl scanDocuments:dict
+                                                   resolve:resolve
+                                                    reject:reject];
+  } else {
+    reject(@"impl_error", @"Swift implementation not found", nil);
+  }
+}
+
+- (void)processDocuments:(JS::NativeDocumentScanner::ProcessOptions &)options
+                 resolve:(RCTPromiseResolveBlock)resolve
+                  reject:(RCTPromiseRejectBlock)reject {
+  NSMutableDictionary *dict = [NSMutableDictionary new];
+
+  /* Convert images array */
+  NSMutableArray *images = [NSMutableArray new];
+  for (NSString *img : options.images()) {
+    [images addObject:img];
+  }
+  dict[@"images"] = images;
+
+  if (options.quality().has_value()) {
+    dict[@"quality"] = @(options.quality().value());
+  }
+  if (options.format()) {
+    dict[@"format"] = options.format();
+  }
+  if (options.filter()) {
+    dict[@"filter"] = options.filter();
+  }
+  if (options.includeBase64().has_value()) {
+    dict[@"includeBase64"] = @(options.includeBase64().value());
+  }
+  if (options.includeText().has_value()) {
+    dict[@"includeText"] = @(options.includeText().value());
+  }
+  if (options.textVersion().has_value()) {
+    dict[@"textVersion"] = @(options.textVersion().value());
+  }
+
+  if (_impl) {
+    [(id<DocumentScannerSwiftProtocol>)_impl processDocuments:dict
+                                                      resolve:resolve
+                                                       reject:reject];
+  } else {
+    reject(@"impl_error", @"Swift implementation not found", nil);
+  }
+}
+
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::NativeDocumentScannerSpecJSI>(
+      params);
+}
+
++ (NSString *)moduleName {
+  return @"DocumentScanner";
+}
+
+@end