Processing

This module is intended as a set of generalized processing routines for modularized GAMMA work flows. The function parametrization is intended to be applicable to any kind of situation and input data set. Thus, instead of choosing a specific parametrization for the data at hand, core parameters are iterated over a set of values in order to find the one best suited for the task. The approach of the single routines is likely to still have drawbacks and might fail in certain situations. Testing and suggestions on improvements are very welcome.

calibrate

radiometric calibration of SAR scenes

convert2gamma

general function for converting SAR images to GAMMA format

correctOSV

correct GAMMA parameter files with orbit state vector information from dedicated OSV files; OSV files are downloaded automatically to either the defined osvdir or relative to the user's home directory: ~/.snap/auxdata/Orbits/Sentinel-1.

gc_map_wrap

helper function for computing DEM products in function geocode.

geocode

general function for radiometric terrain correction (RTC) and geocoding of SAR backscatter images with GAMMA.

lat_linear_to_db

Alternative to LAT module command linear_to_dB.

lat_product

Alternative to LAT module command product.

lat_ratio

Alternative to LAT module command ratio.

multilook

Multilooking of SLC and MLI images.

ovs

compute DEM oversampling factors for a target resolution in meters

pixel_area_wrap

helper function for computing pixel_area files in function geocode.

S1_deburst

Debursting of Sentinel-1 SLC imagery in GAMMA
pyroSAR.gamma.util.S1_deburst(burst1, burst2, burst3, name_out, rlks=5, azlks=1, replace=False, logpath=None, outdir=None, shellscript=None)[source]

Debursting of Sentinel-1 SLC imagery in GAMMA

The procedure consists of two steps. First antenna pattern deramping and then mosaicing of the single deramped bursts. For mosaicing, the burst boundaries are calculated from the number of looks in range (rlks) and azimuth (azlks), in this case 5 range looks and 1 azimuth looks. Alternately 10 range looks and 2 azimuth looks could be used.

Parameters:

  • burst1 (str) – burst image 1

  • burst2 (str) – burst image 2

  • burst3 (str) – burst image 3

  • name_out (str) – the name of the output file

  • rlks (int) – the number of looks in range

  • azlks (int) – the number of looks in azimuth

  • replace (bool) – replace the burst images by the new file? If True, the three burst images will be deleted.

  • logpath (str or None) – a directory to write command logfiles to

  • outdir (str or None) – the directory to execute the command in

  • shellscript (str or None) – a file to write the Gamma commands to in shell format

pyroSAR.gamma.util.calibrate(id, directory, return_fnames=False, logpath=None, outdir=None, shellscript=None)[source]

radiometric calibration of SAR scenes

Parameters:

  • id (ID) – an SAR scene object of type pyroSAR.ID or any subclass

  • directory (str) – the directory to search for GAMMA calibration candidates

  • return_fnames (bool) – return the names of the output image files? Default: False.

  • logpath (str or None) – a directory to write command logfiles to

  • outdir (str or None) – the directory to execute the command in

  • shellscript (str or None) – a file to write the GAMMA commands to in shell format

Return type:

List[str] or None

pyroSAR.gamma.util.convert2gamma(id, directory, S1_tnr=True, S1_bnr=True, basename_extensions=None, exist_ok=False, return_fnames=False, logpath=None, outdir=None, shellscript=None)[source]

general function for converting SAR images to GAMMA format

Parameters:

  • id (ID) – an SAR scene object of type pyroSAR.ID or any subclass

  • directory (str) – the output directory for the converted images

  • S1_tnr (bool) – only Sentinel-1: should thermal noise removal be applied to the image?

  • S1_bnr (bool) – only Sentinel-1 GRD: should border noise removal be applied to the image? This is available since version 20191203, for older versions this argument is ignored.

  • basename_extensions (list[str] or None) – names of additional parameters to append to the basename, e.g. [‘orbitNumber_rel’]

  • exist_ok (bool) – allow existing output files and do not create new ones?

  • return_fnames (bool) – return the names of the output image files? Default: False.

  • logpath (str or None) – a directory to write command logfiles to

  • outdir (str or None) – the directory to execute the command in

  • shellscript (str or None) – a file to write the GAMMA commands to in bash format

Returns:

the sorted image file names if return_fnames=True and None otherwise

Return type:

list[str] or None

pyroSAR.gamma.util.correctOSV(id, directory, osvdir=None, osvType='POE', timeout=20, logpath=None, outdir=None, shellscript=None, url_option=1)[source]

