PinkPixel/lucida-onnx

Lucida ONNX: Soft-Alpha Background Removal and Image Matting

This repository provides a self-contained ONNX export of Lucida, a high-resolution background removal and soft-alpha matting model fine-tuned by Ege Orcun.

Lucida builds on the BiRefNet HR architecture, addressing common failure modes in open background removal models: camouflaged subjects, semi-transparent surfaces (glass, liquids, veils), fine text and typography, VFX glows, and layered illustrations.

Model Summary

Property	Details
Original Model	egeorcun/lucida
Original Code	github.com/egeorcun/lucida
Base Architecture	BiRefNet HR (ZhengPeng7/BiRefNet_HR)
Primary Task	Background removal, salient matting, soft-alpha extraction
Weights Checkpoint	Lucida v7 weights
Format	ONNX (self-contained model weights)
File Size	~932 MB (model.onnx)
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 (Upstream Lucida and BiRefNet are MIT)

Benchmark Highlights

According to the author's 203-image, 9-category benchmark (Mean Absolute Error, lower is better), Lucida v7 delivers high accuracy across challenging segmentation categories:

• Camouflage (0.0270 MAE): Accurate separation when foreground subjects closely match background textures and tones.
• Illustration and Artwork (0.0092 MAE): Preserves crisp line art and multi-layered compositions.
• Text and Logo Preservation (0.0091 MAE): Retains typography without eroded letterforms or missing holes in glyphs.
• Print and Sticker Art (0.0235 MAE): Clean boundaries around designs intended for apparel and print graphics.
• Transparency and Glass: Accurately extracts soft alpha transitions through semi-transparent materials and atmospheric effects.
• Overall Average (0.0257 MAE): Outperformed both specialist open source baselines and commercial references across the 203-image evaluation set.

For the full benchmark gallery, test sets, and evaluation scripts, visit the upstream GitHub repository.

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
session = ort.InferenceSession("model.onnx", providers=["CPUExecutionProvider"])
# The output is already passed through Sigmoid inside the 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 Lucida Model: Developed and published by Ege Orcun.
  • Hugging Face: egeorcun/lucida
  • GitHub: github.com/egeorcun/lucida
  • Interactive Demo: Hugging Face Space
• Base Architecture: BiRefNet (Peng Zheng).
• Illustration Training Data: Includes ToonOut (CC-BY 4.0).
• Research Datasets: Fine-tuning leveraged open research datasets including P3M-10k, COD10K, and DIS5K.

License

The repository structure, scripts, and documentation in this distribution are released under the Apache 2.0 License.

Upstream Lucida weights and code are released under the MIT License. Upstream BiRefNet architecture and base weights are released under the MIT License.