@hoshomoh/react-native-document-scanner 1.2.0

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

@@ -0,0 +1,217 @@
+package com.documentscanner
+
+import android.app.Activity
+import android.content.Intent
+import com.facebook.react.bridge.*
+import com.google.mlkit.vision.documentscanner.GmsDocumentScannerOptions
+import com.google.mlkit.vision.documentscanner.GmsDocumentScanning
+import com.google.mlkit.vision.documentscanner.GmsDocumentScanningResult
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.tasks.await
+
+/**
+ * Native module for Document Scanner.
+ * Handles the communication between React Native and the Android ML Kit Document Scanner.
+ * Implements ActivityEventListener to handle the result of the native scanner activity.
+ */
+class DocumentScannerModule(reactContext: ReactApplicationContext) :
+  NativeDocumentScannerSpec(reactContext), ActivityEventListener {
+
+  private var scanPromise: Promise? = null
+  private var currentScanOptions: ScanOptions? = null
+  private val scope = CoroutineScope(Dispatchers.Main)
+  private val imageProcessor = ImageProcessor(reactContext)
+
+  init {
+    reactContext.addActivityEventListener(this)
+  }
+
+  override fun getName(): String {
+    return NAME
+  }
+
+  /**
+   * Launches the ML Kit Document Scanner activity.
+   *
+   * @param options Dictionary containing scan configuration (maxPageCount, quality, format, etc.)
+   * @param promise React Native promise to resolve with results or reject with error
+   */
+  override fun scanDocuments(options: ReadableMap?, promise: Promise) {
+    val activity: Activity? = reactApplicationContext.currentActivity
+    if (activity == null) {
+      val error = ScannerError.OperationFailed("Activity doesn't exist")
+      promise.reject(error.code, error.message)
+      return
+    }
+
+    // Prevent concurrent scans to ensure state integrity
+    if (scanPromise != null) {
+      val error = ScannerError.OperationFailed("A scan is already in progress")
+      promise?.reject(error.code, error.message)
+      return
+    }
+
+    scanPromise = promise
+    
+    try {
+      // Parse options using strongly-typed helper
+      val scanOptions = ScanOptions.from(options)
+      currentScanOptions = scanOptions
+      Logger.log("Starting scanDocuments with options: MaxPages=${scanOptions.maxPageCount}, Quality=${scanOptions.quality}")
+
+      // Configure GmsDocumentScannerOptions
+      // We always request JPEG + PDF to provide maximum flexibility in post-processing,
+      // though we currently prioritize JPEG for React Native consumption.
+      val scannerOptionsBuilder = GmsDocumentScannerOptions.Builder()
+        .setScannerMode(GmsDocumentScannerOptions.SCANNER_MODE_FULL)
+        .setResultFormats(GmsDocumentScannerOptions.RESULT_FORMAT_JPEG)
+        .setGalleryImportAllowed(true)
+
+      if (scanOptions.maxPageCount > 0) {
+        scannerOptionsBuilder.setPageLimit(scanOptions.maxPageCount)
+      }
+
+      // Initialize the scanner client
+      val scanner = GmsDocumentScanning.getClient(scannerOptionsBuilder.build())
+      
+      // Launch the scanner intent
+      scanner.getStartScanIntent(activity)
+        .addOnSuccessListener(activity) { intentSender ->
+          try {
+            activity.startIntentSenderForResult(intentSender, START_SCAN_REQUEST_CODE, null, 0, 0, 0)
+          } catch (e: Exception) {
+            val error = ScannerError.OperationFailed("Failed to start scanner activity: ${e.message}")
+            Logger.error(error.message, e)
+            scanPromise?.reject(error.code, error.message)
+            scanPromise = null
+          }
+        }
+        .addOnFailureListener { e ->
+          val error = ScannerError.OperationFailed("Failed to launch scanner client: ${e.message}")
+          Logger.error(error.message, e)
+          scanPromise?.reject(error.code, error.message)
+          scanPromise = null
+        }
+
+    } catch (e: Exception) {
+      // Catch-all for configuration or unexpected runtime errors during setup
+      val error = ScannerError.ConfigurationError(e.message ?: "Unknown error")
+      Logger.error(error.message, e)
+      scanPromise?.reject(error.code, error.message)
+      scanPromise = null
+    }
+  }
+
+  /**
+   * Processes existing images (e.g., from Gallery) with the same pipeline as scanned documents.
+   * Applying filters, resizing, compression, and OCR.
+   *
+   * @param options Dictionary containing input images and processing configuration.
+   * @param promise React Native promise to resolve with results.
+   */
+  override fun processDocuments(options: ReadableMap?, promise: Promise) {
+    val processOptions = ProcessOptions.from(options)
+    
+    // Validate inputs immediately
+    if (processOptions.images.isEmpty()) {
+        val error = ScannerError.ConfigurationError("No images provided to process")
+        promise?.reject(error.code, error.message)
+        return
+    }
+
+    Logger.log("Starting processDocuments with ${processOptions.images.size} images")
+
+    // Launch coroutine for background processing to avoid blocking the UI thread
+    scope.launch {
+        try {
+            val resultsArray = Arguments.createArray()
+            // Sequentially process each image
+            for (uri in processOptions.images) {
+                val result = imageProcessor.process(uri, processOptions)
+                resultsArray.pushMap(result)
+            }
+            promise?.resolve(resultsArray)
+        } catch (e: Exception) {
+            val error = ScannerError.OperationFailed(e.message ?: "Unknown processing error")
+            Logger.error("Error in processDocuments", e)
+            promise?.reject(error.code, error.message)
+        }
+    }
+  }
+
+  /**
+   * Handles the result from the native scanner activity.
+   */
+  override fun onActivityResult(activity: Activity, requestCode: Int, resultCode: Int, data: Intent?) {
+    if (requestCode == START_SCAN_REQUEST_CODE) {
+      if (scanPromise == null) {
+          Logger.warn("Received onActivityResult but scanPromise is null. Ignoring.")
+          return
+      }
+
+      if (resultCode == Activity.RESULT_OK && data != null) {
+        val result = GmsDocumentScanningResult.fromActivityResultIntent(data)
+        if (result != null) {
+            val pages = result.pages
+            Logger.log("Scan successful. Received ${pages?.size ?: 0} pages. Starting processing...")
+            
+            // Offload post-processing (copy to cache, OCR, etc.) to background thread
+            scope.launch {
+                try {
+                    val resultsArray = Arguments.createArray()
+                    // Fallback to default options if somehow missing (should not happen in normal flow)
+                    val options = currentScanOptions ?: ScanOptions.from(null) 
+                    
+                    if (pages != null) {
+                        for (page in pages) {
+                            val uri = page.imageUri.toString()
+                            // Pass through the shared ImageProcessor pipeline
+                            val processedResult = imageProcessor.process(uri, options)
+                            resultsArray.pushMap(processedResult)
+                        }
+                    }
+                    scanPromise?.resolve(resultsArray)
+                } catch (e: Exception) {
+                    val error = ScannerError.OperationFailed("Post-processing failed: ${e.message}")
+                    Logger.error(error.message, e)
+                    scanPromise?.reject(error.code, error.message)
+                } finally {
+                    // Cleanup state
+                    scanPromise = null
+                    currentScanOptions = null
+                }
+            }
+        } else {
+            val error = ScannerError.OperationFailed("Scanning result object was null")
+            Logger.error(error.message)
+            scanPromise?.reject(error.code, error.message)
+            scanPromise = null
+            currentScanOptions = null
+        }
+      } else if (resultCode == Activity.RESULT_CANCELED) {
+        val error = ScannerError.Canceled()
+        Logger.log("User canceled the scanner UI")
+        scanPromise?.reject(error.code, error.message)
+        scanPromise = null
+        currentScanOptions = null
+      } else {
+        val error = ScannerError.OperationFailed("Unknown Activity result code: $resultCode")
+        Logger.warn(error.message)
+        scanPromise?.reject(error.code, error.message)
+        scanPromise = null
+        currentScanOptions = null
+      }
+    }
+  }
+
+  override fun onNewIntent(intent: Intent) {
+    // No-op: We only care about onActivityResult
+  }
+
+  companion object {
+    const val NAME = "DocumentScanner"
+    const val START_SCAN_REQUEST_CODE = 1452
+  }
+}

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

