SNAP

Processing

geocode

general function for geocoding of SAR backscatter images with SNAP.

noise_power

Generate Sentinel-1 noise power images for each polarization, calibrated to either beta, sigma or gamma nought.
pyroSAR.snap.util.geocode(infile, outdir, t_srs=4326, spacing=20, polarizations='all', shapefile=None, scaling='dB', geocoding_type='Range-Doppler', removeS1BorderNoise=True, removeS1BorderNoiseMethod='pyroSAR', removeS1ThermalNoise=True, offset=None, allow_RES_OSV=False, demName='SRTM 1Sec HGT', externalDEMFile=None, externalDEMNoDataValue=None, externalDEMApplyEGM=True, terrainFlattening=True, basename_extensions=None, test=False, export_extra=None, groupsize=1, cleanup=True, tmpdir=None, gpt_exceptions=None, gpt_args=None, returnWF=False, nodataValueAtSea=True, demResamplingMethod='BILINEAR_INTERPOLATION', imgResamplingMethod='BILINEAR_INTERPOLATION', alignToStandardGrid=False, standardGridOriginX=0, standardGridOriginY=0, speckleFilter=False, refarea='gamma0', clean_edges=False, clean_edges_npixels=1, rlks=None, azlks=None)[source]

general function for geocoding of SAR backscatter images with SNAP.

This function performs the following steps:

Note

The function may create workflows with multiple Write nodes. All nodes are parametrized to write data in ENVI format, in which case the node parameter file is going to be a directory. All nodes will use the same temporary directory, which will be created in tmpdir. Its name is created from the basename of the infile (pyroSAR.drivers.ID.outname_base()) and a suffix identifying each processing node of the workflow (pyroSAR.snap.auxil.Workflow.suffix()).

For example: S1A__IW___A_20180101T170648_NR_Orb_Cal_ML_TF_TC.

