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.

add_raster(raster_source, **slippy_image_kwargs)

Add the given raster source to the GeoAxes.

raster_source

: cartopy.io.RasterSource like instance

raster_source may be any object which implements the RasterSource interface, including instances of objects such as WMSRasterSource and WMTSRasterSource. Note that image retrievals are done at draw time, not at creation time.

add_wms(wms, layers, wms_kwargs=None, **kwargs)

Add the specified WMS layer to the axes.

This function requires owslib and PIL to work.

wms

: string or owslib.wms.WebMapService instance

The web map service URL or owslib WMS instance to use.

layers

: string or iterable of string

The name of the layer(s) to use.

wms_kwargs

: dict or None

Passed through to the WMSRasterSource constructor’s getmap_extra_kwargs for defining getmap time keyword arguments.

All other keywords are passed through to the construction of the image artist. See imshow() for more details.

add_wmts(wmts, layer_name, wmts_kwargs=None, **kwargs)

Add the specified WMTS layer to the axes.

This function requires owslib and PIL to work.

Args:

• wmts - The URL of the WMTS, or an

  owslib.wmts.WebMapTileService instance.

• layer_name - The name of the layer to use.

Kwargs:

• wmts_kwargs - dict or None. Passed through to the

  WMTSRasterSource constructor’s gettile_extra_kwargs (e.g. time).

All other keywords are passed through to the construction of the image artist. See imshow() for more details.

background_img(name='ne_shaded', resolution='low', extent=None, cache=False)

Adds a background image to the map, from a selection of pre-prepared images held in a directory specified by the CARTOPY_USER_BACKGROUNDS environment variable. That directory is checked with func:self.read_user_background_images and needs to contain a JSON file which defines for the image metadata.

Kwargs:

• name - the name of the image to read according to the contents

  of the JSON file. A typical file might have, for instance: ‘ne_shaded’ : Natural Earth Shaded Relief ‘ne_grey’ : Natural Earth Grey Earth

• resolution - the resolution of the image to read, according to

  the contents of the JSON file. A typical file might have the following for each name of the image: ‘low’, ‘med’, ‘high’, ‘vhigh’, ‘full’.

• extent - using a high resolution background image, zoomed into

  a small area, will take a very long time to render as the image is prepared globally, even though only a small area is used. Adding the extent will only render a particular geographic region. Specified as [longitude start, longitude end,

  latitude start, latitude end].

  e.g. [-11, 3, 48, 60] for the UK or [167.0, 193.0, 47.0, 68.0] to cross the date line.

• cache - logical flag as to whether or not to cache the loaded

  images into memory. The images are stored before the extent is used.

background_patch = None

The patch that provides the filled background of the projection.

barbs(x, y, u, v, *args, **kwargs)

Plot a field of barbs.

Extra Kwargs:

• transform: cartopy.crs.Projection or matplotlib transform

  The coordinate system in which the vectors are defined.

• regrid_shape: int or 2-tuple of ints

  If given, specifies that the points where the arrows are located will be interpolated onto a regular grid in projection space. If a single integer is given then that will be used as the minimum grid length dimension, while the other dimension will be scaled up according to the target extent’s aspect ratio. If a pair of ints are given they determine the grid length in the x and y directions respectively.

• target_extent: 4-tuple

  If given, specifies the extent in the target CRS that the regular grid defined by regrid_shape will have. Defaults to the current extent of the map projection.

See matplotlib.pyplot.barbs() for details on arguments and keyword arguments.

Note

The vector components must be defined as grid eastward and grid northward.

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 the CRS of this Axes.

