GeoContext

Back to Scenes

Datasets in the Descartes Labs catalog have many different resolutions and projections. In two different images, even covering the same place on Earth, the pixels (i, j) usually correspond to two different points on the ground.

GeoContexts are a way to ensure multiple images from different sources are spatially compatible—that is, they all have the same shape (same width and height, in pixels), and the same pixel in each image corresponds to the same area on Earth.

They do this by simply capturing all the spatial parameters that affect how imagery is rasterized—namely output resolution, coordinate reference system, and bounding box—in one object that can be passed into different method calls. In typical use, these contexts are created for you with reasonable defaults, so you only need to understand the different parameters when you need more control.

The different subclasses of GeoContext implement different functionality.

  • AOI clips to arbitrary geometry, and lets you specify any output resolution and projection.

  • DLTile helps you split large regions up into a grid of any spacing and resolution, and represents a single tile in that grid, in UTM projection.

Classes:

AOI([geometry, resolution, crs, …])

A GeoContext that clips scenes to a geometry, and/or to square bounds, with any output resolution and CRS.

DLTile(dltile_dict[, all_touched])

A GeoContext that clips and projects Scenes to a single DLTile.

GeoContext([all_touched])

Specifies spatial parameters to use when loading a raster from the Descartes Labs catalog.

XYZTile(x, y, z[, all_touched])

A GeoContext for XYZ tiles, such as those used in web maps.

class AOI(geometry=None, resolution=None, crs=None, align_pixels=True, bounds=None, bounds_crs='EPSG:4326', shape=None, all_touched=False)[source]

A GeoContext that clips scenes to a geometry, and/or to square bounds, with any output resolution and CRS.

Examples

cutline_aoi = dl.scenes.AOI(my_geometry, resolution=40)
aoi_with_cutline_disabled = cutline_aoi.assign(geometry=None)
no_cutline_aoi = dl.scenes.AOI(geometry=None, resolution=15, bounds=(-40, 35, -39, 36))
aoi_without_auto_bounds = dl.scenes.AOI(geometry=my_geometry, resolution=15, bounds=(-40, 35, -39, 36))
aoi_with_specific_pixel_dimensions = dl.scenes.AOI(geometry=my_geometry, shape=(200, 400))
Parameters
  • geometry (GeoJSON-like dict, object with __geo_interface__; optional) – Clip scenes to this geometry. Coordinates must be WGS84 (lat-lon). If None, scenes will just be clipped to bounds.

  • resolution (float, optional) – Distance, in units of the CRS, that the edge of each pixel represents on the ground. Can only specify one of Resolution and shape.

  • crs (str, optional) – Coordinate Reference System into which scenes will be projected, expressed as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string

  • align_pixels (bool, optional, default True) –

    If True, this ensures that, in different Scenes rasterized with this same AOI GeoContext, pixels (i, j) correspond to the same area in space. This is accomplished by snapping the coordinates of the origin (top-left corner of top-left pixel) to a non-fractional interval of Resolution.

    If align_pixels is False, when using scenes with different native resolutions and/or projections, pixels at the same indicies can be misaligned by a fraction of Resolution (i.e. correspond to slighly different coordinates in space).

    However, this requires warping of the original image, which can be undesireable when you want to work with the original data in its native resolution and projection.

  • bounds (4-tuple, optional) – Clip scenes to these (min_x, min_y, max_x, max_y) bounds, expressed in bounds_crs (which defaults to WGS84 lat-lon). bounds are automatically computed from geometry if not specified. Otherwise, bounds are required.

  • bounds_crs (str, optional, default "EPSG:4326") – The Coordinate Reference System of the bounds, given as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string.

  • shape (2-tuple, optional) – (rows, columns), in pixels, the output raster should fit within; the longer side of the raster will be min(shape). Can only specify one of Resolution and shape.

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Attributes:

__geo_interface__

geometry as a GeoJSON Geometry dict, otherwise bounds as a GeoJSON Polygon dict if geometry is None and bounds_crs is EPSG:4326, otherwise raises RuntimeError.

align_pixels

If True, this ensures that, in different Scenes rasterized with this same AOI GeoContext, pixels (i, j) correspond to the same area in space.

all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

bounds

Clip scenes to these (min_x, min_y, max_x, max_y) bounds, expressed in the coordinate reference system in bounds_crs.

