stems.gis.grids module

Create and work with geospatial data tiling schemes

A tile scheme defines the grid which many products are based on. Tiling schemes define a projection, usually a projection applicable over a wide area, the size (in pixels) of each tile, and georeferencing information that defines the upper left coordinate and pixel sizes (thus defining the posting of each pixel). Tiles are defined by the tile grid coordinate (horizontal & vertical indices) that determines the number of tiles offset from the upper left coordinate of the tiling scheme, such that one can retrieve the real-world coordinate of a pixel if the tile grid index and pixel row/column within the tile is known.

class stems.gis.grids.Tile(index, crs, bounds, res, size)

Bases: object

A Tile

index

The (row, column) index of this tile in the grid

Type

tuple[int, int]

crs

The tile coordinate reference system

Type

rasterio.crs.CRS

bounds

The bounding box of the tile

Type

BoundingBox

res

Pixel X/Y resolution

Type

tuple[float, float]

size

Number of columns and rows in tile

Type

tuple[int, int]

property bbox

This tile’s bounding box geometry

Type

shapely.geometry.Polygon

coords(self, center=True)

Return y/x pixel coordinates

Parameters

center (bool, optional) – Return coordinates for pixel centers (default)

Returns

• np.ndarray – Y coordinates

• np.ndarray – X coordinates

classmethod from_dict(d)

Create a Tile from a dict

Parameters

d (dict) – Tile info, including “index”, “crs” (a WKT), “bounds”, “res”, and “size”

geojson(self, crs='epsg:4326')

Return this Tile’s geometry as GeoJSON

Parameters

crs (rasterio.crs.CRS) – Coordinate reference system of output. Defaults to EPSG:4326 per GeoJSON standard (RFC7946). If None, will return geometries in Tile’s CRS

Returns

This tile’s geometry and crs represented as GeoJSON

Return type

dict

References

1

https://tools.ietf.org/html/rfc7946#page-12

property height

The number of columns in this Tile

Type

int

property horizontal

The horizontal index of this tile in its tile specification

Type

int

to_dict(self)

Return a dict representing this Tile

Returns

This Tile as a dict (CRS will be a WKT for portability)

Return type

dict

property transform

The Affine transform for the tile

Type

affine.Affine

property vertical

The horizontal index of this tile in its tile specification

Type

int

property width

The number of columns in this Tile

Type

int

class stems.gis.grids.TileGrid(ul, crs, res, size, limits=None, name='Grid')

Bases: collections.abc.Mapping

A tile grid specification for gridding data

ul

Upper left X/Y coordinates

Type

tuple

crs

Coordinate system information

Type

rasterio.crs.CRS

res

Pixel X/Y resolution

Type

tuple

size

Number of pixels in X/Y dimensions for each tile

Type

tuple

limits

Maximum and minimum rows (vertical) and columns (horizontal) given as ((row_start, row_stop), (col_start, col_stop)). Used to limit access to Tiles beyond domain.

Type

tuple[tuple, tuple]

name

Name of this tiling scheme

Type

str, optional

bounds_to_tiles(self, bounds)

Yield Tile objects for this grid within a given bounds

Parameters

bounds (BoundingBox) – Input bounds. Bounds must be in the same CRS as the TileGrid.

Yields

tile (Tile) – Tiles that are within within provided bounds

property cols

the horizontal/column numbers for all tiles

Type

list[int]

classmethod from_dict(d)

Return a TileGrid from a dictionary

Parameters

d (dict) – Dictionary of class attributes (see __init__)

Returns

A new TileGrid according to parameters in d

Return type

TileGrid

geojson(self, crs='epsg:4326', rows=None, cols=None, rfc7946=False, skip_invalid=False)

Returns this grid of tiles as GeoJSON

Parameters

• crs (rasterio.crs.CRS) – Coordinate reference system of output. Defaults to EPSG:4326 per GeoJSON standard (RFC7946). If None, will return geometries in TileGrid’s CRS

• rows (Sequence[int], optional) – If this TileGrid was not given limits or if you want a subset of the tiles, specify the rows to map

• cols (Sequence[int], optional) – If this TileGrid was not given limits or if you want a subset of the tiles, specify the rows to map

• rfc7946 (bool, optional) – Return GeoJSON compliant with RFC7946. Helps fix GeoJSON that crosses the anti-meridian/datelines by splitting polygons into multiple as needed

• skip_invalid (bool, optional) – If True, checks for tile bounds for invalid geometries and will only include valid tile geometries.

Returns

GeoJSON

Return type

dict

property ncol

the number of columns in the TileGrid

Type

int

property nrow

the number of rows in the TileGrid

Type

int

point_to_tile(self, point)

Return a Tile containing a given point (x, y)

Parameters

point (tuple) – X/Y coordinates. Coordinates must be in the same CRS as the TileGrid.

Returns

tile – The intersecting :class`Tile`

Return type

stems.gis.grids.Tile

roi_to_tiles(self, roi)

Yield tiles within a Region of Interest (ROI) shapely geometry

Parameters

roi (Polygon, MultiPolygon, etc.) – A shapely geometry. Must be in the same CRS as the TileGrid.

Yields

iterable[Tile] – Yields Tile objects within provided Region of Interest

property rows

the vertical/row numbers for all tiles

Type

list[int]

to_dict(self)

Return this TileGrid as a dictionary (e.g., to serialize)

Returns

TileGrid attributes needed to re-initialize class

Return type

dict

property transform

the affine transform for this TileGrid

Type

affine.Affine

stems.gis.grids.load_grids(filename=None)

Retrieve tile grid specifications from a YAML file

Parameters

filename (str) – Filename of YAML data containing specifications. If None, will load grids packaged with module

Returns

Mapping of (name, TileGrid) pairs for tile grid specifications. By default, returns tile specifications included with this package

Return type

dict