@pixir/background-remover

Client-side AI background removal with hair & edge refinement for the browser.
Powered by the native Pixir.in engine using Bria AI RMBG-1.4 and ONNX Runtime Web.
100% private, zero server calls, zero backend infrastructure costs.

✨ Features

• 🚀 100% Client-Side Execution: Runs entirely in the user's browser using WebGPU or WASM SIMD. Images never leave the client device.
• 💇 Hair & Edge Refinement (Guided Filter): Preserves delicate flyaway hair, animal fur, translucent lace, and fine contours using sub-pixel bilinear interpolation and high-speed edge matting.
• 🛡️ No AGPL Copyleft License: Does not use @imgly/background-removal (AGPL-3.0). The wrapper code is cleanly MIT-licensed.
• ⚡ Near-Instant GPU Acceleration: Automatically leverages WebGPU hardware acceleration on supported devices, with seamless fallback to CPU WebAssembly (WASM SIMD).
• 📦 Zero-Config Cross-Origin Compatibility: Operates without requiring restrictive Cross-Origin-Opener-Policy (COOP) or Cross-Origin-Embedder-Policy (COEP) server headers.
• 💾 Intelligent Model Caching: Model weights (~42.3 MB) are downloaded once from CDN and stored in the browser CacheStorage (pixir-model-cache), ensuring instantaneous loads on subsequent visits.
• 🔄 Singleton Session Lifecycle: Reuses ONNX inference sessions in memory across multiple image removals with instant teardown (disposeSession()).
• 🎯 Universal Input Support: Accepts File, Blob, HTMLImageElement, HTMLCanvasElement, ImageBitmap, ImageData, ArrayBuffer, or URL strings.

📦 Installation

npm install @pixir/background-remover onnxruntime-web

Note: onnxruntime-web is a peer dependency (^1.21.0). Installing it directly ensures your application controls the exact ONNX runtime version without duplicate bundler copies.

If using yarn or pnpm:

yarn add @pixir/background-remover onnxruntime-web
# or
pnpm add @pixir/background-remover onnxruntime-web

🚀 Quick Start

1. Basic Usage (Vanilla JavaScript / TypeScript)

import { removeBackground } from "@pixir/background-remover";

// Direct file input (e.g. from <input type="file" /> or drag-and-drop)
const file = event.target.files[0];

const resultBlob = await removeBackground(file, {
  progress: (info) => {
    console.log(`${info.stage} (${Math.round(info.progress * 100)}%): ${info.message}`);
  }
});

// Display or download transparent PNG
const url = URL.createObjectURL(resultBlob);
const img = document.createElement("img");
img.src = url;
document.body.appendChild(img);

2. React 18 / Next.js Integration

import React, { useState } from 'react';
import { removeBackground } from '@pixir/background-remover';

export function BackgroundRemovalButton() {
  const [outputUrl, setOutputUrl] = useState<string | null>(null);
  const [progress, setProgress] = useState(0);
  const [isProcessing, setIsProcessing] = useState(false);

  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setIsProcessing(true);
    try {
      const blob = await removeBackground(file, {
        device: 'auto', // Tries WebGPU first, then WASM
        refineEdges: true,
        progress: (info) => setProgress(Math.round(info.progress * 100))
      });

      setOutputUrl(URL.createObjectURL(blob));
    } catch (err) {
      console.error('Failed to remove background:', err);
    } finally {
      setIsProcessing(false);
    }
  };

  return (
    <div>
      <input type="file" accept="image/*" onChange={handleUpload} disabled={isProcessing} />
      {isProcessing && <p>Processing: {progress}%</p>}
      {outputUrl && <img src={outputUrl} alt="Cutout" />}
    </div>
  );
}

📖 API Reference

removeBackground(input, options?): Promise<Blob>

Main pipeline function. Decodes the input, executes segmentation, refines edges, and returns a transparent Blob (image/png or image/webp).

const blob = await removeBackground(imageSource, options);

removeBackgroundToCanvas(input, options?): Promise<HTMLCanvasElement>

Processes the image and draws the resulting transparent cutout onto an in-memory HTMLCanvasElement. Ideal for canvas pipelines, photo editors, and graphics tools.

const canvas = await removeBackgroundToCanvas(imageSource, options);
document.body.appendChild(canvas);

removeBackgroundToImageData(input, options?): Promise<ImageData>

Returns the raw pixel array wrapped in an ImageData object (RGBA channels, 0-255). Useful for custom WebGL shaders, filters, or composite masks.

const imageData = await removeBackgroundToImageData(imageSource, options);
console.log(imageData.width, imageData.height, imageData.data);

preloadModel(options?): Promise<void>

Downloads model weights into the browser cache and warms up the ONNX session in advance (e.g. on application splash screen or idle time) so the first user cutout executes immediately.

