pycolorbar.utils package

Submodules

pycolorbar.utils.cmap module

pycolorbar.utils.cmap.get_cmap_from_cpt(filepath)

Create a matplotlib.colors.Colormap from a color palette table (CPT) file.

Parameters:

filepath (str) – The file path to the CPT file.

pycolorbar.utils.cmap.get_colors_from_colorbar(image_path, N=10, skip_first=0, skip_last=None, orientation='vertical', plot_checker=False, plot_cmap=True)

Utility function to infer N equally spaced colors from the middle of a colorbar image.

This routine is useful to attempt reproducing colormaps appearing in scientific visualizations.

pycolorbar.utils.cmap.load_cpt(filepath)

Load a color palette table (CPT) from a file and convert it to a color dictionary.

CPT files are used by the Generic Mapping Tools software and Matlab.

Parameters:

filepath (str) – The file path to the CPT file.

Returns:

colorDict – A dictionary with normalized ‘red’, ‘green’, and ‘blue’ values. Each key holds a list of [x_norm, color_value, color_value] for interpolation.

Return type:

dict

Notes

The function supports both RGB and HSV color models. If HSV is used, it converts HSV to RGB. RGB values are normalized between 0 and 1.

pycolorbar.utils.cmap.plot_colors(colors, name='')

Plot a set of colors.

pycolorbar.utils.cmap.rgb_to_hex(rgb)

Convert RGB to hex.

pycolorbar.utils.directories module

Directory utility functions.

pycolorbar.utils.directories.list_files(dir_path, glob_pattern, recursive=False)

Return a list of filepaths (exclude directory paths).

pycolorbar.utils.directories.list_paths(dir_path, glob_pattern, recursive=False)

Return a list of filepaths and directory paths.

pycolorbar.utils.directories.remove_file_if_exists(filepath, force=False)

Remove a file if exists.

Raise an error if the filepath is an existing directory.

pycolorbar.utils.docstring module

pycolorbar.utils.docstring.copy_docstring(from_func)

Decorator function to assign a docstring from another function.

pycolorbar.utils.mpl module

Matplotlib utility functions.

pycolorbar.utils.mpl.get_mpl_colormaps()

Get the list of available colormaps in matplotlib.

pycolorbar.utils.mpl.get_mpl_named_colors()

Retrieves the list of valid named colors available in matplotlib.

Returns:

An array of valid named colors.

Return type:

numpy.ndarray

Notes

This function combines colors from TABLEAU_COLORS, BASE_COLORS, CSS4_COLORS, and XKCD_COLORS in matplotlib.

pycolorbar.utils.mpl_legend module

Utility to add legends or insets to a Matplotlib figure.

pycolorbar.utils.mpl_legend.add_colorbar_inset(*, ax, colorbar_func, colorbar_func_kwargs, projection=None, box_aspect=1, height=0.2, pad=0.005, loc='upper right', inside_figure=True, optimize_layout=True, fancybox=False, fancybox_pad=0, fancybox_fc='white', fancybox_ec='none', fancybox_lw=0.5, fancybox_alpha=0.4, fancybox_shape='square')

Helper function to add an inset Axes and plot a colorbar within it.

Parameters:

• ax (matplotlib.axes.Axes) – Parent Axes to which the inset will be added.

• colorbar_func (callable) – A function that takes cax and extra keyword arguments to plot the actual colorbar (e.g., plot_bivariate_colorbar).

• colorbar_func_kwargs (dict) – Extra kwargs passed directly to colorbar_func.

• projection (str or None, optional) – Projection type of the inset Axes, passed to ax.inset_axes().

• box_aspect (float, optional) – Aspect ratio of the inset Axes. Default is 1.

• height (float, optional) – Height of the inset as a fraction of the main Axes. Default is 0.2.

• pad (float, optional) – Padding between the inset and main Axes in figure coordinates. Default is 0.005.

• loc (str or tuple, optional) – Location of the inset. Default is ‘upper right’.

• inside_figure (bool, optional) – Whether inset is inside the figure region. Default is True.

• optimize_layout (bool, optional) – Whether to auto-adjust the inset position for ticklabels. Default is True. NOTE: If True, do not call fig.tight_layout() afterwards.

• fancybox (bool, optional) – Whether to draw a fancy box behind the inset. Default is False.

• fancybox_pad (float, optional) – Padding of the fancy box in figure coordinates. Default is 0.

• fancybox_fc (str, optional) – Face color of the fancy box. Default is ‘white’.

• fancybox_ec (str, optional) – Edge color of the fancy box. Default is ‘none’.

• fancybox_lw (float, optional) – Line width of the fancy box. Default is 0.5.

• fancybox_alpha (float, optional) – Alpha of the fancy box. Default is 0.4.

• fancybox_shape ({'circle', 'square'}, optional) – Shape of the fancy box. Default is ‘square’.

Returns:

The image (or artist) returned by colorbar_func.

Return type:

matplotlib.image.AxesImage

pycolorbar.utils.mpl_legend.add_fancybox(ax, bbox, fc='white', ec='none', lw=0.5, alpha=0.5, pad=0, shape='square', zorder=None)

Add fancy box.

