View Source Image (image v0.33.0)

Image is based upon the fabulous vix library that provides a libvips 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, Image is approximately 2 to 3 times faster than Mogrify and uses about 5 times less memory.

Link to this section Summary

Types

aspect()

Image orientation.

composition()

A composition can be a simple image, or an image with associated composition options.

composition_list()

A list of images or images with placement options used in Image.compose/2.

error_message()

Error messages returned by libvips

format()

The data type of the image, using the same type definitions as Nx.Type.t/0.

image_data()

The valid sources of image data when opening an image.

image_hash()

A 512 bit binary hash of an image.

image_or_color()

Represents either in image, or a color that is used to fill a new image

kino_image()

THe structure of an image returned from Kino.Input.read/1 when the input field is a Kino.Input.image/1 type.

pixel()

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

quadrilateral()

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()

The valid rendering intent values. For all functions that take an optional intent parameter the default is :perceptual.

transparency()

The level of transparency for an alpha band where 0 means fully opaque and 255 means fully transparent.

x_location()

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()

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.

Files and streams

from_binary(binary, options \\ [])

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

from_binary!(binary, options \\ [])

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

from_svg(svg, options \\ [])

Returns an image created from an SVG string.

from_svg!(svg, options \\ [])

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

new(image)

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

new(width, height)

Create a new image of the given dimensions.

new(width, height, options)

new!(image)

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

new!(width, height)

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

new!(width, height, options)

open(path_or_stream_or_binary, options \\ [])

Opens an image file or stream for image processing.

open!(image_path, options \\ [])

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

stream!(image, options \\ [])

Convert an image into an enumerable stream.

write(image, image_path, options \\ [])

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

write!(image, image_path, options \\ [])

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

Operations

add_alpha(image, alpha_image)

Add an alpha band to an image.

add_alpha!(image, alpha_image)

Add an alpha band to an image.

autolevel(image)

Scales each band of an image to fit the full dynamic range. Unlike Image.normalize/1, each band is scaled separately.

autolevel!(image)

Scales each band of an image to fit the full dynamic range. Unlike Image.normalize/1, each band is scaled separately. Raises an exception on error.

autorotate(image)

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

autorotate!(image)

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

blur(image, options \\ [])

Applies a gaussian blur to an image.

blur!(image, options \\ [])

Applies a gaussian blur to an image.

cast(image, band_format)

Casts an image from one band format to another.

chroma_color(image)

Automatically determine the chroma key color of an image.

chroma_key(image, options \\ [])

Chroma key an image.

chroma_key!(image, options \\ [])

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

chroma_mask(image, options \\ [])

Return a chroma-based masked image.

chroma_mask!(image, options \\ [])

Return a chroma-based masked image or raises an exception.

compose(base_image, overlay_image_or_images, options \\ [])

Compose two images together to form a new image.

compose!(base_image, image_or_image_list, options \\ [])

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

dilate(image, pixels \\ 1)

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

dilate!(image, pixels \\ 1)

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

embed!(image, width, height, options \\ [])

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

erode(image, pixels \\ 1)

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

erode!(image, pixels \\ 1)

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

feather(image, options \\ [])

Feather (blur the edges) of an image mask.

feather!(image, options \\ [])

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

fft(image)

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

fft!(image)

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

flatten(image)

Flatten an alpha layer out of an image.

flatten!(image)

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

flip(image, direction)

Flip an image horizontally or vertically.

flip!(image, direction)

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

get_pixel(image, x, y)

Returns the pixel value at the given image location.

get_pixel!(image, x, y)

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

hamming_distance(image_1, image_2)

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

histogram(image)

Returns the histogram for an image.

if_then_else(condition_image, if_image_or_color, else_image_or_color, options \\ [])

Scans the condition image cond and uses it to select pixels from either the if_image or the else_image.

if_then_else!(condition_image, if_color, else_image_or_color)

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.

map(image, transformation_matrix, options \\ [])

Applies a transformation matrix to an image.

mutate(image, fun)

Mutate an image with through the given function.

normalize(image)

Normalize an image by expanding the luminance of an image to cover the full dynamic range.

normalize!(image)

Normalize an image by expanding the luminance of an image to cover the full dynamic range. Raises an exception on error.

pixelate(image, scale \\ 0.05)

Pixelates an image.

pixelate!(image, scale \\ 0.05)

Pixelates an image or raise an exception.

ripple(image)

Adds a concentric ripple effect to an image.

ripple!(image)

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

rotate(image, angle, options \\ [])

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

rotate!(image, angle, options \\ [])

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

skew_angle(image)

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

split_alpha(image)

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

straighten_perspective(image, source, options \\ [])

Performs a warp perspective transformation on an image to straighten its perspective.

straighten_perspective!(image, source, options \\ [])

Performs a warp perspective transformation on an image to straighten its perspective or raises an exception.

