Geo¶
Classes:
AOI ([geometry, resolution, crs, …]) |
A GeoContext that clips imagery 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 imagery 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=None, bounds=None, bounds_crs='EPSG:4326', shape=None, all_touched=False)[source]¶ A GeoContext that clips imagery 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) – When searching, filter for elements which intersect this geometry. When rastering, clip imagery to this geometry. Coordinates must be WGS84 (lat-lon). IfNone
, imagery will just be clipped tobounds
. - resolution (float, optional) – Distance, in native units of the CRS, that the edge of each pixel represents on the ground. Do not assume this to always be either degrees or meters. Can only specify one of resolution and shape.
- crs (str, optional) – Coordinate Reference System into which imagery 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 resolution is not None) –
If
True
, this ensures that, in different images 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. Note that in cases where shape has been specified, this may lead to the resulting image being one pixel larger in each dimension, so the the entire bounds is included.If align_pixels is
False
, when using imagery with different native resolutions and/or projections, pixels at the same indices 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 imagery to these
(min_x, min_y, max_x, max_y)
bounds, expressed inbounds_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 (likeEPSG: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. Note that when align_pixels isTrue
, the actual resulting raster may be one pixel larger in each direction. - 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).
-
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 changebounds_crs
toEPSG: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
geometry
without changingbounds
, 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
align_pixels
¶ If True, this ensures that, in different images 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. Note that in cases where shape has been specified, this may lead to the resulting image being one pixel larger in each dimension, so the the entire bounds is included.If align_pixels is False, when using imagery 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
bounds
¶ Clip imagery to these
(min_x, min_y, max_x, max_y)
bounds, expressed in the coordinate reference system inbounds_crs
.Type: tuple
-
property
bounds_crs
¶ The coordinate reference system of the
bounds
, given as an EPSG code (likeEPSG:4326
), a PROJ.4 definition, or an OGC CRS Well-Known Text string.Type: str
-
property
crs
¶ Coordinate reference system into which imagery 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 imagery to this geometry Coordinates must be WGS84 (lat-lon). If
None
, imagery will just be clipped tobounds
.Type: shapely geometry
-
property
raster_params
¶ The properties of this AOI, as keyword arguments to use for
ndarray
orraster
.Raises ValueError if
bounds
, crs,bounds_crs
, resolution, or align_pixels isNone
.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
- geometry (GeoJSON-like dict, object with
-
class
DLTile
(dltile_dict, all_touched=False)[source]¶ A GeoContext that clips and projects imagery 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.geo 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, :meth:`DLTile.from_shape()
, orDLTile.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).
-
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.geo 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: Example
>>> from descarteslabs.geo 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: Example
>>> from descarteslabs.geo 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 inEPSG: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.geo 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
- shape (GeoJSON-like) – A GeoJSON dict, or object with a
-
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 inEPSG: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.geo 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'
- shape (GeoJSON-like) – A GeoJSON dict, or object with a
-
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.geo import DLTile >>> tile = DLTile.from_key("2048:0:30.0:15:3:80") >>> tile.latlon_to_rowcol(lat=44.8, lon=-90.2) [(403,), (1237,)]
-
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.geo import DLTile >>> tile = DLTile.from_key("2048:0:30.0:15:3:80") >>> tile.rowcol_to_latlon(row=56, col=1111) [(44.894653081367544,), (-90.24334206726267,)]
-
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.geo 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
bounds
¶ The
(min_x, min_y, max_x, max_y)
of the area covered by this DLTile, in the UTM coordinate reference system given inbounds_crs
.Type: tuple
-
property
bounds_crs
¶ The coordinate reference system of the
bounds
, given as an EPSG code (likeEPSG:32615
). A DLTile’s CRS is always UTM.Type: str
-
property
crs
¶ Coordinate reference system into which imagery 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)
wherea is the top left pixel’s x-coordinateb is the west-east pixel resolutionc is the row rotation, always 0 for DLTilesd is the top left pixel’s y-coordinatee is the column rotation, always 0 for DLTilesf is the north-south pixel resolution, always a negative valueType: 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) or a shape defining the extent in pixels
- 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). -
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).
-
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
. AlwaysEPSG:3857
(spherical Mercator, aka “Web Mercator”)Type: str
-
property
crs
¶ Coordinate reference system into which common.geo 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) coordinatesType: 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