correct GAMMA parameter files with orbit state vector information from dedicated OSV files; OSV files are downloaded automatically to either the defined osvdir or relative to the user’s home directory: ~/.snap/auxdata/Orbits/Sentinel-1.

Parameters:

  • id (ID) – the scene to be corrected

  • directory (str or None) – a directory to be scanned for files associated with the scene, e.g. an SLC in GAMMA format. If the OSV file is packed in a zip file it will be unpacked to a subdirectory osv.

  • osvdir (str or None) – the directory of the OSV files. Default None: use the SNAP directory as configured via pyroSAR.examine.ExamineSnap or, if SNAP is not installed, ~/.snap/auxdata/Orbits/Sentinel-1 (SNAP default). Subdirectories POEORB and RESORB are created automatically.

  • osvType (str or list[str]) – the OSV type (POE|RES) to be used

  • timeout (int or tuple or None) – the timeout in seconds for downloading OSV files as provided to requests.get()

  • logpath (str or None) – a directory to write command logfiles to

  • outdir (str or None) – the directory to execute the command in

  • shellscript (str or None) – a file to write the GAMMA commands to in shell format

  • url_option (int) – the OSV download URL option; see pyroSAR.S1.OSV.catch()

Examples

>>> from pyroSAR import identify
>>> from pyroSAR.gamma import correctOSV, convert2gamma
>>> filename = 'S1A_IW_GRDH_1SDV_20150222T170750_20150222T170815_004739_005DD8_3768.zip'
# identify the SAR scene
>>> scene = identify(filename)
# unpack the zipped scene to an arbitrary directory
>>> scene.unpack('/home/test')
>>> print(scene.scene)
/home/test/S1A_IW_GRDH_1SDV_20150222T170750_20150222T170815_004739_005DD8_3768.SAFE
# convert the unpacked scene to GAMMA format
>>> convert2gamma(id=scene, directory=scene.scene)
# correct the OSV information of the converted GAMMA images
>>> correctOSV(id=scene, osvdir='/home/test/osv')

See also

pyroSAR.drivers.SAFE.getOSV(), pyroSAR.S1.OSV

pyroSAR.gamma.util.gc_map_wrap(image, namespace, dem, spacing, exist_ok=False, logpath=None, outdir=None, shellscript=None)[source]

helper function for computing DEM products in function geocode.

Parameters:

  • image (str) – the reference SAR image

  • namespace (pyroSAR.gamma.auxil.Namespace) – an object collecting all output file names

  • dem (str) – the digital elevation model

  • spacing (int or float) – the target pixel spacing in meters

  • exist_ok (bool) – allow existing output files and do not create new ones?

  • logpath (str) – a directory to write command logfiles to

  • outdir (str) – the directory to execute the command in

  • shellscript (str) – a file to write the GAMMA commands to in shell format

pyroSAR.gamma.util.geocode(scene, dem, tmpdir, outdir, spacing, scaling='linear', func_geoback=1, nodata=(0, -99), update_osv=True, osvdir=None, allow_RES_OSV=False, cleanup=True, export_extra=None, basename_extensions=None, removeS1BorderNoiseMethod='gamma', refine_lut=False, rlks=None, azlks=None, s1_osv_url_option=1)[source]

general function for radiometric terrain correction (RTC) and geocoding of SAR backscatter images with GAMMA. Applies the RTC method by Small [3] to retrieve gamma nought RTC backscatter.