@@ -0,0 +1,39 @@
+package com.documentscanner
+
+import com.facebook.react.TurboReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import java.util.HashMap
+
+/**
+ * React Native package for the Document Scanner.
+ * Registers the native module for both Legacy and New Architecture (TurboModules).
+ */
+class DocumentScannerPackage : TurboReactPackage() {
+  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+    return if (name == DocumentScannerModule.NAME) {
+      DocumentScannerModule(reactContext)
+    } else {
+      null
+    }
+  }
+
+  override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+    return ReactModuleInfoProvider {
+      val moduleInfos: MutableMap<String, ReactModuleInfo> = HashMap()
+      val isTurboModule: Boolean = true
+      moduleInfos[DocumentScannerModule.NAME] = ReactModuleInfo(
+        DocumentScannerModule.NAME,
+        DocumentScannerModule.NAME,
+        false, // canOverrideExistingModule
+        false, // needsEagerInit
+        true, // hasConstants
+        false, // isCxxModule
+        isTurboModule
+      )
+      moduleInfos
+    }
+  }
+}

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

@@ -0,0 +1,325 @@
+package com.documentscanner
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import android.graphics.ColorMatrix
+import android.graphics.ColorMatrixColorFilter
+import android.graphics.Matrix
+import android.graphics.Paint
+import android.net.Uri
+import androidx.exifinterface.media.ExifInterface
+import android.util.Base64
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableMap
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.io.FileOutputStream
+import java.io.InputStream
+import java.util.UUID
+
+/**
+ * Utility class for image processing operations.
+ * Handles loading, rotating, filtering, and running OCR on images.
+ * All operations are executed on a background IO dispatcher.
+ */
+class ImageProcessor(private val context: Context) {
+
+    /**
+     * Main processing pipeline.
+     * 1. Loads the bitmap (handling EXIF rotation).
+     * 2. Applies filters (Grayscale, Monochrome).
+     * 3. Saves processing result to a temp file (required for OCR/Base64 consistency).
+     * 4. Encodes to Base64 (optional).
+     * 5. Runs OCR (optional).
+     *
+     * @param uriStr The source URI of the image (file://, content://, data:...)
+     * @param options Processing options (quality, format, filters, etc.)
+     * @return WritableMap containing uri, base64, text, blocks, etc.
+     */
+    suspend fun process(uriStr: String, options: BaseOptions): WritableMap = withContext(Dispatchers.IO) {
+        val result = Arguments.createMap()
+        result.putString("uri", uriStr) // Default to original URI if something fails
+
+        try {
+            val uri = Uri.parse(uriStr)
+            var bitmap = loadBitmap(uri) ?: return@withContext result
+
+            // 1. Apply Filters
+            val filter = options.filter
+            if (filter != "color") {
+                Logger.log("Applying filter: $filter")
+                bitmap = applyFilter(bitmap, filter)
+            }
+
+            // 2. Save Processed Image
+            // We save to the cache directory to ensure we deliver a clean file that matches the requested format/quality.
+            val qualityInt = (options.quality * 100).toInt().coerceIn(0, 100)
+            
+            val format = options.format
+            val compressFormat = if (format == "png") Bitmap.CompressFormat.PNG else Bitmap.CompressFormat.JPEG
+            
+            val newFile = File(context.cacheDir, "scan_${UUID.randomUUID()}.${if (format == "png") "png" else "jpg"}")
+            val fos = FileOutputStream(newFile)
+            bitmap.compress(compressFormat, qualityInt, fos)
+            fos.close()
+            
+            val newUri = Uri.fromFile(newFile).toString()
+            result.putString("uri", newUri)
+
+            // 3. Base64 Generation
+            if (options.includeBase64) {
+                val byteArrayOutputStream = ByteArrayOutputStream()
+                bitmap.compress(compressFormat, qualityInt, byteArrayOutputStream)
+                val byteArray = byteArrayOutputStream.toByteArray()
+                val base64String = Base64.encodeToString(byteArray, Base64.NO_WRAP)
+                result.putString("base64", base64String)
+            }
+
+            // 4. Optical Character Recognition (OCR)
+            if (options.includeText) {
+                Logger.log("Running OCR on processed image (Version ${options.textVersion})")
+                val ocrResult = TextRecognizer.processImage(context, Uri.fromFile(newFile), options.textVersion)
+                result.putString("text", ocrResult.getString("text"))
+                if (ocrResult.hasKey("blocks")) {
+                    result.putArray("blocks", ocrResult.getArray("blocks"))
+                }
+            }
+
+        } catch (e: Exception) {
+            Logger.error("Failed to process image: $uriStr", e)
+             // Swallow specific image error to allow other images in a batch to proceed.
+        }
+
+        // 5. Metadata
+        val metadataMap = Arguments.createMap()
+        metadataMap.putString("platform", "android")
+        metadataMap.putInt("textVersion", options.textVersion)
+        metadataMap.putString("filter", options.filter)
+        metadataMap.putString("ocrEngine", if (options.includeText) "MLKit" else "none")
+        result.putMap("metadata", metadataMap)
+
+        return@withContext result
+    }
+
+    /**
+     * Loads a Bitmap from a URI, handling various schemes and correcting orientation.
+     * Supports: content://, file://, data:image/base64
+     */
+    private fun loadBitmap(uri: Uri): Bitmap? {
+         try {
+             // Handle data URI (Base64)
+             if (uri.scheme == "data") {
+                 val base64Data = uri.toString().substringAfter(",")
+                 val decodedBytes = Base64.decode(base64Data, Base64.DEFAULT)
+                 return BitmapFactory.decodeByteArray(decodedBytes, 0, decodedBytes.size)
+             }
+
+             // Handle Content/File URIs
+             var inputStream: InputStream? = context.contentResolver.openInputStream(uri)
+             val originalBitmap = BitmapFactory.decodeStream(inputStream)
+             inputStream?.close()
+
+             if (originalBitmap == null) {
+                 Logger.warn("Failed to decode bitmap from $uri")
+                 return null
+             }
+
+             // Read EXIF to determine orientation
+             // This is critical for images from Gallery or Camera which might use orientation tags
+             inputStream = context.contentResolver.openInputStream(uri)
+             if (inputStream == null) return originalBitmap
+
+             try {
+                val exif = ExifInterface(inputStream)
+                val orientation = exif.getAttributeInt(ExifInterface.TAG_ORIENTATION, ExifInterface.ORIENTATION_NORMAL)
+                inputStream.close()
+                return rotateBitmap(originalBitmap, orientation)
+             } catch (e: Exception) {
+                // If EXIF fails (e.g. some streams don't support it), fail safe and return original
+                Logger.warn("Failed to read EXIF for rotation: ${e.message}")
+                return originalBitmap
+             }
+         } catch (e: Exception) {
+             Logger.error("Error loading bitmap", e)
+             return null
+         }
+    }
+
+    /**
+     * Rotates a bitmap based on EXIF orientation.
+     */
+    private fun rotateBitmap(bitmap: Bitmap, orientation: Int): Bitmap {
+        val matrix = Matrix()
+        when (orientation) {
+            ExifInterface.ORIENTATION_ROTATE_90 -> matrix.postRotate(90f)
+            ExifInterface.ORIENTATION_ROTATE_180 -> matrix.postRotate(180f)
+            ExifInterface.ORIENTATION_ROTATE_270 -> matrix.postRotate(270f)
+            else -> return bitmap
+        }
+        return Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
+    }
+
+    /**
+     * Applies color or convolution filters to the bitmap.
+     * Supports: "grayscale", "monochrome" (high contrast), "denoise", "sharpen", "ocrOptimized".
+     */
+    private fun applyFilter(src: Bitmap, filterType: String?): Bitmap {
+        return when (filterType) {
+            "grayscale" -> applyColorMatrixFilter(src, createGrayscaleMatrix())
+            "monochrome" -> applyColorMatrixFilter(src, createMonochromeMatrix())
+            "denoise" -> applyConvolutionFilter(src, DENOISE_KERNEL)
+            "sharpen" -> applyConvolutionFilter(src, SHARPEN_KERNEL)
+            "ocrOptimized" -> applyOcrOptimizedPipeline(src)
+            else -> src
+        }
+    }
+    
+    /**
+     * 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.
+     *
+     * @param src The source bitmap to process.
+     * @return The fully processed bitmap.
+     */
+    private fun applyOcrOptimizedPipeline(src: Bitmap): Bitmap {
+        var result = src
+        // Step 1: Denoise
+        result = applyConvolutionFilter(result, DENOISE_KERNEL)
+        // Step 2: Sharpen
+        result = applyConvolutionFilter(result, SHARPEN_KERNEL)
+        // Step 3: Monochrome (high contrast B&W)
+        result = applyColorMatrixFilter(result, createMonochromeMatrix())
+        return result
+    }
+    
+    /**
+     * Applies a ColorMatrix filter to the bitmap.
+     * Used for color transformations like grayscale and monochrome.
+     *
+     * @param src The source bitmap to filter.
+     * @param matrix The ColorMatrix defining the transformation.
+     * @return A new bitmap with the filter applied.
+     */
+    private fun applyColorMatrixFilter(src: Bitmap, matrix: ColorMatrix): Bitmap {
+        val dest = Bitmap.createBitmap(src.width, src.height, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(dest)
+        val paint = Paint()
+        paint.colorFilter = ColorMatrixColorFilter(matrix)
+        canvas.drawBitmap(src, 0f, 0f, paint)
+        return dest
+    }
+    
+    /**
+     * Creates a grayscale ColorMatrix.
+     * Desaturates the image while preserving luminance values.
+     *
+     * @return A ColorMatrix configured for grayscale conversion.
+     */
+    private fun createGrayscaleMatrix(): ColorMatrix {
+        val matrix = ColorMatrix()
+        matrix.setSaturation(0f)
+        return matrix
+    }
+    
+    /**
+     * Creates a high-contrast monochrome ColorMatrix.
+     * Combines grayscale desaturation with contrast enhancement.
+     * Produces a dramatic black & white effect ideal for document scanning.
+     *
+     * @return A ColorMatrix configured for monochrome conversion with contrast boost.
+     * @note Uses scale=1.3 for contrast enhancement, optimized for text readability.
+     */
+    private fun createMonochromeMatrix(): ColorMatrix {
+        val matrix = ColorMatrix()
+        matrix.setSaturation(0f)
+        val contrast = ColorMatrix()
+        val scale = 1.3f
+        val translate = (-.5f * scale + .5f) * 255f
+        contrast.set(floatArrayOf(
+            scale, 0f, 0f, 0f, translate,
+            0f, scale, 0f, 0f, translate,
+            0f, 0f, scale, 0f, translate,
+            0f, 0f, 0f, 1f, 0f
+        ))
+        matrix.postConcat(contrast)
+        return matrix
+    }
+    
+    /**
+     * Applies a 3x3 convolution kernel to the bitmap.
+     * Used for spatial filtering effects like blur (denoise) and sharpen.
+     *
+     * @param src The source bitmap to filter.
+     * @param kernel A 9-element float array representing the 3x3 convolution kernel.
+     * @return A new bitmap with the convolution applied.
+     * @note Edge pixels are not processed to avoid bounds checking complexity.
+     */
+    private fun applyConvolutionFilter(src: Bitmap, kernel: FloatArray): Bitmap {
+        val width = src.width
+        val height = src.height
+        val pixels = IntArray(width * height)
+        val result = IntArray(width * height)
+        src.getPixels(pixels, 0, width, 0, 0, width, height)
+        
+        // 3x3 kernel offsets: top-left to bottom-right
+        val offsets = arrayOf(
+            intArrayOf(-1, -1), intArrayOf(0, -1), intArrayOf(1, -1),
+            intArrayOf(-1, 0), intArrayOf(0, 0), intArrayOf(1, 0),
+            intArrayOf(-1, 1), intArrayOf(0, 1), intArrayOf(1, 1)
+        )
+        
+        for (y in 1 until height - 1) {
+            for (x in 1 until width - 1) {
+                var r = 0f; var g = 0f; var b = 0f
+                for (k in 0 until 9) {
+                    val px = pixels[(y + offsets[k][1]) * width + (x + offsets[k][0])]
+                    r += ((px shr 16) and 0xFF) * kernel[k]
+                    g += ((px shr 8) and 0xFF) * kernel[k]
+                    b += (px and 0xFF) * kernel[k]
+                }
+                val a = (pixels[y * width + x] shr 24) and 0xFF
+                result[y * width + x] = (a shl 24) or
+                    (r.toInt().coerceIn(0, 255) shl 16) or
+                    (g.toInt().coerceIn(0, 255) shl 8) or
+                    b.toInt().coerceIn(0, 255)
+            }
+        }
+        
+        val dest = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+        dest.setPixels(result, 0, width, 0, 0, width, height)
+        return dest
+    }
+    
+    companion object {
+        /**
+         * Box blur kernel (3x3) for noise reduction.
+         * Averages each pixel with its 8 neighbors, smoothing out noise.
+         * Useful for improving OCR accuracy on noisy photographs.
+         */
+        private val DENOISE_KERNEL = floatArrayOf(
+            1/9f, 1/9f, 1/9f,
+            1/9f, 1/9f, 1/9f,
+            1/9f, 1/9f, 1/9f
+        )
+        
+        /**
+         * Sharpen kernel (3x3) for edge enhancement.
+         * Emphasizes differences between adjacent pixels.
+         * Improves OCR accuracy on blurry or soft-focused text.
+         */
+        private val SHARPEN_KERNEL = floatArrayOf(
+            0f, -1f, 0f,
+            -1f, 5f, -1f,
+            0f, -1f, 0f
+        )
+    }
+}

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

@@ -0,0 +1,36 @@
+package com.documentscanner
+
+import android.util.Log
+
+/**
+ * Centralized logging utility for the Document Scanner.
+ * Uses Android's native Log system with a consistent tag and visual indicators.
+ */
+object Logger {
+    private const val TAG = "DocumentScanner"
+
+    /**
+     * Logs an informational message.
+     */
+    fun log(message: String) {
+        Log.d(TAG, "ℹ️ $message")
+    }
+
+    /**
+     * Logs a warning message.
+     */
+    fun warn(message: String) {
+        Log.w(TAG, "⚠️ $message")
+    }
+
+    /**
+     * Logs an error message with an optional exception.
+     */
+    fun error(message: String, throwable: Throwable? = null) {
+        if (throwable != null) {
+            Log.e(TAG, "❌ $message", throwable)
+        } else {
+            Log.e(TAG, "❌ $message")
+        }
+    }
+}

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

@@ -0,0 +1,56 @@
+package com.documentscanner
+
+/**
+ * Configuration constants for the OCR engine.
+ * Tuning these values affects how the TextRecognizer reconstructs layout from raw text blocks.
+ */
+object OCRConfiguration {
+    
+    // --- V2 Clustering Heuristics ---
+    
+    /**
+     * Height Compatibility Threshold.
+     * Blocks must have similar heights to be clustered.
+     * Formula: minH / maxH >= threshold
+     */
+    const val HEIGHT_COMPATIBILITY_THRESHOLD: Double = 0.40
+    
+    /**
+     * Overlap Ratio Threshold.
+     * Vertical intersection divided by min height.
+     */
+    const val OVERLAP_RATIO_THRESHOLD: Double = 0.50
+    
+    /**
+     * Centerline Distance Factor.
+     * Max allowed vertical distance between centers as a factor of typical line height.
+     */
+    const val CENTERLINE_DISTANCE_FACTOR: Double = 0.70
+    
+    /**
+     * Adaptive Cluster Growth Limits.
+     * Prevents lines from becoming too tall after merging blocks.
+     */
+    const val STACKED_GROWTH_LIMIT: Double = 1.2
+    const val SKEWED_GROWTH_LIMIT: Double = 2.0
+    
+    // --- Spacing & Reconstruction ---
+    
+    /**
+     * Adaptive Spacing Factor.
+     * Gap width relative to median height to trigger extra spaces.
+     */
+    const val ADAPTIVE_SPACING_FACTOR: Double = 1.0
+    
+    /**
+     * Space Width Factor.
+     * Determines the "width" of a single space character relative to median height.
+     */
+    const val SPACE_WIDTH_FACTOR: Double = 0.3
+    
+    /**
+     * Maximum Spaces Cap.
+     * Limits the number of consecutive spaces inserted.
+     */
+    const val MAX_SPACES: Int = 10
+}