Parameters

  • infile (str or ID or list) – The SAR scene(s) to be processed; multiple scenes are treated as consecutive acquisitions, which will be mosaicked with SNAP’s SliceAssembly operator.

  • outdir (str) – The directory to write the final files to.

  • t_srs (int, str or osr.SpatialReference) – A target geographic reference system in WKT, EPSG, PROJ4 or OPENGIS format. See function spatialist.auxil.crsConvert() for details. Default: 4326.

  • spacing (int or float, optional) – The target pixel spacing in meters. Default is 20

  • polarizations (list[str] or str) – The polarizations to be processed; can be a string for a single polarization, e.g. ‘VV’, or a list of several polarizations, e.g. [‘VV’, ‘VH’]. With the special value ‘all’ (default) all available polarizations are processed.

  • shapefile (str or Vector or dict, optional) – A vector geometry for subsetting the SAR scene to a test site. Default is None.

  • scaling ({'dB', 'db', 'linear'}, optional) – Should the output be in linear or decibel scaling? Default is ‘dB’.

  • geocoding_type ({'Range-Doppler', 'SAR simulation cross correlation'}, optional) – The type of geocoding applied; can be either ‘Range-Doppler’ (default) or ‘SAR simulation cross correlation’

  • removeS1BorderNoise (bool, optional) – Enables removal of S1 GRD border noise (default). Will be ignored if SLC scenes are processed.

  • removeS1BorderNoiseMethod (str, optional) –

    The border noise removal method to be applied if removeS1BorderNoise is True. 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 (default)

  • removeS1ThermalNoise (bool, optional) – Enables removal of S1 thermal noise (default).

  • offset (tuple, optional) – A tuple defining offsets for left, right, top and bottom in pixels, e.g. (100, 100, 0, 0); this variable is overridden if a shapefile is defined. Default is None.

  • allow_RES_OSV (bool) – (only applies to Sentinel-1) Also allow the less accurate RES orbit files to be used? The function first tries to download a POE file for the scene. If this fails and RES files are allowed, it will download the RES file. The selected OSV type is written to the workflow XML file. Processing is aborted if the correction fails (Apply-Orbit-File parameter continueOnFail set to false).

  • demName (str) –

    The name of the auto-download DEM. Default is ‘SRTM 1Sec HGT’. Is ignored when externalDEMFile is not None. Supported options:

    • ACE2_5Min

    • ACE30

    • ASTER 1sec GDEM

    • CDEM

    • Copernicus 30m Global DEM

    • Copernicus 90m Global DEM

    • GETASSE30

    • SRTM 1Sec Grid

    • SRTM 1Sec HGT

    • SRTM 3Sec

  • externalDEMFile (str or None, optional) – The absolute path to an external DEM file. Default is None. Overrides demName.

  • externalDEMNoDataValue (int, float or None, optional) – The no data value of the external DEM. If not specified (default) the function will try to read it from the specified external DEM.

  • externalDEMApplyEGM (bool, optional) – Apply Earth Gravitational Model to external DEM? Default is True.

  • terrainFlattening (bool) – Apply topographic normalization on the data?

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

  • test (bool, optional) – If set to True the workflow xml file is only written and not executed. Default is False.

  • export_extra (list or None) –

    A list of image file IDs to be exported to outdir. The following IDs are currently supported:

    • incidenceAngleFromEllipsoid

    • localIncidenceAngle

    • projectedLocalIncidenceAngle

    • DEM

    • layoverShadowMask

    • scatteringArea (requires terrainFlattening=True)

    • gammaSigmaRatio (requires terrainFlattening=True and refarea=['sigma0', 'gamma0'])

  • groupsize (int) – The number of workers executed together in one gpt call.

  • cleanup (bool) – Should all files written to the temporary directory during function execution be deleted after processing? Default is True.

  • tmpdir (str or None) – Path of custom temporary directory, useful to separate output folder and temp folder. If None, the outdir location will be used. The created subdirectory will be deleted after processing if cleanup=True.

  • gpt_exceptions (dict or None) –

    A dictionary to override the configured GPT executable for certain operators; each (sub-)workflow containing this operator will be executed with the define executable;

    • e.g. {'Terrain-Flattening': '/home/user/snap/bin/gpt'}

  • gpt_args (list or None) –

    A list of additional arguments to be passed to the gpt call.

    • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

  • returnWF (bool) – Return the full name of the written workflow XML file?

  • nodataValueAtSea (bool) – Mask pixels acquired over sea? The sea mask depends on the selected DEM.

  • demResamplingMethod (str) –

    One of the following:

    • ’NEAREST_NEIGHBOUR’

    • ’BILINEAR_INTERPOLATION’

    • ’CUBIC_CONVOLUTION’

    • ’BISINC_5_POINT_INTERPOLATION’

    • ’BISINC_11_POINT_INTERPOLATION’

    • ’BISINC_21_POINT_INTERPOLATION’

    • ’BICUBIC_INTERPOLATION’

  • imgResamplingMethod (str) – The resampling method for geocoding the SAR image; the options are identical to demResamplingMethod.

  • alignToStandardGrid (bool) – Align all processed images to a common grid?

  • standardGridOriginX (int or float) – The x origin value for grid alignment

  • standardGridOriginY (int or float) – The y origin value for grid alignment

  • speckleFilter (str) –

    One of the following:

    • ’Boxcar’

    • ’Median’

    • ’Frost’

    • ’Gamma Map’

    • ’Refined Lee’

    • ’Lee’

    • ’Lee Sigma’

  • refarea (str or list) – ‘sigma0’, ‘gamma0’ or a list of both

  • clean_edges (bool) – erode noisy image edges? See pyroSAR.snap.auxil.erode_edges(). Does not apply to layover-shadow mask.

  • clean_edges_npixels (int) – the number of pixels to erode.

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

Returns

Either the name of the workflow file if returnWF == True or None otherwise

Return type

str or None

../_images/snap_geocode.svg

Function geocode workflow diagram for processing Sentinel-1 scenes. Dashed lines depict optional steps. The output is sigma or gamma nought backscatter with ellipsoid or radiometric terrain correction (suffix elp/rtc) as well as several optional ancillary datasets (controlled via argument export_extra).

Examples

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

>>> from pyroSAR.snap import geocode
>>> filename = 'S1A_IW_GRDH_1SDV_20180829T170656_20180829T170721_023464_028DE0_F7BD.zip'
>>> geocode(infile=filename, outdir='outdir', tr=20, scaling='dB',
>>>         export_extra=['DEM', 'localIncidenceAngle'], t_srs=4326)

See also

pyroSAR.drivers.ID, spatialist.vector.Vector, spatialist.auxil.crsConvert()

