geowombat.util package#

Submodules#

geowombat.util.plotting module#

class geowombat.util.plotting.Plotting[source]#

Bases: object

Methods

imshow(data[, mask, nodata, flip, ...])

Shows an image on a plot.
static imshow(data, mask=False, nodata=0, flip=False, text_color='black', rot=30, **kwargs)[source]#

Shows an image on a plot.

Parameters:

  • data (xarray.DataArray or xarray.Dataset) – The data to plot.

  • mask (Optional[bool]) – Whether to mask ‘no data’ values (given by nodata).

  • nodata (Optional[int or float]) – The ‘no data’ value.

  • flip (Optional[bool]) – Whether to flip an RGB array’s band order.

  • text_color (Optional[str]) – The text color.

  • rot (Optional[int]) – The degree rotation for the x-axis tick labels.

  • kwargs (Optional[dict]) – Keyword arguments passed to xarray.plot.imshow.

Returns:

matplotlib axis object

Examples

>>> import geowombat as gw
>>>
>>> # Open a 3-band image and plot the first band
>>> with gw.open('image.tif') as ds:
>>>     ax = ds.sel(band=1).gw.imshow()
>>>
>>> # Open and plot a 3-band image
>>> with gw.open('image.tif') as ds:
>>>
>>>     ax = ds.sel(band=['red', 'green', 'blue']).gw.imshow(mask=True,
>>>                                                          nodata=0,
>>>                                                          vmin=0.1,
>>>                                                          vmax=0.9,
>>>                                                          robust=True)

geowombat.util.web module#

class geowombat.util.web.CloudPathMixin[source]#

Bases: object

Methods

