View Source Image (image v0.2.0)
Image
is based upon the fabulous
vix library that provides a libvips
wrapper for Elixir.
Image
is intended to provide well-documented common image processing functions in
an idiomatic Elixir functional style as a layer above the very comprehensive set
of functions in Vix
and libvips
.
In a very simple image resizing
benchmark,
Image
is approximately 2 to 3 times faster than Mogrify
and uses about 5 times
less memory.
Link to this section Summary
Types
A composition is a 2-tuple defining an image and the options which describe how to compose this image on a base image.
When composing an image on a base image, these options drive how the composition proceeds.
Error messages returned by libvips
Image orientation.
A pixel is represented as a list of float values. The number of list elements is determined by the colorspace interpreations. For example
The valid rendering intent values. For all
functions that take an optioanl intent
parameter the default is :perceptual
.
Functions
Returns the band number of the alpha channel of an image, or nil if it doesn't have one.
Rotate an image based upon the orientation information in an image's EXIF data. Returns a potentially rotated image or raises and exception.
Rotate an image based upon the orientation information in an image's EXIF data.
Make a circular image intended to be used as an avatar image returning an image or raising an exception.
Make a circular image intended to be used as an avatar image.
Return the number of bands in an image.
Apply a circular mask to an image returning an image or raising an exception.
Apply a circular mask to an image.
Compse two images together to form a new image or raising an exception.
Compse two images together to form a new image.
Convert an image into a mask returning an image or raising an exception.
Convert an image into a mask.
Crop an image returning a cropped image or raising an exception.
Crop an image.
Returns the dominant color of an image as an RBG triplet value in an integer list.
Returns the EXIF data for an image as a map.
Returns the fast fourier transform (fft) of the given image returning an image or raising an exception.
Returns the fast fourier transform (fft) of the given image.
Returns the filename for an image.
Flip an image horizontally or vertically returning a flipped image or raising an exception.
Flip an image horizontally or vertically.
Returns the number of operating system
threads available for use by libvips
.
Returns a boolean based upon whether a given image has an alpha band.
Returns the height of an image.
Guards whether the coordinates can be reasonably interpreted as a bounding box.
Guards whether a term might be reasonable interpreted as an image pixel.
Guards whether a number can be reasonable interpreted as a size (as in size of a crop or mask)
Create an image gradient of the same size as the given image. Returns the gradient image or raises and exception.
Create an image gradient of the same size as the given image.
Minimize metadata by keeping only the artist and copyright (if available).
Minimize metadata by keeping only the artist and copyright (if available).
Opens an image file for image processing returning an image or raising an exception.
Opens an image file for image processing.
Returns the orientation of an image.
Sets the number of available threads for use
by libvips
.
Remove metadata from an image returning an image or raising an exception.
Remove metadata from an image returning an updated image or raising an exception.
Resize an image to fit or fill a bounding box returning an image or raising an exception.
Resize an image to fit or fill a bounding box.
Adds a concentric ripple effect to an image returning an image or raising an exception.
Adds a concentric ripple effect to an image.
Rotate an image clockwise (to the right) by a number of degrees.
Rotate an image clockwise (to the right) by a number of degrees.
Apply rounded corners to an image. Returns an image or raises an exception.
Apply rounded corners to an image.
Attempts top determine the distance from the perpendicular for a given image.
Converts an impage to the given colorspace returning an image or raising an exception.
Converts an impage to the given colorspace.
Convert image to polar coordinates returning an image or raising an exception.
Convert image to polar coordinates.
Convert image to rectangular coordinates returning an image or raising an exception.
Convert image to rectangular coordinates.
Returns the version of libvips
in
operation.
Returns the width of an image.
Writes an image to a file returning the image or raising an exception.
Write an image to a file.
Returns the XMP data for an image as a keyword list.
Link to this section Types
@type composition() :: {Vix.Vips.Image.t(), composition_options()}
A composition is a 2-tuple defining an image and the options which describe how to compose this image on a base image.
@type composition_options() :: [ x: non_neg_integer() | nil | :left | :center | :right, y: non_neg_integer() | nil | :top | :middle | :bottom, dx: integer(), dy: integer(), blend_mode: Image.BlendMode.t(), x_baseline: nil | :left | :center | :right, y_baseline: nil | :top | :middle | :bottom ]
When composing an image on a base image, these options drive how the composition proceeds.
:x
describes the absolutex
offset on the base image where this image will be placed. If this option is set to:left
,:center
or:right
then thex
position will be calculated relative to the base image. If:x
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dx
.:y
describes the absolutey
offset on the base image where this image will be placed. If this option is set to:top
,:middle
or:bottom
then they
position will be calculated relative to the base image. If:y
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dy
.:dx
descibes the relative offset used to calculate thex
value.:dx
is an integer offset from the edge of the previously composed image. Which edge is determined by the:x_baseline
option. If:x
is also specified then:x
is first calculated, then:dx
is added to it. In this case,:x_baseline
is ignored.:dy
descibes the relative offset used to calculate they
value.:dy
is an integer offset from the edge of the previously composed image. Which edge is determined by the:y_baseline
option. If:y
is also specified then:y
is first calculated, then:dy
is added to it. In this case,:x_baseline
is ignored.:blend_mode
is theImage.BlendMode.t/0
used when composing this image over its base image. The default is:over
which is appropriate for most use cases.:x_baseline
establishes the baseline on the previsouly composed image from which:dx
is calculated. The default is:right
.:y_baseline
establishes the baseline on the previsouly composed image from which:dy
is calculated. The default is:bottom
.
@type error_message() :: term()
Error messages returned by libvips
Typically a string.
@type orientation() :: :landscape | :portrait | :square
Image orientation.
@type pixel() :: [float()]
A pixel is represented as a list of float values. The number of list elements is determined by the colorspace interpreations. For example:
RGB
colorspace would be represented by a list of three floats like[0.0, 0,0, 0.0]
for black.CMYK
colorspace would be represented by a list of four floats.A
PNG
image can be in any appropriate colorspace but may also have analpha
band and therefore have three, four or five floats in a list to represent the pixel.
@type render_intent() :: :perceptual | :relative | :saturation | :absolute
The valid rendering intent values. For all
functions that take an optioanl intent
parameter the default is :perceptual
.
perceptual-intent
Perceptual Intent
Perceptual rendering is used to process photographic type images. This intent processes the colors so that the output reproduction is pleasing. This process tends to change the color from the original, so no guarantee the reproduction will be accurate against the original.
relative-intent
Relative Intent
Relative colorimetric changes all the colours out of gamut to the nearest colour in gamut, so many colours change to the same one. It DOES NOT change colours in gamut. Perceptual changes ALL the colours in the image in a proportional way so that they lie in the output device gamut.
saturation-intent
Saturation Intent
Saturation moves in-gamut colors toward the edge of the destination gamut for maximum saturation and impact. This intent will make an image more colorful by using the full gamut of the destination device. This intent cares not for the genuine representation of color.
absolute-intent
Absolute Intent
Absolute rendering attempts to reproduce all colors numerically (destination = source). This can cause unexpected results if the source gamut is larger than the destination.
Link to this section Functions
@spec alpha_band(Vix.Vips.Image.t()) :: 1..4 | nil
Returns the band number of the alpha channel of an image, or nil if it doesn't have one.
The determination is a heuristic so certainty cannot be guaranteed.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
- An integer in the range
1..4
depending on the image interpretation. Returnsnil
if there is no alpha band.
@spec autorotate!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Rotate an image based upon the orientation information in an image's EXIF data. Returns a potentially rotated image or raises and exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
auto_rotated_image
orraises an exception.
@spec autorotate(image :: Vix.Vips.Image.t()) :: {:ok, {Vix.Vips.Image.t(), Keyword.t()}} | {:error, error_message()}
Rotate an image based upon the orientation information in an image's EXIF data.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
{:ok, {auto_rotated_image, flags}}
or{:error, reason}
flags
Flags
Two flags are returned indicating what action was taken:
:flip
which is a boolean indicating if the image was flipped or not and:angle
through which the image was rotated. This value will be one of0
,90
,180
or270
representing the degrees of rotation.
@spec avatar!( Vix.Vips.Image.t(), size :: pos_integer(), options :: Image.Options.Avatar.avatar_options() ) :: Vix.Vips.Image.t() | no_return()
Make a circular image intended to be used as an avatar image returning an image or raising an exception.
The image is resized, a circular mask is applied and all metadata is removed from the image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.size
is the diameter of the resulting image after resizing. The default value is180
.options
is a keyword list of options. SeeImage.resize/3
for the valid options.
returns
Returns
avatar_image
orraises an exception.
@spec avatar( Vix.Vips.Image.t(), size :: pos_integer(), options :: Image.Options.Avatar.avatar_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Make a circular image intended to be used as an avatar image.
The image is resized, a circular mask is applied and all metadata is removed from the image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.size
is the diameter of the resulting image after resizing. The default value is180
.options
is a keyword list of options. SeeImage.resize/3
for the valid options.
returns
Returns
{:ok, avatar_image}
or{:error, reason}
@spec bands(Vix.Vips.Image.t()) :: integer()
Return the number of bands in an image.
A band is sometimes referred to as a channel.
Note than bands are 0-indexed. That is, the first band is band 0, the second band is band 1 and so on.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
- An integer number of bands in the image.
@spec circle!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
Apply a circular mask to an image returning an image or raising an exception.
The returned image has an alpha band masking the circular image.
As a result, it is best saved to a
format, like .png
that supports
alpha transparency.
Note that .jpg
files do not support
alpha transparency.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
circular_image
orraises an exception.
@spec circle(Vix.Vips.Image.t(), Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Apply a circular mask to an image.
The returned image has an alpha band masking the circular image.
As a result, it is best saved to a
format, like .png
that supports
alpha transparency.
Note that .jpg
files do not support
alpha transparency.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
{:ok, circular_image}
or{:error, reason}
@spec compose!( base_image :: Vix.Vips.Image.t(), overlay_image :: Vix.Vips.Image.t(), options :: Keyword.t() ) :: Vix.Vips.Image.t() | no_return()
@spec compose!( base_image :: Vix.Vips.Image.t(), image_list :: [Vix.Vips.Image.t(), ...], options :: Keyword.t() ) :: Vix.Vips.Image.t() | no_return()
Compse two images together to form a new image or raising an exception.
arguments
Arguments
base_image
is anyVix.Vips.Image.t/0
.overlay_image
is anyVix.Vips.Image.t/0
that will be composed over the top ofbase_image
.options
is a keyword list of options.
options
Options
:blend_mode
is the manner in which the two images are composited. Seet:Image.BkendMode.t/0
. The default is:over
which is the most common blend mode.:x
is the offset (0-based) from the left of thebase_image
where theoverlay_image
will be placed. It may also be one of the keywords:left
,:right
or:center
. The default is:center
.:y
is the offset (0-based) from the top of thebase_image
where theoverlay_image
will be placed. It may also be one of the keywords:top
,:bottom
or:middle
. The default is:middle
.
composition-list-options
Composition list options
When overlay_image
is an image_list
, each entry in
the list is either a Vix.Vips.Image.t/0
or a
composition/0
. A composition supports the specification
of how a particular image is composed onto the base image.
:x
describes the absolutex
offset on the base image where this image will be placed. If this option is set to:left
,:center
or:right
then thex
position will be calculated relative to the base image. If:x
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dx
.:y
describes the absolutey
offset on the base image where this image will be placed. If this option is set to:top
,:middle
or:bottom
then they
position will be calculated relative to the base image. If:y
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dy
.:dx
descibes the relative offset used to calculate thex
value.:dx
is an integer offset from the edge of the previously composed image. Which edge is determined by the:x_baseline
option. If:x
is also specified then:x
is first calculated, then:dx
is added to it. In this case,:x_baseline
is ignored.:dy
descibes the relative offset used to calculate they
value.:dy
is an integer offset from the edge of the previously composed image. Which edge is determined by the:y_baseline
option. If:y
is also specified then:y
is first calculated, then:dy
is added to it. In this case,:x_baseline
is ignored.:blend_mode
is theImage.BlendMode.t/0
used when composing this image over its base image. The default is:over
which is appropriate for most use cases.:x_baseline
establishes the baseline on the previsouly composed image from which:dx
is calculated. The default is:right
.:y_baseline
establishes the baseline on the previsouly composed image from which:dy
is calculated. The default is:bottom
.
returns
Returns
composed_image
orraises an exception
examples
Examples
# Compose images over a base image using
# absolute coordinates from the base image
# to place each overlay image
#==> base_image
...> |> Image.compose!(polygon, x: :middle, y: :top)
...> |> Image.compose!(explore_new, x: 260, y: 200)
...> |> Image.compose!(places, x: 260, y: 260)
...> |> Image.compose!(blowout, x: 260, y: 340)
...> |> Image.compose!(start_saving, x: 260, y: 400)
# Compose images over a base image
# using a composition list and coordinates
# that are either absolute with respect to the
# base image or relative to the previously
# composed image
#==> base_image
...> |> Image.compose!([
...> {polygon, x: :center, y: :top},
...> {explore_new, y_baseline: :top, x_baseline: :left, dx: 20, dy: 200},
...> {places, dy: 10},
...> {blowout, dy: 20},
...> {start_saving, dy: 50}
...> ])
@spec compose( base_image :: Vix.Vips.Image.t(), overlay_image :: Vix.Vips.Image.t(), options :: Keyword.t() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec compose( base_image :: Vix.Vips.Image.t(), image_list :: [Vix.Vips.Image.t(), ...], options :: Keyword.t() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Compse two images together to form a new image.
arguments
Arguments
base_image
is anyVix.Vips.Image.t/0
.overlay_image
is anyVix.Vips.Image.t/0
that will be composed over the top ofbase_image
. It can also be a list ofcomposition/0
s that allow for multiple images to be composed in a single call.options
is a keyword list of options.
options-for-a-single-overlay-image
Options for a single overlay image
:blend_mode
is the manner in which the two images are composited. Seet:Image.BkendMode.t/0
. The default is:over
which is the most common blend mode.:x
is the offset (0-based) from the left of thebase_image
where theoverlay_image
will be placed. It may also be one of the keywords:left
,:right
or:center
. The default is:center
.:y
is the offset (0-based) from the top of thebase_image
where theoverlay_image
will be placed. It may also be one of the keywords:top
,:bottom
or:middle
. The default is:middle
.
composition-list-options
Composition list options
When overlay_image
is an image_list
, each entry in
the list is either a Vix.Vips.Image.t/0
or a
composition/0
. A composition supports the specification
of how a particular image is composed onto the base image.
:x
describes the absolutex
offset on the base image where this image will be placed. If this option is set to:left
,:center
or:right
then thex
position will be calculated relative to the base image. If:x
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dx
.:y
describes the absolutey
offset on the base image where this image will be placed. If this option is set to:top
,:middle
or:bottom
then they
position will be calculated relative to the base image. If:y
is nil (the default) then the image will be placed according to the relative offset of the previously composed image using:dy
.:dx
descibes the relative offset used to calculate thex
value.:dx
is an integer offset from the edge of the previously composed image. Which edge is determined by the:x_baseline
option. If:x
is also specified then:x
is first calculated, then:dx
is added to it. In this case,:x_baseline
is ignored.:dy
descibes the relative offset used to calculate they
value.:dy
is an integer offset from the edge of the previously composed image. Which edge is determined by the:y_baseline
option. If:y
is also specified then:y
is first calculated, then:dy
is added to it. In this case,:x_baseline
is ignored.:blend_mode
is theImage.BlendMode.t/0
used when composing this image over its base image. The default is:over
which is appropriate for most use cases.:x_baseline
establishes the baseline on the previsouly composed image from which:dx
is calculated. The default is:right
.:y_baseline
establishes the baseline on the previsouly composed image from which:dy
is calculated. The default is:bottom
.
returns
Returns
{:ok, composed_image}
or{:error, reason}
examples
Examples
# Compose images over a base image using
# absolute coordinates from the base image
# to place each overlay image
#==> {:ok, image} = Image.compose(base_image, polygon, x: :middle, y: :top)
#==> {:ok, image} = Image.compose(image, explore_new, x: 260, y: 200)
#==> {:ok, image} = Image.compose(image, places, x: 260, y: 260)
#==> {:ok, image} = Image.compose(image, blowout, x: 260, y: 340)
#==> {:ok, image} = Image.compose(image, start_saving, x: 260, y: 400)
# Compose images over a base image
# using a composition list and coordinates
# that are either absolute with respect to the
# base image or relative to the previously
# composed image
#==> Image.compose(base_image, [
...> {polygon, x: :center, y: :top},
...> {explore_new, y_baseline: :top, x_baseline: :left, dx: 20, dy: 200},
...> {places, dy: 10},
...> {blowout, dy: 20},
...> {start_saving, dy: 50}
...> ])
@spec convert_to_mask!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Convert an image into a mask returning an image or raising an exception.
Takes an image, extracts its alpha channel which holds the opacity information and inverts the content.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
mask
image orraises an exception
@spec convert_to_mask(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Convert an image into a mask.
Takes an image, extracts its alpha channel which holds the opacity information and inverts the content.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
{:ok, mask}
or{:error, reason}
@spec crop!(Vix.Vips.Image.t(), integer(), integer(), pos_integer(), pos_integer()) :: Vix.Vips.Image.t() | no_return()
Crop an image returning a cropped image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.left
is the left edge of extract area as a positive integer.top
is the top edge of extract area as an integer. Iftop
is positive it is relative to the top of the image. If it is negative it is relative to the bottom of the image.width
is the width of extract area as a positive integer.height
is the height of extract area as a positive integer.
returns
Returns
cropped_image
orraises an exception.
@spec crop(Vix.Vips.Image.t(), integer(), integer(), pos_integer(), pos_integer()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Crop an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.left
is the top edge of crop area as an integer. Ifleft
is positive it is relative to the left edge of the image. If it is negative it is relative to the right edge of the image.top
is the top edge of crop area as an integer. Iftop
is positive it is relative to the top edge of the image. If it is negative it is relative to the bottom edge of the image.width
is the width of area remaining as a positive integer.height
is the height of the area remaining as a positive integer.
notes
Notes
left
is 0-indexed. That is, the leftmost edge of the image starts at0
.top
is 0-indexed. That is, the toptmost edge of the image starts at0
.
returns
Returns
{:ok, cropped_image}
or{:error, reason}
@spec dominant_color(Vix.Vips.Image.t(), Keyword.t()) :: Image.Color.rgb_color()
Returns the dominant color of an image as an RBG triplet value in an integer list.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.options
is a keyword list of options. The default is[]
.
options
Options
:bins
is an integer number of color freuqency bins the image is divided into. The default is10
.
returns
Returns
[r, g, b]
@spec exif(Vix.Vips.Image.t()) :: {:ok, map()}
Returns the EXIF data for an image as a map.
Only a subset of EXIF data is returned but its a substantial subset.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
{:ok, exif_map}
whereexif_map
is a map of selected EXIF data.
@spec fft!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Returns the fast fourier transform (fft) of the given image returning an image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
fft_image
orraises an exception
example
Example
Image.fft!(image)
@spec fft(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Returns the fast fourier transform (fft) of the given image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
{:ok, fft_image}
or{:error, reason}
example
Example
Image.fft(image)
@spec filename(image :: Vix.Vips.Image.t()) :: Path.t()
Returns the filename for an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
- The pathname from which the image was opened.
@spec flip!(image :: Vix.Vips.Image.t(), direction :: :vertical | :horizontal) :: Vix.Vips.Image.t() | no_return()
Flip an image horizontally or vertically returning a flipped image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.direction
is either:horizontal
or:vertical
.
returns
Returns
flipped_image
orraises an exception.
@spec flip(image :: Vix.Vips.Image.t(), direction :: :vertical | :horizontal) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Flip an image horizontally or vertically.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.direction
is either:horizontal
or:vertical
.
returns
Returns
{:ok, flipped_image}
or{:error, reason}
@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 has_alpha?(Vix.Vips.Image.t()) :: boolean()
Returns a boolean based upon whether a given image has an alpha band.
The determination is a heuristic so certainty cannot be guaranteed.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
true
orfalse
@spec height(Vix.Vips.Image.t()) :: integer()
Returns the height of an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
- The image height as an integer.
Guards whether the coordinates can be reasonably interpreted as a bounding box.
left
and top
when positive are relative to
the left and top of the image respectively. When
negative they are relative to the right and bottom
of the image.
Guards whether a term might be reasonable interpreted as an image pixel.
Guards whether a number can be reasonable interpreted as a size (as in size of a crop or mask)
linear_gradient!(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])
View Source@spec linear_gradient!( Vix.Vips.Image.t(), start :: Image.Color.rgb_color(), finish :: Image.Color.rgb_color() ) :: Vix.Vips.Image.t() | no_return()
Create an image gradient of the same size as the given image. Returns the gradient image or raises and exception.
The gradient will interpolate from the start
value to the finish
value. The default start
value is black with 100% transparency. The
default finish
value is black with 100% opacity.
start
and finish
are given as an rgb
triplet
or quadruplet list of integers between 0
and 255
.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
:start is an
rgbtriplet or quadruplet list of numbers between
0and
255. *
:finish is anrgb
triplet or quadruplet list of numbers between0
and255
.
returns
Returns
gradient_image
orraises an exception.
example
Example
# transparent_black and opaque_black are the default
# start and finish values
transparent_black = [0, 0, 0, 0]
opaque_black = [0, 0, 0, 255]
gradient = Image.linear_gradient!(image, transparent_black, opaque_black)
linear_gradient(image, start \\ [0, 0, 0, 0], finish \\ [0, 0, 0, 255])
View Source@spec linear_gradient( Vix.Vips.Image.t(), start :: Image.Color.rgb_color(), finish :: Image.Color.rgb_color() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Create an image gradient of the same size as the given image.
The gradient will interpolate from the start
value to the finish
value. The default start
value is black with 100% transparency. The
default finish
value is black with 100% opacity.
start
and finish
are given as an rgb
triplet
or quadruplet list of integers between 0
and 255
.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
:start is an
rgbtriplet or quadruplet list of numbers between
0and
255. *
:finish is anrgb
triplet or quadruplet list of numbers between0
and255
.
returns
Returns
{:ok, gradient_image}
or{:error, reason}
example
Example
# transparent_black and opaque_black are the default
# start and finish values
transparent_black = [0, 0, 0, 0]
opaque_black = [0, 0, 0, 255]
{:ok, gradient} = Image.linear_gradient(image, transparent_black, opaque_black)
@spec minimize_metadata!(image :: Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Minimize metadata by keeping only the artist and copyright (if available).
See also Image.minimize_metadata/1
.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
image_with_minimal_metadata
orraises an exception.
@spec minimize_metadata(image :: Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Minimize metadata by keeping only the artist and copyright (if available).
Removing metadata from an image can greatly reduce the overall size of an image. The proprtional reduction is most noticable with smaller images which are very common in web applications.
Removing all metadata is a common option however with intellectual property concerns in mind this function will keep the artist and copyright fields if they exist in the original image.
On a 1000x500px image exported from Adobe Lightroom with metadata intact, removing the metadata results in am approximately 50% saving in file size due to the removal of most EXIF and all IPTC and XMP metadata.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
{:ok, image_with_minimal_metadata}
or{:error, reason}
@spec open!( image_path :: Path.t(), options :: Image.Options.Open.image_open_options() ) :: Vix.Vips.Image.t() | no_return()
Opens an image file for image processing returning an image or raising an exception.
arguments
Arguments
image_path
is the file system path to an image file.options
is a keyword list of options. SeeImage.open/2
.
returns
Returns
image
orraises an exception.
@spec open(image_path :: Path.t(), options :: Image.Options.Open.image_open_options()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Opens an image file for image processing.
arguments
Arguments
image_path
is the file system path to an image file.options
is a keyword list of options. The default is[access: :sequential]
.
options
Options
The available options depends on the type of image file being opened.
all-image-types
All image types
:access
is the file access mode, either:random
or:sequential
. THe default is:sequentual
. When:sequential
,Image
(viaVix
) is able to support streaming transformations and optimise memory usage more effectively. Howwevef:sequenial
also means that some operationas cannot be completed because they would require non-sequential access to the image. In these cases,:random
access is required.:fail_on
sets the error level at which image loading and decoding will stop. The default is:none
. Each error state implies all the states before it such that:error
implies also:truncated
.
jpeg-image-options
JPEG image options
:shrink
is an integer factor in the range1..16
by which the image is reduced upon loading. This is an optimization that can result in improved performance and reduced memory usage if the image is being loaded with the intend to resize it to smaller dimensions. The default value is1
meaning no shrnk-on-load.:autorotate
is a boolean value indicating if the image should be rotated according to the orientation data stored in the image metadata. The default isfalse
.
webp-options
Webp options
:scale
will scale the image on load. The value is1..1024
with a default of1
.:page
indicates the image page to be loaded. The value is in the range0..100_000
with a default value of0
.:pages
indicates how many pages to load. THe value is in the range1..100_000
with a default value of1
.
tiff-options
TIFF options
:autorotate
is a boolean value indicating if the image should be rotated according to the orientation data stored in the image metadata. The default isfalse
.:page
indicates the image page to be loaded. The value is in the range0..100_000
with a default value of0
.:pages
indicates how many pages to load. THe value is in the range1..100_000
with a default value of1
.
png-options
PNG options
- There are no PNG-specific image loading options.
returns
Returns
{:ok, image}
or{:error, message}
Returns the orientation of an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
options
is a keyword list of options
options
Options
:square_ratio
indicates when an image is to be considered square. It is a floating point indicator of the ratio between the width and height below which the image is considered square. The default is0.0
meaning that the dimensions must be exactly equal in order for the image to be considered square.
returns
Returns
- Either
:landscape
,:portrait
or:square
.
example
Example
iex> puppy = Image.open!(Path.expand("images/puppy.webp"))
iex> Image.orientation(puppy, square_ratio: 0.05)
:landscape
@spec put_concurrency(pos_integer()) :: pos_integer()
Sets the number of available threads for use
by libvips
.
By default this is the same as the number of cores in the system. Reducing this number may prevent CPU starvation for other workloads.
arguments
Arguments
concurrency
is a positive integer denoting the maximum number of threads thatlibvips
will use for concurrency.
returns
Returns
{:ok, updated_concurrency}
@spec remove_metadata!(Vix.Vips.Image.t(), [binary() | atom()]) :: Vix.Vips.Image.t() | no_return()
Remove metadata from an image returning an image or raising an exception.
This can significant;y reduce the size of an image file.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
fields
is a list of metadata field names as strings. The default is all known field names. There are some special field names interpreted byImage
to simplify metadata removal these are:
notes
Notes
The available field names (ie. metadata fields) in an image can be returned with a call to
Vix.Vips.Image.header_field_names/1
.Errors removing metadata fields is not propogated into the return for this function. Errors might occur when attempting to remove metadata fields that do not exist in the image.
returns
Returns
image_without_metadata_fields
orraises an exception.
@spec remove_metadata(Vix.Vips.Image.t(), [binary() | atom()]) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Remove metadata from an image returning an updated image or raising an exception.
This can significantly reduce the size of an image file.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
fields
is a list of metadata field names as strings. The default is all known field names. There are some special field names interpreted byImage
to simplify metadata removal these are:
notes
Notes
The available field names (ie. metadata fields) in an image can be returned with a call to
Vix.Vips.Image.header_field_names/1
.Errors removing metadata fields is not propogated into the return for this function. Errors might occur when attempting to remove metadata fields that do not exist in the image.
returns
Returns
{:ok, image_without_metadata_fields}
or{:error, reason}
@spec resize!( Vix.Vips.Image.t() | Path.t(), width :: pos_integer(), options :: Image.Options.Resize.resize_options() ) :: Vix.Vips.Image.t() | no_return()
Resize an image to fit or fill a bounding box returning an image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.width
is the width of the resulting image after resizing.options
is a keyword list of options. SeeImage.resize/3
.
returns
Returns
image
orraises an exception.
@spec resize( Vix.Vips.Image.t(), width :: pos_integer(), options :: Image.Options.Resize.resize_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec resize( Path.t(), width :: pos_integer(), options :: Image.Options.Resize.resize_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec resize( Vix.Vips.Image.t() | Path.t(), width :: pos_integer(), options :: Image.Options.Resize.resize_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Resize an image to fit or fill a bounding box.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.width
is the integer width of the resulting image after resizing. It can also be of the form "<width>x<height>". That is, a string with the width and height separated by anx
. The<height>
may be ommitted in which case it is the same as providing an integer width.options
is a keyword list of options.
options
Options
:crop
determines if the strategy is "resize to fit" (crop is:none
) or "resize to fill" (when the crop option is not:none
. The value may be one of:none
,:center
,:entropy
,:attention
,:low
or:high
. The default is:none
. See alsoImage.Options.Crop.crop_focus/0
.:autorotate
is a boolean indicating if the image should be autorated based upon the image metadata. The default istrue
.:intent
indicates the rendering intent. The default is:relative
. See alsoImage.render_intent/0
.:export_icc_profile
-Indicates the icc profile to be attached to the resized image. The value may be an inbuilt profile (:srgb
,:p3
or:cmyk
), the name of an icc profile in the systems profile directory or a full path to an icc profile file. The default is to export the icc profile of the resized image if there is one.:import_icc_profile
-Indicates the icc profile to be attached to the input image. The value may be an inbuilt profile (:srgb
,:p3
or:cmyk
), the name of an icc profile in the systems profile directory or a full path to an icc profile file. The default is to use the icc profile of the input image if there is one.:linear
is a boolean indicating of the image should be resized in linear space. The 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.:resize
determines if an image may be only upsized, only downsized, or both. The value may be one of:up
,:down
or:both
. The default is:both
.:height
- Size to this height. Default is to maintain the image aspect ratio.
returns
Returns
{:ok, resized_image}
or{:error, reason}
@spec ripple!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Adds a concentric ripple effect to an image returning an image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
image_with_ripple
orraises an exception.
@spec ripple(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Adds a concentric ripple effect to an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
{:ok, image_with_ripple}
or{:error, reason}
@spec rotate!( image :: Vix.Vips.Image.t(), angle :: float(), options :: Image.Options.Rotation.rotation_options() ) :: Vix.Vips.Image.t() | no_return()
Rotate an image clockwise (to the right) by a number of degrees.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.angle
is afloat
number of degrees to rotate in a clockwise direction.options
is a keyword list of options. SeeImage.rotate/3
.
notes
Notes
The displacement parameters cause the image canvas to be expanded and the image displaced, relative to the top left corner of the image, by the amount specified.
The rules defining how the image canvas is expanded
is not known to the author of Image
. Experimentation will
be required if you explore these options.
returns
Returns
rotated_image
orraises an exception.
@spec rotate( image :: Vix.Vips.Image.t(), angle :: float(), options :: Image.Options.Rotation.rotation_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Rotate an image clockwise (to the right) by a number of degrees.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.angle
is afloat
number of degrees to rotate in a clockwise direction.options
is a keyword list of options.
options
Options
:idy
is the vertical input displacement which defaults to0.0
:idx
is the horizontal input displacement which defaults to0.0
:ody
is the vertical output displacement which defaults to0.0
:odx
is the horizontal output displacement which defaults to0.0
:background
is the background color to be used for filling the blank areas of the image. The background is specified as a list of 3 or 4 float values depending on the image color space.
notes
Notes
The displacement parameters cause the image canvas to be expanded and the image displaced, relative to the top left corner of the image, by the amount specified.
The rules defining how the image canvas is expanded
is not known to the author of Image
. Experimentation will
be required if you explore these options.
returns
Returns
{:ok, rotated_image}
or{:error, reason}
@spec rounded!(Vix.Vips.Image.t(), Keyword.t()) :: Vix.Vips.Image.t() | no_return()
Apply rounded corners to an image. Returns an image or raises an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.options
is a keyword list of options.
options
Options
:radius
is the desired corner radius. The default is 50.
returns
Returns
rounded_corner_image
orraises an exception.
@spec rounded(Vix.Vips.Image.t(), Keyword.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Apply rounded corners to an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.options
is a keyword list of options.
options
Options
:radius
is the desired corner radius. The default is 50.
returns
Returns
{:ok, rounded_corner_image}
or{:error, reason}
@spec skew_angle(Vix.Vips.Image.t()) :: float()
Attempts top determine the distance from the perpendicular for a given image.
The principle is that rotating the image by the skew angle should return an image in the upright position.
The results are very image sensitive and perfect results are not guaranteed.
The algorithm is an implementation of this stackoverflow post.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
skew_angle
which is a float number of degrees the image is tilted from the upright.
Example
skew_angle = skew_angle(image)
Image.rotate(image, skew_angle)
@spec to_colorspace!(Vix.Vips.Image.t(), Image.Interpretation.interpretation()) :: Vix.Vips.Image.t() | no_return()
Converts an impage to the given colorspace returning an image or raising an exception.
Available colorspaces are returned from
Image.Interpretation.known_interpretations/0
.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
colorspace
is any known colorspace. SeeImage.Interpretation.known_interpretations/0
for a list of the known colorspaces.
returns
Returns
image_in_new_colorspace
orraises an exception
example
Example
Image.to_colorspace!(image, :bw)
@spec to_colorspace(Vix.Vips.Image.t(), Image.Interpretation.interpretation()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Converts an impage to the given colorspace.
Available colorspaces are returned from
Image.Interpretation.known_interpretations/0
.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
colorspace
is any known colorspace. SeeImage.Interpretation.known_interpretations/0
for a list of the known colorspaces.
returns
Returns
{;ok, image_in_new_colorspace}
or{:error, reason}
example
Example
Image.to_colorspace(image, :bw)
@spec to_polar_coordinates!(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
@spec to_polar_coordinates!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Convert image to polar coordinates returning an image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
image_in_polar_coordinates
orraises an exception.
Convert image to polar coordinates.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
returns
Returns
{:ok, image_in_polar_coordinates}
or{:error, reason}
@spec to_rectangular_coordinates!(Vix.Vips.Image.t()) :: Vix.Vips.Image.t() | no_return()
Convert image to rectangular coordinates returning an image or raising an exception.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
notes
Notes
Roundtrip to polar and back to rectangular coordinates displays some image distortion, likely due to rounding errors in float arithmetic. Further study is required.
returns
Returns
image_in_rectuangular_coordinates
orraises an exception.
@spec to_rectangular_coordinates(Vix.Vips.Image.t()) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Convert image to rectangular coordinates.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
.
notes
Notes
Roundtrip to polar and back to rectangular coordinates displays some image distortion, likely due to rounding errors in float arithmetic. Further study is required.
returns
Returns
{:ok, image_in_rectangular_coordinates}
or{:error, reason}
@spec vips_version() :: {:ok, Version.t()}
Returns the version of libvips
in
operation.
@spec width(Vix.Vips.Image.t()) :: integer()
Returns the width of an image.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
- The image width as an integer.
@spec write!( image :: Vix.Vips.Image.t(), image_path :: Path.t(), options :: Image.Options.Write.image_write_options() ) :: Vix.Vips.Image.t() | no_return()
Writes an image to a file returning the image or raising an exception.
arguments
Arguments
image_path
is the file system path to an image file.options
is a keyword list of options. SeeImage.write/2
.
returns
Returns
image
orraises an exception.
@spec write( image :: Vix.Vips.Image.t(), image_path :: Path.t(), options :: Image.Options.Write.image_write_options() ) :: {:ok, Vix.Vips.Image.t()} | {:error, error_message()}
Write an image to a file.
arguments
Arguments
image_path
is the file system path to an image file.options
is a keyword list of options. The default is[]
.
options
Options
The available options depends on the type of image file being opened.
all-image-types
All image types
:profile
is the name of any ICC color profile.:strip
is a boolean indicating if all metadata is to be stripped from the image. The default isfalse
.:background
is the background value to be used for any transparent areas of the image. Jpeg does not support alpha bands so a color value must be assigned.:quality
which influences image compression and is a integer in the range1..100
. The default for most image formats is75
. For PNG files it is the quantization quality with a default of100
. For HEIF files the default is50
.
jpeg-images
JPEG images
:progressive
is a boolean indicating if the image should be interleaved rather than baseline. Progressive has the advantage of perceived time for the inital image load and the cost of multiple decoding passes on the client. For many applications:progressive
is to be preferred but validation of this assumption for specific use cases is required.
png-images
PNG images
:color_depth
is an integer describing the number of bits for each color. The value can be1
,2
,4
,8
or16
. The default is to use the current color depth of the image. For web applications,8
bits would be reasonable for photographic images with lower bit depts for monochromatic images or diagrams.:progressive
which has the same meaning and values as for JPEG images.:compression
is the image compression factor as an image between0..9
. The default is6
.
tiff-images
TIFF images
:color_depth
which has the same meaning as for PNG images.
heif-images
Heif images
:compression
is the compression strategy to be applied. The allowable values are:hevc
,:avc
,:jpeg
and:av1
. The default is:hevc
.
@spec xmp(Vix.Vips.Image.t()) :: {:ok, map()}
Returns the XMP data for an image as a keyword list.
Only a selected set of XMP data is returned.
arguments
Arguments
image
is anyVix.Vips.Image.t/0
returns
Returns
{:ok, xmp_map}
wherexmp_map
is a map of selected XMP data.