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)[source]¶ A subclass of
matplotlib.axes.Axes
which represents a mapProjection
.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.
 map_projection  The target
All other args and keywords are passed through to
matplotlib.axes.Axes
.
add_feature
(feature, **kwargs)[source]¶ 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.
 A

add_geometries
(geoms, crs, **kwargs)[source]¶ 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)[source]¶ 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 arecartopy.io.img_nest.NestedImageCollection
andcartopy.io.image_tiles.GoogleTiles
.

add_raster
(raster_source, **slippy_image_kwargs)[source]¶ 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 asWMSRasterSource
andWMTSRasterSource
. Note that image retrievals are done at draw time, not at creation time.
 raster_source :

add_wms
(wms, layers, wms_kwargs=None, **kwargs)[source]¶ 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’sgetmap_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. wms : string or

add_wmts
(wmts, layer_name, **kwargs)[source]¶ 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.
All other keywords are passed through to the construction of the image artist. See
imshow()
for more details.

background_patch
= None¶ The patch that provides the filled background of the projection.

barbs
(x, y, u, v, *args, **kwargs)[source]¶ Plot a 2D field of barbs.
Extra Kwargs:
 transform:
cartopy.crs.Projection
or matplotlib transform The coordinate system in which the vectors are defined.
 transform:
 regrid_shape: int or 2tuple 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: 4tuple
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)[source]¶ 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)[source]¶ 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)[source]¶ 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 iscartopy.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 xcoordinate 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 ycoordinate of the given CRS. Defaults to None, which implies automatic locating of the gridlines.
Returns:
Acartopy.mpl.gridliner.Gridliner
instance.All other keywords control line properties. These are passed through to
matplotlib.collections.Collection
.

hold_limits
(*args, **kwds)[source]¶ 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)[source]¶ Adds the geometries from the specified Natural Earth shapefile to the Axes as a
PathCollection
.**kwargs
are passed through to thePathCollection
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)[source]¶ Plot a field of arrows.
Extra Kwargs:
 transform:
cartopy.crs.Projection
or matplotlib transform The coordinate system in which the vectors are defined.
 transform:
 regrid_shape: int or 2tuple 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: 4tuple
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.

set_boundary
(path, transform=None, use_as_clip_path=True)[source]¶ Given a path, update the
outline_patch
andbackground_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.
 path :

set_extent
(extents, crs=None)[source]¶ 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
()[source]¶ 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)[source]¶ 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.
 crs  An instance of
Note
This interface is subject to change whilst functionality is added to support other map projections.

set_yticks
(ticks, minor=False, crs=None)[source]¶ 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.
 crs  An instance of
Note
This interface is subject to change whilst functionality is added to support other map projections.

stock_img
(name='ne_shaded')[source]¶ 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)[source]¶ 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.
 transform:
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)[source]¶ 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
¶

cartopy.mpl.patch.
path_to_geos
(path, force_ccw=False)[source]¶ 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/orshapely.geometry.multilinestring.MultiLineString
instances.

cartopy.mpl.patch.
geos_to_path
(shape)[source]¶ 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.