# `Image.Background`
[🔗](https://github.com/elixir-image/image_vision/blob/v0.2.0/lib/background.ex#L2)

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-band
  `t:Vix.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](https://huggingface.co/onnx-community/BiRefNet_lite-ONNX)
— 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](https://hex.pm/packages/ortex)
is configured in your application's `mix.exs`.

# `mask`

```elixir
@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

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

### Options

* `:repo` is the HuggingFace repository for the BiRefNet ONNX
  export. The default is `"onnx-community/BiRefNet_lite-ONNX"`.

* `:model_file` is the ONNX filename within the repo. The default
  is `"onnx/model.onnx"`.

### Returns

* A single-band `t:Vix.Vips.Image.t/0` at 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

# `remove`

```elixir
@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

* `image` is any `t:Vix.Vips.Image.t/0`.

* `options` is a keyword list of options.

### Options

* `:repo` is the HuggingFace repository for the BiRefNet ONNX
  export. The default is `"onnx-community/BiRefNet_lite-ONNX"`.

* `:model_file` is the ONNX filename within the repo. The default
  is `"onnx/model.onnx"`.

### Returns

* `{:ok, cutout}` where `cutout` is a `t:Vix.Vips.Image.t/0`
  with 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

---

*Consult [api-reference.md](api-reference.md) for complete listing*