Cartopy map gridlines and tick labels

The Gridliner instance, often created by calling the cartopy.mpl.geoaxes.GeoAxes.gridlines() method on a cartopy.mpl.geoaxes.GeoAxes instance, has a variety of attributes which can be used to determine draw time behaviour of the gridlines and labels.

Important

The current Gridliner interface is likely to undergo a significant change in the versions following v0.6 in order to fix some of the underying limitations of the current implementation.

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)

Object 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.

• 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).

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.

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.

has_labels()

property label_artists

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.

right_labels

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

rotate_labels

Allow the rotation of labels.

top_labels

Whether to draw labels on the top of the map.

x_inline

Whether to draw x labels inline

xformatter

The Formatter to use for the lon labels.

xlabel_style

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

property xlabels_bottom

property xlabels_top

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

yformatter

The Formatter to use for the lat labels.

ylabel_style

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

property ylabels_left

property ylabels_right

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.

In this first example, gridines and tick labels are plotted in a non-rectangular projection, with most default values and no tuning of the gridliner attributes:

import matplotlib.pyplot as plt
import cartopy.crs as ccrs

rotated_crs = ccrs.RotatedPole(pole_longitude=120.0, pole_latitude=70.0)

ax = plt.axes(projection=rotated_crs)
ax.set_extent([-6, 3, 48, 58], crs=ccrs.PlateCarree())
ax.coastlines(resolution='50m')
ax.gridlines(draw_labels=True, dms=True, x_inline=False, y_inline=False)

plt.show()

(Source code)

The following contrived example makes use of many of the features of the Gridliner class to produce customized gridlines and tick labels:

import matplotlib.pyplot as plt
import matplotlib.ticker as mticker
import cartopy.crs as ccrs

from cartopy.mpl.ticker import (LongitudeFormatter, LatitudeFormatter,
                                LatitudeLocator)


ax = plt.axes(projection=ccrs.Mercator())
ax.coastlines()

gl = ax.gridlines(crs=ccrs.PlateCarree(), draw_labels=True,
                  linewidth=2, color='gray', alpha=0.5, linestyle='--')
gl.top_labels = False
gl.left_labels = False
gl.xlines = False
gl.xlocator = mticker.FixedLocator([-180, -45, 0, 45, 180])
gl.ylocator = LatitudeLocator()
gl.xformatter = LongitudeFormatter()
gl.yformatter = LatitudeFormatter()
gl.xlabel_style = {'size': 15, 'color': 'gray'}
gl.xlabel_style = {'color': 'red', 'weight': 'bold'}

plt.show()

(Source code)