The bbox can be derived using get_tightbbox_position(ax_legend).

pycolorbar.utils.mpl_legend.get_inset_bounds(ax, loc='upper right', inset_height=0.2, inside_figure=True, aspect_ratio=1, border_pad=0)

Calculate the bounds for an inset axes in a matplotlib figure.

This function computes the normalized figure coordinates for placing an inset axes within a figure, based on the specified location, size, and whether the inset should be fully inside the figure bounds. It is designed to be used with matplotlib figures to facilitate the addition of insets (e.g., for maps or zoomed plots) at predefined positions.

Parameters:

• loc (str or tuple) – The location of the inset within the figure. Valid options are 'lower left', 'lower right', 'upper left', and 'upper right'. The default is 'upper right'. Alternatively you can specify a tuple with the (x0, y0) figure coordinates.

• inset_height (float) – The size of the inset height, specified as a fraction of the figure’s height. For example, a value of 0.2 indicates that the inset’s height will be 20% of the figure’s height. The aspect ratio will govern the inset_width.

• aspect_ratio (float, optional) – The desired width-to-height ratio of the inset figure. A value greater than 1 indicates an inset figure wider than it is tall, and a value less than 1 indicates an inset figure taller than it is wide. The default value is 1.0, indicating a square inset figure.

• inside_figure (bool, optional) – Determines whether the inset is constrained to be fully inside the figure bounds. If True (default), the inset is placed fully within the figure. If False, the inset can extend beyond the figure’s edges, allowing for a half-outside placement. This argument is used only if ‘loc’ is specified as a string.

• border_pad (int, float or tuple) – The padding to apply on the x and y direction. If a single value is supplied, applies the same padding in both directions. This arguments is used only if ‘loc’ is specified as a string.

Returns:

inset_bounds – The calculated bounds of the inset, in the format [x0, y0, width, height], where x0 and y0 are the normalized figure coordinates of the lower left corner of the inset, and width and height are the normalized width and height of the inset, respectively.

Return type:

list of float

pycolorbar.utils.mpl_legend.get_location_origin(loc, width, height, x_pad, y_pad)

Get the origin coordinates (x0, y0) for a given location on a plot.

Parameters:

• loc (str) – The location string specifying the position. Accepted values are: ‘upper right’, ‘upper left’, ‘lower right’, ‘lower left’, ‘center left’, ‘center right’, ‘upper center’, ‘lower center’.

• width (float) – The width of the element to be positioned.

• height (float) – The height of the element to be positioned.

• x_pad (float) – The horizontal padding from the specified location.

• y_pad (float) – The vertical padding from the specified location.

Returns:

• x0 (float) – The x-coordinate of the origin.

• y0 (float) – The y-coordinate of the origin.

pycolorbar.utils.mpl_legend.get_locations_acronyms()

Get list of valid location acronyms.

pycolorbar.utils.mpl_legend.get_tightbbox_position(ax)

Return the axis Bbox position in figure coordinates.

This Bbox includes also the area with axis ticklabels, labels and the title.

pycolorbar.utils.mpl_legend.optimize_inset_position(ax, cax, pad=0)

Optimize the inset position to not touch the main plot region.

pycolorbar.utils.mpl_legend.pad_cax(cax, pad_left=0, pad_right=0, pad_top=0, pad_bottom=0)

Add padding to a colorbar axis based on percentages of current dimensions.

Parameters:

• cax (matplotlib.axes.Axes) – The colorbar axes to adjust

• pad_left (float) – Padding values as percentage of the current dimension (e.g., 10 = 10% padding)

• pad_right (float) – Padding values as percentage of the current dimension (e.g., 10 = 10% padding)

• pad_top (float) – Padding values as percentage of the current dimension (e.g., 10 = 10% padding)

• pad_bottom (float) – Padding values as percentage of the current dimension (e.g., 10 = 10% padding)

pycolorbar.utils.mpl_legend.resize_cax(cax, width_percent=None, height_percent=None, x_alignment='left', y_alignment='center')

Resize a colorbar axis based on percentages with specified alignment.

Parameters:

• cax (matplotlib.axes.Axes) – The colorbar axes to adjust

• width_percent (float or None) – If provided, new width as percentage of the original (e.g., 80 = 80% of original width)

• height_percent (float or None) – If provided, new height as percentage of the original (e.g., 90 = 90% of original height)

• x_alignment (str) – Horizontal alignment: ‘left’, ‘center’, or ‘right’

• y_alignment (str) – Vertical alignment: ‘bottom’, ‘center’, or ‘top’

pycolorbar.utils.yaml module

YAML utility.

pycolorbar.utils.yaml.list_yaml_files(directory)

List all YAML files in a directory.

pycolorbar.utils.yaml.read_yaml(filepath: str) → dict

Read a YAML file into a dictionary.

Parameters:

filepath (str) – Input YAML file path.

Returns:

Dictionary with the attributes read from the YAML file.

Return type:

dict

pycolorbar.utils.yaml.write_yaml(dictionary, filepath, sort_keys=False)

Write a dictionary into a YAML file.

Parameters:

dictionary (dict) – Dictionary to write into a YAML file.

Module contents