Auxiliary Data Tools¶

`dem_autoload`	obtain all relevant DEM tiles for selected geometries and optionally mosaic them in a VRT.
`dem_create`	Create a new DEM GeoTIFF file and optionally convert heights from geoid to ellipsoid.
`get_egm_lookup`	Download lookup tables for converting EGM geoid heights to WGS84 ellipsoid heights.
`getasse30_hdr`	create an ENVI HDR file for zipped GETASSE30 DEM tiles
`get_dem_options`	Get the names of all supported DEM type options.
`DEMHandler`	An interface to obtain DEM data for selected geometries.

class pyroSAR.auxdata.DEMHandler(geometries)[source]¶

Bases: object

An interface to obtain DEM data for selected geometries. The files are downloaded into the ESA SNAP auxiliary data directory structure. This class is the foundation for the convenience function dem_autoload().

Parameters:: geometries (list[spatialist.vector.Vector]) – a list of geometries

property config¶

static intrange(extent, step)[source]¶

generate sequence of integer coordinates marking the tie points of the individual DEM tiles

Parameters:

extent (dict) – a dictionary with keys xmin, xmax, ymin and ymax with coordinates in EPSG:4326.
step (int) – the sequence steps

Returns:

the integer sequences as (latitude, longitude)

Return type:

tuple[range]

load(dem_type, vrt=None, buffer=None, username=None, password=None, product='dem', crop=True, lock_timeout=600)[source]¶

obtain DEM tiles for the given geometries and either return the file names in a list or combine them into a VRT mosaic. The VRT is cropped to the combined extent of the geometries but the pixel grid of the source files is preserved and no resampling/shifting is applied.

Parameters:

dem_type (str) – the type fo DEM to be used
vrt (str or None) – an optional GDAL VRT file created from the obtained DEM tiles
buffer (int or float or None) – a buffer in degrees to add around the individual geometries
username (str or None) – the download account username
password (str or None) – the download account password
product (str) –
the sub-product to extract from the DEM product
- ’AW3D30’
’dem’: the actual Digital Elevation Model

’msk’: mask information for each pixel (Cloud/Snow Mask, Land water and low correlation mask, Sea mask, Information of elevation dataset used for the void-filling processing)

’stk’: number of DSM-scene files which were used to produce the 5m resolution DSM
- ’Copernicus 10m EEA DEM’
’dem’: the actual Digital Elevation Model

’edm’: Editing Mask

’flm’: Filling Mask

’hem’: Height Error Mask

’wbm’: Water Body Mask
- ’Copernicus 30m Global DEM’
’dem’: the actual Digital Elevation Model

’edm’: Editing Mask

’flm’: Filling Mask

’hem’: Height Error Mask

’wbm’: Water Body Mask
- ’Copernicus 30m Global DEM II’
’dem’: the actual Digital Elevation Model

’edm’: Editing Mask

’flm’: Filling Mask

’hem’: Height Error Mask

’wbm’: Water Body Mask
- ’Copernicus 90m Global DEM’
’dem’: the actual Digital Elevation Model

’edm’: Editing Mask

’flm’: Filling Mask

’hem’: Height Error Mask

’wbm’: Water Body Mask
- ’Copernicus 90m Global DEM II’
’dem’: the actual Digital Elevation Model

’edm’: Editing Mask

’flm’: Filling Mask

’hem’: Height Error Mask

’wbm’: Water Body Mask
- ’GETASSE30’
’dem’: the actual Digital Elevation Model
- ’SRTM 1Sec HGT’
’dem’: the actual Digital Elevation Model
- ’SRTM 3Sec’
’dem’: the actual Digital Elevation Model
- ’TDX90m’
’dem’: the actual Digital Elevation Model

’am2’: Amplitude Mosaic representing the minimum value

’amp’: Amplitude Mosaic representing the mean value

’com’: Consistency Mask

’cov’: Coverage Map

’hem’: Height Error Map

’lsm’: Layover and Shadow Mask, based on SRTM C-band and Globe DEM data