pyroSAR.snap.util.noise_power(infile, outdir, polarizations, spacing, t_srs, refarea='sigma0', tmpdir=None, test=False, cleanup=True, demName='SRTM 1Sec HGT', externalDEMFile=None, externalDEMNoDataValue=None, externalDEMApplyEGM=True, alignToStandardGrid=False, standardGridOriginX=0, standardGridOriginY=0, groupsize=1, clean_edges=False, clean_edges_npixels=1, rlks=None, azlks=None)[source]

Generate Sentinel-1 noise power images for each polarization, calibrated to either beta, sigma or gamma nought. The written GeoTIFF files will carry the suffix NEBZ, NESZ or NEGZ respectively.

Parameters

  • infile (str) – The SAR scene(s) to be processed

  • outdir (str) – The directory to write the final files to.

  • polarizations (list[str]) – The polarizations to be processed, e.g. [‘VV’, ‘VH’].

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

  • t_srs (int or str or osr.SpatialReference) – A target geographic reference system in WKT, EPSG, PROJ4 or OPENGIS format.

  • refarea (str) – either ‘beta0’, ‘gamma0’ or ‘sigma0’.

  • tmpdir (str) – Path of custom temporary directory, useful to separate output folder and temp folder. If None, the outdir location will be used. The created subdirectory will be deleted after processing if cleanup=True.

  • test (bool) – If set to True the workflow xml file is only written and not executed. Default is False.

  • cleanup (bool) – Should all files written to the temporary directory during function execution be deleted after processing? Default is True.

  • demName (str) –

    The name of the auto-download DEM. Default is ‘SRTM 1Sec HGT’. Is ignored when externalDEMFile is not None. Supported options:

    • ACE2_5Min

    • ACE30

    • ASTER 1sec GDEM

    • CDEM

    • Copernicus 30m Global DEM

    • Copernicus 90m Global DEM

    • GETASSE30

    • SRTM 1Sec Grid

    • SRTM 1Sec HGT

    • SRTM 3Sec

  • externalDEMFile (str or None, optional) – The absolute path to an external DEM file. Default is None. Overrides demName.

  • externalDEMNoDataValue (int, float or None, optional) – The no data value of the external DEM. If not specified (default) the function will try to read it from the specified external DEM.

  • externalDEMApplyEGM (bool, optional) – Apply Earth Gravitational Model to external DEM? Default is True.

  • alignToStandardGrid (bool) – Align all processed images to a common grid?

  • standardGridOriginX (int or float) – The x origin value for grid alignment

  • standardGridOriginY (int or float) – The y origin value for grid alignment

  • groupsize (int) – The number of workers executed together in one gpt call.

  • clean_edges (bool) – erode noisy image edges? See pyroSAR.snap.auxil.erode_edges(). Does not apply to layover-shadow mask.

  • clean_edges_npixels (int) – the number of pixels to erode.

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

Workflow Parsing and Execution

gpt

Wrapper for ESA SNAP's Graph Processing Tool GPT.

execute

execute SNAP workflows via the Graph Processing Tool GPT.

parse_node

parse an XML node recipe.

parse_recipe

parse a SNAP recipe

split

split a workflow file into groups and write them to separate workflows including source and write target linking.

groupbyWorkers

split a SNAP workflow into groups containing a maximum defined number of operators.

Workflow

Class for convenient handling of SNAP XML workflows

Node

class for handling of SNAP workflow processing nodes

Par

class for handling processing node parameters

Par_BandMath

class for handling BandMaths node parameters

dem_parametrize

DEM parametrization for a full workflow or a single node.

geo_parametrize

convenience function for parametrizing geocoding nodes.

mli_parametrize

Convenience function for parametrizing a Multilook node.

orb_parametrize

convenience function for parametrizing an Apply-Orbit-File.

sub_parametrize

convenience function for parametrizing an Subset node.
class pyroSAR.snap.auxil.Node(element)[source]

Bases: object

class for handling of SNAP workflow processing nodes

Parameters

element (Element) – the node XML element

copy()[source]
Returns

a copy of the Node object

Return type

Node

property id
Returns

the node ID

Return type

str

property operator
Returns

the name of the node’s processing operator

Return type

str

property parameters
Returns

the processing parameters of the node

Return type

Par or Par_BandMath

property source
Returns

the ID(s) of the source node(s)

Return type

str or list

class pyroSAR.snap.auxil.Par(operator, element)[source]

Bases: object

class for handling processing node parameters

Parameters

  • operator (str) – the name of the SNAP Node operator

  • element (Element) – the node parameter XML element

