# `Image.BackgroundColor`
[🔗](https://github.com/elixir-image/image/blob/v0.72.0/lib/image/background_color.ex#L1)

Resolves an `Image.Pixel.t()` / `:average` value into a concrete pixel in the
image's colorspace.

A background color specification is either the atom `:average` (the average
color of the image), or any color accepted by
`Image.Pixel.to_pixel/2` (a `Color` struct, a hex string, a CSS named color,
an atom or a list of numbers).

Either form may also be given as `{spec, alpha: transparency}` to attach an
explicit alpha (an integer `0..255`, a float `0.0..1.0`, or `:opaque` /
`:transparent`). The alpha is applied only when `image` has an alpha band,
otherwise it is dropped, since there is no band to carry it.

In all cases the resolved pixel matches `image`'s number of bands.

# `spec`

```elixir
@type spec() ::
  Image.Pixel.t()
  | :average
  | {Image.Pixel.t() | :average, [{:alpha, Image.Pixel.transparency()}]}
```

A background color specification: the image's average color, or any color, optionally with an explicit alpha.

# `resolve`

```elixir
@spec resolve(Vix.Vips.Image.t(), spec()) ::
  {:ok, [number()]} | {:error, Image.Error.t()}
```

Resolves a background color `spec` into a pixel matching `image`'s
interpretation and band layout.

### Arguments

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

* `spec` is `:average` (the image's average color), any color
  accepted by `Image.Pixel.to_pixel/2`, or either of those wrapped
  as `{spec, alpha: transparency}` to attach an explicit alpha.

### Returns

* `{:ok, [number()]}` - the resolved pixel, whose band count matches
  `image` (an opaque alpha band is appended for `:average` when the
  image has alpha), or

* `{:error, t:Image.Error.t/0}`

### Examples

    iex> image = Image.new!(3, 3, color: :red)
    iex> Image.BackgroundColor.resolve(image, :average)
    {:ok, [255, 0, 0]}
    iex> Image.BackgroundColor.resolve(image, :blue)
    {:ok, [0, 0, 255]}
    iex> Image.BackgroundColor.resolve(image, "#00ff00")
    {:ok, [0, 255, 0]}

---

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