cartopy.mpl.gridliner.Gridliner#

class cartopy.mpl.gridliner.Gridliner(axes, crs, draw_labels=False, xlocator=None, ylocator=None, collection_kwargs=None, xformatter=None, yformatter=None, dms=False, x_inline=None, y_inline=None, auto_inline=True, xlim=None, ylim=None, rotate_labels=None, xlabel_style=None, ylabel_style=None, labels_bbox_style=None, xpadding=5, ypadding=5, offset_angle=25, auto_update=None, formatter_kwargs=None)[source]#

Bases: Artist

Artist used by cartopy.mpl.geoaxes.GeoAxes.gridlines() to add gridlines and tick labels to a map.

Parameters:

  • axes – The cartopy.mpl.geoaxes.GeoAxes object to be drawn on.

  • crs – The cartopy.crs.CRS defining the coordinate system that the gridlines are drawn in.

  • draw_labels (optional) –

    Toggle whether to draw labels. For finer control, attributes of Gridliner may be modified individually. Defaults to False.

    • string: “x” or “y” to only draw labels of the respective coordinate in the CRS.

    • list: Can contain the side identifiers and/or coordinate types to select which ones to draw. For all labels one would use ["x", "y", "top", "bottom", "left", "right", "geo"].

    • dict: The keys are the side identifiers (“top”, “bottom”, “left”, “right”) and the values are the coordinates (“x”, “y”); this way you can precisely decide what kind of label to draw and where. For x labels on the bottom and y labels on the right you could pass in {"bottom": "x", "left": "y"}.

    Note that, by default, x and y labels are not drawn on left/right and top/bottom edges respectively, unless explicitly requested.

  • xlocator (optional) – A matplotlib.ticker.Locator instance which will be used to determine the locations of the gridlines in the x-coordinate of the given CRS. Defaults to None, which implies automatic locating of the gridlines.

  • ylocator (optional) – A matplotlib.ticker.Locator instance which will be used to determine the locations of the gridlines in the y-coordinate of the given CRS. Defaults to None, which implies automatic locating of the gridlines.

  • xformatter (optional) – A matplotlib.ticker.Formatter instance to format labels for x-coordinate gridlines. It defaults to None, which implies the use of a cartopy.mpl.ticker.LongitudeFormatter initiated with the dms argument, if the crs is of PlateCarree type.

  • yformatter (optional) – A matplotlib.ticker.Formatter instance to format labels for y-coordinate gridlines. It defaults to None, which implies the use of a cartopy.mpl.ticker.LatitudeFormatter initiated with the dms argument, if the crs is of PlateCarree type.

  • collection_kwargs (optional) – Dictionary controlling line properties, passed to matplotlib.collections.Collection. Defaults to None.

  • dms (bool) – When default locators and formatters are used, ticks are able to stop on minutes and seconds if minutes is set to True, and not fraction of degrees.

  • x_inline (optional) – Toggle whether the x labels drawn should be inline.

  • y_inline (optional) – Toggle whether the y labels drawn should be inline.

  • auto_inline (optional) – Set x_inline and y_inline automatically based on projection.

  • xlim (optional) – Set a limit for the gridlines so that they do not go all the way to the edge of the boundary. xlim can be a single number or a (min, max) tuple. If a single number, the limits will be (-xlim, +xlim).

  • ylim (optional) – Set a limit for the gridlines so that they do not go all the way to the edge of the boundary. ylim can be a single number or a (min, max) tuple. If a single number, the limits will be (-ylim, +ylim).

  • rotate_labels (optional, bool, str) –

    Allow the rotation of non-inline labels.

    • False: Do not rotate the labels.

    • True: Rotate the labels parallel to the gridlines.

    • None: no rotation except for some projections (default).

    • A float: Rotate labels by this value in degrees.

  • xlabel_style (dict) – A dictionary passed through to ax.text on x label creation for styling of the text labels.

  • ylabel_style (dict) – A dictionary passed through to ax.text on y label creation for styling of the text labels.

  • labels_bbox_style (dict) – bbox style for all text labels

  • xpadding (float) – Padding for x labels. If negative, the labels are drawn inside the map.

  • ypadding (float) – Padding for y labels. If negative, the labels are drawn inside the map.

  • offset_angle (float) – Difference of angle in degrees from 90 to define when a label must be flipped to be more readable. For example, a value of 10 makes a vertical top label to be flipped only at 100 degrees.

  • auto_update (bool, default=True) –

    Whether to redraw the gridlines and labels when the figure is updated.

    Deprecated since version 0.23: In future the gridlines and labels will always be redrawn.

  • formatter_kwargs (dict, optional) – Options passed to the default formatters. See LongitudeFormatter and LatitudeFormatter