__getitem__(item)[source]
Parameters

item –

Return type

str

dict()[source]
Returns

the parameters as a dictionary

Return type

dict

items()[source]
Returns

the parameters as (key, value) as from dict.items()

Return type

list

keys()[source]
Returns

the parameter names as from dict.keys()

Return type

list

values()[source]
Returns

the parameter values as from dict.values()

Return type

list

class pyroSAR.snap.auxil.Par_BandMath(operator, element)[source]

Bases: Par

class for handling BandMaths node parameters

Parameters

element (Element) – the node parameter XML element

add_equation()[source]

add an equation element to the node

clear_variables()[source]

remove all variables elements from the node

class pyroSAR.snap.auxil.Workflow(xmlfile)[source]

Bases: object

Class for convenient handling of SNAP XML workflows

Parameters

xmlfile (str) – the workflow XML file

property ids
Returns

the IDs of all nodes

Return type

list

index(node)[source]
Parameters

node (Node) – a node in the workflow

Returns

the index position of the node in the workflow

Return type

int

insert_node(node, before=None, after=None, resetSuccessorSource=True, void=True)[source]

insert one or multiple node(s) into the workflow including setting the source to the predecessor and setting the ID as source of the successor.

Parameters

  • node (Node or list[Node]) – the node(s) to be inserted

  • before (Node, str or list) – a Node object; the ID(s) of the node(s) before the newly inserted node; a list of node IDs is intended for nodes that require multiple sources, e.g. sliceAssembly

  • after (Node, str) – a Node object; the ID of the node after the newly inserted node

  • resetSuccessorSource (bool) – reset the source of the successor node to the ID of the newly inserted node?

  • void (bool) – if false, the function returns the node

Returns

the new node, a list of nodes, or None, depending on the node input and argument void

Return type

Node or list[Node] or None

nodes()[source]
Returns

the list of Node objects in the workflow

Return type

list[Node]

property operators
Returns

the names of the unique operators in the workflow

Return type

list

refresh_ids()[source]

Ensure unique IDs for all nodes. If two nodes with the same ID are found one is renamed to “ID (2)”. E.g. 2 x “Write” -> “Write”, “Write (2)”. This method is no longer used and is just kept in case there is need for it in the future.

set_par(key, value, exceptions=None)[source]

set a parameter for all nodes in the workflow

Parameters

  • key (str) – the parameter name

  • value (bool or int or float or str) – the parameter value

  • exceptions (list) – a list of node IDs whose parameters should not be changed

successors(id, recursive=False)[source]

find the succeeding node(s) of a node

Parameters

  • id (str) – the ID of the node

  • recursive (bool) – find successors recursively?

Returns

the ID(s) of the successors

Return type

list of str

suffix(stop=None)[source]

Get the SNAP operator suffix sequence

Parameters

stop (str) – the ID of the last workflow node

Returns

a file suffix created from the order of which the nodes will be executed

Return type

str

write(outfile)[source]

write the workflow to an XML file

Parameters

outfile (str) – the name of the file to write

pyroSAR.snap.auxil.dem_parametrize(workflow=None, node=None, demName='SRTM 1Sec HGT', externalDEMFile=None, externalDEMNoDataValue=None, externalDEMApplyEGM=False, demResamplingMethod='BILINEAR_INTERPOLATION')[source]

DEM parametrization for a full workflow or a single node. In the former case, all nodes with the DEM-relevant parameters can be modified at once, e.g. Terrain-Flattening and Terrain-Correction.

Parameters

  • workflow (Workflow or None) – a SNAP workflow object

  • node (Node or None) – a SNAP node object

  • demName (str) –

    The name of the auto-download DEM. Default is ‘SRTM 1Sec HGT’. Is ignored when externalDEMFile is not None. Supported options:

    • ACE2_5Min

    • ACE30

    • ASTER 1sec GDEM

    • CDEM

    • Copernicus 30m Global DEM

    • Copernicus 90m Global DEM

    • GETASSE30

    • SRTM 1Sec Grid

    • SRTM 1Sec HGT

    • SRTM 3Sec

  • externalDEMFile (str or None, optional) – The absolute path to an external DEM file. Default is None. Overrides demName.

  • externalDEMNoDataValue (int, float or None, optional) – The no data value of the external DEM. If not specified (default) the function will try to read it from the specified external DEM.

  • externalDEMApplyEGM (bool, optional) – Apply Earth Gravitational Model to external DEM? Default is True.

  • demResamplingMethod (str) – the DEM resampling method

