Cartopy developer interfaces

Cartopy exposes several interfaces to help make it easier to add new functionality quickly and easily.

Data/Download API

In order to keep the size of a cartopy release low, the majority of data is not included as standard. This means that, when developing new features, it is often necessary to provide interfaces which can acquire data from external sources (normally via HTTP). The Downloader class has been designed to make this process as easy as possible for developers to extend, whilst still making it possible for users to configure in their own way.

class cartopy.io.Downloader(url_template, target_path_template, pre_downloaded_path_template='')

Represents a resource, that can be configured easily, which knows how to acquire itself (perhaps via HTTP).

The key interface method is path() - typically all external calls will be made to that method. To get hold of an appropriate Downloader instance the Downloader.from_config() static method should be considered.

Args:

url_template - The template of the full URL representing this

resource.

target_path_template - The template of the full path to the file

that this Downloader represents. Typically the path will be a subdirectory of config['data_dir'], but this is not a strict requirement. If the file does not exist when calling Downloader.path() it will be downloaded to this location.

Kwargs:

pre_downloaded_path_template - The template of a full path of a

file which has been downloaded outside of this Downloader which should be used as the file that this resource represents. If the file does not exist when Downloader.path() is called it will not be downloaded to this location (unlike the target_path_template argument).

FORMAT_KEYS = ('config',)

The minimum keys which should be provided in the format_dict argument for the path, url, target_path, pre_downloaded_path and acquire_resource methods.

path(format_dict)

Returns the path to a file on disk that this resource represents.

If the file doesn’t exist in pre_downloaded_path() then it will check whether it exists in target_path(), otherwise the resource will be downloaded via acquire_resouce() from url() to target_path().

Typically, this is the method that most applications will call, allowing implementors of new Downloaders to specialise acquire_resource().

Args:

format_dict - The dictionary which is used to replace

certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

url(format_dict)

The full URL that this resource represents.

Args:

format_dict - The dictionary which is used to replace

certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

target_path(format_dict)

The path on disk of the file that this resource represents, must either exist, or be writable by the current user. This method does not check either of these conditions.

Args:

format_dict - The dictionary which is used to replace

certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

pre_downloaded_path(format_dict)

The path on disk of the file that this resource represents, if it does not exist, then no further action will be taken with this path, and all further processing will be done using target_path() instead.

Args:

format_dict - The dictionary which is used to replace

certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

acquire_resource(target_path, format_dict)

Downloads, via HTTP, the file that this resource represents. Subclasses will typically override this method.

Args:

format_dict - The dictionary which is used to replace

certain template variables. Subclasses should document which keys are expected as a minimum in their FORMAT_KEYS class attribute.

static from_config(specification, config_dict=None)

The from_config static method implements the logic for acquiring a Downloader (sub)class instance from the config dictionary.

Args:

specification - should be iterable, as it will be traversed

in reverse order to find the most appropriate Downloader instance for this specification. An example specification is ('shapefiles', 'natural_earth') for the Natural Earth shapefiles.

Kwargs:

config_dict - typically this is left as None to use the

default cartopy.config “downloaders” dictionary.

Example:

>>> from cartopy.io import Downloader
>>>
>>> dnldr = Downloader('http://example.com/{name}', './{name}.txt')
>>> config = {('level_1', 'level_2'): dnldr}
>>> d1 = Downloader.from_config(('level_1', 'level_2', 'level_3'),
...                             config_dict=config)
>>> print(d1.url_template)
http://example.com/{name}
>>> print(d1.url({'name': 'item_name'}))
http://example.com/item_name

An example of specialising this class can be found in cartopy.io.shapereader.NEShpDownloader which enables the downloading of zipped shapefiles from the http://NaturalEarthData.com website. All known subclasses of Downloader are listed below for reference:

• cartopy.io.shapereader.NEShpDownloader
• cartopy.io.srtm.SRTM3Downloader

Raster images

The abstraction between retrieval and visualisation of raster data means that the cartopy.io.RasterSource class exists to retrieve an image (given sufficient context of projection, extent, resolution etc.) while in the matplotlib interface the cartopy.mpl.slippy_image_artist.SlippyImageArtist class feeds the appropriate information to the RasterSource and visualises it on a map. The orchestration in matplotlib is made more convenient to the user of a GeoAxes through the add_raster method. Anything which exposes the validate_projection and fetch_raster methods in the form described in RasterSource can be used as a slippy maps source in this way.

class cartopy.io.RasterSource

Defines the cartopy raster fetching interface.

A RasterSource instance is able to supply an image and associated extent (in the form img_array, (min_x, max_x, min_y, max_y)) through its fetch_raster() method.

As a result, further interfacing classes, such as cartopy.mpl.slippy_image_artist.SlippyImageArtist, can then make use of the interface for functionality such as interactive image retrieval with pan and zoom functionality.

fetch_raster(projection, extent, target_resolution)

Return the image and its extent given some constraining information.

projection : cartopy.crs.Projection

The desired projection of the image.

extent : iterable of length 4

The extent of the requested image in projected coordinates. The resulting image may not be defined exactly by these extents, and so the extent of the resulting image is also returned. The extents must be defined in the form (min_x, max_x, min_y, max_y).

target_resolution : iterable of length 2

The desired resolution of the image as ``(width, height)` in pixels.

img : array like object (e.g. PIL.Image.Image)

The representative image.

extent : iterable of length 4

The extent of the returned array in the form (min_x, max_x, min_y, max_y).

Note

Return (None, None) to indicate an invisible result.

validate_projection(projection)

Return whether this raster source can provide images in the specified projection.

projection : cartopy.crs.Projection

The desired projection of the image.

The SlippyImageArtist class provides panning and zooming of image sources which are able to re-retrieve data (such as that from a web service) for efficient and interactive visualisation. Generally the SlippyImageArtist is a developer’s interface, with users often creating a SlippyImageArtist instance through the GeoAxes’ add_raster() method.

class cartopy.mpl.slippy_image_artist.SlippyImageArtist(ax, raster_source, **kwargs)

A subclass of AxesImage which provides an interface for getting a raster from the given object with interactive slippy map type functionality.

Kwargs are passed to the AxesImage constructor.