gridlines(crs=None, draw_labels=False, xlocs=None, ylocs=None, **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.

• xlocs

  An iterable of gridline locations or 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.

• ylocs

  An iterable of gridline locations or 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.

Returns:

A cartopy.mpl.gridliner.Gridliner instance.

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

hold_limits(*args, **kwds)

Keep track of the original view and data limits for the life of this context manager, optionally reverting any changes back to the original values after the manager exits.

hold

: bool (default True)

Whether to revert the data and view limits after the context manager exits.

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.

quiver(x, y, u, v, *args, **kwargs)

Plot a field of arrows.

Extra Kwargs:

• transform: cartopy.crs.Projection or matplotlib transform

  The coordinate system in which the vectors are defined.

• regrid_shape: int or 2-tuple of ints

  If given, specifies that the points where the arrows are located will be interpolated onto a regular grid in projection space. If a single integer is given then that will be used as the minimum grid length dimension, while the other dimension will be scaled up according to the target extent’s aspect ratio. If a pair of ints are given they determine the grid length in the x and y directions respectively.

• target_extent: 4-tuple

  If given, specifies the extent in the target CRS that the regular grid defined by regrid_shape will have. Defaults to the current extent of the map projection.

See matplotlib.pyplot.quiver() for details on arguments and other keyword arguments.

Note

The vector components must be defined as grid eastward and grid northward.

read_user_background_images(verify=True)

Reads the metadata in the specified CARTOPY_USER_BACKGROUNDS environment variable to populate the dictionaries for background_img.

If CARTOPY_USER_BACKGROUNDS is not set then by default the image in lib/cartopy/data/raster/natural_earth/ will be made available.

The metadata should be a standard JSON file which specifies a two level dictionary. The first level is the image type. For each image type there must be the fields: __comment__, __source__ and __projection__ and then an element giving the filename for each resolution.

An example JSON file can be found at: lib/cartopy/data/raster/natural_earth/images.json

set_boundary(path, transform=None, use_as_clip_path=True)

Given a path, update the outline_patch and background_patch to take its shape.

path

: matplotlib.path.Path

The path of the desired boundary.

transform

: None or matplotlib.transforms.Transform

The coordinate system of the given path. Currently this must be convertible to data coordinates, and therefore cannot extend beyond the limits of the axes’ projection.

use_as_clip_path

: bool

Whether axes.patch should be updated. Updating axes.patch means that any artists subsequently created will inherit clipping from this path, rather than the standard unit square in axes coordinates.

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.

streamplot(x, y, u, v, **kwargs)

Draws streamlines of a vector flow.

Extra Kwargs:

• transform: cartopy.crs.Projection or matplotlib transform

  The coordinate system in which the vector field is defined.

See matplotlib.pyplot.streamplot() for details on arguments and keyword arguments.

Note

The vector components must be defined as grid eastward and grid northward.

tissot(rad_km=500000.0, lons=None, lats=None, n_samples=80, **kwargs)

Adds Tissot’s indicatrices to the axes.

Kwargs:

• rad_km - The radius in km of the the circles to be drawn.

• lons - A numpy.ndarray, list or tuple of longitude values that

  locate the centre of each circle. Specifying more than one dimension allows individual points to be drawn whereas a 1D array produces a grid of points.

• lats - A numpy.ndarray, list or tuple of latitude values that

  that locate the centre of each circle. See lons.

• n_samples - Integer number of points sampled around the

  circumference of each circle.

**kwargs are passed through to class:ShapelyFeature.

class cartopy.mpl.geoaxes.GeoAxesSubplot

See cartopy.mpl.geoaxes.GeoAxes.

cartopy.mpl.patch.path_to_geos(path, force_ccw=False)

Creates a list of Shapely geometric objects from a matplotlib.path.Path.

Args:

• path

  A matplotlib.path.Path instance.

Kwargs:

• force_ccw

  Boolean flag determining whether the path can be inverted to enforce ccw.

Returns:

A list of shapely.geometry.polygon.Polygon, shapely.geometry.linestring.LineString and/or shapely.geometry.multilinestring.MultiLineString instances.

cartopy.mpl.patch.geos_to_path(shape)

Creates a list of matplotlib.path.Path objects that describe a shape.

Args:

• shape

  A list, tuple or single instance of any of the following types: shapely.geometry.point.Point, shapely.geometry.linestring.LineString, shapely.geometry.polygon.Polygon, shapely.geometry.multipoint.MultiPoint, shapely.geometry.multipolygon.MultiPolygon, shapely.geometry.multilinestring.MultiLineString, shapely.geometry.collection.GeometryCollection, or any type with a _as_mpl_path() method.

Returns:

A list of matplotlib.path.Path objects.