to_polar_coordinates(image)

Convert image to polar coordinates.

to_polar_coordinates!(image)

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

to_rectangular_coordinates(image)

Convert image to rectangular coordinates.

to_rectangular_coordinates!(image)

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

transform_matrix(image, source, destination)

Returns a transformation matrix for a given image, source quadrilateral and desintation quadrilateral.

warp_perspective(image, source, destination, options \\ [])

Performs a warp perspective transformation on an image.

warp_perspective!(image, from, to, options \\ [])

Performs a warp perspective transformation on an image or raises an exception.

with_colorspace(image, colorspace, fun)

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.

without_alpha_band(image, fun)

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

Resize

embed(image, width, height, options \\ [])

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

resize(image, scale, options \\ [])

Resize an image.

resize!(image, scale, options \\ [])

Resize an image or raise an exception.

thumbnail(image_or_path, length, options \\ [])

Thumbnail an image to fit or fill a bounding box.

thumbnail!(image_or_path, length, options \\ [])

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

trim(image, options \\ [])

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

trim!(image, options \\ [])

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

Crop

center_crop(image, width, height)

Crops the center from an image.

center_crop!(image, crop_width, crop_height)

Crops the center from an image.

crop(image, quadrilateral)

Crop an image.

crop(image, left, top, width, height)

Crop an image.

crop!(image, quadrilateral)

Crop an image or raises an exception.

crop!(image, left, top, width, height)

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

Transforms

avatar(image, options \\ [])

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

avatar!(image, options \\ [])

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

linear_gradient(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])

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

linear_gradient!(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])

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

meme(image, headline, options \\ [])

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

meme!(image, headline, options \\ [])

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

radial_gradient(width, height, options \\ [])

Returns a radial gradient as an image.

rounded(image, options \\ [])

Apply rounded corners to an image.

Split & Join

alpha_band(image)

Returns the band number of the alpha channel of an image, or nil if it doesn't have one.

split_bands(image)

Split the image into a list of its component bands.

Color

replace_color(image, options \\ [])

Replace one color in an image with another.

replace_color!(image, options \\ [])

Replace one color in an image with another or raises an exception.

to_colorspace(image, colorspace)

Converts an image to the given colorspace.

to_colorspace!(image, colorspace)

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

Information

aspect(image, options \\ [])

Returns the aspect of an image.

bands(image)

Return the number of bands in an image.

dominant_color(image, options \\ [])

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

filename(image)

Returns the filename for an image.

has_alpha?(image)

Returns a boolean based upon whether a given image has an alpha band.

height(image)

Returns the height of an image.

interpretation(image)

Returns the image interpretation.

shape(image)

Returns the shape of an image.

type(image)

Returns the data type of the image pixels.

width(image)

Returns the width of an image.

Masks

circle(image, options \\ [])

Apply a circular mask to an image.

circle!(image, options \\ [])

Apply a circular mask to an image returning an image or raising an exception.

convert_to_mask(image)

Convert an image into a mask.

convert_to_mask!(image)

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

rounded!(image, options \\ [])

Apply rounded corners to an image. Returns an image or raises an exception.

Metadata

dhash(image, hash_size \\ 8)

Returns a 64-bit difference hash as a binary.

exif(image)

Returns the EXIF data for an image as a map.

minimize_metadata(image)

Minimize metadata by keeping only the artist and copyright (if available).

minimize_metadata!(image)

Minimize metadata by keeping only the artist and copyright (if available).

remove_metadata(image, fields \\ [])

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

remove_metadata!(image, fields \\ [])

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

xmp(image)

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

Nx & Evision

from_evision(evision_image)

Converts to an Image image from an Evision.Mat image.

from_nx(tensor)

Converts an Nx tensor into an image.

to_evision(image, convert_to_bgr \\ true)

Converts an Image image to an Evision image.

to_nx(image, options \\ [])

Converts an image into an Nx tensor.

to_nx!(image, options \\ [])

Converts an image into an Nx tensor.

Preview

p(image)

Outputs an inline preview of an image to an iTerm2 terminal.

preview(image)

Outputs an inline preview of an image to an iTerm2 terminal.

Guards

is_box(left, top, width, height)

Guards whether the coordinates can be reasonably interpreted as a bounding box.

is_percent(value)

Guards whether a value is a percentage as representeed by a float between -1.0 and 1.0.

is_pixel(value)

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

is_positive_percent(value)

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(top_left, top_right, bottom_right, bottom_left)

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),

is_size(size)

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

libvips Configuration

get_concurrency()

Returns the number of operating system threads available for use by libvips.

put_concurrency(concurrency)

Sets the number of available threads for use by libvips.

vips_version()

Returns the version of libvips in operation.

Functions

average(image)

Returns the average color of an image.

average!(image)

Returns the average color of an image or raises and exception.

dhash_pixels(image, convolution, hash_size)