pyroSAR.snap.auxil.execute(xmlfile, cleanup=True, gpt_exceptions=None, gpt_args=None)[source]

execute SNAP workflows via the Graph Processing Tool GPT. This function merely calls gpt with some additional command line arguments and raises a RuntimeError on fail. This function is used internally by function gpt().

Parameters

  • xmlfile (str) – the name of the workflow XML file

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

  • gpt_exceptions (dict) –

    a dictionary to override the configured GPT executable for certain operators; each (sub-)workflow containing this operator will be executed with the define executable;

    • e.g. {'Terrain-Flattening': '/home/user/snap/bin/gpt'}

  • gpt_args (list or None) –

    a list of additional arguments to be passed to the GPT call

    • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

Raises

RuntimeError –

pyroSAR.snap.auxil.geo_parametrize(spacing, t_srs, tc_method='Range-Doppler', sourceBands=None, demName='SRTM 1Sec HGT', externalDEMFile=None, externalDEMNoDataValue=None, externalDEMApplyEGM=True, alignToStandardGrid=False, standardGridAreaOrPoint='point', standardGridOriginX=0, standardGridOriginY=0, nodataValueAtSea=False, export_extra=None, demResamplingMethod='BILINEAR_INTERPOLATION', imgResamplingMethod='BILINEAR_INTERPOLATION', **kwargs)[source]

convenience function for parametrizing geocoding nodes.

Parameters

  • workflow (Workflow) – the SNAP workflow object

  • before (str) – the ID of the node after which the terrain correction node will be inserted

  • tc_method (str) –

    the terrain correction method. Supported options:

    • Range-Doppler (SNAP node Terrain-Correction)

    • SAR simulation cross correlation (SNAP nodes SAR-Simulation->`Cross-Correlation`->`SARSim-Terrain-Correction`)

  • sourceBands (list[str] or None) – the image band names to geocode; default None: geocode all incoming bands.

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

  • t_srs (int, str or osr.SpatialReference) – A target geographic reference system in WKT, EPSG, PROJ4 or OPENGIS format. See function spatialist.auxil.crsConvert() for details.

  • demName (str) –

    The name of the auto-download DEM. Default is ‘SRTM 1Sec HGT’. Is ignored when externalDEMFile is not None. Supported options:

    • ACE2_5Min

    • ACE30

    • ASTER 1sec GDEM

    • CDEM

    • Copernicus 30m Global DEM

    • Copernicus 90m Global DEM

    • GETASSE30

    • SRTM 1Sec Grid

    • SRTM 1Sec HGT

    • SRTM 3Sec

  • externalDEMFile (str or None, optional) – The absolute path to an external DEM file. Default is None. Overrides demName.

  • externalDEMNoDataValue (int, float or None, optional) – The no data value of the external DEM. If not specified (default) the function will try to read it from the specified external DEM.

  • externalDEMApplyEGM (bool, optional) – Apply Earth Gravitational Model to external DEM? Default is True.

  • alignToStandardGrid (bool) – Align all processed images to a common grid?

  • standardGridAreaOrPoint (str) – treat alignment coordinate as pixel center (‘point’, SNAP default) or upper left (‘area’).

  • standardGridOriginX (int or float) – The x origin value for grid alignment

  • standardGridOriginY (int or float) – The y origin value for grid alignment

  • nodataValueAtSea (bool) – mask values over sea?

  • export_extra (list[str] or None) –

    a list of ancillary layers to write. Supported options:

    • DEM

    • latLon

    • incidenceAngleFromEllipsoid (Range-Doppler only)

    • layoverShadowMask

    • localIncidenceAngle

    • projectedLocalIncidenceAngle

    • selectedSourceBand

  • demResamplingMethod (str) – the DEM resampling method

  • imgResamplingMethod (str) – the image resampling method

  • kwargs –

    further keyword arguments for node parametrization. Known options:

    • outputComplex

    • applyRadiometricNormalization

    • saveSigmaNought

    • saveGammaNought

    • saveBetaNought

    • incidenceAngleForSigma0

    • incidenceAngleForGamma0

    • auxFile

    • externalAuxFile

    • openShiftsFile (SAR simulation cross correlation only)

    • openResidualsFile (SAR simulation cross correlation only)

Returns