’wam’: Water Indication Mask
crop (bool) – If a VRT is created, crop it to spatial extent of the provided geometries or return the full extent of the DEM tiles? In the latter case, the common bounding box of the geometries is expanded so that the coordinates are multiples of the tile size of the respective DEM option.
lock_timeout (int) – how long to wait to acquire a lock on downloaded files?

Returns:

the names of the obtained files or None if a VRT file was defined

Return type:

list[str] or None

remote_ids(extent, dem_type, product='dem', username=None, password=None)[source]¶

parse the names of the remote files overlapping with an area of interest

Parameters:

extent (dict) – the extent of the area of interest with keys xmin, xmax, ymin, ymax
dem_type (str) – the type fo DEM to be used
product (str) – the sub-product to extract from the DEM product. Only needed for DEM options ‘Copernicus 30m Global DEM’ and ‘Copernicus 90m Global DEM’ and ignored otherwise.
username (str or None) – the download account username
password (str or None) – the download account password

Returns:

the sorted names of the remote files

Return type:

str

pyroSAR.auxdata.dem_autoload(geometries, demType, vrt=None, buffer=None, username=None, password=None, product='dem', crop=True)[source]¶

obtain all relevant DEM tiles for selected geometries and optionally mosaic them in a VRT.

Parameters:

geometries (list[spatialist.vector.Vector]) – a list of spatialist.vector.Vector geometries to obtain DEM data for; CRS must be WGS84 LatLon (EPSG 4326)
demType (str) –
the type of DEM to be used; current options:
- ’AW3D30’ (ALOS Global Digital Surface Model “ALOS World 3D - 30m”)
  - info: https://www.eorc.jaxa.jp/ALOS/en/aw3d30/index.htm
  - url: ftp://ftp.eorc.jaxa.jp/pub/ALOS/ext1/AW3D30/release_v1804
  - height reference: EGM96
- ’Copernicus 10m EEA DEM’ (Copernicus 10 m DEM available over EEA-39 countries)
  - registration: https://spacedata.copernicus.eu/web/cscda/data-access/registration
  - url: ftps://cdsdata.copernicus.eu/DEM-datasets/COP-DEM_EEA-10-DGED/2021_1
  - height reference: EGM2008
- ’Copernicus 30m Global DEM’
  - info: https://copernicus-dem-30m.s3.amazonaws.com/readme.html
  - url: https://copernicus-dem-30m.s3.eu-central-1.amazonaws.com/
  - height reference: EGM2008
- ’Copernicus 30m Global DEM II’
  - registration: https://spacedata.copernicus.eu/web/cscda/data-access/registration
  - url: ftps://cdsdata.copernicus.eu/DEM-datasets/COP-DEM_GLO-30-DGED/2021_1
  - height reference: EGM2008
- ’Copernicus 90m Global DEM’
  - info: https://copernicus-dem-90m.s3.amazonaws.com/readme.html
  - url: https://copernicus-dem-90m.s3.eu-central-1.amazonaws.com/
  - height reference: EGM2008
- ’Copernicus 90m Global DEM II’
  - registration: https://spacedata.copernicus.eu/web/cscda/data-access/registration
  - url: ftps://cdsdata.copernicus.eu/DEM-datasets/COP-DEM_GLO-90-DGED/2021_1
  - height reference: EGM2008
- ’GETASSE30’
  - info: https://seadas.gsfc.nasa.gov/help-8.1.0/desktop/GETASSE30ElevationModel.html
  - url: https://step.esa.int/auxdata/dem/GETASSE30
  - height reference: WGS84
- ’SRTM 1Sec HGT’
  - url: https://step.esa.int/auxdata/dem/SRTMGL1
  - height reference: EGM96
- ’SRTM 3Sec’
  - url: https://download.esa.int/step/auxdata/dem/SRTM90/tiff
  - height reference: EGM96
- ’TDX90m’
  - registration: https://geoservice.dlr.de/web/dataguide/tdm90
  - url: ftpes://tandemx-90m.dlr.de
  - height reference: WGS84