Notes

The “x” and “y” labels for locators and formatters do not necessarily correspond to X and Y, but to the first and second coordinates of the specified CRS. For the common case of PlateCarree gridlines, these correspond to longitudes and latitudes. Depending on the projection used for the map, meridians and parallels can cross both the X axis and the Y axis.

property bottom_label_artists#

The bottom labels which were created at draw time

bottom_labels#

Whether to draw labels on the bottom of the map.

collection_kwargs#

A dictionary passed through to matplotlib.collections.LineCollection on grid line creation.

draw(renderer=None)[source]#

Draw the Artist (and its children) using the given renderer.

This has no effect if the artist is not visible (Artist.get_visible returns False).

Parameters:

renderer (RendererBase subclass.)

Notes

This method is overridden in the Artist subclasses.

property geo_label_artists#

The geo spine labels which were created at draw time

geo_labels#

Whether to draw labels near the geographic limits of the map.

get_tightbbox(renderer=None)[source]#

Like Artist.get_window_extent, but includes any clipping.

Parameters:

renderer (RendererBase subclass, optional) – renderer that will be used to draw the figures (i.e. fig.canvas.get_renderer())

Returns:

Bbox or None – The enclosing bounding box (in figure pixel coordinates). Returns None if clipping results in no intersection.

get_visible_children()[source]#

Return a list of the visible child Artists.

property label_artists#

All the labels which were created at draw time

labels_bbox_style#

bbox style for grid labels

property left_label_artists#

The left labels which were created at draw time

left_labels#

Whether to draw labels on the left hand side of the map.

n_steps#

The number of interpolation points which are used to draw the gridlines.

property right_label_artists#

The right labels which were created at draw time

right_labels#

Whether to draw labels on the right hand side of the map.

set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, zorder=<UNSET>)#

Set multiple properties at once.

Supported properties are

Properties:

agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: scalar or None animated: bool clip_box: BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None figure: Figure gid: str in_layout: bool label: object mouseover: bool path_effects: list of AbstractPathEffect picker: None or bool or float or callable rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None transform: Transform url: str visible: bool zorder: float

property top_label_artists#

The top labels which were created at draw time

top_labels#

Whether to draw labels on the top of the map.

x_inline#

Whether to draw x labels inline

property x_inline_label_artists#

The x-coordinate inline labels which were created at draw time

xformatter#

The Formatter to use for the lon labels.

property xlabel_artists#

The x-coordinate labels which were created at draw time

xlabel_style#

A dictionary passed through to ax.text on x label creation for styling of the text labels.

xline_artists#

The x gridlines which were created at draw time.

xlines#

Whether to draw the x gridlines.

xpadding#

The padding from the map edge to the x labels in points.

y_inline#

Whether to draw y labels inline

property y_inline_label_artists#

The y-coordinate inline labels which were created at draw time

yformatter#

The Formatter to use for the lat labels.

property ylabel_artists#

The y-coordinate labels which were created at draw time

ylabel_style#

A dictionary passed through to ax.text on y label creation for styling of the text labels.

yline_artists#

The y gridlines which were created at draw time.

ylines#

Whether to draw the y gridlines.

ypadding#

The padding from the map edge to the y labels in points.