geoips.image_utils package#

Submodules#

geoips.image_utils.colormap_utils module#

Module for generating specific colormaps on the fly.

geoips.image_utils.colormap_utils.create_linear_segmented_colormap(cmapname, min_val, max_val, transition_vals, transition_colors)[source]#

Create a LinearSegmentedColormap instance.

Parameters:

cmapname (str) – Name to attach to the matplotlib.color ColorMap object
min_val (float) – Overall minimum value for the colormap Range must be normalized between 0 and 1
max_val (float) – Overall maximum value for the colormap Range must be normalized between 0 and 1
transition_vals (array-like) – A list of value ranges specified as tuples for generating a specific range of colors ie [(0, 10), (10, 30), (30, 60)]
transition_colors (array-like) – A list of color ranges specified as tuples for generating a specific range of colors corresponding to the transition_vals (see Notes below)

Returns:

cm – matplotlib colormap object

Return type:

LinearSegmentedColormap

Notes

Transition colors specified as:

[('yellow', 'orange'),
 ('pink', 'red'),
 ('violet', 'purple')]

Where:

TRANSITIONPOINT1 = 0.0
TRANSITIONPOINT4 = 1.0
cmdict = { 'red' :  ((TRANSITIONPOINT1, IGNORED, 1to2STARTCOLOR),
                 (TRANSITIONPOINT2, 1to2ENDCOLOR, 2to3STARTCOLOR),
                 (TRANSITIONPOINT3, 2to3ENDCOLOR, 3to4STARTCOLOR),
                 (TRANSITIONPOINT4, 3to4ENDCOLOR, IGNORED)),
       'green' :  ((TRANSITIONPOINT1, IGNORED, 1to2STARTCOLOR),
                 (TRANSITIONPOINT2, 1to2ENDCOLOR, 2to3STARTCOLOR),
                 (TRANSITIONPOINT3, 2to3ENDCOLOR, 3to4STARTCOLOR),
                 (TRANSITIONPOINT4, 3to4ENDCOLOR, IGNORED)),

       'blue' :  ((TRANSITIONPOINT1, IGNORED, 1to2STARTCOLOR),
                 (TRANSITIONPOINT2, 1to2ENDCOLOR, 2to3STARTCOLOR),
                 (TRANSITIONPOINT3, 2to3ENDCOLOR, 3to4STARTCOLOR),
                 (TRANSITIONPOINT4, 3to4ENDCOLOR, IGNORED)),
    }

geoips.image_utils.colormap_utils.from_ascii(fname, cmap_name=None, reverse=False)[source]#

Create a ListedColormap instance from an ASCII file of RGB values.

Parameters:

fname (str) – Full path to ascii RGB colortable file
cmap_name (str, default=None (basename(fname))) – Identifying name of colormap - if None, default to basename(fname)
reverse (bool, default=False) – If True, reverse the colormap

Returns:

cmap – If cmap_name not specified, the colormap name will be the os.path.basename of the file.

Return type:

ListedColormap object

Notes

Lines preceded by ‘#’ are ignored.
0-255 or 0-1.0 RGB values (0-255 values are normalized to 0-1.0 for matplotlib usage)
One white space delimited RGB value per line

geoips.image_utils.colormap_utils.set_matplotlib_colors_rgb()[source]#

Create matplotlib Colors parameters dictionary.

For rgb imagery, we require no color information (it is entirely specified by the RGB(A) arrays).

Returns:: mpl_colors_info – Specifies matplotlib Colors parameters for use in both plotting and colorbar generation. For RGBA arrays, all fields are “None”.
Return type:: dict

geoips.image_utils.colormap_utils.set_matplotlib_colors_standard(data_range, cmap_name='Greys', cbar_label=None, create_colorbar=True)[source]#

Set the matplotlib colors information.

For use in colorbar and image production.

Parameters:

