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).
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.
Adds the given Feature instance to the axes.
Args:
An instance of Feature.
Add the given shapely geometries (in the given crs) to the axes.
Args:
A collection of shapely geometries.
The cartopy CRS in which the provided geometries are defined.
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 the given raster source to the GeoAxes.
Add the specified WMS layer to the axes.
This function requires owslib and PIL to work.
All other keywords are passed through to the construction of the image artist. See imshow() for more details.
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.
The patch that provides the filled background of the projection.
Plot a 2-D field of barbs.
Extra Kwargs:
The coordinate system in which the vectors are defined.
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.
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.
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 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.
Automatically adds gridlines to the axes, in the given coordinate system, at draw time.
Kwargs:
The cartopy._crs.CRS defining the coordinate system in which gridlines are drawn. Default is cartopy.crs.PlateCarree.
Label gridlines like axis ticks, around the edge.
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.
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.
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.
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.
The patch that provides the line bordering the projection.
The cartopy.crs.Projection of this GeoAxes.
Plot a 2-D field of arrows.
Extra Kwargs:
The coordinate system in which the vectors are defined.
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.
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.
Given a path, update the outline_patch and background_patch to take its shape.
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 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 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 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.
Add a standard image to the map.
Currently, the only (and default) option is a downsampled version of the Natural Earth shaded relief raster.
Draws streamlines of a vector flow.
Extra Kwargs:
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.
Creates a list of Shapely geometric objects from a matplotlib.path.Path.
Args:
A matplotlib.path.Path instance.
Kwargs:
Boolean flag determining whether the path can be inverted to enforce ccw.
Creates a list of matplotlib.path.Path objects that describe a shape.
Args:
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.