js-image-bg-remover

High-performance, portable background remover using U-2-Net and onnxruntime-web (WASM). Works in Node.js, serverless, Docker, and browser environments. No native dependencies—just npm install and go!

Features

• 🚀 Fast: WASM inference, much faster than pure JS
• 🖼️ Accurate: Uses U-2-Net for high-quality matting
• 📦 Portable: No native deps, works everywhere Node.js runs
• 🛠️ CLI & API: Use as a CLI or programmatically
• 📊 Benchmarks: Compare with other JS-based removers
• 🧑‍💻 Open source: Easy to contribute and extend

Requirements

• Node.js >= 18.0.0 (for ESM and modern features)
• 2GB+ RAM recommended
• ~200MB disk space for model
• Supported platforms: Linux, macOS, Windows

Installation

1npm install js-image-bg-remover

Ubuntu/Debian Server Setup

If you're running on Ubuntu/Debian server, you'll need these system dependencies:

1# Install required system packages
2sudo apt-get update
3sudo apt-get install -y build-essential libvips libvips-dev
4
5# Optional: For HEIC/AVIF support
6sudo apt-get install -y libheif-dev
7
8# Optional: Set custom model directory for production
9export BG_REMOVER_MODEL_DIR=/path/to/models

Usage

JavaScript (ESM)

1import { removeBackground } from 'js-image-bg-remover';
2
3// Basic usage
4await removeBackground('input.jpg', 'output.png');
5
6// With custom model directory
7await removeBackground('input.jpg', 'output.png', {
8  modelDir: '/path/to/models'
9});
10
11// Process multiple images
12const images = ['img1.jpg', 'img2.jpg', 'img3.jpg'];
13await Promise.all(
14  images.map(img => removeBackground(img, `output_${img}.png`))
15);

JavaScript (CommonJS)

1const { removeBackground } = require('js-image-bg-remover');
2
3async function processImage() {
4  await removeBackground('input.jpg', 'output.png');
5}

TypeScript

1import { removeBackground, RemoveBackgroundOptions } from 'js-image-bg-remover';
2
3// Basic usage with type checking
4await removeBackground('input.jpg', 'output.png');
5
6// With typed options
7const options: RemoveBackgroundOptions = {
8  modelDir: '/custom/models',
9  showProgress: true
10};
11
12await removeBackground('input.jpg', 'output.png', options);
13
14// In an async function with error handling
15async function processImage(input: string, output: string) {
16  try {
17    await removeBackground(input, output);
18    console.log('Background removed successfully');
19  } catch (err) {
20    console.error('Failed to remove background:', err);
21  }
22}

CLI Usage

1# Basic usage
2cleancut input.jpg -o output.png
3
4# Custom model directory
5cleancut input.jpg -o output.png --model-dir /path/to/models
6
7# Process multiple images
8cleancut *.jpg --output-dir ./processed

How it Works

This package uses the U-2-Net model for high-quality background removal:

• Model: U-2-Net - A state-of-the-art deep learning model for salient object detection
• Processing:
  • Downloads U-2-Net ONNX model (~176MB) on first use
  • Preprocesses images to 320x320 tensors
  • Runs WASM inference with onnxruntime-web
  • Postprocesses matte and composites transparent PNG
• Performance: WASM-based inference is significantly faster than pure JS implementations

Benchmarks

Benchmarks are included in the benchmarks/ folder. Run:

1npm run bench

Sample benchmark results:

Size      | Avg (s) | Min (s) | Max (s)
---------|---------|---------|----------
500x500  |    0.8  |    0.7  |    0.9
1024x1024|    1.2  |    1.0  |    1.4
2048x2048|    2.5  |    2.2  |    2.8

Factors affecting performance:

• Image size
• CPU speed
• Available RAM
• Disk speed (for model loading)

Production Tips

1. System Requirements:

   • Node.js >= 14.0.0
   • 2GB+ RAM recommended
   • ~200MB disk space for model

2. Docker Setup:

1FROM node:18
2RUN apt-get update && apt-get install -y \

3    build-essential libvips libvips-dev \
4    && rm -rf /var/lib/apt/lists/*
5ENV BG_REMOVER_MODEL_DIR=/app/models
6VOLUME /app/models

3. Model Storage:

1# Store model in shared location
2export BG_REMOVER_MODEL_DIR=/shared/models

Contributing

We welcome contributions! Here's how you can help:

1. Code Contributions:

   • Fork the repository
   • Create a feature branch
   • Submit a Pull Request

2. Bug Reports:

   • Use the GitHub issue tracker
   • Include sample images when relevant
   • Describe expected vs actual behavior

3. Feature Requests:

   • Open an issue with the "enhancement" label
   • Describe your use case

See CONTRIBUTING.md for detailed guidelines.

License

This project is MIT licensed. See the LICENSE file for details.

Model Attribution

This software uses the U-2-Net model created by Xuebin Qin et al. If you use this software in academic work, please cite:

1@InProceedings{Qin_2020_PR,
2    title = {U2-Net: Going Deeper with Nested U-Structure for Salient Object Detection},
3    author = {Qin, Xuebin and Zhang, Zichen and Huang, Chenyang and Dehghan, Masood and Zaiane, Osmar and Jagersand, Martin},
4    journal = {Pattern Recognition},
5    volume = {106},
6    pages = {107404},
7    year = {2020}
8}

The U-2-Net model is licensed under the Apache-2.0 license. The model weights are automatically downloaded from the official repository.

Author

Sagar Regmi

• GitHub: @sagarregmi2056
• Email: sagarregmi2056@gmail.com

Support

If you find this project helpful, please consider:

• Giving it a star ⭐ on GitHub
• Contributing to its development
• Reporting issues or suggesting features
• Sharing it with others who might find it useful

Links

• GitHub Repository
• Issue Tracker
• npm Package