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

`Image` is based upon the fabulous
[vix](https://hex.pm/packages/vix) library that provides a [libvips](https://www.libvips.org)
wrapper for Elixir.

`Image` is intended to provide well-documented common image processing functions in
an idiomatic Elixir functional style as a layer above the very comprehensive set
of functions in `Vix` and `libvips`.

In a very simple image resizing
[benchmark](https://github.com/kipcole9/image/blob/main/bench/image_resize.exs),
`Image` is approximately 2 to 3 times faster than `Mogrify` and uses about 5 times
less memory.

# `from_binary`
*since 0.7.0* 

```elixir
@spec from_binary(
  binary :: binary(),
  options :: Image.Options.Open.image_open_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Returns an image created from an in-memory binary representation
of an image.

The binary must be a complete formatted image such as that
returned from `File.read!/1`.

### Arguments

* `binary` is a binary representation of a formatted image
  including `.jpg`, `.png`, `.webp` and `.svg` binary data.

* `options` is a keyword list of options. See `Image.open/2`
  for the list of applicable options.

> #### Note {: .info}
>
> This function is typically *not* the best way to open
> an image. It requires that the entire image
> is already loaded into memory which, for most use cases,
> doest not scale well and consumes far more memory than
> necessary.
>
> Since `libvips` is a streaming on-demand architecture,
> it is most likely that a simple `Image.open/2` call will
> deliver better resource utilitsation and equal or better
> performance.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

# `from_binary!`
*since 0.25.0* 

```elixir
@spec from_binary!(
  binary :: binary(),
  options :: Image.Options.Open.image_open_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Returns an image created from an in-memory binary representation
of an image or raises an exception.

* `binary` is a binary representation of a formatted image
  including `.jpg`, `.png`, `.webp` and `.svg` binary data.

### Arguments

* `binary` is a binary representation of a formatted image

* `options` is a keyword list of options. See `Image.open/2`
  for the list of applicable options.

### Returns

* `image` or

* raises an exception.

# `from_svg`
*since 0.32.0* 

```elixir
@spec from_svg(svg :: binary(), options :: Image.Options.Open.image_open_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Returns an image created from an SVG string.

### Arguments

* `svg` is an SVG string.

* `options` is a keyword list of options.

### Options

* `:access` is the file access mode, either `:random`
  or `:sequential`. The default is `:random`.
  When `:sequential`, `Image` (via `Vix`) is able
  to support streaming transformations and optimise
  memory usage more effectively. However `:sequential`
  also means that some operations cannot be completed
  because they would require non-sequential access to
  the image. In these cases, `:random` access is required.

* `:fail_on` sets the error level at which image
  loading and decoding will stop. The default is `:none`.
  Each error state implies all the states before it such
  that `:error` implies also `:truncated`.

* `:scale` will scale the image on load. The value is
  a number greater than `0` and less than or equal
  to `1024` with a default of `1.0` meaning no scaling
  on load. Numbers less than `1.0` scale the image down
  so that a scale of `0.5` will halve the image size on
  load.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

# `from_svg!`
*since 0.32.0* 

```elixir
@spec from_svg!(svg :: binary(), options :: Image.Options.Open.image_open_options()) ::
  Vix.Vips.Image.t() | no_return()
```

Returns an image created from an SVG string or
raises an exception.

### Arguments

* `svg` is an SVG string.

* `options` is a keyword list of options.

### Options

* `:access` is the file access mode, either `:random`
  or `:sequential`. The default is `:random`.
  When `:sequential`, `Image` (via `Vix`) is able
  to support streaming transformations and optimise
  memory usage more effectively. However `:sequential`
  also means that some operations cannot be completed
  because they would require non-sequential access to
  the image. In these cases, `:random` access is required.

* `:fail_on` sets the error level at which image
  loading and decoding will stop. The default is `:none`.
  Each error state implies all the states before it such
  that `:error` implies also `:truncated`.

* `:scale` will scale the image on load. The value is
  a number greater than `0` and less than or equal
  to `1024` with a default of `1.0` meaning no scaling
  on load. Numbers less than `1.0` scale the image down
  so that a scale of `0.5` will halve the image size on
  load.

### Returns

* `image` or

* raises an exception.

# `new`
*since 0.1.13* 

```elixir
@spec new(image :: %Vix.Vips.Image{ref: term()}) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Create a new image of the same shape as the
provided image.

The function creates a new image with the same
width, height and bands as the image argument and
a color of `:black`.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` from
  which the new images `width` and `height` and
` bands` will be derived.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

# `new`

```elixir
@spec new(width :: pos_integer(), height :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
@spec new(image :: %Vix.Vips.Image{ref: term()}, options :: Image.Options.New.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Create a new image of the given dimensions.

### Arguments

Either `width` and `height` OR `image` should be
provided.

* `width` is the image width as an integer.

* `height` is the image height as an integer.

* `image` is an image from which the `width`, `height` are
  derived.

* `options` is a keyword list of options.

### Options

* `:color` defines the color of the image. This
  can be specified as a single integer which will
  be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

* `:bands` defines the number of bands (channels)
  to be created. The default is the number of bands of
  `:color` option or if `:color` is an integer then the
  default value is `3`.

* `:format` defines the format of the image. The
  default is `{:u, 8}`.

* `:interpretation` defines the interpretation of
  the image. The default is `:srgb`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Either `width` and `height` OR `image` should
  be provided as arguments but NOT both.

### Examples

      # 100x100 pixel image of dark blue slate color
      iex> {:ok, _image} = Image.new(100, 100, color: :dark_slate_blue)

      # 100x100 pixel green image, fully transparent
      iex> {:ok, _image} = Image.new(100, 100, color: [0, 255, 0, 255], bands: 4)

# `new`

```elixir
@spec new(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.New.t()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

# `new!`
*since 0.1.13* 

Return a new image of the same shape as the
provided image or raise an exception.

The function creates a new image with the same
width, height and bands as the image argument.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` from
  which the new images `width` and `height` and
` bands` will be derived.

* `options` is a keyword list of options.

### Options

* `:bands` defines the number of bands (channels)
  to be created. The default is the number of bands
  in `image`.

* `:color` defines the color of the image. This
  can be specified as a single integer which will
  be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

* `:format` defines the format of the image. The
  default is `{:u, 8}`.

* `:interpretation` defines the interpretation of
  the image. The default is `:srgb`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

# `new!`

```elixir
@spec new!(width :: pos_integer(), height :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()
@spec new!(image :: %Vix.Vips.Image{ref: term()}, options :: Image.Options.New.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Return a new image of the given dimensions and
background color or raise an exception.

### Arguments

Either `width` and `height` OR `image` should be
provided.

* `width` is the image width as an integer.

* `height` is the image height as an integer.

* `image` is an image from which the `width`, `height` re
  derived.

* `options` is a keyword list of options.

### Options

* `:bands` defines the number of bands (channels)
  to be created. The default is `3`.

* `:color` defines the color of the image. This
  can be specified as a single integer which will
  be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

* `:format` defines the format of the image. The
  default is `{:u, 8}`.

* `:interpretation` defines the interpretation of
  the image. The default is `:srgb`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

* Either `width` and `height` OR `image` should
  be provided as arguments but NOT both.

### Examples

      # 100x100 pixel image of dark blue slate color
      iex> {:ok, _image} = Image.new(100, 100, color: :dark_slate_blue)

      # 100x100 pixel green image, fully transparent
      iex> {:ok, _image} = Image.new(100, 100, color: [0, 255, 0, 1], bands: 4)

# `new!`

```elixir
@spec new!(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.New.t()
) ::
  Vix.Vips.Image.t() | no_return()
```

# `open`

```elixir
@spec open(
  path_or_stream_or_binary :: image_data(),
  options :: Image.Options.Open.image_open_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Opens an image file or stream for image processing.

### Arguments

* `image_path_or_stream_or_binary` is the file system path to an image
  file or a `t:File.Stream.t/0` or any `t:Enumerable.t/0`. It
  can also be any binary `.jpg`, `.png`, `.webp` or `.svg` image.

* `options` is a keyword list of options. The default is
  `[access: :random]` for all images except images
  derived from binary image data.

### Options

The available options depend upon the image type.

#### All image types

* `:access` is the file access mode, either `:random`
  or `:sequential`. The default is `:random`.
  When `:sequential`, `Image` (via `Vix`) is able
  to support streaming transformations and optimise
  memory usage more effectively. However `:sequential`
  also means that some operations cannot be completed
  because they would require non-sequential access to
  the image. In these cases, `:random` access is required.

* `:fail_on` sets the error level at which image
  loading and decoding will stop. The default is `:none`.
  Each error state implies all the states before it such
  that `:error` implies also `:truncated`.

#### JPEG image options

* `:shrink` is an integer factor in the range `1..16` by
  which the image is reduced upon loading. This is an
  optimization that can result in improved performance and
  reduced memory usage if the image is being loaded
  with the intent to resize it to smaller dimensions. The
  default value is `1` meaning no shrink-on-load.

#### WEBP options

* `:scale` will scale the image on load. The value is
  a number greater than `0` and less than or equal
  to `1024` with a default of `1` meaning no scaling
  on load. Numbers less than `1.0` scale the image down
  so that a scale of `0.5` will halve the image size on
  load.

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### TIFF options

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### GIF options

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### PNG options

* There are no PNG-specific image loading
  options.

### Returns

* `{:ok, image}` or

* `{:error, message}`

# `open!`

```elixir
@spec open!(
  path_or_stream_or_binary :: image_data(),
  options :: Image.Options.Open.image_open_options()
) :: Vix.Vips.Image.t() | no_return()
```

Opens an image file for image processing
returning an image or raising an exception.

### Arguments

* `image_path_or_stream_or_binary` is the file system path to an image
  file or a `t:File.Stream.t/0` or any `t:Enumerable.t/0`. It
  can also be any binary `.jpg`, `.png`, `.webp` or `.svg` image.

* `options` is a keyword list of options. The default is
  `[access: :random]` for all images except images
  derived from binary image data.

### Options

The available options depend upon the image type.

#### All image types

* `:access` is the file access mode, either `:random`
  or `:sequential`. The default is `:random`.
  When `:sequential`, `Image` (via `Vix`) is able
  to support streaming transformations and optimise
  memory usage more effectively. However `:sequential`
  also means that some operations cannot be completed
  because they would require non-sequential access to
  the image. In these cases, `:random` access is required.

* `:fail_on` sets the error level at which image
  loading and decoding will stop. The default is `:none`.
  Each error state implies all the states before it such
  that `:error` implies also `:truncated`.

#### JPEG image options

* `:shrink` is an integer factor in the range `1..16` by
  which the image is reduced upon loading. This is an
  optimization that can result in improved performance and
  reduced memory usage if the image is being loaded
  with the intent to resize it to smaller dimensions. The
  default value is `1` meaning no shrink-on-load.

* `:autorotate` is a boolean value indicating if
  the image should be rotated according to the orientation
  data stored in the image metadata. The default is
  `false`.

#### WEBP options

* `:scale` will scale the image on load. The value is
  a number greater than `0` and less than or equal
  to `1024` with a default of `1` meaning no scaling
  on load. Numbers less than `1.0` scale the image down
  so that a scale of `0.5` will halve the image size on
  load.

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### TIFF options

* `:autorotate` is a boolean value indicating if
  the image should be rotated according to the orientation
  data stored in the image metadata. The default is
  `false`.

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### GIF options

* `:page` indicates the first page to be loaded. The
  value is in the range `0..100_000` with a default
  value of `0`. This parameter is useful on animated images.

* `:pages` indicates the number of pages to load.
  The value must be between `-1` and `100_000`. The default
  value is `1`.  A value of `-1` would load all the available
  pages which is useful if you want to keep the animation of
  the input image. The atom `:all` can be used in place of
  `-1` to indicate all pages should be loaded.

#### PNG options

* There are no PNG-specific image loading
  options.

### Returns

* `image` or

* raises an exception.

# `stream!`

```elixir
@spec stream!(
  Vix.Vips.Image.t(),
  options :: Image.Options.Write.image_write_options()
) ::
  Enumerable.t()
```

Convert an image into an enumerable
stream.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:buffer_size` is the size in bytes for
  each chunk in the stream being written.
  Some services, like AWS S3, require a minimum
  5 MiB per chunk to be delivered and this option
  can be used to satisfy that requirement.

For additional options see `Image.write/3`.

### Returns

* An `t:Enumerable.t/0` suitable for
  streaming to an external service such as
  S3, Minio or any other enumerable consumer.

> #### S3 and Buffer Size {: .info}
> You may get an error from S3 if you do not specify a buffer size.
>
> ```text
> EntityTooSmall: Your proposed upload is smaller than the minimum allowed object size.
> ```
>
> Since AWS S3 requires multipart uploads to be 5MiB per chunk, we specify
> the `:buffer_size` option to `Image.stream!/2`.

### Example

In this example an image is resized
and then streamed into AWS S3:

    "some/image.jpg"
    |> Image.thumbnail!(200)
    |> Image.stream!(suffix: ".jpg", buffer_size: 5_242_880)
    |> ExAws.S3.upload("images", "some_object_name.jpg")
    |> ExAws.request()

# `write`

```elixir
@spec write(
  image :: Vix.Vips.Image.t(),
  image_path ::
    Path.t() | Plug.Conn.t() | Enumerable.t() | File.Stream.t() | :memory,
  options :: Image.Options.Write.image_write_options()
) ::
  {:ok, Vix.Vips.Image.t()}
  | {:ok, binary()}
  | {:ok, Plug.Conn.t()}
  | {:error, error()}
```

Write an image to a file, a stream, an enumerable or
to memory.

### Arguments

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

* `image_path` is the file system path to an image
  file. It may also be a stream created with
  `File.stream!/3` or with `Stream.resource/3`, a
  `t:Plug.Conn.t/0` if `Plug` is configured or lastly,
  it can also be `:memory` in which case the image is
  written to a binary. Currently,`:memory` supports only
  TIFF, JPEG and PNG formats.

* `options` is a keyword list of options. The default is
  `[]`.

### Options

The available options depends on the type of image
file being opened.

#### All image types

* `:strip_metadata` is a boolean indicating if all metadata
  is to be stripped from the image. The default is `false`.

* `:background` is the background value to be used
  for any transparent areas of the image. Jpeg does
  not support alpha bands so a color value must be
  assigned.

* `:quality` which influences image compression and
  is a integer in the range `1..100`. The default for
  most image formats is `75`. For HEIF files the default
  is `50`.For PNG files the `:quality` option is ignored.

### Streaming images and :memory images

* `:suffix` must be specified so that the image is written
  in the correct format. For example: `suffix: ".jpg"`.

#### JPEG images

* `:progressive` is a boolean indicating if the image
  should be interleaved rather than baseline. Progressive
  has the advantage of perceived time for the initial
  image load and the cost of multiple decoding passes on
  the client. For many applications `:progressive` is
  to be preferred but validation of this assumption for
  specific use cases is required.

* `:minimize_file_size` is a boolean indicating whether
  to apply a number of techniques to minimise the file
  size of the jpeg file at the cost of additional time to
  save the image. All metadata will also be removed.

* `:icc_profile` indicates the icc profile to be attached
  to the output image. The value may be an inbuilt profile
  (`:none`, `:srgb`, `:cmyk`, `:p3`), the name of an icc
  profile in the systems profile directory or a full path
  to an icc profile file. The default is to use the icc
  profile of the input image if there is one.

#### PNG images

* `:progressive` which has the same meaning and values
    as for JPEG images.

* `:minimize_file_size` is a boolean indicating whether
  to apply a number of techniques to minimise the file
  size of the `png` file at the cost of additional time to
  save the image. All metadata will also be removed.

* `:compression`  is the compression factor which is an
  integer in the range `1..9`. The default is `6`.

* `:effort` is an integer to adjust the level of CPU
  effort to reduce the file size. The value must be in the
  range `1..10`, the default is `7`.

* `:icc_profile` indicates the icc profile to be attached
  to the output image. The value may be an inbuilt profile
  (`:none`, `:srgb`, `:cmyk`, `:p3`), the name of an icc
  profile in the systems profile directory or a full path
  to an icc profile file. The default is to use the icc
  profile of the input image if there is one.

#### WEBP images

* `:minimize_file_size` is a boolean which is most useful
  on animated `WebP`. It enables mixed encoding and optimise
  the file for minimum size at the cost of additional time
  to save the image. All metadata will also be removed.
  Using this parameter on a non-animated `webp` file will
  only remove the metadata as `:strip_metadata` would do.

* `:effort` is an integer to adjust the level of CPU
  effort to reduce the file size.
  The value must be in the range `1..10`, the default
  is `7`.

* `:icc_profile` indicates the icc profile to be attached
  to the output image. The value may be an inbuilt profile
  (`:none`, `:srgb`, `:cmyk`, `:p3`), the name of an icc
  profile in the systems profile directory or a full path
  to an icc profile file. The default is to use the icc
  profile of the input image if there is one.

#### GIF images

* `:interframe_maxerror` Maximum inter-frame error for transparency.
  The value must be in the range `0..32`.
  The default is `0`.
  By increasing this value, the encoder will try to take advantage
  from temporal redundancy between neighboring frames by enabling
  higher compression rates.

* `:effort` is an integer to adjust the level of CPU
  effort to reduce the file size.
  The value must be in the range `1..10`, the default
  is `7`.

#### HEIF/HEIC and AVIF images

* `:compression` is the compression strategy to
  be applied. The allowable values are `:hevc`,
  and `:av1` for HEIF/HEIC files, and `:avc`, `:av1`
  and `:jpeg` for AVIF files.

* `:effort` is an integer to adjust the level of CPU
  effort to reduce the file size.
  The value can be in the range `1..10`, the default is
  `5`.

* `:minimize_file_size` is a boolean indicating whether
  to apply a number of techniques to minimise the file
  size of the `heif` file at the cost of additional time to
  save the image. All metadata will also be removed.

### TIFF options

* `:pyramid` is a boolean indicating whether to write the
  image as an
  [image pyramid](https://en.wikipedia.org/wiki/Pyramid_(image_processing)).

### Merging image type options

Options can also be grouped under an option key
for each known image type. For example:

    Image.write(image, image_path, minimize_file_size: true,
      png: [compress: 60, lossy: true],
      jpg: [quality: 70],
      webp: [quality: 5])

When validating options, the options applicable to the
image type of `image_path` are merged into the rest of
the supplied options.

The valid image type option keys are `:jpg`, `.png`,
`:gif`, `:tif`, `:webp`, `:heif` and `:avif`.

This makes it easier to define a general purpose image
processing pipeline that can still apply specific
options when writing the image file.

### Returns

* `{:ok, image}`, or `{:ok, binary}` if the destination is
  `:memory`) or `{:ok, conn}` if the destination is a `t:Plug.Connt.t/0` or

* `{:error, reason}`

# `write!`

```elixir
@spec write!(
  image :: Vix.Vips.Image.t(),
  image_path ::
    Path.t() | Plug.Conn.t() | Enumerable.t() | File.Stream.t() | :memory,
  options :: Image.Options.Write.image_write_options()
) :: Vix.Vips.Image.t() | binary() | no_return()
```

Write an image to a file, a stream, an enumerable or
to memory returning the image or raising an exception.

### Arguments

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

* `image_path` is the file system path to an image
  file. It may also be a stream created with
  `File.stream!/3` or with `Stream.resource/3`. Lastly,
  it can also be `:memory` in which case the image is
  written to a memory buffer.

* `options` is a keyword list of options.
  See `Image.write/2`.

### Returns

* `image` (or a binary if the destination is `:memory`) or

* raises an exception.

# `apply_tone_curve`
*since 0.35.0* 

```elixir
@spec apply_tone_curve(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ToneCurve.tone_curve_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Applies a tone curve to an image.

A [tone curve](https://en.wikipedia.org/wiki/Curve_(tonality))
is typically used to affect overall image contrast. It
is a function to adjust brightness and contrast by controlling the
input-output density curve for each band of an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:black_point` is an integer between `0`
  (the default) and `100` indicating the darkest
  and most dense black area of the image will
  lie in the overall range of the image.

* `:white_point` is an integer between `0`
  and `100` (the default) indicating the lightest
  area of the image will lie in the overall range
  of the image.

* `:shadow_point` is the point on the tone curve
  around which the shadow values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.2`.

* `:mid_point` is the point on the tone curve
  around which the mid tone values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.5`.

* `:highlight_point` is the point on the tone curve
  around which the highlight values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.8`.

* `:shadows` indicates by how much the shadows should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

* `:mid_points` indicates by how much the mid tones should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

* `:highlights` indicates by how much the highlights should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

### Returns

* `{:ok, tone_mapped_image}` or

* `{:error, reason}`.

# `apply_tone_curve!`
*since 0.35.0* 

```elixir
@spec apply_tone_curve!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ToneCurve.tone_curve_options()
) :: Vix.Vips.Image.t() | no_return()
```

Applies a tone curve to an image or raises
an exception.

A [tone curve](https://en.wikipedia.org/wiki/Curve_(tonality))
is typically used to affect overall image contrast. It
is a function to adjust brightness and contrast by controlling the
input-output density curve for each band of an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:black_point` is an integer between `0`
  (the default) and `100` indicating the darkest
  and most dense black area of the image will
  lie in the overall range of the image.

* `:white_point` is an integer between `0`
  and `100` (the default) indicating the lightest
  area of the image will lie in the overall range
  of the image.

* `:shadow_point` is the point on the tone curve
  around which the shadow values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.2`.

* `:mid_point` is the point on the tone curve
  around which the mid tone values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.5`.

* `:highlight_point` is the point on the tone curve
  around which the highlight values are tone mapped. The
  value is between `0.0` and `1.0`. The default is
  `0.8`.

* `:shadows` indicates by how much the shadows should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

* `:mid_points` indicates by how much the mid tones should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

* `:highlights` indicates by how much the highlights should be
  adjusted. The value is in the range `-30` to `30`.
  The default is `0`.

### Returns

* `tone_mapped_image` or

* raises an exception.

# `brightness`
*since 0.34.0* 

```elixir
@spec brightness(image :: Vix.Vips.Image.t(), brightness :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply a percentage adjustment to an image's brightness
(luminance).

The image is converted to the [LCh color space](https://en.wikipedia.org/wiki/HCL_color_space),
multiplies the luminance band by the provided float percentage and converts
the image back to its original color space.

### Arguments

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

* `brightness` is any float greater than `0.0`. A number less
  than `1.0` means reduce brightness. A number greater than `1.0`
  means increas brightness.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

### Example

    iex> image = Image.open!("./test/support/images/cat.png")
    iex> {:ok, _brighter_image} = Image.brightness(image, 1.5)

# `brightness!`
*since 0.34.0* 

```elixir
@spec brightness!(image :: Vix.Vips.Image.t(), brightness :: float()) ::
  Vix.Vips.Image.t() | no_return()
```

Apply a percentage adjustment to an image's brightness
(luminance) or raises an exception.

The image is converted to the [LCh color space](https://en.wikipedia.org/wiki/HCL_color_space),
multiplies the luminance band by the provided float percentage and converts
the image back to its original color space.

### Arguments

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

* `brightness` is any float greater than `0.0`. A number less
  than `1.0` means reduce brightness. A number greater than `1.0`
  means increas brightness.

### Returns

* `adjusted_image` or

* raises an exception.

### Example

    iex> image = Image.open!("./test/support/images/cat.png")
    iex> _brighter_image = Image.brightness!(image, 1.5)

# `contrast`
*since 0.35.0* 

```elixir
@spec contrast(image :: Vix.Vips.Image.t(), contrast :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply a percentage adjustment to an image's contrast.

This is a simple implementation that applies a linear
function to the image. In most cases, `Image.apply_tone_curve/2`
should be preferred for making constrast adjustments.

Small increments can have a dramatic affect on the image;
contrast in the range of approximately `0.5` to `1.5` are
likely to meet most requirement.

### Arguments

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

* `contrast` is any float greater than `0.0`. A number less
  than `1.0` means reduce contrast. A number greater than `1.0`
  means increase contrast.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

### Example

    iex> image = Image.open!("./test/support/images/cat.png")
    iex> {:ok, _image_with_more_contrast} = Image.contrast(image, 1.2)

# `contrast!`
*since 0.35.0* 

```elixir
@spec contrast!(image :: Vix.Vips.Image.t(), contrast :: float()) ::
  Vix.Vips.Image.t() | no_return()
```

Apply a percentage adjustment to an image's contrast or
raises and exception.

This is a simple implementation that applies a linear
function to the image. In most cases, `Image.apply_tone_curve/2`
should be preferred for making constrast adjustments.

Small increments can have a dramatic affect on the image;
contrast in the range of approximately `0.5` to `1.5` are
likely to meet most requirement.

### Arguments

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

* `contrast` is any float greater than `0.0`. A number less
  than `1.0` means reduce contrast. A number greater than `1.0`
  means increase contrast.

### Returns

* `adjusted_image` or

* raises an exception.

### Example

    iex> image = Image.open!("./test/support/images/cat.png")
    iex> _image_with_more_contrast = Image.contrast!(image, 1.2)

# `equalize`
*since 0.35.0* 

```elixir
@spec equalize(
  image :: Vix.Vips.Image.t(),
  bands :: Image.Options.Equalize.equalize_option()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Equalizes the histogram of an imaage.

Equalization is the process of expanding the
tone range of an image by stretching the darkest
tones towards black and the lightest tones towards
white. As a result, equalization affects overall
image contrast.

### Arguments

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

* `bands` determines which bands are equalized. The
  value may be one of:

  * `:all` (defaalt) means that all bands are eqalized
    such that the darkest tones are expanded to black and the
    lightest tones are expanded to white.

  * `:each` means that each band is equalized individually
    such that each band is expanded to fill the range
    between 5% and 95% of the available tone range. Since
    each band is equalized separately there may be some
    color shifts detected.

  * `:luminance` means that only the luminance band is
    equqlized to fill between 1% and 99% of the tone range.
    The image is converted to the `:lab` color space, the
    `l` band is equalized and the image is converted back to
    its origianal color space.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

# `equalize!`
*since 0.35.0* 

```elixir
@spec equalize!(
  image :: Vix.Vips.Image.t(),
  bands :: Image.Options.Equalize.equalize_option()
) ::
  Vix.Vips.Image.t() | no_return()
```

Apply a global contrast adjustment to an image
or raises an exception.

Equalization is the process of expanding the
tone range of an image by stretching the darkest
tones towards black and the lightest tones towards
white. As a result, equalization affects overall
image contrast.

### Arguments

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

* `bands` determines which bands are equalized. The
  value may be one of:

  * `:all` (defaalt) means that all bands are eqalized
    such that the darkest tones are expanded to black and the
    lightest tones are expanded to white.

  * `:each` means that each band is equalized individually
    such that each band is expanded to fill the range
    between 5% and 95% of the available tone range. Since
    each band is equalized separately there may be some
    color shifts detected.

  * `:luminance` means that only the luminance band is
    equqlized to fill between 1% and 99% of the tone range.
    The image is converted to the `:lab` color space, the
    `l` band is equalized and the image is converted back to
    its origianal color space.

### Returns

* `adjusted_image` or

* raises an exception.

# `invert`
*since 0.42.0* 

```elixir
@spec invert(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Inverts an image.

### Arguments

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

### Returns

* `{:ok, inverted_image}` or

* `{:error, reason}`.

### Notes

* For unsigned formats, this operation calculates
  `(max_value - pixel_value)`, eg. `(255 - pixel_value)` for
  typical 8-bit sRGB images.

* For signed and float formats, this operation calculates
  `(-1 * pixel_value)`.

* For complex images, only the real part is inverted.

# `invert!`
*since 0.42.0* 

```elixir
@spec invert!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Inverts an image or raises an exception.

### Arguments

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

### Returns

* `inverted_image` or

* raises an exception.

### Notes

* For unsigned formats, this operation calculates
  `(max_value - pixel_value)`, eg. `(255 - pixel_value)` for
  typical 8-bit sRGB images.

* For signed and float formats, this operation calculates
  `(-1 * pixel_value)`.

* For complex images, only the real part is inverted.

# `local_contrast`
*since 0.35.0* 

```elixir
@spec local_contrast(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.LocalContrast.local_contrast_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply a local contrast adjustment to an image.

This function applies a [Constrast Limited Adaptive histogram equalization (CLAHE)](https://en.wikipedia.org/wiki/Adaptive_histogram_equalization#Contrast_Limited_AHE)
to improve contrast in images. It differs from ordinary histogram
equalization in the respect that the adaptive method computes several
histograms, each corresponding to a distinct section of the image, and
uses them to redistribute the lightness values of the image.

It is therefore suitable for improving the local contrast and
enhancing the definitions of edges in each region of an image,
hence the name of the function.

### Arguments

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

* `options` is a keyword list of options.

### Options

* :`window_size` is an integer indicating the size of
  the window (in pixels) into the image in which the contrast adjustment
  is calculated. The default is `3`.

* `:max_slope` is the integral level of brightening, between 0 and
  100, where 0 (the default) disables contrast limiting.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

# `modulate`
*since 0.35.0* 

```elixir
@spec modulate(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Modulate.modulate_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Transforms an image using brightness, saturation,
hue rotation, and lightness.

Brightness and lightness both operate on luminance,
with the difference being that brightness is multiplicative
whereas lightness is additive.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:brightness` is any float greater than `0.0`. A number less
  than `1.0` means reduce brightness. A number greater than `1.0`
  means increas brightness.  The default is `1.0` meaning no
  brightness adjustment.

* `:lightness` is any float. This value is added to the luminance
  of an image. This is different to `:brightness` which is *multuplied*
  by the luminance. The default is `0.0` meaning no lightness
  adjustment.

* `:saturation` is any float greater than `0.0`. A number less
  than `1.0` means reduce saturation. A number greater than `1.0`
  means increas saturation. The default is `1.0` meaning no
  saturation adjustment.

* `:hue` is an integer angle in degrees added to the hue. This is often
  referred to as the *hug angle* and the operation as adjusting
  the *hue rotation*. The value should typically be in the range `0..360`.
  The default is `0` meaning no hue adjustment.

### Returns

* `{:ok, modulated_image}` or

* `{:error, reason}`.

# `modulate!`
*since 0.35.0* 

```elixir
@spec modulate!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Modulate.modulate_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Transforms an image using brightness, saturation,
hue rotation, and lightness or raises an exception.

Brightness and lightness both operate on luminance,
with the difference being that brightness is multiplicative
whereas lightness is additive.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:brightness` is any float greater than `0.0`. A number less
  than `1.0` means reduce brightness. A number greater than `1.0`
  means increas brightness.  The default is `1.0` meaning no
  brightness adjustment.

* `:lightness` is any float. This value is added to the luminance
  of an image. This is different to `:brightness` which is *multuplied*
  by the luminance. The default is `0.0` meaning no lightness
  adjustment.

* `:saturation` is any float greater than `0.0`. A number less
  than `1.0` means reduce saturation. A number greater than `1.0`
  means increas saturation. The default is `1.0` meaning no
  saturation adjustment.

* `:hue` is an integer angle in degrees added to the hue. This is often
  referred to as the *hug angle* and the operation as adjusting
  the *hue rotation*. The value should typically be in the range `0..360`.
  The default is `0` meaning no hue adjustment.

### Returns

* `modulated_image` or

* raises an exception.

# `saturation`
*since 0.34.0* 

```elixir
@spec saturation(image :: Vix.Vips.Image.t(), saturation :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply an adjustment to an image's saturation
(chroma).

The image is converted to the [LCh color space](https://en.wikipedia.org/wiki/HCL_color_space),
multiplies the chroma band by the provided float and converts
the image back to its original color space.

### Arguments

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

* `saturation` is any float greater than `0.0`. A number less
  than `1.0` means reduce saturation. A number greater than `1.0`
  means increase saturation.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

# `saturation!`
*since 0.34.0* 

```elixir
@spec saturation!(image :: Vix.Vips.Image.t(), saturation :: float()) ::
  Vix.Vips.Image.t() | no_return()
```

Apply an adjustment to an image's saturation
(chroma) or raises an exception.

The image is converted to the [LCh color space](https://en.wikipedia.org/wiki/HCL_color_space),
multiplies the chroma band by the provided float and converts
the image back to its original color space.

### Arguments

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

* `saturation` is any float greater than `0.0`. A number less
  than `1.0` means reduce saturation. A number greater than `1.0`
  means increase saturation.

### Arguments

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

* `saturation` is any float greater than `0.0`. A number less
  than `1.0` means reduce saturation. A number greater than `1.0`
  means increas saturation.

### Returns

* `adjusted_image` or

* raises an exception.

# `add_alpha`
*since 0.13.0* 

```elixir
@spec add_alpha(
  image :: Vix.Vips.Image.t(),
  alpha_image :: Vix.Vips.Image.t() | transparency()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Add an alpha band to an image.

### Arguments

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

* `alpha_image` is any single-band image
  that will be added as an alpha image to
  `image`

OR

* an integer in the range `0..255` that represents
  the level of transparency of the alpha band. `0`
  represents fully opaque and `255` represents fully
  transparent. The atoms `:opaque` and `:transparent`
  may also be provided representing the values of
  `0` and `255` respectively.

### Returns

* `{:ok, image_with_added_alpha_band}` or

* `{:error, reason}`

# `add_alpha!`
*since 0.13.0* 

```elixir
@spec add_alpha!(
  image :: Vix.Vips.Image.t(),
  alpha_image :: Vix.Vips.Image.t() | Image.Pixel.t()
) ::
  Vix.Vips.Image.t() | no_return()
```

Add an alpha band to an image.

### Arguments

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

* `alpha_image` is any single-band image
  that will be added as an alpha image to
  `image`

OR

* `:color` which defines the color of the alpha
  image. This can be specified as a single integer
  which will be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

### Note

If `color` is provided then the alpha layer determines
the level of transparency of `image`.

White (RGB color 255) means that `image` will be opaque.
Black (the default, RGB 0) means that `image` will be transparent.
Other colors will determine the level of transparency
between the two.

### Returns

* `image_with_added_alpha_band` or

* raises an exception.

# `autorotate`

```elixir
@spec autorotate(image :: Vix.Vips.Image.t()) ::
  {:ok, {Vix.Vips.Image.t(), map()}} | {:error, error()}
```

Rotate an image based upon the orientation
information in an image's EXIF data.

### Arguments

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

### Returns

* `{:ok, {auto_rotated_image, flags}}` or

* `{:error, reason}`

### Flags

A two-entry `Keyword.t` is returned indicating what actions
were taken:

* `:flip` which is a boolean indicating if the image
  was flipped or not and

* `:angle` through which the image was rotated.
  This value will be one of `0`, `90`, `180` or
  `270` representing the degrees of rotation.

# `autorotate!`

```elixir
@spec autorotate!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Rotate an image based upon the orientation
information in an image's EXIF data. Returns
a potentially rotated image or raises and
exception.

### Arguments

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

### Returns

* `auto_rotated_image` or

* raises an exception.

# `blur`
*since 0.13.0* 

```elixir
@spec blur(image :: Vix.Vips.Image.t(), options :: Image.Options.Blur.blur_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Applies a gaussian blur to an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:sigma` is the `float` size of the mask
  to use. A larger number makes the image more
  blurry. A range between `1.0` and `10.0`
  is normally appropriate. The default is
  `5`.

* `:min_amplitude` is a `float` that determines
  the accuracy of the mask. The default is `0.2`.
  A smaller number will generate a larger, more
  accurate mask,

### Returns

* `{:ok, blurred_image}` or

* `{:error reason}`

# `blur!`
*since 0.13.0* 

```elixir
@spec blur!(image :: Vix.Vips.Image.t(), options :: Image.Options.Blur.blur_options()) ::
  Vix.Vips.Image.t() | no_return()
```

Applies a gaussian blur to an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:sigma` is the `float` size of the mask
  to use. A larger number makes the image more
  blurry. A range between `1.0` and `10.0`
  is normally appropriate. The default is
  `5`.

* `:min_amplitude` is a `float` that determines
  the accuracy of the mask. The default is `0.2`.
  A smaller number will generate a larger, more
  accurate mask,

### Returns

* `blurred_image` or

* raises an exception.

# `cast`
*since 0.30.0* 

```elixir
@spec cast(Vix.Vips.Image.t(), Image.BandFormat.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Casts an image from one band format to another.

The band format is the numeric type of each pixel.
In the common case of `sRGB` images, the format is
`{:u, 8}` meaning unsigned 8-bit values.

### Arguments

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

* `band_format` is any known band format. See
  `Image.BandFormat.known_band_formats/0`.

### Returns

* `{:ok, cast_image}` or

* `{:error, reason}`.

# `cast!`
*since 0.42.0* 

```elixir
@spec cast!(Vix.Vips.Image.t(), Image.BandFormat.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Casts an image from one band format to another or
raises an exception.

The band format is the numeric type of each pixel.
In the common case of `sRGB` images, the format is
`{:u, 8}` meaning unsigned 8-bit values.

### Arguments

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

* `band_format` is any known band format. See
  `Image.BandFormat.known_band_formats/0`.

### Returns

* `cast_image` or

* raises an exception.

# `chroma_color`
*since 0.13.0* 

```elixir
@spec chroma_color(image :: Vix.Vips.Image.t()) :: Image.Pixel.t()
```

Automatically determine the chroma key
color of an image.

The top left 10x10 pixels of the flattened
image are averaged to produce a color sample
that can then be used by `Image.chroma_mask/2`,
`Image.chroma_key/2` and `Image.trim/2`.

### Argument

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

### Returns

* An RGB color as a three-element list of
  integers.

# `chroma_key`
*since 0.13.0* 

```elixir
@spec chroma_key(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ChromaKey.chroma_key_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Chroma key an image.

Chroma keying is the process of removing a background color
from an image resulting in a foreground image that may
be composited over another image.

If the image already has an alpha band then the
image is flattened before adding the image mask
as a new alpha band.

### Arguments

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

* `options` is a keyword list of options.

### Options

There are two masking strategies available: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be masked. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold` is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

*  `:less_than` is an RGB color which represents the lower
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

# `chroma_key!`
*since 0.13.0* 

```elixir
@spec chroma_key!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ChromaKey.chroma_key_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Chroma key an image and return an image or
raise an exception.

Chroma keying is the process of removing a background color
from an image resulting in a foreground image that may
be composited over another image.

If the image already has an alpha band then the
image is flattened before adding the image mask
as a new alpha band.

### Arguments

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

* `options` is a keyword list of options.

### Options

There are two masking strategies available: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be masked. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold` is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

*  `:less_than` is an RGB color which represents the lower
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

# `compare`
*since 0.34.0* 

```elixir
@spec compare(Vix.Vips.Image.t(), Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, number(), Vix.Vips.Image.t()} | {:error, error()}
```

Compare two images using a particular comparison metric
returning a score indicating the similarity of the images and
an image highlighting the differences between the two images.

### Arguments

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

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

* `options` is a keyword list of options.

### Options

* `:metric` indicates which comparison metric to use. The default
  is `:ae`. The valid metrics are:

  * [:ae](https://en.wikipedia.org/wiki/Sum_of_absolute_differences) which returns
    the absolute nuber of pixels that are different between the two images.
    The returned value is conformed to the range of the underlying image format.
    Therefore the returned value is between `0.0` (images appear to be the same)
    and `1.0` (meaning the images appear completely different).

  * [:rmse](https://en.wikipedia.org/wiki/Root-mean-square_deviation) is the root
    mean square error. The returned value is conformed to the range of
    the underlying image format. Therefore the returned value is between `0.0`
    (images appear to be the same) and `1.0` (meaning the images appear
    completely different),

  * [:mse](https://en.wikipedia.org/wiki/Mean_squared_error) which
    is the mean squared error (default). The returned value is a float
    indicating how similar the images are. A value of
    `0.0` means the images are the same. The number itself it simply a
    measure of the error difference between images. A larger number means
    the two images are less similar but the number itself cannot be
    interpreted as a percentage value.

* `:saturation` is a float between `0.0` and `1.0` that is applied to the
  base image when overlaying the difference image. This may help the difference
  pixels become more obvious. The default ia `1.0` meaning no change in
  saturation.

* `:brightness` is a float between `0.0` and `1.0` that is applied to the
  base image when overlaying the difference image. This may help the difference
  pixels become more obvious. The default ia `1.0` meaning no change in
  brightness.

* `:difference_color` is the color to be used for the pixels that are
  different between the two images. This can be specified as a single integer
  which will be applied to all bands, or a list of integers representing
  he color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of the form `#rrggbb`. The default
  is `:red`.

* `:difference_boost` is a float multiplier that is applied to the difference
  image. This has the effect of boosting the overall brightness of the difference
  pixels making them stand out more against the background image. The default
  is `1.5`.

### Notes

* The images are conformed to the band format of the
  first image before comparison and cast up to the smallest common
  format.

* If the images differ in size, the smaller image is enlarged
  to match the larger by adding zero pixels along the bottom and right.

* If the number of bands differs, one of the images must have one band.
  In this case, an n-band image is formed from the one-band image by joining
  `n` copies of the one-band image together, and then the two n-band images
  are operated upon.

* The two input images are cast up to the smallest common format.

### Returns

* `{:ok, comparison_metric, difference_image}` or

* `{:error, reason}`

# `compose`

```elixir
@spec compose(
  base_image :: Vix.Vips.Image.t(),
  overlay_image :: Vix.Vips.Image.t(),
  options :: Image.Options.Compose.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
@spec compose(
  base_image :: Vix.Vips.Image.t(),
  image_list :: composition_list(),
  options :: Image.Options.Compose.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Compose two images together, or an image and a list of
images compositions, to form a new image.

### Arguments

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

* `overlay_image` is any `t:Vix.Vips.Image.t/0` that will
  be composed over the top of `base_image`. It can also
  be a list of `t:composition/0`s that allow for multiple
  images to be composed in a single call.

* `options` is a keyword list of options.

### Options for a single overlay image

* `:blend_mode` is the manner in which the two
  images are composited. See `t:Image.BlendMode.t/0`.
  The default is `:over` which is the most common blend
  mode.

* `:x` is the offset (0-based) which, if zero or positive,
  from the *left* of the `base_image`. If negative is is
  the offset from the *right* of the `base_image`.
  where the `overlay_image` will be placed. It may also be
  one of the keywords `:left`, `:right` or `:center`. The
  default is `:center`.

* `:y` is the offset (0-based) which, if zero or positive,
  from the *top* of the `base_image`. If negative is is
  the offset from the *bottom* of the `base_image`.
  where the `overlay_image` will be placed.  It may also be
  one of the keywords `:top`, `:bottom` or `:middle`. The
  default is `:middle`.

### Composition list options

When `overlay_image` is an `image_list`, each entry in
the list is either a `t:Vix.Vips.Image.t/0` or a
`t:Image.composition_list/0`. A composition supports the specification
of how a particular image is composed onto the base image.

* `:x` describes the absolute `x` offset on the
  base image where this image will be placed. If
  this option is set to `:left`, `:center` or
  `:right` then the `x` position will be calculated
  relative to the base image. If `:x` is nil
  (the default) then the image will be placed according
  to the relative offset of the previously composed
  image using `:dx`.

* `:y` describes the absolute `y` offset on the
  base image where this image will be placed. If
  this option is set to `:top`, `:middle` or
  `:bottom` then the `y` position will be calculated
  relative to the base image. If `:y` is nil
  (the default) then the image will be placed according
  to the relative offset of the previously composed
  image using `:dy`.

* `:dx` describes the relative offset used to calculate
  the `x` value. `:dx` is an integer offset from the
  edge of the previously composed image. Which edge is
  determined by the `:x_baseline` option. If `:x` is also
  specified then `:x` is first calculated, then `:dx` is
  added to it. In this case, `:x_baseline` is ignored.

* `:dy` describes the relative offset used to calculate
  the `y` value. `:dy` is an integer offset from the
  edge of the previously composed image. Which edge is
  determined by the `:y_baseline` option. If `:y` is also
  specified then `:y` is first calculated, then `:dy` is
  added to it. In this case, `:x_baseline` is ignored.

* `:blend_mode` is the `t:Image.BlendMode.t/0` used when
  composing this image over its base image. The default
  is `:over` which is appropriate for most use cases.

* `:x_baseline` establishes the baseline on the
  previously composed image from which `:dx` is
  calculated. The default is `:right`.

* `:y_baseline` establishes the baseline on the
  previously composed image from which `:dy` is
  calculated. The default is `:bottom`.

### Returns

* `{:ok, composed_image}` or

* `{:error, reason}`

### Examples

    # Compose images over a base image using
    # absolute coordinates from the base image
    # to place each overlay image.

    #=> {:ok, image} = Image.compose(base_image, polygon, x: :middle, y: :top)
    #=> {:ok, image} = Image.compose(image, explore_new, x: 260, y: 200)
    #=> {:ok, image} = Image.compose(image, places, x: 260, y: 260)
    #=> {:ok, image} = Image.compose(image, blowout, x: 260, y: 340)
    #=> {:ok, image} = Image.compose(image, start_saving, x: 260, y: 400)

    # Compose images over a base image
    # using a composition list and coordinates
    # that are either absolute with respect to the
    # base image or relative to the previously
    # composed image.

    #=> Image.compose(base_image, [
    ..>   {polygon, x: :center, y: :top},
    ..>   {explore_new, y_baseline: :top, x_baseline: :left, dx: 20, dy: 200},
    ..>   {places, dy: 10},
    ..>   {blowout, dy: 20},
    ..>   {start_saving, dy: 50}
    ..> ])

# `compose!`

```elixir
@spec compose!(
  base_image :: Vix.Vips.Image.t(),
  overlay_image :: Vix.Vips.Image.t(),
  options :: Image.Options.Compose.t()
) :: Vix.Vips.Image.t() | no_return()
@spec compose!(
  base_image :: Vix.Vips.Image.t(),
  image_list :: composition_list(),
  options :: Image.Options.Compose.t()
) :: Vix.Vips.Image.t() | no_return()
```

Compose two images together to form a new image or
raise an exception.

### Arguments

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

* `overlay_image` is any `t:Vix.Vips.Image.t/0` that will
  be composed over the top of `base_image`.

* `options` is a keyword list of options.

### Options

* `:blend_mode` is the manner in which the two
  images are composited. See `t:Image.BlendMode.t/0`.
  The default is `:over` which is the most common blend
  mode.

* `:x` is the offset (0-based) which, if zero or positive,
  from the *left* of the `base_image`. If negative is is
  the offset from the *right* of the `base_image`.
  where the `overlay_image` will be placed. It may also be
  one of the keywords `:left`, `:right` or `:center`. The
  default is `:center`.

* `:y` is the offset (0-based) which, if zero or positive,
  from the *top* of the `base_image`. If negative is is
  the offset from the *bottom* of the `base_image`.
  where the `overlay_image` will be placed.  It may also be
  one of the keywords `:top`, `:bottom` or `:middle`. The
  default is `:middle`.

### Composition list options

When `overlay_image` is an `image_list`, each entry in
the list is either a `t:Vix.Vips.Image.t/0` or a
`t:Image.composition_list/0`. A composition supports the specification
of how a particular image is composed onto the base image.

* `:x` describes the absolute `x` offset on the
  base image where this image will be placed. If
  this option is set to `:left`, `:center` or
  `:right` then the `x` position will be calculated
  relative to the base image. If `:x` is nil
  (the default) then the image will be placed according
  to the relative offset of the previously composed
  image using `:dx`.

* `:y` describes the absolute `y` offset on the
  base image where this image will be placed. If
  this option is set to `:top`, `:middle` or
  `:bottom` then the `y` position will be calculated
  relative to the base image. If `:y` is nil
  (the default) then the image will be placed according
  to the relative offset of the previously composed
  image using `:dy`.

* `:dx` describes the relative offset used to calculate
  the `x` value. `:dx` is an integer offset from the
  edge of the previously composed image. Which edge is
  determined by the `:x_baseline` option. If `:x` is also
  specified then `:x` is first calculated, then `:dx` is
  added to it. In this case, `:x_baseline` is ignored.

* `:dy` describes the relative offset used to calculate
  the `y` value. `:dy` is an integer offset from the
  edge of the previously composed image. Which edge is
  determined by the `:y_baseline` option. If `:y` is also
  specified then `:y` is first calculated, then `:dy` is
  added to it. In this case, `:x_baseline` is ignored.

* `:blend_mode` is the `t:Image.BlendMode.t/0` used when
  composing this image over its base image. The default
  is `:over` which is appropriate for most use cases.

* `:x_baseline` establishes the baseline on the
  previously composed image from which `:dx` is
  calculated. The default is `:right`.

* `:y_baseline` establishes the baseline on the
  previously composed image from which `:dy` is
  calculated. The default is `:bottom`.

### Returns

* `composed_image` or

* raises an exception

### Examples

    # Compose images over a base image using
    # absolute  coordinates from the base image
    # to place each overlay image
    #=> base_image
    ..> |> Image.compose!(polygon, x: :middle, y: :top)
    ..> |> Image.compose!(explore_new, x: 260, y: 200)
    ..> |> Image.compose!(places, x: 260, y: 260)
    ..> |> Image.compose!(blowout, x: 260, y: 340)
    ..> |> Image.compose!(start_saving, x: 260, y: 400)

    # Compose images over a base image
    # using a composition list and coordinates
    # that are either absolute with respect to the
    # base image or relative to the previously
    # composed image
    #=> base_image
    ..> |> Image.compose!([
    ..>   {polygon, x: :center, y: :top},
    ..>   {explore_new, y_baseline: :top, x_baseline: :left, dx: 20, dy: 200},
    ..>   {places, dy: 10},
    ..>   {blowout, dy: 20},
    ..>   {start_saving, dy: 50}
    ..> ])

# `dilate`
*since 0.23.0* 

```elixir
@spec dilate(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Dilate an image mask, adding a pixels to the
edge of the mask.

Mask is used in the sense of an image, potentially
wuth an alpha band. The results on
other image types is undefined.

The added pixels are the same color as the edge
pixels in the mask.

### Arguments

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

* `radius` is an integer in the range `1..100`
  representing the approximate number of
  pixels to dilate. The default is `1`.

### Returns

* `{:ok, dilated_mask}` or

* `{:error, reason}`

### Notes

* Dilate works for any non-complex image type, with any
  number of bands. The input is dilated by copying
  edge pixels before performing the operation so that
  the output image has the same size as the input.

* Edge pixels in the output image are only
  approximate.

* The dilation is implemented as a [rank filter](https://www.sciencedirect.com/science/article/abs/pii/S0031320301000474?via%3Dihub).

# `dilate!`
*since 0.23.0* 

```elixir
@spec dilate!(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()
```

Dilate an image mask, adding a pixels to the
edge of the mask or raising an exception.

Mask is used in the sense of an image, potentially
wuth an alpha band. The results on
other image types is undefined.

The added pixels are the same color as the edge
pixels in the mask.

### Arguments

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

* `radius` is an integer in the range `1..100`
  representing the approximate number of
  pixels to dilate. The default is `1`.

### Returns

* `dilated_mask` or

* raises an exception.

### Notes

* Dilate works for any non-complex image type, with any
  number of bands. The input is dilated by copying
  edge pixels before performing the operation so that
  the output image has the same size as the input.

* Edge pixels in the output image are only
  approximate.

* The dilation is implemented as a [rank filter](https://www.sciencedirect.com/science/article/abs/pii/S0031320301000474?via%3Dihub).

# `embed!`
*since 0.27.0* 

```elixir
@spec embed!(
  Vix.Vips.Image.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Embed.embed_options()
) :: Vix.Vips.Image.t() | no_return()
```

Embeds an image in a larger image canvas, generating
addition border pixels if required.

### Arguments

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

* `width` is the width in pixels of the canvas
  image.

* `height` is the height in pixels of the canvas
  image.

* `options` is a keyword list of options.

### Options

See `Image.embed/4`.

### Returns

* `embedded_image` or

* raises an exception.

# `erode`
*since 0.23.0* 

```elixir
@spec erode(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Erode an image mask, removing pixels from the
edge of the mask.

Mask is used in the sense of an image, potentially
with an alpha band. The results on
other image types is undefined.

### Arguments

* `image` is any non-complex-number `t:Vix.Vips.Image.t/0`.

* `radius` is an integer in the range `1..100`
  representing the approximate number of
  pixels to erode. The default is `1`.

### Returns

* `{:ok, eroded_mask}` or

* `{:error, reason}`

### Notes

* Erode works for any non-complex-number image type with any
  number of bands. The input is eroded by copying
  edge pixels before performing the operation so that
  the output image has the same size as the input.

* Edge pixels in the output image are only
  approximate.

* The erosion is implemented as a [rank filter](https://www.sciencedirect.com/science/article/abs/pii/S0031320301000474?via%3Dihub).

# `erode!`
*since 0.23.0* 

```elixir
@spec erode!(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()
```

Erode an image mask, removing pixels from the
edge of the mask or raising an exception.

Mask is used in the sense of an image, potentially
with an alpha band. The results on
other image types is undefined.

### Arguments

* `image` is any non-complex-number `t:Vix.Vips.Image.t/0`.

* `radius` is an integer in the range `1..100`
  representing the approximate number of
  pixels to erode. The default is `1`.

### Returns

* `eroded_mask` or

* raises an exception

### Notes

* Erode works for any non-complex-number image type with any
  number of bands. The input is eroded by copying
  edge pixels before performing the operation so that
  the output image has the same size as the input.

* Edge pixels in the output image are only
  approximate.

* The erosion is implemented as a [rank filter](https://www.sciencedirect.com/science/article/abs/pii/S0031320301000474?via%3Dihub).

# `extract_pages`
*since 0.44.0* 

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

Extract each page of a multi-page image into its
own image.

Not all image types support multi-page images.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` in `.gif`
   or `.png` multi-page format.

### Returns

* `{:ok, list_of_images}` or

* `{:error, reasom}`

### Notes

The `pages: :all` option should be used when opening the
multi-page image.

### Example

    iex> image = Image.open!("./test/support/images/animated.gif", pages: :all)
    iex> {:ok, list_of_images} = Image.extract_pages(image)
    iex> Enum.count(list_of_images)
    19

# `feather`
*since 0.13.0* 

```elixir
@spec feather(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Blur.blur_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Feather (blur the edges) of an image
mask.

Applies a gaussian blur to a one-band image
or the alpha band of a multi-band image
that can be used to smooth the blending of
one image into another.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` that is either
  a single band image or an image with an alpha band.

* `options` is a keyword list of options.

### Options

* `:sigma` is the `float` size of the mask
  to use. A larger number makes the image more
  blurry. A range between `1.0` and `10.0`
  is normally appropriate. The default is
  `5`.

* `:min_amplitude` is a `float` that determines
  the accuracy of the mask. The default is `0.2`.
  A smaller number will generate a larger, more
  accurate mask,

### Returns

* `{:ok, blurred_mask_image}` or

* `{:error, reason}`

# `feather!`
*since 0.13.0* 

```elixir
@spec feather!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Blur.blur_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Feather (blur the edges) of an image
mask returning an image or raising an
exception.

Applies a gaussian blur to a one-band image
or the alpha band of a multi-band image
that can be used to smooth the blending of
one image into another.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` that is either
  a single band image or an image with an alpha band.

* `options` is a keyword list of options.

### Options

* `:sigma` is the `float` size of the mask
  to use. A larger number makes the image more
  blurry. A range between `1.0` and `10.0`
  is normally appropriate. The default is
  `5`.

* `:min_amplitude` is a `float` that determines
  the accuracy of the mask. The default is `0.2`.
  A smaller number will generate a larger, more
  accurate mask,

### Returns

* `blurred_mask_image` or

* raises an exception.

# `flatten`
*since 0.23.0* 

```elixir
@spec flatten(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Flatten an alpha layer out of an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background_color` is an RGB color which is used
  to fill the transparent parts of the image.. The color
  can be an integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:black`.

### Returns

* `{:ok, flattened_image}` or

* `{:error, reason}`

# `flatten!`
*since 0.23.0* 

```elixir
@spec flatten!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Flatten an alpha layer out of an image
or raises an exception.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background_color` is an RGB color which is used
  to fill the transparent parts of the image.. The color
  can be an integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:black`.

### Returns

* `flattened_image` or

* raises an exception

# `flip`

```elixir
@spec flip(image :: Vix.Vips.Image.t(), direction :: :vertical | :horizontal) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Flip an image horizontally or vertically.

### Arguments

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

* `direction` is either `:horizontal` or
  `:vertical`.

### Returns

* `{:ok, flipped_image}` or

* `{:error, reason}`

# `flip!`

```elixir
@spec flip!(image :: Vix.Vips.Image.t(), direction :: :vertical | :horizontal) ::
  Vix.Vips.Image.t() | no_return()
```

Flip an image horizontally or vertically returning
a flipped image or raising an exception.

### Arguments

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

* `direction` is either `:horizontal` or
  `:vertical`.

### Returns

* `flipped_image` or

* raises an exception.

# `get_pixel`
*since 0.3.0* 

```elixir
@spec get_pixel(Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, Image.Pixel.t()} | {:error, error()}
```

Returns the pixel value at the given image location.

The returned pixel is a list of numbers where
the length of the list is equal to the number
of bands in the image.

If the colorspace of the image is `:srgb` then
the values are rounded.

### Arguments

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

* `x` is an integer offset from the top
  left of the image along the `x` (width) axis.
  The number must be in the range `0..width - 1`.

* `y` is an integer offset from the top
  left of the image along the `y` (height) axis.
  The number must be in the range `0..height - 1`.

### Returns

* `{:ok, pixel_value}` or

* `{:error, reason}`

# `get_pixel!`
*since 0.26.0* 

```elixir
@spec get_pixel!(Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer()) ::
  Image.Pixel.t() | no_return()
```

Returns the pixel value at the given image location
or raises an exception.

The returned pixel is a list of numbers where
the length of the list is equal to the number
of bands in the image.

### Arguments

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

* `x` is an integer offset from the top
  left of the image along the `x` (width) axis.
  The number must be in the range `0..width - 1`.

* `y` is an integer offset from the top
  left of the image along the `y` (height) axis.
  The number must be in the range `0..height - 1`.

### Returns

* `pixel_value` or

* raises an exception

# `hamming_distance`
*since 0.6.0* 

```elixir
@spec hamming_distance(
  image_1 :: Vix.Vips.Image.t(),
  image_2 :: Vix.Vips.Image.t(),
  hash_size :: pos_integer()
) :: {:ok, non_neg_integer()} | {:error, error()}
```

Returns the hamming distance of two images
or two image hashes.

A [hamming distance](https://en.wikipedia.org/wiki/Hamming_distance)
gives an indication of the similarity of two images.

In general, a hamming distance of less than `10` indicates
that the images are very similar.  A distance of
less than `20` suggests the images are quite similar. Any
other distance suggests the images have little in common.

### Arguments

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

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

Alternatively, both arguments may be image hashes
returned by `Image.dhash/1`. Both arguments must
be of the same type.

### Returns

* `{:ok, hamming_distance}` where hamming distance is
  a positive integer or

* `{:error, reason}`.

# `if_then_else`
*since 0.13.0* 

```elixir
@spec if_then_else(
  condition_image :: Vix.Vips.Image.t(),
  if_image :: image_or_color(),
  else_image :: image_or_color(),
  options :: Keyword.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Scans the `condition_image` cond and uses it to select
pixels from either the `if_image` or the `else_image`.

Non-zero means copy a pixel from `if_image`, `0` means
copy a pixel from `else_image`.

### Arguments

* `condition_image` is any image. Typically it is an image
  formed by the relation operations such as `Image.Math.greater_than/2`.

* `if_image_or_color` is either an `t:Vimage.t/0` or
  a `t:Image.Pixel.t/0`. If a color is provided then
  an image is constructed with the same shape as `condition_image`
  filled with the provided color.

* `else_image_or_color` is either an `t:Vimage.t/0` or
  a `t:Image.Pixel.t/0`. If a color is provided then
  an image is constructed with the same shape as `condition_image`
  filled with the provided color.

* `options` is a keyword list of options.

### Options

* `:blend` is a boolean indicating if a the operation should blend
  smoothly between `then` and `else` images. The default is `false`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

### Notes

Any image can have either 1 band or `n` bands, where `n`
is the same for all the non-1-band images. Single band
images are then effectively copied to make n-band images.

Images `if_image` and `else_image` are cast up to the
smallest common format. The `condition_image` is cast to
`{:u, 8}`.

If the images differ in size, the smaller images are
enlarged to match the largest by adding zero pixels along
the bottom and right.

The output image is calculated pixel by pixel as:

    (condition_image / 255) * if_image + (1 - condition_image / 255) * else_image

# `if_then_else!`
*since 0.30.0* 

```elixir
@spec if_then_else!(
  condition_image :: Vix.Vips.Image.t(),
  if_image :: image_or_color(),
  else_image :: image_or_color()
) :: Vix.Vips.Image.t() | no_return()
```

Scans the condition image cond and uses it to select
pixels from either the `if_image` or the `else_image`.
Raise an exception on error.

Non-zero means copy a pixel from `if_image`, `0` means
copy a pixel from `else_image`.

### Arguments

* `condition_image` is any image. Typically it is an image
  formed by the relation operations such as `Image.Math.greater_than/2`.

* `if_image_or_color` is either an `t:Vimage.t/0` or
  a `t:Image.Pixel.t/0`. If a color is provided then
  an image is constructed with the same shape as `condition_image`
  filled with the provided color.

* `else_image_or_color` is either an `t:Vimage.t/0` or
  a `t:Image.Pixel.t/0`. If a color is provided then
  an image is constructed with the same shape as `condition_image`
  filled with the provided color.

### Returns

* `image` or

* raises an exception.

### Notes

Any image can have either 1 band or `n` bands, where `n`
is the same for all the non-1-band images. Single band
images are then effectively copied to make n-band images.

Images `if_image` and `else_image` are cast up to the
smallest common format. The `condition_image` is cast to
`{:u, 8}`.

If the images differ in size, the smaller images are
enlarged to match the largest by adding zero pixels along
the bottom and right.

The output image is calculated pixel by pixel as:

    (condition_image / 255) * if_image + (1 - condition_image / 255) *`else_image`

# `local_contrast!`
*since 0.35.0* 

```elixir
@spec local_contrast!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.LocalContrast.local_contrast_options()
) :: Vix.Vips.Image.t() | no_return()
```

Apply a local contrast adjustment to an image
or raises an exception.

This function applies a [Constrast Limited Adaptive histogram equalization (CLAHE)](https://en.wikipedia.org/wiki/Adaptive_histogram_equalization#Contrast_Limited_AHE)
to improve contrast in images. It differs from ordinary histogram
equalization in the respect that the adaptive method computes several
histograms, each corresponding to a distinct section of the image, and
uses them to redistribute the lightness values of the image.

It is therefore suitable for improving the local contrast and
enhancing the definitions of edges in each region of an image,
hence the name of the function.

### Arguments

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

* `options` is a keyword list of options.

### Options

* :`window_size` is an integer indicating the size of
  the window (in pixels) into the image in which the contrast adjustment
  is calculated. The default is `3`.

* `:max_slope` is the integral level of brightening, between 0 and
  100, where 0 (the default) disables contrast limiting.

### Returns

* `adjusted_image` or

* raises an exception.

# `map`
*since 0.28.0* 

```elixir
@spec map(Vix.Vips.Image.t(), Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Applies a transformation matrix to an image.

A transformation matrix is returned by
`Image.transform_matrix/3`.

`Image.warp_perspective/4` uses this function to
apply a perspective transform to an image.

### Arguments

* `image` is any `t:Vimage.t/0`

* `transform_matrix` is a matrix returned by
  `Image.transform_matrix/3`.

### Returns

* `{:ok, mapped_image}` or

* `{:error, reason}`

# `map_join_pages`
*since 0.39.0* 

```elixir
@spec map_join_pages(Vix.Vips.Image.t(), (Vix.Vips.Image.t() ->
                                      {:ok, Vix.Vips.Image.t()}
                                      | {:error, error()})) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

For each page of an image, execute `fun/1` then
reassemble the pages.

If the function is successful for each page,
assemble the new pages (returned from `fun/1`)
into a new image.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` in `.gif`
   or `.png` multi-page format.

* `fun` is any 1-arity function that takes a
  page as a `t:Vix.Vips.Image.t/0` as its argument
  and is required to return either `{:ok, new_page_image}`
  or `{:error, reason}` as its return value.

### Returns

* `{:ok, mapped_joined_image}` where all the new pages returned
  from `fun/1` are assembled into `mapped_image` or

* `{:error, reason}`.

### Examples

    # The option `pages: -1` means load all the pages of a multi-page image.
    iex> image = Image.open!("./test/support/images/animated.webp", pages: :all)
    iex> {:ok, _mapped_image} = Image.map_join_pages(image, &Image.equalize/1)

    # Also works for .gif images
    iex> image = Image.open!("./test/support/images/animated.gif", pages: :all)
    iex> {:ok, _mapped_image} = Image.map_join_pages(image, &Image.equalize/1)

    # If an image isn't opened with `pages: :all` then only
    # the first page of an image is loaded.
    iex> image_2 = Image.open!("./test/support/images/animated.webp")
    iex> {:error, %Image.Error{reason: :missing_page_height}} = Image.map_join_pages(image_2, &Image.equalize/1)
    iex> :ok
    :ok

# `mutate`
*since 0.7.0* 

```elixir
@spec mutate(Vix.Vips.Image.t(), (Vix.Vips.MutableImage.t() -> any())) ::
  {:ok, Vix.Vips.Image.t()}
  | {:ok, {Vix.Vips.Image.t(), term()}}
  | {:error, error()}
```

Mutate an image with through the given
function.

Mutations, like those functions in the
`Image.Draw`, module are operations on
a *copy* of the base image and operations
are serialized through a gen_server in order
to maintain thread safety.

In order to perform multiple mutations without
coopying for each each mutation,`Image.mutate/2` takes
a function argument `fun` that is passed a
`t:Vix.Vips.MutableImage.t/0` as a parameter. In that
way several mutations can be safely applied withouout
copying the image prior to each mutation.

Although the image is not copied before each mutuation,
each mutable operation is still serialized behind
a genserver to ensure thread safety.

The functions in `Image.Draw` all support either
a `t:Vix.Vips.Image.t/0` or a `t:Vix.Vips.MutableImage.t/0`
as the image parameter.

When the parameter `fun` returns, the mutation
process is ended and a normal `t:Vix.Vips.Image.t/0`
is returned.

### Arguments

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

* `fun` is any 1-arity function that receives
  a `t:Vix.Vips.MutableImage.t/0` parameter. This function
  *must* return either `:ok` or `{:ok, term}`.

### Returns

* `{:ok, mutated_image}` or

* `{:error, reason}`

### Notes

The image is copied and operations are serialized behind a gen_server.
Only one copy is made but all operations will be serialized behind the
gen_server. When the function returns, the gen_server is broken down and
the underlying mutated `t:Vix.Vips.Image.t/0` is returned.

### Example

    iex> {:ok, image} = Image.open("./test/support/images/puppy.webp")
    iex> {:ok, _mutated_copy} =
    ...>   Image.mutate(image, fn mut_image ->
    ...>     cx = cy = div(Image.height(image), 2)
    ...>     {:ok, _image} = Image.Draw.circle(mut_image, cx, cy, 100, color: :green)
    ...>   end)

# `pixelate`
*since 0.14.0* 

```elixir
@spec pixelate(image :: Vix.Vips.Image.t(), scale :: number()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Pixelates an image.

Pixelation is the process of reducing the image
resolution while retaining the image dimensions.

### Arguments

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

* `scale` is the scale factor to apply to
  the image when it is pixelated. This means that
  one "pixel" is `image width * scale`. The default
  is `0.05`.

### Returns

* `{:ok, pixelated_image}` or

* `{:error, reason}`

# `pixelate!`
*since 0.14.0* 

```elixir
@spec pixelate!(image :: Vix.Vips.Image.t(), scale :: number()) ::
  Vix.Vips.Image.t() | no_return()
```

Pixelates an image or raise an exception.

Pixelation is the process of reducing the image
resolution while retaining the image dimensions.

### Arguments

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

* `scale` is the scale factor to apply to
  the image when it is pixelated. This means that
  one "pixel" is `image width * scale`. The default
  is `0.05`.

### Returns

* `pixelated_image` or

* raises an exception

# `reduce_noise`
*since 0.35.0* 

```elixir
@spec reduce_noise(image :: Vix.Vips.Image.t(), window_size :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Reduces noise in an image by applying a median
filter.

The implementation uses a [median rank filter](https://en.wikipedia.org/wiki/Median_filter)
based on ordering the pixel values under a convolution kernel of a given
window size and extracting the median value.

The result is appropriate for removing
[salt and pepper noise](https://en.wikipedia.org/wiki/Salt-and-pepper_noise) and
may be useful for smoothing gaussian noise in some cases.

### Arguments

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

* `window_size` is the integer size of the convolution kernel used
  in the median rank filter. The default is `3`.

### Returns

* `{:ok, reduced_noise_image}` or

* `{:error, reason}`

# `reduce_noise!`
*since 0.35.0* 

```elixir
@spec reduce_noise!(image :: Vix.Vips.Image.t(), window_size :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()
```

Reduces noise in an image by applying a median
filter or raises an exception.

The implementation uses a [median rank filter](https://en.wikipedia.org/wiki/Median_filter)
based on ordering the pixel values under a convolution kernel of a given
window size and extracting the median value.

The result is appropriate for removing
[salt and pepper noise](https://en.wikipedia.org/wiki/Salt-and-pepper_noise) and
may be useful for smoothing gaussian noise in some cases.

### Arguments

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

* `window_size` is the integer size of the convolution kernel used
  in the median rank filter. The default is `3`.

### Returns

* `reduced_noise_image` or

* raises an exception.

# `ripple`

```elixir
@spec ripple(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Adds a concentric ripple effect to an image.

### Arguments

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

### Returns

* `{:ok, image_with_ripple}` or

* `{:error, reason}`

# `ripple!`

```elixir
@spec ripple!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Adds a concentric ripple effect to an image
returning an image or raising an exception.

### Arguments

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

### Returns

* `image_with_ripple` or

* raises an exception.

# `rotate`

```elixir
@spec rotate(
  image :: Vix.Vips.Image.t(),
  angle :: float(),
  options :: Image.Options.Rotate.rotation_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Rotate an image clockwise (to the
right) by a number of degrees.

### Arguments

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

* `angle` is a `float` number of degrees
  to rotate in a clockwise direction.

* `options` is a keyword list of options.

### Options

* `:idy` is the vertical input displacement which
  defaults to `0.0`

* `:idx` is the horizontal input displacement which
  defaults to `0.0`

* `:ody` is the vertical output displacement
  which defaults to `0.0`

* `:odx` is the horizontal output displacement
  which defaults to `0.0`

* `:background` is the background color to be used for filling
  the blank areas of the image. The background is specified as
  a list of 3 or 4 float values depending on the image
  color space.

## Notes

The displacement parameters cause the image canvas to be
expanded and the image displaced, relative to the top left
corner of the image, by the amount specified.

The rules defining how the image canvas is expanded
is not known to the author of `Image`. Experimentation will
be required if you explore these options.

### Returns

* `{:ok, rotated_image}` or

* `{:error, reason}`

# `rotate!`

```elixir
@spec rotate!(
  image :: Vix.Vips.Image.t(),
  angle :: float(),
  options :: Image.Options.Rotate.rotation_options()
) :: Vix.Vips.Image.t() | no_return()
```

Rotate an image clockwise (to the
right) by a number of degrees.

### Arguments

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

* `angle` is a `float` number of degrees
  to rotate in a clockwise direction.

* `options` is a keyword list of options.
  See `Image.rotate/3`.

## Notes

The displacement parameters cause the image canvas to be
expanded and the image displaced, relative to the top left
corner of the image, by the amount specified.

The rules defining how the image canvas is expanded
is not known to the author of `Image`. Experimentation will
be required if you explore these options.

### Returns

* `rotated_image` or

* raises an exception.

# `sharpen`
*since 0.35.0* 

```elixir
@spec sharpen(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Sharpen.sharpen_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Sharpens an image.

Selectively sharpens the `L` channel of a LAB image. `image`
is converted to `:labs` for sharpening and the converted back
to its original interpretation.

The operation performs a gaussian blur and subtracts from `image` to generate a
high-frequency signal. This signal is passed through a lookup table formed
from the five parameters and then added back to `image`.

The lookup table is formed like this:

```
                    ^
                 y2 |          -----------
                    |         /
                    |        / slope m2
                    |    .../
            -x1     | ...   |
-------------------...---------------------->
            |   ... |      x1
            |... slope m1
            /       |
           / m2     |
          /         |
         /          |
        /           |
       /            |
______/             | -y3
                    |
```

Where:

* `m1` is `:flat_amount`
* `m2` is `:jagged_amount`
* `x1` is `:threshold`
* `y2` is `:max_brightening`
* `y3` is `:max_darkening`

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:jagged_amount` is the primary means of specifing how much
  sharpening to apply. Shaprening is applied to the jagged areas
  of the image. It is a float greater or equal to `0.0`
  with a default of `3.0`.

* `:flat_amount` is the specifies how much
  sharpening to apply to flat areas of the image. It is a float
  greater or equal to `0.0` with a default of `0.0`.

* `:threshold` indicates where the transition from the flat
  part of the image to the jaggy part of the image is to be
  considered on the curve. It is a float amount greater than
  or equal to `0.0` with a default of `2.0`.

* `:max_brightening` specifies how much the image may be
  brightened as part of the sharpening process. It is a positive
  integer greater than or equal to `0`. The default is `10`.

* `:max_darkening` specifies how much the image may be
  darkened as part of the sharpening process. It is a positive
  integer greater than or equal to `0`. The default is `20`.

* `:sigma` changes the width of the sharpening fringe and can be
  adjusted according to the output printing resolution. As an approximate
  guideline, use `0.5` for 4 pixels/mm (display resolution),
  `1.0` for 12 pixels/mm and `1.5` for 16 pixels/mm (300 dpi == 12
  pixels/mm). These figures refer to the image raster, not the half-tone
  resolution. The default is `0.5`.

### Returns

* `{:ok, sharpened_image}` or

* `{:error reason}`

### Output sharpening

For screen output sharpening the default options are recommended.
Adjust `:sigma` for other output devices as required.

# `sharpen!`
*since 0.35.0* 

```elixir
@spec sharpen!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Sharpen.sharpen_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Sharpens an image or raises an exception.

Selectively sharpens the `L` channel of a LAB image. `image`
is converted to `:labs` for sharpening and the converted back
to its original interpretation.

The operation performs a gaussian blur and subtracts from `image` to generate a
high-frequency signal. This signal is passed through a lookup table formed
from the five parameters and then added back to `image`.

The lookup table is formed like this:

```
                    ^
                 y2 |          -----------
                    |         /
                    |        / slope m2
                    |    .../
            -x1     | ...   |
-------------------...---------------------->
            |   ... |      x1
            |... slope m1
            /       |
           / m2     |
          /         |
         /          |
        /           |
       /            |
______/             | -y3
                    |
```

Where:

* `m1` is `:flat_amount`
* `m2` is `:jagged_amount`
* `x1` is `:threshold`
* `y2` is `:max_brightening`
* `y3` is `:max_darkening`

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:jagged_amount` is the primary means of specifing how much
  sharpening to apply. Shaprening is applied to the jagged areas
  of the image. It is a float greater or equal to `0.0`
  with a default of `3.0`.

* `:flat_amount` is the specifies how much
  sharpening to apply to flat areas of the image. It is a float
  greater or equal to `0.0` with a default of `0.0`.

* `:threshold` indicates where the transition from the flat
  part of the image to the jaggy part of the image is to be
  considered on the curve. It is a float amount greater than
  or equal to `0.0` with a default of `2.0`.

* `:max_brightening` specifies how much the image may be
  brightened as part of the sharpening process. It is a positive
  integer greater than or equal to `0`. The default is `10`.

* `:max_darkening` specifies how much the image may be
  darkened as part of the sharpening process. It is a positive
  integer greater than or equal to `0`. The default is `20`.

* `:sigma` changes the width of the sharpening fringe and can be
  adjusted according to the output printing resolution. As an approximate
  guideline, use `0.5` for 4 pixels/mm (display resolution),
  `1.0` for 12 pixels/mm and `1.5` for 16 pixels/mm (300 dpi == 12
  pixels/mm). These figures refer to the image raster, not the half-tone
  resolution. The default is `0.5`.

### Returns

* `sharpened_image` or

* raises an exception.

### Output sharpening

For screen output sharpening the default options are recommended.
Adjust `:sigma` for other output devices as required.

# `split_alpha`
*since 0.13.0* 

```elixir
@spec split_alpha(image :: Vix.Vips.Image.t()) ::
  {bands :: Vix.Vips.Image.t(), alpha :: Vix.Vips.Image.t() | nil}
```

Split an image to separate the alpha band
from the other image bands.

### Arguments

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

### Returns

* `{image_without_alpha, alpha_band}` or

* `{image, nil}` if there is no
  alpha band detected.

# `to_polar_coordinates`

```elixir
@spec to_polar_coordinates(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Convert image to polar coordinates.

### Arguments

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

### Returns

* `{:ok, image_in_polar_coordinates}` or

* `{:error, reason}`

# `to_polar_coordinates!`

```elixir
@spec to_polar_coordinates!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Convert image to polar coordinates returning
an image or raising an exception.

### Arguments

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

### Returns

* `image_in_polar_coordinates` or

* raises an exception.

# `to_rectangular_coordinates`

```elixir
@spec to_rectangular_coordinates(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Convert image to rectangular coordinates.

### Arguments

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

## Notes

Roundtrip to polar and back to rectangular
coordinates displays some image distortion,
likely due to rounding errors in float
arithmetic. Further study is required.

### Returns

* `{:ok, image_in_rectangular_coordinates}` or

* `{:error, reason}`

# `to_rectangular_coordinates!`

```elixir
@spec to_rectangular_coordinates!(Vix.Vips.Image.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Convert image to rectangular coordinates
returning an image or raising an exception.

### Arguments

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

## Notes

Roundtrip to polar and back to rectangular
coordinates displays some image distortion,
likely due to rounding errors in float
arithmetic. Further study is required.

### Returns

* `image_in_rectangular_coordinates` or

* raises an exception.

# `vibrance`
*since 0.54.0* 

```elixir
@spec vibrance(
  image :: Vix.Vips.Image.t(),
  vibrance :: float(),
  options :: Image.Options.Vibrance.vibrance_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply an curve adjustment to an image's saturation
(chroma) such that less saturated colors are more
affected than more saturated colors.

This operation is similar to the vibrance function
in Adobe Lightroom. However this implementation does
not account for skin tones.

### Arguments

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

* `vibrance` is any float greater than `0.0`. A number less
  than `1.0` means reduce vibrance. A number greater than `1.0`
  means increase vibrance.

* `options` is a keyword list of options.

### Options

* `:threshold` is the saturation level above which no
  adjustment is made. The range is `1..100` with a default
  of `70`.

### Returns

* `{:ok, adjusted_image}` or

* `{:error, reason}`.

# `vibrance!`
*since 0.54.0* 

```elixir
@spec vibrance!(
  image :: Vix.Vips.Image.t(),
  vibrance :: float(),
  options :: Image.Options.Vibrance.vibrance_options()
) :: Vix.Vips.Image.t() | no_return()
```

Apply an curve adjustment to an image's saturation
(chroma) such that less saturated colors are more
affected than more saturated colors. Raises on
error.

This operation is similar to the vibrance function
in Adobe Lightroom. However this implementation does
not account for skin tones.

### Arguments

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

* `vibrance` is any float greater than `0.0`. A number less
  than `1.0` means reduce vibrance. A number greater than `1.0`
  means increase vibrance.

* `options` is a keyword list of options.

### Options

* `:threshold` is the saturation level above which no
  adjustment is made. The range is `1..100` with a default
  of `60`.

### Returns

* `adjusted_image` or

* raises an exception.

# `with_band_format`
*since 0.35.0* 

```elixir
@spec with_band_format(
  Vix.Vips.Image.t(),
  band_format :: Image.BandFormat.t(),
  (Vix.Vips.Image.t() -> {:ok, Vix.Vips.Image.t()} | {:error, error()})
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Execute a function over the image casting it
first to a different band format and ensuring the band
format reverted when the function returns.

### Arguments

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

* `band_format` is any valid band format.
  See `Image.BandFormat.known_band_formats/0`.

* `fun` is any 1-arity function that is
  required to return `{:ok, image}` or
  `{:error, reason}`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

### Example

    iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
    iex> {:ok, updated_image} = Image.with_band_format(image, {:s, 16}, fn i -> {:ok, i} end)
    iex> Image.band_format(updated_image)
    {:u, 8}

# `with_colorspace`
*since 0.29.0* 

```elixir
@spec with_colorspace(
  Vix.Vips.Image.t(),
  colorspace :: Image.Interpretation.t(),
  (Vix.Vips.Image.t() -> {:ok, Vix.Vips.Image.t()} | {:error, error()})
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Execute a function over the image casting it
first to a color space and ensuring the color
space conversion is reverted when the function
returns.

### Arguments

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

* `colorspace` is any valid color space.
  See `Image.Interpretation.known_interpretations/0`.

* `fun` is any 1-arity function that is
  required to return `{:ok, image}` or
  `{:error, reason}`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

# `without_alpha_band`
*since 0.29.0* 

```elixir
@spec without_alpha_band(
  Vix.Vips.Image.t(),
  (Vix.Vips.Image.t() -> {:ok, Vix.Vips.Image.t()} | {:error, error()})
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Execute a function over the image without
its alpha band (if any) ensuring the alpha
band is replaced when the function returns.

### Arguments

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

* `fun` is any 1-arity function that is
  required to return `{:ok, image}` or
  `{:error, reason}`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

# `embed`
*since 0.27.0* 

```elixir
@spec embed(
  image :: Vix.Vips.Image.t(),
  width :: non_neg_integer(),
  height :: non_neg_integer(),
  options :: Image.Options.Embed.embed_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Embeds an image in a larger image canvas, generating
addition border pixels if required.

### Arguments

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

* `width` is the width in pixels of the canvas
  image.

* `height` is the height in pixels of the canvas
  image.

* `options` is a keyword list of options.

### Options

* `:x` is the x-offset into the canvas image
  where `image` will be embedded. The value may be
  a positive integer indicating a 0-based offset from
  the left of the canvas or a negative integer indicating
  a 1-based offset from the right side of the image.
  It may also be `:center` (the default) in which case the
  image will be centered horizontally within the canvas.

* `:y` is the y-offset into the canvas image
  where `image` will be embedded. The value may be
  a positive integer indicating a 0-based offset from
  the top of the canvas or a negative integer indicating
  a 1-based offset from the bottom of the image.
  It may also be `:center` (the default) in which case the
  image will be centered vertically within the canvas.

* `:background_color` defines the color of the generated background
  pixels. This can be specified as a single integer which will
  be applied to all bands, or a list of integers representing
  the color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of
  the form `#rrggbb`. The default is `:black`. `:background` can
  also be set to `:average` in which case the background will be
  the average color of the base image. See also `Color.new/2`
  from the Color library.

* `:background_transparency` defines the transparency of the
  `:background` pixels when `image` has an alpha band.
  The default is `:opaque`. The values are an integer in the
  range `0..255` where `0` is transparent and `255` is opaque.
  The number can also be a float in the range `0.0` to `1.0`.
  In this case the float is converted to an integer in the range
  `0..255`. Lastly, the atoms `:transparent` and `:opaque` can
  also be used.

* `:extend_mode` determines how any additional pixels
  are generated. The values are:

  * `:black` (the default if no `background_color` is specified)
    meaning the generated pixels are black.
  * `:white` meaning the generated pixels are white.
  * `:copy` means the generated pixels take the value of the
    nearest edge pixel of the base image.
  * `:repeat` means the generated pixels are tiles from the
    base image.
  * `:mirror` means the generated pixels are reflected tiles of
    the base image.
  * `:background` means the generated pixels are the `:background_color`
    color set in `options`. This is the default if a `background_color`
    is specified.

### Returns

* `{:ok, embedded_image}` or

* `{:error, reason}`

# `find_trim`
*since 0.56.0* 

```elixir
@spec find_trim(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Trim.trim_options()
) ::
  {:ok, bounding_box()} | {:error, error()}
```

Finds the bounding box of the non-background
area.

The image is median-filtered, all the row and column sums
of the absolute difference from background are calculated
in a single pass.

Then the first row or column in each of the four directions
where the sum is greater than threshold gives the bounding
box.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background` is the color to be considered
  the background color. The default is automatically
  detected by averaging the pixels at the top
  left of the image. If background is set to
  `:alpha` then the image is trimmed to the size
  of the alpha mask.

* `:threshold` is the integer threshold (or color
  similarity) that is applied when determining the
  bounds of the non-background area. The default is
  `10`. The default value means only a small color
  background color range is considered.  Increasing
  the threshold value maybe required.

### Returns

* `{:ok, {left, top, width, height}}` which is the bounding box
  of the non-background area or

* `{:error, reason}`.

# `find_trim!`
*since 0.56.0* 

```elixir
@spec find_trim!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Trim.trim_options()
) ::
  bounding_box() | no_return()
```

Finds the bounding box of the non-background
area or raises an error.

The image is median-filtered, all the row and column sums
of the absolute difference from background are calculated
in a single pass.

Then the first row or column in each of the four directions
where the sum is greater than threshold gives the bounding
box.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background` is the color to be considered
  the background color. The default is automatically
  detected by averaging the pixels at the top
  left of the image. If background is set to
  `:alpha` then the image is trimmed to the size
  of the alpha mask.

* `:threshold` is the integer threshold (or color
  similarity) that is applied when determining the
  bounds of the non-background area. The default is
  `10`. The default value means only a small color
  background color range is considered.  Increasing
  the threshold value maybe required.

### Returns

* `{left, top, width, height}` which is the bounding box
  of the non-background area or

* raises an exception.

# `resize`
*since 0.13.0* 

```elixir
@spec resize(
  Vix.Vips.Image.t(),
  scale :: number(),
  options :: Image.Options.Resize.resize_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Resize an image.

If the intent is to thumbnail an image then `Image.thumbnail/3`
is recommended since it applies a very efficient downsizing
algorithm for that use case.

### Arguments

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

* `scale` is a float scale factor.

* `options` is a keyword list of options.

### Options

* `:centre` is a boolean indicating whether to use
  the centre downsampling convention. The default is
  `false`.

* `:interpolate` defines which resampling kernel to apply.
  The options are `:nearest`, `:linear`, `:cubic`,
  `:mitchell`, `:lanczos2` or `:lanczos3` (the default).

* `:vertical_scale` is a float indicating the scaling
  factor of the vertical axis. In specified, then `scale`
  is applied only to the horizontal axis.

### Returns

* `{:ok, resized_image}` or

* raises an exception

# `resize!`
*since 0.14.0* 

```elixir
@spec resize!(
  Vix.Vips.Image.t(),
  scale :: number(),
  options :: Image.Options.Resize.resize_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Resize an image or raise an exception.

If the intent is to thumbnail an image then `Image.thumbnail/3`
is recommended since it applies a very efficient downsizing
algorithm for that use case.

### Arguments

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

* `scale` is a float scale factor.

* `options` is a keyword list of options.

### Options

* `:centre` is a boolean indicating whether to use
  the centre downsampling convention. The default is
  `false`.

* `:interpolate` defines which resampling kernel to apply.
  The options are `:nearest`, `:linear`, `:cubic`,
  `:mitchell`, `:lanczos2` or `:lanczos3` (the default).

* `:vertical_scale` is a float indicating the scaling
  factor of the vertical axis. In specified, then `scale`
  is applied only to the horizontal axis.

### Returns

* `resized_image` or

* raises an exception

# `thumbnail`

```elixir
@spec thumbnail(
  Vix.Vips.Image.t(),
  length :: pos_integer(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
@spec thumbnail(
  Path.t(),
  length :: pos_integer(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
@spec thumbnail(
  Vix.Vips.Image.t() | Path.t(),
  dimensions :: binary(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Thumbnail an image to fit or fill a bounding box.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` or a
  pathname to an image file.

* `length` is the integer length of the longest
  side of the resulting image after resizing. It can
  also be of the form "<width>x<height>". That
  is, a string with the width and height separated
  by an `x`. The `<height>` may be omitted in which
  case it is the same as providing an integer length.

* `options` is a keyword list of options.

### Options

* `:crop` determines if the strategy is "resize to fit"
  (crop is `:none`) or "resize to fill" (when the crop
  option is not `:none`). The value may be one of
  `:none`, `:center`, `:entropy`, `:attention`, `:low`
  or `:high`. The default is `:none`. See also `t:Image.Options.Crop.crop_focus/0`.

* `:height` - Size to this height. Default is to maintain
  the image aspect ratio unless `resize: :force` is set. If
  `resize; :force` is set then the default `:height` is the
  height of `image`.

* `:fit` sets the `:crop` and `:resize` options to align
  with the CSS [object-fit](https://www.w3schools.com/css/css3_object-fit.asp)
  property. Note that using the `:fit` option overwrites the
  options `:crop` and `:resize`. Since options are processed in
  the order in which they are presented, `:crop` and `:resize`
  may still be force set if they are after the `:fit` option.
  `:fit` takes one of the following values:

  * `:fill` - the image is resized to fill the given dimension.
    If necessary, the image will be stretched or squished to fit.
    This is the same as setting `resize: :force`. Note that is
    `:height` is not specified it will be the same height as `image`.

  * `:contain` - the image keeps its aspect ratio, but is resized
    to fit within the given dimension. This is the same as
    setting `crop: :none` and `resize: :both`.

  * `:cover` - the image keeps its aspect ratio and fills the given
    dimensions. The image will be clipped to fit. Clipping will default to
    `:center` unless `:crop` is already set to a value other
    than `:none`. This is the same as setting `crop: :center`
    (if `:crop` is not already set) and `resize: :both`.

* `:autorotate` is a boolean indicating if the image should
  be autorotated based upon the image metadata. The default
  is `true`.

* `:intent` indicates the rendering intent. The default
  is `:relative`. See also `t:Image.render_intent/0`.

* `:export_icc_profile` indicates the icc profile to be attached
  to the resized image. The value may be an inbuilt profile (`:srgb`,
  `:p3` or `:cmyk`), the name of an icc profile in the systems
  profile directory or a full path to an icc profile file. The
  default is to export the icc profile of the resized image if
  there is one.

* `:import_icc_profile` indicates the icc profile to be attached
  to the input image. The value may be an inbuilt profile (`:srgb`,
  `:p3` or `:cmyk`), the name of an icc profile in the systems
  profile directory or a full path to an icc profile file. The
  default is to use the icc profile of the input image if
  there is one.

* `:linear` is a boolean indicating of the image should
  be resized in linear space. The default `false`. Shrinking is
  normally done in sRGB colourspace. Set linear to shrink in
  linear light colourspace instead. This can give better results,
  but can also be far slower, since tricks like JPEG shrink-on-load
  cannot be used in linear space.

* `:resize` determines if an image may be only upsized, only
  downsized, both or a forced aspect ratio is applied. The value
  may be one of `:up`, `:down`, `:both` or `:force`. The default
  is `:both`.

### Returns

* `{:ok, thumbnailed_image}` or

* `{:error, reason}`

# `thumbnail!`

```elixir
@spec thumbnail!(
  Vix.Vips.Image.t(),
  length :: pos_integer(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: Vix.Vips.Image.t() | no_return()
@spec thumbnail!(
  Path.t(),
  length :: pos_integer(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: Vix.Vips.Image.t() | no_return()
@spec thumbnail!(
  Vix.Vips.Image.t() | Path.t(),
  dimensions :: binary(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: Vix.Vips.Image.t() | no_return()
```

Thumbnail an image to fit or fill a bounding box
returning an image or raising an exception.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` or a
  pathname to an image file.

* `length` is the integer length of the longest
  side of the resulting image after resizing. It c
  an also be of the form "<width>x<height>". That
  is, a string with the width and height separated
  by an `x`. The `<height>` may be omitted in which
  case it is the same as providing an integer length.

* `options` is a keyword list of options.
  See `Image.thumbnail/3`.

### Returns

* `image` or

* raises an exception.

# `trim`
*since 0.23.0* 

```elixir
@spec trim(image :: Vix.Vips.Image.t(), options :: Image.Options.Trim.trim_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Trims an image to the bounding box of the non-background
area.

The image is median-filtered, all the row and column sums
of the absolute difference from background are calculated
in a single pass.

Then the first row or column in each of the four directions
where the sum is greater than threshold gives the bounding
box that is used to define the crop area.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background` is the color to be considered
  the background color. The default is automatically
  detected by averaging the pixels at the top
  left of the image. If background is set to
  `:alpha` then the image is trimmed to the size
  of the alpha mask.

* `:threshold` is the integer threshold (or color
  similarity) that is applied when determining the
  bounds of the non-background area. The default is
  `10`. The default value means only a small color
  background color range is considered.  Increasing
  the threshold value maybe required.

### Returns

* `{:ok, cropped_image}` which is the image
  cropped to the bounding box of the non-background
  area.

* `{:error, reason}`.  Reason may be
  `:uncropped` which means the image was
  considered to be only the background color.

# `trim!`
*since 0.23.0* 

```elixir
@spec trim!(image :: Vix.Vips.Image.t(), options :: Image.Options.Trim.trim_options()) ::
  Vix.Vips.Image.t() | no_return()
```

Trims an image to the bounding box of the non-background
area or raises an exception.

The image is median-filtered, all the row and column sums
of the absolute difference from background are calculated
in a single pass.

Then the first row or column in each of the four directions
where the sum is greater than threshold gives the bounding
box that is used to define the crop area.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:background` is the color to be considered
  the background color. The default is automatically
  detected by averaging the pixels at the top
  left of the image. If background is set to
  `:alpha` then the image is trimmed to the size
  of the alpha mask.

* `:threshold` is the integer threshold (or color
  similarity) that is applied when determining the
  bounds of the non-background area. The default is
  `10`. The default value means only a small color
  background color range is considered.  Increasing
  the threshold value maybe required.

### Returns

* `cropped_image` which is the image
  cropped to the bounding box of the non-background
  area or

* raises an exception.

# `center_crop`
*since 0.27.0* 

```elixir
@spec center_crop(
  image :: Vix.Vips.Image.t(),
  width :: pos_integer(),
  height :: pos_integer()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Crops the center from an image.

### Arguments

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

* `width` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `width` is an integer it is the absolute number
  of pixels. If `width` is a float it is the fraction
  of the original image width.

* `height` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `height` is an integer it is the absolute number
  of pixels. If `height` is a float it is the fraction
  of the original image height.

### Notes

* An error will be returned if `width` and `height` are
  not equal to or smaller than the `image` dimensions.

* This function is a convenience function equivalent to
  calling `Image.crop(image, :center, :middle, width, height)`.

### Returns

* `{:ok, cropped_image}` or

* `{:error, reason}`.

# `center_crop!`
*since 0.27.0* 

```elixir
@spec center_crop!(Vix.Vips.Image.t(), pos_integer(), pos_integer()) ::
  Vix.Vips.Image.t() | no_return()
```

Crops the center from an image.

### Arguments

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

* `width` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `width` is an integer it is the absolute number
  of pixels. If `width` is a float it is the fraction
  of the original image width.

* `height` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `height` is an integer it is the absolute number

  of pixels. If `height` is a float it is the fraction
  of the original image height.

### Notes

* An error will be returned if `width` and `height` are
  not equal to or smaller than the `image` dimensions.

* This function is a convenience function equivalent to
  calling `Image.crop!(image, :center, :middle, width, height)`.

### Returns

* `cropped_image` or

* raises an exception.

# `crop`
*since 0.28.0* 

```elixir
@spec crop(Vix.Vips.Image.t(), quadrilateral()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Crop an image.

### Arguments

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

* `quadrilateral` is a list of four 2-tuples
  representing the points of the bounding rectangle. The
  points must be ordered as `[top_left, top_right, bottom_right, bottom_left]`
  Each point is of the form `{x, y}` where `x` is the
  0-based offset from the left of the image and `y` is
  the 0-based offset from the top of the image.

### Returns

* `{:ok, cropped_image}` or

* `{:error, reason}`

### Note

The bounding box must be a rectangle, not an
arbitrary quadrilateral. If required, use `Image.warp_perspective/4`
prior to cropping.

# `crop`

```elixir
@spec crop(
  image :: Vix.Vips.Image.t(),
  left :: x_location(),
  top :: y_location(),
  width :: pos_integer(),
  height :: pos_integer()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Crop an image.

### Arguments

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

* `left` is the top edge of crop area as an
  integer or a float in the range `-1.0..1.0`.
  If `left` is an integer it is the absolute number
  of pixels. If `left` is a float it's a fraction of the width
  of the image. If `left` is positive it is relative to
  the left edge of the image. If it's negative it's
  relative to the right edge of the image. `left` may
  also be one of `:left`, `:center` and `:right`
  indicating the crop is relative to the left, center
  or right of the image.

* `top` is the top edge of crop area as an
  integer or a float in the range `-1.0..1.0`.
  If `top` is an integer it is the absolute number of
  pixels. If `top` is a float it's a fraction of the height
  of the image. If `top` is positive it is relative to
  the top edge of the image. If it's negative it's
  relative to the bottom edge of the image. `top` may
  also be one of `:top`, `:middle` and `:bottom`
  indicating the crop is relative to the top, middle
  or bottom of the image.

* `width` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `width` is an integer it is the absolute number
  of pixels. If `width` is a float it's the fraction
  of the original image width.

* `height` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `height` is an integer it's the absolute number
  of pixels. If `height` is a float it's the fraction
  of the original image height.

### Notes

* `left` is 0-indexed. That is, the leftmost
  edge of the image starts at `0`.

* `top` is 0-indexed. That is, the topmost
  edge of the image starts at `0`.

* If the image has multiple pages, like an animated
  `.gif` or `.webp` then each page is extracted,
  cropped and then the image reassembled.

### Returns

* `{:ok, cropped_image}` or

* `{:error, reason}`

# `crop!`
*since 0.28.0* 

```elixir
@spec crop!(Vix.Vips.Image.t(), quadrilateral()) :: Vix.Vips.Image.t() | no_return()
```

Crop an image or raises an exception.

### Arguments

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

* `quadrilateral` is a list of four 2-tuples
  representing the points of the bounding rectangle. The
  points must be ordered as `[top_left, top_right, bottom_right, bottom_left]`
  Each point is of the form `{x, y}` where `x` is the
  0-based offset from the left of the image and `y` is
  the 0-based offset from the top of the image.

### Returns

* `cropped_image` or

* raises an exception.

### Note

The bounding box must be a rectangle, not an
arbitrary quadrilateral. If required, use `Image.warp_perspective/4`
prior to cropping.

# `crop!`

```elixir
@spec crop!(
  image :: Vix.Vips.Image.t(),
  left :: x_location(),
  top :: y_location(),
  width :: pos_integer(),
  height :: pos_integer()
) :: Vix.Vips.Image.t() | no_return()
```

Crop an image returning a cropped image
or raising an exception.

### Arguments

* `left` is the top edge of crop area as an
  integer or a float in the range `-1.0..1.0`.
  If `left` is an integer it is the absolute number
  of pixels. If `left` a float is fraction of the width
  of the image. If `left` is positive it is relative to
  the left edge of the image. If it is negative it is
  relative to the right edge of the image. `left` may
  also be one of `:left`, `:center` and `:right`
  indicating the crop is relative to the left, center
  or right of the image.

* `top` is the top edge of crop area as an
  integer or a float in the range `-1.0..1.0`.
  If `top` is an integer it is the absolute number of
  pixels. If `top` is a float is fraction of the height
  of the image. If `top` is positive it is relative to
  the top edge of the image. If it is negative it is
  relative to the bottom edge of the image. `top` may
  also be one of `:top`, `:middle` and `:bottom`
  indicating the crop is relative to the top, middle
  or bottom of the image.

* `width` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `width` is an integer it is the absolute number
  of pixels. If `width` is a float it is the fraction
  of the original image width.

* `height` is the width of area remaining as a
  positive integer or float in the range `0.0..1.0`.
  If `height` is an integer it is the absolute number
  of pixels. If `height` is a float it is the fraction
  of the original image height.

### Returns

* `cropped_image` or

* raises an exception.

# `avatar`

```elixir
@spec avatar(Vix.Vips.Image.t(), options :: Image.Options.Avatar.avatar_options()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Make a circular, squircular or square image intended to be used
as an avatar image.

The image is resized and all metadata is removed
from the image. The image will be cropped to a square
shape and then depending on the `:shape` option
a circular or squircular mask may be applied.

### Arguments

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

* `options` is a keyword list of options. The
  default is `[shape: :circle, crop: :none, size: 180]`.

### Options

* `:size` is the diameter in pixels of the avatar (in the case of
  `shape: :circle` or `shape; :squircle`. It is the width/height in
  pixels in the case of a `shape: :square` avatar.
  The default value is `180`.

* `:shape` defines shape of the avatar
  which can be either `:circle` (the default), `:squircle`
  or `:square`.  In each case the image is first
  cropped to a square shape. Then if the
  format is `:circle` or `:squircle` an appropriate image
  mask is applied.

* `:crop_focus` is one of `:center`, `:entropy`,
  `:attention`, `:low`, `:high`. The default is `:center`.
  For details see `t:Image.Options.Crop.crop_focus/0`.

### Returns

* `{:ok, avatar_image}` or

* `{:error, reason}`

# `avatar!`

```elixir
@spec avatar!(Vix.Vips.Image.t(), options :: Image.Options.Avatar.avatar_options()) ::
  Vix.Vips.Image.t() | no_return()
```

Make a circular, squircular or square image intended to be used
as an avatar image or raise an exception.

The image is resized and all metadata is removed
from the image. The image will be cropped to a square
shape and then depending on the `:shape` option
a circular or squirclar mask may be applied.

### Arguments

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

* `options` is a keyword list of options. The
  default is `[shape: :circle, crop: :none, size: 180]`.

### Options

* `:size` is the diameter in pixels of the avatar (in the case of
  `shape: :circle` or `shape; :squircle`. It is the width/height in
  pixels in the case of a `shape: :square` avatar.
  The default value is `180`.

* `:shape` defines shape of the avatar
  which can be either `:circle` (the default), `:squircle`
  or `:square`.  In each case the image is first
  cropped to a square shape. Then if the
  format is `:circle` or `:squircle` an appropriate image
  mask is applied.

* `:crop_focus` is one of `:center`, `:entropy`,
  `:attention`, `:low`, `:high`. The default is `:center`.
  For details see `t:Image.Options.Crop.crop_focus/0`.

### Returns

* `avatar_image` or

* raises an exception.

# `linear_gradient`

```elixir
@spec linear_gradient(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Create an image gradient the size of a given
image, or the size of the given dimenssion.

The gradient will be interpolated from the `start_color`
value to the `finish_color` value.

### Arguments using a template image

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

* `options` is a keyword list of options.

### Arguments supplying a width and height

* `width` is the width in pixels of the gradient image.

* `height` is the height in pixels of the gradient image.

* `options` is a keyword list of options. See
  `t:Image.Options.LinearGradient.linear_gradient_option/0`.

### Options

* `:start_color` is an sRGB color which represents the starting
  color of the gradient. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color, or an atom
  representing a CSS color name. The default is `:black`
  with 100% transparency.

* `:finish_color` is an sRGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:black` with 100% opacity.

* `:angle` is a float or integer number of degrees of
  clockwise rotation applied to the gradient. The default
  is `0.0`. The number is normalized into the range `0..360`.

### Returns

* `{:ok, gradient_image}` or

* `{:error, reason}`

### Example

    # transparent_black and opaque_black are the default
    # start and finish values
    iex> transparent_black = [0, 0, 0, 0]
    iex> opaque_black = [0, 0, 0, 255]
    iex> Image.linear_gradient(100, 100, start_color: transparent_black, finish_color: opaque_black)
    iex> Image.linear_gradient(100, 100, start_color: :red, finish_color: :blue, angle: 42)

# `linear_gradient!`

Create an image gradient the size of a given
image, or the size of the given dimenssion or
raises an exception.

The gradient will be interpolated from the `start_color`
value to the `finish_color` value.

### Arguments using a template image

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

* `options` is a keyword list of options.

### Arguments supplying a width and height

* `width` is the width in pixels of the gradient image.

* `height` is the height in pixels of the gradient image.

* `options` is a keyword list of options. See
  `t:Image.Options.LinearGradient.linear_gradient_option/0`.

### Options

* `:start_color` is an sRGB color which represents the starting
  color of the gradient. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color, or an atom
  representing a CSS color name. The default is `:black`
  with 100% transparency.

* `:finish_color` is an sRGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:black` with 100% opacity.

* `:angle` is a float or integer number of degrees of
  clockwise rotation applied to the gradient. The default
  is `0.0`. The number is normalized into the range `0..360`.

### Returns

* `gradient_image` or

* raises an exception.

### Example

    # transparent_black and opaque_black are the default
    # start and finish values
    iex> transparent_black = [0, 0, 0, 0]
    iex> opaque_black = [0, 0, 0, 255]
    iex> Image.linear_gradient!(100, 100, start_color: transparent_black, finish_color: opaque_black)

# `meme`
*since 0.13.0* 

```elixir
@spec meme(
  image :: Vix.Vips.Image.t(),
  headline :: String.t(),
  options :: Image.Options.Meme.meme_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Create a meme image from a base image and
one or two lines of text.

The size of the text is determined by the size
of the base image.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` over which
  the meme text will be composed.

* `headline` is the top line of the meme text.

* `options` is a keyword list of options.

### Options

* `:text` is the second line of text at the bottom of the
  meme image. The default is `""`.

* `:text_size` is the size of the bottom text in points.
  The default is calculated proportional to the size of the
  image.

* `:headline_size` is the size of the headline text in points.
  The default is calculated proportional to the size of the
  image.

* `:font` is the name of the font family to be applied.
  The default is `Impact`.

* `:font_file` is the path name to a font file that will be
  loaded. The default is `:default` which will load the included
  `Impact` font if the font family is `Impact`. If the font family
  is not `Impact` and the `:font_file` is `:default` then the
  font displayed is resolved by the underlying operating system.
  If `:font_file` is a string, then it is expected to be a valid
  font file. If `:font_file` is set to a path then the `:font` option
  should also be set to the correct font name.

* `:weight` is the font weight to be rendered. The options
  are `:ultralight`, `:light`, `:normal`, `:bold`, `:ultrabold`,
  and `:heavy`. The default `:bold`.

* `:transform` determines how the text is presented. The
  options are `:upcase`, `:downcase`, `:capitalize` and `:none`.
  The default is `:upcase`.

* `:color` is an RGB color of the text. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:white`.

* `:outline_color` is an RGB color of the text outline. The
  color can be an integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:black`.

* `:margin` is the width of the margin in pixels. The margin is
  applied to both the left and right sides of the image. The
  default is calculated proportional to the size of the
  image.

# `meme!`
*since 0.13.0* 

```elixir
@spec meme!(
  image :: Vix.Vips.Image.t(),
  headline :: String.t(),
  options :: Image.Options.Meme.meme_options()
) :: Vix.Vips.Image.t() | no_return()
```

Return a meme image from a base image and
one or two lines of text or raise an exception.

The size of the text is determined by the size
of the base image.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` over which
  the meme text will be composed.

* `headline` is the top line of the meme text.

* `options` is a keyword list of options.

### Options

* `:text` is the second line of text at the bottom of the
  meme image. The default is `""`.

* `:text_size` is the size of the bottom text in points.
  The default is calculated proportional to the size of the
  image.

* `:headline_size` is the size of the headline text in points.
  The default is calculated proportional to the size of the
  image.

* `:font` is the name of the font family to be applied.
  The default is `Impact`. If the font family name is `"Impact"`
  then the included `unicode.impact.ttf` font file will also be
  loaded. This ensures that the `Impact` font is available on all
  systems.

* `:font_file` is the path name to a font file that will be
  loaded. The default is `:default` which will load the included
  `Impact` font if the font family is `Impact`. If the font family
  is not `Impact` and the `:font_file` is `:default` then the
  font displayed is resolved by the underlying operating system.
  If `:font_file` is a string, then it is expected to be a valid
  font file. If `:font_file` is set to a path then the `:font` option
  should also be set to the correct font name.

* `:weight` is the font weight to be rendered. The options
  are `:ultralight`, `:light`, `:normal`, `:bold`, `:ultrabold`,
  and `:heavy`. The default `:bold`.

* `:justify` is a boolean indicating if the headline and text
  are to be justified. If `true` then space is added between
  words so that both edges of each line are aligned with both
  margins. The default is `false`.

* `:transform` determines how the text is presented. The
  options are `:upcase`, `:downcase`, `:capitalize` and `:none`.
  The default is `:upcase`.

* `:color` is an RGB color of the text. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:white`.

* `:outline_color` is an RGB color of the text outline. The
  color can be an integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is `:black`.

* `:margin` is the width of the margin in pixels. The margin is
  applied to both the left and right sides of the image. The
  default is calculated proportional to the size of the
  image.

# `radial_gradient`
*since 0.6.0* 

```elixir
@spec radial_gradient(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.RadialGradient.radial_gradient_options()
) :: {:ok, %Vix.Vips.Image{ref: term()}} | {:error, error()}
```

Returns a radial gradient as an image.

This image might then be composited over
another image.

### Arguments

* `width` is the width of the gradient in
  pixels.

* `height` is the height of the gradient in
  pixels.

* `options` is a keyword list of options. See
  `t:Image.Options.RadialrGradient.radial_gradient_option/0`.

### Options

* `:start_color` is an sRGB color which represents the starting
  color of the gradient. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color, or an atom
  representing a CSS color name. The default is `:black`
  with 100% transparency.

* `:finish_color` is an sRGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:black` with 100% opacity.

* `:feather` is the slope of the gradient. That is,
  how quickly the gradient moves from the `:start_color`
  color to the `:finish_color`. The valid range is
  `1..10` representing the smallest amount of feather
  (harshest transition) to the largest amount of
  feather (smoothest transition). The default is `1`.

* `:radius` is the radius of the gradient in the range `1..5`
  where `1` fully fills the space and `5` fills a small section
  of the center of the space.  The default is `2`.

### Returns

* `{:ok, gradient_image}` or

* `{:error, reason}`

# `radial_gradient!`
*since 0.43.0* 

```elixir
@spec radial_gradient!(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.RadialGradient.radial_gradient_options()
) :: %Vix.Vips.Image{ref: term()} | no_return()
```

Returns a radial gradient as an image.

This image might then be composited over
another image.

### Arguments

* `width` is the width of the gradient in
  pixels.

* `height` is the height of the gradient in
  pixels.

* `options` is a keyword list of options. See
  `t:Image.Options.RadialrGradient.radial_gradient_option/0`.

### Options

* `:start_color` is an sRGB color which represents the starting
  color of the gradient. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color, or an atom
  representing a CSS color name. The default is `:black`
  with 100% transparency.

* `:finish_color` is an sRGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-or-four-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:black` with 100% opacity.

* `:feather` is the slope of the gradient. That is,
  how quickly the gradient moves from the `:start_color`
  color to the `:finish_color`. The valid range is
  `1..10` representing the smallest amount of feather
  (harshest transition) to the largest amount of
  feather (smoothest transition). The default is `1`.

* `:radius` is the radius of the gradient in the range `1..5`
  where `1` fully fills the space and `5` fills a small section
  of the center of the space.  The default is `2`.

### Returns

* `{:ok, gradient_image}` or

* `{:error, reason}`

# `squircle`

```elixir
@spec squircle(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply squircle mask to an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:radius` is the desired squircle radius.
  The default is 20.

### Returns

* `{:ok, squircle_image}` or

* `{:error, reason}`

# `distort`
*since 0.57.0* 

```elixir
@spec distort(
  image :: Vix.Vips.Image.t(),
  source :: [point()],
  destination :: [point()]
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Distorts an image using [Shepards algorithm](https://legacy.imagemagick.org/Usage/distorts/#shepards).

Shepard’s distortion moves (or smudges) a given
source point to a destination point.

### Arguments

* `image` is any `t:Vimage.t/0`.

* `source` is a list of 2-tuples representing the source
   points in `image`.

* `destination` is a list of 2-tuples representing the
  the destination points into which the
  image is transformed.

### Example

In this example the points around `{30,11}` are distorted to `{20,11}` and
`{48, 29}` to `{58,29}`.

      iex> koala = Image.open!("./test/support/images/koala.gif")
      iex> {:ok, _distorted} = Image.distort(koala, [{30, 11}, {48, 29}], [{20,11}, {58,29}])

# `straighten_perspective`
*since 0.28.0* 

```elixir
@spec straighten_perspective(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: {:ok, quadrilateral(), Vix.Vips.Image.t()} | {:error, error()}
```

Performs a warp perspective transformation on an
image to straighten its perspective.

Requires `Nx` to be configured as a dependency.

### Arguments

* `image` is any `t:Vimage.t/0`.

* `source` is a list of four 2-tuples representing the
  four corners of the subject-of-interest in `image`.

* `options` is a keyword list of options. The default
  is `[]`.

### Options

* `:background` defines the color of any generated background
  pixels. This can be specified as a single integer which will
  be applied to all bands, or a list of integers representing
  the color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of
  the form `#rrggbb`. The default is `:black`. `:background` can
  also be set to `:average` in which case the background will be
  the average color of the base image. See also `Color.new/2` from the Color library.

* `:extend_mode` determines how any additional pixels
  are generated. The values are:

  * `:black` (the default) meaning the generated pixels are
    black.
  * `:white` meaning the generated pixels are white.
  * `:copy` means the generated pixels take the value of the
    nearest edge pixel of the base image.
  * `:repeat` means the generated pixels are tiles from the
    base image.
  * `:mirror` means the generated pixels are a reflected tiles of
    the base image.
  * `:background` means the generated pixels are the background
    color setin `options`.

### Returns

* `{:ok, destination, straightened_image}` or

* `{:error, reason}`

### Notes

* The image is flattened before warping and therefore any
  alpha band will be multiplied into to the image data and
  removed.

* The returned `destination` is a four element list of
  2-tuples representing the four points to which the `source`
  points were transformed. `destination` can be passed as
  a parameter to `Image.crop/2` to crop the transformed image
  to the subject-of-interest that was warped.

# `straighten_perspective!`
*since 0.28.0* 

```elixir
@spec straighten_perspective!(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: Vix.Vips.Image.t() | no_return()
```

Performs a warp perspective transformation on an
image to straighten its perspective or raises an
exception.

Requires `Nx` to be configured as a dependency.

### Arguments

* `image` is any `t:Vimage.t/0`.

* `source` is a list of four 2-tuples representing the
  four corners of the subject-of-interest in `image`.

* `options` is a keyword list of options. The default
  is `[]`.

### Options

* `:background` defines the color of any generated background
  pixels. This can be specified as a single integer which will
  be applied to all bands, or a list of integers representing
  the color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of
  the form `#rrggbb`. The default is `:black`. `:background` can
  also be set to `:average` in which case the background will be
  the average color of the base image. See also `Color.new/2` from the Color library.

* `:extend_mode` determines how any additional pixels
  are generated. The values are:

  * `:black` (the default) meaning the generated pixels are
    black.
  * `:white` meaning the generated pixels are white.
  * `:copy` means the generated pixels take the value of the
    nearest edge pixel of the base image.
  * `:repeat` means the generated pixels are tiles from the
    base image.
  * `:mirror` means the generated pixels are a reflected tiles of
    the base image.
  * `:background` means the generated pixels are the background
    color setin `options`.

### Returns

* `straightened_image` or

* `{:error, reason}`

### Notes

* The image is flattened before warping and therefore any
  alpha band will be multiplied into to the image data and
  removed.

* The returned `destination` is a four element list of
  2-tuples representing the four points to which the `source`
  points were transformed. `destination` can be passed as
  a parameter to `Image.crop/2` to crop the transformed image
  to the subject-of-interest that was warped.

# `transform_matrix`
*since 0.28.0* 

```elixir
@spec transform_matrix(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  destination :: quadrilateral()
) :: {:ok, transform_matrix :: Vix.Vips.Image.t()} | {:error, error()}
```

Returns a transformation matrix for a given
image, source quadrilateral and desintation quadrilateral.

A transformation matrix when applied to an image
(using, for example, `Image.map/2`) maps pixels from
the source persecptive to the destination perspective.

Requires `Nx` to be configured as a dependency.

### Arguments

* `image` is any `t:Vimage.t/0`

* `source` is a list of four 2-tuples representing the
  four corners of the subject-of-interest in `image`.

* `destination` is a list of four 2-tuples representing the
  four corners of the destination image into which the
  subject-of-interest is transformed.

### Returns

* `{:ok, transform_matrix}` or

* `{:error, reason}`.

# `warp_perspective`
*since 0.28.0* 

```elixir
@spec warp_perspective(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  destination :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Performs a warp perspective transformation on an
image.

Requires `Nx` to be configured as a dependency.

### Arguments

* `image` is any `t:Vimage.t/0`

* `source` is a list of four 2-tuples representing the
  four corners of the subject-of-interest in `image`.

* `destination` is a list of four 2-tuples representing the
  four corners of the destination image into which the
  subject-of-interest is transformed.

* `options` is a keyword list of options. The default
  is `[]`.

### Options

* `:background` defines the color of any generated background
  pixels. This can be specified as a single integer which will
  be applied to all bands, or a list of integers representing
  the color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of the form `#rrggbb`.
  The default is `:black`. `:background` can also be set to `:average`
  in which case the background will be the average color of the base
  image. See also `Color.new/2` from the Color library.

* `:extend_mode` determines how any additional pixels
  are generated. The values are:

  * `:black` (the default) meaning the generated pixels are
    black.
  * `:white` meaning the generated pixels are white.
  * `:copy` means the generated pixels take the value of the
    nearest edge pixel of the base image.
  * `:repeat` means the generated pixels are tiles from the
    base image.
  * `:mirror` means the generated pixels are a reflected tiles of
    the base image.
  * `:background` means the generated pixels are the background
    color setin `options`.

### Notes

* The image is flattened before warping and therefore any
  alpha band will be multiplied into to the image data and
  removed.

### Returns

* `{:ok, warped_image}` or

* `{:error, reason}`

# `warp_perspective!`
*since 0.28.0* 

```elixir
@spec warp_perspective!(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  destination :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: Vix.Vips.Image.t() | no_return()
```

Performs a warp perspective transformation on an
image or raises an exception.

Requires `Nx` to be configured as a dependency.

### Arguments

* `image` is any `t:Vimage.t/0`

* `source` is a list of four 2-tuples representing the
  four corners of the subject-of-interest in `image`.

* `destination` is a list of four 2-tuples representing the
  four corners of the destination image into which the
  subject-of-interest is transformed.

* `options` is a keyword list of options. The default
  is `[]`.

### Options

* `:background` defines the color of any generated background
  pixels. This can be specified as a single integer which will
  be applied to all bands, or a list of integers representing
  the color for each band. The color can also be supplied as a
  CSS color name as a string or atom. For example: `:misty_rose`.
  It can also be supplied as a hex string of
  the form `#rrggbb`. The default is `:black`. `:background` can
  also be set to `:average` in which case the background will be
  the average color of the base image. See also `Color.new/2` from the Color library.

* `:extend_mode` determines how any additional pixels
  are generated. The values are:

  * `:black` (the default) meaning the generated pixels are
    black.
  * `:white` meaning the generated pixels are white.
  * `:copy` means the generated pixels take the value of the
    nearest edge pixel of the base image.
  * `:repeat` means the generated pixels are tiles from the
    base image.
  * `:mirror` means the generated pixels are a reflected tiles of
    the base image.
  * `:background` means the generated pixels are the background
    color setin `options`.

### Returns

* `warped_image` or

* raises an exception.

### Notes

* The image is flattened before warping and therefore any
  alpha band will be multiplied into to the image data and
  removed.

# `alpha_band`

```elixir
@spec alpha_band(Vix.Vips.Image.t()) :: 1..4 | nil
```

Returns the band number of the alpha
channel of an image, or nil if it doesn't
have one.

The determination is a heuristic so certainty
cannot be guaranteed.

### Arguments

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

### Returns

* An integer in the range `1..4` depending
  on the image interpretation. Returns `nil`
  if there is no alpha band. The integer
  is a 0-based offset and can therefore be
  directly used to access the band. For example
  `image[alpha_band(image)]`.

# `band_and`
*since 0.60.0* 

```elixir
@spec band_and(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Boolean "and" the bands of an image together to
produce a single band image.

### Arguments

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

### Returns

* `{:ok, and_image}` where `and_image` a single band image that is the
  result of boolean "and"ing the bands of `image` togther.

# `band_and!`
*since 0.60.0* 

```elixir
@spec band_and!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
@spec band_and!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Boolean "and" the bands of an image together to
produce a single band image or raises an exception.

### Arguments

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

### Returns

* `and_image` where `and_image` a single band image that is the
  result of boolean "and"ing the bands of `image` togther or

* raises an exception.

# `band_or`
*since 0.60.0* 

```elixir
@spec band_or(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Boolean "or" the bands of an image together to
produce a single band image.

### Arguments

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

### Returns

* `{:ok, or_image}` where `or_image` a single band image that is the
  result of boolean "or"ing the bands of `image` togther.

# `band_or!`
*since 0.60.0* 

Boolean "or" the bands of an image together to
produce a single band image or raises an exception.

### Arguments

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

### Returns

* `or_image` where `or_image` a single band image that is the
  result of boolean "or"ing the bands of `image` togther or

* raises an exception.

# `band_xor`
*since 0.60.0* 

```elixir
@spec band_xor(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Boolean "exclusive or" the bands of an image together to
produce a single band image.

### Arguments

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

### Returns

* `{:ok, xor_image}` where `xor_image` a single band image that is the
  result of boolean "exclusive or"ing the bands of `image` togther.

# `band_xor!`
*since 0.60.0* 

```elixir
@spec band_xor!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Boolean "exclusive or" the bands of an image together to
produce a single band image or raises an exception.

### Arguments

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

### Returns

* `xor_image` where `xor_image` a single band image that is the
  result of boolean "exclusive or"ing the bands of `image` togther or

* raises an exception.

# `join_bands`
*since 0.53.0* 

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

Joins a list of bands into a single image.

This can be considered the inverse operation of
`Image.split_bands/1`.

### Arguments

* `image_list` is any list of `t:Vix.Vips.Image.t/0`.

### Returns

* `{:ok, image}` where `image` is created by joining
  `image_bands` together or

* `{:error, reason}`.

# `join_bands!`
*since 0.53.0* 

```elixir
@spec join_bands!(image_list :: [Vix.Vips.Image.t()]) ::
  Vix.Vips.Image.t() | no_return()
```

Joins a list of bands into a single image or
raises an exception.

This can be considered the inverse operation of
`Image.split_bands/1`.

### Arguments

* `image_list` is any list of `t:Vix.Vips.Image.t/0`.

### Returns

* an image created by joining `image_bands`
  together or

* raises an exception.

# `split_bands`
*since 0.13.0* 

```elixir
@spec split_bands(Vix.Vips.Image.t()) :: [Vix.Vips.Image.t()]
```

Split the image into a list of its component
bands.

This can be considered the inverse of
`Image.join_bands/1`.

### Arguments

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

### Returns

* a list of single band images extracted
  from `image`.

# `replace_color`
*since 0.30.0* 

```elixir
@spec replace_color(
  Vix.Vips.Image.t(),
  Image.Options.ChromaKey.chroma_key_options()
  | [{:replace_with, Image.Pixel.t()}]
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Replace one color in an image with another.

### Arguments

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

* `options` is a keyword list of options.

### Options

With the exception of the option `:replace_with`, the
options for specifying the color or color range
to be replaced are passed to `Image.chroma_mask/2`.

* `:blend` is a boolean indicating if a the replacement
  should blend at the border of the color replacement.
  The default is `false`.

* `:replace_with` is the replacement color.  This can be specified as
  a single integer which wil be applied to all bands, or a
  list of integers representing the color for each band. The
  color can also be supplied as a CSS color name as a string or
  atom. For example: `:misty_rose`. It can also be supplied as a
  hex string of the form `#rrggbb`. The default is `:black`.
  See also `Color.new/2` from the Color library.

There are two strategies available for selecting the
color or color range to be replaced: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold`is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be selected. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

* `:less_than` is an RGB color which represents the lower
   end of the color range to be selected. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

### Returns

* `{:ok, image}` or

* `{:error, reason}`.

# `replace_color!`
*since 0.30.0* 

```elixir
@spec replace_color!(
  Vix.Vips.Image.t(),
  Image.Options.ChromaKey.chroma_key_options()
  | [{:replace_with, Image.Pixel.t()}]
) :: Vix.Vips.Image.t() | no_return()
```

Replace one color in an image with another or
raises an exception.

### Arguments

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

* `options` is a keyword list of options.

### Options

With the exception of the option `:replace_with`, the
options for specifying the color or color range
to be replaced are passed to `Image.chroma_mask/2`.

* `:replace_with` is the replacement color.  This can be specified as
  a single integer which wil be applied to all bands, or a
  list of integers representing the color for each band. The
  color can also be supplied as a CSS color name as a string or
  atom. For example: `:misty_rose`. It can also be supplied as a
  hex string of the form `#rrggbb`. The default is `:black`.
  See also `Color.new/2` from the Color library.

There are two strategies available for selecting the
color or color range to be replaced: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be selected. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold`is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be selected. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

* `:less_than` is an RGB color which represents the lower
   end of the color range to be selected. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

### Returns

* `image` or

* raises an exception.

# `to_colorspace`

```elixir
@spec to_colorspace(Vix.Vips.Image.t(), Image.Interpretation.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Converts an image to the given colorspace.

Available colorspaces are returned from
`Image.Interpretation.known_interpretations/0`.

### Arguments

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

* `colorspace` is any known colorspace. See
  `Image.Interpretation.known_interpretations/0`
  for a list of the known colorspaces.

### Returns

* `{;ok, image_in_new_colorspace}` or

* `{:error, reason}`

### Example

    Image.to_colorspace(image, :bw)

# `to_colorspace!`

```elixir
@spec to_colorspace!(Vix.Vips.Image.t(), Image.Interpretation.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Converts an image to the given colorspace returning
an image or raising an exception.

Available colorspaces are returned from
`Image.Interpretation.known_interpretations/0`.

### Arguments

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

* `colorspace` is any known colorspace. See
  `Image.Interpretation.known_interpretations/0`
  for a list of the known colorspaces.

### Returns

* `image_in_new_colorspace` or

* raises an exception

### Example

    Image.to_colorspace!(image, :bw)

# `aspect`

Returns the aspect of an image.

### Arguments

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

* `options` is a keyword list of options

### Options

* `:square_ratio` indicates when an image
  is to be considered square. It is a floating
  point indicator of the ratio between the width
  and height below which the image is considered
  square. The default is `0.0` meaning that the
  dimensions must be exactly equal in order for
  the image to be considered square.

### Returns

* Either `:landscape`, `:portrait` or `:square`.

### Example

    iex> puppy = Image.open!(Path.expand("test/support/images/puppy.webp"))
    iex> Image.aspect(puppy, square_ratio: 0.05)
    :landscape

# `band_format`
*since 0.35.0* 

```elixir
@spec band_format(image :: Vix.Vips.Image.t()) :: Image.BandFormat.t()
```

Returns the band format of an image.

### Arguments

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

### Returns

* The band format of the image in `Nx` notation.

### Examples

      iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
      iex> Image.band_format(image)
      {:u, 8}

# `bands`

```elixir
@spec bands(image :: Vix.Vips.Image.t()) :: pos_integer()
```

Return the number of bands in an image.

A band is sometimes referred to as a
channel.

Note than bands are 0-indexed. That is, the
first band is band 0, the second band is
band 1 and so on.

### Arguments

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

### Returns

* An integer number of bands in the image.

# `colorspace`
*since 0.9.0* 

```elixir
@spec colorspace(image :: Vix.Vips.Image.t()) :: Image.Interpretation.t()
```

Returns the image colorspace.

The colorspace is how `Image` understands
the image data. For example, `:srgb`, `:cmyk` or
`:bw`.

For most common web applications, the
colorspace will be `:srgb`.

### Arguments

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

### Returns

* The image colorspace as an atom.

### Notes

* See also `Image.Interpretation.known_interpretations/0`

### Example

    iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
    iex> Image.colorspace(image)
    :srgb

# `dominant_color`
*since 0.3.0* 

```elixir
@spec dominant_color(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Image.Pixel.t() | [Image.Pixel.t()] | [{0..255, 0..255, 0..255}]}
  | {:error, error()}
```

Returns the dominant sRGB color(s) of an image.

Two methods are supported for identifying dominant
colors:

* `:histogram` (default) uses a coarse 3D RGB histogram
  (via `vips_hist_find_ndim`) and returns the centre of
  the most populated bins. It is fast and has no external
  dependencies beyond libvips itself.

* `:imagequant` asks libvips to quantise the image with
  `libimagequant` (via `vips_gifsave_buffer`) and returns
  the resulting palette ordered by perceptual importance.
  This generally yields visually better dominant colors
  on photographic images, at the cost of running the
  quantiser.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:method` is either `:histogram` or `:imagequant`.
  The default is `:histogram`.

* `:bins` is an integer number of color
  frequency bins the image is divided into.
  Only used when `method: :histogram`.
  The default is `16`.

* `:top_n` returns the top `n` most
  dominant colors in the image. The default
  is `1`. When `method: :imagequant`,
  `:top_n` is rounded up to the next power of two
  (clamped to the range `2..256`) to select the GIF
  palette bitdepth; the returned list is then truncated
  to `:top_n` entries.

* `:effort` is an integer in the range `1..10` that
  controls the libimagequant CPU effort. Only used when
  `method: :imagequant`. The default is `7`.

* `:dither` is a float in the range `0.0..1.0` that
  controls the libimagequant dithering amount. Only used
  when `method: :imagequant`. The default is `0.0`
  (no dithering, which preserves the palette colors exactly).

### Returns

* `{:ok, [r, g, b]}` when `method: :histogram` and `top_n: 1`, or

* `{:ok, [[r, g, b], ...]}` when `method: :histogram` and `top_n > 1`, or

* `{:ok, [{r, g, b}, ...]}` when `method: :imagequant`, or

* `{:error, reason}`.

### Notes

* `image` will be converted to the `:srgb` colorspace
  and the dominant color will be returned as an sRGB
  value.

### Examples

    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> Image.dominant_color(image)
    {:ok, [8, 8, 24]}

    iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
    iex> Image.dominant_color(image)
    {:ok, [88, 88, 88]}

    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> {:ok, palette} = Image.dominant_color(image, method: :imagequant, top_n: 4)
    iex> length(palette)
    4
    iex> Enum.all?(palette, fn {r, g, b} -> r in 0..255 and g in 0..255 and b in 0..255 end)
    true

# `dominant_color!`
*since 0.43.0* 

```elixir
@spec dominant_color!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Image.Pixel.t() | [Image.Pixel.t()] | [{0..255, 0..255, 0..255}] | no_return()
```

Returns the dominant sRGB color of an image
or raises an exception.

### Arguments

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

* `options` is a keyword list of options.

### Options

See `dominant_color/2` for the full list of options,
including `:method` for selecting between the `:histogram`
and `:imagequant` backends.

### Returns

* The dominant color (see `dominant_color/2` for the
  shape of the return value), or

* raises an exception.

### Notes

* `image` will be converted to the `:srgb` colorspace
  and the dominant color will be returned as an sRGB
  list.

### Example

    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> Image.dominant_color!(image)
    [8, 8, 24]

    iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
    iex> Image.dominant_color!(image)
    [88, 88, 88]

# `filename`

```elixir
@spec filename(image :: Vix.Vips.Image.t()) :: Path.t() | nil
```

Returns the filename for an image.

### Arguments

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

### Returns

* The pathname from which the image was opened or
  `nil` if there is no associated path. This can
  happen in the case of a streamed image or an image
  created from a memory buffer.

# `has_alpha?`

```elixir
@spec has_alpha?(Vix.Vips.Image.t()) :: boolean()
```

Returns a boolean based upon whether a given
image has an alpha band.

The determination is a heuristic so certainty
cannot be guaranteed.

### Arguments

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

### Returns

* `true` or `false`

### Examples

    iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
    iex> Image.has_alpha?(image)
    true

    iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
    iex> Image.has_alpha?(image)
    false

# `height`

```elixir
@spec height(image :: Vix.Vips.Image.t()) :: pos_integer()
```

Returns the height of an image.

### Arguments

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

### Returns

* The image height as an integer.

# `pages`
*since 0.38.0* 

```elixir
@spec pages(image :: Vix.Vips.Image.t()) :: pos_integer()
```

Returns the number of pages in an image.

Animated images will return an integer representing
the number of animated frames. Normal images will
return `1`.

### Arguments

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

### Returns

* `integer` number of pages in the `image`.

### Example

    iex> image = Image.open!("./test/support/images/animated.webp")
    iex> Image.pages(image)
    12

    iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
    iex> Image.pages(image)
    1

# `range`
*since 0.35.0* 

```elixir
@spec range(image :: Vix.Vips.Image.t()) ::
  {non_neg_integer() | float(), non_neg_integer() | float()}
```

Returns the range of permissable values
as a tuple for each pixel in an image.

### Arguments

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

### Returns

* `{min_value, max_value}` where `min_value` and
  `max_value` are integers for unsigned images and
  floats for signed images.

### Examples

      iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
      iex> Image.range(image)
      {0, 255}

# `shape`
*since 0.9.0* 

```elixir
@spec shape(image :: Vix.Vips.Image.t() | Vix.Vips.MutableImage.t()) ::
  {width :: pos_integer(), height :: pos_integer(), bands :: pos_integer()}
```

Returns the shape of an image.

### Arguments

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

### Returns

* The image shape as a tuple of
  `{width, height, bands}`.

### Example

    iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
    iex> Image.shape(image)
    {1000,542, 3}

# `width`

```elixir
@spec width(image :: Vix.Vips.Image.t()) :: pos_integer()
```

Returns the width of an image.

### Arguments

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

### Returns

* The image width as an integer.

# `logistic_curve_rhs`
*since 0.54.0* 

```elixir
@spec logistic_curve_rhs(k :: float()) :: Vix.Vips.Image.t()
```

Returns a single band image representing the
right hand side (positive range) of the
[logistic function](https://en.wikipedia.org/wiki/Logistic_function).

### Arguments

* `k` is a float in the range `-1.0` to `1.0` representing
  the logistic growth rate (slope of the curve).

### Returns

* A single band `t:Vimage.t/0` representing the right hand side
  (positive numbers) of the logistic curve.

### Notes

* This is not a general purpose curve generator. It is used by
  `Image.vibrance/3` and may, in the future, be developed into a more
  general purpose logistic curve function.

# `histogram`
*since 0.3.0* 

```elixir
@spec histogram(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Returns the histogram for an image.

The histogram is returned as a `t:Vimage.t/0`
that is a 255 by 1 pixel image with the same numbers of
bands as the source image.

### Argument

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

### Returns

* `{:ok, histogram_image}` or

* `{:error, reason}`

### Notes

The returned image is is organized
as a 256x1 pixel image with
the same number of bands as the original
image.

Each pixel on the image returns the *count*
of pixels in the original image that are
in that 1/256th part of the image.

Each band is separated into 1/256ths individually.
For an RGB image the first number of the
pixel element of the histogram is the count of the
number of pixels in the red band, the second the count
of pixels in the green band and the third a count of
the pixels in the blue band.

### Example

    iex> image = Image.new!(3, 3, color: [0, 128, 0])
    iex> {:ok, _histogram} = Image.histogram(image)

    # Here is the returned list (which is just a way of
    # visualing the histogram). The first entry of `[9, 0, 9]`
    # is saying "in the first 1/256th of values, there are 9 pixels
    # in the red band and 9 pixels in the blue band". Later on,
    # in the 128th entry, we can see there are 9 pixels in the green
    # band and none in the red and blue bands.

    histogram |> Image.to_nx!() |> Nx.to_list()
    [
      [
        [9, 0, 9],
        [0, 0, 0],
        ...
        [0, 9, 0],
        ...
        [0, 0, 0],
        [0, 0, 0]
      ]
    ]

# `k_means`
*since 0.49.0* 

```elixir
@spec k_means(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, [Image.Pixel.t()]} | {:error, error()}
```

Applies [K-means](https://en.wikipedia.org/wiki/K-means_clustering) clustering
to an image using the [scholar](https://hex.pm/packages/scholar)
library. The returned result is a list of colors resulting from
partioning the colors in an image.

This function is only available if [Scholar](https://hex.pm/packages/scholar)
is configured.

### Arguments

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

* `options` is a keyword list of options.

### Options

* See `Scholar.Cluster.KMeans.fit/2` for the
  available options.

### Returns

* `{:ok, list_of_colors}` or

* `{:error, reason}`

### Notes

* The current implementation is performed in the
  sRGB colorspace. This may not produce the most
  perceptually appropriate clusters. This limitation
  will be removed in a future release.

* The option `:num_clusters` determines the
  number of clusters into which image colors are
  partioned. The default is `num_clusters: 16`.

* The default options mean that the results are
  not deterministic. Different calls to `Image.k_means/2`
  can return different - but equally valid - results. Use
  the `:key` option to return deterministic results.

* Performance is very correlated with image size.
  Where possible, resize the image to be under a 1_000_000
  pixels or even less before invoking `Image.k_means/2`.

* Performance is primarily determined by the vector
  performance of the system and specifically by the
  GPU configuration and EXLAs support of that GPU.
  In most cases it is recommended that the following
  be added to `config.exs`:

```elixir
config :nx,
  default_backend: EXLA.Backend

config :nx, :default_defn_options,
  compiler: EXLA
```

### Example

    iex> key = Nx.Random.key(40)
    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> Image.k_means(image, key: key)
    {:ok,
     [
       [35, 112, 151],
       [36, 70, 89],
       [38, 36, 33],
       [39, 187, 56],
       [96, 93, 108],
       [97, 148, 178],
       [107, 70, 39],
       [144, 119, 151],
       [153, 117, 89],
       [171, 179, 200],
       [173, 168, 134],
       [180, 113, 35],
       [217, 131, 137],
       [225, 223, 223],
       [226, 163, 80],
       [232, 198, 155]
     ]}

# `k_means!`
*since 0.49.0* 

```elixir
@spec k_means!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  [Image.Pixel.t()] | no_return()
```

Applies [K-means](https://en.wikipedia.org/wiki/K-means_clustering) clustering
to an image using the [scholar](https://hex.pm/packages/scholar)
library. The returned result is a list of colors resulting from
partioning the colors in an image.

This function is only available if [Scholar](https://hex.pm/packages/scholar)
is configured.

### Arguments

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

* `options` is a keyword list of options.

### Options

* See `Scholar.Cluster.KMeans.fit/2` for the
  available options.

### Returns

* `{:ok, list_of_colors}` or

* `{:error, reason}`

### Notes

* The current implementation is targetted towards
  sRGB images Results for images in other colorspaces
  is undefined. It is planned this limitation be
  removed in a future release.

* The option `:num_clusters` determines the
  number of clusters into which image colors are
  partioned. The default is `num_clusters: 16`.

* The default options mean that the results are
  not deterministic. Different calls to `Image.k_means/2`
  can return different - but equally valid - results. Use
  the `:key` option to return deterministic results.

* Performance is very correlated with image size.
  Where possible, resize the image to be under a 1_000_000
  pixels or even less before invoking `Image.k_means/2`.

* Performance is primarily determined by the vector
  performance of the system and specifically by the
  GPU configuration and EXLAs support of that GPU.
  In most cases it is recommended that the following
  be added to `config.exs`:

```elixir
config :nx,
  default_backend: EXLA.Backend

config :nx, :default_defn_options,
  compiler: EXLA
```

### Example

    iex> key = Nx.Random.key(40)
    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> Image.k_means!(image, key: key)
    [
      [35, 112, 151],
      [36, 70, 89],
      [38, 36, 33],
      [39, 187, 56],
      [96, 93, 108],
      [97, 148, 178],
      [107, 70, 39],
      [144, 119, 151],
      [153, 117, 89],
      [171, 179, 200],
      [173, 168, 134],
      [180, 113, 35],
      [217, 131, 137],
      [225, 223, 223],
      [226, 163, 80],
      [232, 198, 155]
    ]

# `reduce_colors`
*since 0.50.0* 

Reduces the number of colors in an image.

Takes the `k_means/2` of the image and then
re-colors the image using the returned cluster
colors.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:colors` is the number of distinct colors to be
  used in the returned image. The default is `16`.

* See also `Scholar.Cluster.KMeans.fit/2` for the
  available options.

### Note

* Note the performance considerations described in
  `Image.k_means/2` since they also apply to this function.

* If the intent is to reduce colors in order to
  reduce the size of an image file it is strongly advised to
  use the appropriate arguments when calling `Image.write/2`.

### Returns

* `{:ok, reduced_colors_image}` or

* `{:error, reason}`

# `reduce_colors!`
*since 0.51.0* 

Reduces the number of colors in an image or
raises an exception.

Takes the `k_means/2` of the image and then
re-colors the image using the returned cluster
colors.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:colors` is the number of distinct colors to be
  used in the returned image. The default is `16`.

* See also `Scholar.Cluster.KMeans.fit/2` for the
  available options.

### Note

* Note the performance considerations described in
  `Image.k_means/2` since they also apply to this function.

* If the intent is to reduce colors in order to
  reduce the size of an image file it is strongly advised to
  use the appropriate arguments when calling `Image.write/2`.

### Returns

* `reduced_colors_image` or

* raises an exception.

# `delta_e`
*since 0.49.0* 

```elixir
@spec delta_e(
  color_1 :: Vix.Vips.Image.t() | Image.Pixel.t(),
  color_2 :: Vix.Vips.Image.t() | Image.Pixel.t(),
  version :: :de76 | :de00 | :cmc
) :: {:ok, float()} | {:error, error()}
```

Returns the [color difference](https://en.wikipedia.org/wiki/Color_difference)
between two colors calculated using the
[CIE](https://cie.co.at) [ΔE*](https://en.wikipedia.org/wiki/Color_difference#CIELAB_ΔE*)
algorithms.

The available difference algorithms are:

* [CIDE2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000)
* [CIE CMC](https://en.wikipedia.org/wiki/Color_difference#CMC_l:c_(1984))
* [CIE 1976](https://en.wikipedia.org/wiki/Color_difference#CIE76)

### Arguments

* `color_1` which can be specified as a single integer
  or a list of integers representing the color.
  The color can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. Lastly, the
  color can be supplied as a hex string like `#ffe4e1`. See
  `Color.new/2` from the Color library.

* `color_2` which is specified in the same manner as `color_1`.

* `version` is one of `:de00` (the default), `:decmc` or `:de76`.

### Returns

* `{:ok, int_distance}` where `int_distance` is `0`
  when the colors are identical and `100` when they are completely
  different.

* `{:error, reason}`.

### Examples

    iex> Image.delta_e([0,0,0], [0,0,0])
    {:ok, 0.0}

    iex> Image.delta_e([0,0,0], [255,255,255])
    {:ok, 100.0}

# `delta_e!`
*since 0.51.0* 

Returns the [color difference](https://en.wikipedia.org/wiki/Color_difference)
between two colors calculated using the
[CIE](https://cie.co.at) [ΔE*](https://en.wikipedia.org/wiki/Color_difference#CIELAB_ΔE*)
algorithms or raises an exception.

The available difference algorithms are:

* [CIDE2000](https://en.wikipedia.org/wiki/Color_difference#CIEDE2000)
* [CIE CMC](https://en.wikipedia.org/wiki/Color_difference#CMC_l:c_(1984))
* [CIE 1976](https://en.wikipedia.org/wiki/Color_difference#CIE76)

### Arguments

* `color_1` which can be specified as a single integer
  or a list of integers representing the color.
  The color can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. Lastly, the
  color can be supplied as a hex string like `#ffe4e1`. See
  `Color.new/2` from the Color library.

* `color_2` which is specified in the same manner as `color_1`.

* `version` is one of `:de00` (the default), `:decmc` or `:de76`.

### Returns

* `{:ok, int_distance}` where `int_distance` is `0`
  when the colors are identical and `100` when they are completely
  different.

* `{:error, reason}`.

### Examples

    iex> Image.delta_e!([0,0,0], [0,0,0])
    0.0

    iex> Image.delta_e!([0,0,0], [255,255,255])
    100.0

    iex> Image.delta_e!([0,0,0], :misty_rose)
    iex> |> Float.round(3)
    90.155

    iex> Image.delta_e!(:green, :misty_rose)
    iex> |> Float.round(3)
    52.937

    iex> Image.delta_e!(:green, :misty_rose, :de76)
    iex> |> Float.round(4)
    88.5516

# `chroma_mask`
*since 0.13.0* 

```elixir
@spec chroma_mask(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ChromaKey.chroma_key_options() | map()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Return a chroma-based masked image.

Chroma masking is the process of removing a background color
from an image and returning the remaining content as an alpha
mask.

The masking is done in the LCh color space since it's perceptually
more uniform.  The returned mask in reverted to the interpretation
of the original image.

### Arguments

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

* `options` is a keyword list of options.

### Options

There are two masking strategies available: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be masked. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold` is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

* `:less_than` is an RGB color which represents the lower
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

# `chroma_mask!`
*since 0.13.0* 

```elixir
@spec chroma_mask!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ChromaKey.chroma_key_options()
) ::
  Vix.Vips.Image.t() | no_return()
```

Return a chroma-based masked image or raises
an exception.

Chroma masking is the process of removing a background color
from an image and returning the remaining content as an alpha
mask.

### Arguments

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

* `options` is a keyword list of options.

### Options

There are two masking strategies available: the
thresholding strategy (default) and the color
range strategy.

#### Threshold strategy

* `:color` is an RGB color which represents the the
  chroma key to be masked. The color can be an
  integer between `0..255`, a three-element list of
  integers representing an RGB color or an atom
  representing a CSS color name. The default is
  `:auto` in which the average of the top left `10x10`
  pixels of the image is used.

* `:threshold` is a positive integer to indicate the
  threshold around `:color` when calculating the mask.
  The default is `20`.

#### Color range strategy

* `:greater_than` is an RGB color which represents the upper
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

 * `:less_than` is an RGB color which represents the lower
   end of the color range to be masked. The color can be an
   integer between `0..255`, a three-element list of
   integers representing an RGB color or an atom
   representing a CSS color name.

# `circle`

```elixir
@spec circle(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply a circular mask to an image.

The returned image has an alpha
band masking the circular image.

As a result, it is best saved to a
format, like `.png` that supports
alpha transparency.

Note that `.jpg` files do not support
alpha transparency.

### Arguments

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

### Returns

* `{:ok, circular_image}` or

* `{:error, reason}`

# `circle!`

```elixir
@spec circle!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
```

Apply a circular mask to an image
returning an image or raising an
exception.

The returned image has an alpha
band masking the circular image.

As a result, it is best saved to a
format, like `.png` that supports
alpha transparency.

Note that `.jpg` files do not support
alpha transparency.

### Arguments

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

### Returns

* `circular_image` or

* raises an exception.

# `convert_alpha_to_mask`

```elixir
@spec convert_alpha_to_mask(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Convert an image alpha band into a mask.

Takes an image, extracts its alpha band
which holds the opacity information and
inverts the content to produce a mask.

### Arguments

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

### Returns

* `{:ok, mask}` or

* `{:error, reason}`

# `convert_alpha_to_mask!`

```elixir
@spec convert_alpha_to_mask!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
```

Convert an image alpha band into a mask returning
an image or raising an exception.

Takes an image, extracts its alpha band
which holds the opacity information and
inverts the content to produce a mask.

### Arguments

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

### Returns

* `mask` image or

* raises an exception

# `rounded`

```elixir
@spec rounded(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Apply rounded corners to an image.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:radius` is the desired corner radius.
  The default is 50.

### Returns

* `{:ok, rounded_corner_image}` or

* `{:error, reason}`

# `rounded!`

```elixir
@spec rounded!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
```

Apply rounded corners to an image. Returns
an image or raises an exception.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:radius` is the desired corner radius.
  The default is 50.

### Returns

* `rounded_corner_image` or

* raises an exception.

# `squircle!`

```elixir
@spec squircle!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
```

Apply a squircle mask to an image. Returns
an image or raises an exception.

### Arguments

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

* `options` is a keyword list of options.

### Options

* `:radius` is the desired squircle radius.
  The default is 20.

### Returns

* `squircle_image` or

* raises an exception.

# `dhash`
*since 0.6.0* 

```elixir
@spec dhash(image :: Vix.Vips.Image.t(), hash_size :: pos_integer()) ::
  {:ok, image_hash()} | {:error, error()}
```

Returns a 64-bit (for a hash size of the default 64) difference hash as a
binary.

Image hashes can be used to compare the similarity
of images. See `Image.hamming_distance/2`.

A `dhash` is a "difference hash" for a given image. This
is a perceptual hash based on Neal Krawetz's dHash algorithm in
a [Hacker Factor](http://www.hackerfactor.com/blog/index.php?/archives/529-Kind-of-Like-That.html)
blog entry.

The code is adapted from the Ruby implementation in
[dhash-vips](https://github.com/Nakilon/dhash-vips).

### Arguments

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

* `hash_size_bits` is the size in bits of the returned hash.
  The default is `64`. The returned binary is only
  guaranteed to be the provided size if `sqrt(hash_size_bits)` is
  an integer.

### Returns

* `{:ok, 64-bit binary}` or

* `{:error, reason}`

### Example

      iex> {:ok, image} = Image.open("./test/support/images/Kamchatka-2019-8754.jpg")
      iex> Image.dhash(image)
      {:ok, <<227, 127, 61, 34, 206, 143, 156, 122>>}

# `exif`

```elixir
@spec exif(Vix.Vips.Image.t()) :: {:ok, map()} | {:error, error()}
```

Returns the EXIF data for an image as a
map.

Only a subset of EXIF data is returned but
its a substantial subset.

### Arguments

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

### Returns

* `{:ok, exif_map}` where `exif_map` is a map
  of selected EXIF data.

* `{:error, reason}`

# `minimize_metadata`

```elixir
@spec minimize_metadata(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Minimize metadata by keeping only the artist
and copyright (if available).

Removing metadata from an image can greatly reduce
the overall size of an image. The proportional
reduction is most noticeable with smaller images
which are very common in web applications.

Removing all metadata is a common option however
with intellectual property concerns in mind
this function will keep the artist and
copyright fields if they exist in the original
image EXIF. Creator/Author/Artist and Copyright in
other fields like IPTC and XMP are not considered
in the current implementation.

On a 1000x500px image exported from Adobe Lightroom
with metadata intact, removing the metadata
results in am approximately 50% saving in file
size due to the removal of most EXIF and all
IPTC and XMP metadata.

> #### Note {: .info}
>
> the minimized metadata is only materialized when the minimized image is saved.

### Arguments

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

### Returns

* `{:ok, image_with_minimal_metadata}` or

* `{:error, reason}`

# `minimize_metadata!`

```elixir
@spec minimize_metadata!(image :: Vix.Vips.Image.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Minimize metadata by keeping only the artist
and copyright (if available).

See also `Image.minimize_metadata/1`.

### Arguments

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

### Returns

* ` image_with_minimal_metadata` or

* raises an exception.

# `remove_metadata`

```elixir
@spec remove_metadata(Vix.Vips.Image.t(), [binary() | atom()]) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Remove metadata from an image returning
an updated image or raising an exception.

This can significantly reduce the size of
an image file.

### Arguments

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

* `fields` is a list of metadata field names
  as strings. The default is all known
  field names. There are some special field
  names interpreted by `Image` to simplify
  metadata removal these are:

  * `:exif` which means remove all
    [EXIF](https://en.wikipedia.org/wiki/Exif) metadata
  * `:iptc` which means remove all
    [IPTC](https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model) metadata
  * `:xmp` which means remove all
    [xmp](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) data

## Notes

* The available field names (ie. metadata fields)
  in an image can be returned with a call to
  `Vix.Vips.Image.header_field_names/1`.

* Errors removing metadata fields are not propagated
  into the return for this function. Errors might occur
  when attempting to remove metadata fields that
  do not exist in the image.

### Returns

  * `{:ok, image_without_metadata_fields}` or

  * `{:error, reason}`

# `remove_metadata!`

```elixir
@spec remove_metadata!(Vix.Vips.Image.t(), [binary() | atom()]) ::
  Vix.Vips.Image.t() | no_return()
```

Remove metadata from an image returning
an image or raising an exception.

This can significant;y reduce the size of
an image file.

### Arguments

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

* `fields` is a list of metadata field names
  as strings. The default is all known
  field names. There are some special field
  names interpreted by `Image` to simplify
  metadata removal these are:

  * `:exif` which means remove all
    [EXIF](https://en.wikipedia.org/wiki/Exif) metadata
  * `:iptc` which means remove all
    [IPTC](https://en.wikipedia.org/wiki/IPTC_Information_Interchange_Model) metadata
  * `:xmp` which means remove all
    [xmp](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) data

## Notes

* The available field names (ie. metadata fields)
  in an image can be returned with a call to
  `Vix.Vips.Image.header_field_names/1`.

* Errors removing metadata fields are not propagated
  into the return for this function. Errors might occur
  when attempting to remove metadata fields that
  do not exist in the image.

### Returns

  * `image_without_metadata_fields` or

  * raises an exception.

# `xmp`

```elixir
@spec xmp(Vix.Vips.Image.t()) :: {:ok, map()} | {:error, error()}
```

Returns the XMP data for an image as a
keyword list.

Only a selected set of XMP data is returned.

### Arguments

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

### Returns

* `{:ok, xmp_map}` where `xmp_map` is a map
  of selected XMP data.

# `from_evision`
*since 0.9.0* 

Converts to an `Image` image from an `t:Evision.Mat.t/0` image.

### Arguments

* `evision_image` is any `t:Evision.Mat.t/0` image.

### Returns

* `{:ok, image}`

### Notes

* `Image` images have the shape `{width, height, bands}`
  whereas `Evision` images have the shape `{height, width, bands}`
  so this function transposes the dimensions to match.

* `Image` data is arranged as `rgb` data elements whereas
  `Evision` requires the data to be in `bgr` order. This function
  also reorders the data appropriately.

# `from_nx`
*since 0.5.0* 

```elixir
@spec from_nx(tensor :: Nx.Tensor.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Converts an [Nx](https://hex.pm/packages/nx) tensor
into an image.

### Arguments

* `tensor` is any three dimensional `t:Nx.Tensor.t/0`.

* `options` is a keyword list of options. For valid
  options see `Nx.from_binary/2`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

### Notes

In order to convert a tensor into an image it must
satisfy these constraints:

* It must have three dimensions.

* It must have a tensor type that is compatible
  with `libvips` (most tensors will satisfy this
  requirement other than tensors whose type is complex).

* The names of the axes must be `[:width, :height, any_other]`
  or `[:height, :width, any_other]`.

### Example

    iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
    iex> {:ok, tensor} = Image.to_nx(image)
    iex> {:ok, _image_2} = Image.from_nx(tensor)

# `from_nx!`
*since 0.47.0* 

```elixir
@spec from_nx!(tensor :: Nx.Tensor.t()) :: Vix.Vips.Image.t() | no_return()
```

Converts an [Nx](https://hex.pm/packages/nx) tensor
into an image or raises an exception.

### Arguments

* `tensor` is any three dimensional `t:Nx.Tensor.t/0`.

* `options` is a keyword list of options. For valid
  options see `Nx.from_binary/2`.

### Returns

* `image` or

* `{:error, reason}`

### Notes

In order to convert a tensor into an image it must
satisfy these constraints:

* It must have three dimensions.

* It must have a tensor type that is compatible
  with `libvips` (most tensors will satisfy this
  requirement other than tensors whose type is complex).

* The names of the axes must be `[:width, :height, any_other]`
  or `[:height, :width, any_other]`.

### Example

    iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
    iex> {:ok, tensor} = Image.to_nx(image)
    iex> _image_2 = Image.from_nx(tensor)

# `to_evision`
*since 0.9.0* 

Converts an `Image` image to an `t:Evision.Mat.t/0` image.

Note that only images with 3 bands can be transferred
to `eVision`.

### Arguments

* `image` is any `t:Vimage.t/0`.

* `convert_to_bgr` is a boolean indicating if the
  color order should be converted from `RGB` to `BGR`
  which is the normal channel layout for OpenCV. The
  default is `true`.

### Returns

* `{:ok, evision_image}`

* `{:error, reason}`

### Notes

* `Image` images have the shape `{width, height, bands}`
  whereas `Evision` images have the shape `{height, width, bands}`
  so this function transposes the dimensions to match.

* `Image` data is arranged as `rgb` data elements whereas
  `Evision` requires the data to be in `bgr` order. This function
  also reorders the data appropriately.

# `to_list`
*since 0.62.0* 

```elixir
@spec to_list(image :: Vix.Vips.Image.t()) :: {:ok, list()} | {:error, error()}
```

Returns an image as a nested list of pixels.

### Arguments

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

### Returns

* `{:ok, list}` where `list` is a list of rows where is row is a list
  of pixels and each pixel is a list of numbers. Each pixel will have
  1 to 4 numbers depending on the number of bands in the image.

* `{:error, reason}`

### Notes

This function is intended primary for debugging purposes.

It renders the image to memory as a binary (therefore executing a full
image pipeline) and then decomposes the binary into a list of lists.

As a result it can consume considerable amounst of memory and time
for anything other than small images.

### Example

    iex> image = Image.new!(3, 4, color: :green)
    iex> Image.to_list(image)
    {:ok,
     [
       [[0, 128, 0], [0, 128, 0], [0, 128, 0]],
       [[0, 128, 0], [0, 128, 0], [0, 128, 0]],
       [[0, 128, 0], [0, 128, 0], [0, 128, 0]],
       [[0, 128, 0], [0, 128, 0], [0, 128, 0]]
     ]}

# `to_nx`
*since 0.5.0* 

```elixir
@spec to_nx(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Nx.Tensor.t()} | {:error, error()}
```

Converts an image into an [Nx](https://hex.pm/packages/nx)
tensor.

### Arguments

* `image` is any `t:Vimage.t/0`

* `options` is a keyword list of options

### Options

* `:shape` determines how the tensor is shaped. The valid
  values are:

  * `:hwb` or `:hwc` which leaves the tensor unchanged with
    the underlying data in `{height, width, bands}` shape.
    This is the default action.

  * `:whc` or `:whb` which reshapes the tensor to
    `width, height, bands`.

### Returns

* `{:ok, tensor)` where tensor is an `t:Nx.Tensor.t/0` tensor
  suitable for use in the `Nx` library or

* `{:error, reason}`.

### Note

* The image type, `t:Vix.Vips.Image.t/0` stores data in
  `{width, height, band}` format. However when the data is conerted
  into an `t:Nx.Tensor.t/0` the data is written in `{height, width, band}`
  format.

### Example

    iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
    iex> Image.to_nx(image, backend: Nx.BinaryBackend)
    {:ok,
      Nx.tensor([[[0], [0], [0]], [[0], [0], [0]], [[0], [0], [0]]],
        type: {:u, 8}, names: [:height, :width, :bands], backend: Nx.BinaryBackend)}

# `to_nx!`
*since 0.27.0* 

```elixir
@spec to_nx!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Nx.Tensor.t() | no_return()
```

Converts an image into an [Nx](https://hex.pm/packages/nx)
tensor.

### Arguments

* `image` is any `t:Vimage.t/0`

* `options` is a keyword list of options

### Options

* `:shape` determines how the tensor is shaped. The valid
  values are:

  * `:hwb` or `:hwc` which leaves the tensor unchanged with
    the underlying data in `{height, width, bands}` shape.
    This is the default action.

  * `:whc` or `:whb` which reshapes the tensor to
    `width, height, bands`.

### Returns

* `tensor` where tensor is an `t:Nx.Tensor.t/0` tensor
  suitable for use in the `Nx` library or

* raises an exception.

### Note

* The image type, `t:Vix.Vips.Image.t/0` stores data in
  `{width, height, band}` format. However when the data is conerted
  into an `t:Nx.Tensor.t/0` the data is written in `{height, width, band}`
  format.

### Example

    iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
    iex> Image.to_nx!(image, backend: Nx.BinaryBackend)
    Nx.tensor([[[0], [0], [0]], [[0], [0], [0]], [[0], [0], [0]]],
      type: {:u, 8}, names: [:height, :width, :bands], backend: Nx.BinaryBackend)

# `p`
*since 0.13.0* 

```elixir
@spec p(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | {:error, error()}
```

Outputs an inline preview of an image to
an iTerm2 terminal.

Only iTerm2 terminal windows are supported.

Delegates to `Image.preview/1`

### Arguments

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

### Notes

* The function `Image.p/1` is delegated to
  this function.

* The maximum width of the preview can be set
  by the environment variable `IMAGE_PREVIEW_MAX_WIDTH`.
  The default is `1_000` pixels wide. If the width
  of the image is greater than the maximum it will be
  resized to the maximum width for the preview.

* Intended to be used as shortcut in `iex`.
  It can be included in `.iex.exs` file:

    # .iex.exs
    import_if_available(Image, only: [p: 1])

# `preview`
*since 0.13.0* 

```elixir
@spec preview(Vix.Vips.Image.t() | {:ok, Vix.Vips.Image.t()}) ::
  Vix.Vips.Image.t() | {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Outputs an inline preview of an image to
an iTerm2 terminal.

Only iTerm2 terminal windows are supported.

### Arguments

* `image` is any `t:Vix.Vips.Image.t/0` or
  a tuple of the form `{:ok, image}`.

### Returns

* The `image` parameter as provided with the
  side effect of emitting an image preview on
  an iTerm terminal.

### Notes

* The function `Image.p/1` is delegated to
  this function.

* The maximum width of the preview can be set
  by the environment variable `IMAGE_PREVIEW_MAX_WIDTH`.
  The default is `1_000` pixels wide. If the width
  of the image is greater than the maximum it will be
  resized to the maximum width for the preview.

* Intended to be used as shortcut in `iex`.
  It can be included in an `.iex.exs` file:

    # .iex.exs
    import_if_available(Image, only: [preview: 1])

# `to_kino`
*since 0.51.0* 

Transfers an image to Kino for display
in a livebook.

### Arguments

* `image` is any `t:Vimage.t/0`.

### Returns

* a Kino image struct.

### Example

    iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
    iex> %Kino.Image{} = Image.to_kino(image)
    iex> match?(%Kino.Image{}, Image.to_kino(image))
    true

# `is_box`
*macro* 

Guards whether the coordinates can be reasonably
interpreted as a bounding box.

`left` and `top` when positive are relative to
the left and top of the image respectively. When
negative they are relative to the right and bottom
of the image.

# `is_multiplier`
*macro* 

Guards whether a value is a multiplier as representeed
by a float greater than `0.0`.

# `is_percent`
*macro* 

Guards whether a value is a percentage as representeed
by a float between `-1.0` and `1.0`.

# `is_pixel`
*macro* 

Guards whether a term might be reasonably interpreted
as an image pixel — that is, *not* a `Vix.Vips.Image` or
`Vix.Vips.MutableImage`, but anything else `Color.new/2`
(or `Image.Pixel.to_pixel/3`) could turn into a pixel.

Accepts numbers, lists, atoms (CSS named colours),
binary inputs (hex strings, named colours), and `Color.*`
structs. `Vix.Vips.Image` / `Vix.Vips.MutableImage` are
explicitly excluded so callers can dispatch between
"image" and "color" arguments cleanly.

# `is_positive_percent`
*macro* 

Guards whether a value is a positive percentage as representeed
by a float greater than `0.0` and less than or equal to `1.0`.

# `is_rectangle`
*macro* 

Guards whether a parameter is a rectangular bounding box. A
rectangular bounding box is a list of four 2-tuples that must
represent a rectangle (not an arbitrary quadrilateral),

The order of points is top_left -> top right -> bottom
right -> bottm left.

# `is_size`
*macro* 

Guards whether a number can be reasonably interpreted
as a size (as in size of a crop or mask)

# `get_concurrency`

```elixir
@spec get_concurrency() :: pos_integer()
```

Returns the number of operating system
threads available for use by `libvips`.

By default the number of threads will be
the number of cores in the system.

Since image processing is CPU intensive it
may be appropriate to reduce the number of
threads to be available to reduce the risk
of CPU starvation for other workloads.

See `Image.put_concurrency/1`.

# `put_concurrency`

```elixir
@spec put_concurrency(pos_integer()) :: pos_integer()
```

Sets the number of available threads for use
by `libvips`.

By default this is the same as the number of
cores in the system. Reducing this number may
prevent CPU starvation for other workloads.

### Arguments

* `concurrency` is a positive integer denoting
  the maximum number of threads that `libvips` will
  use for concurrency.

### Returns

* `{:ok, updated_concurrency}`

# `vips_version`

```elixir
@spec vips_version() :: {:ok, Version.t()}
```

Returns the version of `libvips` in
operation.

# `aspect`

```elixir
@type aspect() :: :landscape | :portrait | :square
```

Image orientation.

# `bounding_box`

```elixir
@type bounding_box() ::
  {left :: non_neg_integer(), top :: non_neg_integer(),
   width :: non_neg_integer(), height :: non_neg_integer()}
```

The bounding box returned by find_time/2

# `composition`

```elixir
@type composition() ::
  Vix.Vips.Image.t() | {Vix.Vips.Image.t(), Image.Options.Compose.t()}
```

A composition can be a simple image, or an image with
associated composition options.

# `composition_list`

```elixir
@type composition_list() :: [composition(), ...]
```

A list of images or images with placement options used in
Image.compose/2.

# `error`

```elixir
@type error() :: Image.Error.t()
```

The error half of every `{:ok, _} | {:error, _}` tuple returned by
this library is an `Image.Error` struct. The struct carries a
structured `:reason` (atom or `{atom, value}` tuple), an optional
`:operation`, `:path`, and `:value`, plus a derived `:message`.

See `Image.Error` for the full set of reason atoms and the pattern
for matching on them.

# `format`

```elixir
@type format() :: {:u | :s | :f | :c | :bf, 8 | 16 | 32 | 64 | 128}
```

The data type of the image, using the same
type definitions as `t:Nx.Type.t/0`.

# `image_data`

```elixir
@type image_data() :: Path.t() | File.Stream.t() | binary() | Enumerable.t()
```

The valid sources of image data when opening an
image.

# `image_hash`

```elixir
@type image_hash() :: binary()
```

A 512 bit binary hash of an image.

Useful for comparing the similarity of
two images. See `Image.dhash/1` and
`Image.hamming_distance/2`.

# `image_or_color`

```elixir
@type image_or_color() :: Vix.Vips.Image.t() | Image.Pixel.t() | number()
```

Represents either an image or a color value used to fill a new
image. The colour form accepts everything `Image.Pixel.to_pixel/3`
understands plus a bare numeric value (treated as a uniform grey).

# `kino_image`

```elixir
@type kino_image() :: %{
  :file_ref =&gt; {:file, binary()} | binary(),
  :format =&gt; :rgb | :png,
  optional(:width) =&gt; pos_integer(),
  optional(:height) =&gt; pos_integer()
}
```

THe structure of an image returned from `Kino.Input.read/1`
when the input field is a `Kino.Input.image/1` type.

# `pixel`

```elixir
@type pixel() :: [number()] | number()
```

A pixel is represented as a list of number values or
a single number (which is then assumed to be the value
for all bands).

The number of list elements is determined by
the colorspace interpretations. For example:

* `RGB` colorspace would be represented by
  a list of three floats like `[0.0, 0,0, 0.0]` for black.

* `CMYK` colorspace would be represented by a
  list of four floats.

* A `PNG` image can be in any appropriate
  colorspace but may also have an `alpha` band
  and therefore have three, four or five floats
  in a list to represent the pixel.

# `point`

```elixir
@type point() :: {x :: non_neg_integer(), y :: non_neg_integer()}
```

Representaton of a coordinate in an image.

The first number is the displacement on the
x-axis (starting at 0 from the left) and the
second number is the displacement on the
y-axis (starting at 0 from the top).

# `quadrilateral`

```elixir
@type quadrilateral() :: [{x :: non_neg_integer(), y :: non_neg_integer()}, ...]
```

An image bounding box being a four element list
of 2-tuples representing the points of a rectangle
in the order top left -> top right -> bottom right ->
bottom left.

# `render_intent`

```elixir
@type render_intent() :: :perceptual | :relative | :saturation | :absolute
```

The valid rendering intent values. For all
functions that take an optional intent
parameter the default is `:perceptual`.

## Perceptual Intent

Perceptual rendering is used to process photographic
type images. This intent processes the colors so that
the output reproduction is pleasing. This process
tends to change the color from the original, so no
guarantee the reproduction will be accurate against
the original.

## Relative Intent

Relative colorimetric changes all the colours out
of gamut to the nearest colour in gamut, so many
colours change to the same one. It DOES NOT change
colours in gamut. Perceptual changes ALL the colours
in the image in a proportional way so that they lie
in the output device gamut.

## Saturation Intent

Saturation moves in-gamut colors toward the edge of the
destination gamut for maximum saturation and impact.
This intent will make an image more colorful by using
the full gamut of the destination device. This intent
cares not for the genuine representation of color.

## Absolute Intent

Absolute rendering attempts to reproduce all
colors numerically (destination = source). This
can cause unexpected results if the source gamut is
larger than the destination.

# `transparency`

```elixir
@type transparency() :: 0..255 | :opaque | :transparent
```

The level of transparency for an alpha band
where `0` means fully opaque and `255` means
fully transparent.

# `x_location`

```elixir
@type x_location() :: integer() | :left | :center | :right
```

The x location on an image which is either a
non_negative 0-based integer relative to the image left or
a negative -1-based integer relative to the image right or
the symbolic references `:left`, `:center` and
`:right`.

# `y_location`

```elixir
@type y_location() :: integer() | :top | :middle | :bottom
```

The y location on an image which is either a
non_negative 0-based integer relative to the image top or
a negative -1-based integer relative to the image right or
the symbolic references `:top`, `:middle` and
`:bottom`.

# `average`
*since 0.27.0* 

```elixir
@spec average(Vix.Vips.Image.t()) :: Image.Pixel.t() | {:error, error()}
```

Returns the average color of an image.

The average is calculated for each band
of an image and then combined.

### Arguments

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

### Returns

* A list of average pixel values which can
  be interpreted as the average color of the
  image.

### Example

      iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
      ...> |> Image.average()
      [66, 86, 106]

# `average!`
*since 0.27.0* 

```elixir
@spec average!(Vix.Vips.Image.t()) :: Image.Pixel.t() | no_return()
```

Returns the average color of an image or
raises and exception.

The average is calculated for each band
of an image and then combined.

### Arguments

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

### Returns

* A list of average pixel values which can
  be interpreted as the average color of the
  image.

### Example

      iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
      ...> |> Image.average!()
      [66, 86, 106]

# `from_kino`
*since 0.27.0* 

```elixir
@spec from_kino(image :: kino_image(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

Returns an image from a [Kino](https://hex.pm/packages/kino) image
input.

### Arguments

* `image` is a a map returned from `Kino.Input.read(image)`
  via a `Kino.Input.image/1` input field. The data will have
  the following fields:

  * `:file_ref` which contains a file reference to the image. It can be dereferenced
    into a path with `Kino.Input.file_path/1`
  * `:width` which is the width of the image in pixels
  * `:height` which is the height of the image in pixels
  * `:format` which is the image band format which must be `:rgb` or `:png`.

* `options` is a keyword list of options that is passed to `Image.open/2`
  in the case of a `:png` image.

### Notes

* This function is only defined when the optional dependency
  `:kino` (v0.11.0 or later) is configured in `mix.exs`.

* For image type of `:rgb`, the image is required to contain raw pixel data
  that is in unsigned 8-bit rgb format.

* For image type of `:png`, the image can by any format and it will be
  opened with `Image.open/2`. Any options are passed to `Image.open/2`.

### Returns

* `{:ok, image}` or

* `{:error, reason}`

# `from_kino!`
*since 0.27.0* 

```elixir
@spec from_kino!(image :: kino_image(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

Returns an image from a [Kino](https://hex.pm/packages/kino) image
input or raises an exception.

### Arguments

* `image` is a a map returned from `Kino.Input.read(image)`
  via a `Kino.Input.image/1` input field. The data will have
  the following fields:

  * `:file_ref` which contains a file reference to the image. It can be dereferenced
    into a path with `Kino.Input.file_path/1`
  * `:width` which is the width of the image in pixels
  * `:height` which is the height of the image in pixels
  * `:format` which is the image band format which must be `:rgb` or `:png`.

* `options` is a keyword list of options

### Options

* `options` is a keyword list of options that is passed to `Image.open/2`
  in the case of a `:png` image.

### Notes

* This function is only defined when the optional dependency
  `:kino` (v0.11.0 or later) is configured in `mix.exs`.

* For image type of `:rgb`, the image is required to contain raw pixel data
  that is in unsigned 8-bit rgb format.

* For image type of `:png`, the image can by any format and it will be
  opened with `Image.open/2`. Any options are passed to `Image.open/2`.

### Returns

* `image` or

* raises an exception.

# `from_req_stream`
*since 0.61.0* 

Opens an image as a stream from a URL that will be retrieved
by [Req](https://github.com/wojtekmach/req) request.

The URL is retrieved by `Req.get!(url, into: :self)` which is then
wrapped in a `Stream.resource/3` and opened as a streaming image.

### Arguments

* `url` is any URL representing an image or a t:Req.Request.t/1

* `options` is a keyword list of options.

### Options

* `:timeout` is an integer number of milliseconds upon which
  the next chunk of the image stream is waited. If the timeout is
  exceeded then an error is returned. The default is 5000
  milliseconds.

### Returns

* `{:ok, image}` or

* `{:error reason}`

### Notes

* Due to the nature of the interaction between Req and Vix, error
  responses from the embedded `Reg.get/2` are swallowed and a generic
  `{:error, %Image.Error{message: "Failed to find loader for the source", reason: "Failed to find loader for the source"}}` may be returned instead.

### Example

    url = "https://files.amoi.no/dog.webp"
    Image.from_req_stream(url)
    {:ok, %Vix.Vips.Image{ref: #Reference<0.3575018002.2188509222.143025>}}

# `is_image`
*macro* 

Guards whether the given struct is an image type
either `Vix.Vips.Image` or `Vix.Vips.MutableImage`.

# `join`

```elixir
@spec join(
  image_list :: [Vix.Vips.Image.t()],
  options :: Image.Options.Join.join_options()
) ::
  {:ok, joined_image :: Vix.Vips.Image.t()} | {:error, error()}
```

Join a list of images into a single image.

### Arguments

* `image_list` is a non-empty list of `t:Vimage.t/0`
  images.

* `options` is a keyword list of options.

### Options

* `:across` is an integer number of images in the
  horizontal direction of the grid. The default is `1`.

* `:vertical_spacing` determines the height in pixels of
  each image row. The default, `0`, means that the row
  height is the maximum height of the
  images in `image_list`.

* `:horizontal_spacing` determines the width in pixels of
  each image in a row. The default, `0`, means
  that the width is the maximum width of the
  images in `image_list`.

* `:vertical_align` is `:bottom`, `:middle` or `:top`.
  The default is `:bottom`.

* `:horizontal_align` is `:left`, `:center` or `:right`.
  The default is `:left`.

* `:background_color` is the color of any pixels generated
  between images. This can be specified as a single integer
  which will be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

* `:shim` is the number of pixels of spacing between
  images in the grid. The default is `0`.

### Returns

* `{:ok, joined_image}` or

* `{:error, reason}`

### Notes

`Image.join/2` lays out the list of images in a grid.
The grid is `:across` images across and however high
is necessary to use up all of `image_list`.  Images are
set down left-to-right and top-to-bottom.

Each input image is placed with a box of size `:horizontal_spacing`
by `:vertical_spacing` pixels and cropped. These default
to the largest width and largest height of the input images.

Space between images is filled with `:background_color` .
This defaults to black.

Images are positioned within their `:horizontal_spacing` by
`:vertical_spacing` box at `:vertical_align` of `:bottom`,
`:middle` or `:top` and by `:horizontal_align` of `:left`,
`:center` or `:right`. The defaults are `:bottom`, `:left`.

# `join!`

```elixir
@spec join!(
  image_list :: [Vix.Vips.Image.t()],
  options :: Image.Options.Join.join_options()
) ::
  joined_image :: Vix.Vips.Image.t() | no_return()
```

Join a list of images into a single image or raises
an exception.

### Arguments

* `image_list` is a non-empty list of `t:Vimage.t/0`
  images.

* `options` is a keyword list of options.

### Options

* `:across` is an integer number of images in the
  horizontal direction of the grid. The default is `1`.

* `:vertical_spacing` determines the height in pixels of
  each image row. The default, `0`, means that the row
  height is the maximum height of the
  images in `image_list`.

* `:horizontal_spacing` determines the width in pixels of
  each image in a row. The default, `0`, means
  that the width is the maximum width of the
  images in `image_list`.

* `:vertical_align` is `:bottom`, `:middle` or `:top`.
  The default is `:bottom`.

* `:horizontal_align` is `:left`, `:center` or `:right`.
  The default is `:left`.

* `:background_color` is the color of any pixels generated
  between images. This can be specified as a single integer
  which will be applied to all bands, or a list of
  integers representing the color for each
  band. The default is `0`, meaning black. The color
  can also be supplied as a CSS color name as a
  string or atom. For example: `:misty_rose`. See
  `Color.new/2` from the Color library.

* `:shim` is the number of pixels of spacing between
  images in the grid. The default is `0`.

### Returns

* `{:ok, joined_image}` or

* `{:error, reason}`

### Notes

`Image.join/2`Lay out the list of images in a grid.
The grid is `:across` images across and however high
is necessary to use up all of `image_list`.  Images are
set down left-to-right and top-to-bottom.

Each input image is placed with a box of size `:horizontal_spacing`
by `:vertical_spacing` pixels and cropped. These default
to the largest width and largest height of the input images.

Space between images is filled with `:background_color` .
This defaults to black.

Images are positioned within their `:horizontal_spacing` by
`:vertical_spacing` box at `:vertical_align` of `:bottom`,
`:middle` or `:top``and by `:horizontal_align` of `:left`,
`:center` or `:righ`. The defaults are `:bottom`, `:left.

# `linear_gradient`

```elixir
@spec linear_gradient(Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
@spec linear_gradient(width :: pos_integer(), height :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

# `linear_gradient`

```elixir
@spec linear_gradient(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Keyword.t()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error()}
```

# `linear_gradient!`

```elixir
@spec linear_gradient!(Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
```

# `linear_gradient!`

---

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