Parameters:

  • scene (str or ID or list) – the SAR scene(s) to be processed

  • dem (str) – the reference DEM in GAMMA format

  • tmpdir (str) – a temporary directory for writing intermediate files

  • outdir (str) – the directory for the final GeoTIFF output files

  • spacing (float or int) – the target pixel spacing in meters

  • scaling (str or list[str]) – the value scaling of the backscatter values; either ‘linear’, ‘db’ or a list of both, i.e. [‘linear’, ‘db’]

  • func_geoback ({0, 1, 2, 3, 4, 5, 6, 7}) –

    backward geocoding interpolation mode (see GAMMA command geocode_back)

    • 0: nearest-neighbor

    • 1: bicubic spline (default)

    • 2: bicubic-spline, interpolate log(data)

    • 3: bicubic-spline, interpolate sqrt(data)

    • 4: B-spline interpolation (default B-spline degree: 5)

    • 5: B-spline interpolation sqrt(x) (default B-spline degree: 5)

    • 6: Lanczos interpolation (default Lanczos function order: 5)

    • 7: Lanczos interpolation sqrt(x) (default Lanczos function order: 5)

    Note

    log and sqrt interpolation modes should only be used with non-negative data!

    Note

    GAMMA recommendation for MLI data: “The interpolation should be performed on the square root of the data. A mid-order (3 to 5) B-spline interpolation is recommended.”

  • nodata (tuple[float or int]) – the nodata values for the output files; defined as a tuple with two values, the first for linear, the second for logarithmic scaling

  • update_osv (bool) – update the orbit state vectors?

  • osvdir (str or None) – a directory for Orbit State Vector files; this is currently only used by for Sentinel-1 where two subdirectories POEORB and RESORB are created; if set to None, a subdirectory OSV is created in the directory of the unpacked scene.

  • allow_RES_OSV (bool) – also allow the less accurate RES orbit files to be used? Otherwise the function will raise an error if no POE file exists.

  • cleanup (bool) – should all files written to the temporary directory during function execution be deleted after processing?

  • export_extra (list[str] or None) –

    a list of image file IDs to be exported to outdir

    • format is GeoTIFF if the file is geocoded and ENVI otherwise. Non-geocoded images can be converted via GAMMA command data2tiff yet the output was found impossible to read with GIS software

    • scaling of SAR image products is applied as defined by parameter scaling

    • see Notes for ID options

  • basename_extensions (list[str] or None) – names of additional parameters to append to the basename, e.g. [‘orbitNumber_rel’]

  • removeS1BorderNoiseMethod (str or None) –

    the S1 GRD border noise removal method to be applied, See pyroSAR.S1.removeGRDBorderNoise() for details; one of the following:

    • ’ESA’: the pure implementation as described by ESA

    • ’pyroSAR’: the ESA method plus the custom pyroSAR refinement

    • ’gamma’: the GAMMA implementation of [1]

    • None: do not remove border noise

  • refine_lut (bool) – should the LUT for geocoding be refined using pixel area normalization?

  • rlks (int or None) – the number of range looks. If not None, overrides the computation done by function pyroSAR.ancillary.multilook_factors() based on the image pixel spacing and the target spacing.

  • azlks (int or None) – the number of azimuth looks. Like rlks.

  • s1_osv_url_option (int) – the OSV download URL option; see pyroSAR.S1.OSV.catch()

Note

intermediate output files
DEM products are named <scene identifier>_<ID>, e.g. S1A__IW___A_20141012T162337_inc_geo
SAR products will additionally contain the polarization, e.g. S1A__IW___A_20141012T162337_VV_grd_mli
IDs in brackets are only written if selected by export_extra

  • images in range-Doppler geometry

    • grd: the ground range detected SAR intensity image

    • grd_mli: the multi-looked grd image with approximated target resolution

    • (pix_ellip_sigma0): ellipsoid-based pixel area

    • (pix_area_sigma0): illuminated area as obtained from integrating DEM-facets in sigma projection (command pixel_area)

    • (pix_area_gamma0): illuminated area as obtained from integrating DEM-facets in gamma projection (command pixel_area)

    • pix_ratio: pixel area normalization factor (pix_ellip_sigma0 / pix_area_gamma0)

    • grd_mli_gamma0-rtc: the terrain-corrected gamma0 backscatter (grd_mli * pix_ratio)

    • (gs_ratio): gamma-sigma ratio (pix_gamma0 / pix_sigma0)

  • images in map geometry

    • dem_seg_geo: dem subsetted to the extent of the intersection between input DEM and SAR image

    • (u_geo): zenith angle of surface normal vector n (angle between z and n)

    • (v_geo): orientation angle of n (between x and projection of n in xy plane)

    • inc_geo: local incidence angle (between surface normal and look vector)

    • (psi_geo): projection angle (between surface normal and image plane normal)

    • ls_map_geo: layover and shadow map

    • (sim_sar_geo): simulated SAR backscatter image

    • (pix_ellip_sigma0_geo): ellipsoid-based pixel area

    • (pix_area_sigma0_geo): illuminated area as obtained from integrating DEM-facets in sigma projection (command pixel_area)

    • (pix_area_gamma0_geo): illuminated area as obtained from integrating DEM-facets in gamma projection (command pixel_area)

    • (pix_ratio_geo): pixel area normalization factor (pix_ellip_sigma0 / pix_area_gamma0)

    • (gs_ratio_geo): gamma-sigma ratio (pix_gamma0 / pix_sigma0)

  • additional files

    • lut_init: initial geocoding lookup table

  • files specific to lookup table refinement

    • lut_fine: refined geocoding lookup table

    • diffpar: ISP offset/interferogram parameter file

    • offs: offset estimates (fcomplex)

    • coffs: culled range and azimuth offset estimates (fcomplex)

    • coffsets: culled offset estimates and cross correlation values (text format)

    • ccp: cross-correlation of each patch (0.0->1.0) (float)

