API Documentation
Configuration
Stores GDAL configuration options for the current process. |
|
Returns a dictionary of additional parameters for |
|
Returns the content of a config.ini file as a dictionary. |
- S1_NRB.config.get_config(config_file, proc_section='PROCESSING')[source]
Returns the content of a config.ini file as a dictionary.
- Parameters
- Returns
out_dict – Dictionary of the parsed config parameters.
- Return type
- S1_NRB.config.snap_conf(config)[source]
Returns a dictionary of additional parameters for
S1_NRB.snap.process()based on processing configurations provided by the config file.- Parameters
config (dict) – Dictionary of the parsed config parameters for the current process.
- Returns
Dictionary of parameters that can be passed to
S1_NRB.snap.process()- Return type
Processing
Main function that initiates and controls the processing workflow. |
- S1_NRB.processor.main(config_file, section_name='PROCESSING', debug=False)[source]
Main function that initiates and controls the processing workflow.
SNAP
core processing
Main function for SAR processing with SNAP. |
|
Range-Doppler geocoding. |
|
GRD extent buffering. |
|
Gamma-sigma ratio computation for either ellipsoidal or RTC sigma nought. |
|
Multi-looking. |
|
General SAR preprocessing. |
|
Radiometric Terrain Flattening. |
ancillary functions
Find processed datasets for a scene in a certain CRS. |
|
Get processing metadata needed for NRB metadata. |
|
Performs SLC edge cleaning and sets the nodata value in the output ENVI HDR files. |
- S1_NRB.snap.find_datasets(scene, outdir, epsg)[source]
Find processed datasets for a scene in a certain CRS.
- Parameters
- Returns
Either None if no datasets were found or a dictionary with the following keys and values pointing to the file names (polarization-specific keys depending on product availability):
hh-g-lin: gamma nought RTC backscatter HH polarization
hv-g-lin: gamma nought RTC backscatter HV polarization
vh-g-lin: gamma nought RTC backscatter VH polarization
vv-g-lin: gamma nought RTC backscatter VV polarization
hh-s-lin: sigma nought ellipsoidal backscatter HH polarization
hv-s-lin: sigma nought ellipsoidal backscatter HV polarization
vh-s-lin: sigma nought ellipsoidal backscatter VH polarization
vv-s-lin: sigma nought ellipsoidal backscatter VV polarization
dm: layover-shadow data mask
ei: ellipsoidal incident angle
gs: gamma-sigma ratio
lc: local contributing area (aka scattering area)
li: local incident angle
sg: sigma-gamma ratio
np-hh: NESZ HH polarization
np-hv: NESZ HV polarization
np-vh: NESZ VH polarization
np-vv: NESZ VV polarization
- Return type
dict or None
- S1_NRB.snap.geo(*src, dst, workflow, spacing, crs, geometry=None, buffer=0.01, export_extra=None, standard_grid_origin_x=0, standard_grid_origin_y=0, dem, dem_resampling_method='BILINEAR_INTERPOLATION', img_resampling_method='BILINEAR_INTERPOLATION', **bands)[source]
Range-Doppler geocoding.
- Parameters
src (list[str or None]) – variable number of input scene file names
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the target XML workflow file name
geometry (dict or spatialist.vector.Vector or str or None) – a vector geometry to limit the target product’s extent
buffer (int or float) – an additional buffer in degrees to add around geometry
export_extra (list[str] or None) –
a list of ancillary layers to write. Supported options:
DEM
incidenceAngleFromEllipsoid
layoverShadowMask
localIncidenceAngle
projectedLocalIncidenceAngle
standard_grid_origin_x (int or float) – the X coordinate for pixel alignment
standard_grid_origin_y (int or float) – the Y coordinate for pixel alignment
dem (str) – the DEM file
dem_resampling_method (str) – the DEM resampling method
img_resampling_method (str) – the SAR image resampling method
bands – band ids for the input scenes in src as lists with keys bands<index>, e.g.,
bands1=['NESZ_VV'], bands2=['Gamma0_VV'], ...
- S1_NRB.snap.grd_buffer(src, dst, workflow, neighbors, buffer=10)[source]
GRD extent buffering. GRDs, unlike SLCs, do not overlap in azimuth. With this function, a GRD can be buffered using the neighboring acquisitions. First, all images are mosaicked using the SliceAssembly operator and then subsetted to the extent of the main scene including a buffer.
- S1_NRB.snap.gsr(src, dst, workflow, src_sigma=None)[source]
Gamma-sigma ratio computation for either ellipsoidal or RTC sigma nought.
- Parameters
src (str) – the file name of the source scene. Both gamma and sigma bands are expected unless src_sigma is defined.
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the output SNAP XML workflow filename.
src_sigma (str or None) – the optional file name of a second source product from which to read the sigma band.
- S1_NRB.snap.mli(src, dst, workflow, spacing=None, rlks=None, azlks=None)[source]
Multi-looking.
- Parameters
src (str) – the file name of the source scene
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the output SNAP XML workflow filename.
spacing (int or float) – the target pixel spacing for automatic determination of looks using function
pyroSAR.ancillary.multilook_factors(). Overridden by arguments rlks and azlks if they are not None.rlks (int or None) – the number of range looks.
azlks (int or None) – the number of azimuth looks.
- S1_NRB.snap.postprocess(src, slc_clean_edges=True, slc_clean_edges_pixels=4)[source]
Performs SLC edge cleaning and sets the nodata value in the output ENVI HDR files.
- S1_NRB.snap.pre(src, dst, workflow, allow_res_osv=True, osv_continue_on_fail=False, output_noise=True, output_beta0=True)[source]
General SAR preprocessing. The following operators are used (optional steps in brackets): Apply-Orbit-File(->Remove-GRD-Border-Noise)->Calibration->ThermalNoiseRemoval(->TOPSAR-Deburst)
- Parameters
src (str) – the file name of the source scene
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the output SNAP XML workflow filename.
allow_res_osv (bool) – Also allow the less accurate RES orbit files to be used?
osv_continue_on_fail (bool) – Continue processing if no OSV file can be downloaded or raise an error?
output_noise (bool) – output the noise power images?
output_beta0 (bool) – output beta nought backscatter needed for RTC?
See also
- S1_NRB.snap.process(scene, outdir, measurement, spacing, kml, dem, dem_resampling_method='BILINEAR_INTERPOLATION', img_resampling_method='BILINEAR_INTERPOLATION', rlks=None, azlks=None, tmpdir=None, export_extra=None, allow_res_osv=True, slc_clean_edges=True, slc_clean_edges_pixels=4, neighbors=None, cleanup=True)[source]
Main function for SAR processing with SNAP.
- Parameters
scene (str) – The SAR scene file name.
outdir (str) – The output directory for storing the final results.
measurement ({'sigma', 'gamma'}) –
the backscatter measurement convention:
gamma: RTC gamma nought (gamma^0_T)
sigma: ellipsoidal sigmal nought (sigma^0_E)
spacing (int or float) – The output pixel spacing in meters.
kml (str) – Path to the Sentinel-2 tiling grid KML file.
dem (str) – The DEM filename. Can be created with
S1_NRB.dem.mosaic().dem_resampling_method (str) – The DEM resampling method.
img_resampling_method (str) – The image resampling method.
rlks (int or None) – The number of range looks.
azlks (int or None) – The number of azimuth looks.
tmpdir (str or None) – Path to a temporary directory for intermediate products.
export_extra (list[str] or None) –
A list of ancillary layers to create. Default None: do not create any ancillary layers. Options:
DEM
gammaSigmaRatio: sigma^0_T / gamma^0_T
sigmaGammaRatio: gamma^0_T / sigma^0_E
incidenceAngleFromEllipsoid
layoverShadowMask
localIncidenceAngle
NESZ: noise equivalent sigma zero
projectedLocalIncidenceAngle
scatteringArea
allow_res_osv (bool) – Also allow the less accurate RES orbit files to be used?
slc_clean_edges (bool) – Erode noisy image edges? See
pyroSAR.snap.auxil.erode_edges(). Does not apply to layover-shadow mask.slc_clean_edges_pixels (int) – The number of pixels to erode.
neighbors (list[str] or None) – (only applies to GRD) an optional list of neighboring scenes to add a buffer around the main scene using function
grd_buffer(). If GRDs are processed compeletely independently, gaps are introduced due to a missing overlap between GRDs.cleanup (bool) – Delete intermediate files after successful process termination?
Examples
>>> from S1_NRB import snap >>> scene = 'S1A_IW_SLC__1SDV_20200103T170700_20200103T170727_030639_0382D5_6A12.zip' >>> kml = 'S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml' >>> dem = 'S1A_IW_SLC__1SDV_20200103T170700_20200103T170727_030639_0382D5_6A12_DEM_EEA10.tif' >>> outdir = '.' >>> spacing = 10 >>> rlks = 5 >>> azlks = 1 >>> export_extra = ['localIncidenceAngle', 'incidenceAngleFromEllipsoid', >>> 'scatteringArea', 'layoverShadowMask', 'gammaSigmaRatio'] >>> snap.process(scene=scene, outdir=outdir, spacing=spacing, kml=kml, dem=dem, >>> rlks=rlks, azlks=azlks, export_extra=export_extra)
- S1_NRB.snap.rtc(src, dst, workflow, dem, dem_resampling_method='BILINEAR_INTERPOLATION', sigma0=True, scattering_area=True)[source]
Radiometric Terrain Flattening.
- Parameters
src (str) – the file name of the source scene
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the output SNAP XML workflow filename.
dem (str) – the input DEM file name.
dem_resampling_method (str) – the DEM resampling method.
sigma0 (bool) – output sigma0 RTC backscatter?
scattering_area (bool) – output scattering area image?
- S1_NRB.snap.sgr(src, dst, workflow, src_gamma=None)[source]
Sigma-gamma ratio computation.
- Parameters
src (str) – the file name of the source scene. Both sigma and gamma bands are expected unless src_gamma is defined.
dst (str) – the file name of the target scene. Format is BEAM-DIMAP.
workflow (str) – the output SNAP XML workflow filename.
src_gamma (str or None) – the optional file name of a second source product from which to read the gamma band.
NRB
Calculates the start and stop times of the NRB product. |
|
Creation of the Acquisition ID image. |
|
Creation of the Data Mask image. |
|
Creation of the color composite VRT file. |
|
Creates a VRT file for the specified source dataset(s) and adds a pixel function that should be applied on the fly when opening the VRT file. |
|
Finalizes the generation of Sentinel-1 NRB products after RTC processing has finished. |
|
Reads metadata from all source SLC/GRD scenes, finds matching output files in datadir and filters both lists depending on the actual overlap of each SLC/GRD footprint with the current MGRS tile geometry. |
- S1_NRB.nrb.calc_product_start_stop(src_ids, extent, epsg)[source]
Calculates the start and stop times of the NRB product. The geolocation grid points including their azimuth time information are extracted first from the metadata of each source SLC. These grid points are then used to interpolate the azimuth time for the lower right and upper left (ascending) or upper right and lower left (descending) corners of the MGRS tile extent.
- Parameters
- Returns
tuple[str]
Start time of the NRB product formatted as %Y%m%dT%H%M%S in UTC.
Stop time of the NRB product formatted as %Y%m%dT%H%M%S in UTC.
- S1_NRB.nrb.create_acq_id_image(outname, ref_tif, datasets, src_ids, extent, epsg, driver, creation_opt, overviews, dst_nodata)[source]
Creation of the Acquisition ID image.
- Parameters
outname (str) – Full path to the output data mask file.
ref_tif (str) – Full path to any GeoTIFF file of the NRB product.
datasets (list[dict]) – List of processed output files that match the source SLC scenes and overlap with the current MGRS tile.
src_ids (list[pyroSAR.drivers.ID]) – List of
IDobjects of all source SLC scenes that overlap with the current MGRS tile.extent (dict) – Spatial extent of the MGRS tile, derived from a
Vectorobject.epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
driver (str) – GDAL driver to use for raster file creation.
creation_opt (list[str]) – GDAL creation options to use for raster file creation. Should match specified GDAL driver.
overviews (list[int]) – Internal overview levels to be created for each raster file.
dst_nodata (int or str) – Nodata value to write to the output raster.
- S1_NRB.nrb.create_data_mask(outname, datasets, extent, epsg, driver, creation_opt, overviews, overview_resampling, dst_nodata, wbm=None)[source]
Creation of the Data Mask image.
- Parameters
outname (str) – Full path to the output data mask file.
datasets (list[dict]) – List of processed output files that match the source scenes and overlap with the current MGRS tile. An error will be thrown if not all datasets contain a key datamask. The function will return without an error if not all datasets contain a key dm.
extent (dict) – Spatial extent of the MGRS tile, derived from a
Vectorobject.epsg (int) – The coordinate reference system as an EPSG code.
driver (str) – GDAL driver to use for raster file creation.
creation_opt (list[str]) – GDAL creation options to use for raster file creation. Should match specified GDAL driver.
overviews (list[int]) – Internal overview levels to be created for each raster file.
overview_resampling (str) – Resampling method for overview levels.
dst_nodata (int or str) – Nodata value to write to the output raster.
wbm (str or None) – Path to a water body mask file with the dimensions of an MGRS tile.
- S1_NRB.nrb.create_rgb_vrt(outname, infiles, overviews, overview_resampling)[source]
Creation of the color composite VRT file.
- Parameters
outname (str) – Full path to the output VRT file.
infiles (list[str]) – A list of paths pointing to the linear scaled measurement backscatter files.
overviews (list[int]) – Internal overview levels to be defined for the created VRT file.
overview_resampling (str) – Resampling method applied to overview pyramids.
- S1_NRB.nrb.create_vrt(src, dst, fun, relpaths=False, scale=None, offset=None, args=None, options=None, overviews=None, overview_resampling=None)[source]
Creates a VRT file for the specified source dataset(s) and adds a pixel function that should be applied on the fly when opening the VRT file.
- Parameters
dst (str) – The output dataset.
fun (str) – A PixelFunctionType that should be applied on the fly when opening the VRT file. The function is applied to a band that derives its pixel information from the source bands. A list of possible options can be found here: https://gdal.org/drivers/raster/vrt.html#default-pixel-functions. Furthermore, the option ‘decibel’ can be specified, which will implement a custom pixel function that uses Python code for decibel conversion (10*log10).
relpaths (bool) – Should all SourceFilename XML elements with attribute @relativeToVRT=”0” be updated to be paths relative to the output VRT file? Default is False.
scale (int or None) – The scale that should be applied when computing “real” pixel values from scaled pixel values on a raster band. Will be ignored if fun=’decibel’.
offset (float or None) – The offset that should be applied when computing “real” pixel values from scaled pixel values on a raster band. Will be ignored if fun=’decibel’.
args (dict or None) – arguments for fun passed as PixelFunctionArguments. Requires GDAL>=3.5 to be read.
options (dict or None) – Additional parameters passed to gdal.BuildVRT.
overviews (list[int] or None) – Internal overview levels to be created for each raster file.
overview_resampling (str or None) – Resampling method for overview levels.
Examples
linear gamma0 backscatter as input:
>>> src = 's1a-iw-nrb-20220601t052704-043465-0530a1-32tpt-vh-g-lin.tif'
decibel scaling I: use log10 pixel function and additional Scale parameter. Known to display well in QGIS, but Scale is ignored when reading array in Python.
>>> dst = src.replace('-lin.tif', '-log1.vrt') >>> create_vrt(src=src, dst=dst, fun='log10', scale=10)
decibel scaling II: use custom Python pixel function. Requires additional environment variable GDAL_VRT_ENABLE_PYTHON set to YES.
>>> dst = src.replace('-lin.tif', '-log2.vrt') >>> create_vrt(src=src, dst=dst, fun='decibel')
decibel scaling III: use dB pixel function with additional PixelFunctionArguments. Works best but requires GDAL>=3.5.
>>> dst = src.replace('-lin.tif', '-log3.vrt') >>> create_vrt(src=src, dst=dst, fun='dB', args={'fact': 10})
- S1_NRB.nrb.format(config, scenes, datadir, outdir, tile, extent, epsg, wbm=None, dem_type=None, multithread=True, compress=None, overviews=None, kml=None, annotation=None, update=False)[source]
Finalizes the generation of Sentinel-1 NRB products after RTC processing has finished. This includes the following: - Creating all measurement and annotation datasets in Cloud Optimized GeoTIFF (COG) format - Creating additional annotation datasets in Virtual Raster Tile (VRT) format - Applying the NRB product directory structure & naming convention - Generating metadata in XML and JSON formats for the NRB product as well as source SLC datasets
- Parameters
config (dict) – Dictionary of the parsed config parameters for the current process.
scenes (list[str]) – List of scenes to process. Either an individual scene or multiple, matching scenes (consecutive acquisitions).
datadir (str) – The directory containing the datasets processed from the source scenes using pyroSAR.
outdir (str) – The directory to write the final files to.
tile (str) – ID of an MGRS tile.
extent (dict) – Spatial extent of the MGRS tile, derived from a
Vectorobject.epsg (int) – The CRS used for the NRB product; provided as an EPSG code.
wbm (str or None) – Path to a water body mask file with the dimensions of an MGRS tile.
dem_type (str or None) – if defined, a DEM layer will be added to the product. The suffix em (elevation model) is used. Default None: do not add a DEm layer.
multithread (bool) – Should gdalwarp use multithreading? Default is True. The number of threads used, can be adjusted in the config.ini file with the parameter gdal_threads.
compress (str or None) – Compression algorithm to use. See https://gdal.org/drivers/raster/gtiff.html#creation-options for options. Defaults to ‘LERC_DEFLATE’.
overviews (list[int] or None) – Internal overview levels to be created for each GeoTIFF file. Defaults to [2, 4, 9, 18, 36]
kml (str or None) – The KML file containing the MGRS tile geometries. Only needs to be defined if dem_type!=None.
annotation (list[str] or None) –
an optional list to select the annotation layers. Default None: create all layers if the source products contain the required input layers. Options:
dm: data mask (four masks: not layover not shadow, layover, shadow, ocean water)
ei: ellipsoidal incident angle
em: digital elevation model
id: acquisition ID image (source scene ID per pixel)
lc: RTC local contributing area
li: local incident angle
np: noise power (NESZ, per polarization)
gs: gamma-sigma ratio: sigma0 RTC / gamma0 RTC
sg: sigma-gamma ratio: gamma0 RTC / sigma0 ellipsoidal
update (bool) – modify existing products so that only missing files are re-created?
- Returns
Either the time spent executing the function in seconds or ‘Already processed - Skip!’
- Return type
- S1_NRB.nrb.get_datasets(scenes, datadir, extent, epsg)[source]
Reads metadata from all source SLC/GRD scenes, finds matching output files in datadir and filters both lists depending on the actual overlap of each SLC/GRD footprint with the current MGRS tile geometry.
- Parameters
scenes (list[str]) – List of scenes to process. Either an individual scene or multiple, matching scenes (consecutive acquisitions).
datadir (str) – The directory containing the datasets processed from the source scenes using pyroSAR.
extent (dict) – Spatial extent of the MGRS tile, derived from a
Vectorobject.epsg (int) – The coordinate reference system as an EPSG code.
- Returns
ids (list[
pyroSAR.drivers.ID]) – List ofIDobjects of all source SLC/GRD scenes that overlap with the current MGRS tile.datasets (list[dict]) – List of RTC processing output files that match each
IDobject of ids. The format is a list of dictionaries per scene with keys as described by e.g.S1_NRB.snap.find_datasets().
ETAD
Apply ETAD correction to a Sentinel-1 SLC product. |
- S1_NRB.etad.process(scene, etad_dir, out_dir, log)[source]
Apply ETAD correction to a Sentinel-1 SLC product.
- Parameters
scene (pyroSAR.drivers.ID) – The Sentinel-1 SLC scene.
etad_dir (str) – The directory containing ETAD products. This will be searched for products matching the defined SLC.
out_dir (str) – The directory to store results. The ETAD product is unpacked to this directory if necessary. Two new sub-directories SLC_original SLC_ETAD and are created, which contain the original unpacked scene and the corrected one respectively.
log (logging.Logger) – A logger object to write log info.
- Returns
The corrected scene as a pyroSAR ID object.
- Return type
DEM
Create a new scene-specific DEM mosaic GeoTIFF file. |
|
Downloads DEM and WBM tiles and restructures them into the MGRS tiling scheme including re-projection and vertical datum conversion. |
- S1_NRB.dem.authenticate(dem_type, username=None, password=None)[source]
Query the username and password. If None, environment variables DEM_USER and DEM_PASS are read. If they are also None, the user is queried interactively.
- Parameters
dem_type (str) – the DEM type. Needed for determining whether authentication is needed.
username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.
password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.
- Returns
the username and password
- Return type
- S1_NRB.dem.mosaic(geometry, dem_type, outname, epsg=None, kml_file=None, dem_dir=None, username=None, password=None, threads=4)[source]
Create a new scene-specific DEM mosaic GeoTIFF file. Can be created from MGRS-tiled DEMs as created by
S1_NRB.dem.prepare()or ad hoc usingpyroSAR.auxdata.dem_autoload()andpyroSAR.auxdata.dem_create(). In the former case the arguments username, password and threads are ignored and all tiles found in dem_dir are read. In the latter case the arguments epsg, kml_file and dem_dir are ignored and the DEM is only mosaiced and geoid-corrected.- Parameters
geometry (spatialist.vector.Vector) – The geometry to be covered by the mosaic.
dem_type (str) – The DEM type.
outname (str) – The name of the mosaic.
epsg (int or None) – The coordinate reference system as an EPSG code.
kml_file (str or None) – The KML file containing the MGRS tile geometries.
dem_dir (str or None) – The directory containing the DEM MGRS tiles.
username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.
password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.
threads (int) – The number of threads to pass to
pyroSAR.auxdata.dem_create().
- S1_NRB.dem.prepare(vector, dem_type, dem_dir, wbm_dir, kml_file, dem_strict=True, tilenames=None, threads=None, username=None, password=None)[source]
Downloads DEM and WBM tiles and restructures them into the MGRS tiling scheme including re-projection and vertical datum conversion.
- Parameters
vector (spatialist.vector.Vector) – The vector object for which to prepare the DEM and WBM tiles. CRS must be EPSG:4236.
dem_type (str) – The DEM type.
dem_dir (str or None) – The DEM target directory. DEM preparation can be skipped if set to None.
wbm_dir (str or None) – The WBM target directory. WBM preparation can be skipped if set to None
kml_file (str) – The KML file containing the MGRS tile geometries.
dem_strict (bool) – strictly only create DEM tiles in the native CRS of the MGRS tile or also allow reprojection to ensure full coverage of the vector object in every CRS.
tilenames (list[str] or None) – an optional list of MGRS tile names. Default None: process all overalapping tiles.
threads (int or None) – The number of threads to pass to
pyroSAR.auxdata.dem_create(). Default None: use the value of GDAL_NUM_THREADS without modification.username (str or None) – The username for accessing the DEM tiles. If None and authentication is required for the selected DEM type, the environment variable ‘DEM_USER’ is read. If this is not set, the user is prompted interactively to provide credentials.
password (str or None) – The password for accessing the DEM tiles. If None: same behavior as for username but with env. variable ‘DEM_PASS’.
Examples
>>> from S1_NRB import dem >>> from spatialist import bbox >>> ext = {'xmin': 12, 'xmax': 13, 'ymin': 50, 'ymax': 51} >>> kml = 'S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml' # strictly only create overlapping DEM tiles in their native CRS. # Will create tiles 32UQA, 32UQB, 33UUR and 33UUS. >>> with bbox(coordinates=ext, crs=4326) as vec: >>> dem.prepare(vector=vec, dem_type='Copernicus 30m Global DEM', >>> dem_dir='DEM', wbm_dir=None, dem_strict=True, >>> kml_file=kml, threads=4) # Process all overlapping DEM tiles to each CRS. # Will additionally create tiles 32UQA_32633, 32UQB_32633, 33UUR_32632 and 33UUS_32632. >>> with bbox(coordinates=ext, crs=4326) as vec: >>> dem.prepare(vector=vec, dem_type='Copernicus 30m Global DEM', >>> dem_dir='DEM', wbm_dir=None, dem_strict=False, >>> kml_file=kml, threads=4)
See also
- S1_NRB.dem.to_mgrs(tile, dst, kml, dem_type, overviews, tr, format='COG', create_options=None, threads=None, pbar=False)[source]
Create an MGRS-tiled DEM file.
- Parameters
tile (str) – the MGRS tile ID
dst (str) – the destination file name
kml (str) – The KML file containing the MGRS tile geometries.
dem_type (str) – The DEM type.
format (str) – the output file format
create_options (list[str] or None) – additional creation options to be passed to
spatialist.auxil.gdalwarp().threads (int or None) – The number of threads to pass to
pyroSAR.auxdata.dem_create(). Default None: use the value of GDAL_NUM_THREADS without modification.pbar (bool) –
Tile Extraction
Extract one or multiple MGRS tiles from the global Sentinel-2 tiling grid and return it as a |
|
Convert the HTML description field of the MGRS tile KML file to a dictionary. |
|
Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest. |
- S1_NRB.tile_extraction.aoi_from_tile(kml, tile)[source]
Extract one or multiple MGRS tiles from the global Sentinel-2 tiling grid and return it as a
Vectorobject.- Parameters
kml (str) – Path to the Sentinel-2 tiling grid KML file.
tile (str or list[str]) – The MGRS tile ID(s) that should be extracted and returned as a vector object. Can also be expressed as <tile ID>_<EPSG code> (e.g. 33TUN_32632). In this case the geometry of the tile is reprojected to the target EPSG code, its corner coordinates rounded to multiples of 10, and a new
Vectorobject created.
- Returns
either a single object or a list depending on tile
- Return type
Notes
The global Sentinel-2 tiling grid can be retrieved from: https://sentinel.esa.int/documents/247904/1955685/S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml
- S1_NRB.tile_extraction.description2dict(description)[source]
Convert the HTML description field of the MGRS tile KML file to a dictionary.
- S1_NRB.tile_extraction.tile_from_aoi(vector, kml, epsg=None, strict=True, return_geometries=False, tilenames=None)[source]
Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest.
- Parameters
vector (spatialist.vector.Vector or list[spatialist.vector.Vector]) – The vector object(s) to read. CRS must be EPSG:4236.
kml (str) – Path to the Sentinel-2 tiling grid KML file.
epsg (int or list[int] or None) – Define which EPSG code(s) are allowed for the tile selection. If None, all tile IDs are returned regardless of projection.
strict (bool) – Strictly only return the names/geometries of the overlapping tiles in the target projection or also allow reprojection of neighbouring tiles? In the latter case a tile name takes the form <tile ID>_<EPSG code>, e.g. 33TUN_32632. Only applies if argument epsg is of type int or a list with one element.
return_geometries (bool) – return a list of
spatialist.vector.Vectorgeometry objects (or just the tile names)?tilenames (list[str] or None) – an optional list of MGRS tile names to limit the selection
- Returns
tiles – A list of unique MGRS tile IDs or
spatialist.vector.Vectorobjects with an attribute mgrs containing the tile ID.- Return type
Notes
The global Sentinel-2 tiling grid can be retrieved from: https://sentinel.esa.int/documents/247904/1955685/S2A_OPER_GIP_TILPAR_MPC__20151209T095117_V20150622T000000_21000101T000000_B00.kml
Ancillary Functions
Check presence of neighboring acquisitions. |
|
Check the consistency of a scene selection. |
|
Check whether the spacing fits into the MGRS tile boundaries. |
|
Returns a unique product identifier as a hexadecimal string. |
|
Gets the maximum extent from a list of geometries. |
|
Group scenes by their acquisition time difference. |
|
Format and handle log messages during processing. |
|
Set logging for the current process. |
|
Add overviews to an existing VRT file. |
- S1_NRB.ancillary.check_acquisition_completeness(scenes, archive)[source]
Check presence of neighboring acquisitions. Check that for each scene a predecessor and successor can be queried from the database unless the scene is at the start or end of the data take. This ensures that no scene that could be covering an area of interest is missed during processing.
- Parameters
scenes (list[pyroSAR.drivers.ID]) – a list of scenes
archive (pyroSAR.drivers.Archive) – an open scene archive connection
- Raises
- S1_NRB.ancillary.check_scene_consistency(scenes)[source]
Check the consistency of a scene selection. The following pyroSAR object attributes must be the same:
sensor
acquisition_mode
product
frameNumber (data take ID)
- Parameters
scenes (list[str or pyroSAR.drivers.ID]) –
- Raises
- S1_NRB.ancillary.check_spacing(spacing)[source]
Check whether the spacing fits into the MGRS tile boundaries.
- S1_NRB.ancillary.generate_unique_id(encoded_str)[source]
Returns a unique product identifier as a hexadecimal string. The CRC-16 algorithm used to compute the unique identifier is CRC-CCITT (0xFFFF).
- S1_NRB.ancillary.get_max_ext(geometries, buffer=None)[source]
Gets the maximum extent from a list of geometries.
- S1_NRB.ancillary.group_by_time(scenes, time=3)[source]
Group scenes by their acquisition time difference.
- Parameters
scenes (list[pyroSAR.drivers.ID or str]) – a list of image names
time (int or float) – a time difference in seconds by which to group the scenes. The default of 3 seconds incorporates the overlap between SLCs.
- Returns
a list of sub-lists containing the file names of the grouped scenes
- Return type
- S1_NRB.ancillary.log(handler, mode, proc_step, scenes, msg)[source]
Format and handle log messages during processing.
- Parameters
handler (logging.Logger) – The log handler for the current process.
mode ({'info', 'warning', 'exception'}) – Calls the respective logging helper function. E.g.,
handler.info().proc_step (str) – The processing step for which the message is logged.
scenes (str or list[str]) – Scenes that are currently being processed.
msg (Any) – The message that should be logged.
Metadata
Extraction
Calculates the radial root mean square error, which is a target requirement of the CARD4L NRB specification (Item 4.3). |
|
Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images if available. |
|
Retrieve the manifest and annotation XML data of a scene as a dictionary using an |
|
Extracts all values for Peak Side Lobe Ratio (PSLR) and Integrated Side Lobe Ratio (ISLR) from the annotation metadata of a scene and calculates the mean value for all swaths. |
|
Search for a pattern in all XML annotation files provided and return a dictionary of results. |
|
Get geometry information for usage in STAC and XML metadata from a |
|
Gets the header size of a GeoTIFF file in bytes. |
|
Returns a metadata dictionary, which is generated from the name of a product scene using a regular expression pattern and from a measurement GeoTIFF file of the same product scene using the |
|
Creates a dictionary containing metadata for a product scene, as well as its source scenes. |
|
Creates a single |
- S1_NRB.metadata.extract.calc_geolocation_accuracy(swath_identifier, ei_tif, dem_type, etad)[source]
Calculates the radial root mean square error, which is a target requirement of the CARD4L NRB specification (Item 4.3). For more information see: https://s1-nrb.readthedocs.io/en/latest/general/geoaccuracy.html. Currently only the Copernicus DEM is supported.
- Parameters
- Returns
rmse_planar – The calculated rRMSE value rounded to two decimal places or None if a DEM other than Copernicus is used.
- Return type
float or None
- S1_NRB.metadata.extract.calc_performance_estimates(files)[source]
Calculates the performance estimates specified in CARD4L NRB 1.6.9 for all noise power images if available.
- S1_NRB.metadata.extract.etree_from_sid(sid)[source]
Retrieve the manifest and annotation XML data of a scene as a dictionary using an
pyroSAR.drivers.IDobject.- Parameters
sid (pyroSAR.drivers.ID) – A pyroSAR
IDobject generated with e.g.pyroSAR.drivers.identify().- Returns
A dictionary containing the parsed etree.ElementTree objects for the manifest and annotation XML files.
- Return type
- S1_NRB.metadata.extract.extract_pslr_islr(annotation_dict)[source]
Extracts all values for Peak Side Lobe Ratio (PSLR) and Integrated Side Lobe Ratio (ISLR) from the annotation metadata of a scene and calculates the mean value for all swaths.
- S1_NRB.metadata.extract.find_in_annotation(annotation_dict, pattern, single=False, out_type='str')[source]
Search for a pattern in all XML annotation files provided and return a dictionary of results.
- Parameters
annotation_dict (dict) – A dict of annotation files in the form: {‘swath ID’: lxml.etree._Element object}
pattern (str) – The pattern to search for in each annotation file.
single (bool) – If True, the results found in each annotation file are expected to be the same and therefore only a single value will be returned instead of a dict. If the results differ, an error is raised. Default is False.
out_type (str) –
Output type to convert the results to. Can be one of the following:
’str’ (default)
’float’
’int’
- Returns
out – A dictionary of the results containing a list for each of the annotation files. E.g., {‘swath ID’: list[str or float or int]}
- Return type
- S1_NRB.metadata.extract.geometry_from_vec(vectorobject)[source]
Get geometry information for usage in STAC and XML metadata from a
spatialist.vector.Vectorobject.- Parameters
vectorobject (spatialist.vector.Vector) – The vector object to extract geometry information from.
- Returns
out – A dictionary containing the geometry information extracted from the vector object.
- Return type
- S1_NRB.metadata.extract.get_header_size(tif)[source]
Gets the header size of a GeoTIFF file in bytes. The code used in this function and its helper function _get_block_offset were extracted from the following source:
Copyright (c) 2017, Even Rouault
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
- S1_NRB.metadata.extract.get_prod_meta(product_id, tif, src_ids, rtc_dir)[source]
Returns a metadata dictionary, which is generated from the name of a product scene using a regular expression pattern and from a measurement GeoTIFF file of the same product scene using the
Rasterclass.- Parameters
product_id (str) – The top-level product folder name.
tif (str) – The path to a measurement GeoTIFF file of the product scene.
src_ids (list[pyroSAR.drivers.ID]) – List of
IDobjects of all source SLC scenes that overlap with the current MGRS tile.rtc_dir (str) – A path pointing to the processed datasets of the product.
- Returns
A dictionary containing metadata for the product scene.
- Return type
- S1_NRB.metadata.extract.meta_dict(config, target, src_ids, rtc_dir, proc_time, start, stop, compression)[source]
Creates a dictionary containing metadata for a product scene, as well as its source scenes. The dictionary can then be utilized by
parse()andparse()to generate XML and STAC JSON metadata files, respectively.- Parameters
config (dict) – Dictionary of the parsed config parameters for the current process.
target (str) – A path pointing to the NRB product scene being created.
src_ids (list[pyroSAR.drivers.ID]) – List of
IDobjects of all source scenes that overlap with the current MGRS tile.rtc_dir (str) – The RTC processing output directory.
proc_time (datetime.datetime) – The processing time object used to generate the unique product identifier.
start (datetime.datetime) – The product start time.
stop (datetime.datetime) – The product stop time.
compression (str) – The compression type applied to raster files of the product.
- Returns
meta – A dictionary containing a collection of metadata for product as well as source scenes.
- Return type
XML
Wrapper for |
|
Function to generate product-level metadata for an NRB product in OGC 10-157r4 compliant XML format. |
|
Function to generate source-level metadata for an NRB product in OGC 10-157r4 compliant XML format. |
- S1_NRB.metadata.xml.parse(meta, target, tifs, exist_ok=False)[source]
Wrapper for
source_xml()andproduct_xml().- Parameters
- S1_NRB.metadata.xml.product_xml(meta, target, tifs, nsmap, exist_ok=False)[source]
Function to generate product-level metadata for an NRB product in OGC 10-157r4 compliant XML format.
- Parameters
meta (dict) – Metadata dictionary generated with
meta_dict()target (str) – A path pointing to the root directory of a product scene.
tifs (list[str]) – List of paths to all GeoTIFF files of the currently processed NRB product.
nsmap (dict) – Dictionary listing abbreviation (key) and URI (value) of all necessary XML namespaces.
exist_ok (bool) – Do not create files if they already exist?
- S1_NRB.metadata.xml.source_xml(meta, target, nsmap, exist_ok=False)[source]
Function to generate source-level metadata for an NRB product in OGC 10-157r4 compliant XML format.
- Parameters
meta (dict) – Metadata dictionary generated with
meta_dict()target (str) – A path pointing to the root directory of a product scene.
nsmap (dict) – Dictionary listing abbreviation (key) and URI (value) of all necessary XML namespaces.
exist_ok (bool) – Do not create files if they already exist?
STAC
Wrapper for |
|
Function to generate product-level metadata for an NRB product in STAC compliant JSON format. |
|
Function to generate source-level metadata for an NRB product in STAC compliant JSON format. |
|
For a given directory of Sentinel-1 NRB products, this function will create a high-level STAC |
- S1_NRB.metadata.stac.make_catalog(directory, recursive=True, silent=False)[source]
For a given directory of Sentinel-1 NRB products, this function will create a high-level STAC
Catalogobject serving as the STAC endpoint and lower-level STACCollectionobjects for each subdirectory corresponding to a unique MGRS tile ID.WARNING: The directory content will be reorganized into subdirectories based on unique MGRS tile IDs if this is not yet the case.
- Parameters
- Returns
nrb_catalog – STAC Catalog object
- Return type
Notes
The returned STAC Catalog object contains Item asset hrefs that are absolute, whereas the actual on-disk files contain relative asset hrefs corresponding to the self-contained Catalog-Type. The returned in-memory STAC Catalog object deviates in this regard to ensure compatibility with the stackstac library: https://github.com/gjoseph92/stackstac/issues/20
- S1_NRB.metadata.stac.parse(meta, target, tifs, exist_ok=False)[source]
Wrapper for
source_json()andproduct_json().
- S1_NRB.metadata.stac.product_json(meta, target, tifs, exist_ok=False)[source]
Function to generate product-level metadata for an NRB product in STAC compliant JSON format.
- Parameters
- S1_NRB.metadata.stac.source_json(meta, target, exist_ok=False)[source]
Function to generate source-level metadata for an NRB product in STAC compliant JSON format.
- Parameters
meta (dict) – Metadata dictionary generated with
meta_dict().target (str) – A path pointing to the root directory of a product scene.
exist_ok (bool) – Do not create files if they already exist?