@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• An integer in the range 1..4 depending on the image interpretation. Returns nil if there is no alpha band.

@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• auto_rotated_image or

• raises an exception.

@spec autorotate(image :: Vix.Vips.Image.t()) ::
  {:ok, {Vix.Vips.Image.t(), Keyword.t()}} | {:error, error_message()}

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

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, {auto_rotated_image, flags}} or

• {:error, reason}

flags

Flags

Two flags are returned indicating what action was 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.

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

Make a circular image intended to be used as an avatar image returning an image or raising an exception.

The image is resized, a circular mask is applied and all metadata is removed from the image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• size is the diameter of the resulting image after resizing. The default value is 180.

• options is a keyword list of options. See Image.resize/3 for the valid options.

returns

Returns

• avatar_image or

• raises an exception.

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

Make a circular image intended to be used as an avatar image.

The image is resized, a circular mask is applied and all metadata is removed from the image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• size is the diameter of the resulting image after resizing. The default value is 180.

• options is a keyword list of options. See Image.resize/3 for the valid options.

returns

Returns

• {:ok, avatar_image} or

• {:error, reason}

@spec bands(Vix.Vips.Image.t()) :: 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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• An integer number of bands in the image.

@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• circular_image or

• raises an exception.

@spec circle(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, circular_image} or

• {:error, reason}

@spec compose!(
  base_image :: Vix.Vips.Image.t(),
  overlay_image :: Vix.Vips.Image.t(),
  options :: Keyword.t()
) :: Vix.Vips.Image.t() | no_return()

@spec compose!(
  base_image :: Vix.Vips.Image.t(),
  image_list :: [Vix.Vips.Image.t(), ...],
  options :: Keyword.t()
) :: Vix.Vips.Image.t() | no_return()

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

arguments

Arguments

• base_image is any Vix.Vips.Image.t/0.

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

• options is a keyword list of options.

options

Options

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

• :x is the offset (0-based) from the left 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) from the top 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

Composition list options

When overlay_image is an image_list, each entry in the list is either a Vix.Vips.Image.t/0 or a composition/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 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

Returns

• composed_image or

• raises an exception

examples

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}
...> ])

@spec compose(
  base_image :: Vix.Vips.Image.t(),
  overlay_image :: Vix.Vips.Image.t(),
  options :: Keyword.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

@spec compose(
  base_image :: Vix.Vips.Image.t(),
  image_list :: [Vix.Vips.Image.t(), ...],
  options :: Keyword.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Compose two images together to form a new image.

arguments

Arguments

• base_image is any Vix.Vips.Image.t/0.

• overlay_image is any Vix.Vips.Image.t/0 that will be composed over the top of base_image. It can also be a list of composition/0s 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

Options for a single overlay image

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

• :x is the offset (0-based) from the left 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) from the top 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

Composition list options

When overlay_image is an image_list, each entry in the list is either a Vix.Vips.Image.t/0 or a composition/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 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

Returns

• {:ok, composed_image} or

• {:error, reason}

examples

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}
...> ])

@spec convert_to_mask!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()

Convert an image into a mask returning an image or raising an exception.

Takes an image, extracts its alpha channel which holds the opacity information and inverts the content.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• mask image or

• raises an exception