Examples

geocode a Sentinel-1 scene and export the local incidence angle map with it

>>> from pyroSAR.gamma import geocode
>>> filename = 'S1A_IW_GRDH_1SDV_20180829T170656_20180829T170721_023464_028DE0_F7BD.zip'
>>> geocode(scene=filename, dem='demfile', outdir='outdir', spacing=20, scaling='db',
>>>         export_extra=['dem_seg_geo', 'inc_geo', 'ls_map_geo'])
../../_images/gamma_geocode.svg

Workflow diagram for function geocode for processing a Sentinel-1 Ground Range Detected (GRD) scene to radiometrically terrain corrected (RTC) gamma nought backscatter.

pyroSAR.gamma.util.lat_linear_to_db(data_in, data_out)[source]

Alternative to LAT module command linear_to_dB.

Parameters:

  • data_in (str) – the input data file

  • data_out (str) – the output data file

pyroSAR.gamma.util.lat_product(data_in1, data_in2, data_out)[source]

Alternative to LAT module command product.

Parameters:

  • data_in1 (str) – input data file 1

  • data_in2 (str) – input data file 2

  • data_out (str) – the output data file

pyroSAR.gamma.util.lat_ratio(data_in1, data_in2, data_out)[source]

Alternative to LAT module command ratio.

Parameters:

  • data_in1 (str) – input data file 1

  • data_in2 (str) – input data file 2

  • data_out (str) – the output data file

pyroSAR.gamma.util.multilook(infile, outfile, spacing, rlks=None, azlks=None, exist_ok=False, logpath=None, outdir=None, shellscript=None)[source]

Multilooking of SLC and MLI images.

If the image is in slant range the ground range resolution is computed by dividing the range pixel spacing by the sine of the incidence angle.

The looks in range and azimuth are chosen to approximate the target resolution by rounding the ratio between target resolution and ground range/azimuth pixel spacing to the nearest integer.

An ENVI HDR parameter file is automatically written for better handling in other software.

Parameters:

  • infile (str or list[str]) –

    one of the following:

    • a SAR image in GAMMA format with a parameter file <infile>.par

    • a list of ScanSAR SLC swaths with parameter files <slc>.par and <slc>.tops_par; in this case a text file <outfile>_slc-tab.txt will be created, which is passed to the GAMMA command multi_look_ScanSAR

  • outfile (str) – the name of the output GAMMA MLI file

  • spacing (int) – the target pixel spacing in ground range

  • rlks (int or None) – the number of range looks. If not None, overrides the computation done by function pyroSAR.ancillary.multilook_factors() based on the image pixel spacing and the target spacing.

  • azlks (int or None) – the number of azimuth looks. Like rlks.

  • exist_ok (bool) – allow existing output files and do not create new ones?

  • logpath (str or None) – a directory to write command logfiles to

  • outdir (str or None) – the directory to execute the command in

  • shellscript (str or None) – a file to write the GAMMA commands to in shell format

See also

pyroSAR.ancillary.multilook_factors

pyroSAR.gamma.util.ovs(parfile, spacing)[source]

compute DEM oversampling factors for a target resolution in meters

Parameters:

  • parfile (str) – a GAMMA DEM parameter file

  • spacing (int or float) – the target pixel spacing in meters

Returns:

the oversampling factors for latitude and longitude

Return type:

tuple of float

pyroSAR.gamma.util.pixel_area_wrap(image, namespace, lut, exist_ok=False, logpath=None, outdir=None, shellscript=None)[source]

helper function for computing pixel_area files in function geocode.

Parameters:

  • image (str) – the reference SAR image

  • namespace (pyroSAR.gamma.auxil.Namespace) – an object collecting all output file names

  • lut (str) – the name of the lookup table

  • exist_ok (bool) – allow existing output files and do not create new ones?

  • logpath (str) – a directory to write command logfiles to

  • outdir (str) – the directory to execute the command in

  • shellscript (str) – a file to write the GAMMA commands to in shell format