Gradient

Gradients between colors.

Examples

Get purple inbetween red and blue:

>>> grad = Grad(["ff0000", "0000ff"])
>>> grad(0.5)  # By default interpolates in CIELuv
Hex('#be0090')

Depending on your use-case, it may be useful to rather interpolate colors in a cilindrical color space, such as HSV or HCLuv. To do this, use PolarGrad, which supports color lerping through polar coordinate color components:

>>> p_grad = PolarGrad(["ff0000", "0000ff"])
>>> p_grad(0.5)
Hex('#f000cc')

You can control how the hue is interpolated with the hue_lerp attribute:

>>> p_grad.hue_lerp = "longest"  # Calculates the longest distance between the hue of red and blue
>>> p_grad(0.5)  # Now we get green instead of purple
Hex('#008800')

Get 5 colors interspaced in the gradient:

>>> grad.n_colors(5)
[Hex('#ff0000'), Hex('#e00066'), Hex('#be0090'), Hex('#9400b9'), Hex('#0000ff')]

You can use the ‘domain’ argument to change the range in which values are interpolated:

>>> grad = Grad(["ff0000", "0000ff"], domain=[4, 8])
>>> grad(6)
Hex('#be0090')

And the ‘color_coords’ argument to specify the position of the input colors in the gradient:

>>> grad = Grad(["ff0000", "00ff00", "0000ff"], color_coords=[0, 0.75, 1])  # Green sits closer to blue than to red
>>> grad(0.75)
Hex('#00ff00')
class colorir.gradient.Grad(colors, color_sys=<class 'colorir.color_class.CIELuv'>, color_format=None, color_coords=None, domain=(0, 1), discrete=False)

Bases: object

Linear interpolation gradient.

Parameters:

  • colors (Iterable[ColorBase | str | tuple]) – Iterable of colors that compose the gradient.

  • color_format – Color format specifying how to output colors. Defaults to config.DEFAULT_COLOR_FORMAT.

  • color_sys (Type[ColorBase]) – Color system in which the colors will be interpolated.

  • domain – Range (inclusive on both ends) from which colors can be interpolated.

  • color_coords (List[float]) – A list of the coordinates where each color in ‘colors’ is located in the gradient. If left empty, interspaced points will be automatically generated. For example, the default for a list of three colors with domain == [0, 1] is [0, 0.5, 1]. Must have the same length as the colors argument.

  • discrete – If True, does not interpolate the colors and instead return the closest color to the input value (according to color_coords). Useful to plot categorical data.

property colors
property color_edges
self(x, restrict_domain=False)

Call self as a function.

grayscale()
at(x, restrict_domain=False)
perc(p, restrict_domain=False)

Returns the color placed in a given percentage of the gradient.

Parameters:

  • restrict_domain –

  • p (float) – Percentage of the gradient expressed in a range of 0-1 from which a color will be drawn.

Examples

Get purple inbetween red and blue:

>>> grad = Grad([RGB(1, 0, 0), RGB(0, 0, 1)])
>>> grad.perc(0.5)
Hex('#be0090')

Get a very “reddish” purple:

>>> grad.perc(0.2)
Hex('#e6005c')
n_colors(n, include_ends=True)

Return n interspaced colors from the gradient.

Parameters:

  • n (int) – Number of colors to retrieve.

  • include_ends – Stops the colors at the extreme of the gradient from being sampled. This allows sampling a small number of colors (such as two) without having it return the same colors that were used to create the gradient in the first place.

to_cmap(name=None, n=256)

Converts this gradient into a matplotlib ListedColormap.

Parameters:

  • n – Number of discrete colors in the resulting color map.

  • name – Passed down to color map constructor.

to_plotly_colorscale(n=256)

Make a color scale according to plotly’s format definition.

Parameters:

n – Number of internal interpolations to perform before creating the color scale. Increases the accuracy of the color scale. This argument is not used if the gradient is discrete.

class colorir.gradient.PolarGrad(colors, color_sys=<class 'colorir.color_class.HCLuv'>, hue_lerp='shortest', **kwargs)

Bases: Grad

Similar to Grad but can calculate the shortest path for hue interpolation.

Parameters:

  • hue_lerp – Which method to apply to hue interpolation. Options are: None, “increase”, “decrease”, “shortest” and “longest”. None means that the hue will be treated as any other color component and interpolated normally. “increment” and “decrement” indicate that the hue can only be incremented or decremented respectively. “shortest” and “longest” make sure that the hue is interpolated in the shortest or longest paths between the colors. Default is “shortest”.

  • colors – Iterable of colors that compose the gradient.

  • color_sys – Color system in which the colors will be interpolated.

class colorir.gradient.RGBGrad(colors, use_linear_rgb=True, **kwargs)

Bases: Grad

Linear interpolation gradient using the RGB color space.

This class allows colors to be interpolated using linear RGB through the ‘use_linear_rgb’ parameter. Otherwise, RGBGrad(..., use_linear_rgb=False) is the same as Grad(..., color_sys=sRGB).

Parameters:

  • colors (Iterable[ColorBase | str | tuple]) – Iterable of colors that compose the gradient. There can be more than two colors in this iterable.

  • color_format – Color format specifying how to output colors. Defaults to config.DEFAULT_COLOR_FORMAT.

  • use_linear_rgb – Whether to use linear RGB rather than sRGB to create the gradient. Defaults to True.

Notes

Often using linear RGB may result in a gradient that looks more natural to the human eye [1]. THIS IS THE DEFAULT.

References

colorir.gradient.RGBLinearGrad

alias of RGBGrad