s3dlib.cmap_utilities

Contents

Functions

The following functions return a Matplotlib colormap.

rgb_cmap_gradient([lowColor, highColor, ...])

A linear-in-RGB-space Colormap.

hsv_cmap_gradient([lowHSV, hiHSV, name, ...])

A linear-in-HSV-space Colormap.

hue_cmap([lowHue, hiHue, smooth, name])

A 'smooth-HSV' colormap.

stitch_cmap(*maps[, bndry, name])

Colormap composed of multiple colormaps.

stitch_color(*colorArr[, bndry, name])

Colormap composed of multiple colors.

binary_cmap([negColor, posColor, name, bndry])

A two-color Colormap.

mirrored_cmap(cmap[, name, rev])

A mirrored colormap.

reversed_cmap(cmap[, name])

A reversed colormap.

alpha_cmap(cmap, alpha[, constant, name])

Set the Colormap alpha channel.

op_cmap(operation[, rgb, name])

A Colormap defined by a function argument.

op_alpha_cmap(cmap, operation[, fit, name])

A Colormap modified by functional values of alpha.

section_cmap(cmap, lowIndx, hiIndx[, name])

A Colormap from a section of a colormap.

Additional Functions

linsegfunc(v, arr)

Linear segment function, y = f(x) with domain/range [0,1]

Classes

DualCmap(xcmap, ycmap[, kind, norm, name])

A 2D colormap.

Code Documentation

Module containing functions to create Matplotlib color maps.

s3dlib.cmap_utilities.alpha_cmap(cmap, alpha, constant=False, name=None)[source]

Set the Colormap alpha channel.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name

  • alpha (scalar) – Value set for the color alpha channel. The alpha values are in the range 0+ to 1-.

  • constant (bool { True, False }, optional, False) – If False, alpha channel values are multiplied by alpha. If True, all alpha channels are assigned to a constant alpha.

  • name (str, optional) – The registered name to identify the colormap. If it’s None, the name assigned the colormap name with ‘_a’ at the end characters.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.binary_cmap(negColor='b', posColor='r', name=None, bndry=None)[source]

A two-color Colormap.

Parameters:

  • negColor (color, optional, default: 'blue') – Color at the low end of the Colormap range.

  • posColor (color, optional, default: 'red') – Color at the high end of the Colormap range.

  • name (str, optional, default: None) – The registered name to identify the colormap. If it’s None, name is assigned a string of 8 random characters.

  • bndry (float, optional, default: 0.5) – The division between the negColor and posColor, with range from 0.03 to 0.97

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.hsv_cmap_gradient(lowHSV=[0, 1, 1], hiHSV=[1, 1, 1], name=None, mirrored=False, smooth=None)[source]

A linear-in-HSV-space Colormap.

Using hSV or hSVA values for HSV color. SVA values are in the range [0,1]. The h values are in the range [0,2] so that Hue is mod(h,1).

Parameters:

  • lowHSV (3 or 4 array or string, optional, default: [0,1,1], , 'red') – HSV, HSVA color at the low end of the Colormap range. If a string, a named color (may be proceeded by a ‘+’)

  • hiHSV (3 or 4 array or string, optional, default: [1,1,1] , '+red') – HSV, HSVA color at the high end of the Colormap range. If a string, a named color (may be proceeded by a ‘+’)

  • name (str, optional, default: None) – The registered name to identify the colormap. If it’s None, name is assigned a string of 8 random characters.

  • mirrored (bool) – If True, colormap is divided into two linear segments with the lowHSV at the low and high values, the highColr in the middle.

  • smooth (float, optional, default: None) – Controls the ratio of the amount of CMY to RGB color. CMY is extended relative to the RGB hues for values greater than one (relative to standard HSV colormap). RGB is extended relative to the CMY hues for values less than one. Range is [.1,10]

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.hue_cmap(lowHue=0, hiHue=None, smooth=1.6, name=None)[source]

A ‘smooth-HSV’ colormap.

Non linear adjustment of Hue in a HSV colormap. For the HSV colors, S and V are 1. The h values are shifted based on the smoothing parameter.

Parameters:

  • lowHue (float or string, optional, default: 0) – Hue at the low end of the Colormap range. Values are in the range [0,2]. If a string, the hue of a named color (may be proceeded by a ‘+’)

  • hiHue (float or string, optional, default: 1) – Hue at the upper end of the Colormap range. Values are in the range [0,2]. If a string, the hue of a named color (may be proceeded by a ‘+’)

  • smooth (float, optional, default: 1.6) – Controls the ratio of the amount of CMY to RGB color. CMY is extended relative to the RGB hues for values greater than one (relative to standard HSV colormap). RGB is extended relative to the CMY hues for values less than one. Range is [.1,10]

  • name (str, optional, default: None) – The registered name to identify the colormap. If it’s None, name is assigned a string of 8 random characters.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.linsegfunc(v, arr)[source]

Linear segment function, y = f(x) with domain/range [0,1]

Parameters:

  • v (float or array) – Independent variable in the range 0 to 1.

  • arr (N X 2 array) – An array of N values (x,y), with increasing values of x and, y in the range 0 to 1.

Returns:

float – Dependent values or array of values

s3dlib.cmap_utilities.mirrored_cmap(cmap, name=None, rev=False)[source]

