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')

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