data_range (list) – the minimum and maximum value for the data range [min_val, max_val]
cmap_name (str, default='Greys') – Specify the standard matplotlib colormap
cbar_label (str, optional) – If specified, use cbar_label string as colorbar label
create_colorbar (bool, default=True) – Specify whether the image should contain a colorbar or not

Returns:

mpl_colors_info – Specifies matplotlib Colors parameters for use in both plotting and colorbar generation. See geoips.image_utils.mpl_utils.create_colorbar for field descriptions.

Return type:

dict

geoips.image_utils.colormap_utils.set_mpl_colors_info_dict(cmap, norm, cbar_ticks, cbar_tick_labels=None, boundaries=None, cbar_label=None, cbar_spacing='proportional', create_colorbar=True, cbar_full_width=False)[source]#

Create the mpl_colors_info dictionary directly from passed arguments.

Parameters:

cmap (Colormap) – This is a valid matplotlib cm Colormap object that can be used for both plotting and colorbar creation.
norm (Normalize) – This is a valid matplotlib Normalize object that can be used for both plotting and colorbar creation.
cbar_ticks (list) – List of values where tick marks should be placed on colorbar
cbar_tick_labels (list, optional) – List of tick label values
boundaries (list, optional) – List of boundaries to use in matplotlib plotting and colorbar creation
cbar_label – The label for the colorbar
optional – The label for the colorbar
cbar_spacing (str, default='proportional') – One of ‘proportional’ or ‘uniform’
create_colorbar (bool, default=True) – True if colorbar should be created with the set of color info, False otherwise
cbar_full_width (bool, default=False) – True if colorbar should be full width of figure, center 50% if False

Returns:

mpl_colors_info – Dictionary of mpl_colors_info for use in plotting and colorbar creation.

Return type:

dict

geoips.image_utils.maps module#

matplotlib geographic map (basemap or cartopy) utilities.

geoips.image_utils.maps.check_feature_annotator(feature_annotator)[source]#

Check that the provided feature_annotator plugin has all required fields.

Parameters:: feature_annotator (YamlPlugin) – A feature annotator plugin.
Raises:: ValueError – if any field is missing

See also

geoips.image_utils.maps.get_feature_annotator: For complete list of fields, and appropriate defaults

geoips.image_utils.maps.check_gridline_annotator(gridline_annotator)[source]#

Check gridlines_info dictionary for that all required fields.

Parameters:: gridline_annotator (YamlPlugin) – A gridline annotator plugin instance.
Raises:: ValueError – If required field is missing

geoips.image_utils.maps.compute_lat_auto_spacing(area_def)[source]#: Compute automatic spacing for latitude lines based on area definition.

geoips.image_utils.maps.compute_lon_auto_spacing(area_def)[source]#: Compute automatic spacing for longitude lines based on area definition.

geoips.image_utils.maps.draw_features(mapobj, curr_ax, feature_annotator, zorder=None)[source]#

Draw cartopy features.

Draw features on specified cartopy map instance, based on specs found in the feature_annotator plugin.

Parameters:

mapobj (map object) – CRS object for plotting map features
curr_ax (matplotlib.axes._axes.Axes) – matplotlib Axes object for plotting map features
feature_annotator (dict) – Dictionary of parameters for plotting map features
zorder (int, optional) – The matplotlib zorder

See also

geoips.image_utils.maps.check_feature_annotator: for required dictionary entries and defaults.

geoips.image_utils.maps.draw_gridlines(mapobj, area_def, curr_ax, gridline_annotator, zorder=None)[source]#

Draw gridlines on map object.

Draw gridlines on a cartopy map object, as specified by a gridline_annotator plugin instance

Parameters:

mapobj (map object) – CRS object for plotting gridlines
area_def (AreaDefinition) – pyresample AreaDefinition object
curr_ax (matplotlib.axes._axes.Axes) – matplotlib Axes object for plotting gridlines
gridline_annotator (YamlPlugin) – A gridline_annotator plugin instance
zorder (int, optional) – The matplotlib zorder value

See also

geoips.image_utils.maps.get_gridlines_info_dict: For complete list of fields, and appropriate default