@spec convert_to_mask(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Convert an image into a mask.

Takes an image, extracts its alpha channel which holds the opacity information and inverts the content.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• {:ok, mask} or

• {:error, reason}

@spec crop!(Vix.Vips.Image.t(), integer(), integer(), pos_integer(), pos_integer()) ::
  Vix.Vips.Image.t() | no_return()

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

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• left is the left edge of extract area as a positive integer.

• top is the top edge of extract area as an integer. If top is positive it is relative to the top of the image. If it is negative it is relative to the bottom of the image.

• width is the width of extract area as a positive integer.

• height is the height of extract area as a positive integer.

returns

Returns

• cropped_image or

• raises an exception.

@spec crop(Vix.Vips.Image.t(), integer(), integer(), pos_integer(), pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Crop an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• left is the top edge of crop area as an integer. 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.

• top is the top edge of crop area as an integer. 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.

• width is the width of area remaining as a positive integer.

• height is the height of the area remaining as a positive integer.

notes

Notes

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

• top is 0-indexed. That is, the toptmost edge of the image starts at 0.

returns

Returns

• {:ok, cropped_image} or

• {:error, reason}

Returns a 512-bit difference hash as a binary.

Image hashes can be used to compare the similarity of images. See Image.hamming_distance/2.

dhash is generates a "difference hash" for a given image -- a perceptual hash based on Neal Krawetz's dHash algorithm in a Hacker Factor blog entry.

The code is adapted from the Ruby implementation in dhash-vips.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, 512-bit binary} or

• {:error, reason}

@spec dominant_color(Vix.Vips.Image.t(), Keyword.t()) :: Image.Color.rgb_color()

Returns the dominant color of an image as an RBG triplet value in an integer list.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• options is a keyword list of options. The default is [].

options

Options

• :bins is an integer number of color frequency bins the image is divided into. The default is 10.

returns

Returns

• [r, g, b]

@spec exif(Vix.Vips.Image.t()) :: {:ok, map()}

Returns the EXIF data for an image as a map.

Only a subset of EXIF data is returned but its a substantial subset.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• {:ok, exif_map} where exif_map is a map of selected EXIF data.

@spec fft!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()

Returns the fast fourier transform (fft) of the given image returning an image or raising an exception.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• fft_image or

• raises an exception

example

Example

Image.fft!(image)

@spec fft(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Returns the fast fourier transform (fft) of the given image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• {:ok, fft_image} or

• {:error, reason}

example

Example

Image.fft(image)

@spec filename(image :: Vix.Vips.Image.t()) :: Path.t() | nil

Returns the filename for an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

returns

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.

@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

Arguments

• image is any Vix.Vips.Image.t/0.

• direction is either :horizontal or :vertical.

returns

Returns

• flipped_image or

• raises an exception.

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

Flip an image horizontally or vertically.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• direction is either :horizontal or :vertical.

returns

Returns

• {:ok, flipped_image} or

• {:error, reason}

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

Returns a 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

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

Returns

• {:ok, image} or

• {:error, reason}

@spec from_nx(tensor :: Nx.Tensor.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Converts an Nx tensor into an image.

arguments

Arguments

• tensor is any three dimensional Nx.Tensor.t/0.

• options is a keyword list of options. For valid options see Nx.from_binary/2.

returns

Returns

• {:ok, image} or

• {:error, reason}

notes

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

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)

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

@spec get_pixel(Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, Image.Color.rgb_color()} | {:error, error_message()}

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.

arguments

Arguments

• image is any 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

Returns

• {:ok, pixel_value} or

• {:error, reason}

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

@spec hamming_distance(image_hash(), image_hash()) ::
  {:ok, non_neg_integer()} | {:error, error_message()}

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

A 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

Arguments

• image_1 is any Vix.Vips.Image.t/0

• image_2 is any 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

Returns

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

• {:error, reason}.

@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• true or false

@spec height(Vix.Vips.Image.t()) :: integer()

Returns the height of an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• The image height as an integer.

@spec histogram(Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Returns the histogram for an image.

The histogram is returned as a t:Vimage.t/0 that is a 255 by 255 image with three bands.

argument

Argument

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, histogram_image} or

• {:error, reason}

notes

Notes

The returned image is is organized as a 256x256 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.

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.

Guards whether a term might be reasonably interpreted as an image pixel.

Guards whether a number can be reasonably interpreted as a size (as in size of a crop or mask)

@spec linear_gradient!(
  Vix.Vips.Image.t(),
  start :: Image.Color.rgb_color(),
  finish :: Image.Color.rgb_color()
) :: Vix.Vips.Image.t() | no_return()

Create an image gradient of the same size as the given image. Returns the gradient image or raises and exception.

The gradient will interpolate from the start value to the finish value. The default start value is black with 100% transparency. The default finish value is black with 100% opacity.

start and finish are given as an rgb triplet or quadruplet list of integers between 0 and 255.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

• :start is anrgbtriplet or quadruplet list of numbers between0and255. *:finish is an rgb triplet or quadruplet list of numbers between 0 and 255.

returns

Returns

• gradient_image or

• raises an exception.

example

Example

# transparent_black and opaque_black are the default
# start and finish values
transparent_black = [0, 0, 0, 0]
opaque_black = [0, 0, 0, 255]
gradient = Image.linear_gradient!(image, transparent_black, opaque_black)

@spec linear_gradient(
  Vix.Vips.Image.t(),
  start :: Image.Color.rgb_color(),
  finish :: Image.Color.rgb_color()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Create an image gradient of the same size as the given image.

The gradient will interpolate from the start value to the finish value. The default start value is black with 100% transparency. The default finish value is black with 100% opacity.

start and finish are given as an rgb triplet or quadruplet list of integers between 0 and 255.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

• :start is anrgbtriplet or quadruplet list of numbers between0and255. *:finish is an rgb triplet or quadruplet list of numbers between 0 and 255.

returns

Returns

• {:ok, gradient_image} or

• {:error, reason}

example

Example

# transparent_black and opaque_black are the default
# start and finish values
transparent_black = [0, 0, 0, 0]
opaque_black = [0, 0, 0, 255]
{:ok, gradient} = Image.linear_gradient(image, transparent_black, opaque_black)

@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

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• image_with_minimal_metadata or

• raises an exception.

@spec minimize_metadata(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

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.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• {:ok, image_with_minimal_metadata} or

• {:error, reason}

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

Mutate an image with through the given function.

This funcation is a convenience wrapper around Vix.Vips.Image.mutate/2.

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

Create a new image of the given dimensions and background color.

arguments

Arguments

• width is the image width as an integer.

• height is the image height as an integer.

• options is a keyword list of options.

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 Image.Color.color_map/0 and Image.Color.rgb_color/1.

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

• :interpretation defines the interpretation of the image. The default is :srgb.

returns

Returns

• {:ok, image} or

• {:error, reason}

examples

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)

@spec open!(
  image_path :: Path.t(),
  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

Arguments

• image_path is the file system path to an image file.

• options is a keyword list of options. See Image.open/2.

returns

Returns

• image or

• raises an exception.

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

Opens an image file or stream for image processing.

arguments

Arguments

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

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

options

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 :sequentual. When :sequential, Image (via Vix) is able to support streaming transformations and optimise memory usage more effectively. Howwevef :sequenial also means that some operationas 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 intend to resize it to smaller dimensions. The default value is 1 meaning no shrnk-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 1..1024 with a default of 1.

• :page indicates the image page to be loaded. The value is in the range 0..100_000 with a default value of 0.

• :pages indicates how many pages to load. The value is in the range 1..100_000 with a default value of 1.

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 image page to be loaded. The value is in the range 0..100_000 with a default value of 0.

• :pages indicates how many pages to load. The value is in the range 1..100_000 with a default value of 1.

PNG options

• There are no PNG-specific image loading options.

returns

Returns

• {:ok, image} or

• {:error, message}

Returns the orientation of an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

• options is a keyword list of options

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

Returns

• Either :landscape, :portrait or :square.

example

Example

iex> puppy = Image.open!(Path.expand("images/puppy.webp"))
iex> Image.orientation(puppy, square_ratio: 0.05)
:landscape

@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

Arguments

• concurrency is a positive integer denoting the maximum number of threads that libvips will use for concurrency.

returns

Returns

• {:ok, updated_concurrency}

@spec radial_gradient(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Keyword.t()
) ::
  {:ok, %Vix.Vips.Image{ref: term()}} | {:error, error_message()}

Returns a radial gradient as an image.

This image might then be composited over another image.

arguments

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. The default is [].

options

Options

• :start is the color from which the gradient starts in the center of the image.

• :finish is the color at which the gradient finishes at the end of the gradient.

• :feather is the slope of the gradient. That it, how quickly the gradient moves from the :start 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).

returns

Returns

• {:ok, gradient_image} or

• {:error, reason}

@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

Arguments

• image is any 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 metadata
  • :iptc which means remove all IPTC metadata
  • :xmp which means remove all xmp data

notes

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 is 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

Returns

• image_without_metadata_fields or

• raises an exception.

@spec remove_metadata(Vix.Vips.Image.t(), [binary() | atom()]) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Remove metadata from an image returning an updated image or raising an exception.

This can significantly reduce the size of an image file.

arguments

Arguments

• image is any 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 metadata
  • :iptc which means remove all IPTC metadata
  • :xmp which means remove all xmp data

notes

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 is 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

Returns

• {:ok, image_without_metadata_fields} or

• {:error, reason}

@spec resize!(
  Vix.Vips.Image.t() | Path.t(),
  width_or_dimensions :: pos_integer() | binary(),
  options :: Image.Options.Resize.resize_options()
) :: Vix.Vips.Image.t() | no_return()

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

arguments

Arguments

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

• width is the integer width 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 width.

• options is a keyword list of options. See Image.resize/3.

returns

Returns

• image or

• raises an exception.

@spec resize(
  Vix.Vips.Image.t(),
  width :: pos_integer() | binary(),
  options :: Image.Options.Resize.resize_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

@spec resize(
  Path.t(),
  width :: pos_integer(),
  options :: Image.Options.Resize.resize_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

@spec resize(
  Vix.Vips.Image.t() | Path.t(),
  dimensions :: binary(),
  options :: Image.Options.Resize.resize_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Resize an image to fit or fill a bounding box.

arguments

Arguments

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

• width is the integer width 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 width.

• options is a keyword list of options.

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 Image.Options.Crop.crop_focus/0.

• :autorotate is a boolean indicating if the image should be autorated based upon the image metadata. The default is true.

• :intent indicates the rendering intent. The default is :relative. See also 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, or both. The value may be one of :up, :down, :both or :force. The default is :both.

• :height - Size to this height. Default is to maintain the image aspect ratio unless resize: :force is set.

returns

Returns

• {:ok, resized_image} or

• {:error, reason}

@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• image_with_ripple or

• raises an exception.

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

Adds a concentric ripple effect to an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, image_with_ripple} or

• {:error, reason}

@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

Arguments

• image is any 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

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

Returns

• rotated_image or

• raises an exception.

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

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

arguments

Arguments

• image is any 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

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

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

Returns

• {:ok, rotated_image} or

• {:error, reason}

@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

Arguments

• image is any Vix.Vips.Image.t/0.

• options is a keyword list of options.

options

Options

• :radius is the desired corner radius. The default is 50.

returns

Returns

• rounded_corner_image or

• raises an exception.

@spec rounded(Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Apply rounded corners to an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• options is a keyword list of options.

options

Options

• :radius is the desired corner radius. The default is 50.

returns

Returns

• {:ok, rounded_corner_image} or

• {:error, reason}

@spec skew_angle(Vix.Vips.Image.t()) :: float()

Attempts top determine the distance from the perpendicular for a given image.

The principle is that rotating the image by the skew angle should return an image in the upright position.

The results are very image sensitive and perfect results are not guaranteed.

The algorithm is an implementation of this stackoverflow post.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• skew_angle which is a float number of degrees the image is tilted from the upright.

Example

skew_angle = skew_angle(image)
Image.rotate(image, skew_angle)

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

Convert an image into an enumerable stream.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

• options is a keyword list of options.

options

Options

• :buffer_size is the size in bytes for each chunk in the stream being written. Some services, like AWS S3, require a minumum 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

Returns

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

example

Example

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

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

Since AWS S3 requires multipart uploads to be 5MiB per chunk, we specify the :buffer_size option to Image.stream!/2.

@spec to_colorspace!(Vix.Vips.Image.t(), Image.Interpretation.t()) ::
  Vix.Vips.Image.t() | no_return()

Converts an impage to the given colorspace returning an image or raising an exception.

Available colorspaces are returned from Image.Interpretation.known_interpretations/0.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

• colorspace is any known colorspace. See Image.Interpretation.known_interpretations/0 for a list of the known colorspaces.

returns

Returns

• image_in_new_colorspace or

• raises an exception

example

Example

Image.to_colorspace!(image, :bw)

@spec to_colorspace(Vix.Vips.Image.t(), Image.Interpretation.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Converts an image to the given colorspace.

Available colorspaces are returned from Image.Interpretation.known_interpretations/0.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

• colorspace is any known colorspace. See Image.Interpretation.known_interpretations/0 for a list of the known colorspaces.

returns

Returns

• {;ok, image_in_new_colorspace} or

• {:error, reason}

example

Example

Image.to_colorspace(image, :bw)

@spec to_nx(image :: Vix.Vips.Image.t(), [{:options, Keyword.t()}]) ::
  {:ok, Nx.Tensor.t()} | {:error, error_message()}

Converts an image into an Nx tensor.

arguments

Arguments

• image is any t:Vimage.t/0

returns

Returns

• An Nx.Tensor.t/0 tensor suitable for use in the Nx library.

example

Example

iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
iex> Image.to_nx(image)
{:ok,
  Nx.tensor([[[0], [0], [0]], [[0], [0], [0]], [[0], [0], [0]]], type: {:u, 8}, names: [:width, :height, :bands])}

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

@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

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• image_in_polar_coordinates or

• raises an exception.

Convert image to polar coordinates.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

returns

Returns

• {:ok, image_in_polar_coordinates} or

• {:error, reason}

@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

Arguments

• image is any Vix.Vips.Image.t/0.

notes

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

Returns

• image_in_rectuangular_coordinates or

• raises an exception.

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

Convert image to rectangular coordinates.

arguments

Arguments

• image is any Vix.Vips.Image.t/0.

notes

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

Returns

• {:ok, image_in_rectangular_coordinates} or

• {:error, reason}

@spec vips_version() :: {:ok, Version.t()}

Returns the version of libvips in operation.

@spec width(Vix.Vips.Image.t()) :: integer()

Returns the width of an image.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• The image width as an integer.

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

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

arguments

Arguments

• image is any 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

Returns

• image or

• raises an exception.

@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()} | {:error, error_message()}

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

arguments

Arguments

• image is any 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 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.

• options is a keyword list of options. The default is [].

options

Options

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

all-image-types

All image types

• :profile is the name of any ICC color profile.

• :strip 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 PNG files it is the quantization quality with a default of 100. For HEIF files the default is 50.

streaming-images-and-memory-images

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

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.

png-images

PNG images

• :color_depth is an integer describing the number of bits for each color. The value can be 1, 2, 4, 8 or 16. The default is to use the current color depth of the image. For web applications, 8 bits would be reasonable for photographic images with lower bit depths for monochromatic images or diagrams.

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

• :compression is the image compression factor as an image between 0..9. The default is 6.

tiff-images

TIFF images

• :color_depth which has the same meaning as for PNG images.

heif-images

Heif images

• :compression is the compression strategy to be applied. The allowable values are :hevc, :avc, :jpeg and :av1. The default is :hevc.

@spec xmp(Vix.Vips.Image.t()) :: {:ok, map()}

Returns the XMP data for an image as a keyword list.

Only a selected set of XMP data is returned.

arguments

Arguments

• image is any Vix.Vips.Image.t/0

returns

Returns

• {:ok, xmp_map} where xmp_map is a map of selected XMP data.