BiRefNet
The bilateral reference matting model — config, forward, and its methods.
from nobg import BiRefNet
from nobg.birefnet.modeling_birefnet import BiRefNetConfigBilateral Reference Network for high-resolution dichotomous image segmentation
(arXiv:2401.03407), with a Swin backbone from transformers.
feyninc/FeyNobg is the published checkpoint.
BiRefNetConfig
A plain dataclass; every field has a default, so BiRefNet() is valid (randomly initialized). It is
serialized verbatim to config.json.
Prop
Type
__post_init__ raises if depths or num_heads disagree with num_layers.
model = BiRefNet(BiRefNetConfig(image_size=512, embed_dim=128))forward
forward(pixel_values: Tensor, labels: Tensor | None = None) -> dictProp
Type
Returns:
| Key | Shape | Notes |
|---|---|---|
logits | (B, 1, H, W) | Raw alpha-matte logits — the final decoder scale, not sigmoided |
intermediate_logits | list of (B, 1, h, w) | The earlier decoder scales, used by the multi-scale loss |
loss | scalar | Only when labels was passed; computed by model.criterion |
Unlike SAM3, forward accepts no prompt and no boxes.
predict
predict(processor, image, *, batch_size=1, return_type="cutout", **processor_kwargs)The full preprocess → forward → post-process → composite pipeline, under no_grad in eval mode on the
model's own device and dtype. A single image returns a single result; a list returns a list, each at its
original resolution.
processor must be a BiRefNetImageProcessor. BiRefNet's signature stops at image — passing a third
positional argument is a TypeError.
See Removing a background for the full argument table.
process
process(image, *, batch_size=1, return_type="cutout", **processor_kwargs)predict with the processor default_processor() describes. Everything else is forwarded unchanged.
default_processor
default_processor() -> BiRefNetImageProcessorBuilds BiRefNetImageProcessor(size={"height": config.image_size, "width": config.image_size}).
BiRefNet's preprocessing is fully determined by the config, so this needs nothing from the Hub — it
mirrors AutoProcessor's fallback for repos without a preprocessor_config.json.
from_origin
@classmethod
from_origin(origin, config=None, *, token=None, **overrides) -> BiRefNetBuilds a possibly re-parameterized model from an existing one, injecting every weight whose (remapped) key and shape still match. Understands both the current key layout and the pre-0.2.0 custom-Swin layout. See Hub round-trips.
criterion
model.criterion = my_loss # (scaled_preds: list[Tensor], gt: Tensor) -> TensorDefaults to nobg.loss.birefnet_loss. It is a plain function attribute, not a submodule, so it never
enters the state dict and can be replaced outright. See Losses.
Inherited
From Revised_Mixin (PyTorchModelHubMixin + Onnx_Mixin):
save_pretrained,from_pretrained,push_to_hub— the last auto-prefixes a barerepo_idwith your Hub username and injects the generated model cardonnx_save_pretrained,onnx_push_to_hub,onnx_from_pretrained,onnx_dummy_inputs— see ONNX
onnx_dynamo is True for BiRefNet: the torch.export path is required, because torchvision no
longer registers an ONNX symbolic for deform_conv2d.