bounds_crs

The coordinate reference system of the bounds, given as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string.

crs

Coordinate reference system into which scenes will be projected, expressed as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string.

geometry

Clip scenes to this geometry Coordinates must be WGS84 (lat-lon).

raster_params

The properties of this AOI, as keyword arguments to use for ndarray or raster.

resolution

Distance, in units of the CRS, that the edge of each pixel represents on the ground.

shape

(rows, columns), in pixels, the output raster should fit within; the longer side of the raster will be min(shape).

Methods:

assign([geometry, resolution, crs, …])

Return a copy of the AOI with the given values assigned.

assign(geometry='unchanged', resolution='unchanged', crs='unchanged', align_pixels='unchanged', bounds='unchanged', bounds_crs='unchanged', shape='unchanged', all_touched='unchanged')[source]

Return a copy of the AOI with the given values assigned.

Note

If you are assigning a new geometry and want bounds to updated as well, use bounds="update". This will also change bounds_crs to EPSG:4326, since the geometry’s coordinates are in WGS84 decimal degrees, so the new bounds determined from those coordinates must be in that CRS as well.

If you assign bounds without changing bounds, the new AOI GeoContext will produce rasters with the same shape and covering the same spatial area as the old one, just with pixels masked out that fall outside your new geometry.

Returns

new

Return type

AOI

property __geo_interface__

geometry as a GeoJSON Geometry dict, otherwise bounds as a GeoJSON Polygon dict if geometry is None and bounds_crs is EPSG:4326, otherwise raises RuntimeError.

Type

dict

property align_pixels

If True, this ensures that, in different Scenes rasterized with this same AOI GeoContext, pixels (i, j) correspond to the same area in space. This is accomplished by snapping the coordinates of the origin (top-left corner of top-left pixel) to a non-fractional interval of Resolution.

If align_pixels is False, when using scenes with different native resolutions and/or projections, pixels at the same indicies can be misaligned by a fraction of resolution (i.e. correspond to slighly different coordinates in space).

However, this requires warping of the original image, which can be undesireable when you want to work with the original data in its native resolution and projection.

Type

bool

property all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Type

bool

property bounds

Clip scenes to these (min_x, min_y, max_x, max_y) bounds, expressed in the coordinate reference system in bounds_crs.

Type

tuple

property bounds_crs

The coordinate reference system of the bounds, given as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string.

Type

str

property crs

Coordinate reference system into which scenes will be projected, expressed as an EPSG code (like EPSG:4326), a PROJ.4 definition, or an OGC CRS Well-Known Text string.

Type

str

property geometry

Clip scenes to this geometry Coordinates must be WGS84 (lat-lon). If None, scenes will just be clipped to bounds.

Type

shapely geometry

property raster_params

The properties of this AOI, as keyword arguments to use for ndarray or raster.

Raises ValueError if bounds, crs, bounds_crs, Resolution, or align_pixels is None.

Type

dict

property resolution

Distance, in units of the CRS, that the edge of each pixel represents on the ground.

Type

float

property shape

(rows, columns), in pixels, the output raster should fit within; the longer side of the raster will be min(shape).

Type

tuple

class DLTile(dltile_dict, all_touched=False)[source]

A GeoContext that clips and projects Scenes to a single DLTile.

DLTiles allow you to define a grid of arbitrary spacing, resolution, and overlap that can cover the globe. DLTiles are always in a UTM projection.

Example

>>> import descarteslabs as dl
>>> from descarteslabs.scenes import DLTile
>>> tile = DLTile.from_latlon(
...    lat=35.691,
...    lon=-105.944,
...    tilesize=512,
...    resolution=10,
...    pad=0
... )
>>> scenes, ctx = dl.scenes.search(tile, "landsat:LC08:PRE:TOAR")  
>>> Scenes  
    SceneCollection of 93 scenes
      * Dates: Apr 19, 2013 to Apr 14, 2017
      * Products: landsat:LC08:PRE:TOAR: 93
