| --- |
| license: mit |
| library_name: onnx |
| tags: |
| - onnx |
| - image-segmentation |
| - background-removal |
| - birefnet |
| pipeline_tag: image-segmentation |
| --- |
| |
| # BiRefNet_lite — browser-tuned ONNX export (static 1024², opset 17) |
| |
| Custom ONNX export of **BiRefNet_lite** (bilateral reference network for |
| dichotomous image segmentation, Swin-v1-tiny backbone) from the official |
| [ZhengPeng7/BiRefNet_lite](https://huggingface.co/ZhengPeng7/BiRefNet_lite) |
| weights, re-hosted for [AllPrivate](https://allprivate.app) — where every model |
| runs in the visitor's browser and nothing is uploaded. |
| |
| ## Why a custom export |
| |
| The community export ([onnx-community/BiRefNet_lite-ONNX](https://huggingface.co/onnx-community/BiRefNet_lite-ONNX)) |
| throws `OrtRun std::bad_alloc` in ONNX Runtime Web on every EP (fp32/fp16 × |
| wasm/webgpu, tested 2026-07 on an M-series MacBook): it is a dynamic-shape |
| trace whose deformable convolutions decompose into GatherND/ScatterND/Clip |
| chains that fall back to CPU on the WebGPU EP and materialize im2col tensors of |
| hundreds of MB inside the 32-bit wasm heap. |
|
|
| This export replaces `DeformableConv2d.forward` with a numerically identical |
| per-kernel-tap **GridSample** decomposition (one bilinear GridSample + 1×1 Conv |
| per tap, accumulated — peak extra memory is one `[1,C,H,W]` tensor per tap) and |
| traces with a **static** input shape, so all shape dynamism constant-folds |
| away. It runs to completion on both the wasm and WebGPU execution providers of |
| ONNX Runtime Web (verified 1.26-dev). |
|
|
| ## Provenance |
|
|
| - Source weights: [`model.safetensors`](https://huggingface.co/ZhengPeng7/BiRefNet_lite/blob/main/model.safetensors) |
| at pinned revision [`7838f1c`](https://huggingface.co/ZhengPeng7/BiRefNet_lite/tree/7838f1c3472f827cd8ce13ab5ccc2ce48077360f) |
| - sha256: `4417d89795250e698c3cb0ae8df15743810065f646f48a694fdfa7ca052d0815` |
| - Exported with `torch.onnx.export` (PyTorch 2.8.0, TorchScript exporter), |
| opset 17, fp32, constant folding on, post-processed with onnxslim 0.1.94 |
| (constant-folds the Swin attention-mask construction; Gemm fusion disabled) |
| plus a content-hash initializer dedupe (the backbone is traced twice for the |
| multi-scale 'cat' input) — see [`export_birefnet_lite.py`](./export_birefnet_lite.py) |
| for the exact reproducible script |
| - I/O: `input_image` `[1, 3, 1024, 1024]` (NCHW, RGB, float32, ImageNet |
| normalization: `(x/255 - mean) / std`, mean `[0.485, 0.456, 0.406]`, std |
| `[0.229, 0.224, 0.225]`) → `output_image` `[1, 1, 1024, 1024]` **logits**; |
| apply sigmoid for the [0,1] matte |
| - Graph ops: `Add, BatchNormalization, Concat, Conv, Div, Erf, Gather, |
| GlobalAveragePool, GridSample, LayerNormalization, MatMul, Mul, Pad, Relu, |
| Reshape, Resize, Shape, Sigmoid, Slice, Softmax, Transpose, Unsqueeze` — |
| no GatherND, no ScatterND, no Clip |
| - Validated against the unpatched PyTorch reference (torchvision |
| `deform_conv2d`): GridSample decomposition max abs dev `3.1e-5` vs |
| torchvision; full-model ONNX (onnxruntime CPU) max abs logits dev `1.0e-4`, |
| max post-sigmoid dev `1.3e-9` |
| - File sha256: `50a57872cc739192446da2a934159f957c81af8b5a161dfda8e3daa51660ca67` |
|
|
| ## License |
|
|
| MIT, inherited from [BiRefNet](https://github.com/ZhengPeng7/BiRefNet/blob/main/LICENSE) |
| (© Zheng Peng et al.). This repo only re-packages the officially released |
| weights in ONNX form. |
|
|
| ## Citation |
|
|
| ```bibtex |
| @article{BiRefNet, |
| 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}, |
| year = {2024} |
| } |
| ``` |
|
|
