PinkPixel/fey-nobg-onnx

FeyNobg ONNX: Production Background Removal and Soft-Alpha Matting

This repository provides a self-contained ONNX export of FeyNobg, a high-quality background removal and soft-alpha matting model developed by Feyn Inc and powered by the nobg library.

FeyNobg utilizes a BiRefNet backbone optimized for production workflows, offering clean foreground isolation, fine edge matting, and natural transparency across portraits, product photography, apparel, and graphic assets.

Model Summary

Property	Details
Original Model	feyninc/FeyNobg
Original Library	github.com/feyninc/nobg
Upstream Organization	Feyn Inc
Architecture Base	BiRefNet
Primary Task	Background removal, salient matting, soft-alpha extraction
Native Resolution	1024x1024
Format	ONNX (self-contained model weights)
Available Variants	FP32 (1.1 GB), FP16 (538 MB), INT8 (1.2 GB), UINT8 (1.2 GB), Q4 (1.2 GB)
Input Tensor	image: [1, 3, 1024, 1024] (Float32, ImageNet normalized RGB)
Output Tensor	alpha: [1, 1, 1024, 1024] (Float32, Sigmoid activated, range [0.0, 1.0])
Supported Execution Providers	CPU, CUDA, DirectML, CoreML, WebGPU
License	Apache 2.0

Available Quantizations

File	Precision	File Size	Recommended Runtime	Notes
model.onnx	Float32	1064 MB (1.1 GB)	High-precision reference	Base unquantized model
model_fp16.onnx	Float16	538 MB	CUDA, WebGPU, Apple Silicon, DirectML	Recommended. Halves memory footprint and accelerates 2D convolutions with zero loss in alpha detail
model_int8.onnx	Dynamic INT8	1223 MB	CPU servers	Quantizes linear projection layers
model_uint8.onnx	Dynamic UINT8	1222 MB	Specific CPU runtimes	Unsigned 8-bit dynamic quantization
model_q4.onnx	4-bit block-wise	1184 MB	Edge memory	MatMul 4-bit weight packing

Model Highlights

• Production Soft-Alpha Matting: Generates continuous grayscale alpha values rather than harsh binary cutouts, cleanly resolving flyaway hair, glass, fine fur, and translucent fabrics.
• Self-Contained ONNX Weights: Runs directly with ONNX Runtime across CPU, GPU (CUDA / DirectML), and edge runtimes without requiring PyTorch, transformers, or the nobg Python library.
• Balanced Generalization: Tuned for e-commerce, studio portraits, design cutouts, and challenging lighting environments.

Quickstart (Python)

1. Install Dependencies

pip install onnxruntime pillow numpy
# Or for NVIDIA GPU acceleration:
# pip install onnxruntime-gpu pillow numpy

2. Run Background Removal

import numpy as np
import onnxruntime as ort
from PIL import Image

# 1. Load source image
img = Image.open("input.jpg").convert("RGB")
orig_w, orig_h = img.size

# 2. Resize to 1024x1024 and apply ImageNet normalization
resized = img.resize((1024, 1024), Image.Resampling.BILINEAR)
arr = np.array(resized, dtype=np.float32) / 255.0

mean = np.array([0.485, 0.456, 0.406], dtype=np.float32)
std = np.array([0.229, 0.224, 0.225], dtype=np.float32)
norm = (arr - mean) / std

# 3. Format tensor to shape [1, 3, 1024, 1024]
tensor = np.transpose(norm, (2, 0, 1))[np.newaxis, ...].astype(np.float32)

# 4. Run ONNX inference (use model_fp16.onnx for GPU acceleration)
session = ort.InferenceSession("model_fp16.onnx", providers=["CUDAExecutionProvider", "CPUExecutionProvider"])
# The output tensor already contains Sigmoid activation within the ONNX graph
alpha_raw = session.run(["alpha"], {"image": tensor})[0]

# 5. Extract alpha, clamp, and resize to original image dimensions
alpha_2d = np.squeeze(alpha_raw)
alpha_uint8 = (np.clip(alpha_2d, 0.0, 1.0) * 255.0).round().astype(np.uint8)
alpha_mask = Image.fromarray(alpha_uint8, mode="L").resize(
    (orig_w, orig_h), Image.Resampling.BILINEAR
)

# 6. Compose transparent RGBA image and save
cutout = img.convert("RGBA")
cutout.putalpha(alpha_mask)
cutout.save("output.png")

Command-Line Usage

This repository includes a standalone CLI utility: infer.py.

Single Image

# Generate transparent cutout (output defaults to <name>_cutout.png)
python infer.py --image photo.jpg

# Specify custom output path
python infer.py --image photo.jpg --output cutout.png

# Run on GPU via CUDA
python infer.py --image photo.jpg --provider cuda

# Save only the grayscale alpha matte mask
python infer.py --image photo.jpg --mask-only --output mask.png

Batch Processing

# Process all supported images in a directory
python infer.py --dir ./input_images --output-dir ./cutouts

# Save only masks in batch mode
python infer.py --dir ./input_images --output-dir ./masks --mask-only

Technical Details

Input Specification

• Name: image
• Shape: [1, 3, 1024, 1024]
• Data Type: Float32
• Color Order: RGB
• Normalization: ImageNet statistics
  • Mean: [0.485, 0.456, 0.406]
  • Standard Deviation: [0.229, 0.224, 0.225]
  • Formula: (pixel_value / 255.0 - mean) / std

Output Specification

• Name: alpha
• Shape: [1, 1, 1024, 1024]
• Data Type: Float32
• Activation: Sigmoid (values are in range [0.0, 1.0])
  • 0.0: Definite background
  • 1.0: Definite foreground
  • 0.0 < alpha < 1.0: Soft edges, hair, glass, or translucent features

Upstream Attribution

• Original Model & Library: Developed by Feyn Inc.
  • Hugging Face Model: feyninc/FeyNobg
  • GitHub Repository: github.com/feyninc/nobg
  • FeyNobg Technical Blog: usefeyn.com/blog/feynobg
  • Hugging Face Announcement: huggingface.co/blog/feyninc/feynobg
• Base Architecture Reference: BiRefNet (ZhengPeng7/BiRefNet).

Citation

@article{zheng2024birefnet,
  title={Bilateral Reference for High-Resolution Dichotomous Image Segmentation},
  author={Zheng, Peng and Gao, Dehong and Fan, Deng-Ping and Liu, Li and Laaksonen, Jorma and Ouyang, Wanli and Sebe, Nicu},
  journal={CAAI Artificial Intelligence Research},
  volume={3},
  pages={9150038},
  year={2024},
  url={https://arxiv.org/abs/2401.03407}
}

License

This repository and the upstream FeyNobg model weights are released under the Apache 2.0 License.