Cartopy matplotlib integration reference document

The primary class for integrating cartopy into matplotlib is the GeoAxes, which is a subclass of a normal matplotlib Axes. The GeoAxes class adds extra functionality to an axes which is specific to drawing maps. The majority of the methods which have been specialised from the original Axes are there to add improved -expected- behaviour, but some are to work around limitations that the standard matplotlib axes treats data in a Cartesian way (most of which either have, or will be, submitted back to the matplotlib project).

class cartopy.mpl.geoaxes.GeoAxes(*args, **kwargs)

A subclass of matplotlib.axes.Axes which represents a map Projection.

This class replaces the matplotlib Axes class when created with the projection keyword. For example:

# Set up a standard map for latlon data.
geo_axes = pyplot.axes(projection=cartopy.crs.PlateCarree())

# Set up an OSGB map.
geo_axes = pyplot.subplot(2, 2, 1, projection=cartopy.crs.OSGB())

When a source projection is provided to one of it’s plotting methods, using the transform keyword, the standard matplotlib plot result is transformed from source coordinates to the target projection. For example:

# Plot latlon data on an OSGB map.
pyplot.axes(projection=cartopy.crs.OSGB())
pyplot.contourf(x, y, data, transform=cartopy.crs.PlateCarree())

Create a GeoAxes object using standard matplotlib Axes args and kwargs.

Kwargs:

• map_projection - The target Projection of

  this Axes object.

All other args and keywords are passed through to matplotlib.axes.Axes.

add_feature(feature, **kwargs)

Adds the given Feature instance to the axes.

Args:

• feature:

  An instance of Feature.

Kwargs:

Keyword arguments to be used when drawing the feature. This allows standard matplotlib control over aspects such as ‘facecolor’, ‘alpha’, etc.

Returns:

• A cartopy.mpl.feature_artist.FeatureArtist instance responsible for drawing the feature.

add_geometries(geoms, crs, **kwargs)

Add the given shapely geometries (in the given crs) to the axes.

Args:

• geoms:

  A collection of shapely geometries.

• crs:

  The cartopy CRS in which the provided geometries are defined.

Kwargs:

Keyword arguments to be used when drawing this feature.

Returns:

• A cartopy.mpl.feature_artist.FeatureArtist instance responsible for drawing the geometries.

add_image(factory, *args, **kwargs)

Adds an image “factory” to the Axes.

Any image “factory” added, will be asked to retrieve an image with associated metadata for a given bounding box at draw time. The advantage of this approach is that the limits of the map do not need to be known when adding the image factory, but can be deferred until everything which can effect the limits has been added.

Currently an image “factory” is just an object with a image_for_domain method. Examples of image factories are cartopy.io.img_nest.NestedImageCollection and cartopy.io.image_tiles.GoogleTiles.

background_patch = None

The patch that provides the filled background of the projection.

coastlines(resolution='110m', color='black', **kwargs)

Adds coastal outlines to the current axes from the Natural Earth “coastline” shapefile collection.

Kwargs:

• resolution - a named resolution to use from the Natural Earth

  dataset. Currently can be one of “110m”, “50m”, and “10m”.

Note

Currently no clipping is done on the coastlines before adding them to the axes. This means, if very high resolution coastlines are being used, performance is likely to be severely effected. This should be resolved transparently by v0.5.

get_extent(crs=None)

Get the extent (x0, x1, y0, y1) of the map in the given coordinate system.

If no crs is given, the returned extents’ coordinate system will be assumed to be the Geodetic version of this axes’ projection.

gridlines(crs=None, draw_labels=False, **kwargs)

Automatically adds gridlines to the axes, in the given coordinate system, at draw time.

Kwargs:

• crs

  The cartopy._crs.CRS defining the coordinate system in which gridlines are drawn. Default is cartopy.crs.PlateCarree.

• draw_labels

  Label gridlines like axis ticks, around the edge.

Returns:

A cartopy.mpl.gridliner.Gridliner instance.

All other keywords control line properties. These are passed through to matplotlib.collections.Collection.

natural_earth_shp(name='land', resolution='110m', category='physical', **kwargs)

Adds the geometries from the specified Natural Earth shapefile to the Axes as a PathCollection.

**kwargs are passed through to the PathCollection constructor.

Returns the created PathCollection.

Note

Currently no clipping is done on the geometries before adding them to the axes. This means, if very high resolution geometries are being used, performance is likely to be severely effected. This should be resolved transparently by v0.5.

outline_patch = None

The patch that provides the line bordering the projection.

projection = None

The cartopy.crs.Projection of this GeoAxes.

set_extent(extents, crs=None)

Set the extent (x0, x1, y0, y1) of the map in the given coordinate system.

If no crs is given, the extents’ coordinate system will be assumed to be the Geodetic version of this axes’ projection.

set_global()

Set the extent of the Axes to the limits of the projection.

Note

In some cases where the projection has a limited sensible range the set_global method does not actually make the whole globe visible. Instead, the most appropriate extents will be used (e.g. Ordnance Survey UK will set the extents to be around the British Isles.

set_xticks(ticks, minor=False, crs=None)

Set the x ticks.

Args:

• ticks - list of floats denoting the desired position of x ticks.

Kwargs:

• minor - boolean flag indicating whether the ticks should be minor

  ticks i.e. small and unlabelled (default is False).

• crs - An instance of CRS indicating the

  coordinate system of the provided tick values. If no coordinate system is specified then the values are assumed to be in the coordinate system of the projection. Only transformations from one rectangular coordinate system to another rectangular coordinate system are supported.

Note

This interface is subject to change whilst functionality is added to support other map projections.

set_yticks(ticks, minor=False, crs=None)

Set the y ticks.

Args:

• ticks - list of floats denoting the desired position of y ticks.

Kwargs:

• minor - boolean flag indicating whether the ticks should be minor

  ticks i.e. small and unlabelled (default is False).

• crs - An instance of CRS indicating the

  coordinate system of the provided tick values. If no coordinate system is specified then the values are assumed to be in the coordinate system of the projection. Only transformations from one rectangular coordinate system to another rectangular coordinate system are supported.

Note

This interface is subject to change whilst functionality is added to support other map projections.

stock_img(name='ne_shaded')

Add a standard image to the map.

Currently, the only (and default) option is a downsampled version of the Natural Earth shaded relief raster.