View Source Image.Color (image v0.53.0)

Functions to manage image color and color conversion.

Summary

Types

icc_profile()

Reference to an ICC color profile

rgb_color()

An rbg color expressed as a list of numbers.

t()

A color can be expressed as a list of numbers or as a CSS color name in atom or string format.

transparency()

A transparency value which is one of the atoms :none, :transparent or :opaque. Or an integer between 0 and 255 where 0 is transparent and 255 is opaque. Or a float in the range 0.0 to 1.0 that is converted to the range 0 to 255.

Functions

color_map()

Returns a mapping from CSS color names to CSS hex values and RGB triplets as a list.

convert(color, from, to, options \\ [])

Converts a color from one color space to another.

convert!(color, from, to, options \\ [])

Converts an color from one color space to another or raises an exception.

greyscale_color_map()

Returns a mapping from CSS color names to CSS hex values and RGB triplets as a list - but only for greyscal colors.

hex_to_rgb(invalid_color)

Converts a hex color string to an RGB list.

inbuilt_profiles()

Returns the list of color profiles built into libvips.

is_color(color)

Guards whether a given value can be interpreted as a color value.

is_inbuilt_profile(profile)

Guards whether a given profile is one of the inbuilt profiles.

known_icc_profile?(profile)

Returns a boolean indicating if the given profile is known and can be used for image operations.

rgb_color(color)

rgb_color!(color)

rgb_to_hex(color)

Converts a color name or RGB value to a hex string.

sort(colors, options \\ [])

Sorts a list of colors.

validate_color(color)

Validates a color returning an [r, g, b] triplet or error.

validate_transparency(float)

Returns a transparency value in the range 0 to 255 where 0 means transparent and 255 means opqque.

Types

icc_profile()

@type icc_profile() :: :none | :cmyk | :srgb | :p3 | Path.t()

Reference to an ICC color profile

:none means no profile
:cmyk, :srgb and :p3 refer to the built-in color profiles
Path.t() means any file system path. If the path is a relative path then is will be loaded from the systems profile directory.

rgb_color()

@type rgb_color() :: [number()] | number()

An rbg color expressed as a list of numbers.

The number of list elements and the type varies depending on the image format, colorspace and dimensions.

For a common sRGB image it will be a list of three of four images. If the fourth number is provided it will be considered as an alpha transparency band.

t()

@type t() :: rgb_color() | atom() | String.t()

A color can be expressed as a list of numbers or as a CSS color name in atom or string format.

transparency()

@type transparency() :: :none | :transparent | :opaque | non_neg_integer() | float()

Functions

color_map()

Returns a mapping from CSS color names to CSS hex values and RGB triplets as a list.

convert(color, from, to, options \\ [])

(since 0.49.0)

Converts a color from one color space to another.

Arguments

color which 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". See Image.Color.color_map/0 and Image.Color.rgb_color/1.
from is the colorspace from which color is converted.
to is the colorspace into which the color is converted.
options is a keyword list of options.

Options

There are currently no defined options.

Returns

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

Example

iex> Image.Color.convert(:misty_rose, :srgb, :hsv)
{:ok, [4, 30, 255]}

iex> Image.Color.convert([255, 255, 255], :srgb, :lab)
{:ok, [100.0, 0.005245208740234375, -0.010609626770019531]}

convert!(color, from, to, options \\ [])

(since 0.49.0)

Converts an color from one color space to another or raises an exception.

Arguments

color which can be specified as a single integer which 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. See Image.Color.color_map/0 and Image.Color.rgb_color/1.
from is the colorspace from which color is converted.
to is the colorspace into which the color is converted.
options is a keyword list of options.

Options

There are currently no defined options.

Returns

converted_color or
raises an exception.

Example

iex> Image.Color.convert!(:misty_rose, :srgb, :hsv)
[4, 30, 255]

iex> Image.Color.convert!([255, 255, 255], :srgb, :lab)
[100.0, 0.005245208740234375, -0.010609626770019531]

greyscale_color_map()

Returns a mapping from CSS color names to CSS hex values and RGB triplets as a list - but only for greyscal colors.

hex_to_rgb(invalid_color)

Converts a hex color string to an RGB list.

Arguments

color is a hex string representing an RGB color. It has the form #RRGGBB.

Returns

{:ok, [r, g, b]} or
{:error, reason}.

Examples

iex> Image.Color.validate_color "#0000FF"
{:ok, [0, 0, 255]}

inbuilt_profiles()

Returns the list of color profiles built into libvips.

is_color(color)

(macro)

Guards whether a given value can be interpreted as a color value.

is_inbuilt_profile(profile)

(macro)

Guards whether a given profile is one of the inbuilt profiles.

known_icc_profile?(profile)

Returns a boolean indicating if the given profile is known and can be used for image operations.

rgb_color(color)

rgb_color!(color)

rgb_to_hex(color)

Converts a color name or RGB value to a hex string.

Arguments

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

Returns

{:ok, #RRGGBB} string or
{:error, reason}.

Examples

iex> Image.Color.rgb_to_hex(:green)
{:ok, "#008000"}

iex> Image.Color.rgb_to_hex([10,20,30])
{:ok, "#A141E"}

sort(colors, options \\ [])

(since 0.49.0)

Sorts a list of colors.

The color sorting is based upon https://www.alanzucconi.com/2015/09/30/colour-sorting/

Arguments

color which 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. See Image.Color.color_map/0 and Image.Color.rgb_color/1.
options is a keyword list of options.

Options

There are currently no defined options.

Returns

A sorted list of colors.

validate_color(color)

Validates a color returning an [r, g, b] triplet or error.

Arguments

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

Returns

{:ok, [r, g, b]} or
{:error, reason}

validate_transparency(float)

Returns a transparency value in the range 0 to 255 where 0 means transparent and 255 means opqque.