Foreground/background separation — "remove the background from this image".
Two entry points cover different use cases:
remove/2— returns the input image with the foreground mask applied as an alpha channel. The background becomes transparent. Useful when you want a cutout you can drop onto another background or save as a transparent PNG.mask/2— returns the foreground mask itself as a single-bandVix.Vips.Image.t/0(white = foreground, black = background). Useful when you want to do your own compositing.
This is class-agnostic salient-object detection: the model
decides what is "the subject" of the image and separates it from
the rest. For a class-labeled segmentation use
Image.Segmentation.segment_panoptic/2 instead; for promptable
per-object segmentation use Image.Segmentation.segment/2.
Quick start
iex> image = Image.open!("./test/support/images/puppy.webp")
iex> {:ok, cutout} = Image.Background.remove(image)Default model
BiRefNet lite — MIT licensed, ~210 MB. Current state-of-the-art for salient object detection / dichotomous image segmentation, distilled into a smaller variant suitable for general use.
Override via :repo and :model_file to use the full BiRefNet
or another compatible export.
Optional dependency
This module is only available when Ortex
is configured in your application's mix.exs.
Summary
Functions
@spec mask(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t()
Computes a foreground mask for an image.
Returns a single-band greyscale image at the original dimensions where pixel intensity reflects the model's confidence that the pixel belongs to the foreground.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:repois the HuggingFace repository for the BiRefNet ONNX export. The default is"onnx-community/BiRefNet_lite-ONNX".:model_fileis the ONNX filename within the repo. The default is"onnx/model.onnx".
Returns
- A single-band
Vix.Vips.Image.t/0at the input image's width and height. Pixel values are in[0, 255]where higher values are more confidently foreground.
Examples
iex> image = Image.open!("./test/support/images/puppy.webp")
iex> mask = Image.Background.mask(image)
iex> {Image.width(mask), Image.height(mask)} == {Image.width(image), Image.height(image)}
true@spec remove(Vix.Vips.Image.t(), Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, Image.error()}
Removes the background from an image.
Computes a foreground mask and returns the input image with that mask applied as the alpha channel. Background pixels become transparent.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:repois the HuggingFace repository for the BiRefNet ONNX export. The default is"onnx-community/BiRefNet_lite-ONNX".:model_fileis the ONNX filename within the repo. The default is"onnx/model.onnx".
Returns
{:ok, cutout}wherecutoutis aVix.Vips.Image.t/0with the foreground only and a soft alpha channel reflecting the model's confidence at the boundaries, or{:error, reason}.
Examples
iex> image = Image.open!("./test/support/images/puppy.webp")
iex> {:ok, cutout} = Image.Background.remove(image)
iex> Image.has_alpha?(cutout)
true