View Source Image (image v0.43.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.

Summary

Files and streams

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

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

Returns an image created from an SVG string.

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

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

Create a new image of the given dimensions.

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

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

Opens an image file or stream for image processing.

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

Convert an image into an enumerable stream.

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

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

Operations

Add an alpha band to an image.

Add an alpha band to an image.

Applies a tone curve to an image.

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

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

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

Applies a gaussian blur to an image.

Applies a gaussian blur to an image.

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

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

Casts an image from one band format to another.

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

Automatically determine the chroma key color of an image.

Chroma key an image.

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

Return a chroma-based masked image.

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

Compare two images using a particular comparison metric returning a score indicating the similarity of the images.

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

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

Apply a percentage adjustment to an image's contrast.

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

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

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

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

Equalizes the histogram of an imaage.

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

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

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

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

Feather (blur the edges) of an image mask.

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

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

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

Flatten an alpha layer out of an image.

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

Flip an image horizontally or vertically.

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

Returns the pixel value at the given image location.

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

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

Returns the histogram for an image.

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

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.

Apply a local contrast adjustment to an image.

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

Applies a transformation matrix to an image.

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

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

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

Mutate an image with through the given function.

Pixelates an image.

Pixelates an image or raise an exception.

Reduces noise in an image by applying a median filter.

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

Adds a concentric ripple effect to an image.

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

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

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

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

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

Sharpens an image.

Sharpens an image or raises an exception.

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

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

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

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

Convert image to polar coordinates.

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

Convert image to rectangular coordinates.

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

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

Performs a warp perspective transformation on an image.

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

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

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.

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

Resize

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

Resize an image or raise an exception.

Thumbnail an image to fit or fill a bounding box.

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

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

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

Crop

Crops the center from an image.

Crops the center from an image.

Crop an image or raises an exception.

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

Transforms

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

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

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

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

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

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

Returns a radial gradient as an image.

Returns a radial gradient as an image.

Apply rounded corners to an image.

Apply squircle mask to an image.

Split & Join

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

Split the image into a list of its component bands.

Color

Replace one color in an image with another.

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

Converts an image to the given colorspace.

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

Information

Returns the aspect of an image.

Returns the band format of an image.

Return the number of bands in an image.

Returns the image colorspace.

Returns the dominant sRGB color of an image.

Returns the dominant sRGB color of an image or raises an exception.

Returns the filename for an image.

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

Returns the height of an image.

Returns the number of pages in an image.

Returns the range of permissable values as a tuple for each pixel in an image.

Returns the shape of an image.

Returns the width of an image.

Masks

Apply a circular mask to an image.

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

Convert an image alpha band into a mask.

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

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

Apply a squircle mask to an image. Returns an image or raises an exception.

Nx & Evision

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

Converts an Nx tensor into an image.

Converts an image into an Nx tensor.

Converts an image into an Nx tensor.

Preview

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

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

Guards

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

Guards whether a value is a multiplier as representeed by a float greater than 0.0.

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

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

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.

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

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

libvips Configuration

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

Sets the number of available threads for use by libvips.

Returns the version of libvips in operation.

Types

Image orientation.

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

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

Error messages returned by libvips

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

The valid sources of image data when opening an image.

A 512 bit binary hash of an image.

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

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

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

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.

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

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

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.

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.

Functions

Returns the average color of an image.

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

Returns an image from a Kino image input.

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

Inverts an image.

Inverts an image or raises an exception.

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

Join a list of images into a single image.

Join a list of images into a single image or raises an exception.

Files and streams

Link to this function

from_binary(binary, options \\ [])

View Source (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

  • 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

  • {:ok, image} or

  • {:error, reason}

Link to this function

from_binary!(binary, options \\ [])

View Source (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

  • binary is a binary representation of a formatted image

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

Returns

  • image or

  • raises an exception.

Link to this function

from_svg(svg, options \\ [])

View Source (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

  • svg is an SVG string.

  • options is a keyword list of options.

Options

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

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

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

Returns

  • {:ok, image} or

  • {:error, reason}

Link to this function

from_svg!(svg, options \\ [])

View Source (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

  • svg is an SVG string.

  • options is a keyword list of options.

Options

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

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

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

Returns

  • image or

  • raises an exception.

Link to this function

new(image)

View Source (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 and a color of :black.

Arguments

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

Returns

  • {:ok, image} or

  • {:error, reason}

@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

Either width and height OR image should be provided.

  • width is the image width as an integer.

  • height is the image height as an integer.

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

  • options is a keyword list of options.

Options

  • :color defines the color of the image. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The default is 0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. See 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

  • {:ok, image} or

  • {:error, reason}

Notes

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

Examples

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

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

new(width, height, options)

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

new!(image)

View Source (since 0.1.13)

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

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

Arguments

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

  • options is a keyword list of options.

Options

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

  • :color defines the color of the image. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The default is 0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. See 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

  • {:ok, image} or

  • {:error, reason}

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

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

Arguments

Either width and height OR image should be provided.

  • width is the image width as an integer.

  • height is the image height as an integer.

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

  • options is a keyword list of options.

Options

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

  • :color defines the color of the image. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The default is 0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. See 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

  • {:ok, image} or

  • {:error, reason}

Notes

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

Examples

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

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

new!(width, height, options)

View Source
@spec new!(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.New.t()
) ::
  Vix.Vips.Image.t() | no_return()
Link to this function

open(path_or_stream_or_binary, options \\ [])

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

  • 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

The available options depend upon the image type.

All image types

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

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

JPEG image options

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

WEBP options

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

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

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

TIFF options

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

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

GIF options

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

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

PNG options

  • There are no PNG-specific image loading options.

Returns

  • {:ok, image} or

  • {:error, message}

Link to this function

open!(path_or_stream_or_binary, options \\ [])

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

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

Arguments

  • image_path_or_stream_or_binary is the file system path to an image file or a 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

The available options depend upon the image type.

All image types

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

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

JPEG image options

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

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

WEBP options

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

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

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

TIFF options

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

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

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

GIF options

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

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

PNG options

  • There are no PNG-specific image loading options.

Returns

  • image or

  • raises an exception.

Link to this function

stream!(image, options \\ [])

View Source

Convert an image into an enumerable stream.

Arguments

Options

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

For additional options see Image.write/3.

Returns

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

S3 and Buffer Size

You may get an error from S3 if you do not specify a buffer size.

EntityTooSmall: Your proposed upload is smaller than the minimum allowed object size.

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

Example

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

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

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

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

  • 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

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

All image types

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

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

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

Streaming images and :memory images

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

JPEG images

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

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

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

PNG images

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

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

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

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

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

WEBP images

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

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

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

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

Merging image type options

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

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

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

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

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

Returns

  • {:ok, image} (or {:ok, binary} if the destination is :memory) or

  • {:error, reason}

Link to this function

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

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

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

Arguments

Returns

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

  • raises an exception.

Operations

Link to this function

add_alpha(image, alpha_image)

View Source (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

  • 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

OR

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

Returns

  • {:ok, image_with_added_alpha_band} or

  • {:error, reason}

Link to this function

add_alpha!(image, alpha_image)

View Source (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

  • 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

OR

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

Note

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

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

Returns

  • image_with_added_alpha_band or

  • raises an exception.

Link to this function

apply_tone_curve(image, options \\ [])

View Source (since 0.35.0)
@spec apply_tone_curve(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ToneCurve.tone_curve_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Applies a tone curve to an image.

A tone curve is typically used to affect overall image contrast. It is a function to adjust brightness and contrast by controlling the input-output density curve for each band of an image.

Arguments

Options

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

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

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

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

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

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

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

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

Returns

  • {:ok, tone_mapped_image} or

  • {:error, reason}.

Link to this function

apply_tone_curve!(image, options \\ [])

View Source (since 0.35.0)
@spec apply_tone_curve!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.ToneCurve.tone_curve_options()
) :: Vix.Vips.Image.t() | no_return()

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

A tone curve is typically used to affect overall image contrast. It is a function to adjust brightness and contrast by controlling the input-output density curve for each band of an image.

Arguments

Options

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

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

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

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

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

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

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

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

Returns

  • tone_mapped_image or

  • raises an exception.

@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

Returns

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

  • {:error, reason}

Flags

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

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

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

@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

Returns

  • auto_rotated_image or

  • raises an exception.

Link to this function

blur(image, options \\ [])

View Source (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

Options

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

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

Returns

  • {:ok, blurred_image} or

  • {:error reason}

Link to this function

blur!(image, options \\ [])

View Source (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

Options

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

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

Returns

  • blurred_image or

  • raises an exception.

Link to this function

brightness(image, brightness)

View Source (since 0.34.0)
@spec brightness(image :: Vix.Vips.Image.t(), brightness :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

The image is converted to the lch color space, multiplies the luminance band by the provided float percentage and converts the image back to its original color space.

Arguments

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

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

Returns

  • {:ok, adjusted_image} or

  • {:error, reason}.

Link to this function

brightness!(image, brightness)

View Source (since 0.34.0)
@spec brightness!(image :: Vix.Vips.Image.t(), brightness :: float()) ::
  Vix.Vips.Image.t() | no_return()

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

The image is converted to the lch color space, multiplies the luminance band by the provided float percentage and converts the image back to its original color space.

Arguments

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

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

Returns

  • adjusted_image or

  • raises an exception.

Link to this function

cast(image, band_format)

View Source (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

Returns

  • {:ok, cast_image} or

  • {:error, reason}.

Link to this function

cast!(image, band_format)

View Source (since 0.42.0)

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

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

Arguments

Returns

  • cast_image or

  • raises an exception.

Link to this function

chroma_color(image)

View Source (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

Returns

  • An RGB color as a three-element list of integers.
Link to this function

chroma_key(image, options \\ [])

View Source (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

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.

Link to this function

chroma_key!(image, options \\ [])

View Source (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

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.

Link to this function

chroma_mask(image, options \\ [])

View Source (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

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.

Link to this function

chroma_mask!(image, options \\ [])

View Source (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

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.

Link to this function

compare(image_1, image_2, options \\ [])

View Source (since 0.34.0)
@spec compare(Vix.Vips.Image.t(), Vix.Vips.Image.t(), Keyword.t()) ::
  {:ok, number(), Vix.Vips.Image.t()} | {:error, error_message()}

Compare two images using a particular comparison metric returning a score indicating the similarity of the images.

Arguments

Options

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

    • :ae which returns the absolute nuber of pixels that are different between the two images. The returned value is conformed to the range of the underlying image format. Therefore the returned value is between 0.0 (images appear to be the same) and 1.0 (meaning the images appear completely different).

    • :rmse is the root mean square error. The returned value is conformed to the range of the underlying image format. Therefore the returned value is between 0.0 (images appear to be the same) and 1.0 (meaning the images appear completely different),

    • :mse which is the mean squared error (default). The returned value is a float indicating how similar the images are. A value of 0.0 means the images are the same. The number itself it simply a measure of the error difference between images. A larger number means the two images are less similar but the number itself cannot be interpreted as a percentage value.

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

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

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

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

Notes

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

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

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

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

Returns

  • {:ok, comparison_score} or

  • {:error, reason}

Link to this function

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

View Source
@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, or an image and a list of images compositions, to form a new image.

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

  • :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) which, if zero or positive, from the left of the base_image. If negative is is the offset from the right of the base_image. where the overlay_image will be placed. It may also be one of the keywords :left, :right or :center. The default is :center.

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

Composition list options

When overlay_image is an image_list, each entry in the list is either a 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

  • {:ok, composed_image} or

  • {:error, reason}

Examples

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

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

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

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

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

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

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) which, if zero or positive, from the left of the base_image. If negative is is the offset from the right of the base_image. where the overlay_image will be placed. It may also be one of the keywords :left, :right or :center. The default is :center.

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

Composition list options

When overlay_image is an image_list, each entry in the list is either a 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

  • composed_image or

  • raises an exception

Examples

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

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

contrast(image, contrast)

View Source (since 0.35.0)
@spec contrast(image :: Vix.Vips.Image.t(), contrast :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Apply a percentage adjustment to an image's contrast.

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

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

Arguments

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

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

Returns

  • {:ok, adjusted_image} or

  • {:error, reason}.

Link to this function

contrast!(image, contrast)

View Source (since 0.35.0)
@spec contrast!(image :: Vix.Vips.Image.t(), contrast :: float()) ::
  Vix.Vips.Image.t() | no_return()

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

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

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

Arguments

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

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

Returns

  • adjusted_image or

  • raises an exception.

Link to this function

dilate(image, radius \\ 1)

View Source (since 0.23.0)
@spec dilate(image :: Vix.Vips.Image.t(), radius :: 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, potentially wuth an alpha band. The results on other image types is undefined.

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

Arguments

  • image is any non-complex Vix.Vips.Image.t/0.

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

Returns

  • {:ok, dilated_mask} or

  • {:error, reason}

Notes

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

  • Edge pixels in the output image are only approximate.

  • The dilation is implemented as a rank filter.

Link to this function

dilate!(image, radius \\ 1)

View Source (since 0.23.0)
@spec dilate!(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()

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

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

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

Arguments

  • image is any non-complex Vix.Vips.Image.t/0.

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

Returns

  • dilated_mask or

  • raises an exception.

Notes

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

  • Edge pixels in the output image are only approximate.

  • The dilation is implemented as a rank filter.

Link to this function

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

View Source (since 0.27.0)

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

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

See Image.embed/4.

Returns

  • embedded_image or

  • raises an exception.

Link to this function

equalize(image, bands \\ :all)

View Source (since 0.35.0)
@spec equalize(
  image :: Vix.Vips.Image.t(),
  bands :: Image.Options.Equalize.equalize_option()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Equalizes the histogram of an imaage.

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

Arguments

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

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

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

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

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

Returns

  • {:ok, adjusted_image} or

  • {:error, reason}.

Link to this function

equalize!(image, bands \\ :all)

View Source (since 0.35.0)
@spec equalize!(
  image :: Vix.Vips.Image.t(),
  bands :: Image.Options.Equalize.equalize_option()
) ::
  Vix.Vips.Image.t() | no_return()

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

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

Arguments

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

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

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

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

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

Returns

  • adjusted_image or

  • raises an exception.

Link to this function

erode(image, radius \\ 1)

View Source (since 0.23.0)
@spec erode(image :: Vix.Vips.Image.t(), radius :: 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, potentially wuth an alpha band. The results on other image types is undefined.

Arguments

  • image is any non-complex Vix.Vips.Image.t/0.

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

Returns

  • {:ok, eroded_mask} or

  • {:error, reason}

Notes

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

  • Edge pixels in the output image are only approximate.

  • The erosion is implemented as a rank filter.

Link to this function

erode!(image, radius \\ 1)

View Source (since 0.23.0)
@spec erode!(image :: Vix.Vips.Image.t(), radius :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()

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

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

Arguments

  • image is any non-complex Vix.Vips.Image.t/0.

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

Returns

  • eroded_mask or

  • raises an exception

Notes

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

  • Edge pixels in the output image are only approximate.

  • The erosion is implemented as a rank filter.

Link to this function

extract_pages(image)

View Source (since 0.44.0)
@spec extract_pages(Vix.Vips.Image.t()) ::
  {:ok, [Vix.Vips.Image.t()]} | {:error, error_message()}

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

Not all image types support multi-page images.

Arguments

Returns

  • {:ok, list_of_images} or

  • {:error, reasom}

Notes

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

Example

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

feather(image, options \\ [])

View Source (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

  • 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

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

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

Returns

  • {:ok, blurred_mask_image} or

  • {:error, reason}

Link to this function

feather!(image, options \\ [])

View Source (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

  • 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

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

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

Returns

  • blurred_mask_image or

  • raises an exception.

@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

Returns

  • {:ok, fft_image} or

  • {:error, reason}

Example

Image.fft(image)

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

Arguments

Returns

  • fft_image or

  • raises an exception

Example

Image.fft!(image)
Link to this function

flatten(image)

View Source (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

Returns

  • {:ok, flattened_image} or

  • {:error, reason}

Link to this function

flatten!(image)

View Source (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

Returns

  • flattened_image or

  • raises an exception

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

Flip an image horizontally or vertically.

Arguments

Returns

  • {:ok, flipped_image} or

  • {:error, reason}

@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

Returns

  • flipped_image or

  • raises an exception.

Link to this function

get_pixel(image, x, y)

View Source (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

  • 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

  • {:ok, pixel_value} or

  • {:error, reason}

Link to this function

get_pixel!(image, x, y)

View Source (since 0.26.0)

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

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

Arguments

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

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

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

Returns

  • pixel_value or

  • raises an exception

Link to this function

hamming_distance(image_1, image_2, hash_size \\ 64)

View Source (since 0.6.0)
@spec hamming_distance(
  image_1 :: Vix.Vips.Image.t(),
  image_2 :: Vix.Vips.Image.t(),
  hash_size :: pos_integer()
) :: {:ok, non_neg_integer()} | {:error, error_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

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

Returns

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

  • {:error, reason}.

Link to this function

histogram(image)

View Source (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

Returns

  • {:ok, histogram_image} or

  • {:error, reason}

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.

Link to this function

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

View Source (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

  • 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

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

Returns

  • {:ok, image} or

  • {:error, reason}.

Notes

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

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

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

The output image is calculated pixel by pixel as:

(condition_image / 255) * if_image + (1 - condition_image / 255) * else_image
Link to this function

if_then_else!(condition_image, if_color, else_image_or_color)

View Source (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

  • 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

  • image or

  • raises an exception.

Notes

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

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

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

The output image is calculated pixel by pixel as:

(condition_image / 255) * if_image + (1 - condition_image / 255) *`else_image`
Link to this function

local_contrast(image, options \\ [])

View Source (since 0.35.0)
@spec local_contrast(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.LocalContrast.local_contrast_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Apply a local contrast adjustment to an image.

This function applies a Constrast Limited Adaptive histogram equalization (AHE) to improve contrast in images. It differs from ordinary histogram equalization in the respect that the adaptive method computes several histograms, each corresponding to a distinct section of the image, and uses them to redistribute the lightness values of the image.

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

Arguments

Options

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

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

Returns

  • {:ok, adjusted_image} or

  • {:error, reason}.

Link to this function

local_contrast!(image, options \\ [])

View Source (since 0.35.0)
@spec local_contrast!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.LocalContrast.local_contrast_options()
) :: Vix.Vips.Image.t() | no_return()

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

This function applies a Constrast Limited Adaptive histogram equalization (AHE) to improve contrast in images. It differs from ordinary histogram equalization in the respect that the adaptive method computes several histograms, each corresponding to a distinct section of the image, and uses them to redistribute the lightness values of the image.

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

Arguments

Options

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

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

Returns

  • adjusted_image or

  • raises an exception.

Link to this function

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

View Source (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

Returns

  • {:ok, mapped_image} or

  • {:error, reason}

Link to this function

map_join_pages(image, fun)

View Source (since 0.39.0)
@spec map_join_pages(
  Vix.Vips.Image.t(),
  (Vix.Vips.Image.t() -> {:ok, Vix.Vips.Image.t()} | {:error, error_message()})
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

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

Arguments

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

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

Returns

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

  • {:error, reason}.

Examples

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

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

# If an image isn't opened with `pages: :all` then only
# the first page of an image is loaded.
iex> image_2 = Image.open!("./test/support/images/animated.webp")
iex> Image.map_join_pages(image_2, &Image.equalize/1)
{:error, "Image does not have a page-height header. " <>
  "Perhaps the image wasn't opened with the `pages: :all` option or " <>
  "libvips wasn't built with libwebp-dev/libgif-dev configured? " <>
  "Run `vips --vips-config` from the command line to check."}
Link to this function

modulate(image, options \\ [])

View Source (since 0.35.0)
@spec modulate(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Modulate.modulate_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

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

Arguments

Options

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

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

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

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

Returns

  • {:ok, modulated_image} or

  • {:error, reason}.

Link to this function

modulate!(image, options \\ [])

View Source (since 0.35.0)
@spec modulate!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Modulate.modulate_options()
) ::
  Vix.Vips.Image.t() | no_return()

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

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

Arguments

Options

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

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

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

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

Returns

  • modulated_image or

  • raises an exception.

Link to this function

mutate(image, fun)

View Source (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

Returns

  • {:ok, mutated_image} or

  • {:error, reason}

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
Link to this function

pixelate(image, scale \\ 0.05)

View Source (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

  • 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

  • {:ok, pixelated_image} or

  • {:error, reason}

Link to this function

pixelate!(image, scale \\ 0.05)

View Source (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

  • 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

  • {:ok, pixelated_image} or

  • {:error, reason}

Link to this function

reduce_noise(image, window_size \\ 3)

View Source (since 0.35.0)
@spec reduce_noise(image :: Vix.Vips.Image.t(), window_size :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Reduces noise in an image by applying a median filter.

The implementation uses a median rank filter based on ordering the pixel values under a convolution kernel of a given window size and extracting the median value.

The result is appropriate for removing salt and pepper noise and may be useful for smoothing gaussian noise in some cases.

Arguments

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

  • window_size is the integer size of the convolution kernel use in the median rank filter. The default is 3.

Returns

  • {:ok, reduced_noise_image} or

  • {:error, reason}

Link to this function

reduce_noise!(image, window_size \\ 3)

View Source (since 0.35.0)
@spec reduce_noise!(image :: Vix.Vips.Image.t(), window_size :: pos_integer()) ::
  Vix.Vips.Image.t() | no_return()

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

The implementation uses a median rank filter based on ordering the pixel values under a convolution kernel of a given window size and extracting the median value.

The result is appropriate for removing salt and pepper noise and may be useful for smoothing gaussian noise in some cases.

Arguments

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

  • window_size is the integer size of the convolution kernel use in the median rank filter. The default is 3.

Returns

  • reduced_noise_image or

  • raises an exception.

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

Adds a concentric ripple effect to an image.

Arguments

Returns

  • {:ok, image_with_ripple} or

  • {:error, reason}

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

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

Arguments

Returns

  • image_with_ripple or

  • raises an exception.

Link to this function

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

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

  • 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

  • :idy is the vertical input displacement which defaults to 0.0

  • :idx is the horizontal input displacement which defaults to 0.0

  • :ody is the vertical output displacement which defaults to 0.0

  • :odx is the horizontal output displacement which defaults to 0.0

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

Notes

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

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

Returns

  • {:ok, rotated_image} or

  • {:error, reason}

Link to this function

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

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

Notes

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

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

Returns

  • rotated_image or

  • raises an exception.

Link to this function

saturation(image, saturation)

View Source (since 0.34.0)
@spec saturation(image :: Vix.Vips.Image.t(), saturation :: float()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

The image is converted to the lch color space, multiplies the chroma band by the provided float and converts the image back to its original color space.

Arguments

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

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

Returns

  • {:ok, adjusted_image} or

  • {:error, reason}.

Link to this function

saturation!(image, saturation)

View Source (since 0.34.0)
@spec saturation!(image :: Vix.Vips.Image.t(), saturation :: float()) ::
  Vix.Vips.Image.t() | no_return()

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

The image is converted to the lch color space, multiplies the chroma band by the provided float and converts the image back to its original color space.

Arguments

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

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

Arguments

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

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

Returns

  • adjusted_image or

  • raises an exception.

Link to this function

sharpen(image, options \\ [])

View Source (since 0.35.0)
@spec sharpen(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Sharpen.sharpen_options()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Sharpens an image.

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

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

The lookup table is formed like this:

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

Where:

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

Arguments

Options

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

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

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

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

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

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

Returns

  • {:ok, sharpened_image} or

  • {:error reason}

Output sharpening

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

Link to this function

sharpen!(image, options \\ [])

View Source (since 0.35.0)
@spec sharpen!(
  image :: Vix.Vips.Image.t(),
  options :: Image.Options.Sharpen.sharpen_options()
) ::
  Vix.Vips.Image.t() | no_return()

Sharpens an image or raises an exception.

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

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

The lookup table is formed like this:

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

Where:

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

Arguments

Options

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

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

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

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

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

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

Returns

  • sharpened_image or

  • raises an exception.

Output sharpening

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

@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

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)
Link to this function

split_alpha(image)

View Source (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

Returns

  • {image_without_alpha, alpha_band} or

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

Link to this function

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

View Source (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

  • image is any t:Vimage.t/0

  • source is a list of four 2-tuples representing the four corners of the subject-of-interest in image.

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

Options

  • :background defines the color of any generated background pixels. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. It can also be supplied as a hex string of the form #rrggbb. The default is :black. :background can also be set to :average in which case the background will be the average color of the base image. See also 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

  • {:ok, destination, straightened_image} or

  • {:error, reason}

Notes

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

  • The returned destination is a four element list of 2-tuples representing the four points to which the source points were transformed. destination can be passed as a parameter to Image.crop/2 to crop the transformed image to the subject-of-interest that was warped.

Link to this function

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

View Source (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

  • image is any t:Vimage.t/0

  • source is a list of four 2-tuples representing the four corners of the subject-of-interest in image.

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

Options

  • :background defines the color of any generated background pixels. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. It can also be supplied as a hex string of the form #rrggbb. The default is :black. :background can also be set to :average in which case the background will be the average color of the base image. See also 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

  • straightened_image or

  • {:error, reason}

Notes

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

  • The returned destination is a four element list of 2-tuples representing the four points to which the source points were transformed. destination can be passed as a parameter to Image.crop/2 to crop the transformed image to the subject-of-interest that was warped.

Link to this function

to_polar_coordinates(image)

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

Convert image to polar coordinates.

Arguments

Returns

  • {:ok, image_in_polar_coordinates} or

  • {:error, reason}

Link to this function

to_polar_coordinates!(image)

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

Returns

  • image_in_polar_coordinates or

  • raises an exception.

Link to this function

to_rectangular_coordinates(image)

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

Convert image to rectangular coordinates.

Arguments

Notes

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

Returns

  • {:ok, image_in_rectangular_coordinates} or

  • {:error, reason}

Link to this function

to_rectangular_coordinates!(image)

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

Notes

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

Returns

  • image_in_rectangular_coordinates or

  • raises an exception.

Link to this function

transform_matrix(image, source, destination)

View Source (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

  • image is any t:Vimage.t/0

  • source is a list of four 2-tuples representing the four corners of the subject-of-interest in image.

  • destination is a list of four 2-tuples representing the four corners of the destination image into which the subject-of-interest is transformed.

Returns

  • {:ok, transform_matrix} or

  • {:error, reason}.

Link to this function

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

View Source (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

  • image is any t:Vimage.t/0

  • source is a list of four 2-tuples representing the four corners of the subject-of-interest in image.

  • destination is a list of four 2-tuples representing the four corners of the destination image into which the subject-of-interest is transformed.

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

Options

  • :background defines the color of any generated background pixels. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. It can also be supplied as a hex string of the form #rrggbb. The default is :black. :background can also be set to :average in which case the background will be the average color of the base image. See also 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

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

Returns

  • {:ok, warped_image} or

  • {:error, reason}

Link to this function

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

View Source (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

  • image is any t:Vimage.t/0

  • source is a list of four 2-tuples representing the four corners of the subject-of-interest in image.

  • destination is a list of four 2-tuples representing the four corners of the destination image into which the subject-of-interest is transformed.

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

Options

  • :background defines the color of any generated background pixels. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. It can also be supplied as a hex string of the form #rrggbb. The default is :black. :background can also be set to :average in which case the background will be the average color of the base image. See also 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

  • warped_image or

  • raises an exception.

Notes

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

with_band_format(image, band_format, fun)

View Source (since 0.35.0)
@spec with_band_format(
  Vix.Vips.Image.t(),
  band_format :: Image.BandFormat.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 different band format and ensuring the band format reverted when the function returns.

Arguments

Returns

  • {:ok, image} or

  • {:error, reason}.

Example

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

with_colorspace(image, colorspace, fun)

View Source (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

Returns

  • {:ok, image} or

  • {:error, reason}.

Link to this function

without_alpha_band(image, fun)

View Source (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

  • 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

  • {:ok, image} or

  • {:error, reason}.

Resize

Link to this function

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

View Source (since 0.27.0)
@spec embed(
  image :: Vix.Vips.Image.t(),
  width :: non_neg_integer(),
  height :: non_neg_integer(),
  options :: Image.Options.Embed.embed_options()
) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

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

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

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

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

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

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

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

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

Returns

  • {:ok, embedded_image} or

  • {:error, reason}

Link to this function

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

View Source (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

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

  • scale is a float scale factor.

  • options is a keyword list of options.

Options

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

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

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

Returns

  • {:ok, resized_image} or

  • raises an exception

Link to this function

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

View Source (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

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

  • scale is a float scale factor.

  • options is a keyword list of options.

Options

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

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

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

Returns

  • resized_image or

  • raises an exception

Link to this function

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

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

  • 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

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

  • {:ok, thumbnailed_image} or

  • {:error, reason}

Link to this function

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

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

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

Arguments

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

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

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

Returns

  • image or

  • raises an exception.

Link to this function

trim(image, options \\ [])

View Source (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.

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

Options

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

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

Returns

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

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

Link to this function

trim!(image, options \\ [])

View Source (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 or raises an exception.

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

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

Arguments

Options

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

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

Returns

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

  • raises an exception.

Crop

Link to this function

center_crop(image, width, height)

View Source (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

  • 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

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

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

Returns

  • {:ok, cropped_image} or

  • {:error, reason}.

Link to this function

center_crop!(image, crop_width, crop_height)

View Source (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

  • 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

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

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

Returns

  • cropped_image or

  • raises an exception.

Link to this function

crop(image, quadrilateral)

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

Crop an image.

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

  • {:ok, cropped_image} or

  • {:error, reason}

Note

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

Link to this function

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

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

  • 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 is a float it's a fraction of the width of the image. If left is positive it is relative to the left edge of the image. If it's negative it's relative to the right edge of the image. left may also be one of :left, :center and :right indicating the crop is relative to the left, center or right of the image.

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

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

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

Notes

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

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

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

Returns

  • {:ok, cropped_image} or

  • {:error, reason}

Link to this function

crop!(image, quadrilateral)

View Source (since 0.28.0)

Crop an image or raises an exception.

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

  • cropped_image or

  • raises an exception.

Note

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

Link to this function

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

View Source

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

Arguments

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

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

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

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

Returns

  • cropped_image or

  • raises an exception.

Transforms

Link to this function

avatar(image, options \\ [])

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

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

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

Arguments

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

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

Options

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

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

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

Returns

  • {:ok, avatar_image} or

  • {:error, reason}

Link to this function

avatar!(image, options \\ [])

View Source

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

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

Arguments

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

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

Options

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

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

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

Returns

  • avatar_image or

  • raises an exception.

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

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

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

Arguments using a template image

Arguments supplying a width and height

Options

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

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

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

Returns

  • {:ok, gradient_image} or

  • {:error, reason}

Example

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

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

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

Arguments using a template image

Arguments supplying a width and height

Options

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

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

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

Returns

  • gradient_image or

  • raises an exception.

Example

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

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

View Source (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

  • 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

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

Link to this function

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

View Source (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

  • 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

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

Link to this function

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

View Source (since 0.6.0)
@spec radial_gradient(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Image.Options.RadialGradient.radial_gradient_options()
) :: {: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

  • width is the width of the gradient in pixels.

  • height is the height of the gradient in pixels.

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

Options

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

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

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

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

Returns

  • {:ok, gradient_image} or

  • {:error, reason}

Link to this function

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

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

Returns a radial gradient as an image.

This image might then be composited over another image.

Arguments

  • width is the width of the gradient in pixels.

  • height is the height of the gradient in pixels.

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

Options

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

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

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

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

Returns

  • {:ok, gradient_image} or

  • {:error, reason}

Link to this function

rounded(image, options \\ [])

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

Apply rounded corners to an image.

Arguments

Options

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

Returns

  • {:ok, rounded_corner_image} or

  • {:error, reason}

Link to this function

squircle(image, options \\ [])

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

Apply squircle mask to an image.

Arguments

Options

  • :radius is the desired squircle radius. The default is 20.

Returns

  • {:ok, squircle_image} or

  • {:error, reason}

Split & Join

@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

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)].
Link to this function

split_bands(image)

View Source (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

Returns

  • a list of single band images extracted from image.

Color

Link to this function

replace_color(image, options \\ [])

View Source (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

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

  • {:ok, image} or

  • {:error, reason}.

Link to this function

replace_color!(image, options \\ [])

View Source (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

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

  • image or

  • raises an exception.

Link to this function

to_colorspace(image, colorspace)

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

Returns

  • {;ok, image_in_new_colorspace} or

  • {:error, reason}

Example

Image.to_colorspace(image, :bw)
Link to this function

to_colorspace!(image, colorspace)

View Source

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

Returns

  • image_in_new_colorspace or

  • raises an exception

Example

Image.to_colorspace!(image, :bw)

Information

Link to this function

aspect(image, options \\ [])

View Source

Returns the aspect of an image.

Arguments

Options

  • :square_ratio indicates when an image is to be considered square. It is a floating point indicator of the ratio between the width and height below which the image is considered square. The default is 0.0 meaning that the dimensions must be exactly equal in order for the image to be considered square.

Returns

  • Either :landscape, :portrait or :square.

Example

iex> puppy = Image.open!(Path.expand("test/support/images/puppy.webp"))
iex> Image.aspect(puppy, square_ratio: 0.05)
:landscape
Link to this function

band_format(image)

View Source (since 0.35.0)
@spec band_format(image :: Vix.Vips.Image.t()) :: Image.BandFormat.t()

Returns the band format of an image.

Arguments

Returns

  • The band format of the image in Nx notation.

Examples

  iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
  iex> Image.band_format(image)
  {:u, 8}
@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

Returns

  • An integer number of bands in the image.
Link to this function

colorspace(image)

View Source (since 0.9.0)
@spec colorspace(image :: Vix.Vips.Image.t()) :: Image.Interpretation.t()

Returns the image colorspace.

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

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

Arguments

Returns

  • The image colorspace as an atom.

Notes

Example

iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
iex> Image.colorspace(image)
:srgb
Link to this function

dominant_color(image, options \\ [])

View Source (since 0.3.0)
@spec dominant_color(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Image.Color.rgb_color()} | {:error, error_message()}

Returns the dominant sRGB color of an image.

Arguments

Options

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

Returns

  • {:ok, [r, g, b]} or

  • {:error, reason}

Notes

  • image will be converted to the :srgb colorspace and the dominant color will be returned as an sRGB list.

Example

iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> Image.dominant_color(image)
{:ok, [13, 64, 115]}

iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
iex> Image.dominant_color(image)
{:ok, [90, 90, 90]}
Link to this function

dominant_color!(image, options \\ [])

View Source (since 0.43.0)
@spec dominant_color!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Image.Color.rgb_color() | no_return()

Returns the dominant sRGB color of an image or raises an exception.

Arguments

Options

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

Returns

  • {:ok, [r, g, b]} or

  • raises an exception.

Notes

  • image will be converted to the :srgb colorspace and the dominant color will be returned as an sRGB list.

Example

iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> Image.dominant_color!(image)
[13, 64, 115]

iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
iex> Image.dominant_color!(image)
[90, 90, 90]
@spec filename(image :: Vix.Vips.Image.t()) :: Path.t() | nil

Returns the filename for an image.

Arguments

Returns

  • The pathname from which the image was opened or nil if there is no associated path. This can happen in the case of a streamed image or an image created from a memory buffer.
@spec 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

Returns

  • true or false

Examples

iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
iex> Image.has_alpha?(image)
true

iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
iex> Image.has_alpha?(image)
false
@spec height(image :: Vix.Vips.Image.t()) :: pos_integer()

Returns the height of an image.

Arguments

Returns

  • The image height as an integer.
Link to this function

pages(image)

View Source (since 0.38.0)
@spec pages(image :: Vix.Vips.Image.t()) :: pos_integer()

Returns the number of pages in an image.

Animated images will return an integer representing the number of animated frames. Normal images will return 1.

Arguments

Returns

  • integer number of pages in the image.

Example

iex> image = Image.open!("./test/support/images/animated.webp")
iex> Image.pages(image)
12

iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
iex> Image.pages(image)
1
Link to this function

range(image)

View Source (since 0.35.0)
@spec range(image :: Vix.Vips.Image.t()) ::
  {non_neg_integer() | float(), non_neg_integer() | float()}

Returns the range of permissable values as a tuple for each pixel in an image.

Arguments

Returns

  • {min_value, max_value} where min_value and max_value are integers for unsigned images and floats for signed images.

Examples

  iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
  iex> Image.range(image)
  {0, 255}
Link to this function

shape(image)

View Source (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

Returns

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

Example

iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
iex> Image.shape(image)
{1000,542, 3}
@spec width(image :: Vix.Vips.Image.t()) :: pos_integer()

Returns the width of an image.

Arguments

Returns

  • The image width as an integer.

Masks

Link to this function

circle(image, options \\ [])

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

Returns

  • {:ok, circular_image} or

  • {:error, reason}

Link to this function

circle!(image, options \\ [])

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

Returns

  • circular_image or

  • raises an exception.

Link to this function

convert_alpha_to_mask(image)

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

Convert an image alpha band into a mask.

Takes an image, extracts its alpha band which holds the opacity information and inverts the content to produce a mask.

Arguments

Returns

  • {:ok, mask} or

  • {:error, reason}

Link to this function

convert_alpha_to_mask!(image)

View Source
@spec convert_alpha_to_mask!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()

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

Takes an image, extracts its alpha band which holds the opacity information and inverts the content to produce a mask.

Arguments

Returns

  • mask image or

  • raises an exception

Link to this function

rounded!(image, options \\ [])

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

Options

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

Returns

  • rounded_corner_image or

  • raises an exception.

Link to this function

squircle!(image, options \\ [])

View Source
@spec squircle!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()

Apply a squircle mask to an image. Returns an image or raises an exception.

Arguments

Options

  • :radius is the desired squircle radius. The default is 20.

Returns

  • squircle_image or

  • raises an exception.

Metadata

Nx & Evision

Link to this function

from_evision(evision_image)

View Source (since 0.9.0)

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

Arguments

Returns

  • {:ok, image}

Notes

  • Image images have the shape {width, height, bands} whereas Evision images have the shape {height, width, bands} so this function transposes the dimensions to match.

  • Image data is arranged as rgb data elements whereas Evision requires the data to be in bgr order. This function also reorders the data appropriately.

Link to this function

from_nx(tensor)

View Source (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

Returns

  • {:ok, image} or

  • {:error, reason}

Notes

In order to convert a tensor into an image it must satisfy these constraints:

  • It must have three dimensions.

  • It must have a tensor type that is compatible with libvips (most tensors will satisfy this requirement other than tensors whose type is complex).

  • The names of the axes must be [:width, :height, any_other] or [:height, :width, any_other].

Example

iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
iex> {:ok, tensor} = Image.to_nx(image)
iex> {:ok, _image_2} = Image.from_nx(tensor)
Link to this function

to_evision(image, convert_to_bgr \\ true)

View Source (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

  • image is any t:Vimage.t/0

  • convert_to_bgr is a boolean indicating if the color order should be converted from RGB to BGR which is the normal channel layout for OpenCV. The default is true.

Returns

  • {:ok, evision_image}

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.

Link to this function

to_nx(image, options \\ [])

View Source (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

  • image is any t:Vimage.t/0

  • options is a keyword list of options

Options

  • :shape determines how the tensor is shaped. The valid values are:
    • :hwb or :hwc which leaves the tensor unchanged with the underlying data in {height, width, bands} shape. This is the default action.

    • :whc or :whb which reshapes the tensor to width, height, bands.

Returns

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

  • {:error, reason}.

Note

  • The image type, Vix.Vips.Image.t/0 stores data in {width, height, band} format. However when the data is conerted into an Nx.Tensor.t/0 the data is written in {height, width, band} format.

Example

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

to_nx!(image, options \\ [])

View Source (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

  • image is any t:Vimage.t/0

  • options is a keyword list of options

Options

  • :shape determines how the tensor is shaped. The valid values are:
    • :hwb or :hwc which leaves the tensor unchanged with the underlying data in {height, width, bands} shape. This is the default action.

    • :whc or :whb which reshapes the tensor to width, height, bands.

Returns

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

  • raises an exception.

Note

  • The image type, Vix.Vips.Image.t/0 stores data in {width, height, band} format. However when the data is conerted into an Nx.Tensor.t/0 the data is written in {height, width, band} format.

Example

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

Preview

@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

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

Link to this function

preview(image)

View Source (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

Returns

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

Notes

  • The function Image.p/1 is delegated to this function.

  • The maximum width of the preview can be set by the environment variable IMAGE_PREVIEW_MAX_WIDTH. The default is 1_000 pixels wide. If the width of the image is greater than the maximum it will be resized to the maximum width for the preview.

  • Intended to be used as shortcut in iex. It can be included in an .iex.exs file:

    # .iex.exs import_if_available(Image, only: [preview: 1])

Guards

Link to this macro

is_box(left, top, width, height)

View Source (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.

Link to this macro

is_multiplier(value)

View Source (macro)

Guards whether a value is a multiplier as representeed by a float greater than 0.0.

Link to this macro

is_percent(value)

View Source (macro)

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

Link to this macro

is_pixel(value)

View Source (macro)

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

Link to this macro

is_positive_percent(value)

View Source (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.

Link to this macro

is_rectangle(top_left, top_right, bottom_right, bottom_left)

View Source (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.

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

libvips Configuration

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

Link to this function

put_concurrency(concurrency)

View Source
@spec put_concurrency(pos_integer()) :: pos_integer()

Sets the number of available threads for use by libvips.

By default this is the same as the number of cores in the system. Reducing this number may prevent CPU starvation for other workloads.

Arguments

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

Returns

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

Returns the version of libvips in operation.

Types

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

Image orientation.

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

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

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

@type error_message() :: term()

Error messages returned by libvips

Typically a string.

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

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

The valid sources of image data when opening an image.

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

@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

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

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

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

@type render_intent() :: :perceptual | :relative | :saturation | :absolute

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

Perceptual Intent

Perceptual rendering is used to process photographic type images. This intent processes the colors so that the output reproduction is pleasing. This process tends to change the color from the original, so no guarantee the reproduction will be accurate against the original.

Relative Intent

Relative colorimetric changes all the colours out of gamut to the nearest colour in gamut, so many colours change to the same one. It DOES NOT change colours in gamut. Perceptual changes ALL the colours in the image in a proportional way so that they lie in the output device gamut.

Saturation Intent

Saturation moves in-gamut colors toward the edge of the destination gamut for maximum saturation and impact. This intent will make an image more colorful by using the full gamut of the destination device. This intent cares not for the genuine representation of color.

Absolute Intent

Absolute rendering attempts to reproduce all colors numerically (destination = source). This can cause unexpected results if the source gamut is larger than the destination.

@type transparency() :: 0..255 | :opaque | :transparent

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

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

The x location on an image which is either a non_negative 0-based integer relative to the image left or a negative -1-based integer relative to the image right or the symbolic references :left, :center and :right.

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

The y location on an image which is either a non_negative 0-based integer relative to the image top or a negative -1-based integer relative to the image right or the symbolic references :top, :middle and :bottom.

Functions

Link to this function

average(image)

View Source (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

Returns

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

Example

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

average!(image)

View Source (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

Returns

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

Example

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

dhash_pixels(image, convolution, hash_size)

View Source
Link to this function

from_kino(map, options \\ [])

View Source (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

  • 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

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

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

  • {:ok, image} or

  • {:error, reason}

Link to this function

from_kino!(map, options \\ [])

View Source (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

  • 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

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

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

  • {:ok, image} or

  • raises an exception.

Link to this function

invert(image)

View Source (since 0.42.0)
@spec invert(image :: Vix.Vips.Image.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}

Inverts an image.

Arguments

Returns

  • {:ok, inverted_image} or

  • {:error, reason}.

Notes

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

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

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

Link to this function

invert!(image)

View Source (since 0.42.0)
@spec invert!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()

Inverts an image or raises an exception.

Arguments

Returns

  • inverted_image or

  • raises an exception.

Notes

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

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

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

Link to this macro

is_image(image_type)

View Source (macro)

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

Link to this function

join(image_list, options \\ [])

View Source
@spec join(
  image_list :: [Vix.Vips.Image.t()],
  options :: Image.Options.Join.join_options()
) ::
  {:ok, joined_image :: Vix.Vips.Image.t()} | {:error, error_message()}

Join a list of images into a single image.

Arguments

  • image_list is a non-empty list of t:Vimage.t/0 images.

  • options is a keyword list of options.

Options

  • :across is an integer number of images in the horizontal direction of the grid. The default is 1.

  • :vertical_spacing determines the height in pixels of each image row. The default, 0, means that the row height is the maximum height of the images in image_list.

  • :horizontal_spacing determines the width in pixels of each image in a row. The default, 0, means that the width is the maximum width of the images in image_list.

  • :vertical_align is :bottom, :middle or :top. The default is :bottom.

  • :horizontal_align is :left, :center or :right. The default is :left.

  • :background_color is the color of any pixels generated between images. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The default is 0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. See Image.Color.color_map/0 and Image.Color.rgb_color/1.

  • :shim is the number of pixels of spacing between images in the grid. The default is 0.

Returns

  • {:ok, joined_image} or

  • {:error, reason}

Notes

Image.join/2Lay out the list of images in a grid. The grid is :across images across and however high is necessary to use up all of image_list. Images are set down left-to-right and top-to-bottom.

Each input image is placed with a box of size :horizontal_spacing by :vertical_spacing pixels and cropped. These default to the largest width and largest height of the input images.

Space between images is filled with :background_color . This defaults to black.

Images are positioned within their :horizontal_spacing by :vertical_spacing box at :vertical_align of :bottom, :middle or :top``and by:horizontal_alignof:left,:centeror:righ. The defaults are:bottom,:left.

Link to this function

join!(image_list, options \\ [])

View Source
@spec join!(
  image_list :: [Vix.Vips.Image.t()],
  options :: Image.Options.Join.join_options()
) ::
  joined_image :: Vix.Vips.Image.t() | no_return()

Join a list of images into a single image or raises an exception.

Arguments

  • image_list is a non-empty list of t:Vimage.t/0 images.

  • options is a keyword list of options.

Options

  • :across is an integer number of images in the horizontal direction of the grid. The default is 1.

  • :vertical_spacing determines the height in pixels of each image row. The default, 0, means that the row height is the maximum height of the images in image_list.

  • :horizontal_spacing determines the width in pixels of each image in a row. The default, 0, means that the width is the maximum width of the images in image_list.

  • :vertical_align is :bottom, :middle or :top. The default is :bottom.

  • :horizontal_align is :left, :center or :right. The default is :left.

  • :background_color is the color of any pixels generated between images. This can be specified as a single integer which will be applied to all bands, or a list of integers representing the color for each band. The default is 0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example: :misty_rose. See Image.Color.color_map/0 and Image.Color.rgb_color/1.

  • :shim is the number of pixels of spacing between images in the grid. The default is 0.

Returns

  • {:ok, joined_image} or

  • {:error, reason}

Notes

Image.join/2Lay out the list of images in a grid. The grid is :across images across and however high is necessary to use up all of image_list. Images are set down left-to-right and top-to-bottom.

Each input image is placed with a box of size :horizontal_spacing by :vertical_spacing pixels and cropped. These default to the largest width and largest height of the input images.

Space between images is filled with :background_color . This defaults to black.

Images are positioned within their :horizontal_spacing by :vertical_spacing box at :vertical_align of :bottom, :middle or :top``and by:horizontal_alignof:left,:centeror:righ. The defaults are:bottom,:left.

Link to this function

linear_gradient(image, options)

View Source
@spec linear_gradient(Vix.Vips.Image.t(), options :: Keyword.t()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec linear_gradient(width :: pos_integer(), height :: pos_integer()) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Link to this function

linear_gradient(width, height, options)

View Source
@spec linear_gradient(
  width :: pos_integer(),
  height :: pos_integer(),
  options :: Keyword.t()
) ::
  {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Link to this function

linear_gradient!(image, options)

View Source
@spec linear_gradient!(Vix.Vips.Image.t(), options :: Keyword.t()) ::
  Vix.Vips.Image.t() | no_return()
Link to this function

linear_gradient!(width, height, options \\ [])

View Source