cartopy.io.img_nest.NestedImageCollection#

class cartopy.io.img_nest.NestedImageCollection(name, crs, collections, _ancestry=None)[source]#

Represents a complex nest of ImageCollections.

On construction, the image collections are scanned for ancestry, leading to fast image finding capabilities.

A complex (and time consuming to create) NestedImageCollection instance can be saved as a pickle file and subsequently be (quickly) restored.

There is a simplified creation interface for NestedImageCollection from_configuration for more detail.

Parameters:

  • name – The name of the nested image collection.

  • crs – The native Projection of all the image collections.

  • collections – A list of one or more ImageCollection instances.

find_images(target_domain, target_z, start_tiles=None)[source]#

A generator that finds all images that overlap the bounded target location.

Parameters:

  • target_domain – A LineString instance that specifies the target location requiring image coverage.

  • target_z – The name of the target ImageCollection which specifies the target zoom level (resolution) of the required images.

  • start_tiles (optional) – A list of one or more tuple pairs, composed of a ImageCollection name and an Img instance, from which to search for the target images.

Returns:

generator – A generator tuple pair composed of a ImageCollection name and an Img instance.

classmethod from_configuration(name, crs, name_dir_pairs, glob_pattern='*.tif', img_class=<class 'cartopy.io.img_nest.Img'>)[source]#

Create a NestedImageCollection instance given the list of image collection name and directory path pairs.

This is very convenient functionality for simple configuration level creation of this complex object.

For example, to produce a nested collection of OS map tiles:

files = [['OS 1:1,000,000', '/directory/to/1_to_1m'],
         ['OS 1:250,000', '/directory/to/1_to_250k'],
         ['OS 1:50,000', '/directory/to/1_to_50k'],
        ]
r = NestedImageCollection.from_configuration('os',
                                             ccrs.OSGB(),
                                             files)
Parameters:

  • name – The name for the NestedImageCollection instance.

  • crs – The Projection of the image collection.

  • name_dir_pairs – A list of image collection name and directory path pairs.

  • glob_pattern (optional) – The image collection filename glob pattern. Defaults to '*.tif'.

  • img_class (optional) – The class of images created in the image collection.

Returns:

A NestedImageCollection instance.

Warning

The list of image collection name and directory path pairs must be given in increasing resolution order i.e. from low resolution to high resolution.

get_image(collection_image)[source]#

Retrieve the data of the target image from file.

Parameters:

collection_image – A tuple pair containing the target ImageCollection name and Img instance.

Returns:

img_data, img.extent, img.origin – A tuple containing three items, consisting of the associated image file data, the (x_lower, x_upper, y_lower, y_upper) extent of the image, and the image origin.

Note

The format of the retrieved image file data is controlled by desired_tile_form, which defaults to ‘RGB’ format.

image_for_domain(target_domain, target_z)[source]#

Determine the image that provides complete coverage of target location.

The composed image is merged from one or more image tiles that overlay the target location and provide complete image coverage of the target location.

Parameters:

  • target_domain – A LineString instance that specifies the target location requiring image coverage.

  • target_z – The name of the target :class`~cartopy.io.img_nest.ImageCollection` which specifies the target zoom level (resolution) of the required images.

Returns:

img, extent, origin – A tuple containing three items, consisting of the target location numpy.ndarray image data, the (x-lower, x-upper, y-lower, y-upper) extent of the image, and the origin for the target location.

subtiles(collection_image)[source]#

Find the higher resolution image tiles that compose this parent image tile.

Parameters:

collection_image – A tuple pair containing the parent ImageCollection name and Img instance.

Returns:

iterator – An iterator of tuple pairs containing the higher resolution child ImageCollection name and Img instance that compose the parent.