mediversal-rn-image-intelligence 1.0.6

package/README.md

@@ -0,0 +1,361 @@
+# mediversal-rn-image-intelligence
+
+[![npm version](https://badge.fury.io/js/mediversal-rn-image-intelligence.svg)](https://badge.fury.io/js/mediversal-rn-image-intelligence)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+🎯 **Production-ready React Native library for intelligent image analysis using Google ML Kit (on-device)**
+
+Analyze images to detect faces, extract printed text, and recognize handwritten content—all processed locally on the device for maximum privacy and performance.
+
+## 🌟 Features
+
+- **Face Detection**: Detect human faces with detailed metadata (smiling probability, eye open probability, head rotation, etc.)
+- **Text Recognition (OCR)**: Extract printed text from images with high accuracy
+- **Handwriting Recognition**: Recognize handwritten text (requires stroke data)
+- **🚀 On-Device Processing**: All analysis happens locally using Google ML Kit
+- **🔒 Privacy-First**: No data sent to external servers
+- **⚡ Fast & Efficient**: Optimized for mobile performance
+- **📱 Cross-Platform**: Works seamlessly on iOS and Android
+- **🎨 TurboModule Architecture**: Built with React Native New Architecture support
+- **💪 TypeScript**: Fully typed API for excellent developer experience
+
+## 📦 Installation
+
+```bash
+npm install mediversal-rn-image-intelligence
+# or
+yarn add mediversal-rn-image-intelligence
+```
+
+### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+**Required**: Add the following to your `Info.plist` if you need camera or photo library access:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>We need access to your camera to capture images for analysis</string>
+<key>NSPhotoLibraryUsageDescription</key>
+<string>We need access to your photo library to analyze images</string>
+```
+
+### Android Setup
+
+The library will automatically configure the required Google ML Kit dependencies. Ensure your `minSdkVersion` is at least 21:
+
+```gradle
+// android/build.gradle
+buildscript {
+    ext {
+        minSdkVersion = 21
+    }
+}
+```
+
+**Required**: Add permissions to your `AndroidManifest.xml` if needed:
+
+```xml
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.CAMERA" />
+```
+
+## 🚀 Usage
+
+### Basic Example
+
+```typescript
+import { analyzeImage } from 'mediversal-rn-image-intelligence';
+
+async function analyzeMyImage() {
+  try {
+    const result = await analyzeImage('file:///path/to/image.jpg');
+
+    console.log('Contains face:', result.containsFace);
+    console.log('Contains printed text:', result.containsPrintedText);
+    console.log('Contains handwritten text:', result.containsHandwrittenText);
+
+    // Access detected faces
+    if (result.faces) {
+      result.faces.forEach((face, index) => {
+        console.log(`Face ${index + 1}:`);
+        console.log('  Bounding box:', face.boundingBox);
+        console.log('  Smiling:', face.smilingProbability);
+        console.log('  Left eye open:', face.leftEyeOpenProbability);
+        console.log('  Right eye open:', face.rightEyeOpenProbability);
+      });
+    }
+
+    // Access extracted text
+    if (result.printedText) {
+      console.log('Extracted text:', result.printedText);
+    }
+  } catch (error) {
+    console.error('Analysis failed:', error);
+  }
+}
+```
+
+### Advanced Example with Options
+
+```typescript
+import {
+  analyzeImage,
+  type AnalysisOptions,
+} from 'mediversal-rn-image-intelligence';
+
+const options: AnalysisOptions = {
+  detectFaces: true,
+  detectPrintedText: true,
+  detectHandwrittenText: false, // Skip handwriting for performance
+  faceDetectionMode: 'accurate', // 'fast' or 'accurate'
+  minFaceSize: 0.15, // Minimum face size (0.0 to 1.0)
+};
+
+const result = await analyzeImage('file:///path/to/image.jpg', options);
+```
+
+### With Image Picker
+
+```typescript
+import { launchImageLibrary } from 'react-native-image-picker';
+import { analyzeImage } from 'mediversal-rn-image-intelligence';
+
+async function pickAndAnalyze() {
+  const response = await launchImageLibrary({
+    mediaType: 'photo',
+    quality: 1,
+  });
+
+  if (response.assets && response.assets[0].uri) {
+    const result = await analyzeImage(response.assets[0].uri);
+    console.log(result);
+  }
+}
+```
+
+### React Component Example
+
+```typescript
+import React, { useState } from 'react';
+import { View, Button, Text, Image } from 'react-native';
+import { launchImageLibrary } from 'react-native-image-picker';
+import {
+  analyzeImage,
+  type AnalysisResult,
+} from 'mediversal-rn-image-intelligence';
+
+export default function ImageAnalyzer() {
+  const [imageUri, setImageUri] = useState<string | null>(null);
+  const [result, setResult] = useState<AnalysisResult | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const selectAndAnalyze = async () => {
+    const response = await launchImageLibrary({ mediaType: 'photo' });
+
+    if (response.assets && response.assets[0].uri) {
+      const uri = response.assets[0].uri;
+      setImageUri(uri);
+      setLoading(true);
+
+      try {
+        const analysis = await analyzeImage(uri);
+        setResult(analysis);
+      } catch (error) {
+        console.error(error);
+      } finally {
+        setLoading(false);
+      }
+    }
+  };
+
+  return (
+    <View style={{ padding: 20 }}>
+      <Button title="Select Image" onPress={selectAndAnalyze} />
+
+      {imageUri && (
+        <Image source={{ uri: imageUri }} style={{ width: 300, height: 300 }} />
+      )}
+
+      {loading && <Text>Analyzing...</Text>}
+
+      {result && (
+        <View style={{ marginTop: 20 }}>
+          <Text>Faces detected: {result.containsFace ? 'Yes' : 'No'}</Text>
+          <Text>
+            Text detected: {result.containsPrintedText ? 'Yes' : 'No'}
+          </Text>
+          {result.faces && <Text>Number of faces: {result.faces.length}</Text>}
+          {result.printedText && (
+            <Text>Extracted text: {result.printedText}</Text>
+          )}
+        </View>
+      )}
+    </View>
+  );
+}
+```
+
+## 📚 API Reference
+
+### `analyzeImage(imageUri: string, options?: AnalysisOptions): Promise<AnalysisResult>`
+
+Main function to analyze an image.
+
+**Parameters:**
+
+- `imageUri` (string): Local file URI. Supported formats:
+  - Android: `file:///path/to/image.jpg`, `content://...`, or absolute path
+  - iOS: `file:///path/to/image.jpg`, `ph://...`, `assets-library://...`, or absolute path
+- `options` (AnalysisOptions, optional): Configuration options
+
+**Returns:** Promise<AnalysisResult>
+
+### `isAvailable(): Promise<boolean>`
+
+Check if the library is properly installed and native modules are available.
+
+## 📋 Types
+
+### `AnalysisResult`
+
+```typescript
+interface AnalysisResult {
+  containsFace: boolean;
+  containsPrintedText: boolean;
+  containsHandwrittenText: boolean;
+  faces?: FaceData[];
+  printedText?: string;
+  handwrittenText?: string;
+  errors?: {
+    faceDetection?: string;
+    textRecognition?: string;
+    handwritingRecognition?: string;
+  };
+}
+```
+
+### `FaceData`
+
+```typescript
+interface FaceData {
+  boundingBox: BoundingBox;
+  smilingProbability?: number; // 0.0 to 1.0
+  leftEyeOpenProbability?: number; // 0.0 to 1.0
+  rightEyeOpenProbability?: number; // 0.0 to 1.0
+  headEulerAngleY?: number; // Yaw in degrees
+  headEulerAngleZ?: number; // Roll in degrees
+  trackingId?: number;
+}
+```
+
+### `BoundingBox`
+
+```typescript
+interface BoundingBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+### `AnalysisOptions`
+
+```typescript
+interface AnalysisOptions {
+  detectFaces?: boolean; // default: true
+  detectPrintedText?: boolean; // default: true
+  detectHandwrittenText?: boolean; // default: true
+  faceDetectionMode?: 'fast' | 'accurate'; // default: 'fast'
+  minFaceSize?: number; // 0.0 to 1.0, default: 0.1
+}
+```
+
+## ⚡ Performance Tips
+
+1. **Use 'fast' mode for real-time applications**: The `faceDetectionMode: 'fast'` option provides better performance for live camera feeds.
+
+2. **Disable unused features**: If you only need face detection, disable text recognition:
+
+   ```typescript
+   analyzeImage(uri, {
+     detectPrintedText: false,
+     detectHandwrittenText: false,
+   });
+   ```
+
+3. **Optimize image size**: Resize large images before analysis to improve processing time.
+
+4. **Parallel processing**: The library automatically runs all enabled analyses in parallel for maximum efficiency.
+
+## 🔒 Privacy & Security
+
+All image processing happens **locally on the device** using Google ML Kit's on-device APIs. No image data is ever sent to external servers, ensuring:
+
+- ✅ Complete user privacy
+- ✅ Offline functionality
+- ✅ Faster processing
+- ✅ No data usage costs
+- ✅ GDPR & CCPA compliance
+
+## 🐛 Troubleshooting
+
+### iOS: "Module not found"
+
+Make sure you've run `pod install`:
+
+```bash
+cd ios && pod install
+```
+
+### Android: Gradle build errors
+
+Ensure your `minSdkVersion` is at least 21 and you're using Java 11:
+
+```gradle
+android {
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_11
+        targetCompatibility JavaVersion.VERSION_11
+    }
+}
+```
+
+### Image URI format errors
+
+- **Android**: Use `file://`, `content://`, or absolute paths
+- **iOS**: Use `file://`, `ph://`, `assets-library://`, or absolute paths
+
+### Digital Ink Recognition limitation
+
+The Digital Ink Recognition API is designed for real-time stroke data (from drawing apps), not static images. For handwriting recognition in static images, consider:
+
+- Using Google Cloud Vision API (cloud-based)
+- Pre-processing images to extract stroke information
+- Using alternative OCR solutions specifically designed for handwriting
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+MIT © Mediversal
+
+## 🙏 Acknowledgments
+
+Built with:
+
+- [Google ML Kit](https://developers.google.com/ml-kit)
+- [React Native](https://reactnative.dev/)
+
+## 📞 Support
+
+- 📧 Email: sushantbibhu@gmail.com
+- 🐛 Issues: [GitHub Issues](https://github.com/thisissushant/mediversal-rn-image-intelligence)
+- 📖 Documentation: [GitHub Wiki](https://github.com/thisissushant/mediversal-rn-image-intelligence)
+
+---

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Tue Jan 27 14:16:03 IST 2026
+gradle.version=8.9

package/android/build.gradle

@@ -0,0 +1,71 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath 'com.android.tools.build:gradle:7.4.2'
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
+
+def safeExtGet(prop, fallback) {
+  rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+}
+
+android {
+  compileSdkVersion safeExtGet('compileSdkVersion', 33)
+  
+  namespace "com.mediversalrnimagintelligence"
+
+  defaultConfig {
+    minSdkVersion safeExtGet('minSdkVersion', 21)
+    targetSdkVersion safeExtGet('targetSdkVersion', 33)
+    versionCode 1
+    versionName "1.0.0"
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_11
+    targetCompatibility JavaVersion.VERSION_11
+  }
+
+  kotlinOptions {
+    jvmTarget = '11'
+  }
+}
+
+repositories {
+  google()
+  mavenCentral()
+}
+
+dependencies {
+  // React Native
+  implementation 'com.facebook.react:react-native:+'
+  
+  // Kotlin
+  implementation "org.jetbrains.kotlin:kotlin-stdlib:1.8.0"
+  
+  // Google ML Kit - Face Detection
+  implementation 'com.google.mlkit:face-detection:16.1.5'
+  
+  // Google ML Kit - Text Recognition v2 (newer API)
+  implementation 'com.google.android.gms:play-services-mlkit-text-recognition:19.0.0'
+  
+  // Google ML Kit - Digital Ink Recognition
+  implementation 'com.google.mlkit:digital-ink-recognition:18.1.0'
+  
+  // Coroutines for async operations
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.6.4'
+  implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4'
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,10 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+          package="com.mediversalrnimagintelligence">
+  
+  <!-- Permissions for reading images -->
+  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+  
+  <!-- Optional: for camera access if needed -->
+  <uses-permission android:name="android.permission.CAMERA" />
+  
+</manifest>

package/android/src/main/java/com/mediversalrnimagintelligence/FaceDetectionModule.kt

@@ -0,0 +1,147 @@
+package com.mediversalrnimagintelligence
+
+import android.graphics.Rect
+import android.net.Uri
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.bridge.WritableArray
+import com.google.mlkit.vision.common.InputImage
+import com.google.mlkit.vision.face.Face
+import com.google.mlkit.vision.face.FaceDetection
+import com.google.mlkit.vision.face.FaceDetectorOptions
+import java.io.IOException
+
+class FaceDetectionModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return "FaceDetectionModule"
+    }
+
+    @ReactMethod
+    fun detectFaces(imageUri: String, mode: String, minFaceSize: Double, promise: Promise) {
+        try {
+            // Parse the image from URI
+            val image = parseImageFromUri(imageUri)
+            
+            // Configure face detector
+            val detectorOptions = when (mode) {
+                "accurate" -> FaceDetectorOptions.Builder()
+                    .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
+                    .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
+                    .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
+                    .setMinFaceSize(minFaceSize.toFloat())
+                    .enableTracking()
+                    .build()
+                else -> FaceDetectorOptions.Builder()
+                    .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_FAST)
+                    .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
+                    .setMinFaceSize(minFaceSize.toFloat())
+                    .build()
+            }
+
+            val detector = FaceDetection.getClient(detectorOptions)
+
+            // Process the image
+            detector.process(image)
+                .addOnSuccessListener { faces ->
+                    val result = Arguments.createMap()
+                    val facesArray = Arguments.createArray()
+
+                    for (face in faces) {
+                        facesArray.pushMap(convertFaceToMap(face))
+                    }
+
+                    result.putArray("faces", facesArray)
+                    promise.resolve(result)
+                }
+                .addOnFailureListener { e ->
+                    val result = Arguments.createMap()
+                    result.putArray("faces", Arguments.createArray())
+                    result.putString("error", e.message ?: "Face detection failed")
+                    promise.resolve(result)
+                }
+
+        } catch (e: Exception) {
+            val result = Arguments.createMap()
+            result.putArray("faces", Arguments.createArray())
+            result.putString("error", e.message ?: "Failed to process image")
+            promise.resolve(result)
+        }
+    }
+
+    private fun parseImageFromUri(uriString: String): InputImage {
+        val context = reactApplicationContext
+        
+        return try {
+            when {
+                uriString.startsWith("file://") -> {
+                    val uri = Uri.parse(uriString)
+                    InputImage.fromFilePath(context, uri)
+                }
+                uriString.startsWith("content://") -> {
+                    val uri = Uri.parse(uriString)
+                    InputImage.fromFilePath(context, uri)
+                }
+                uriString.startsWith("/") -> {
+                    // Absolute file path
+                    val uri = Uri.parse("file://$uriString")
+                    InputImage.fromFilePath(context, uri)
+                }
+                else -> {
+                    throw IOException("Unsupported URI format: $uriString")
+                }
+            }
+        } catch (e: IOException) {
+            throw IOException("Failed to load image from URI: ${e.message}")
+        }
+    }
+
+    private fun convertFaceToMap(face: Face): WritableMap {
+        val faceMap = Arguments.createMap()
+
+        // Bounding box
+        val boundingBox = Arguments.createMap()
+        val bounds: Rect = face.boundingBox
+        boundingBox.putInt("x", bounds.left)
+        boundingBox.putInt("y", bounds.top)
+        boundingBox.putInt("width", bounds.width())
+        boundingBox.putInt("height", bounds.height())
+        faceMap.putMap("boundingBox", boundingBox)
+
+        // Smiling probability
+        if (face.smilingProbability != null) {
+            faceMap.putDouble("smilingProbability", face.smilingProbability!!.toDouble())
+        }
+
+        // Left eye open probability
+        if (face.leftEyeOpenProbability != null) {
+            faceMap.putDouble("leftEyeOpenProbability", face.leftEyeOpenProbability!!.toDouble())
+        }
+
+        // Right eye open probability
+        if (face.rightEyeOpenProbability != null) {
+            faceMap.putDouble("rightEyeOpenProbability", face.rightEyeOpenProbability!!.toDouble())
+        }
+
+        // Head Euler angles
+        if (face.headEulerAngleY != null) {
+            faceMap.putDouble("headEulerAngleY", face.headEulerAngleY!!.toDouble())
+        }
+
+        if (face.headEulerAngleZ != null) {
+            faceMap.putDouble("headEulerAngleZ", face.headEulerAngleZ!!.toDouble())
+        }
+
+        // Tracking ID
+        if (face.trackingId != null) {
+            faceMap.putInt("trackingId", face.trackingId!!)
+        }
+
+        return faceMap
+    }
+}

package/android/src/main/java/com/mediversalrnimagintelligence/HandwritingRecognitionModule.kt

@@ -0,0 +1,74 @@
+package com.mediversalrnimagintelligence
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.google.mlkit.vision.digitalink.DigitalInkRecognition
+import com.google.mlkit.vision.digitalink.DigitalInkRecognitionModel
+import com.google.mlkit.vision.digitalink.DigitalInkRecognitionModelIdentifier
+import com.google.mlkit.vision.digitalink.DigitalInkRecognizer
+import com.google.mlkit.vision.digitalink.DigitalInkRecognizerOptions
+import com.google.mlkit.vision.digitalink.Ink
+import java.io.IOException
+import java.io.InputStream
+
+class HandwritingRecognitionModule(reactContext: ReactApplicationContext) :
+    ReactContextBaseJavaModule(reactContext) {
+
+    override fun getName(): String {
+        return "HandwritingRecognitionModule"
+    }
+
+    @ReactMethod
+    fun recognizeHandwriting(imageUri: String, promise: Promise) {
+        try {
+            // Note: Digital Ink Recognition in ML Kit is designed for real-time stroke data,
+            // not static images. For production use with static images, you would need to:
+            // 1. Use a different API (like Cloud Vision API's handwriting detection)
+            // 2. Or pre-process the image to extract strokes
+            // 
+            // For this implementation, we'll provide a graceful fallback indicating
+            // that handwriting recognition from static images is not fully supported
+            // by the on-device Digital Ink API.
+
+            val result = Arguments.createMap()
+            result.putString("text", "")
+            result.putString(
+                "error", 
+                "Digital Ink Recognition requires stroke data, not static images. " +
+                "For handwriting in static images, consider using Cloud Vision API or " +
+                "preprocessing to extract stroke information."
+            )
+            promise.resolve(result)
+
+            // Alternative implementation note:
+            // If you have stroke data (from a drawing canvas), the proper implementation would be:
+            // 1. Create an Ink object from strokes
+            // 2. Get recognizer with appropriate model
+            // 3. Call recognizer.recognize(ink)
+            //
+            // Example (commented out as it requires stroke data):
+            // val modelIdentifier = DigitalInkRecognitionModelIdentifier.fromLanguageTag("en-US")
+            // val model = DigitalInkRecognitionModel.builder(modelIdentifier!!).build()
+            // val recognizer = DigitalInkRecognition.getClient(
+            //     DigitalInkRecognizerOptions.builder(model).build()
+            // )
+            // recognizer.recognize(ink)
+            //     .addOnSuccessListener { result ->
+            //         // Process candidates
+            //     }
+
+        } catch (e: Exception) {
+            val result = Arguments.createMap()
+            result.putString("text", "")
+            result.putString("error", e.message ?: "Handwriting recognition failed")
+            promise.resolve(result)
+        }
+    }
+}