expo-segmentation

Native background removal and subject segmentation for Expo and React Native.

Detects foreground subjects in photos and removes their backgrounds, returning cropped PNG cutouts with optional greyscale masks.

Platform support

| Platform | Engine | Min version | |----------|--------|-------------| | iOS | Apple Vision (VNGenerateForegroundInstanceMaskRequest) | iOS 17 | | Android | Google ML Kit Subject Segmentation | API 24 | | Web | — | isAvailable() returns false |

Installation

npm install expo-segmentation
# or
yarn add expo-segmentation

This module contains native code. Managed Expo projects must use a development build or EAS Build — it will not work in Expo Go.

iOS — install pods after adding the package:

npx pod-install
# or
cd ios && pod install

Android — no extra steps. ML Kit is fetched automatically via Gradle.

Quick start

import ExpoSegmentation from 'expo-segmentation';
import * as ImagePicker from 'expo-image-picker';

// 1. Check availability
if (!ExpoSegmentation.isAvailable()) {
  console.warn('Segmentation not available on this device / OS version');
  return;
}

// 2. Pick an image
const result = await ImagePicker.launchImageLibraryAsync({ mediaTypes: ['images'] });
if (result.canceled) return;
const { uri } = result.assets[0];

// 3. Detect individual subjects
const subjects = await ExpoSegmentation.detectSubjects(uri);
// subjects: [{ index: 0, previewUri: 'file://...' }, ...]

// 4. Remove background for selected subjects
const cutouts = await ExpoSegmentation.removeBackground(uri, {
  subjectIndices: [0],   // omit to composite all subjects into one result
  returnMask: false,     // set true to also receive a greyscale mask PNG
});
// cutouts: [{ uri, width, height, cropRect: { x, y, width, height } }]

API reference

ExpoSegmentation.isAvailable(): boolean

Synchronous check. Returns true when the native segmentation API is available on the current device and OS version (iOS 17+, Android API 24+).

ExpoSegmentation.detectSubjects(imageUri: string): Promise<SubjectInfo[]>

Runs the segmentation model and returns one entry per detected foreground subject.

Parameters

| Name | Type | Description | |------|------|-------------| | imageUri | string | file:// URI or http(s):// URL of the source image |

Returns Promise<SubjectInfo[]>

Each SubjectInfo:

interface SubjectInfo {
  index: number;      // zero-based subject identifier
  previewUri: string; // file:// URI — PNG of this subject on a transparent bg
}

ExpoSegmentation.removeBackground(imageUri: string, options?: SegmentationOptions): Promise<SegmentationResult[]>

Removes the background and returns one cropped PNG per requested subject.

Parameters

| Name | Type | Description | |------|------|-------------| | imageUri | string | file:// URI or http(s):// URL of the source image | | options | SegmentationOptions | Optional — see below |

SegmentationOptions

interface SegmentationOptions {
  subjectIndices?: number[];  // indices from detectSubjects(); omit = all subjects combined
  returnMask?: boolean;       // also return a greyscale mask PNG (default: false)
}

Returns Promise<SegmentationResult[]>

Each SegmentationResult:

interface SegmentationResult {
  uri: string;          // file:// URI — PNG cutout with transparent background
  maskUri?: string;     // file:// URI — greyscale mask PNG (only when returnMask: true)
  width: number;        // pixel width of the cropped output image
  height: number;       // pixel height of the cropped output image
  cropRect: {           // position of the crop inside the original image
    x: number;
    y: number;
    width: number;
    height: number;
  };
}

Example app

A full demo is included at example/. It shows the three-step flow: pick/take a photo → review detected subjects → remove background and share results.

cd example
npm install
npx expo start

To use native features on a real device, run via EAS Build or npx expo run:ios / npx expo run:android after npx expo prebuild.

Notes

• iOS: requires iOS 17 or later. On iOS 16 and below, isAvailable() returns false and both async methods will throw.
• Android: ML Kit Subject Segmentation requires at least API level 24 (Android 7.0). isAvailable() always returns true on supported Android versions.
• Output images are written to the device's temporary cache directory. Clean them up when no longer needed if your app processes many images.
• For very large photos (12 MP+), the module automatically downscales before processing to keep memory usage reasonable while preserving output quality.

Contributing

Contributions are welcome. Please open an issue or pull request on GitHub.

License

MIT