Image.BackgroundColor (image v0.72.0)

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.

Summary

Types

spec()

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

Functions

resolve(image, color)

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

Types

spec()

@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.

Functions

resolve(image, color)

@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 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]}