vrt (str or None) – an optional GDAL VRT file created from the obtained DEM tiles
buffer (int, float, None) – a buffer in degrees to add around the individual geometries
username (str or None) – (optional) the username for services requiring registration
password (str or None) – (optional) the password for the registration account
product (str) –
the sub-product to extract from the DEM product. The following options are available for the respective DEM types:
- ’AW3D30’
  - ’dem’: the actual Digital Elevation Model
  - ’msk’: mask information for each pixel (Cloud/Snow Mask, Land water and low correlation mask, Sea mask, Information of elevation dataset used for the void-filling processing)
  - ’stk’: number of DSM-scene files which were used to produce the 5 m resolution DSM
- ’Copernicus 10m EEA DEM’
  - ’dem’: the actual Digital Elevation Model
  - ’edm’: editing mask
  - ’flm’: filling mask
  - ’hem’: height error mask
  - ’wbm’: water body mask
- ’Copernicus 30m Global DEM’
  - ’dem’: the actual Digital Elevation Model
  - ’edm’: Editing Mask
  - ’flm’: Filling Mask
  - ’hem’: Height Error Mask
  - ’wbm’: Water Body Mask
- ’Copernicus 30m Global DEM II’
  - ’dem’: the actual Digital Elevation Model
  - ’edm’: editing mask
  - ’flm’: filling mask
  - ’hem’: height error mask
  - ’wbm’: water body mask
- ’Copernicus 90m Global DEM’
  - ’dem’: the actual Digital Elevation Model
  - ’edm’: Editing Mask
  - ’flm’: Filling Mask
  - ’hem’: Height Error Mask
  - ’wbm’: Water Body Mask
- ’Copernicus 90m Global DEM II’
  - ’dem’: the actual Digital Elevation Model
  - ’edm’: editing mask
  - ’flm’: filling mask
  - ’hem’: height error mask
  - ’wbm’: water body mask
- ’GETASSE30’
  - ’dem’: the actual Digital Elevation Model
- ’SRTM 1Sec HGT’
  - ’dem’: the actual Digital Elevation Model
- ’SRTM 3Sec’
  - ’dem’: the actual Digital Elevation Model
- ’TDX90m’
  - ’dem’: the actual Digital Elevation Model
  - ’am2’: Amplitude Mosaic representing the minimum value
  - ’amp’: Amplitude Mosaic representing the mean value
  - ’com’: Consistency Mask
  - ’cov’: Coverage Map
  - ’hem’: Height Error Map
  - ’lsm’: Layover and Shadow Mask, based on SRTM C-band and Globe DEM data
  - ’wam’: Water Indication Mask
crop (bool) – crop to the provided geometries (or return the full extent of the DEM tiles)?

Returns:

the names of the obtained files or None if a VRT file was defined

Return type:

list[str] or None

Examples

download all SRTM 1 arcsec DEMs overlapping with a Sentinel-1 scene and mosaic them to a single GeoTIFF file

from pyroSAR import identify
from pyroSAR.auxdata import dem_autoload
from spatialist import gdalwarp

# identify the SAR scene
filename = 'S1A_IW_SLC__1SDV_20150330T170734_20150330T170801_005264_006A6C_DA69.zip'
scene = identify(filename)

# extract the bounding box as spatialist.Vector object
bbox = scene.bbox()

# download the tiles and virtually combine them in an in-memory
# VRT file subsetted to the extent of the SAR scene plus a buffer of 0.01 degrees
vrt = '/vsimem/srtm1.vrt'
dem_autoload(geometries=[bbox], demType='SRTM 1Sec HGT',
             vrt=vrt, buffer=0.01)

# write the final GeoTIFF file
outname = scene.outname_base() + 'srtm1.tif'
gdalwarp(src=vrt, dst=outname, options={'format': 'GTiff'})

# alternatively use function dem_create and warp the DEM to UTM
# including conversion from geoid to ellipsoid heights
from pyroSAR.auxdata import dem_create
outname = scene.outname_base() + 'srtm1_ellp.tif'
dem_create(src=vrt, dst=outname, t_srs=32632, tr=(30, 30),
           geoid_convert=True, geoid='EGM96')