geoips.image_utils.maps.ellps2axis(ellps_name)[source]#

Get semi-major and semi-minor axis from ellipsis definition.

Parameters:

ellps_name (str) – Standard name of ellipsis

Returns:

avar (float) – semi-major axis
bvar (float) – semi-minor axis

geoips.image_utils.maps.is_crs(mapobj)[source]#

Determine if the map object we are using is a cartopy crs instance.

Parameters:: mapobj (map object) – Basemap or cartopy._PROJ4Projection object
Returns:: crs – True if it is a CRS object, False otherwise.
Return type:: bool

geoips.image_utils.maps.meridians(area_def, grid_size)[source]#

Calculate the meridians (longitude) that are within the input sector.

Parameters:

area_def (AreaDefinition) – pyresample AreaDefinition
grid_size (float) – grid spacing in degrees

Returns:

meridians_to_draw – longitude locations for gridlines

Return type:

list

geoips.image_utils.maps.parallels(area_def, grid_size)[source]#

Calculate the parallels (latitude) that fall within the input sector.

Parameters:

area_def (AreaDefinition) – pyresample AreaDefinition
grid_size (float) – grid spacing in degrees

Returns:

lat_ticks – latitude locations for gridlines

Return type:

list

geoips.image_utils.maps.set_gridlines_info_dict(gridlines_info, area_def)[source]#

Set plotting gridlines.

Set the final values for gridlines plotting params, pulling from argument and defaults.

Parameters:

gridlines_info (dict) – Dictionary of parameters for plotting gridlines. The following fields are available. If a field is not included in the dictionary, the field is added to the return dictionary and the default is used.
area_def (AreaDefinition) – pyresample AreaDefinition

Returns:

use_gridlines_info – gridlines_info dictionary, with fields as specified above.

Return type:

dict

Notes

Defaults specified as:

gridlines_info['grid_lat_spacing']      default auto calculated 5 lat grid lines
gridlines_info['grid_lon_spacing']      default auto calculated 5 lon grid lines
gridlines_info['grid_lat_xoffset']      default None (0.01 * image height)
gridlines_info['grid_lon_xoffset']      default None (0.01 * image width)
gridlines_info['grid_lat_yoffset']      default None (0.01 * image height)
gridlines_info['grid_lon_yoffset']      default None (0.01 * image width)
gridlines_info['grid_lat_fontsize']     default None (plot fontsize)
gridlines_info['grid_lon_fontsize']     default None (plot fontsize)
gridlines_info['left_label']            default True
gridlines_info['right_label']           default False
gridlines_info['top_label']             default True
gridlines_info['bottom_label']          default False
gridlines_info['grid_lat_linewidth']    default 1
gridlines_info['grid_lon_linewidth']    default 1
gridlines_info['grid_lat_color']        default 'black'
gridlines_info['grid_lon_color']        default 'black'
gridlines_info['grid_lat_dashes']       default [4, 2]
gridlines_info['grid_lon_dashes']       default [4, 2]

geoips.image_utils.mpl_utils module#

matplotlib utilities.

geoips.image_utils.mpl_utils.alpha_from_masked_arrays(arrays)[source]#

Convert from arrays to alpha.

Return an alpha transparency array based on the masks from a list of masked arrays. 0=transparent, 1=opaque

Parameters:: arrays (numpy.ndarray) – list of numpy masked arrays, must all be the same shape
Returns:: alp – the alpha transparency layer in matplotlib, values between 0 and 1, where 0 is fully transparent and 1 is fully opaque
Return type:: numpy.ndarray

geoips.image_utils.mpl_utils.create_colorbar(fig, mpl_colors_info)[source]#

Routine to create a single colorbar.

Parameters:

fig (matplotlib.figure.Figure) – Figure object to attach the colorbar - the colorbar will create its own ax
mpl_colors_info (dict) – Dictionary of matplotlib Color information, required fields in Notes below.

Returns:

cbar – This will have all the pertinent information for ensuring plot and colorbar use the same parameters

Return type:

matplotlib.colorbar.Colorbar

Notes

Required mpl_colors_info fields:

mpl_colors_info['cmap'] (Colormap):
    matplotlib.colors.Colormap object (LinearSegmentedColormap, etc)
    this is used to plot the image and to generated the colorbar
mpl_colors_info['norm'] (Normalize):
    matplotlib.colors.Normalize object (BoundaryNorm, Normalize, etc)
    again, this should be used to plot the data also
mpl_colors_info['cbar_ticks'] (list):
    list of floats - values requiring tick marks on the colorbar
mpl_colors_info['cbar_tick_labels'] (list)
    list of values to use to label tick marks, if other than
    found in cbar_ticks
mpl_colors_info['boundaries'] (list):
    if cmap_norm is BoundaryNorm, list of boundaries for discrete colors
mpl_colors_info['cbar_spacing'] (string):
    DEFAULT 'proportional', 'uniform' or 'proportional'
mpl_colors_info['cbar_label'] (string):
    string label for colorbar
mpl_colors_info['colorbar']: (bool)
    True if a colorbar should be included in the image, False if no cbar

Colorbar set as:

cbar_ax = fig.add_axes([<cbar_start_pos>, <cbar_bottom_pos>,
                        <cbar_width>, <cbar_height>])
cbar = fig.colorbar(mappable=matplotlib.cm.ScalarMappable(norm=cmap_norm,
                                                          cmap=mpl_cmap),
                    cax=cbar_ax,
                    norm=cmap_norm,
                    boundaries=cmap_boundaries,
                    spacing=cbar_spacing,
                    **cbar_kwargs)
cbar.set_ticks(cbar_ticks, labels=cbar_tick_labels, **set_ticks_kwargs)
if cbar_label:
    cbar.set_label(cbar_label, **set_label_kwargs)

geoips.image_utils.mpl_utils.create_figure_and_main_ax_and_mapobj(x_size, y_size, area_def, font_size=None, existing_mapobj=None, noborder=False)[source]#

Create a figure of x pixels horizontally and y pixels vertically.

Use information from matplotlib.rcParams.

Parameters:

x_size (int) – number pixels horizontally xsize = (float(x_size)/dpi)/(right_margin - left_margin)
y_size (int) – number pixels vertically ysize = (float(y_size)/dpi)/(top_margin - bottom_margin)
font_size (int) – matplotlib font size
area_def (AreaDefinition) – pyresample AreaDefinition object - used for initializing map object (basemap or cartopy)
existing_mapobj (CRS or basemap, optional) – If specified, do not regenerate mapobj. If None, create CRS or basemap object from specified area_def.
noborder (bool, default=False) – If true, use [0, 0, 1, 1] for axes (allowing for image exact shape of sector).

Returns:

fig (matplotlib.figure.Figure) – matplotlib Figure object to subsequently use for plotting imagery / colorbars / etc
main_ax (matplotlib.axes._axes.Axes) – matplotlib Axes object corresponding to the single main plotting area.
mapobj (mapobject) – cartopy crs or Basemap object for plotting

geoips.image_utils.mpl_utils.get_title_string_from_objects(area_def, xarray_obj, product_name_title, product_datatype_title=None, bg_xarray=None, bg_product_name_title=None, bg_datatype_title=None, title_copyright=None, title_formatter=None)[source]#

Get the title from object information.

Parameters:

area_def (AreaDefinition) – pyresample AreaDefinition object specifying the area covered by the current plot
xarray_obj (xarray.Dataset) – data used to produce product
product_name_title (str) – name to display for the title
product_datatype_title (str, optional) – the data type
bg_xarray (xarray, optional) – data used for background
bg_product_name_title (str, optional) – background product title
bg_datatype_title (str, optional) – background data type
title_copyright (str, optional) – string for copyright
title_formatter (str, optional) – format for title

Returns:

title_string – the title to use for matplotlib

Return type:

str

geoips.image_utils.mpl_utils.percent_unmasked_rgba(rgba)[source]#

Convert to percent.

Return percentage of array that is NOT fully transparent / masked (ie, non-zero values in the 4th dimension)

Parameters:: rgba (numpy.ndarray) – 4 dimensional array where the 4th dimension is the alpha transparency array: 1 is fully opaque, 0 is fully transparent
Returns:: coverage – Coverage in percentage, between 0 and 100.
Return type:: float

geoips.image_utils.mpl_utils.plot_image(main_ax, data, mapobj, mpl_colors_info, zorder=None)[source]#

Plot the “data” array and map in the matplotlib “main_ax”.

Parameters:

main_ax (Axes) – matplotlib Axes object for plotting data and overlays
data (numpy.ndarray)) – Numpy array of data to plot
mapobj (Map Object) – Basemap or Cartopy CRS instance
mpl_colors_info (dict) – Specifies matplotlib Colors parameters for use in both plotting and colorbar

See also

geoips.image_utils.mpl_utils.create_colorbar: for field descriptions for mpl_colors_info

geoips.image_utils.mpl_utils.plot_overlays(mapobj, curr_ax, area_def, feature_annotator=None, gridline_annotator=None, features_zorder=None, gridlines_zorder=None)[source]#

Plot specified coastlines and gridlines on the matplotlib axes.

Parameters:

mapobj (map object) – Basemap or CRS object for boundary and gridline plotting.
ax (matplotlib.axes._axes.Axes) – matplotlib Axes object for boundary and gridline plotting.
area_def (AreaDefinition) – pyresample AreaDefinition object specifying the area covered by the current plot
feature_annotator (YamlPlugin) – A feature annotator plugin instance.
gridline_annotator (YamlPlugin) – A gridlines annotator plugin instance.

geoips.image_utils.mpl_utils.remove_duplicates(fname, min_range)[source]#: Not implemented.

geoips.image_utils.mpl_utils.rgba_from_arrays(red, grn, blu, alp=None)[source]#

Return rgba from red, green, blue, and alpha arrays.

Parameters:

red (numpy.ndarray) – red gun values
grn (numpy.ndarray) – green gun values
blu (numpy.ndarray) – blue gun values
alp (numpy.ndarray, optional) – alpha values 1 is fully opaque, 0 is fully transparent If none, calculate alpha from red, grn, blu guns

Returns:

rgba – 4 layer dimensional numpy.ndarray

Return type:

numpy.ndarray

geoips.image_utils.mpl_utils.save_image(fig, out_fname, is_final=True, image_datetime=None, remove_duplicate_minrange=None, savefig_kwargs=None)[source]#

Save the image specified by the matplotlib figure “fig” to the filename out_fname.

Parameters:

fig (matplotlib.figure.Figure) – Figure object that needs to be written to a file.
out_fname (str) – full path to the output filename
is_final (bool, default=True) – Final imagery must set_axis_on for all axes. Non-final imagery must be transparent with set_axis_off for all axes, and no pad inches.

Notes

No return values (image is written to disk and IMAGESUCCESS is written to log file)

geoips.image_utils.mpl_utils.set_fonts(figure_y_size, font_size=None)[source]#

Set the fonts in the matplotlib.rcParams dictionary, using matplotlib.rc.

Parameters:: figure_y_size (int) – Font size set relative to number of pixels in the y direction

geoips.image_utils.mpl_utils.set_title(ax, title_string, figure_y_size, xpos=None, ypos=None, fontsize=None)[source]#

Set the title on figure axis “ax” to string “title_string”.

Parameters:

ax (Axes) – matplotlib.axes._axes.Axes object to add the title
title_string (str) – string specifying title to attach to axis “ax”
figure_y_size (int) – vertical size of the image, used to proportionally set the title size
xpos (float, optional) – x position of the title
ypos (float, optional) – y position of the title
fontsize (int, optional) – matplotlib font size

Module contents#

image_utils init file.