the Terrain-Correction node object or a list containing the objects for SAR-Simulation, Cross-Correlation and SARSim-Terrain-Correction.

Return type

Node or list[Node]

pyroSAR.snap.auxil.gpt(xmlfile, tmpdir, groups=None, cleanup=True, gpt_exceptions=None, gpt_args=None, removeS1BorderNoiseMethod='pyroSAR')[source]

Wrapper for ESA SNAP’s Graph Processing Tool GPT. Input is a readily formatted workflow XML file as for example created by function geocode(). Additional to calling GPT, this function will

Note

Depending on the parametrization this function might create two sub-directories in tmpdir, carrying a suffix *_bnr for S1 GRD border noise removal and *_sub for sub-workflows and their intermediate outputs. Both are deleted if cleanup=True. If tmpdir is empty afterwards, it is also deleted.

Parameters

  • xmlfile (str) – the name of the workflow XML file

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

  • groups (list[list[str]] or None) – a list of lists each containing IDs for individual nodes

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

  • gpt_exceptions (dict or None) –

    a dictionary to override the configured GPT executable for certain operators; each (sub-)workflow containing this operator will be executed with the define executable;

    • e.g. {'Terrain-Flattening': '/home/user/snap/bin/gpt'}

  • gpt_args (list or None) –

    a list of additional arguments to be passed to the gpt call

    • e.g. ['-x', '-c', '2048M'] for increased tile cache size and intermediate clearing

  • removeS1BorderNoiseMethod (str) –

    the 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

pyroSAR.snap.auxil.groupbyWorkers(xmlfile, n=2)[source]

split a SNAP workflow into groups containing a maximum defined number of operators.

Parameters

  • xmlfile (str) – the SNAP xml workflow

  • n (int) – the maximum number of worker nodes in each group; Read, Write and BandSelect are excluded.

Returns

a list of lists each containing the IDs of all nodes belonging to the groups including Read and Write nodes; this list can e.g. be passed to function split() to split the workflow into new sub-workflow files based on the newly created groups or directly to function gpt(), which will call split() internally.

Return type

list[list[str]]

pyroSAR.snap.auxil.mli_parametrize(scene, spacing=None, rlks=None, azlks=None, **kwargs)[source]

Convenience function for parametrizing a Multilook node.

Parameters

  • scene (pyroSAR.drivers.ID) – The SAR scene to be processed

  • spacing (int or float or None) – the target pixel spacing for automatic determination of looks using function 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

  • bands (list[str] or None) – an optional list of bands names

  • kwargs –

    further keyword arguments for node parametrization. Known options:

    • grSquarePixel

    • outputIntensity

    • sourceBands

Returns

either a Node object if multilooking is necessary (either rlks or azlks are greater than 1) or None.

Return type

Node or None

See also

pyroSAR.ancillary.multilook_factors

pyroSAR.snap.auxil.orb_parametrize(scene, formatName, allow_RES_OSV=True, **kwargs)[source]

convenience function for parametrizing an Apply-Orbit-File. Required Sentinel-1 orbit files are directly downloaded.

Parameters

  • scene (pyroSAR.drivers.ID) – The SAR scene to be processed

  • workflow (Workflow) – the SNAP workflow object

  • before (str) – the ID of the node after which the Apply-Orbit-File node will be inserted

  • formatName (str) – the scene’s data format

  • allow_RES_OSV (bool) – (only applies to Sentinel-1) Also allow the less accurate RES orbit files to be used?

  • kwargs –

    further keyword arguments for node parametrization. Known options:

    • continueOnFail

    • polyDegree

Returns

the Apply-Orbit-File node object

Return type

Node

pyroSAR.snap.auxil.parse_node(name, use_existing=True)[source]

parse an XML node recipe. The XML representation and parameter default values are read from the docstring of an individual node by calling gpt <node> -h. The result is then written to an XML text file under $HOME/.pyroSAR/snap/nodes which is subsequently read for parsing instead of again calling gpt.

Parameters

  • name (str) – the name of the processing node, e.g. Terrain-Correction

  • use_existing (bool) – use an existing XML text file or force re-parsing the gpt docstring and overwriting the XML file?

Returns

the parsed node

Return type

Node

Examples

>>> tnr = parse_node('ThermalNoiseRemoval')
>>> print(tnr.parameters)
{'selectedPolarisations': None, 'removeThermalNoise': 'true', 'reIntroduceThermalNoise': 'false'}
pyroSAR.snap.auxil.parse_recipe(name)[source]