pyroSAR.auxdata.dem_create(src, dst, t_srs=None, tr=None, threads=None, geoid_convert=False, geoid='EGM96', nodata=None, resampleAlg='bilinear', dtype=None, pbar=False, lock_timeout=600, **kwargs)[source]¶

Create a new DEM GeoTIFF file and optionally convert heights from geoid to ellipsoid. This is basically a convenience wrapper around osgeo.gdal.Warp() via spatialist.auxil.gdalwarp(). The following argument defaults deviate from those of osgeo.gdal.WarpOptions():

format is set to ‘GTiff’
resampleAlg is set to ‘bilinear’
targetAlignedPixels is set to ‘True’

Parameters:

src (str) – the input dataset, e.g. a VRT from function dem_autoload()
dst (str) – the output dataset
t_srs (None, int, str or osgeo.osr.SpatialReference) – A target geographic reference system in WKT, EPSG, PROJ4 or OPENGIS format. See function spatialist.auxil.crsConvert() for details. Default (None): use the crs of src.
tr (None or tuple[int or float]) – the target resolution as (xres, yres)
threads (int, str or None) –
the number of threads to use. Possible values:
- Default None: use the value of GDAL_NUM_THREADS without modification. If GDAL_NUM_THREADS is None, multi-threading is still turned on and two threads are used, one for I/O and one for computation.
- integer value: temporarily modify GDAL_NUM_THREADS and reset it once done. If 1, multithreading is turned off.
- ALL_CPUS: special string to use all cores/CPUs of the computer; will also temporarily modify GDAL_NUM_THREADS.
geoid_convert (bool) – convert geoid heights?
geoid (str) –
the geoid model to be corrected, only used if geoid_convert == True; current options:
- ’EGM96’
- ’EGM2008’
nodata (int or float or str or None) – the no data value of the source and destination files. Can be used if no source nodata value can be read or to override it. A special string ‘None’ can be used to skip reading the value from the source file.
resampleAlg (str) – the resampling algorithm tu be used. See here for options: https://gdal.org/programs/gdalwarp.html#cmdoption-gdalwarp-r
dtype (str or None) – override the data type of the written file; Default None: use same type as source data. Data type notations of GDAL (e.g. Float32) and numpy (e.g. int8) are supported. See spatialist.raster.Dtype.
pbar (bool) – add a progressbar?
lock_timeout (int) – how long to wait to acquire a lock on dst?
**kwargs –
additional keyword arguments to be passed to spatialist.auxil.gdalwarp(). See osgeo.gdal.WarpOptions() for options. The following arguments cannot be set as they are controlled internally:
- xRes, yRes: controlled via argument tr
- srcSRS, dstSRS: controlled via the CRS of src and arguments t_srs, geoid, geoid_convert
- srcNodata, dstNodata: controlled via argument nodata
- outputType: controlled via argument dtype
- multithread controlled via argument threads

pyroSAR.auxdata.get_dem_options(require_auth=None)[source]¶

Get the names of all supported DEM type options.

Parameters:: require_auth (bool or None) – only return options that do/don’t require authentication. Default None: return all options.
Returns:: the names of the DEM options
Return type:: list[str]

pyroSAR.auxdata.get_egm_lookup(geoid, software)[source]¶

Download lookup tables for converting EGM geoid heights to WGS84 ellipsoid heights.

Parameters:

geoid (str) –
the geoid model; current options:
- SNAP: ‘EGM96’
- PROJ: ‘EGM96’, ‘EGM2008’
software (str) –
the software for which to download the EGM lookup
- SNAP: default directory: ~/.snap/auxdata/dem/egm96; URL:
  - https://step.esa.int/auxdata/dem/egm96/ww15mgh_b.zip
- PROJ: requires PROJ_DATA or PROJ_LIB environment variable to be set as download directory; URLs:
  - https://cdn.proj.org/us_nga_egm96_15.tif
  - https://cdn.proj.org/us_nga_egm08_25.tif

pyroSAR.auxdata.getasse30_hdr(fname)[source]¶

create an ENVI HDR file for zipped GETASSE30 DEM tiles

Parameters:: fname (str) – the name of the zipped tile

Auxiliary Data Tools¶

Table of Contents

Previous topic

Next topic

This Page