rn-remove-image-bg 0.0.10

package/NitroRnRemoveImageBg.podspec

@@ -0,0 +1,33 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroRnRemoveImageBg"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/a-eid/rn-remove-image-bg.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.resources = "ios/Models/*.mlmodel"
+
+  load 'nitrogen/generated/ios/NitroRnRemoveImageBg+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,386 @@
+# rn-remove-image-bg
+
+[![GitHub](https://img.shields.io/badge/GitHub-a--eid%2Frn--remove--image--bg-blue)](https://github.com/a-eid/rn-remove-image-bg)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/a-eid/rn-remove-image-bg/blob/main/LICENSE)
+
+**Offline background removal for React Native** using native ML models. Works completely on-device with no internet connection required.
+
+| Platform | Technology | Min Version |
+|----------|------------|-------------|
+| **iOS** | Vision Framework / CoreML | iOS 16+ |
+| **Android** | ML Kit Subject Segmentation | API 21+ |
+| **Web** | @imgly/background-removal (WASM) | Modern browsers |
+
+---
+
+## Installation
+
+Install from GitHub:
+
+```bash
+# Using npm
+npm install github:a-eid/rn-remove-image-bg react-native-nitro-modules
+
+# Using yarn
+yarn add github:a-eid/rn-remove-image-bg react-native-nitro-modules
+
+# Using pnpm
+pnpm add github:a-eid/rn-remove-image-bg react-native-nitro-modules
+```
+
+Or add to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "rn-remove-image-bg": "github:a-eid/rn-remove-image-bg",
+    "react-native-nitro-modules": "0.31.10"
+  }
+}
+```
+
+### Peer Dependencies
+
+This library requires the following peer dependencies for image manipulation:
+
+```bash
+npx expo install expo-file-system expo-image-manipulator
+```
+
+### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+> **Note:** The library bundles a ~4.5MB CoreML model for iOS 16 support. iOS 17+ uses the built-in Vision Framework.
+
+### Android Setup
+
+No additional setup required. The ML Kit model (~10MB) downloads automatically on first use.
+
+---
+
+## Quick Start
+
+```typescript
+import { removeBgImage } from 'rn-remove-image-bg'
+
+// Remove background from an image
+const resultUri = await removeBgImage('file:///path/to/photo.jpg')
+console.log(resultUri) // file:///path/to/cache/bg_removed_xxx.png
+```
+
+---
+
+## API Reference
+
+### `removeBgImage(uri, options?)`
+
+Remove background from an image using native ML models.
+
+```typescript
+import { removeBgImage } from 'rn-remove-image-bg'
+
+const result = await removeBgImage('file:///path/to/image.jpg', {
+  maxDimension: 2048,
+  format: 'PNG',
+  quality: 100,
+  useCache: true,
+  debug: false,
+  onProgress: (progress) => console.log(`${progress}%`)
+})
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `uri` | `string` | File path or `file://` URI to the source image |
+| `options` | `RemoveBgImageOptions` | Optional processing options |
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxDimension` | `number` | `2048` | Max width/height. Larger images are downsampled. |
+| `format` | `'PNG' \| 'WEBP'` | `'PNG'` | Output format. WEBP gives smaller files. |
+| `quality` | `number` | `100` | Quality 0-100 (only affects WEBP). |
+| `useCache` | `boolean` | `true` | Use in-memory cache for repeated calls. |
+| `debug` | `boolean` | `false` | Enable debug logging. |
+| `onProgress` | `(n: number) => void` | — | Progress callback (0-100). |
+
+#### Returns
+
+`Promise<string>` — A URI suitable for use as an `<Image>` source. The format varies by platform:
+- **iOS/Android**: File path (`file:///path/to/cache/bg_removed_xxx.png`)
+- **Web**: Data URL (`data:image/png;base64,...`)
+
+Both formats work directly with React Native's `<Image>` component.
+
+#### Example with Options
+
+```typescript
+import { removeBgImage } from 'rn-remove-image-bg'
+
+const processImage = async (imageUri: string) => {
+  try {
+    const result = await removeBgImage(imageUri, {
+      maxDimension: 1024,      // Faster processing
+      format: 'WEBP',          // Smaller file size
+      quality: 90,             // Good quality, smaller size
+      onProgress: (p) => {
+        console.log(`Processing: ${p}%`)
+      }
+    })
+    
+    console.log('Background removed:', result)
+    return result
+  } catch (error) {
+    if (error instanceof BackgroundRemovalError) {
+      console.error('Error code:', error.code)
+      console.error('User message:', error.toUserMessage())
+    }
+    throw error
+  }
+}
+```
+
+---
+
+### `compressImage(uri, options?)`
+
+Compress and resize an image to a target file size.
+
+```typescript
+import { compressImage } from 'rn-remove-image-bg'
+
+const compressedUri = await compressImage('file:///path/to/image.jpg', {
+  maxSizeKB: 250,
+  width: 1024,
+  height: 1024,
+  quality: 0.85,
+  format: 'WEBP'
+})
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxSizeKB` | `number` | `250` | Target max file size in KB. |
+| `width` | `number` | `1024` | Target width. |
+| `height` | `number` | `1024` | Target height. |
+| `quality` | `number` | `0.85` | Compression quality (0-1). |
+| `format` | `SaveFormat` | `WEBP` | Output format. |
+
+---
+
+### `generateThumbhash(uri, options?)`
+
+Generate a compact [thumbhash](https://evanw.github.io/thumbhash/) placeholder for an image.
+
+```typescript
+import { generateThumbhash } from 'rn-remove-image-bg'
+
+const hash = await generateThumbhash('file:///path/to/image.jpg', {
+  size: 32
+})
+// Returns base64 string like "YTkGJwaRhWWIeHiogohYV4r..."
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `size` | `number` | `32` | Thumbnail size for hash generation. |
+
+---
+
+### Cache Management
+
+```typescript
+import { clearCache, getCacheSize } from 'rn-remove-image-bg'
+
+// Get number of cached results
+const size = getCacheSize()
+console.log(`${size} items in cache`)
+
+// Clear all cached results
+clearCache()
+```
+
+---
+
+## Error Handling
+
+The library throws `BackgroundRemovalError` with specific error codes:
+
+```typescript
+import { removeBgImage, BackgroundRemovalError } from 'rn-remove-image-bg'
+
+try {
+  await removeBgImage(imageUri)
+} catch (error) {
+  if (error instanceof BackgroundRemovalError) {
+    switch (error.code) {
+      case 'INVALID_PATH':
+        console.log('Invalid file path format')
+        break
+      case 'FILE_NOT_FOUND':
+        console.log('Image file not found')
+        break
+      case 'DECODE_FAILED':
+        console.log('Could not decode image')
+        break
+      case 'ML_PROCESSING_FAILED':
+        console.log('ML model failed to process')
+        break
+      case 'SAVE_FAILED':
+        console.log('Could not save result')
+        break
+      case 'INVALID_OPTIONS':
+        console.log('Invalid options provided')
+        break
+      default:
+        console.log('Unknown error')
+    }
+    
+    // Get user-friendly message
+    console.log(error.toUserMessage())
+  }
+}
+```
+
+---
+
+## Platform Notes
+
+### iOS
+
+| iOS Version | Technology | Notes |
+|-------------|------------|-------|
+| iOS 17+ | Vision Framework | Built-in, fastest |
+| iOS 16 | CoreML U2Netp | Bundled ~4.5MB model |
+
+- **Output**: PNG (WEBP requested → HEIC on iOS 17+, PNG on iOS 16)
+- **Processing**: Hardware-accelerated via Metal
+- **Memory**: ~2-3x image size during processing
+
+### Android
+
+- **Technology**: ML Kit Subject Segmentation (beta)
+- **Model**: Downloads ~10MB on first use
+- **Output**: PNG or WEBP (lossy/lossless based on quality)
+- **Requires**: Google Play Services
+
+### Web
+
+- **Technology**: @imgly/background-removal (WebAssembly + ONNX)
+- **Model**: Downloads ~35MB on first use
+- **Output**: Data URL (`data:image/png;base64,...`) or WEBP
+- **Note**: Works in modern browsers with WebAssembly support
+
+> **Return Value Difference**: Web returns data URLs instead of file paths. Both work with `<Image>` components.
+
+If you don't need web support, you can tree-shake the `@imgly/background-removal` dependency.
+
+---
+
+## Performance
+
+| Metric | iOS | Android |
+|--------|-----|---------|
+| **Processing Time** | 300-1500ms | 500-2000ms |
+| **Peak Memory** | 2-3x image size | 2-3x image size |
+| **First Load** | Instant | ~10MB download |
+
+### Optimization Tips
+
+1. **Use `maxDimension`** to downsample large images:
+   ```typescript
+   await removeBgImage(uri, { maxDimension: 1024 })
+   ```
+
+2. **Use WEBP format** for smaller output files:
+   ```typescript
+   await removeBgImage(uri, { format: 'WEBP', quality: 85 })
+   ```
+
+3. **Enable caching** for repeated operations:
+   ```typescript
+   await removeBgImage(uri, { useCache: true })
+   ```
+
+---
+
+## Best Practices for Quality Results
+
+### Photography Tips
+
+| Do ✅ | Don't ❌ |
+|------|---------|
+| Even, diffused lighting | Harsh shadows |
+| Plain backgrounds | Busy patterns |
+| Subject 1-2m from backdrop | Subject touching background |
+| Sharp focus on subject | Motion blur |
+| High contrast vs background | Similar colors to background |
+
+### What Works Best
+
+- ✅ Single, well-defined subjects (people, products, pets)
+- ✅ Solid, opaque objects
+- ✅ Clear edges and outlines
+- ✅ High resolution images (1600x1200+)
+
+### Challenging Cases
+
+- ⚠️ Transparent/translucent objects (glass, liquids)
+- ⚠️ Very fine details (hair, fur, thin straps)
+- ⚠️ Multiple overlapping subjects
+- ⚠️ Low contrast between subject and background
+
+---
+
+## Troubleshooting
+
+### Poor Results?
+
+1. Check lighting conditions
+2. Try a simpler, contrasting background
+3. Ensure subject is in sharp focus
+4. Increase distance between subject and background
+
+### Partial Subject Cutoff?
+
+1. Ensure clear boundaries around subject
+2. Try repositioning or changing background
+3. Avoid busy patterns near edges
+
+### Android Model Not Loading?
+
+1. Ensure device has Google Play Services
+2. Check internet connection for first download
+3. Clear app cache and retry
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import type {
+  RemoveBgImageOptions,
+  CompressImageOptions,
+  GenerateThumbhashOptions,
+  OutputFormat,
+  BackgroundRemovalErrorCode
+} from 'rn-remove-image-bg'
+```
+
+---
+
+## License
+
+MIT © [Ahmed Eid](https://github.com/a-eid)

package/android/CMakeLists.txt

@@ -0,0 +1,28 @@
+project(NitroRnRemoveImageBg)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME NitroRnRemoveImageBg)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+)
+
+# Add Nitrogen specs and autolinking - this adds all necessary sources
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroRnRemoveImageBg+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android                                   # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,142 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.13.0"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroRnRemoveImageBg+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+if (isNewArchitectureEnabled()) {
+  // apply plugin: "com.facebook.react"
+}
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroRnRemoveImageBg_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroRnRemoveImageBg_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.rnremoveimagebg"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+  sourceSets {
+    main {
+      if (isNewArchitectureEnabled()) {
+        java.srcDirs += [
+          // React Codegen files
+          "${project.buildDir}/generated/source/codegen/java"
+        ]
+      }
+    }
+  }
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // For < 0.71, this will be from the local maven repo
+  // For > 0.71, this will be replaced by `com.facebook.react:react-android:$version` by react gradle plugin
+  //noinspection GradleDynamicVersion
+  compileOnly "com.facebook.react:react-android:+"
+  
+  // Add a dependency on NitroModules
+  implementation project(":react-native-nitro-modules")
+  implementation 'com.google.android.gms:play-services-mlkit-subject-segmentation:16.0.0-beta1'
+}
+

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroRnRemoveImageBg_kotlinVersion=2.1.20
+NitroRnRemoveImageBg_minSdkVersion=23
+NitroRnRemoveImageBg_targetSdkVersion=36
+NitroRnRemoveImageBg_compileSdkVersion=36
+NitroRnRemoveImageBg_ndkVersion=27.1.12297006

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,3 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+  package="com.margelo.nitro.rnremoveimagebg">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "NitroRnRemoveImageBgOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::rnremoveimagebg::initialize(vm);
+}