Scripting interface#

sandman.sandman.cmap_from_json(jsonfile, mapname)#

Generates a matplotlib colormap from the given JSON file.

Parameters:

  • jsonfile (str) – Name of the JSON file defining colormaps

  • mapname (str) – Name of the colormap

Returns:

The final colormap

Return type:

matplotlib.colors.LinearSegmentedColormap

sandman.sandman.cmap_from_params(name, hxs, params, kind, lightness_base, saturation_base)#

Generates a matplotlib colormap from the given parameters.

Parameters:

  • name (str) – Name to assign to this colormap

  • hxs (list of str) – Hex color codes of colors to interpolate

  • params (numpy.ndarray) – Parameters of the colormap

  • kind (str) – One of sequential, diverging, or cyclic

  • lightness_base (float) – Additive boost for the lightness parameter

  • saturation_base (float) – Additive boost for the saturation parameter

Returns:

The final colormap

Return type:

matplotlib.colors.LinearSegmentedColormap

sandman.sandman.find_optimal_params(hxs, target, ld0, sat0)#

Optimizes the given colors such that they have perceptual lightness values as close as possible to the given target values

Parameters:

  • hxs (list of str) – Colors to be optimized

  • target (numpy.ndarray) – Proposed target values for the lightness parameter, with shape (len(hxs),)

  • ld0 (float) – Baseline lightness to add after the transform

  • sat0 (float) – Baseline saturation to add after the transform

Returns:

Optimized parameters and value of the objective function

Return type:

tuple of numpy.ndarray and float

sandman.sandman.find_optimal_params_diverging(hxs, lightness_base=0, saturation_base=0, min_intensity=55, max_intensity=85)#

Optimizes the given colors by modifying their lightness and saturation to reach a diverging perceived intensity.

Parameters:

  • hxs (list of str) – Hex color codes of colors to optimize

  • lightness_base (float) – Additive boost for the lightness parameter

  • saturation_base (float) – Additive boost for the saturation parameter

  • min_intensity (float) – Minimum target perceived intensity

  • max_intensity (float) – Maximum target perceived intensity

Returns:

Optimized parameters and value of the objective function

Return type:

tuple of numpy.ndarray and float

sandman.sandman.find_optimal_params_sequential(hxs, lightness_base=0, saturation_base=0, min_intensity=55, max_intensity=85)#

Optimizes the given colors by modifying their lightness and saturation to reach a sequential perceived intensity.

Parameters:

  • hxs (list of str) – Hex color codes of colors to optimize

  • lightness_base (float) – Additive boost for the lightness parameter

  • saturation_base (float) – Additive boost for the saturation parameter

  • min_intensity (float) – Minimum target perceived intensity

  • max_intensity (float) – Maximum target perceived intensity

Returns:

Optimized parameters and value of the objective function

Return type:

tuple of numpy.ndarray and float

sandman.sandman.interpolate_diverging(hxs, params, lightness_base, saturation_base)#

Performs an interpolation in intensity space between the given colors, assuming the map is diverging.

Parameters:

  • hxs (list of str) – Hex color codes of colors to interpolate

  • params (numpy.ndarray) – Parameters of the colormap

  • lightness_base (float) – Additive boost for the lightness parameter

  • saturation_base (float) – Additive boost for the saturation parameter

Returns:

Interpolated colors in CAM space

Return type:

numpy.ndarray

sandman.sandman.interpolate_sequential(hxs, params, lightness_base, saturation_base)#

Performs an interpolation in intensity space between the given colors, assuming the map is sequential.

Parameters:

  • hxs (list of str) – Hex color codes of colors to interpolate

  • params (numpy.ndarray) – Parameters of the colormap

  • lightness_base (float) – Additive boost for the lightness parameter

  • saturation_base (float) – Additive boost for the saturation parameter

Returns:

Interpolated colors in CAM space

Return type:

numpy.ndarray

sandman.sandman.modify_color(hc, lightdark=1, saturate=1)#

Modifies the given color by lightening and saturating according to the input parameters

Parameters:

  • hc (str) – Hex code for the input color

  • lightdark (float, optional) – Lightening parameter. For values greater than unity, the color will be lightened, and, for values less than unity, the color will be darkened. The lightness of the color in HLS space is scaled by the value of lightdark, but it will not exceed unity when the color is reconstructed

  • saturate (float, optional) – Saturation parameter. For values greater than unity, the color will be saturated, and, for values less than unity, the color will be desaturated. The saturation of the color in HLS space is scaled by the value of saturate, but it will not exceed unity when the color is reconstructed

Returns:

The modified, reconstructed color as a hex code

Return type:

str

sandman.sandman.params_to_cam(p, hxs, ld0, sat0)#

Converts the input parameters and colors into CAM02 triples

Parameters:

  • p (numpy.ndarray) – Input parameters as fed into objective function, with shape (2 * len(hxs),)

  • hxs (list of str) – User-specified colors for the current optimization

  • ld0 (float) – Baseline lightness to add after the transform

  • sat0 (float) – Baseline saturation to add after the transform

Returns:

CAM02 triples on their native intervals, with shape (len(hxs), 3)

Return type:

numpy.ndarray

sandman.sandman.params_to_rgb(p, hxs, ld0, sat0)#

Converts the input parameters and colors into RGB triples

Parameters:

  • p (numpy.ndarray) – Input parameters as fed into objective function, with shape (2 * len(hxs),)

  • hxs (list of str) – User-specified colors for the current optimization

  • ld0 (float) – Baseline lightness to add after the transform

  • sat0 (float) – Baseline saturation to add after the transform

Returns:

RGB triples mapped to the [0,1] interval, with shape (len(hxs), 3)

Return type:

numpy.ndarray

sandman.sandman.params_to_standard(p, hxs, ld0, sat0)#

Converts the input parameters into a standard form

Parameters:

  • p (numpy.ndarray) – Input parameters as fed into objective function, with shape (2 * len(hxs),)

  • hxs (list of str) – User-specified colors for the current optimization

  • ld0 (float) – Baseline lightness to add after the transform

  • sat0 (float) – Baseline saturation to add after the transform

Returns:

Parameters that can be converted to colors, with shape (2, len(hxs))

Return type:

numpy.ndarray

sandman.sandman.simulate_cvd(fig, kind, severity)#

Applies the given color vision deficiency to the given figure and returns a modified image.

Parameters:

  • fig (matplotlib.figure) – Figure to modify

  • kind (str) – One of protanomaly, deuteranomaly, or tritanomaly

  • severity (float) – Severity of the CVD, in the range [0, 100]

Returns:

An approximate image perceived with this CVD

Return type:

PIL.Image.Image

sandman.sandman.simulate_grayscale(fig)#

Applies a grayscale intensity mapping to the given figure and returns a modified image. This is intended to approximate the appearance either in black-and-white print media or perceived with no color vision whatsoever.

Important

The returned image has the perceived lightness assigned to the red, green, and blue channels equally.

Parameters:

fig (matplotlib.figure) – Figure to modify

Returns:

An approximate image with no color

Return type:

PIL.Image.Image