fastplotlib.utils#

calculate_figure_shape(n_subplots)[source]#

Returns (n_rows, n_cols) from given number of subplots n_subplots

Return type:

tuple[int, int]

get_cmap(name, alpha=1.0, gamma=1.0)[source]#

Get a colormap as numpy array

Parameters:

  • name (str) – name of colormap

  • alpha (float) – alpha, 0.0 - 1.0

  • gamma (float) – gamma, 0.0 - 1.0

Returns:

[n_colors, 4], i.e. [n_colors, RGBA]

Return type:

np.ndarray

make_colors(n_colors, cmap, alpha=1.0)[source]#

Get colors from a colormap. The returned colors are uniformly spaced, except for qualitative colormaps where they are returned subsequently.

Parameters:

  • n_colors (int) – number of colors to get

  • cmap (str) – name of colormap

  • alpha (float, default 1.0) – alpha value

Returns:

shape is [n_colors, 4], where the last dimension is RGBA

Return type:

np.ndarray

make_colors_dict(labels, cmap, **kwargs)[source]#

Get a dict for mapping labels onto colors.

Parameters:

  • labels (Sequence[Any]) – labels for creating a colormap. Order is maintained if it is a list of unique elements.

  • cmap (str) – name of colormap

  • **kwargs – passed to make_colors()

Returns:

keys are labels, values are colors

Return type:

OrderedDict

Examples

from fastplotlib.utils import get_colors_dict

labels = ["l1", "l2", "l3"]
labels_cmap = get_colors_dict(labels, cmap="tab10")

# illustration of what the `labels_cmap` dict would look like:
# keep in mind that the tab10 cmap was chosen here

{
    "l1": <RGBA array for the blue 'tab10' color>,
    "l2": <RGBA array for the orange 'tab10' color>,
    "l3": <RGBA array for the green 'tab10' color>,
}

# another example with a non-qualitative cmap
labels_cmap_seismic = get_colors_dict(labels, cmap="bwr")

{
    "l1": <RGBA array for the blue 'bwr' color>,
    "l2": <RGBA array for the white 'bwr' color>,
    "l3": <RGBA array for the red 'bwr' color>,
}
make_pygfx_colors(colors, n_colors)[source]#

Parse and make colors array using pyfx.Color

Parameters:

  • colors (str, list, tuple, or np.ndarray) – pygfx parseable color

  • n_colors (int) – number of repeats of the color

Returns:

shape is [n_colors, 4], i.e. [n_colors, RGBA]

Return type:

np.ndarray

normalize_min_max(a)[source]#

normalize an array between 0 - 1

parse_cmap_values(n_colors, cmap_name, transform=None)[source]#
Parameters:

  • n_colors (int) – number of graphics in collection

  • cmap_name (str) – colormap name

  • transform (np.ndarray | List[int | float], optional) – cmap transform

Return type:

ndarray

quick_min_max(data, max_size=1000000.0)[source]#

Adapted from pyqtgraph.ImageView. Estimate the min/max values of data by subsampling.

Parameters:

  • data (np.ndarray or array-like with min and max attributes)

  • max_size (int, optional) – largest array size allowed in the subsampled array. Default is 1e6.

Returns:

(min, max)

Return type:

(float, float)

subsample_array(arr, max_size=1000000.0, ignore_dims=None)[source]#

Subsamples an input array while preserving its relative dimensional proportions.

The dimensions (shape) of the array can be represented as:

\[[d_1, d_2, \dots d_n]\]

The product of the dimensions can be represented as:

\[\prod_{i=1}^{n} d_i\]

To find the factor f by which to divide the size of each dimension in order to get max_size s we must solve for f in the following expression:

\[\prod_{i=1}^{n} \frac{d_i}{\mathbf{f}} = \mathbf{s}\]

The solution for f is is simply the nth root of the product of the dims divided by the max_size where n is the number of dimensions

\[\mathbf{f} = \sqrt[n]{\frac{\prod_{i=1}^{n} d_i}{\mathbf{s}}}\]
Parameters:

  • arr (np.ndarray) – input array of any dimensionality to be subsampled.

  • max_size (int, default 1e6) – maximum number of elements in subsampled array

  • ignore_dims (Sequence[int], optional) – List of dimension indices to exclude from subsampling (i.e. retain full resolution). For example, ignore_dims=[0] will avoid subsampling along the first axis.

Returns:

subsample of the input array

Return type:

np.ndarray

get_nearest_graphics(pos, graphics)[source]#

Returns the nearest graphics to the passed position pos in world space. Uses the distance between pos and the center of the bounding sphere for each graphic.

Parameters:

  • pos ((x, y) | (x, y, z)) – position in world space, z-axis is ignored when calculating L2 norms if pos is 2D

  • graphics (Sequence, i.e. array, list, tuple, etc. of Graphic | GraphicCollection) – the graphics from which to return a sorted array of graphics in order of closest to furthest graphic

Returns:

nearest graphics to pos in order

Return type:

ndarray[Graphic]

get_nearest_graphics_indices(pos, graphics)[source]#

Returns indices of the nearest graphics to the passed position pos in world space in order of closest to furtherst. Uses the distance between pos and the center of the bounding sphere for each graphic.

Parameters:

  • pos ((x, y) | (x, y, z)) – position in world space, z-axis is ignored when calculating L2 norms if pos is 2D

  • graphics (Sequence, i.e. array, list, tuple, etc. of Graphic | GraphicCollection) – the graphics from which to return a sorted array of graphics in order of closest to furthest graphic

Returns:

indices of the nearest nearest graphics to pos in order

Return type:

ndarray[int]