import { preloadModel } from "@pixir/background-remover";

// Warm up model in the background
await preloadModel({
  device: 'auto',
  progress: (info) => console.log('Warming model:', info.message)
});

disposeSession(): Promise<void>

Releases memory and GPU execution resources associated with the active ONNX session. Recommended when unmounting editor pages.

import { disposeSession } from "@pixir/background-remover";

await disposeSession();

⚙️ Configuration Options

RemoveBackgroundOptions

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | device | 'auto' \| 'webgpu' \| 'wasm' | 'auto' | Hardware execution provider. 'auto' attempts WebGPU first, falling back cleanly to multi-threaded/single-threaded WASM SIMD. | | modelPath | string | Hugging Face CDN | Custom URL or path to self-hosted rmbg_quantized.onnx file. | | wasmPath | string | jsDelivr CDN | Custom URL or path for onnxruntime-web WASM binaries. | | refineEdges | boolean | true | Runs edge-preserving guided filtering to extract hair, fur, and delicate contours. | | refinementOptions| RefinementOptions | {} | Fine-tuning options for edge matting (see table below). | | outputType | 'image/png' \| 'image/webp' | 'image/png' | Desired output MIME format. | | quality | number | 0.95 | Compression quality for lossy formats like image/webp (0.0 to 1.0). | | progress | (info: ProgressInfo) => void | undefined | Granular callback reporting stage, percentage, and status message. | | signal | AbortSignal | undefined | Allows canceling download or inference at any time via AbortController. |

RefinementOptions

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | radius | number | 3 | Box blur radius for the guided filter. | | eps | number | 0.001 | Regularization parameter balancing edge sharpness and smoothing. | | fgThreshold | number | 0.95 | Probability above which pixels are locked to 100% opaque alpha (255), resolving the 254 ceiling bug. | | bgThreshold | number | 0.03 | Probability below which pixels are clamped to 100% transparent (0). | | defringe | boolean | true | Suppresses color halo artifacts on semi-transparent boundary pixels without modifying solid interior colors. |

📊 Progress Reporting

The progress callback receives detailed status updates across all pipeline stages:

interface ProgressInfo {
  stage: 'downloading-model' | 'initializing-model' | 'preprocessing' | 'inference' | 'refining' | 'complete';
  progress: number; // 0.0 to 1.0
  message: string;
}

await removeBackground(file, {
  progress: ({ stage, progress, message }) => {
    console.log(`[${stage}] ${Math.round(progress * 100)}% - ${message}`);
  }
});

🛠️ Error Handling

The package exports PixirError with machine-readable error codes:

import { removeBackground, PixirError } from "@pixir/background-remover";

try {
  const result = await removeBackground(file);
} catch (error) {
  if (error instanceof PixirError) {
    switch (error.code) {
      case 'UNSUPPORTED_ENVIRONMENT':
        console.error('DOM Canvas or WebAssembly unavailable');
        break;
      case 'WEBGPU_NOT_SUPPORTED':
        console.error('WebGPU requested but unsupported; try device: "wasm"');
        break;
      case 'MODEL_DOWNLOAD_FAILED':
        console.error('Network failure loading model weights');
        break;
      case 'ABORTED':
        console.log('Operation was canceled by user');
        break;
      case 'INVALID_INPUT':
        console.error('Corrupt image or CORS violation');
        break;
      default:
        console.error(error.code, error.message);
    }
  }
}

🏢 Self-Hosting & Offline Deployments

For intranet, offline, or enterprise applications that restrict external CDN requests:

1. Download the quantized model file:

   curl -L -o public/models/rmbg_quantized.onnx \
     "https://huggingface.co/briaai/RMBG-1.4/resolve/main/onnx/model_quantized.onnx"

2. Copy ONNX Runtime Web WASM binaries into your static assets directory:

   cp -r node_modules/onnxruntime-web/dist/*.wasm public/wasm/

3. Configure paths in removeBackground:

   const result = await removeBackground(file, {
     modelPath: '/models/rmbg_quantized.onnx',
     wasmPath: '/wasm/'
   });

⚖️ Licensing & Legal Compliance

This project maintains strict license separation between the open-source software wrapper and the deep learning model weights:

1. Package Source Code: Distributed under the MIT License.
   Free to use, modify, merge, publish, distribute, sublicense, and sell.

2. Neural Model Weights (BRIA AI RMBG-1.4):

   • Authored by BRIA AI.
   • Distributed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) license.
   • Non-commercial & research use is permitted for free.
   • Commercial production use requires obtaining a commercial license directly from BRIA AI (bria.ai/contact-us).

🌐 Powered By

• Web Studio: Pixir.in
• Model Architecture: Bria AI RMBG-1.4
• Runtime: ONNX Runtime Web