> This is the documentation for LibreYOLO 1.5.0. Current version: https://www.libreyolo.com/docs/models/birefnet

# BiRefNet
A bilateral-reference network that predicts a soft alpha matte separating a subject from its background. LibreYOLO ships inference and validation for BiRefNet's matte task.
Tasks: matte. Install: pip install libreyolo.
Verified against LibreYOLO v1.5.0.

## Install

BiRefNet needs no optional extra. Everything it imports is in the base
install.

```bash
pip install libreyolo
```

## Predict

Weights download from Hugging Face on first use and are cached locally.

**Python**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreBiRefNetl-matte.pt")
result = model(SAMPLE_IMAGE, save=True)

matte = result.matte
print(matte.array.shape, matte.array.dtype)
```

**CLI**

```bash
libreyolo predict model=LibreBiRefNetl-matte.pt source=https://raw.githubusercontent.com/LibreYOLO/libreyolo/release/libreyolo/assets/parkour.jpg save=True
```

**Cutout**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

model = LibreYOLO("LibreBiRefNetl-matte.pt")
result = model(SAMPLE_IMAGE)

# RGBA (H, W, 4) uint8: source RGB plus the matte as an alpha channel.
rgba = result.cutout()
result.save("subject.png")
```

A matte result carries no boxes; `result.matte` is a dense `(H, W)`
float32 array in `[0, 1]`, 1 fully foreground and 0 fully background. Unlike a
binary mask, the soft matte keeps anti-aliased edge detail such as hair and
fur. `result.cutout()` composites the source image with that alpha channel
into an RGBA array, and `result.save(path)` (or `save=True` on the predict
call) writes it straight to a transparent-background PNG. The model runs at a
fixed native 1024x1024 canvas; a different resolution is not supported,
because the Swin backbone's relative-position tables are tied to it, and a
mismatch interpolates them badly rather than raising an error. See
[prediction](/docs/v1.5.0/predict) for sources, streaming and result handling.

## Variants

One published checkpoint, `l`, the Swin-L tier BiRefNet-general model and the
quality default upstream. The family's code also supports a Swin-T lite tier,
`t`, but no LibreYOLO conversion of it is published yet.

## Validate

`val()` reports two metrics over a paired image/matte folder, both in
`[0, 1]` and independent of resolution: MAE, the mean absolute error against
the ground-truth alpha (lower is better), and S-measure (Fan et al., ICCV
2017), a structural similarity that credits preserving the subject's shape and
holes, which pixel MAE alone misses (higher is better). Validation drives the
model's own `predict`, so it uses the family's exact preprocessing.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreBiRefNetl-matte.pt")

# A directory containing images/ and an auto-detected matte directory
# (mattes/, matte/, gt/, masks/, mask/ or alpha/) also works in place
# of a dataset YAML.
metrics = model.val(data="my-matte-dataset/")

print(metrics["metrics/MAE"])
print(metrics["metrics/Smeasure"])
```

Validation is inference-only; fine-tuning is a documented follow-up rather
than a shipped feature (see Predict for the exact resolution constraint that
any future trainer would inherit).

## Export

| Task | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | ncnn | TFLite | CoreML | Core AI |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| matte | yes | yes |  |  |  |  |  |  |  |  |  |  |

A "yes" means the export is supported. An empty cell means the exporter refuses that combination.

An exported artifact loads back through `LibreYOLO()` on its file suffix, so a
`.onnx` file behaves like a checkpoint and returns the same `Results`.
TorchScript is the validated path; ONNX conversion runs but has not cleared
the same parity bar. [Export](/docs/v1.5.0/export) lists the arguments every format
accepts and the extras a few of them add.

**Python**

```python
from libreyolo import LibreYOLO

model = LibreYOLO("LibreBiRefNetl-matte.pt")
model.export(format="onnx")
```

**CLI**

```bash
libreyolo export model=LibreBiRefNetl-matte.pt format=onnx
```

**Use the exported file**

```python
from libreyolo import LibreYOLO, SAMPLE_IMAGE

# The factory routes on the file suffix, so an exported artifact loads
# like any checkpoint and returns the same Results object.
model = LibreYOLO("LibreBiRefNetl-matte.onnx")
result = model(SAMPLE_IMAGE)

print(result.matte.array.shape)
```

## Checkpoints

Every published weight file for this family.

| File | Input (px) | Task | Weights license |
| --- | --- | --- | --- |
| `LibreBiRefNetl-matte.pt` |  | matte | mit |

## Licensing

Check the license on the Hugging Face repository of the specific weights you download. That repository is authoritative and licenses are not always uniform across a family. This is a description of the licenses involved, not legal advice.

- Original work: BiRefNet, Nankai University
- Upstream license: MIT
- Upstream source: https://github.com/ZhengPeng7/BiRefNet
- LibreYOLO code: MIT
- Weights: MIT, republished at https://huggingface.co/LibreYOLO
- Interpretation: MIT is a permissive license, so these weights can be used in commercial and closed-source products. The one standing obligation is to keep the license text and copyright notice with any copy you redistribute. It places no condition on your own application code. LibreYOLO's checkpoint is a format conversion of the official pretrained BiRefNet-general weights (the Swin-L, quality-default tier), with the learned parameters unchanged; fine-tuning is not wired into this library in v1, so there is no LibreYOLO-trained variant to license separately.

## Citation

```bibtex
@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}
}
```

Copied from https://github.com/ZhengPeng7/BiRefNet#citation


## BiRefNet architecture

- t: [SVG](/diagrams/models/birefnet/t-matte.svg), [interactive diagram](/diagrams/models/birefnet/t-matte.html)
- l: [SVG](/diagrams/models/birefnet/l-matte.svg), [interactive diagram](/diagrams/models/birefnet/l-matte.html)
- Shared dual-scale topology: [SVG](/diagrams/models/birefnet/family.svg), [interactive diagram](/diagrams/models/birefnet/family.html)