A mirrored colormap.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name.

  • name (str, optional) – The registered name to identify the colormap. If None, ‘_m’ will be appended to the colormap name.

  • rev (boolean {True, False}, default: False) – If True, the reversed colormap will be used.

s3dlib.cmap_utilities.op_alpha_cmap(cmap, operation, fit=True, name=None)[source]

A Colormap modified by functional values of alpha.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name

  • operation (function object) – Function that takes one argument, a Numpy array of float values in the range from 0 to 1. The function returns a Numpy array of float values in the range from 0 to 1.

  • name (str, optional, default: None) – The registered name to identify the colormap. If it’s None, the map is not registered if a lambda function is the operation argument, otherwise, the operatonal function name is assigned to the cmap name.

  • fit (bool, optional, default: True) – If True, the values return by the operation function will be fit to the range 0 to 1.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.op_cmap(operation, rgb=True, name=None)[source]

A Colormap defined by a function argument.

Parameters:

  • operation (function object) – Function that takes one argument, a Numpy array of float values in the range from 0 to 1. The function returns a 3xN color value.

  • rgb (bool {True, False}, optional, default: True) – By default, RGB color values are returned by the operation function. If set False, the operation returns HSV color values.

  • name (str, optional, default: None) – The registered name to identify the colormap. If it’s None, the operatonal function name is assigned to the cmap name if not a lambda function. If a lamddda function, the name is assigned a string of 8 random characters.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.reversed_cmap(cmap, name=None)[source]

A reversed colormap.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name

  • name (str, optional) – The registered name to identify the colormap. If None, ‘_r’ will be appended to the colormap name.

s3dlib.cmap_utilities.rgb_cmap_gradient(lowColor='k', highColor='w', name=None, mirrored=False)[source]

A linear-in-RGB-space Colormap.

Parameters:

  • locColor (color, optional, default: 'black') – Color at the low end of the Colormap range.

  • highColor (color, optional, default: 'white') – Color at the high end of the Colormap range.

  • name (str, optional) – The registered name to identify the colormap. If it’s None, the name will be a string of 8 random characters.

  • mirrored (bool) – If True, colormap is divided into two linear segments with the lowColor at the low and high values, the highColr in the middle.

Returns:

LinearSegmentedColormap – An instance of a colormap.

s3dlib.cmap_utilities.section_cmap(cmap, lowIndx, hiIndx, name=None)[source]

A Colormap from a section of a colormap.

Parameters:

  • cmap (str or Colormap, optional) – A Colormap instance or registered colormap name

  • lowIndx (float) – Value of the start of the input colormap. Range is 0 to 0.97.

  • hiIndx (float) – Value of the end of the input colormap. Range is 0.03 to 1.0.

  • name (str, optional) – The registered name to identify the colormap. If None, the name will be a string of random characters and the map is not registered.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.stitch_cmap(*maps, bndry=None, name=None)[source]

Colormap composed of multiple colormaps.

Parameters:

  • maps (str or Colormap, optional) – A Colormap instance or registered colormap name

  • bndry (scalar or list, default: None) – Boundary between colormaps. If a list, the number of values must be one less than the number of maps. The list values must be in assending order. If None, input colormaps are evenly spaced in the returned colormap. The bndry values are in the range 0+ to 1-.

  • name (str, optional) – The registered name to identify the colormap. If it’s None, the name will be assigned a string of 8 random characters.

Returns:

ListedColormap – An instance of a colormap.

s3dlib.cmap_utilities.stitch_color(*colorArr, bndry=None, name=None)[source]

Colormap composed of multiple colors.

Parameters:

  • *colorArr (colors) –

  • bndry (scalar or list, default: None) – Boundary between colors. If a list, the number of values must be one less than the number of maps. The list values must be in assending order. If None, input colors are evenly spaced in the returned colormap. The bndry values are in the range 0+ to 1-.

  • name (str, optional) – The registered name to identify the colormap. If it’s None, the name will assigned be a string of 8 random characters.

Returns:

ListedColormap – An instance of a colormap.

class s3dlib.cmap_utilities.DualCmap(xcmap, ycmap, kind='sum', norm=True, name=None)[source]

Bases: object

A 2D colormap.

Parameters:

  • xcmap (colormap or string of a colormap name.) –

  • ycmap (colormap or string of a colormap name.) –

  • kind (string {'sum','ave','ave2','srt'} or number, default: 'sum') – Method of combining colormaps.

  • norm (bool, optional, default True) – Normalize array values in __call__

  • name (string,optional.) – name to identify the dual colormap.

__call__(x, y)[source]

RGBA color values from x,y positions.

Parameters:

  • x (arrays of N floats with values in the) – interval [0,1]. Normalization will occur if ‘norm’ is set to True in the constructor. Both arrays must be of the same length, N.

  • y (arrays of N floats with values in the) – interval [0,1]. Normalization will occur if ‘norm’ is set to True in the constructor. Both arrays must be of the same length, N.

Returns:

RGBA values with N shape (4,N)

distfact(p)[source]

Set distribution factor of resulting color values.

Parameters:

p (float in the range [0.2, 4]) – For a value of 1, there is no redistribution. A value of 0.5 is equivalent to using the constructor argument of kind=’srt’.

Returns:

self (DualCmap object)

property name

Descriptive identifier for the DualCmap object.

property norm

Boolean indicator for value normalization