Hugging Face's logo

PinkPixel
/
fey-nobg-onnx

Image Segmentation
ONNX
nobg
background-removal
image-matting
onnxruntime
feynobg
soft-alpha
transparency
rgba
Model card Files
xet
 Community
fey-nobg-onnx / README.md
sizzlebop's picture
sizzlebop
Upload 5 files
223f80f verified
preview code
|
Raw History Blame Contribute Delete
6.92 kB
metadata 
license: apache-2.0
pipeline_tag: image-segmentation
base_model: feyninc/FeyNobg
tags:
  - background-removal
  - image-matting
  - image-segmentation
  - onnx
  - onnxruntime
  - nobg
  - feynobg
  - soft-alpha
  - transparency
  - rgba
library_name: 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

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.