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.
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:

  • 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, **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?

  • **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_egm_lookup(geoid, software)[source]

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

Parameters: