Input/output capabilities (cartopy.io)

Cartopy has many built-in image and map acquisition capabilities. These capabilities allow the maps to be loaded, saved, and retrieved in various data formats.

Shapereader

This module provides a basic interface for accessing shapefiles. Combine the shapefile access of pyshp or fiona with the geometry representation of shapely:

>>> import cartopy.io.shapereader as shapereader
>>> filename = shapereader.natural_earth(resolution='110m',
...                                      category='physical',
...                                      name='geography_regions_points')
>>> reader = shapereader.Reader(filename)
>>> len(reader)
3
>>> records = list(reader.records())
>>> print(', '.join(str(r) for r in sorted(records[0].attributes.keys())))
comment, ... name, name_alt, ... region, ...
>>> print(records[0].attributes['name'])
Niagara Falls
>>> geoms = list(reader.geometries())
>>> print(type(geoms[0]))
<class 'shapely.geometry.point.Point'>
>>> reader.close()

Reader	Alias of the default available shapereader interface.
BasicReader(filename[, bbox])	Provide an interface for accessing the contents of a shapefile with the Python Shapefile Library (PyShp).
FionaReader(filename[, bbox])	Provides an interface for accessing the contents of a shapefile with the fiona library, which has a much faster reader than PyShp.
Record(shape, attributes, fields)	A single logical entry from a shapefile, combining the attributes with their associated geometry.
FionaRecord(geometry, attributes)	A single logical entry from a shapefile, combining the attributes with their associated geometry.
natural_earth([resolution, category, name])	Return the path to the requested natural earth shapefile, downloading and unzipping if necessary.
NEShpDownloader([url_template, ...])	Specialise cartopy.io.Downloader to download the zipped Natural Earth shapefiles and extract them to the defined location (typically user configurable).
gshhs([scale, level])	Return the path to the requested GSHHS shapefile, downloading and unzipping if necessary.
GSHHSShpDownloader([url_template, ...])	Specialise cartopy.io.Downloader to download the zipped GSHHS shapefiles and extract them to the defined location.

Image collections

Provides an interface for representing images.

Img(*args, **kwargs)	Represents a simple geo-located image.
ImageCollection(name, crs[, images])	Represents a collection of images at the same logical level.
NestedImageCollection(name, crs, collections)	Represents a complex nest of ImageCollections.

Image tiles

Implements image tile identification and fetching from various sources, automatically loading the proper tile and resolution depending on the desired domain.

The Matplotlib interface can make use of tile objects (defined below) via the cartopy.mpl.geoaxes.GeoAxes.add_image() method. For example, to add a MapQuest Open Aerial tileset to an existing axes at zoom level 2, do ax.add_image(MapQuestOpenAerial(), 2). An example of using tiles in this way can be found at the Map tile acquisition example.

OSM([desired_tile_form, user_agent, cache])
GoogleTiles([desired_tile_form, style, url, ...])
GoogleWTS([desired_tile_form, user_agent, cache])	Implement web tile retrieval using the Google WTS coordinate system.
MapQuestOSM([desired_tile_form, user_agent, ...])
MapQuestOpenAerial([desired_tile_form, ...])
MapboxStyleTiles(access_token, username, map_id)	Implement web tile retrieval from a user-defined Mapbox style.
MapboxTiles(access_token, map_id[, cache])	Implement web tile retrieval from Mapbox.
OrdnanceSurvey(apikey[, layer, ...])	Implement web tile retrieval from Ordnance Survey map data.
QuadtreeTiles([desired_tile_form, ...])	Implement web tile retrieval using the Microsoft WTS quadkey coordinate system.
StadiaMapsTiles(apikey[, style, resolution, ...])	Retrieves tiles from stadiamaps.com.
Stamen([style, desired_tile_form, cache])	Retrieves tiles from maps.stamen.com.

Open Geospatial Consortium (OGC) Clients

Implements RasterSource classes which can retrieve imagery from web services such as WMS and WMTS.

The matplotlib interface can make use of RasterSources via the cartopy.mpl.geoaxes.GeoAxes.add_raster() method, with additional specific methods which make use of this for WMS and WMTS (add_wms() and add_wmts()). An example of using WMTS in this way can be found at Interactive WMTS (Web Map Tile Service).

WFSGeometrySource(service, features[, ...])	Web Feature Service (WFS) retrieval for Cartopy.
WMSRasterSource(service, layers[, ...])	A WMS imagery retriever which can be added to a map.
WMTSRasterSource(wmts, layer_name[, ...])	A WMTS imagery retriever which can be added to a map.

Shuttle Radar Topography Mission (SRTM)

The Shuttle Radar Topography Mission (SRTM) is an international research effort that obtained digital elevation models on a near-global scale from 56S to 60N, to generate the most complete high-resolution digital topographic database of Earth prior to the release of the ASTER GDEM in 2009.

• Wikipedia (August 2012)

The SRTM data can be accessed through the cartopy.io.srtm module using classes and functions defined below.

SRTM1Source([downloader, max_nx, max_ny])	A source of SRTM1 data, which implements Cartopy's RasterSource interface.
SRTM3Source([downloader, max_nx, max_ny])	A source of SRTM3 data, which implements Cartopy's RasterSource interface.
SRTMDownloader(target_path_template[, ...])	Provide a SRTM download mechanism.
read_SRTM(fh)	Read the array of (y, x) elevation data from the given named file-handle.
read_SRTM1(fh)	Read the array of (y, x) elevation data from the given named file-handle.
read_SRTM3(fh)	Read the array of (y, x) elevation data from the given named file-handle.
add_shading(elevation, azimuth, altitude)	Add shading to SRTM elevation data, using azimuth and altitude of the sun.

Base classes and functions

These are the base classes in cartopy.io that new resources can leverage to implement a new reader or tile client. Together they provide a collection of sub-packages for loading, saving and retrieving various data formats.

Downloader(url_template, target_path_template)	Represents a resource, that can be configured easily, which knows how to acquire itself (perhaps via HTTP).
DownloadWarning	Issued when a file is being downloaded by a Downloader.
LocatedImage(image, extent)	Define an image and associated extent in the form:
RasterSource()	Define the cartopy raster fetching interface.
RasterSourceContainer(contained_source)	A container which simply calls the appropriate methods on the contained RasterSource.
PostprocessedRasterSource(contained_source, ...)	A RasterSource which wraps another, an then applies a post-processing step on the raster fetched from the contained source.
fh_getter(fh[, mode, needs_filename])	Convenience function for opening files.