>>> ctx     
DLTile(key='512:0:10.0:13:-17:771',
   resolution=10.0,
   tilesize=512,
   pad=0,
   crs='EPSG:32613',
   bounds=(412960.0, 3947520.0, 418080.0, 3952640.0),
   bounds_crs='EPSG:32613',
   geometry=<shapely.geom...x7f121488c890>,
   zone=13,
   ti=-17,
   tj=771,
   geotrans=[
  412960.0,...  0,
  -10.0
], ...

Constructs a DLTile from a parameter dictionary. It is preferred to use the DLTile.from_latlon, DLTile.from_shape, or DLTile.from_key class methods to construct a DLTile GeoContext.

Parameters
  • dltile_dict (Dict[Str, Any]) – Dictionary for the tile.

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Attributes:

__geo_interface__

geometry as a GeoJSON Polygon

all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

bounds

The (min_x, min_y, max_x, max_y) of the area covered by this DLTile, in the UTM coordinate reference system given in bounds_crs.

bounds_crs

The coordinate reference system of the bounds, given as an EPSG code (like EPSG:32615).

crs

Coordinate reference system into which scenes will be projected.

geometry

The polygon covered by this DLTile in WGS84 (lat-lon) coordinates

geotrans

The 6-tuple GDAL geotrans for this DLTile in the shape (a, b, c, d, e, f) where

key

The DLTile’s key, which encodes the tiling parameters, and which number in the grid this tile is.

pad

Number of extra pixels by which each side of the tile is buffered.

proj4

PROJ.4 definition for this DLTile’s coordinate reference system

raster_params

The properties of this DLTile, as keyword arguments to use for Raster.ndarray or Raster.raster.

resolution

Distance, in meters, that the edge of each pixel represents on the ground

ti

The y-index of this tile in its grid

tile_extent

total extent of geocontext length in pixels, including pad.

tilesize

Length of each side of the tile, in pixels.

tj

The x-index of this tile in its grid

wkt

OGC Well-Known Text definition for this DLTile’s coordinate reference system

zone

The UTM zone of this tile

Methods:

assign([pad, all_touched])

Return a copy of the DLTile with the pad and/or all_touched value modified.

from_key(dltile_key[, all_touched])

Return a DLTile GeoContext from a DLTile key.

from_latlon(lat, lon, resolution, tilesize, pad)

Return a DLTile GeoContext that covers a latitude/longitude.

from_shape(shape, resolution, tilesize, pad)

Return a list of DLTiles that intersect the given geometry.

iter_from_shape(shape, resolution, tilesize, pad)

Return a iterator for DLTiles that intersect the given geometry.

latlon_to_rowcol(lat, lon)

Convert lat, lon coordinates to pixel coordinates

rowcol_to_latlon(row, col)

Convert pixel coordinates to lat, lon coordinates

subtile(subdivide[, resolution, pad, keys_only])

Return an iterator for new DLTiles that subdivide this tile.

assign(pad='unchanged', all_touched='unchanged')[source]

Return a copy of the DLTile with the pad and/or all_touched value modified.

Parameters
  • pad (int, default "unchanged") – New pad value

  • all_touched (bool, default "unchanged") – New all_touched value

Returns

  • tile (DLTile)

  • Example

  • ——–

  • >>> from descarteslabs.scenes import DLTile

  • >>> tile = DLTile.from_key(“2048 (16:30.0:15:3:80”))

  • >>> tile.pad

  • 16

  • >>> tile = tile.assign(123)

  • >>> tile.pad

  • 123

classmethod from_key(dltile_key, all_touched=False)[source]

Return a DLTile GeoContext from a DLTile key.

Parameters
  • dltile_key (str) – DLTile key, e.g. ‘128:16:960.0:15:-1:37’

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Returns

tile

Return type

DLTile

Example

>>> from descarteslabs.scenes import DLTile
>>> tile = DLTile.from_key("2048:16:30.0:15:3:80")
>>> tile            
DLTile(key='2048:16:30.0:15:3:80',
       resolution=30.0,
       tilesize=2048,
       pad=16,
       crs='EPSG:32615',
       bounds=(683840.0, 4914720.0, 746240.0, 4977120.0),
       bounds_crs='EPSG:32615',
       geometry=<shapely.geom...>,
       zone=15,
       ti=3,
       tj=80,
       geotrans=[
...
classmethod from_latlon(lat, lon, resolution, tilesize, pad, all_touched=False)[source]

Return a DLTile GeoContext that covers a latitude/longitude.

Where the point falls within the tile will vary, depending on the point and tiling parameters.

Parameters
  • lat (float) – Latitude (WGS84)

  • lon (float) – Longitude (WGS84)

  • resolution (float) – Distance, in meters, that the edge of each pixel represents on the ground

  • tilesize (int) – Length of each side of the tile, in pixels

  • pad (int) – Number of extra pixels by which each side of the tile is buffered. This determines the number of pixels by which two tiles overlap.

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Returns

tile

Return type

DLTile

Example

>>> from descarteslabs.scenes import DLTile
>>> # make a tile with total size 100, centered on lat, lon
>>> # total tilesize == tilesize + 2 * pad
>>> params = {
...    "lat": 30.0131,
...    "lon": 31.2089,
...    "resolution": 10,
...    "tilesize": 2,
...    "pad": 49,
... }
>>> tile = DLTile.from_latlon(**params)
>>> tile.key
'2:49:10.0:36:-8637:166079'
>>> tile.geometry.centroid.xy  
(array('d', [31.20899205942612]), array('d', [30.013121672688087]))
classmethod from_shape(shape, resolution, tilesize, pad, keys_only=False, all_touched=False)[source]

Return a list of DLTiles that intersect the given geometry.

Parameters
  • shape (GeoJSON-like) – A GeoJSON dict, or object with a __geo_interface__. Must be in EPSG:4326 (WGS84 lat-lon) projection.

  • resolution (float) – Distance, in meters, that the edge of each pixel represents on the ground.

  • tilesize (int) – Length of each side of the tile, in pixels.

  • pad (int) – Number of extra pixels by which each side of the tile is buffered. This determines the number of pixels by which two tiles overlap.

  • keys_only (bool, default False) – Whether to return DLTile objects or only DLTile keys. Set to True when returning a large number of tiles and you do not need the full objects.

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Returns

tiles

Return type

List[DLTile] or List[Str]

Example

>>> from descarteslabs.scenes import DLTile
>>> shape = {
... "type":"Feature",
... "geometry":{
...     "type":"Polygon",
...     "coordinates":[[
...            [-122.51140471760839,37.77130087547876],
...            [-122.45475646845254,37.77475476721895],
...            [-122.45303985468301,37.76657207194229],
...            [-122.51057242081689,37.763446782666094],
...            [-122.51140471760839,37.77130087547876]]]
...    },"properties": None
... }
>>> tiles = DLTile.from_shape(
...    shape=shape,
...    resolution=1,
...    tilesize=500,
...    pad=0,
... )
>>> len(tiles)
31
classmethod iter_from_shape(shape, resolution, tilesize, pad, keys_only=False, all_touched=False)[source]

Return a iterator for DLTiles that intersect the given geometry.

Parameters
  • shape (GeoJSON-like) – A GeoJSON dict, or object with a __geo_interface__. Must be in EPSG:4326 (WGS84 lat-lon) projection.

  • resolution (float) – Distance, in meters, that the edge of each pixel represents on the ground.

  • tilesize (int) – Length of each side of the tile, in pixels.

  • pad (int) – Number of extra pixels by which each side of the tile is buffered. This determines the number of pixels by which two tiles overlap.

  • keys_only (bool, default False) – Whether to return DLTile objects or only DLTile keys. Set to True when returning a large number of tiles and you do not need the full objects.

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Returns

Return type

Iterator of DLTiles or str

Example

>>> from descarteslabs.scenes import DLTile
>>> shape = {
... "type":"Feature",
... "geometry":{
...     "type":"Polygon",
...     "coordinates":[[
...            [-122.51140471760839,37.77130087547876],
...            [-122.45475646845254,37.77475476721895],
...            [-122.45303985468301,37.76657207194229],
...            [-122.51057242081689,37.763446782666094],
...            [-122.51140471760839,37.77130087547876]]]
...    },"properties": None
... }
>>> gen = DLTile.from_shape(
...    shape=shape,
...    resolution=1,
...    tilesize=500,
...    pad=0,
...    keys_only=True
... )
>>> tiles = [tile for tile in gen]  
>>> tiles[0]                        
'500:0:1.0:10:94:8359'
latlon_to_rowcol(lat, lon)[source]

Convert lat, lon coordinates to pixel coordinates

Parameters
  • lat (float or List[float]) – Latitude coordinate or coordinates

  • lon (float or List[float]) – Longitude coordinate or coordinates

Returns

coords – Tuple with the first element the row values and the second element column values

Return type

List[Tuple[int] Tuple[int]]

Example

>>> from descarteslabs.scenes import DLTile
>>> tile = DLTile.from_key("2048:0:30.0:15:3:80")
>>> tile.latlon_to_rowcol(lat=44.8, lon=-90.2)
[(403,), (1238,)]
rowcol_to_latlon(row, col)[source]

Convert pixel coordinates to lat, lon coordinates

Parameters
  • row (int or List[int]) – Pixel row coordinate or coordinates

  • col (int or List[int]) – Pixel column coordinate or coordinates

Returns

coords – List with the first element the latitude values and the second element longitude values

Return type

List[Tuple[float], Tuple[float]]

Example

>>> from descarteslabs.scenes import DLTile
>>> tile = DLTile.from_key("2048:0:30.0:15:3:80")
>>> tile.rowcol_to_latlon(row=56, col=1111)
[(44.89479253978484,), (-90.24352536949974,)]
subtile(subdivide, resolution=None, pad=None, keys_only=False)[source]

Return an iterator for new DLTiles that subdivide this tile.

The DLtile will be sub-divided into subdivide^2 total sub-tiles each with a side length of tile_size / subdivide. The resulting sub-tile size must be an integer. Each sub-tile will by default inherit the same resolution and pad as the orginal tile.

Parameters
  • subdivide (int) – The value to subdivide the tile. The total number of sub-tiles will be the square of this value. This value must evenly divide the original tilesize.

  • resolution (None, float) – A new resolution for the sub-tiles. None defaults to the original DLTile resolution. The new resolution must evenly divide the the original tilesize divided by the subdivide ratio.

  • pad (None, int) – A new pad value for the sub-tiles. None defaults to the original DLTile pad value.

  • keys_only (bool, default False) – Whether to return DLTile objects or only DLTile keys. Set to True when returning a large number of tiles and you do not need the full objects.

Returns

  • Iterator over DLTiles or str

  • Example

  • ——-

  • >>> from descarteslabs.scenes import DLTile

  • >>> tile = DLTile.from_key(“2048 (0:30.0:15:3:80”))

  • >>> tiles = [tile for tile in tile.subtile(8)]

  • >>> len(tiles)

  • 64

  • >>> tiles[0].tilesize

  • 256

property __geo_interface__

geometry as a GeoJSON Polygon

Type

dict

property all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Type

bool

property bounds

The (min_x, min_y, max_x, max_y) of the area covered by this DLTile, in the UTM coordinate reference system given in bounds_crs.

Type

tuple

property bounds_crs

The coordinate reference system of the bounds, given as an EPSG code (like EPSG:32615). A DLTile’s CRS is always UTM.

Type

str

property crs

Coordinate reference system into which scenes will be projected. For DLTiles, this is always a UTM projection, given as an EPSG code.

Type

str

property geometry

The polygon covered by this DLTile in WGS84 (lat-lon) coordinates

Type

shapely.geometry.Polygon

property geotrans

The 6-tuple GDAL geotrans for this DLTile in the shape (a, b, c, d, e, f) where

a is the top left pixel’s x-coordinate
b is the west-east pixel resolution
c is the row rotation, always 0 for DLTiles
d is the top left pixel’s y-coordinate
e is the column rotation, always 0 for DLTiles
f is the north-south pixel resolution, always a negative value
Type

tuple

property key

The DLTile’s key, which encodes the tiling parameters, and which number in the grid this tile is.

Type

str

property pad

Number of extra pixels by which each side of the tile is buffered. This determines the number of pixels by which two tiles overlap.

Type

int

property proj4

PROJ.4 definition for this DLTile’s coordinate reference system

Type

str

property raster_params

The properties of this DLTile, as keyword arguments to use for Raster.ndarray or Raster.raster.

Type

dict

property resolution

Distance, in meters, that the edge of each pixel represents on the ground

Type

float

property ti

The y-index of this tile in its grid

Type

int

property tile_extent

total extent of geocontext length in pixels, including pad. Size is tile_size + 2 * pad.

Type

int

property tilesize

Length of each side of the tile, in pixels. Note that the total number of pixels along each side of an image is tile_size + 2 * padding

Type

int

property tj

The x-index of this tile in its grid

Type

int

property wkt

OGC Well-Known Text definition for this DLTile’s coordinate reference system

Type

str

property zone

The UTM zone of this tile

Type

int

class GeoContext(all_touched=False)[source]

Specifies spatial parameters to use when loading a raster from the Descartes Labs catalog.

Two Scenes loaded with the same GeoContext will result in images with the same shape (in pixels), covering the same spatial extent, regardless of the dimensions or projection of the original data.

Specifically, a fully-defined GeoContext specifies:

  • geometry to use as a cutline (WGS84), and/or bounds

  • resolution (m)

  • EPSG code of the output coordinate reference system

  • whether to align pixels to the output CRS (see docstring for AOI.align_pixels for more information)

GeoContexts are immutable.

Parameters

all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Attributes:

all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

raster_params

The properties of this GeoContext, as keyword arguments to use for Raster.ndarray or Raster.raster.

property all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Type

bool

property raster_params

The properties of this GeoContext, as keyword arguments to use for Raster.ndarray or Raster.raster.

Type

dict

class XYZTile(x, y, z, all_touched=False)[source]

A GeoContext for XYZ tiles, such as those used in web maps.

The tiles are always 256x256 pixels, in the spherical Mercator or “Web Mercator” coordinate reference system (EPSG:3857).

Parameters
  • x (int) – X-index of the tile (increases going east)

  • y (int) – Y-index of the tile (increases going south)

  • z (int) – Zoom level of the tile

  • all_touched (bool, default False) – If True, this ensures that any source pixel which intersects the AOI GeoContext contributes to the raster result. Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Attributes:

__geo_interface__

geometry as a GeoJSON Polygon

all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

bounds

The (min_x, min_y, max_x, max_y) of the area covered by this XYZTile, in spherical Mercator coordinates (EPSG:3857).

bounds_crs

The coordinate reference system of the bounds.

crs

Coordinate reference system into which scenes will be projected.

geometry

The polygon covered by this XYZTile in WGS84 (lat-lon) coordinates

raster_params

The properties of this XYZTile, as keyword arguments to use for Raster.ndarray or Raster.raster.

resolution

Distance, in meters, that the edge of each pixel represents in the spherical Mercator (“Web Mercator”, EPSG:3857) projection.

tilesize

Length of each side of the tile, in pixels.

x

X-index of the tile (increases going east)

y

Y-index of the tile (increases going south)

z

Zoom level of the tile

Methods:

children()

List of child XYZTiles contained within this one

parent()

The parent XYZTile enclosing this one

children()[source]

List of child XYZTiles contained within this one

parent()[source]

The parent XYZTile enclosing this one

property __geo_interface__

geometry as a GeoJSON Polygon

Type

dict

property all_touched

If True, this ensures that any source pixel which intersects the GeoContext contributes to the raster result.

Normally this mode is not enabled, and its use is strongly discouraged. However, it can be useful when the AOI is smaller than a source pixel, which under many situations will return no result at all (i.e. entirely masked).

Type

bool

property bounds

The (min_x, min_y, max_x, max_y) of the area covered by this XYZTile, in spherical Mercator coordinates (EPSG:3857).

Type

tuple

property bounds_crs

The coordinate reference system of the bounds. Always EPSG:3857 (spherical Mercator, aka “Web Mercator”)

Type

str

property crs

Coordinate reference system into which scenes will be projected. Always EPSG:3857 (spherical Mercator, aka “Web Mercator”)

Type

str

property geometry

The polygon covered by this XYZTile in WGS84 (lat-lon) coordinates

Type

shapely.geometry.Polygon

property raster_params

The properties of this XYZTile, as keyword arguments to use for Raster.ndarray or Raster.raster.

Type

dict

property resolution

Distance, in meters, that the edge of each pixel represents in the spherical Mercator (“Web Mercator”, EPSG:3857) projection.

Type

float

property tilesize

Length of each side of the tile, in pixels. Always 256.

Type

int

property x

X-index of the tile (increases going east)

Type

int

property y

Y-index of the tile (increases going south)

Type

int

property z

Zoom level of the tile

Type

int