from_kino(map, options \\ [])

Returns an image from a Kino image input.

from_kino!(map, options \\ [])

Returns an image from a Kino image input or raises an exception.

is_image(image_type)

Guards whether the given struct is an image type either Vix.Vips.Image or Vix.Vips.MutableImage.

Link to this section Types

aspect()

@type aspect() :: :landscape | :portrait | :square

Image orientation.

composition()

@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()

@type composition_list() :: [composition(), ...]

A list of images or images with placement options used in Image.compose/2.

error_message()

@type error_message() :: term()

Error messages returned by libvips

Typically a string.

format()

@type format() :: {:u | :s | :f | :c | :bf, 8 | 16 | 32 | 64 | 128}

The data type of the image, using the same type definitions as Nx.Type.t/0.

image_data()

@type image_data() :: Path.t() | File.Stream.t() | binary()

The valid sources of image data when opening an image.

image_hash()

@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()

@type image_or_color() :: Vix.Vips.Image.t() | Image.Color.t()

Represents either in image, or a color that is used to fill a new image

kino_image()

@type kino_image() :: %{
  data: binary(),
  width: pos_integer(),
  height: pos_integer(),
  format: :rgb
}

THe structure of an image returned from Kino.Input.read/1 when the input field is a Kino.Input.image/1 type.

pixel()

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

quadrilateral()

@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()

@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 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 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 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 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()

@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()

@type x_location() :: integer() | :left | :center | :right

y_location()

@type y_location() :: integer() | :top | :middle | :bottom

Link to this section Files and streams

from_binary(binary, options \\ [])

(since 0.7.0)

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

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

returns
Returns

{:ok, image} or
{:error, reason}

from_binary!(binary, options \\ [])

(since 0.25.0)

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

image or
raises an exception.

from_svg(svg, options \\ [])

(since 0.32.0)

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

Returns an image created from an SVG string.

arguments
Arguments

svg is an SVG string.
options is a keyword list of options.

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
Returns

{:ok, image} or
{:error, reason}

from_svg!(svg, options \\ [])

(since 0.32.0)

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

svg is an SVG string.
options is a keyword list of options.

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
Returns

image or
raises an exception.

new(image)

(since 0.1.13)

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

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.

arguments
Arguments

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

new(width, height)

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

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

Create a new image of the given dimensions.

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

{:ok, image} or
{:error, reason}

notes
Notes

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

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, 255], bands: 4)

new(width, height, options)

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

new!(image)

(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
Arguments

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

new!(width, height)

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

notes
Notes

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

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)

new!(width, height, options)

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

open(path_or_stream_or_binary, options \\ [])

@spec open(
  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, .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
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.

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.

PNG options

There are no PNG-specific image loading options.

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.

returns
Returns

{:ok, image} or
{:error, message}

open!(image_path, options \\ [])

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

returns
Returns

image or
raises an exception.

stream!(image, options \\ [])

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

write(image, image_path, options \\ [])

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

Write an image to a file, a stream, an 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

: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 PNG files it is the compression amount with a default of 60. 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

: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.
: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 options

: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 images

:compression is the compression strategy to be applied. The allowable values are :hevc, :avc, :jpeg and :av1. The default is :hevc.
: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.

returns
Returns

{:ok, image} (or {:ok, binary} is the destination is :memory) or
{:error, reason}

write!(image, image_path, options \\ [])

@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() | binary() | no_return()

Write an image to a file, a stream, an enumerable 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 a binary is the destination is :memory) or
raises an exception.

Link to this section Operations

add_alpha(image, alpha_image)

(since 0.13.0)

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

Add an alpha band to an image.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
alpha_image is any single-band image that will be added as an alpha image to image

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
Returns

{:ok, image_with_added_alpha_band} or
{:error, reason}

add_alpha!(image, alpha_image)

(since 0.13.0)

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

Add an alpha band to an image.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
alpha_image is any single-band image that will be added as an alpha image to image

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

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

image_with_added_alpha_band or
raises an exception.

autolevel(image)

(since 0.23.0)

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

Scales each band of an image to fit the full dynamic range. Unlike Image.normalize/1, each band is scaled separately.

The function finds the image histogram, searches for thresholds which will select 0.3% and 0.7% of pixels in each image band, then rescales the image so that those pixel values become 0 and 255.

The scaling is performed in the :srgb color space but the image is converted back to its original color space after levelling.

arguments
Arguments

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

returns
Returns

{:ok, auto_levelled_image} or
{:error, reason}.

autolevel!(image)

(since 0.23.0)

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

Scales each band of an image to fit the full dynamic range. Unlike Image.normalize/1, each band is scaled separately. Raises an exception on error.

The function finds the image histogram, searches for thresholds which will select 0.3% and 0.7% of pixels in each image band, then rescales the image so that those pixel values become 0 and 255.

