isnet-background-removal
v1.0.2
Published
🎨 **AI-powered background removal** using ISNet and ONNX Runtime for **both Node.js and browsers**.
Readme
isnet-background-removal
🎨 AI-powered background removal using ISNet and ONNX Runtime for both Node.js and browsers.
Features
✨ Works in both Node.js and browsers
🚀 Fast inference using ONNX Runtime
🎯 High-quality results with ISNet model
📦 Simple API, no configuration needed
🔧 Customizable for advanced use cases
Installation
npm install isnet-background-removalUsage
Node.js
import { removeBackground } from 'isnet-background-removal';
import { writeFile } from 'fs/promises';
// From file path
const result = await removeBackground('./image.jpg');
await writeFile('output.png', result);
// From URL
const result = await removeBackground('https://example.com/image.jpg');
// From Buffer
const imageBuffer = await readFile('./image.jpg');
const result = await removeBackground(imageBuffer);Browser
<!DOCTYPE html>
<html>
<body>
<input type="file" id="upload" accept="image/*">
<img id="result">
<script type="module">
import { removeBackground } from 'isnet-background-removal';
document.getElementById('upload').addEventListener('change', async (e) => {
const file = e.target.files[0];
const blob = await removeBackground(file);
document.getElementById('result').src = URL.createObjectURL(blob);
});
</script>
</body>
</html>API
removeBackground(image, config?)
Removes the background from an image.
Parameters:
image: Image source- Node.js:
string(file path or URL),Buffer, orUint8Array - Browser:
string(URL),Blob,File,HTMLImageElement,ImageData, orImageBitmap
- Node.js:
config(optional): Configuration object
Returns:
- Node.js:
Promise<Buffer>- PNG image buffer - Browser:
Promise<Blob>- PNG image blob
Configuration Options
All options are optional:
{
modelUrl?: string; // Custom model URL (defaults to bundled ISNet model)
publicPath?: string; // Path to ONNX Runtime WASM files (browser only)
numThreads?: number; // Number of threads (default: 1)
debug?: boolean; // Enable debug logging
device?: 'cpu' | 'webgl' | 'wasm'; // Execution device (browser only)
}Example with options:
const result = await removeBackground(image, {
publicPath: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/',
numThreads: 1,
debug: true
});Examples
Node.js Demo
Run the included Node.js demo:
npm run demo:node [image-path-or-url]Example:
npm run demo:node https://images.unsplash.com/photo-1574158622682-e40e69881006?w=800Browser Demo
Open examples/browser-demo.html in your browser to try the interactive demo with drag-and-drop support.
How It Works
- Image Loading: Loads the input image from various sources
- Preprocessing: Resizes image to 1024×1024 (ISNet input size)
- Inference: Runs the ISNet model to generate a segmentation mask
- Postprocessing: Applies the mask as an alpha channel to create transparency
- Output: Returns a PNG image with transparent background
Troubleshooting
Node.js Issues
Error: Canvas/Sharp installation failed
These packages require native compilation. Make sure you have:
- Python 3.x
- C++ build tools (Visual Studio on Windows, Xcode on macOS, build-essential on Linux)
Error: Cannot find module
Make sure you're using ES modules. Add "type": "module" to your package.json or use .mjs file extension.
Browser Issues
CORS errors
When loading images from URLs, ensure the server sends proper CORS headers.
WASM loading errors
If you see WASM loading errors, specify the publicPath option:
await removeBackground(image, {
publicPath: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/'
});SharedArrayBuffer errors
If you see SharedArrayBuffer errors, either:
- Set
numThreads: 1in the config (recommended) - Configure your server with COOP/COEP headers
Performance Tips
- First run is slower: Model loading and WASM initialization happen on first use
- Reuse the session: The model session is cached automatically
- Optimize image size: Smaller images process faster (they're resized to 1024×1024 anyway)
- Use appropriate threads: In browsers, use
numThreads: 1to avoid COOP/COEP requirements
Model
This package uses the ISNet (Intermediate Supervision Network) model, which provides high-quality salient object detection for background removal.
License
MIT
Credits
- ISNet model: DIS (Dichotomous Image Segmentation)
- ONNX Runtime: Microsoft ONNX Runtime