geodesic.boson.dataset.Dataset.get_pixels#

Dataset.get_pixels(*, bbox, datetime=None, pixel_size=None, shape=None, pixel_dtype=<class 'numpy.float32'>, bbox_crs='EPSG:4326', output_crs='EPSG:3857', resampling='nearest', no_data=None, content_type='raw', asset_bands=[], filter={}, image_ids=[], compress=True, bands_last=False)[source]#

Get pixel data or an image from this Dataset.

get_pixels gets requested pixels from a dataset by calling Boson. This method returns either a numpy array or the bytes of a image file (jpg, png, gif, or tiff). If the content_type is “raw”, this will return a numpy array, otherwise it will return the requested image format as bytes that can be written to a file. Where possible, a COG will be returned for Tiff format, but is not guaranteed.

Parameters:

  • bbox (list) – a bounding box to export as imagery (xmin, ymin, xmax, ymax)

  • datetime (List | Tuple | None) – a start and end datetime to query against. Imagery will be filtered to between this range and mosaiced.

  • pixel_size (list | None) – a list of the x/y pixel size of the output imagery. This list needs to have length equal to the number of bands. This should be specified in the output spatial reference.

  • shape (list | None) – the shape of the output image (rows, cols). Either this or the pixel_size must be specified, but not both.

  • pixel_dtype (dtype | str) – a numpy datatype or string descriptor in numpy format (e.g. <f4) of the output. Most, but not all basic dtypes are supported.

  • bbox_crs (str) – the spatial reference of the bounding bbox, as a string. May be EPSG:<code>, WKT, Proj4, ProjJSON, etc.

  • output_crs (str) – the spatial reference of the output pixels.

  • resampling (str) – a string to select the resampling method.

  • no_data (Any | None) – in the source imagery, what value should be treated as no data?

  • content_type (str) – the image format. Default is “raw” which returns a numpy array. If “jpg”, “gif”, or “tiff”, returns the bytes of an image file instead, which can directly be written to disk.

  • asset_bands (List[AssetBands] | AssetBands) – either a list containing dictionaries with the keys “asset” and “bands” or a single dictionary with the keys “asset” and “bands”. Asset should point to an asset in the dataset, and “bands” should list band indices (0-indexed) or band names.

  • filter (dict) – a CQL2 JSON filter to filter images that will be used for the resulting output.

  • image_ids (List[str]) – a list of image IDs to filter to

  • compress (bool) – compress bytes when transfering. This will usually, but not always improve performance

  • bands_last (bool) – if True, the returned numpy array will have the bands as the last dimension.

Returns:

a numpy array or bytes of an image file.

Examples

>>> # Get a numpy array of pixels from sentinel-2-l2a
>>> import datetime
>>> from geodesic.boson import AssetBands
>>> bbox = [-109.050293,36.993778,-102.030029,41.004775] # roughly the state of Colorado
>>> date_range = (datetime.datetime(2020,1,1), datetime.datetime(2020,2,1))
>>> # The RGB bands of sentinel-2-l2a are B04, B03, B02
>>> asset_bands = [
...         AssetBands(asset="B04", bands=[0]),
...         AssetBands(asset="B03", bands=[0]),
...         AssetBands(asset="B02", bands=[0])
...         ]
>>> pixels = ds.get_pixels(
...             bbox=bbox,
...             datetime=date_range,
...             pixel_size=(1000,1000), # 1kmx1km area because our output EPSG:3857
...             asset_bands=asset_bands,
...             output_crs="EPSG:3857",
...             bbox_crs="EPSG:4326",
...             )
On this page

This Page