The scaling is performed in the :srgb color space but the image is converted back to its original color space after levelling.

arguments
Arguments

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

returns
Returns

auto_levelled_image or
raises an exception.

autorotate(image)

@spec autorotate(image :: Vix.Vips.Image.t()) ::
  {:ok, {Vix.Vips.Image.t(), map()}} | {: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.

autorotate!(image)

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

blur(image, options \\ [])

(since 0.13.0)

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

Applies a gaussian blur to an image.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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
Returns

{:ok, blurred_image} or
{:error reason}

blur!(image, options \\ [])

(since 0.13.0)

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

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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
Returns

blurred_image or
raises an exception.

cast(image, band_format)

(since 0.30.0)

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

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
Arguments

image is any Vix.Vips.Image.t/0.
band_format is any known band format. See Image.BandFormat.known_band_formats/0.

returns
Returns

{:ok, cast_image} or
{:error, reason}.

chroma_color(image)

(since 0.13.0)

@spec chroma_color(image :: Vix.Vips.Image.t()) :: Image.Color.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
Argument

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

returns
Returns

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

chroma_key(image, options \\ [])

(since 0.13.0)

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

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
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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!(image, options \\ [])

(since 0.13.0)

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

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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(image, options \\ [])

(since 0.13.0)

@spec chroma_mask(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ChromaKey.chroma_key_options() | map()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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.
:thresholdis 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!(image, options \\ [])

(since 0.13.0)

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

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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.
:thresholdis 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.

compose(base_image, overlay_image_or_images, options \\ [])

@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_message()}

@spec compose(
  base_image :: Vix.Vips.Image.t(),
  image_list :: composition_list(),
  options :: Image.Options.Compose.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 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 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 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}
..> ])

compose!(base_image, image_or_image_list, options \\ [])

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

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

dilate(image, pixels \\ 1)

(since 0.23.0)

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

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

Mask is used in the sense of an image on a transparent background. The results on other image types is undefined.

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

note
Note

Dilate works for any non-complex image type, with any number of bands. The input is expanded 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 therefore only approximate.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
pixels is a positive integer number of pixels to dilate. The default is 1.

returns
Returns

{:ok, dilated_mask} or
{:error, reason}

dilate!(image, pixels \\ 1)

(since 0.23.0)

@spec dilate!(image :: Vix.Vips.Image.t(), pixels :: 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 on a transparent background. The results on other image types is undefined.

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

note
Note

Edge pixels in the output image are therefore only approximate.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
pixels is a positive integer number of pixels to dilate. The default is 1.

returns
Returns

dilated_mask or
raises an exception

embed!(image, width, height, options \\ [])

(since 0.27.0)

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

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

See Image.embed/4.

returns
Returns

embedded_image or
raises an exception.

erode(image, pixels \\ 1)

(since 0.23.0)

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

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

Mask is used in the sense of an image on a transparent background. The results on other image types is undefined.

note
Note

Erode works for any non-complex image type, with any number of bands. The input is expanded 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 therefore only approximate.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
pixels is a positive integer number of pixels to dilate. The default is 1.

returns
Returns

{:ok, eroded_mask} or
{:error, reason}

erode!(image, pixels \\ 1)

(since 0.23.0)

@spec erode!(image :: Vix.Vips.Image.t(), pixels :: 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 on a transparent background. The results on other image types is undefined.

note
Note

Edge pixels in the output image are therefore only approximate.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
pixels is a positive integer number of pixels to dilate. The default is 1.

returns
Returns

eroded_mask or
raises an exception

feather(image, options \\ [])

(since 0.13.0)

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

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
Arguments

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

{:ok, blurred_mask_image} or
{:error, reason}

feather!(image, options \\ [])

(since 0.13.0)

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

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

{:ok, blurred_mask_image} or
{:error, reason}

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)

fft!(image)

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

flatten(image)

(since 0.23.0)

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

Flatten an alpha layer out of an image.

arguments
Arguments

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

returns
Returns

{:ok, flattened_image} or
{:error, reason}

flatten!(image)

(since 0.23.0)

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

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

arguments
Arguments

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

returns
Returns

flattened_image or
raises an exception

flip(image, direction)

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

flip!(image, direction)

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

get_pixel(image, x, y)

(since 0.3.0)

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

get_pixel!(image, x, y)

(since 0.26.0)

@spec get_pixel!(Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer()) ::
  Image.Color.rgb_color() | 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
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

pixel_value or
raises an exception

hamming_distance(image_1, image_2)

(since 0.6.0)

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

histogram(image)

(since 0.3.0)

@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 the same numbers of bands as the source image.

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.

if_then_else(condition_image, if_image_or_color, else_image_or_color, options \\ [])

(since 0.13.0)

@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_message()}

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
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 Image.Color.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 Image.Color.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
Options

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

returns
Returns

{:ok, image} or
{:error, reason}.

