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())

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.

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, **kwargs)

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

**kwargs - are passed through to the created

matplotlib.collections.Collection allowing control of colors and linewidths etc.

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.

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.

Note

This method is limited to cylindrical projections.

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.

Note

This method is limited to cylindrical projections.

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.