parse a SNAP recipe

Parameters

name (str) –

the name of the recipe; current options:

  • blank: a workflow without any nodes

  • geocode: a basic workflow containing Read, Apply-Orbit-File, Calibration, Terrain-Flattening and Write nodes

Returns

the parsed recipe

Return type

Workflow

Examples

>>> from pyroSAR.snap.auxil import parse_recipe
>>> workflow = parse_recipe('base')
pyroSAR.snap.auxil.split(xmlfile, groups, outdir=None)[source]

split a workflow file into groups and write them to separate workflows including source and write target linking. The new workflows are written to a sub-directory temp of the target directory defined in the input’s Write node. Each new workflow is parameterized with a Read and Write node if they don’t already exist. Temporary outputs are written to BEAM-DIMAP files named after the workflow suffix sequence.

Parameters

  • xmlfile (str) – the workflow to be split

  • groups (list) – a list of lists each containing IDs for individual nodes

  • outdir (str or None) – the directory into which to write the XML workflows and the intermediate files created by them. If None, the name will be created from the file name of the node with ID ‘Write’, which is treated as a directory, and a subdirectory ‘tmp’.

Returns

the names of the newly written temporary workflows

Return type

list of str

Raises

RuntimeError –

pyroSAR.snap.auxil.sub_parametrize(scene, geometry=None, offset=None, buffer=0.01, copyMetadata=True, **kwargs)[source]

convenience function for parametrizing an Subset node.

Parameters

  • scene (pyroSAR.drivers.ID) – The SAR scene to be processed

  • geometry (dict or spatialist.vector.Vector or str or None) –

    A vector geometry for geographic subsetting (node parameter geoRegion):

    • Vector: a vector object in arbitrary CRS

    • str: a name of a file that can be read with Vector in arbitrary CRS

    • dict: a dictionary with keys xmin, xmax, ymin, ymax in LatLon coordinates

  • offset (tuple or None) – a tuple with pixel coordinates as (left, right, top, bottom)

  • buffer (int or float) – an additional buffer in degrees to add around the geometry

  • copyMetadata (bool) – copy the metadata of the source product?

  • kwargs –

    further keyword arguments for node parametrization. Known options:

    • fullSwath

    • referenceBand

    • sourceBands

    • subSamplingX

    • subSamplingY

    • tiePointGrids

Returns

the Subset node object

Return type

Node

General Utilities

erode_edges

Erode noisy edge pixels in SNAP-processed images.

writer

SNAP product writing utility
pyroSAR.snap.auxil.erode_edges(src, only_boundary=False, connectedness=4, pixels=1)[source]

Erode noisy edge pixels in SNAP-processed images. It was discovered that images contain border pixel artifacts after Terrain-Correction. Likely this is coming from treating the value 0 as regular value instead of no data during resampling. This function erodes these edge pixels using scipy.ndimage.binary_erosion(). scipy is not a base dependency of pyroSAR and has to be installed separately.

../_images/snap_erode_edges.png

VV gamma0 RTC backscatter image visualizing the noisy border (left) and the cleaned result (right). The area covers approx. 2.3 x 2.3 km². Pixel spacing is 20 m. connectedness 4, 1 pixel.

Parameters

  • src (str) – a processed SAR image in BEAM-DIMAP format (.dim), a single .img file (ENVI format) or a directory with .img files. 0 is assumed as no data value.

  • only_boundary (bool) – only erode edges at the image boundary (or also at data gaps caused by e.g. masking during Terrain-Flattening)?

  • connectedness (int) – the number of pixel neighbors considered for the erosion. Either 4 or 8, translating to a scipy.ndimage.generate_binary_structure() connectivity of 1 or 2, respectively.

  • pixels (int) – the number of pixels to erode from the edges. Directly translates to iterations of scipy.ndimage.iterate_structure().

pyroSAR.snap.auxil.writer(xmlfile, outdir, basename_extensions=None, clean_edges=False, clean_edges_npixels=1)[source]

SNAP product writing utility

Parameters

  • xmlfile (str) – the name of the workflow XML file.

  • outdir (str) – the directory into which to write the final files.

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

  • clean_edges (bool) – erode noisy image edges? See pyroSAR.snap.auxil.erode_edges(). Does not apply to layover-shadow mask.

  • clean_edges_npixels (int) – the number of pixels to erode.