get_landsat_urls(scene_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Landsat.

get_sentinel2_urls(safe_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Sentinel 2.
static get_landsat_urls(scene_id, bands=None, cloud='gcp')[source]#

Gets Google Cloud Platform COG urls for Landsat.

Parameters:

  • scene_id (str) – The Landsat scene id.

  • bands (Optional[list]) – The list of band names.

  • cloud (Optional[str]) – The cloud strorage to get the URL from. For now, only ‘gcp’ is supported.

Returns:

tuple of band URLs and metadata URL as strings

Example

>>> import os
>>> import geowombat as gw
>>> from geowombat.util import GeoDownloads
>>>
>>> os.environ['CURL_CA_BUNDLE'] = '/etc/ssl/certs/ca-certificates.crt'
>>>
>>> gdl = GeoDownloads()
>>>
>>> scene_urls, meta_url = gdl.get_landsat_urls('LC08_L1TP_042034_20171225_20180103_01_T1',
>>>                                             bands=['blue', 'green', 'red'])
>>>
>>> with gw.open(urls) as src:
>>>     print(src)
static get_sentinel2_urls(safe_id, bands=None, cloud='gcp')[source]#

Gets Google Cloud Platform COG urls for Sentinel 2.

Parameters:

  • safe_id (str) – The Sentinel 2 SAFE id.

  • bands (Optional[list]) – The list of band names.

  • cloud (Optional[str]) – The cloud strorage to get the URL from. For now, only ‘gcp’ is supported.

Returns:

tuple of band URLs and metadata URL as strings

Example

>>> import os
>>> import geowombat as gw
>>> from geowombat.util import GeoDownloads
>>>
>>> os.environ['CURL_CA_BUNDLE'] = '/etc/ssl/certs/ca-certificates.crt'
>>>
>>> gdl = GeoDownloads()
>>>
>>> safe_id = 'S2A_MSIL1C_20180109T135101_N0206_R024_T21HUD_20180109T171608.SAFE/GRANULE/L1C_T21HUD_A013320_20180109T135310'
>>>
>>> scene_urls, meta_url = gdl.get_sentinel2_urls(safe_id,
>>>                                               bands=['blue', 'green', 'red', 'nir'])
>>>
>>> with gw.open(urls) as src:
>>>     print(src)
class geowombat.util.web.DownloadMixin[source]#

Bases: object

Methods

download_aws(landsat_id, band_list[, outdir])

Downloads Landsat 8 data from Amazon AWS.

download_gcp(sensor[, downloads, outdir, ...])

Downloads a file from Google Cloud platform.
download_aws(landsat_id, band_list, outdir='.')[source]#

Downloads Landsat 8 data from Amazon AWS.

Parameters:

  • landsat_id (str) – The Landsat id to download.

  • band_list (list) – The Landsat bands to download.

  • outdir (Optional[str]) – The output directory.

Examples

>>> from geowombat.util import GeoDownloads
>>>
>>> dl = GeoDownloads()
>>> dl.download_aws('LC08_L1TP_224077_20200518_20200518_01_RT', ['b2', 'b3', 'b4'])
download_gcp(sensor, downloads=None, outdir='.', outdir_brdf=None, search_wildcards=None, search_dict=None, n_jobs=1, verbose=0)[source]#

Downloads a file from Google Cloud platform.

Parameters:

  • sensor (str) – The sensor to query. Choices are [‘l5’, ‘l7’, ‘l8’, ‘s2a’, ‘s2c’].

  • downloads (Optional[str or list]) – The file or list of keys to download. If not given, keys will be taken from search_dict or self.search_dict.

  • outdir (Optional[str | Path]) – The output directory.

  • outdir_brdf (Optional[Path]) – The output directory.

  • search_wildcards (Optional[list]) – A list of search wildcards.

  • search_dict (Optional[dict]) – A keyword search dictionary to override self.search_dict.

  • n_jobs (Optional[int]) – The number of files to download in parallel.

  • verbose (Optional[int]) – The verbosity level.

Returns:

dict of dicts

where sub-dictionaries contain a namedtuple of the downloaded file and tag

class geowombat.util.web.FileInfo(name, key)#

Bases: tuple

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.
key#

Alias for field number 1

name#

Alias for field number 0

class geowombat.util.web.GeoDownloads[source]#

Bases: CloudPathMixin, DownloadMixin

Attributes:
get_gcp_results

Methods

download_aws(landsat_id, band_list[, outdir])

Downloads Landsat 8 data from Amazon AWS.

download_cube(sensors, date_range, bounds, bands)

Downloads a cube of Landsat and/or Sentinel 2 imagery.

download_gcp(sensor[, downloads, outdir, ...])

Downloads a file from Google Cloud platform.

get_landsat_urls(scene_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Landsat.

get_sentinel2_urls(safe_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Sentinel 2.

list_gcp(sensor, query)

Lists files from Google Cloud Platform.
download_cube(sensors, date_range, bounds, bands, bands_out=None, crs=None, out_bounds=None, outdir='.', resampling='bilinear', ref_res=None, l57_angles_path=None, l8_angles_path=None, subsample=1, write_format='gtiff', write_angle_files=False, mask_qa=False, lqa_mask_items=None, chunks=512, cloud_heights=None, sr_method='srem', earthdata_username=None, earthdata_key_file=None, earthdata_code_file=None, srtm_outdir=None, n_jobs=1, num_workers=1, num_threads=1, **kwargs)[source]#

Downloads a cube of Landsat and/or Sentinel 2 imagery.

Parameters:

  • sensors (str or list) – The sensors, or sensor, to download.

  • date_range (list) – The date range, given as [date1, date2], where the date format is yyyy-mm.

  • bounds (GeoDataFrame, list, or tuple) – The geometry bounds (in WGS84 lat/lon) that define the cube extent to download. If given as a GeoDataFrame, only the first DataFrame record will be used. If given as a tuple or a list, the order should be (left, bottom, right, top).

  • bands (str or list) –

    The bands to download.

    E.g.:

    Sentinel s2cloudless bands:

    bands = [‘coastal’, ‘blue’, ‘red’, ‘nir1’, ‘nir’, ‘rededge’, ‘water’, ‘cirrus’, ‘swir1’, ‘swir2’]

  • bands_out (Optional[list]) – The bands to write to file. This might be useful after downloading all bands to mask clouds, but are only interested in subset of those bands.

  • crs (Optional[str or object]) – The output CRS. If bounds is a GeoDataFrame, the CRS is taken from the object.

  • out_bounds (Optional[list or tuple]) – The output bounds in crs. If not given, the bounds are taken from bounds.

  • outdir (Optional[str]) – The output directory.

  • ref_res (Optional[tuple]) – A reference cell resolution.

  • resampling (Optional[str]) – The resampling method.

  • l57_angles_path (str) – The path to the Landsat 5 and 7 angles bin.

  • l8_angles_path (str) – The path to the Landsat 8 angles bin.

  • subsample (Optional[int]) – The sub-sample factor when calculating the angles.

  • write_format (Optional[bool]) – The data format to write. Choices are [‘gtiff’, ‘netcdf’].

  • write_angle_files (Optional[bool]) – Whether to write the angles to file.

  • mask_qa (Optional[bool]) – Whether to mask data with the QA file.

  • lqa_mask_items (Optional[list]) – A list of QA mask items for Landsat.

  • chunks (Optional[int]) – The chunk size to read at.

  • cloud_heights (Optional[list]) – The cloud heights, in kilometers.

  • sr_method (Optional[str]) – The surface reflectance correction method. Choices are [‘srem’, ‘6s’].

  • earthdata_username (Optional[str]) – The EarthData username.

  • earthdata_key_file (Optional[str]) – The EarthData secret key file.

  • earthdata_code_file (Optional[str]) – The EarthData secret passcode file.

  • srtm_outdir (Optional[str]) – The output SRTM directory.

  • n_jobs (Optional[int]) – The number of parallel download workers for joblib.

  • num_workers (Optional[int]) – The number of parallel workers for dask.compute.

  • num_threads (Optional[int]) – The number of GDAL warp threads.

  • kwargs (Optional[dict]) – Keyword arguments passed to to_raster.

Examples

>>> from geowombat.util import GeoDownloads
>>> gdl = GeoDownloads()
>>>
>>> # Download a Landsat 7 panchromatic cube
>>> gdl.download_cube(['l7'],
>>>                   ['2010-01-01', '2010-02-01'],
>>>                   (-91.57, 40.37, -91.46, 40.42),
>>>                   ['pan'],
>>>                   crs="+proj=aea +lat_1=-5 +lat_2=-42 +lat_0=-32 +lon_0=-60 +x_0=0 +y_0=0 +ellps=aust_SA +units=m +no_defs")
>>>
>>> # Download a Landsat 7, 8 and Sentinel 2 cube of the visible spectrum
>>> gdl.download_cube(['l7', 'l8', 's2a'],
>>>                   ['2017-01-01', '2018-01-01'],
>>>                   (-91.57, 40.37, -91.46, 40.42),
>>>                   ['blue', 'green', 'red'],
>>>                   crs={'init': 'epsg:102033'},
>>>                   readxsize=1024,
>>>                   readysize=1024,
>>>                   n_workers=1,
>>>                   n_threads=8)
property get_gcp_results#
list_gcp(sensor, query)[source]#

Lists files from Google Cloud Platform.

Parameters:

  • sensor (str) – The sensor to query. Choices are [‘l5’, ‘l7’, ‘l8’, ‘s2a’, ‘s2c’].

  • query (str) – The query string.

Examples

>>> dl = GeoDownloads()
>>>
>>> # Query from a known directory
>>> dl.list_gcp('landsat', 'LC08/01/042/034/LC08_L1TP_042034_20161104_20170219_01_T1/')
>>>
>>> # Query a date for Landsat 5
>>> dl.list_gcp('l5', '042/034/*2016*')
>>>
>>> # Query a date for Landsat 7
>>> dl.list_gcp('l7', '042/034/*2016*')
>>>
>>> # Query a date for Landsat 8
>>> dl.list_gcp('l8', '042/034/*2016*')
>>>
>>> # Query Sentinel-2
>>> dl.list_gcp('s2a', '21/H/UD/*2019*.SAFE/GRANULE/*')
Returns:

dict

class geowombat.util.web.GoogleFileInfo(url, url_file, meta, angles)#

Bases: tuple

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.
angles#

Alias for field number 3

meta#

Alias for field number 2

url#

Alias for field number 0

url_file#

Alias for field number 1

class geowombat.util.web.OrbitDates(start, end)#

Bases: tuple

Methods

count(value, /)

Return number of occurrences of value.

index(value[, start, stop])

Return first index of value.
end#

Alias for field number 1

start#

Alias for field number 0

Module contents#

class geowombat.util.GeoDownloads[source]#

Bases: CloudPathMixin, DownloadMixin

Attributes:
get_gcp_results

Methods

download_aws(landsat_id, band_list[, outdir])

Downloads Landsat 8 data from Amazon AWS.

download_cube(sensors, date_range, bounds, bands)

Downloads a cube of Landsat and/or Sentinel 2 imagery.

download_gcp(sensor[, downloads, outdir, ...])

Downloads a file from Google Cloud platform.

get_landsat_urls(scene_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Landsat.

get_sentinel2_urls(safe_id[, bands, cloud])

Gets Google Cloud Platform COG urls for Sentinel 2.

list_gcp(sensor, query)

Lists files from Google Cloud Platform.
download_cube(sensors, date_range, bounds, bands, bands_out=None, crs=None, out_bounds=None, outdir='.', resampling='bilinear', ref_res=None, l57_angles_path=None, l8_angles_path=None, subsample=1, write_format='gtiff', write_angle_files=False, mask_qa=False, lqa_mask_items=None, chunks=512, cloud_heights=None, sr_method='srem', earthdata_username=None, earthdata_key_file=None, earthdata_code_file=None, srtm_outdir=None, n_jobs=1, num_workers=1, num_threads=1, **kwargs)[source]#

Downloads a cube of Landsat and/or Sentinel 2 imagery.

Parameters:

  • sensors (str or list) – The sensors, or sensor, to download.

  • date_range (list) – The date range, given as [date1, date2], where the date format is yyyy-mm.

  • bounds (GeoDataFrame, list, or tuple) – The geometry bounds (in WGS84 lat/lon) that define the cube extent to download. If given as a GeoDataFrame, only the first DataFrame record will be used. If given as a tuple or a list, the order should be (left, bottom, right, top).

  • bands (str or list) –

    The bands to download.

    E.g.:

    Sentinel s2cloudless bands:

    bands = [‘coastal’, ‘blue’, ‘red’, ‘nir1’, ‘nir’, ‘rededge’, ‘water’, ‘cirrus’, ‘swir1’, ‘swir2’]

  • bands_out (Optional[list]) – The bands to write to file. This might be useful after downloading all bands to mask clouds, but are only interested in subset of those bands.

  • crs (Optional[str or object]) – The output CRS. If bounds is a GeoDataFrame, the CRS is taken from the object.

  • out_bounds (Optional[list or tuple]) – The output bounds in crs. If not given, the bounds are taken from bounds.

  • outdir (Optional[str]) – The output directory.

  • ref_res (Optional[tuple]) – A reference cell resolution.

  • resampling (Optional[str]) – The resampling method.

  • l57_angles_path (str) – The path to the Landsat 5 and 7 angles bin.

  • l8_angles_path (str) – The path to the Landsat 8 angles bin.

  • subsample (Optional[int]) – The sub-sample factor when calculating the angles.

  • write_format (Optional[bool]) – The data format to write. Choices are [‘gtiff’, ‘netcdf’].

  • write_angle_files (Optional[bool]) – Whether to write the angles to file.

  • mask_qa (Optional[bool]) – Whether to mask data with the QA file.

  • lqa_mask_items (Optional[list]) – A list of QA mask items for Landsat.

  • chunks (Optional[int]) – The chunk size to read at.

  • cloud_heights (Optional[list]) – The cloud heights, in kilometers.

  • sr_method (Optional[str]) – The surface reflectance correction method. Choices are [‘srem’, ‘6s’].

  • earthdata_username (Optional[str]) – The EarthData username.

  • earthdata_key_file (Optional[str]) – The EarthData secret key file.

  • earthdata_code_file (Optional[str]) – The EarthData secret passcode file.

  • srtm_outdir (Optional[str]) – The output SRTM directory.

  • n_jobs (Optional[int]) – The number of parallel download workers for joblib.

  • num_workers (Optional[int]) – The number of parallel workers for dask.compute.

  • num_threads (Optional[int]) – The number of GDAL warp threads.

  • kwargs (Optional[dict]) – Keyword arguments passed to to_raster.

Examples

>>> from geowombat.util import GeoDownloads
>>> gdl = GeoDownloads()
>>>
>>> # Download a Landsat 7 panchromatic cube
>>> gdl.download_cube(['l7'],
>>>                   ['2010-01-01', '2010-02-01'],
>>>                   (-91.57, 40.37, -91.46, 40.42),
>>>                   ['pan'],
>>>                   crs="+proj=aea +lat_1=-5 +lat_2=-42 +lat_0=-32 +lon_0=-60 +x_0=0 +y_0=0 +ellps=aust_SA +units=m +no_defs")
>>>
>>> # Download a Landsat 7, 8 and Sentinel 2 cube of the visible spectrum
>>> gdl.download_cube(['l7', 'l8', 's2a'],
>>>                   ['2017-01-01', '2018-01-01'],
>>>                   (-91.57, 40.37, -91.46, 40.42),
>>>                   ['blue', 'green', 'red'],
>>>                   crs={'init': 'epsg:102033'},
>>>                   readxsize=1024,
>>>                   readysize=1024,
>>>                   n_workers=1,
>>>                   n_threads=8)
property get_gcp_results#
list_gcp(sensor, query)[source]#

Lists files from Google Cloud Platform.

Parameters:

  • sensor (str) – The sensor to query. Choices are [‘l5’, ‘l7’, ‘l8’, ‘s2a’, ‘s2c’].

  • query (str) – The query string.

Examples

>>> dl = GeoDownloads()
>>>
>>> # Query from a known directory
>>> dl.list_gcp('landsat', 'LC08/01/042/034/LC08_L1TP_042034_20161104_20170219_01_T1/')
>>>
>>> # Query a date for Landsat 5
>>> dl.list_gcp('l5', '042/034/*2016*')
>>>
>>> # Query a date for Landsat 7
>>> dl.list_gcp('l7', '042/034/*2016*')
>>>
>>> # Query a date for Landsat 8
>>> dl.list_gcp('l8', '042/034/*2016*')
>>>
>>> # Query Sentinel-2
>>> dl.list_gcp('s2a', '21/H/UD/*2019*.SAFE/GRANULE/*')
Returns:

dict

geowombat.util.imshow(data, mask=False, nodata=0, flip=False, text_color='black', rot=30, **kwargs)#

Shows an image on a plot.

Parameters:

  • data (xarray.DataArray or xarray.Dataset) – The data to plot.

  • mask (Optional[bool]) – Whether to mask ‘no data’ values (given by nodata).

  • nodata (Optional[int or float]) – The ‘no data’ value.

  • flip (Optional[bool]) – Whether to flip an RGB array’s band order.

  • text_color (Optional[str]) – The text color.

  • rot (Optional[int]) – The degree rotation for the x-axis tick labels.

  • kwargs (Optional[dict]) – Keyword arguments passed to xarray.plot.imshow.

Returns:

matplotlib axis object

Examples

>>> import geowombat as gw
>>>
>>> # Open a 3-band image and plot the first band
>>> with gw.open('image.tif') as ds:
>>>     ax = ds.sel(band=1).gw.imshow()
>>>
>>> # Open and plot a 3-band image
>>> with gw.open('image.tif') as ds:
>>>
>>>     ax = ds.sel(band=['red', 'green', 'blue']).gw.imshow(mask=True,
>>>                                                          nodata=0,
>>>                                                          vmin=0.1,
>>>                                                          vmax=0.9,
>>>                                                          robust=True)