View Source Image (image v0.54.4)
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.
Basic Adjustments
Applies a tone curve to an image.
Applies a tone curve to an image or raises an exception.
Apply a percentage adjustment to an image's brightness (luminance).
Apply a percentage adjustment to an image's brightness (luminance) or raises an exception.
Apply a percentage adjustment to an image's contrast.
Apply a percentage adjustment to an image's contrast or raises and exception.
Equalizes the histogram of an imaage.
Apply a global contrast adjustment to an image or raises an exception.
Inverts an image.
Inverts an image or raises an exception.
Apply a local contrast adjustment to an image.
Transforms an image using brightness, saturation, hue rotation, and lightness.
Transforms an image using brightness, saturation, hue rotation, and lightness or raises an exception.
Apply an adjustment to an image's saturation (chroma).
Apply an adjustment to an image's saturation (chroma) or raises an exception.
Operations
Add an alpha band to an image.
Add an alpha band to an image.
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.
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.
Compare two images using a particular comparison metric returning a score indicating the similarity of the images and an image highlighting the differences between the two images.
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.
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.
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.
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.
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 or raises an exception.
Applies a transformation matrix to an image.
For each page of an image, execute fun/1 then
reassemble the pages.
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.
Sharpens an image.
Sharpens an image or raises an exception.
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.
Apply an curve adjustment to an image's saturation (chroma) such that less saturated colors are more affected than more saturated colors.
Apply an curve adjustment to an image's saturation (chroma) such that less saturated colors are more affected than more saturated colors. Raises on error.
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.
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.
Crop 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.
Joins a list of bands into a single image.
Joins a list of bands into a single image or raises an exception.
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 image to the given colorspace returning an image or raising an exception.
Introspection
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.
Histogram
Returns a single band image representing the right hand side (positive range) of the logistic function.
Clusters
Returns the histogram for an image.
Reduces the number of colors in an image.
Reduces the number of colors in an image or raises an exception.
Color Difference
Returns the color difference between two colors calculated using the CIE ΔE* algorithms.
Returns the color difference between two colors calculated using the CIE ΔE* algorithms or raises an exception.
Masks
Return a chroma-based masked image.
Return a chroma-based masked image or raises an exception.
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.t/0 image.
Converts an Nx tensor into an image.
Converts an Nx tensor into an image or raises an exception.
Converts an Image image to an Evision.Mat.t/0 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.
Kino
Transfers an image to Kino for display in a livebook.
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.
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
@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
binaryis a binary representation of a formatted image including.jpg,.png,.webpand.svgbinary data.optionsis a keyword list of options. SeeImage.open/2for the list of applicable options.
Returns
{:ok, image}or{:error, reason}
@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.
binaryis a binary representation of a formatted image including.jpg,.png,.webpand.svgbinary data.
Arguments
binaryis a binary representation of a formatted imageoptionsis a keyword list of options. SeeImage.open/2for the list of applicable options.
Returns
imageorraises an exception.
@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
svgis an SVG string.optionsis a keyword list of options.
Options
:accessis the file access mode, either:randomor:sequential. The default is:random. When:sequential,Image(viaVix) is able to support streaming transformations and optimise memory usage more effectively. However:sequentialalso means that some operations cannot be completed because they would require non-sequential access to the image. In these cases,:randomaccess is required.:fail_onsets 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:errorimplies also:truncated.:scalewill scale the image on load. The value is a number greater than0and less than or equal to1024with a default of1.0meaning no scaling on load. Numbers less than1.0scale the image down so that a scale of0.5will halve the image size on load.
Returns
{:ok, image}or{:error, reason}
@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
svgis an SVG string.optionsis a keyword list of options.
Options
:accessis the file access mode, either:randomor:sequential. The default is:random. When:sequential,Image(viaVix) is able to support streaming transformations and optimise memory usage more effectively. However:sequentialalso means that some operations cannot be completed because they would require non-sequential access to the image. In these cases,:randomaccess is required.:fail_onsets 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:errorimplies also:truncated.:scalewill scale the image on load. The value is a number greater than0and less than or equal to1024with a default of1.0meaning no scaling on load. Numbers less than1.0scale the image down so that a scale of0.5will halve the image size on load.
Returns
imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0from which the new imageswidthandheightandbandswill 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.
widthis the image width as an integer.heightis the image height as an integer.imageis an image from which thewidth,heightare derived.optionsis a keyword list of options.
Options
:colordefines 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.:bandsdefines the number of bands (channels) to be created. The default is the number of bands of:coloroption or if:coloris an integer then the default value is3.:formatdefines the format of the image. The default is{:u, 8}.:interpretationdefines the interpretation of the image. The default is:srgb.
Returns
{:ok, image}or{:error, reason}
Notes
- Either
widthandheightORimageshould 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)@spec new( width :: pos_integer(), height :: pos_integer(), options :: Image.Options.New.t() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
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
imageis anyVix.Vips.Image.t/0from which the new imageswidthandheightandbandswill be derived.optionsis a keyword list of options.
Options
:bandsdefines the number of bands (channels) to be created. The default is the number of bands inimage.:colordefines 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.:formatdefines the format of the image. The default is{:u, 8}.:interpretationdefines 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.
widthis the image width as an integer.heightis the image height as an integer.imageis an image from which thewidth,heightre derived.optionsis a keyword list of options.
Options
:bandsdefines the number of bands (channels) to be created. The default is3.:colordefines 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.:formatdefines the format of the image. The default is{:u, 8}.:interpretationdefines the interpretation of the image. The default is:srgb.
Returns
{:ok, image}or{:error, reason}
Notes
- Either
widthandheightORimageshould 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)@spec new!( width :: pos_integer(), height :: pos_integer(), options :: Image.Options.New.t() ) :: Vix.Vips.Image.t() | no_return()
@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_binaryis the file system path to an image file or aFile.Stream.t/0or anyEnumerable.t/0. It can also be any binary.jpg,.png,.webpor.svgimage.optionsis 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
:accessis the file access mode, either:randomor:sequential. The default is:random. When:sequential,Image(viaVix) is able to support streaming transformations and optimise memory usage more effectively. However:sequentialalso means that some operations cannot be completed because they would require non-sequential access to the image. In these cases,:randomaccess is required.:fail_onsets 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:errorimplies also:truncated.
JPEG image options
:shrinkis an integer factor in the range1..16by 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 is1meaning no shrink-on-load.
WEBP options
:scalewill scale the image on load. The value is a number greater than0and less than or equal to1024with a default of1meaning no scaling on load. Numbers less than1.0scale the image down so that a scale of0.5will halve the image size on load.:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
TIFF options
:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
GIF options
:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
PNG options
- There are no PNG-specific image loading options.
Returns
{:ok, image}or{:error, message}
@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_binaryis the file system path to an image file or aFile.Stream.t/0or anyEnumerable.t/0. It can also be any binary.jpg,.png,.webpor.svgimage.optionsis 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
:accessis the file access mode, either:randomor:sequential. The default is:random. When:sequential,Image(viaVix) is able to support streaming transformations and optimise memory usage more effectively. However:sequentialalso means that some operations cannot be completed because they would require non-sequential access to the image. In these cases,:randomaccess is required.:fail_onsets 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:errorimplies also:truncated.
JPEG image options
:shrinkis an integer factor in the range1..16by 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 is1meaning no shrink-on-load.:autorotateis a boolean value indicating if the image should be rotated according to the orientation data stored in the image metadata. The default isfalse.
WEBP options
:scalewill scale the image on load. The value is a number greater than0and less than or equal to1024with a default of1meaning no scaling on load. Numbers less than1.0scale the image down so that a scale of0.5will halve the image size on load.:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
TIFF options
:autorotateis a boolean value indicating if the image should be rotated according to the orientation data stored in the image metadata. The default isfalse.:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
GIF options
:pageindicates the first page to be loaded. The value is in the range0..100_000with a default value of0. This parameter is useful on animated images.:pagesindicates the number of pages to load. The value must be between-1and100_000. The default value is1. A value of-1would load all the available pages which is useful if you want to keep the animation of the input image. The atom:allcan be used in place of-1to indicate all pages should be loaded.
PNG options
- There are no PNG-specific image loading options.
Returns
imageorraises an exception.
@spec stream!( Vix.Vips.Image.t(), options :: Image.Options.Write.image_write_options() ) :: Enumerable.t()
Convert an image into an enumerable stream.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:buffer_sizeis 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/0suitable 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_sizeoption toImage.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()@spec write( image :: Vix.Vips.Image.t(), image_path :: Path.t() | Plug.Conn.t() | Enumerable.t() | File.Stream.t() | :memory, options :: Image.Options.Write.image_write_options() ) :: {:ok, Vix.Vips.Image.t()} | {:ok, binary()} | {:ok, Plug.Conn.t()} | {:error, error_message()}
Write an image to a file, a stream, an enumerable or to memory.
Arguments
imageis anyVix.Vips.Image.t/0.image_pathis the file system path to an image file. It may also be a stream created withFile.stream!/3or withStream.resource/3, aPlug.Conn.t/0ifPlugis configured or lastly, it can also be:memoryin which case the image is written to a binary.optionsis 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_metadatais a boolean indicating if all metadata is to be stripped from the image. The default isfalse.:backgroundis 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.:qualitywhich influences image compression and is a integer in the range1..100. The default for most image formats is75. For HEIF files the default is50.For PNG files the:qualityoption is ignored.
Streaming images and :memory images
:suffixmust be specified so that the image is written in the correct format. For example:suffix: ".jpg".
JPEG images
:progressiveis 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:progressiveis to be preferred but validation of this assumption for specific use cases is required.:minimize_file_sizeis 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_profileindicates 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
:progressivewhich has the same meaning and values as for JPEG images.:minimize_file_sizeis a boolean indicating whether to apply a number of techniques to minimise the file size of thepngfile at the cost of additional time to save the image. All metadata will also be removed.:compressionis the compression factor which is an integer in the range1..9. The default is6.:effortis an integer to adjust the level of CPU effort to reduce the file size. The value must be in the range1..10, the default is7.:icc_profileindicates 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_sizeis a boolean which is most useful on animatedWebP. 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-animatedwebpfile will only remove the metadata as:strip_metadatawould do.:effortis an integer to adjust the level of CPU effort to reduce the file size. The value must be in the range1..10, the default is7.:icc_profileindicates 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_maxerrorMaximum inter-frame error for transparency. The value must be in the range0..32. The default is0. By increasing this value, the encoder will try to take advantage from temporal redundancy between neighboring frames by enabling higher compression rates.:effortis an integer to adjust the level of CPU effort to reduce the file size. The value must be in the range1..10, the default is7.
HEIF images
:compressionis the compression strategy to be applied. The allowable values are:hevc,:avc,:jpegand:av1. The default is:hevc.:effortis an integer to adjust the level of CPU effort to reduce the file size. The value can be in the range1..10, the default is5.:minimize_file_sizeis a boolean indicating whether to apply a number of techniques to minimise the file size of theheiffile 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{:ok, conn}if the destination is at:Plug.Connt.t/0or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.image_pathis the file system path to an image file. It may also be a stream created withFile.stream!/3or withStream.resource/3. Lastly, it can also be:memoryin which case the image is written to a memory buffer.optionsis a keyword list of options. SeeImage.write/2.
Returns
image(or a binary if the destination is:memory) orraises an exception.
Basic Adjustments
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:black_pointis an integer between0(the default) and100indicating the darkest and most dense black area of the image will lie in the overall range of the image.:white_pointis an integer between0and100(the default) indicating the lightest area of the image will lie in the overall range of the image.:shadow_pointis the point on the tone curve around which the shadow values are tone mapped. The value is between0.0and1.0. The default is0.2.:mid_pointis the point on the tone curve around which the mid tone values are tone mapped. The value is between0.0and1.0. The default is0.5.:highlight_pointis the point on the tone curve around which the highlight values are tone mapped. The value is between0.0and1.0. The default is0.8.:shadowsindicates by how much the shadows should be adjusted. The value is in the range-30to30. The default is0.:mid_pointsindicates by how much the mid tones should be adjusted. The value is in the range-30to30. The default is0.:highlightsindicates by how much the highlights should be adjusted. The value is in the range-30to30. The default is0.
Returns
{:ok, tone_mapped_image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:black_pointis an integer between0(the default) and100indicating the darkest and most dense black area of the image will lie in the overall range of the image.:white_pointis an integer between0and100(the default) indicating the lightest area of the image will lie in the overall range of the image.:shadow_pointis the point on the tone curve around which the shadow values are tone mapped. The value is between0.0and1.0. The default is0.2.:mid_pointis the point on the tone curve around which the mid tone values are tone mapped. The value is between0.0and1.0. The default is0.5.:highlight_pointis the point on the tone curve around which the highlight values are tone mapped. The value is between0.0and1.0. The default is0.8.:shadowsindicates by how much the shadows should be adjusted. The value is in the range-30to30. The default is0.:mid_pointsindicates by how much the mid tones should be adjusted. The value is in the range-30to30. The default is0.:highlightsindicates by how much the highlights should be adjusted. The value is in the range-30to30. The default is0.
Returns
tone_mapped_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.brightnessis any float greater than0.0. A number less than1.0means reduce brightness. A number greater than1.0means increas brightness.
Returns
{:ok, adjusted_image}or{:error, reason}.
Example
iex> image = Image.open!("./test/support/images/cat.png")
iex> {:ok, _brighter_image} = Image.brightness(image, 1.5)@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
imageis anyVix.Vips.Image.t/0.brightnessis any float greater than0.0. A number less than1.0means reduce brightness. A number greater than1.0means increas brightness.
Returns
adjusted_imageorraises an exception.
Example
iex> image = Image.open!("./test/support/images/cat.png")
iex> _brighter_image = Image.brightness!(image, 1.5)@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
imageis anyVix.Vips.Image.t/0.contrastis any float greater than0.0. A number less than1.0means reduce contrast. A number greater than1.0means increase contrast.
Returns
{:ok, adjusted_image}or{:error, reason}.
Example
iex> image = Image.open!("./test/support/images/cat.png")
iex> {:ok, _image_with_more_contrast} = Image.contrast(image, 1.2)@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
imageis anyVix.Vips.Image.t/0.contrastis any float greater than0.0. A number less than1.0means reduce contrast. A number greater than1.0means increase contrast.
Returns
adjusted_imageorraises an exception.
Example
iex> image = Image.open!("./test/support/images/cat.png")
iex> _image_with_more_contrast = Image.contrast!(image, 1.2)@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
imageis anyVix.Vips.Image.t/0.bandsdetermines 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.:eachmeans 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.:luminancemeans that only the luminance band is equqlized to fill between 1% and 99% of the tone range. The image is converted to the:labcolor space, thelband is equalized and the image is converted back to its origianal color space.
Returns
{:ok, adjusted_image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.bandsdetermines 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.:eachmeans 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.:luminancemeans that only the luminance band is equqlized to fill between 1% and 99% of the tone range. The image is converted to the:labcolor space, thelband is equalized and the image is converted back to its origianal color space.
Returns
adjusted_imageorraises an exception.
@spec invert(image :: Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Inverts an image.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
{:ok, inverted_image}or{:error, reason}.
Notes
For unsigned formats, this operation calculates
(max_value - pixel_value), eg.(255 - pixel_value)for typical 8-bit sRGB images.For signed and float formats, this operation calculates
(-1 * pixel_value).For complex images, only the real part is inverted.
@spec invert!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Inverts an image or raises an exception.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
inverted_imageorraises 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.
@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 (CLAHE) 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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:
window_sizeis an integer indicating the size of the window (in pixels) into the image in which the contrast adjustment is calculated. The default is3.:max_slopeis the integral level of brightening, between 0 and 100, where 0 (the default) disables contrast limiting.
Returns
{:ok, adjusted_image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:brightnessis any float greater than0.0. A number less than1.0means reduce brightness. A number greater than1.0means increas brightness. The default is1.0meaning no brightness adjustment.:lightnessis any float. This value is added to the luminance of an image. This is different to:brightnesswhich is multuplied by the luminance. The default is0.0meaning no lightness adjustment.:saturationis any float greater than0.0. A number less than1.0means reduce saturation. A number greater than1.0means increas saturation. The default is1.0meaning no saturation adjustment.:hueis 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 range0..360. The default is0meaning no hue adjustment.
Returns
{:ok, modulated_image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:brightnessis any float greater than0.0. A number less than1.0means reduce brightness. A number greater than1.0means increas brightness. The default is1.0meaning no brightness adjustment.:lightnessis any float. This value is added to the luminance of an image. This is different to:brightnesswhich is multuplied by the luminance. The default is0.0meaning no lightness adjustment.:saturationis any float greater than0.0. A number less than1.0means reduce saturation. A number greater than1.0means increas saturation. The default is1.0meaning no saturation adjustment.:hueis 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 range0..360. The default is0meaning no hue adjustment.
Returns
modulated_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.saturationis any float greater than0.0. A number less than1.0means reduce saturation. A number greater than1.0means increase saturation.
Returns
{:ok, adjusted_image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.saturationis any float greater than0.0. A number less than1.0means reduce saturation. A number greater than1.0means increase saturation.
Arguments
imageis anyVix.Vips.Image.t/0.saturationis any float greater than0.0. A number less than1.0means reduce saturation. A number greater than1.0means increas saturation.
Returns
adjusted_imageorraises an exception.
Operations
@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
imageis anyVix.Vips.Image.t/0.alpha_imageis any single-band image that will be added as an alpha image toimage
OR
- an integer in the range
0..255that represents the level of transparency of the alpha band.0represents fully opaque and255represents fully transparent. The atoms:opaqueand:transparentmay also be provided representing the values of0and255respectively.
Returns
{:ok, image_with_added_alpha_band}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.alpha_imageis any single-band image that will be added as an alpha image toimage
OR
:colorwhich 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.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_bandorraises 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
imageis anyVix.Vips.Image.t/0.
Returns
{:ok, {auto_rotated_image, flags}}or{:error, reason}
Flags
A two-entry Keyword.t is returned indicating what actions
were taken:
:flipwhich is a boolean indicating if the image was flipped or not and:anglethrough which the image was rotated. This value will be one of0,90,180or270representing 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
imageis anyVix.Vips.Image.t/0.
Returns
auto_rotated_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:sigmais thefloatsize of the mask to use. A larger number makes the image more blurry. A range between1.0and10.0is normally appropriate. The default is5.:min_amplitudeis afloatthat determines the accuracy of the mask. The default is0.2. A smaller number will generate a larger, more accurate mask,
Returns
{:ok, blurred_image}or{:error reason}
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:sigmais thefloatsize of the mask to use. A larger number makes the image more blurry. A range between1.0and10.0is normally appropriate. The default is5.:min_amplitudeis afloatthat determines the accuracy of the mask. The default is0.2. A smaller number will generate a larger, more accurate mask,
Returns
blurred_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.band_formatis any known band format. SeeImage.BandFormat.known_band_formats/0.
Returns
{:ok, cast_image}or{:error, reason}.
@spec cast!(Vix.Vips.Image.t(), Image.BandFormat.t()) :: Vix.Vips.Image.t() | no_return()
Casts an image from one band format to another or raises an exception.
The band format is the numeric type of each pixel.
In the common case of sRGB images, the format is
{:u, 8} meaning unsigned 8-bit values.
Arguments
imageis anyVix.Vips.Image.t/0.band_formatis any known band format. SeeImage.BandFormat.known_band_formats/0.
Returns
cast_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.
Returns
- An RGB color as a three-element list of integers.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
There are two masking strategies available: the thresholding strategy (default) and the color range strategy.
Threshold strategy
:coloris an RGB color which represents the the chroma key to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
There are two masking strategies available: the thresholding strategy (default) and the color range strategy.
Threshold strategy
:coloris an RGB color which represents the the chroma key to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.
@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 and an image highlighting the differences between the two images.
Arguments
image_1is anyVix.Vips.Image.t/0.image_2is anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:metricindicates 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) and1.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) and1.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.0means 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.
:saturationis a float between0.0and1.0that is applied to the base image when overlaying the difference image. This may help the difference pixels become more obvious. The default ia1.0meaning no change in saturation.:brightnessis a float between0.0and1.0that is applied to the base image when overlaying the difference image. This may help the difference pixels become more obvious. The default ia1.0meaning no change in brightness.:difference_coloris 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_boostis 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 is1.5.
Notes
The images are conformed to the band format of the first image before comparison and cast up to the smallest common format.
If the images differ in size, the smaller image is enlarged to match the larger by adding zero pixels along the bottom and right.
If the number of bands differs, one of the images must have one band. In this case, an n-band image is formed from the one-band image by joining
ncopies of the one-band image together, and then the two n-band images are operated upon.The two input images are cast up to the smallest common format.
Returns
{:ok, comparison_metric, difference_image}or{:error, reason}
@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_imageis anyVix.Vips.Image.t/0.overlay_imageis anyVix.Vips.Image.t/0that will be composed over the top ofbase_image. It can also be a list ofcomposition/0s that allow for multiple images to be composed in a single call.optionsis a keyword list of options.
Options for a single overlay image
:blend_modeis the manner in which the two images are composited. SeeImage.BlendMode.t/0. The default is:overwhich is the most common blend mode.:xis the offset (0-based) which, if zero or positive, from the left of thebase_image. If negative is is the offset from the right of thebase_image. where theoverlay_imagewill be placed. It may also be one of the keywords:left,:rightor:center. The default is:center.:yis the offset (0-based) which, if zero or positive, from the top of thebase_image. If negative is is the offset from the bottom of thebase_image. where theoverlay_imagewill be placed. It may also be one of the keywords:top,:bottomor: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.
:xdescribes the absolutexoffset on the base image where this image will be placed. If this option is set to:left,:centeror:rightthen thexposition will be calculated relative to the base image. If:xis nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dx.:ydescribes the absoluteyoffset on the base image where this image will be placed. If this option is set to:top,:middleor:bottomthen theyposition will be calculated relative to the base image. If:yis nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dy.:dxdescribes the relative offset used to calculate thexvalue.:dxis an integer offset from the edge of the previously composed image. Which edge is determined by the:x_baselineoption. If:xis also specified then:xis first calculated, then:dxis added to it. In this case,:x_baselineis ignored.:dydescribes the relative offset used to calculate theyvalue.:dyis an integer offset from the edge of the previously composed image. Which edge is determined by the:y_baselineoption. If:yis also specified then:yis first calculated, then:dyis added to it. In this case,:x_baselineis ignored.:blend_modeis theImage.BlendMode.t/0used when composing this image over its base image. The default is:overwhich is appropriate for most use cases.:x_baselineestablishes the baseline on the previously composed image from which:dxis calculated. The default is:right.:y_baselineestablishes the baseline on the previously composed image from which:dyis 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}
..> ])@spec compose!( base_image :: Vix.Vips.Image.t(), overlay_image :: Vix.Vips.Image.t(), options :: Image.Options.Compose.t() ) :: Vix.Vips.Image.t() | no_return()
@spec compose!( base_image :: Vix.Vips.Image.t(), image_list :: composition_list(), options :: Image.Options.Compose.t() ) :: Vix.Vips.Image.t() | no_return()
Compose two images together to form a new image or raise an exception.
Arguments
base_imageis anyVix.Vips.Image.t/0.overlay_imageis anyVix.Vips.Image.t/0that will be composed over the top ofbase_image.optionsis a keyword list of options.
Options
:blend_modeis the manner in which the two images are composited. SeeImage.BlendMode.t/0. The default is:overwhich is the most common blend mode.:xis the offset (0-based) which, if zero or positive, from the left of thebase_image. If negative is is the offset from the right of thebase_image. where theoverlay_imagewill be placed. It may also be one of the keywords:left,:rightor:center. The default is:center.:yis the offset (0-based) which, if zero or positive, from the top of thebase_image. If negative is is the offset from the bottom of thebase_image. where theoverlay_imagewill be placed. It may also be one of the keywords:top,:bottomor: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.
:xdescribes the absolutexoffset on the base image where this image will be placed. If this option is set to:left,:centeror:rightthen thexposition will be calculated relative to the base image. If:xis nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dx.:ydescribes the absoluteyoffset on the base image where this image will be placed. If this option is set to:top,:middleor:bottomthen theyposition will be calculated relative to the base image. If:yis nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dy.:dxdescribes the relative offset used to calculate thexvalue.:dxis an integer offset from the edge of the previously composed image. Which edge is determined by the:x_baselineoption. If:xis also specified then:xis first calculated, then:dxis added to it. In this case,:x_baselineis ignored.:dydescribes the relative offset used to calculate theyvalue.:dyis an integer offset from the edge of the previously composed image. Which edge is determined by the:y_baselineoption. If:yis also specified then:yis first calculated, then:dyis added to it. In this case,:x_baselineis ignored.:blend_modeis theImage.BlendMode.t/0used when composing this image over its base image. The default is:overwhich is appropriate for most use cases.:x_baselineestablishes the baseline on the previously composed image from which:dxis calculated. The default is:right.:y_baselineestablishes the baseline on the previously composed image from which:dyis calculated. The default is:bottom.
Returns
composed_imageorraises 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}
..> ])@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
imageis any non-complexVix.Vips.Image.t/0.radiusis an integer in the range1..100representing the approximate number of pixels to dilate. The default is1.
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.
@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
imageis any non-complexVix.Vips.Image.t/0.radiusis an integer in the range1..100representing the approximate number of pixels to dilate. The default is1.
Returns
dilated_maskorraises 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.
@spec embed!( Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer(), Image.Options.Embed.embed_options() ) :: Vix.Vips.Image.t() | no_return()
Embeds an image in a larger image canvas, generating addition border pixels if required.
Arguments
imageis anyVix.Vips.Image.t/0.widthis the width in pixels of the canvas image.heightis the height in pixels of the canvas image.optionsis a keyword list of options.
Options
See Image.embed/4.
Returns
embedded_imageorraises an exception.
@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
imageis any non-complexVix.Vips.Image.t/0.radiusis an integer in the range1..100representing the approximate number of pixels to erode. The default is1.
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.
@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
imageis any non-complexVix.Vips.Image.t/0.radiusis an integer in the range1..100representing the approximate number of pixels to erode. The default is1.
Returns
eroded_maskorraises 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.
@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
imageis anyVix.Vips.Image.t/0in.gifor.pngmulti-page format.
Returns
{:ok, list_of_images}or{:error, reasom}
Notes
The pages: :all option should be used when opening the
multi-page image.
Example
iex> image = Image.open!("./test/support/images/animated.gif", pages: :all)
iex> {:ok, list_of_images} = Image.extract_pages(image)
iex> Enum.count(list_of_images)
19@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
imageis anyVix.Vips.Image.t/0that is either a single band image or an image with an alpha band.optionsis a keyword list of options.
Options
:sigmais thefloatsize of the mask to use. A larger number makes the image more blurry. A range between1.0and10.0is normally appropriate. The default is5.:min_amplitudeis afloatthat determines the accuracy of the mask. The default is0.2. A smaller number will generate a larger, more accurate mask,
Returns
{:ok, blurred_mask_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0that is either a single band image or an image with an alpha band.optionsis a keyword list of options.
Options
:sigmais thefloatsize of the mask to use. A larger number makes the image more blurry. A range between1.0and10.0is normally appropriate. The default is5.:min_amplitudeis afloatthat determines the accuracy of the mask. The default is0.2. A smaller number will generate a larger, more accurate mask,
Returns
blurred_mask_imageorraises an exception.
@spec flatten(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Flatten an alpha layer out of an image.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:background_coloris an RGB color which is used to fill the transparent parts of the image.. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:black.
Returns
{:ok, flattened_image}or{:error, reason}
@spec flatten!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: Vix.Vips.Image.t() | no_return()
Flatten an alpha layer out of an image or raises an exception.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:background_coloris an RGB color which is used to fill the transparent parts of the image.. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:black.
Returns
flattened_imageorraises 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
imageis anyVix.Vips.Image.t/0.directionis either:horizontalor:vertical.
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
imageis anyVix.Vips.Image.t/0.directionis either:horizontalor:vertical.
Returns
flipped_imageorraises an exception.
@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.
If the colorspace of the image is :srgb then
the values are rounded.
Arguments
imageis anyVix.Vips.Image.t/0.xis an integer offset from the top left of the image along thex(width) axis. The number must be in the range0..width - 1.yis an integer offset from the top left of the image along they(height) axis. The number must be in the range0..height - 1.
Returns
{:ok, pixel_value}or{:error, reason}
@spec get_pixel!(Vix.Vips.Image.t(), non_neg_integer(), non_neg_integer()) :: Image.Color.rgb_color() | no_return()
Returns the pixel value at the given image location or raises an exception.
The returned pixel is a list of numbers where the length of the list is equal to the number of bands in the image.
Arguments
imageis anyVix.Vips.Image.t/0.xis an integer offset from the top left of the image along thex(width) axis. The number must be in the range0..width - 1.yis an integer offset from the top left of the image along they(height) axis. The number must be in the range0..height - 1.
Returns
pixel_valueorraises an exception
@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
image_1is anyVix.Vips.Image.t/0.image_2is anyVix.Vips.Image.t/0.
Alternatively, both arguments may be image hashes
returned by Image.dhash/1. Both arguments must
be of the same type.
Returns
{:ok, hamming_distance}where hamming distance is a positive integer or{:error, reason}.
if_then_else(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_imageis any image. Typically it is an image formed by the relation operations such asImage.Math.greater_than/2.if_image_or_coloris either ant:Vimage.t/0or aImage.Color.t/0. If a color is provided then an image is constructed with the same shape ascondition_imagefilled with the provided color.else_image_or_coloris either ant:Vimage.t/0or aImage.Color.t/0. If a color is provided then an image is constructed with the same shape ascondition_imagefilled with the provided color.optionsis a keyword list of options.
Options
:blendis a boolean indicating if a the operation should blend smoothly betweenthenandelseimages. The default isfalse.
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_imageif_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_imageis any image. Typically it is an image formed by the relation operations such asImage.Math.greater_than/2.if_image_or_coloris either ant:Vimage.t/0or aImage.Color.t/0. If a color is provided then an image is constructed with the same shape ascondition_imagefilled with the provided color.else_image_or_coloris either ant:Vimage.t/0or aImage.Color.t/0. If a color is provided then an image is constructed with the same shape ascondition_imagefilled with the provided color.
Returns
imageorraises 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`@spec local_contrast!( image :: Vix.Vips.Image.t(), options :: Image.Options.LocalContrast.local_contrast_options() ) :: Vix.Vips.Image.t() | no_return()
Apply a local contrast adjustment to an image or raises an exception.
This function applies a Constrast Limited Adaptive histogram equalization (CLAHE) 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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:
window_sizeis an integer indicating the size of the window (in pixels) into the image in which the contrast adjustment is calculated. The default is3.:max_slopeis the integral level of brightening, between 0 and 100, where 0 (the default) disables contrast limiting.
Returns
adjusted_imageorraises an exception.
@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
imageis anyt:Vimage.t/0transform_matrixis a matrix returned byImage.transform_matrix/3.
Returns
{:ok, mapped_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0in.gifor.pngmulti-page format.funis any 1-arity function that takes a page as aVix.Vips.Image.t/0as 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 fromfun/1are assembled intomapped_imageor{: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."}@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 gen_server in order
to maintain thread safety.
In order to perform multiple mutations without
coopying for each each mutation,Image.mutate/2 takes
a function argument fun that is passed a
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.
Arguments
imageis anyVix.Vips.Image.t/0.funis any 1-arity function that receives aVix.Vips.MutableImage.t/0parameter. This function must return either:okor{:ok, term}.
Returns
{:ok, mutated_image}or{:error, reason}
Notes
The image is copied and operations are serialized behind a gen_server.
Only one copy is made but all operations will be serialized behind the
gen_server. When the function returns, the gen_server is broken down and
the underlying mutated Vix.Vips.Image.t/0 is returned.
Example
iex> {:ok, image} = Image.open("./test/support/images/puppy.webp")
iex> {:ok, _mutated_copy} =
...> Image.mutate(image, fn mut_image ->
...> cx = cy = div(Image.height(image), 2)
...> {:ok, _image} = Image.Draw.circle(mut_image, cx, cy, 100, color: :green)
...> end)@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
imageis anyVix.Vips.Image.t/0.scaleis the scale factor to apply to the image when it is pixelated. This means that one "pixel" isimage width * scale. The default is0.05.
Returns
{:ok, pixelated_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.scaleis the scale factor to apply to the image when it is pixelated. This means that one "pixel" isimage width * scale. The default is0.05.
Returns
{:ok, pixelated_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.window_sizeis the integer size of the convolution kernel used in the median rank filter. The default is3.
Returns
{:ok, reduced_noise_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.window_sizeis the integer size of the convolution kernel used in the median rank filter. The default is3.
Returns
reduced_noise_imageorraises 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
imageis anyVix.Vips.Image.t/0.
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
imageis anyVix.Vips.Image.t/0.
Returns
image_with_rippleorraises an exception.
@spec rotate( image :: Vix.Vips.Image.t(), angle :: float(), options :: Image.Options.Rotate.rotation_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Rotate an image clockwise (to the right) by a number of degrees.
Arguments
imageis anyVix.Vips.Image.t/0.angleis afloatnumber of degrees to rotate in a clockwise direction.optionsis a keyword list of options.
Options
:idyis the vertical input displacement which defaults to0.0:idxis the horizontal input displacement which defaults to0.0:odyis the vertical output displacement which defaults to0.0:odxis the horizontal output displacement which defaults to0.0:backgroundis 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}
@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
imageis anyVix.Vips.Image.t/0.angleis afloatnumber of degrees to rotate in a clockwise direction.optionsis a keyword list of options. SeeImage.rotate/3.
Notes
The displacement parameters cause the image canvas to be expanded and the image displaced, relative to the top left corner of the image, by the amount specified.
The rules defining how the image canvas is expanded
is not known to the author of Image. Experimentation will
be required if you explore these options.
Returns
rotated_imageorraises an exception.
@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:
m1is:flat_amountm2is:jagged_amountx1is:thresholdy2is:max_brighteningy3is:max_darkening
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:jagged_amountis 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 to0.0with a default of3.0.:flat_amountis the specifies how much sharpening to apply to flat areas of the image. It is a float greater or equal to0.0with a default of0.0.:thresholdindicates 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 to0.0with a default of2.0.:max_brighteningspecifies how much the image may be brightened as part of the sharpening process. It is a positive integer greater than or equal to0. The default is10.:max_darkeningspecifies how much the image may be darkened as part of the sharpening process. It is a positive integer greater than or equal to0. The default is20.:sigmachanges the width of the sharpening fringe and can be adjusted according to the output printing resolution. As an approximate guideline, use0.5for 4 pixels/mm (display resolution),1.0for 12 pixels/mm and1.5for 16 pixels/mm (300 dpi == 12 pixels/mm). These figures refer to the image raster, not the half-tone resolution. The default is0.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.
@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:
m1is:flat_amountm2is:jagged_amountx1is:thresholdy2is:max_brighteningy3is:max_darkening
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:jagged_amountis 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 to0.0with a default of3.0.:flat_amountis the specifies how much sharpening to apply to flat areas of the image. It is a float greater or equal to0.0with a default of0.0.:thresholdindicates 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 to0.0with a default of2.0.:max_brighteningspecifies how much the image may be brightened as part of the sharpening process. It is a positive integer greater than or equal to0. The default is10.:max_darkeningspecifies how much the image may be darkened as part of the sharpening process. It is a positive integer greater than or equal to0. The default is20.:sigmachanges the width of the sharpening fringe and can be adjusted according to the output printing resolution. As an approximate guideline, use0.5for 4 pixels/mm (display resolution),1.0for 12 pixels/mm and1.5for 16 pixels/mm (300 dpi == 12 pixels/mm). These figures refer to the image raster, not the half-tone resolution. The default is0.5.
Returns
sharpened_imageorraises an exception.
Output sharpening
For screen output sharpening the default options are recommended.
Adjust :sigma for other output devices as required.
@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
imageis anyVix.Vips.Image.t/0.
Returns
{image_without_alpha, alpha_band}or{image, nil}if there is no alpha band detected.
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
imageis anyt:Vimage.t/0sourceis a list of four 2-tuples representing the four corners of the subject-of-interest inimage.optionsis a keyword list of options. The default is[].
Options
:backgrounddefines 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.:backgroundcan also be set to:averagein which case the background will be the average color of the base image. See alsoImage.Color.color_map/0andImage.Color.rgb_color/1.:extend_modedetermines how any additional pixels are generated. The values are::black(the default) meaning the generated pixels are black.:whitemeaning the generated pixels are white.:copymeans the generated pixels take the value of the nearest edge pixel of the base image.:repeatmeans the generated pixels are tiles from the base image.:mirrormeans the generated pixels are a reflected tiles of the base image.:backgroundmeans the generated pixels are the background color setinoptions.
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
destinationis a four element list of 2-tuples representing the four points to which thesourcepoints were transformed.destinationcan be passed as a parameter toImage.crop/2to crop the transformed image to the subject-of-interest that was warped.
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
imageis anyt:Vimage.t/0sourceis a list of four 2-tuples representing the four corners of the subject-of-interest inimage.optionsis a keyword list of options. The default is[].
Options
:backgrounddefines 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.:backgroundcan also be set to:averagein which case the background will be the average color of the base image. See alsoImage.Color.color_map/0andImage.Color.rgb_color/1.:extend_modedetermines how any additional pixels are generated. The values are::black(the default) meaning the generated pixels are black.:whitemeaning the generated pixels are white.:copymeans the generated pixels take the value of the nearest edge pixel of the base image.:repeatmeans the generated pixels are tiles from the base image.:mirrormeans the generated pixels are a reflected tiles of the base image.:backgroundmeans the generated pixels are the background color setinoptions.
Returns
straightened_imageor{: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
destinationis a four element list of 2-tuples representing the four points to which thesourcepoints were transformed.destinationcan be passed as a parameter toImage.crop/2to crop the transformed image to the subject-of-interest that was warped.
@spec to_polar_coordinates(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Convert image to polar coordinates.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
{:ok, image_in_polar_coordinates}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.
Returns
image_in_polar_coordinatesorraises an exception.
@spec to_rectangular_coordinates(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Convert image to rectangular coordinates.
Arguments
imageis anyVix.Vips.Image.t/0.
Notes
Roundtrip to polar and back to rectangular coordinates displays some image distortion, likely due to rounding errors in float arithmetic. Further study is required.
Returns
{:ok, image_in_rectangular_coordinates}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.
Notes
Roundtrip to polar and back to rectangular coordinates displays some image distortion, likely due to rounding errors in float arithmetic. Further study is required.
Returns
image_in_rectangular_coordinatesorraises an exception.
@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
imageis anyt:Vimage.t/0sourceis a list of four 2-tuples representing the four corners of the subject-of-interest inimage.destinationis 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}.
@spec vibrance( image :: Vix.Vips.Image.t(), vibrance :: float(), options :: Image.Options.Vibrance.vibrance_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Apply an curve adjustment to an image's saturation (chroma) such that less saturated colors are more affected than more saturated colors.
This operation is similar to the vibrance function in Adobe Lightroom. However this implementation does not account for skin tones.
Arguments
imageis anyVix.Vips.Image.t/0.vibranceis any float greater than0.0. A number less than1.0means reduce vibrance. A number greater than1.0means increase vibrance.optionsis a keyword list of options.
Options
:thresholdis the saturation level above which no adjustment is made. The range is1..100with a default of70.
Returns
{:ok, adjusted_image}or{:error, reason}.
@spec vibrance!( image :: Vix.Vips.Image.t(), vibrance :: float(), options :: Image.Options.Vibrance.vibrance_options() ) :: Vix.Vips.Image.t() | no_return()
Apply an curve adjustment to an image's saturation (chroma) such that less saturated colors are more affected than more saturated colors. Raises on error.
This operation is similar to the vibrance function in Adobe Lightroom. However this implementation does not account for skin tones.
Arguments
imageis anyVix.Vips.Image.t/0.vibranceis any float greater than0.0. A number less than1.0means reduce vibrance. A number greater than1.0means increase vibrance.optionsis a keyword list of options.
Options
:thresholdis the saturation level above which no adjustment is made. The range is1..100with a default of60.
Returns
adjusted_imageorraises an exception.
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
imageis anyt:Vimage.t/0sourceis a list of four 2-tuples representing the four corners of the subject-of-interest inimage.destinationis a list of four 2-tuples representing the four corners of the destination image into which the subject-of-interest is transformed.optionsis a keyword list of options. The default is[].
Options
:backgrounddefines 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.:backgroundcan also be set to:averagein which case the background will be the average color of the base image. See alsoImage.Color.color_map/0andImage.Color.rgb_color/1.:extend_modedetermines how any additional pixels are generated. The values are::black(the default) meaning the generated pixels are black.:whitemeaning the generated pixels are white.:copymeans the generated pixels take the value of the nearest edge pixel of the base image.:repeatmeans the generated pixels are tiles from the base image.:mirrormeans the generated pixels are a reflected tiles of the base image.:backgroundmeans the generated pixels are the background color setinoptions.
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}
@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
imageis anyt:Vimage.t/0sourceis a list of four 2-tuples representing the four corners of the subject-of-interest inimage.destinationis a list of four 2-tuples representing the four corners of the destination image into which the subject-of-interest is transformed.optionsis a keyword list of options. The default is[].
Options
:backgrounddefines 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.:backgroundcan also be set to:averagein which case the background will be the average color of the base image. See alsoImage.Color.color_map/0andImage.Color.rgb_color/1.:extend_modedetermines how any additional pixels are generated. The values are::black(the default) meaning the generated pixels are black.:whitemeaning the generated pixels are white.:copymeans the generated pixels take the value of the nearest edge pixel of the base image.:repeatmeans the generated pixels are tiles from the base image.:mirrormeans the generated pixels are a reflected tiles of the base image.:backgroundmeans the generated pixels are the background color setinoptions.
Returns
warped_imageorraises an exception.
Notes
- The image is flattened before warping and therefore any alpha band will be multiplied into to the image data and removed.
@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
imageis anyVix.Vips.Image.t/0.band_formatis any valid band format. SeeImage.BandFormat.known_band_formats/0.funis any 1-arity function that is required to return{:ok, image}or{:error, reason}.
Returns
{:ok, image}or{:error, reason}.
Example
iex> image = Image.open!("./test/support/images/Singapore-2016-09-5887.jpg")
iex> {:ok, updated_image} = Image.with_band_format(image, {:s, 16}, fn i -> {:ok, i} end)
iex> Image.band_format(updated_image)
{:u, 8}@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
imageis anyVix.Vips.Image.t/0.colorspaceis any valid color space. SeeImage.Interpretation.known_interpretations/0.funis any 1-arity function that is required to return{:ok, image}or{:error, reason}.
Returns
{:ok, image}or{:error, reason}.
@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
imageis anyVix.Vips.Image.t/0.funis any 1-arity function that is required to return{:ok, image}or{:error, reason}.
Returns
{:ok, image}or{:error, reason}.
Resize
@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
imageis anyVix.Vips.Image.t/0.widthis the width in pixels of the canvas image.heightis the height in pixels of the canvas image.optionsis a keyword list of options.
Options
:xis the x-offset into the canvas image whereimagewill 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.:yis the y-offset into the canvas image whereimagewill 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_colordefines 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.:backgroundcan also be set to:averagein which case the background will be the average color of the base image. See alsoImage.Color.color_map/0andImage.Color.rgb_color/1.:background_transparencydefines the transparency of the:backgroundpixels whenimagehas an alpha band. The default is:opaque. The values are an integer in the range0..255where0is transparent and255is opaque. The number can also be a float in the range0.0to1.0. In this case the float is converted to an integer in the range0..255. Lastly, the atoms:transparentand:opaquecan also be used.:extend_modedetermines how any additional pixels are generated. The values are::black(the default if nobackground_coloris specified) meaning the generated pixels are black.:whitemeaning the generated pixels are white.:copymeans the generated pixels take the value of the nearest edge pixel of the base image.:repeatmeans the generated pixels are tiles from the base image.:mirrormeans the generated pixels are reflected tiles of the base image.:backgroundmeans the generated pixels are the:background_colorcolor set inoptions. This is the default if abackground_coloris specified.
Returns
{:ok, embedded_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.scaleis a float scale factor.optionsis a keyword list of options.
Options
:centreis a boolean indicating whether to use the centre downsampling convention. The default isfalse.:interpolatedefines which resampling kernel to apply. The options are:nearest,:linear,:cubic,:mitchell,:lanczos2or:lanczos3(the default).:vertical_scaleis a float indicating the scaling factor of the vertical axis. In specified, thenscaleis applied only to the horizontal axis.
Returns
{:ok, resized_image}orraises an exception
@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
imageis anyVix.Vips.Image.t/0.scaleis a float scale factor.optionsis a keyword list of options.
Options
:centreis a boolean indicating whether to use the centre downsampling convention. The default isfalse.:interpolatedefines which resampling kernel to apply. The options are:nearest,:linear,:cubic,:mitchell,:lanczos2or:lanczos3(the default).:vertical_scaleis a float indicating the scaling factor of the vertical axis. In specified, thenscaleis applied only to the horizontal axis.
Returns
resized_imageorraises an exception
@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
imageis anyVix.Vips.Image.t/0or a pathname to an image file.lengthis 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 anx. The<height>may be omitted in which case it is the same as providing an integer length.optionsis a keyword list of options.
Options
:cropdetermines 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,:lowor:high. The default is:none. See alsoImage.Options.Crop.crop_focus/0.:height- Size to this height. Default is to maintain the image aspect ratio unlessresize: :forceis set. Ifresize; :forceis set then the default:heightis the height ofimage.:fitsets the:cropand:resizeoptions to align with the CSS object-fit property. Note that using the:fitoption overwrites the options:cropand:resize. Since options are processed in the order in which they are presented,:cropand:resizemay still be force set if they are after the:fitoption.:fittakes 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 settingresize: :force. Note that is:heightis not specified it will be the same height asimage.:contain- the image keeps its aspect ratio, but is resized to fit within the given dimension. This is the same as settingcrop: :noneandresize: :both.:cover- the image keeps its aspect ratio and fills the given dimensions. The image will be clipped to fit. Clipping will default to:centerunless:cropis already set to a value other than:none. This is the same as settingcrop: :center(if:cropis not already set) andresize: :both.
:autorotateis a boolean indicating if the image should be autorotated based upon the image metadata. The default istrue.:intentindicates the rendering intent. The default is:relative. See alsoImage.render_intent/0.:export_icc_profileindicates the icc profile to be attached to the resized image. The value may be an inbuilt profile (:srgb,:p3or: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_profileindicates the icc profile to be attached to the input image. The value may be an inbuilt profile (:srgb,:p3or: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.:linearis a boolean indicating of the image should be resized in linear space. The defaultfalse. 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.:resizedetermines 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,:bothor:force. The default is:both.
Returns
{:ok, thumbnailed_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0or a pathname to an image file.lengthis 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 anx. The<height>may be omitted in which case it is the same as providing an integer length.optionsis a keyword list of options. SeeImage.thumbnail/3.
Returns
imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:backgroundis 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:alphathen the image is trimmed to the size of the alpha mask.:thresholdis the integer threshold (or color similarity) that is applied when determining the bounds of the non-background area. The default is10. 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:uncroppedwhich means the image was considered to be only the background color.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:backgroundis 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:alphathen the image is trimmed to the size of the alpha mask.:thresholdis the integer threshold (or color similarity) that is applied when determining the bounds of the non-background area. The default is10. The default value means only a small color background color range is considered. Increasing the threshold value maybe required.
Returns
cropped_imagewhich is the image cropped to the bounding box of the non-background area orraises an exception.
Crop
@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
imageis anyVix.Vips.Image.t/0.widthis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifwidthis an integer it is the absolute number of pixels. Ifwidthis a float it is the fraction of the original image width.heightis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifheightis an integer it is the absolute number of pixels. Ifheightis a float it is the fraction of the original image height.
Notes
An error will be returned if
widthandheightare not equal to or smaller than theimagedimensions.This function is a convenience function equivalent to calling
Image.crop(image, :center, :middle, width, height).
Returns
{:ok, cropped_image}or{:error, reason}.
@spec center_crop!(Vix.Vips.Image.t(), pos_integer(), pos_integer()) :: Vix.Vips.Image.t() | no_return()
Crops the center from an image.
Arguments
imageis anyVix.Vips.Image.t/0.widthis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifwidthis an integer it is the absolute number of pixels. Ifwidthis a float it is the fraction of the original image width.heightis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifheightis an integer it is the absolute numberof pixels. If
heightis a float it is the fraction of the original image height.
Notes
An error will be returned if
widthandheightare not equal to or smaller than theimagedimensions.This function is a convenience function equivalent to calling
Image.crop!(image, :center, :middle, width, height).
Returns
cropped_imageorraises an exception.
@spec crop(Vix.Vips.Image.t(), quadrilateral()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Crop an image.
Arguments
imageis anyVix.Vips.Image.t/0.quadrilateralis 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}wherexis the 0-based offset from the left of the image andyis 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.
@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
imageis anyVix.Vips.Image.t/0.leftis the top edge of crop area as an integer or a float in the range-1.0..1.0. Ifleftis an integer it is the absolute number of pixels. Ifleftis a float it's a fraction of the width of the image. Ifleftis 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.leftmay also be one of:left,:centerand:rightindicating the crop is relative to the left, center or right of the image.topis the top edge of crop area as an integer or a float in the range-1.0..1.0. Iftopis an integer it is the absolute number of pixels. Iftopis a float it's a fraction of the height of the image. Iftopis 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.topmay also be one of:top,:middleand:bottomindicating the crop is relative to the top, middle or bottom of the image.widthis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifwidthis an integer it is the absolute number of pixels. Ifwidthis a float it's the fraction of the original image width.heightis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifheightis an integer it's the absolute number of pixels. Ifheightis a float it's the fraction of the original image height.
Notes
leftis 0-indexed. That is, the leftmost edge of the image starts at0.topis 0-indexed. That is, the topmost edge of the image starts at0.If the image has multiple pages, like an animated
.gifor.webpthen each page is extracted, cropped and then the image reassembled.
Returns
{:ok, cropped_image}or{:error, reason}
@spec crop!(Vix.Vips.Image.t(), quadrilateral()) :: Vix.Vips.Image.t() | no_return()
Crop an image or raises an exception.
Arguments
imageis anyVix.Vips.Image.t/0.quadrilateralis 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}wherexis the 0-based offset from the left of the image andyis the 0-based offset from the top of the image.
Returns
cropped_imageorraises an exception.
Note
The bounding box must be a rectangle, not an
arbitrary quadrilateral. If required, use Image.warp_perspective/4
prior to cropping.
@spec crop!(Vix.Vips.Image.t(), integer(), integer(), pos_integer(), pos_integer()) :: Vix.Vips.Image.t() | no_return()
Crop an image returning a cropped image or raising an exception.
Arguments
leftis the top edge of crop area as an integer or a float in the range-1.0..1.0. Ifleftis an integer it is the absolute number of pixels. Iflefta float is fraction of the width of the image. Ifleftis 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.leftmay also be one of:left,:centerand:rightindicating the crop is relative to the left, center or right of the image.topis the top edge of crop area as an integer or a float in the range-1.0..1.0. Iftopis an integer it is the absolute number of pixels. Iftopis a float is fraction of the height of the image. Iftopis 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.topmay also be one of:top,:middleand:bottomindicating the crop is relative to the top, middle or bottom of the image.widthis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifwidthis an integer it is the absolute number of pixels. Ifwidthis a float it is the fraction of the original image width.heightis the width of area remaining as a positive integer or float in the range0.0..1.0. Ifheightis an integer it is the absolute number of pixels. Ifheightis a float it is the fraction of the original image height.
Returns
cropped_imageorraises an exception.
Transforms
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options. The default is[shape: :circle, crop: :none, size: 180].
Options
:sizeis the diameter in pixels of the avatar (in the case ofshape: :circleorshape; :squircle. It is the width/height in pixels in the case of ashape: :squareavatar. The default value is180.:shapedefines shape of the avatar which can be either:circle(the default),:squircleor:square. In each case the image is first cropped to a square shape. Then if the format is:circleor:squirclean appropriate image mask is applied.:crop_focusis one of:center,:entropy,:attention,:low,:high. The default is:center. For details seeImage.Options.Crop.crop_focus/0.
Returns
{:ok, avatar_image}or{:error, reason}
@spec avatar!(Vix.Vips.Image.t(), options :: Image.Options.Avatar.avatar_options()) :: Vix.Vips.Image.t() | no_return()
Make a circular, squircular or square image intended to be used as an avatar image or raise an exception.
The image is resized and all metadata is removed
from the image. The image will be cropped to a square
shape and then depending on the :shape option
a circular or squirclar mask may be applied.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options. The default is[shape: :circle, crop: :none, size: 180].
Options
:sizeis the diameter in pixels of the avatar (in the case ofshape: :circleorshape; :squircle. It is the width/height in pixels in the case of ashape: :squareavatar. The default value is180.:shapedefines shape of the avatar which can be either:circle(the default),:squircleor:square. In each case the image is first cropped to a square shape. Then if the format is:circleor:squirclean appropriate image mask is applied.:crop_focusis one of:center,:entropy,:attention,:low,:high. The default is:center. For details seeImage.Options.Crop.crop_focus/0.
Returns
avatar_imageorraises 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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Arguments supplying a width and height
widthis the width in pixels of the gradient image.heightis the height in pixels of the gradient image.optionsis a keyword list of options. SeeImage.Options.LinearGradient.linear_gradient_option/0.
Options
:start_coloris an sRGB color which represents the starting color of the gradient. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color, or an atom representing a CSS color name. The default is:blackwith 100% transparency.:finish_coloris an sRGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:blackwith 100% opacity.:angleis a float or integer number of degrees of clockwise rotation applied to the gradient. The default is0.0. The number is normalized into the range0..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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Arguments supplying a width and height
widthis the width in pixels of the gradient image.heightis the height in pixels of the gradient image.optionsis a keyword list of options. SeeImage.Options.LinearGradient.linear_gradient_option/0.
Options
:start_coloris an sRGB color which represents the starting color of the gradient. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color, or an atom representing a CSS color name. The default is:blackwith 100% transparency.:finish_coloris an sRGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:blackwith 100% opacity.:angleis a float or integer number of degrees of clockwise rotation applied to the gradient. The default is0.0. The number is normalized into the range0..360.
Returns
gradient_imageorraises 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)@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
imageis anyVix.Vips.Image.t/0over which the meme text will be composed.headlineis the top line of the meme text.optionsis a keyword list of options.
Options
:textis the second line of text at the bottom of the meme image. The default is"".:text_sizeis the size of the bottom text in points. The default is calculated proportional to the size of the image.:headline_sizeis the size of the headline text in points. The default is calculated proportional to the size of the image.:fontis the name of the font family to be applied. The default isImpact.:font_fileis the path name to a font file that will be loaded. The default is:defaultwhich will load the includedImpactfont if the font family isImpact. If the font family is notImpactand the:font_fileis:defaultthen the font displayed is resolved by the underlying operating system. If:font_fileis a string, then it is expected to be a valid font file. If:font_fileis set to a path then the:fontoption should also be set to the correct font name.:weightis the font weight to be rendered. The options are:ultralight,:light,:normal,:bold,:ultrabold, and:heavy. The default:bold.:transformdetermines how the text is presented. The options are:upcase,:downcase,:capitalizeand:none. The default is:upcase.:coloris an RGB color of the text. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:white.:outline_coloris an RGB color of the text outline. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:black.:marginis 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.
@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
imageis anyVix.Vips.Image.t/0over which the meme text will be composed.headlineis the top line of the meme text.optionsis a keyword list of options.
Options
:textis the second line of text at the bottom of the meme image. The default is"".:text_sizeis the size of the bottom text in points. The default is calculated proportional to the size of the image.:headline_sizeis the size of the headline text in points. The default is calculated proportional to the size of the image.:fontis the name of the font family to be applied. The default isImpact. If the font family name is"Impact"then the includedunicode.impact.ttffont file will also be loaded. This ensures that theImpactfont is available on all systems.:font_fileis the path name to a font file that will be loaded. The default is:defaultwhich will load the includedImpactfont if the font family isImpact. If the font family is notImpactand the:font_fileis:defaultthen the font displayed is resolved by the underlying operating system. If:font_fileis a string, then it is expected to be a valid font file. If:font_fileis set to a path then the:fontoption should also be set to the correct font name.:weightis the font weight to be rendered. The options are:ultralight,:light,:normal,:bold,:ultrabold, and:heavy. The default:bold.:justifyis a boolean indicating if the headline and text are to be justified. Iftruethen space is added between words so that both edges of each line are aligned with both margins. The default isfalse.:transformdetermines how the text is presented. The options are:upcase,:downcase,:capitalizeand:none. The default is:upcase.:coloris an RGB color of the text. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:white.:outline_coloris an RGB color of the text outline. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:black.:marginis 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.
@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
widthis the width of the gradient in pixels.heightis the height of the gradient in pixels.optionsis a keyword list of options. Seet:Image.Options.RadialrGradient.radial_gradient_option/0.
Options
:start_coloris an sRGB color which represents the starting color of the gradient. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color, or an atom representing a CSS color name. The default is:blackwith 100% transparency.:finish_coloris an sRGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:blackwith 100% opacity.:featheris the slope of the gradient. That is, how quickly the gradient moves from the:start_colorcolor to the:finish_color. The valid range is1..10representing the smallest amount of feather (harshest transition) to the largest amount of feather (smoothest transition). The default is1.:radiusis the radius of the gradient in the range1..5where1fully fills the space and5fills a small section of the center of the space. The default is2.
Returns
{:ok, gradient_image}or{:error, reason}
@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
widthis the width of the gradient in pixels.heightis the height of the gradient in pixels.optionsis a keyword list of options. Seet:Image.Options.RadialrGradient.radial_gradient_option/0.
Options
:start_coloris an sRGB color which represents the starting color of the gradient. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color, or an atom representing a CSS color name. The default is:blackwith 100% transparency.:finish_coloris an sRGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-or-four-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:blackwith 100% opacity.:featheris the slope of the gradient. That is, how quickly the gradient moves from the:start_colorcolor to the:finish_color. The valid range is1..10representing the smallest amount of feather (harshest transition) to the largest amount of feather (smoothest transition). The default is1.:radiusis the radius of the gradient in the range1..5where1fully fills the space and5fills a small section of the center of the space. The default is2.
Returns
{:ok, gradient_image}or{:error, reason}
@spec rounded(Vix.Vips.Image.t(), Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Apply rounded corners to an image.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:radiusis the desired corner radius. The default is 50.
Returns
{:ok, rounded_corner_image}or{:error, reason}
@spec squircle(Vix.Vips.Image.t(), Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Apply squircle mask to an image.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:radiusis 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
imageis anyVix.Vips.Image.t/0.
Returns
- An integer in the range
1..4depending on the image interpretation. Returnsnilif there is no alpha band. The integer is a 0-based offset and can therefore be directly used to access the band. For exampleimage[alpha_band(image)].
@spec join_bands(image_list :: [Vix.Vips.Image.t()]) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Joins a list of bands into a single image.
This can be considered the inverse operation of
Image.split_bands/1.
Arguments
image_listis any list ofVix.Vips.Image.t/0.
Returns
{:ok, image}whereimageis created by joiningimage_bandstogether or{:error, reason}.
@spec join_bands!(image_list :: [Vix.Vips.Image.t()]) :: Vix.Vips.Image.t() | no_return()
Joins a list of bands into a single image or raises an exception.
This can be considered the inverse operation of
Image.split_bands/1.
Arguments
image_listis any list ofVix.Vips.Image.t/0.
Returns
an image created by joining
image_bandstogether orraises an exception.
@spec split_bands(Vix.Vips.Image.t()) :: [Vix.Vips.Image.t()]
Split the image into a list of its component bands.
This can be considered the inverse of
Image.join_bands/1.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
- a list of single band images extracted
from
image.
Color
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
With the exception of the option :replace_with, the
options for specifying the color or color range
to be replaced are passed to Image.chroma_mask/2.
:blendis a boolean indicating if a the replacement should blend at the border of the color replacement. The default isfalse.:replace_withis 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 alsoImage.Color.color_map/0andImage.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
:coloris an RGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be selected. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be selected. The color can be an integer between0..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}.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
With the exception of the option :replace_with, the
options for specifying the color or color range
to be replaced are passed to Image.chroma_mask/2.
:replace_withis 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 alsoImage.Color.color_map/0andImage.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
:coloris an RGB color which represents the the chroma key to be selected. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be selected. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be selected. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.
Returns
imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0colorspaceis any known colorspace. SeeImage.Interpretation.known_interpretations/0for a list of the known colorspaces.
Returns
{;ok, image_in_new_colorspace}or{:error, reason}
Example
Image.to_colorspace(image, :bw)@spec to_colorspace!(Vix.Vips.Image.t(), Image.Interpretation.t()) :: Vix.Vips.Image.t() | no_return()
Converts an image to the given colorspace returning an image or raising an exception.
Available colorspaces are returned from
Image.Interpretation.known_interpretations/0.
Arguments
imageis anyVix.Vips.Image.t/0colorspaceis any known colorspace. SeeImage.Interpretation.known_interpretations/0for a list of the known colorspaces.
Returns
image_in_new_colorspaceorraises an exception
Example
Image.to_colorspace!(image, :bw)Introspection
Returns the aspect of an image.
Arguments
imageis anyVix.Vips.Image.t/0optionsis a keyword list of options
Options
:square_ratioindicates 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 is0.0meaning that the dimensions must be exactly equal in order for the image to be considered square.
Returns
- Either
:landscape,:portraitor:square.
Example
iex> puppy = Image.open!(Path.expand("test/support/images/puppy.webp"))
iex> Image.aspect(puppy, square_ratio: 0.05)
:landscape@spec band_format(image :: Vix.Vips.Image.t()) :: Image.BandFormat.t()
Returns the band format of an image.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
- The band format of the image in
Nxnotation.
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
imageis anyVix.Vips.Image.t/0.
Returns
- An integer number of bands in the image.
@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
imageis anyVix.Vips.Image.t/0.
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@spec dominant_color(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: {:ok, Image.Color.rgb_color() | [Image.Color.rgb_color()]} | {:error, error_message()}
Returns the dominant sRGB color of an image.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:binsis an integer number of color frequency bins the image is divided into. The default is16.:top_nreturns the topnmost dominant colors in the image. The default is1.
Returns
{:ok, [r, g, b]}or{:error, reason}
Notes
imagewill be converted to the:srgbcolorspace 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, [8, 8, 24]}
iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
iex> Image.dominant_color(image)
{:ok, [88, 88, 88]}@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:binsis an integer number of color frequency bins the image is divided into. The default is16.:top_nreturns the topnmost dominant colors in the image. The default is1.
Returns
{:ok, [r, g, b]}orraises an exception.
Notes
imagewill be converted to the:srgbcolorspace and the dominant color will be returned as an sRGB list.
Example
iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> Image.dominant_color!(image)
[8, 8, 24]
iex> image = Image.open!("./test/support/images/image_with_alpha2.png")
iex> Image.dominant_color!(image)
[88, 88, 88]@spec filename(image :: Vix.Vips.Image.t()) :: Path.t() | nil
Returns the filename for an image.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
- The pathname from which the image was opened or
nilif 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
imageis anyVix.Vips.Image.t/0.
Returns
trueorfalse
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
imageis anyVix.Vips.Image.t/0.
Returns
- The image height as an integer.
@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
imageis anyVix.Vips.Image.t/0.
Returns
integernumber of pages in theimage.
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@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
imageis anyVix.Vips.Image.t/0.
Returns
{min_value, max_value}wheremin_valueandmax_valueare 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}@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
imageis anyVix.Vips.Image.t/0.
Returns
- The image shape as a tuple of
{width, height, bands}.
Example
iex> image = Image.open!("./test/support/images/Kamchatka-2019-8754.jpg")
iex> Image.shape(image)
{1000,542, 3}@spec width(image :: Vix.Vips.Image.t()) :: pos_integer()
Returns the width of an image.
Arguments
imageis anyVix.Vips.Image.t/0.
Returns
- The image width as an integer.
Histogram
@spec logistic_curve_rhs(k :: float()) :: Vix.Vips.Image.t()
Returns a single band image representing the right hand side (positive range) of the logistic function.
Arguments
kis a float in the range-1.0to1.0representing the logistic growth rate (slope of the curve).
Returns
- A single band
t:Vimage.t/0representing the right hand side (positive numbers) of the logistic curve.
Notes
- This is not a general purpose curve generator. It is used by
Image.vibrance/3and may, in the future, be developed into a more general purpose logistic curve function.
Clusters
@spec histogram(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Returns the histogram for an image.
The histogram is returned as a t:Vimage.t/0
that is a 255 by 255 image with the same numbers of
bands as the source image.
Argument
imageis anyVix.Vips.Image.t/0.
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.
@spec k_means(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: {:ok, [Image.Color.t()]} | {:error, error_message()}
Applies K-means clustering to an image using the scholar library. The returned result is a list of colors resulting from partioning the colors in an image.
This function is only available if Scholar is configured.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
- See
Scholar.Cluster.KMeans.fit/2for the available options.
Returns
{:ok, list_of_colors}or{:error, reason}
Notes
The current implementation is performed in the sRGB colorspace. This may not produce the most perceptually appropriate clusters. This limitation will be removed in a future release.
The option
:num_clustersdetermines the number of clusters into which image colors are partioned. The default isnum_clusters: 16.The default options mean that the results are not deterministic. Different calls to
Image.k_means/2can return different - but equally valid - results. Use the:keyoption to return deterministic results.Performance is very correlated with image size. Where possible, resize the image to be under a 1_000_000 pixels or even less before invoking
Image.k_means/2.Performance is primarily determined by the vector performance of the system and specifically by the GPU configuration and EXLAs support of that GPU. In most cases it is recommended that the following be added to
config.exs:
config :nx,
default_backend: EXLA.Backend
config :nx, :default_defn_options,
compiler: EXLAExample
iex> key = Nx.Random.key(40)
iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> Image.k_means(image, key: key)
{:ok,
[
[32, 37, 39],
[34, 76, 101],
[41, 121, 158],
[42, 189, 58],
[93, 61, 32],
[99, 87, 90],
[112, 156, 184],
[115, 112, 140],
[157, 100, 37],
[166, 125, 103],
[175, 191, 206],
[178, 148, 158],
[217, 145, 60],
[228, 170, 116],
[228, 226, 226],
[231, 200, 167]
]}@spec k_means!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: [Image.Color.t()] | no_return()
Applies K-means clustering to an image using the scholar library. The returned result is a list of colors resulting from partioning the colors in an image.
This function is only available if Scholar is configured.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
- See
Scholar.Cluster.KMeans.fit/2for the available options.
Returns
{:ok, list_of_colors}or{:error, reason}
Notes
The current implementation is targetted towards sRGB images Results for images in other colorspaces is undefined. It is planned this limitation be removed in a future release.
The option
:num_clustersdetermines the number of clusters into which image colors are partioned. The default isnum_clusters: 16.The default options mean that the results are not deterministic. Different calls to
Image.k_means/2can return different - but equally valid - results. Use the:keyoption to return deterministic results.Performance is very correlated with image size. Where possible, resize the image to be under a 1_000_000 pixels or even less before invoking
Image.k_means/2.Performance is primarily determined by the vector performance of the system and specifically by the GPU configuration and EXLAs support of that GPU. In most cases it is recommended that the following be added to
config.exs:
config :nx,
default_backend: EXLA.Backend
config :nx, :default_defn_options,
compiler: EXLAExample
iex> key = Nx.Random.key(40)
iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> Image.k_means!(image, key: key)
[
[32, 37, 39],
[34, 76, 101],
[41, 121, 158],
[42, 189, 58],
[93, 61, 32],
[99, 87, 90],
[112, 156, 184],
[115, 112, 140],
[157, 100, 37],
[166, 125, 103],
[175, 191, 206],
[178, 148, 158],
[217, 145, 60],
[228, 170, 116],
[228, 226, 226],
[231, 200, 167]
]Reduces the number of colors in an image.
Takes the k_means/2 of the image and then
re-colors the image using the returned cluster
colors.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:colorsis the number of distinct colors to be used in the returned image. The default is16.See also
Scholar.Cluster.KMeans.fit/2for the available options.
Note
Note the performance considerations described in
Image.k_means/2since they also apply to this function.If the intent is to reduce colors in order to reduce the size of an image file it is strongly advised to use the appropriate arguments when calling
Image.write/2.
Returns
{:ok, reduced_colors_image}or{:error, reason}
Reduces the number of colors in an image or raises an exception.
Takes the k_means/2 of the image and then
re-colors the image using the returned cluster
colors.
Arguments
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:colorsis the number of distinct colors to be used in the returned image. The default is16.See also
Scholar.Cluster.KMeans.fit/2for the available options.
Note
Note the performance considerations described in
Image.k_means/2since they also apply to this function.If the intent is to reduce colors in order to reduce the size of an image file it is strongly advised to use the appropriate arguments when calling
Image.write/2.
Returns
reduced_colors_imageorraises an exception.
Color Difference
Returns the color difference between two colors calculated using the CIE ΔE* algorithms.
The available difference algorithms are:
Arguments
color_1which can be specified as a single integer or a list of integers representing the color. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. Lastly, the color can be supplied as a hex string like#ffe4e1. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.color_2which is specified in the same manner ascolor_1.versionis one of:de00(the default),:decmcor:de76.
Returns
{:ok, int_distance}whereint_distanceis0when the colors are identical and100when they are completely different.{:error, reason}.
Examples
iex> Image.delta_e([0,0,0], [0,0,0])
{:ok, 0.0}
iex> Image.delta_e([0,0,0], [255,255,255])
{:ok, 100.0}
iex> Image.delta_e([0,0,0], :misty_rose)
{:ok, 90.15503692626953}
iex> Image.delta_e(:green, :misty_rose)
{:ok, 52.937347412109375}
iex> Image.delta_e(:green, :misty_rose, :de76)
{:ok, 88.5516128540039}Returns the color difference between two colors calculated using the CIE ΔE* algorithms or raises an exception.
The available difference algorithms are:
Arguments
color_1which can be specified as a single integer or a list of integers representing the color. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. Lastly, the color can be supplied as a hex string like#ffe4e1. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.color_2which is specified in the same manner ascolor_1.versionis one of:de00(the default),:decmcor:de76.
Returns
{:ok, int_distance}whereint_distanceis0when the colors are identical and100when they are completely different.{:error, reason}.
Examples
iex> Image.delta_e!([0,0,0], [0,0,0])
0.0
iex> Image.delta_e!([0,0,0], [255,255,255])
100.0
iex> Image.delta_e!([0,0,0], :misty_rose)
90.15503692626953
iex> Image.delta_e!(:green, :misty_rose)
52.937347412109375
iex> Image.delta_e!(:green, :misty_rose, :de76)
88.5516128540039Masks
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
There are two masking strategies available: the thresholding strategy (default) and the color range strategy.
Threshold strategy
:coloris an RGB color which represents the the chroma key to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
There are two masking strategies available: the thresholding strategy (default) and the color range strategy.
Threshold strategy
:coloris an RGB color which represents the the chroma key to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name. The default is:autoin which the average of the top left10x10pixels of the image is used.:thresholdis a positive integer to indicate the threshold around:colorwhen calculating the mask. The default is20.
Color range strategy
:greater_thanis an RGB color which represents the upper end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.:less_thanis an RGB color which represents the lower end of the color range to be masked. The color can be an integer between0..255, a three-element list of integers representing an RGB color or an atom representing a CSS color name.
@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
imageis anyVix.Vips.Image.t/0.
Returns
{:ok, circular_image}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.
Returns
circular_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.
Returns
{:ok, mask}or{:error, reason}
@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
imageis anyVix.Vips.Image.t/0.
Returns
maskimage orraises an exception
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:radiusis the desired corner radius. The default is 50.
Returns
rounded_corner_imageorraises an exception.
@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
imageis anyVix.Vips.Image.t/0.optionsis a keyword list of options.
Options
:radiusis the desired squircle radius. The default is 20.
Returns
squircle_imageorraises an exception.
Metadata
Nx & Evision
Converts to an Image image from an Evision.Mat.t/0 image.
Arguments
evision_imageis anyEvision.Mat.t/0image.
Returns
{:ok, image}
Notes
Imageimages have the shape{width, height, bands}whereasEvisionimages have the shape{height, width, bands}so this function transposes the dimensions to match.Imagedata is arranged asrgbdata elements whereasEvisionrequires the data to be inbgrorder. This function also reorders the data appropriately.
@spec from_nx(tensor :: Nx.Tensor.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Converts an Nx tensor into an image.
Arguments
tensoris any three dimensionalNx.Tensor.t/0.optionsis a keyword list of options. For valid options seeNx.from_binary/2.
Returns
{:ok, image}or{:error, reason}
Notes
In order to convert a tensor into an image it must satisfy these constraints:
It must have three dimensions.
It must have a tensor type that is compatible with
libvips(most tensors will satisfy this requirement other than tensors whose type is complex).The names of the axes must be
[:width, :height, any_other]or[:height, :width, any_other].
Example
iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
iex> {:ok, tensor} = Image.to_nx(image)
iex> {:ok, _image_2} = Image.from_nx(tensor)@spec from_nx!(tensor :: Nx.Tensor.t()) :: Vix.Vips.Image.t() | no_return()
Converts an Nx tensor into an image or raises an exception.
Arguments
tensoris any three dimensionalNx.Tensor.t/0.optionsis a keyword list of options. For valid options seeNx.from_binary/2.
Returns
imageor{:error, reason}
Notes
In order to convert a tensor into an image it must satisfy these constraints:
It must have three dimensions.
It must have a tensor type that is compatible with
libvips(most tensors will satisfy this requirement other than tensors whose type is complex).The names of the axes must be
[:width, :height, any_other]or[:height, :width, any_other].
Example
iex> {:ok, image} = Vix.Vips.Operation.black(3, 3)
iex> {:ok, tensor} = Image.to_nx(image)
iex> _image_2 = Image.from_nx(tensor)Converts an Image image to an Evision.Mat.t/0 image.
Note that only images with 3 bands can be transferred
to eVision.
Arguments
imageis anyt:Vimage.t/0.convert_to_bgris a boolean indicating if the color order should be converted fromRGBtoBGRwhich is the normal channel layout for OpenCV. The default istrue.
Returns
{:ok, evision_image}{:error, reason}
Notes
Imageimages have the shape{width, height, bands}whereasEvisionimages have the shape{height, width, bands}so this function transposes the dimensions to match.Imagedata is arranged asrgbdata elements whereasEvisionrequires the data to be inbgrorder. This function also reorders the data appropriately.
@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
imageis anyt:Vimage.t/0optionsis a keyword list of options
Options
:shapedetermines how the tensor is shaped. The valid values are::hwbor:hwcwhich leaves the tensor unchanged with the underlying data in{height, width, bands}shape. This is the default action.:whcor:whbwhich reshapes the tensor towidth, height, bands.
Returns
{:ok, tensor)where tensor is anNx.Tensor.t/0tensor suitable for use in theNxlibrary or{:error, reason}.
Note
- The image type,
Vix.Vips.Image.t/0stores data in{width, height, band}format. However when the data is conerted into anNx.Tensor.t/0the 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)}@spec to_nx!(image :: Vix.Vips.Image.t(), options :: Keyword.t()) :: Nx.Tensor.t() | no_return()
Converts an image into an Nx tensor.
Arguments
imageis anyt:Vimage.t/0optionsis a keyword list of options
Options
:shapedetermines how the tensor is shaped. The valid values are::hwbor:hwcwhich leaves the tensor unchanged with the underlying data in{height, width, bands}shape. This is the default action.:whcor:whbwhich reshapes the tensor towidth, height, bands.
Returns
tensorwhere tensor is anNx.Tensor.t/0tensor suitable for use in theNxlibrary orraises an exception.
Note
- The image type,
Vix.Vips.Image.t/0stores data in{width, height, band}format. However when the data is conerted into anNx.Tensor.t/0the 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
imageis anyVix.Vips.Image.t/0.
Notes
The function
Image.p/1is delegated to this function.The maximum width of the preview can be set by the environment variable
IMAGE_PREVIEW_MAX_WIDTH. The default is1_000pixels 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.exsfile:# .iex.exs import_if_available(Image, only: [p: 1])
@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
imageis anyVix.Vips.Image.t/0or a tuple of the form{:ok, image}.
Returns
- The
imageparameter as provided with the side effect of emitting an image preview on an iTerm terminal.
Notes
The function
Image.p/1is delegated to this function.The maximum width of the preview can be set by the environment variable
IMAGE_PREVIEW_MAX_WIDTH. The default is1_000pixels 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.exsfile:# .iex.exs import_if_available(Image, only: [preview: 1])
Kino
Transfers an image to Kino for display in a livebook.
Arguments
imageis anyt:Vimage.t/0.
Returns
- a Kino image struct.
Example
iex> image = Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
iex> %Kino.Image{} = Image.to_kino(image)
iex> match?(%Kino.Image{}, Image.to_kino(image))
trueGuards
Guards whether the coordinates can be reasonably interpreted as a bounding box.
left and top when positive are relative to
the left and top of the image respectively. When
negative they are relative to the right and bottom
of the image.
Guards whether a 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),
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.
@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
concurrencyis a positive integer denoting the maximum number of threads thatlibvipswill 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() :: %{ file_ref: 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.
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:
RGBcolorspace would be represented by a list of three floats like[0.0, 0,0, 0.0]for black.CMYKcolorspace would be represented by a list of four floats.A
PNGimage can be in any appropriate colorspace but may also have analphaband 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
@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
imageis anyVix.Vips.Image.t/0.
Returns
- A list of average pixel values which can be interpreted as the average color of the image.
Example
iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
...> |> Image.average()
[66, 86, 106]@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
imageis anyVix.Vips.Image.t/0.
Returns
- A list of average pixel values which can be interpreted as the average color of the image.
Example
iex> Image.open!("./test/support/images/Hong-Kong-2015-07-1998.jpg")
...> |> Image.average!()
[66, 86, 106]@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
imageis a a map returned fromKino.Input.read(image)via aKino.Input.image/1input field. The data will have the following fields::file_refwhich contains a file reference to the image. It can be extraced into a path withKino.Input.file_path/1:widthwhich is the width of the image in pixels:heightwhich is the height of the image in pixels:formatwhich is the image band format which must be:rgb.
optionsis a keyword list of options.
Options
:bandsindicates the integer number of bands (channels) in the image. The default is3.
Notes
Thus function requries Kino v0.11.0 which in turn requires Livebook v0.11.0.
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}
@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
imageis a a map returned fromKino.Input.read(image)via aKino.Input.image/1input field. The data will have the following fields::file_refwhich contains a file reference to the image. It can be extraced into a path withKino.Input.file_path/1:widthwhich is the width of the image in pixels:heightwhich is the height of the image in pixels:formatwhich is the image band format which must be:rgb
optionsis a keyword list of options
Options
:bandsindicates the integer number of bands (channels) in the image. The default is3.
Notes
Thus function requries Kino v0.11.0 which in turn requires Livebook v0.11.0.
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}orraises an exception.
Guards whether the given struct is an image type
either Vix.Vips.Image or Vix.Vips.MutableImage.
@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_listis a non-empty list oft:Vimage.t/0images.optionsis a keyword list of options.
Options
:acrossis an integer number of images in the horizontal direction of the grid. The default is1.:vertical_spacingdetermines the height in pixels of each image row. The default,0, means that the row height is the maximum height of the images inimage_list.:horizontal_spacingdetermines the width in pixels of each image in a row. The default,0, means that the width is the maximum width of the images inimage_list.:vertical_alignis:bottom,:middleor:top. The default is:bottom.:horizontal_alignis:left,:centeror:right. The default is:left.:background_coloris 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.:shimis the number of pixels of spacing between images in the grid. The default is0.
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.
@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_listis a non-empty list oft:Vimage.t/0images.optionsis a keyword list of options.
Options
:acrossis an integer number of images in the horizontal direction of the grid. The default is1.:vertical_spacingdetermines the height in pixels of each image row. The default,0, means that the row height is the maximum height of the images inimage_list.:horizontal_spacingdetermines the width in pixels of each image in a row. The default,0, means that the width is the maximum width of the images inimage_list.:vertical_alignis:bottom,:middleor:top. The default is:bottom.:horizontal_alignis:left,:centeror:right. The default is:left.:background_coloris 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 is0, meaning black. The color can also be supplied as a CSS color name as a string or atom. For example::misty_rose. SeeImage.Color.color_map/0andImage.Color.rgb_color/1.:shimis the number of pixels of spacing between images in the grid. The default is0.
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.
@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()}
@spec linear_gradient( width :: pos_integer(), height :: pos_integer(), options :: Keyword.t() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec linear_gradient!(Vix.Vips.Image.t(), options :: Keyword.t()) :: Vix.Vips.Image.t() | no_return()