notes
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!(condition_image, if_color, else_image_or_color)

(since 0.30.0)

@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
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 Image.Color.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 Image.Color.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
Returns

image or
raises an exception.

notes
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`

map(image, transformation_matrix, options \\ [])

(since 0.28.0)

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

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
Arguments

image is any t:Vimage.t/0
transform_matrix is a matrix returned by Image.transform_matrix/3.

returns
Returns

{:ok, mapped_image} or
{:error, reason}

mutate(image, fun)

(since 0.7.0)

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

Mutations, like those functions in the Image.Draw, module are operations on a copy of the base image and operations are serialized through a genserver 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 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 Vix.Vips.Image.t/0 or a Vix.Vips.MutableImage.t/0 as the image parameter.

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

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

arguments
Arguments

image is any Vix.Vips.Image.t/0.
fun is any 1-arity function that receives a Vix.Vips.MutableImage.t/0 parameter.

returns
Returns

{:ok, mutated_image} or
{:error, reason}

example
Example

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

  Image.mutate image, fn mutable_image ->
    mutable_image
    |> Image.Draw.rect!(0, 0, 10, 10, color: :red)
    |> Image.Draw.rect!(10, 10, 20, 20, color: :green)
  end

normalize(image)

(since 0.23.0)

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

Normalize an image by expanding the luminance of an image to cover the full dynamic range.

arguments
Arguments

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

returns
Returns

{:ok, normalized_image} or
{:error, reason}.

normalize!(image)

(since 0.23.0)

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

Normalize an image by expanding the luminance of an image to cover the full dynamic range. Raises an exception on error.

arguments
Arguments

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

returns
Returns

normalized_image or
raises an exception.

pixelate(image, scale \\ 0.05)

(since 0.14.0)

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

Pixelates an image.

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

arguments
Arguments

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

{:ok, pixelated_image} or
{:error, reason}

pixelate!(image, scale \\ 0.05)

(since 0.14.0)

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

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

{:ok, pixelated_image} or
{:error, reason}

ripple(image)

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

ripple!(image)

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

rotate(image, angle, options \\ [])

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

rotate!(image, angle, options \\ [])

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

skew_angle(image)

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

split_alpha(image)

(since 0.13.0)

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

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

returns
Returns

{image_bands_without_alpha, alpha_band} or
{:image_bands, nil} if there is not alpha band detected.

straighten_perspective(image, source, options \\ [])

(since 0.28.0)

@spec straighten_perspective(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: {:ok, quadrilateral(), Vix.Vips.Image.t()} | {:error, error_message()}

Performs a warp perspective transformation on an image to straighten its perspective.

Requires Nx to be configured as a dependency.

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

{:ok, destination, straightened_image} or
{:error, reason}

notes
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!(image, source, options \\ [])

(since 0.28.0)

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

straightened_image or
{:error, reason}

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

to_polar_coordinates(image)

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

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}

to_polar_coordinates!(image)

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

to_rectangular_coordinates(image)

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

to_rectangular_coordinates!(image)

@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_rectangular_coordinates or
raises an exception.

transform_matrix(image, source, destination)

(since 0.28.0)

@spec transform_matrix(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  destination :: quadrilateral()
) :: {:ok, transform_matrix :: Vix.Vips.Image.t()} | {:error, error_message()}

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

{:ok, transform_matrix} or
{:error, reason}.

warp_perspective(image, source, destination, options \\ [])

(since 0.28.0)

@spec warp_perspective(
  Vix.Vips.Image.t(),
  source :: quadrilateral(),
  destination :: quadrilateral(),
  Image.Options.WarpPerspective.t()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Performs a warp perspective transformation on an image.

Requires Nx to be configured as a dependency.

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

The image is flattened before warping and therefore any alpha band will be multiplied into to the image data and removed.

returns
Returns

{:ok, warped_image} or
{:error, reason}

warp_perspective!(image, from, to, options \\ [])

(since 0.28.0)

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

warped_image or
raises an exception.

notes
Notes

The image is flattened before warping and therefore any alpha band will be multiplied into to the image data and removed.

with_colorspace(image, colorspace, fun)

(since 0.29.0)

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

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
Arguments

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

{:ok, image} or
{:error, reason}.

without_alpha_band(image, fun)

(since 0.29.0)

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

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

arguments
Arguments

image is any Vix.Vips.Image.t/0.
fun is any 1-arity function that is required to return {:ok, image} or {:error, reason}.

returns
Returns

{:ok, image} or
{:error, reason}.

Link to this section Resize

embed(image, width, height, options \\ [])

(since 0.27.0)

@spec embed(
  Vix.Vips.Image.t(),
  non_neg_integer(),
  non_neg_integer(),
  Image.Options.Embed.embed_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

arguments
Arguments

image is any 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
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 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 Image.Color.color_map/0 and Image.Color.rgb_color/1.
: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 set in options.

returns
Returns

{:ok, embedded_image} or
{:error, reason}

resize(image, scale, options \\ [])

(since 0.13.0)

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

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
Arguments

image is any Vix.Vips.Image.t/0.
scale is a float scale factor.
options is a keyword list of options.

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

returns
Returns

{:ok, resized_image} or
raises an exception

resize!(image, scale, options \\ [])

(since 0.14.0)

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

image is any Vix.Vips.Image.t/0.
scale is a float scale factor.
options is a keyword list of options.

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

returns
Returns

resized_image or
raises an exception

thumbnail(image_or_path, length, options \\ [])

@spec thumbnail(
  Vix.Vips.Image.t(),
  length :: pos_integer(),
  options :: Image.Options.Thumbnail.thumbnail_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

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

Thumbnail 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.
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
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.
: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 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 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
Returns

{:ok, thumbnailed_image} or
{:error, reason}

thumbnail!(image_or_path, length, options \\ [])

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

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

image or
raises an exception.

trim(image, options \\ [])

(since 0.23.0)

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

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

Any alpha is flattened out, then 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
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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.
: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
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!(image, options \\ [])

(since 0.23.0)

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

Any alpha is flattened out, then 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
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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.
: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
Returns

cropped_image which is the image cropped to the bounding box of the non-background area or
raises an exception.

Link to this section Crop

center_crop(image, width, height)

(since 0.27.0)

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

Crops the center from an image.

arguments
Arguments

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

{:ok, cropped_image} or
{:error, reason}.

center_crop!(image, crop_width, crop_height)

(since 0.27.0)

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

Crops the center from an image.

arguments
Arguments

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

cropped_image or
raises an exception.

crop(image, quadrilateral)

(since 0.28.0)

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

Crop an image.

arguments
Arguments

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

{:ok, cropped_image} or
{:error, reason}

note
Note

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

crop(image, left, top, width, height)

@spec crop(
  Vix.Vips.Image.t(),
  x_location(),
  y_location(),
  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 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.

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

returns
Returns

{:ok, cropped_image} or
{:error, reason}

crop!(image, quadrilateral)

(since 0.28.0)

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

Crop an image or raises an exception.

arguments
Arguments

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

cropped_image or
raises an exception.

note
Note

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

crop!(image, left, top, width, height)

@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

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
Returns

cropped_image or
raises an exception.

Link to this section Transforms

avatar(image, options \\ [])

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

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

The image is resized and all metadata is removed from the image. Depending on the :shape option the image may be center cropped to a square and may have a circular mask applied.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options. The default is [shape: :cirlce, crop: :none].

options
Options

:size is the diameter (in the case of shape: :circle or width/height in the case of shape: :square of the resulting image after resizing. The default value is 180.
:shape defines shape of the avator which can be either :circle (the default) or :square. In both cases the image is first center cropped to a square shape. Then if the format is :circle a circular image mask is applied.
For other options see Image.thumbnail/3.

returns
Returns

{:ok, avatar_image} or
{:error, reason}

avatar!(image, options \\ [])

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

Make a circular 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. Depending on the :shape option the image may be center cropped to a square and may have a circular mask applied.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options. The default is [shape: :cirlce, crop: :none].

options
Options

:size is the diameter (in the case of shape: :circle or width/height in the case of shape: :square of the resulting image after resizing. The default value is 180.
:shape defines shape of the avator which can be either :circle (the default) or :square. In both cases the image is first center cropped to a square shape. Then if the format is :circle a circular image mask is applied.
For other options see Image.thumbnail/3.

returns
Returns

avatar_image or
raises an exception.

linear_gradient(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])

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

linear_gradient!(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])

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

meme(image, headline, options \\ [])

(since 0.13.0)

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

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
Arguments

image is any 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
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!(image, headline, options \\ [])

(since 0.13.0)

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

image is any 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
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(width, height, options \\ [])

(since 0.6.0)

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

rounded(image, options \\ [])

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

Link to this section Split & Join

alpha_band(image)

@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. The integer is a 0-based offset and can therefore be directly used to access the band. For example image[alpha_band(image)].

split_bands(image)

(since 0.13.0)

@spec split_bands(Vix.Vips.Image.t()) :: [Vix.Vips.Image.t()]

Split the image into a list of its component bands.

arguments
Arguments

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

returns
Returns

a list of single band images extracted from image.

Link to this section Color

replace_color(image, options \\ [])

(since 0.30.0)

@spec replace_color(
  Vix.Vips.Image.t(),
  Image.Options.ChromaKey.chroma_key_options()
  | [{:replace_with, Image.Color.t()}]
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Replace one color in an image with another.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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

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.
:thresholdis 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
Returns

{:ok, image} or
{:error, reason}.

replace_color!(image, options \\ [])

(since 0.30.0)

@spec replace_color!(
  Vix.Vips.Image.t(),
  Image.Options.ChromaKey.chroma_key_options()
  | [{:replace_with, Image.Color.t()}]
) :: Vix.Vips.Image.t() | no_return()

Replace one color in an image with another or raises an exception.

arguments
Arguments

image is any Vix.Vips.Image.t/0.
options is a keyword list of options.

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

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.
:thresholdis 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
Returns

image or
raises an exception.

to_colorspace(image, colorspace)

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

to_colorspace!(image, colorspace)

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

Link to this section Information

aspect(image, options \\ [])

Returns the aspect 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("test/support/images/puppy.webp"))
iex> Image.aspect(puppy, square_ratio: 0.05)
:landscape

bands(image)

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

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

returns
Returns

An integer number of bands in the image.

dominant_color(image, options \\ [])

(since 0.3.0)

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

filename(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.

has_alpha?(image)

@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

height(image)

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

interpretation(image)

(since 0.9.0)

@spec interpretation(image :: Vix.Vips.Image.t()) :: Image.Interpretation.t()

Returns the image interpretation.

The interpretation is how Image understands the image date. For example, :srgb or :cmyk or :bw.

For most common web applications, the interpretation will be :srgb.

arguments
Arguments

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

returns
Returns

The image interpretation as an atom.

notes
Notes

See also Image.Interpretation.known_interpretations/0

shape(image)

(since 0.9.0)

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

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

returns
Returns

The image shape as a tuple of {width, height, bands}.

type(image)

(since 0.9.0)

@spec type(image :: Vix.Vips.Image.t()) :: Image.BandFormat.t()

Returns the data type of the image pixels.

arguments
Arguments

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

returns
Returns

The image type as a tuple in the same format as Nx.Type.t/0. For example {:u, 8} for a common :srgb image.

width(image)

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

Link to this section Masks

circle(image, options \\ [])

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

circle!(image, options \\ [])

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

convert_to_mask(image)

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

convert_to_mask!(image)

@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

rounded!(image, options \\ [])

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

Link to this section Metadata

dhash(image, hash_size \\ 8)

(since 0.6.0)

Returns a 64-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. This is 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, 64-bit binary} or
{:error, reason}

exif(image)

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

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.
{:error, reason}

minimize_metadata(image)

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

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 that the minimized metadata is only materialized when the minimized image is saved to a file.

arguments
Arguments

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

returns
Returns

{:ok, image_with_minimal_metadata} or
{:error, reason}

minimize_metadata!(image)

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

arguments
Arguments

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

returns
Returns

image_with_minimal_metadata or
raises an exception.

remove_metadata(image, fields \\ [])

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

remove_metadata!(image, fields \\ [])

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

xmp(image)

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

Link to this section Nx & Evision

from_evision(evision_image)

(since 0.9.0)

Converts to an Image image from an Evision.Mat image.

arguments
Arguments

evision_image is any Evision.Mat image.

returns
Returns

{:ok, image}

notes
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(tensor)

(since 0.5.0)

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

to_evision(image, convert_to_bgr \\ true)

(since 0.9.0)

Converts an Image image to an Evision image.

Note that only images with 3 bands can be transferred to eVision.

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

{:ok, evision_image}

notes
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_nx(image, options \\ [])

(since 0.5.0)

@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
options is a keyword list of options

options
Options

:shape determines how the tensor is shaped. The valid values are:
- :whb or :whc which leaves the tensor unchanged with the underlying data in width, height, bands shape. This is the default action.
- :hwc or :hwb which reshapes the tensor to height, width, channels which is commonly used for machine learning models.

returns
Returns

{:ok, tensor) where tensor is an Nx.Tensor.t/0 tensor suitable for use in the Nx library or
{:error, reason}.

example
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: [:width, :height, :bands], backend: Nx.BinaryBackend)}

to_nx!(image, options \\ [])

(since 0.27.0)

@spec to_nx!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Nx.Tensor.t() | no_return()

Converts an image into an Nx tensor.

arguments
Arguments

image is any t:Vimage.t/0
options is a keyword list of options

options
Options

:shape determines how the tensor is shaped. The valid values are:
- :whb or :whc which leaves the tensor unchanged with the underlying data in width, height, bands shape. This is the default action.
- :hwc or :hwb which reshapes the tensor to height, width, channels which is commonly used for machine learning models.

returns
Returns

tensor where tensor is an Nx.Tensor.t/0 tensor suitable for use in the Nx library or
raises an exception.

example
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: [:width, :height, :bands], backend: Nx.BinaryBackend)

Link to this section Preview

p(image)

(since 0.13.0)

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

Outputs an inline preview of an image to an iTerm2 terminal.

Only iTerm2 terminal windows are supported.

Delegates to Image.preview/1

arguments
Arguments

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

notes
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(image)

(since 0.13.0)

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

Outputs an inline preview of an image to an iTerm2 terminal.

Only iTerm2 terminal windows are supported.

arguments
Arguments

image is any Vix.Vips.Image.t/0 or a tuple of the form {:ok, image}.

returns
Returns

The image parameter as provided with the side effect of emitting an image preview on an iTerm terminal.

notes
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])

Link to this section Guards

is_box(left, top, width, height)

(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_percent(value)

(macro)

Guards whether a value is a percentage as representeed by a float between -1.0 and 1.0.

is_pixel(value)

(macro)

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

is_positive_percent(value)

(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(top_left, top_right, bottom_right, bottom_left)

(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(size)

(macro)

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

Link to this section libvips Configuration

get_concurrency()

@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(concurrency)

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

vips_version()

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

Returns the version of libvips in operation.

Link to this section Functions

average(image)

(since 0.27.0)

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

Returns the average color of an image.

The average is calculated for each band of an image and then combined.

arguments
Arguments

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

returns
Returns

A list of average pixel values which can be interpreted as the average color of the image.

example
Example

  iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
  ...> |> Image.average()
  [66, 86, 106]

average!(image)

(since 0.27.0)

@spec average!(Vix.Vips.Image.t()) :: Image.Color.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
Arguments

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

returns
Returns

A list of average pixel values which can be interpreted as the average color of the image.

example
Example

  iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
  ...> |> Image.average!()
  [66, 86, 106]

dhash_pixels(image, convolution, hash_size)

from_kino(map, options \\ [])

(since 0.27.0)

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

Returns an image from a Kino image input.

arguments
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:
- :data which contains the raw binary of the image
- :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
options is a keyword list of options

options
Options

:bands indicates the integer number of bands (channels) in the image. The default is 3.

notes
Notes

The image is assumed to contain pixel data that is in unsigned 8-bit format which is common for most web-oriented images.

returns
Returns

{:ok, image} or
{:error, reason}

from_kino!(map, options \\ [])

(since 0.27.0)

@spec from_kino!(image :: kino_image(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()

Returns an image from a Kino image input or raises an exception.

arguments
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:
- :data which contains the raw binary of the image
- :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
options is a keyword list of options

options
Options

:bands indicates the integer number of bands (channels) in the image. The default is 3.

notes
Notes

The image is assumed to contain pixel data that is in unsigned 8-bit format which is common for most web-oriented images.

returns
Returns

{:ok, image} or
raises an exception.

is_image(image_type)

(macro)

Guards whether the given struct is an image type either Vix.Vips.Image or Vix.Vips.MutableImage.

Settings View Source Image (image v0.33.0)

Link to this section Summary

Link to this section Types

aspect()

composition()

composition_list()

error_message()

format()

image_data()

image_hash()

image_or_color()

kino_image()

pixel()

quadrilateral()

render_intent()

perceptual-intent Perceptual Intent

relative-intent Relative Intent

saturation-intent Saturation Intent

absolute-intent Absolute Intent

transparency()

x_location()

y_location()

Link to this section Files and streams

from_binary(binary, options \\ [])

arguments Arguments

returns Returns

from_binary!(binary, options \\ [])

arguments Arguments

returns Returns

from_svg(svg, options \\ [])

arguments Arguments

options Options

returns Returns

from_svg!(svg, options \\ [])

arguments Arguments

options Options

returns Returns

new(image)

arguments Arguments

options Options

returns Returns

new(width, height)

arguments Arguments

options Options

returns Returns

notes Notes

examples Examples

new(width, height, options)

new!(image)

arguments Arguments

options Options

returns Returns

new!(width, height)

arguments Arguments

options Options

returns Returns

notes Notes

examples Examples

new!(width, height, options)

open(path_or_stream_or_binary, options \\ [])

arguments Arguments

options Options

All image types

JPEG image options

WEBP options

TIFF options

PNG options

GIF options

returns Returns

open!(image_path, options \\ [])

arguments Arguments

returns Returns

stream!(image, options \\ [])

arguments Arguments

options Options

returns Returns

example Example

write(image, image_path, options \\ [])

arguments Arguments

options Options

View Source Image (image v0.33.0)

perceptual-intent
Perceptual Intent

relative-intent
Relative Intent

saturation-intent
Saturation Intent

absolute-intent
Absolute Intent

arguments
Arguments

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

options
Options

returns
Returns

notes
Notes

examples
Examples

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

options
Options

returns
Returns

notes
Notes

examples
Examples

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

options
Options

returns
Returns

example
Example

arguments
Arguments

options
Options

streaming-images-and-memory-images
Streaming images and :memory images

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

note
Note

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

returns
Returns

arguments
Arguments

returns
Returns

flags
Flags

arguments
Arguments

returns
Returns

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

options
Options

returns
Returns

arguments
Arguments

returns
Returns

argument
Argument

returns
Returns

arguments
Arguments

options
Options

arguments
Arguments

options
Options