s1etad.product module

S1-ETAD data model core classes.

class s1etad.product.ECorrectionType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration for correction types.

BISTATIC = 'bistatic'

DOPPLER = 'doppler'

FMRATE = 'fmrate'

GEODETIC = 'geodetic'

IONOSPHERIC = 'ionospheric'

SUM = 'sum'

TROPOSPHERIC = 'tropospheric'

class s1etad.product.Sentinel1Etad(product)

Bases: object

Sentinel-1 ETAD product.

Class to decode and access the elements of the Sentinel ETAD product which specification is governed by ETAD-DLR-PS-0014.

The index operator [] (implemented with the __getitem__ method) returns a Sentinel1EtadSwath instance.

Parameters:

product (str or pathlib.Path) – path of the S1-ETAD product (it is a directory)

product

path of the S1-ETAD product (it is a directory)

Type:

pathlib.Path

burst_catalogue

dataframe containing main information of all bursts present in the product

Type:

pandas.DataFrame

ds

(provisional) the NetCDF.Dataset in which data are stored

Type:

netCDF.Dataset

get_footprint(selection=None, merge=False)

Return the footprints of all the bursts as MultiPolygon.

It calls in the back the get_footprint of the Sentinel1EtadBurst class.

Parameters:

• selection (list(str) or pd.Dataframe, optional) – the list of selected swath IDs or the result of a Sentinel1Etad.query_burst query. If the selection is None (default) the iteration is performed on all the swaths of the product.

• merge (bool) – if set to True return a single polygon that is the union of the footprints of all bursts

get_statistics(correction, meter=False)

Return the global statistic value of the specified correction.

The returned value is the pre-computed one that is stored in the XML annotation file of the product.

Parameters:

• correction (str or ECorrectionType) – the corrections for which the statistic value is requested

• meter (bool) – if set to True then the returned value is expressed in meters, otherwise it is expressed in seconds (default: False)

Returns:

a dictionary containing Statistics (min, mean and max) for all available components of the specified correction:

x:

a Statistics instance relative to the range component of the specified correction

y:

a Statistics instance relative to the azimuth component of the specified correction

unit:

the units of the returned statistics (“m” or “s”)

Return type:

dict

intersects(geometry: shapely.geometry.base.BaseGeometry)

Return the list of burst indexes intersecting the input geometry.

Computes the intersection of the footprint of the swath (all bursts) with the input geometry.

Parameters:

geometry (shapely.geometry.[Point, Polygon, MultiPolygon, line]) –

Returns:

list of all the burst intersecting with the input shape geometry

Return type:

list

iter_bursts(selection=None)

Iterate over burst according to the specified selection.

Parameters:

selection (list(int) or pd.Dataframe, optional) – the list of selected burst indexes or the result of a Sentinel1Etad.query_burst query. If the selection is None (default) the iteration is performed on all the bursts of the product.

iter_swaths(selection=None)

Iterate over swaths according to the specified selection.

Parameters:

selection (list(str) or pd.Dataframe, optional) – the list of selected swath IDs or the result of a Sentinel1Etad.query_burst query. If the selection is None (default) the iteration is performed on all the swaths of the product.

merge_correction(name: ECorrectionType | str = ECorrectionType.SUM, selection=None, set_auto_mask=True, meter=False, direction=None)

Merge multiple swaths of the specified correction variable.

Data of the selected swaths (typically overlapped) are merged together to form a single data matrix with a consistent (range and azimuth) time axis.

Note

The current implementation uses a very simple algorithm that iterates over selected swaths and bursts and stitches correction data together.

In overlapping regions, new data simply overwrite the old ones. This is an easy algorithm and perfectly correct for atmospheric and geodetic correction.

It is, instead, sub-optimal for system corrections (bi-static, Doppler, FM Rate) which have different values in overlapping regions. In this case results are not correct.

Parameters:

• name (str or CorrectionType) – the name of the desired correction

• selection (list or pandas.DataFrame) – list of selected bursts (by default all bursts are selected)

• set_auto_mask (bool) – requested for netCDF4 to avoid retrieving a masked array

• meter (bool) – transform the result in meters

• direction (str or None) – if set to “x” (for range) or “y” (for “azimuth”) only extracts the specified correction component. By default (None) all available components are returned.

Returns:

a dictionary containing merged data and sampling information:

<burst_var_name>:

merged data for the selected burst_var

first_azimuth_time:

the relative azimuth first time

first_slant_range_time:

the relative (slant) range first time

sampling:

a dictionary containing the sampling along the ‘x’ and ‘y’ directions and the ‘unit’

units:

of the correction (seconds or meters)

lats:

the matrix of latitude values (in degrees) for each point

lons:

the matrix of longitude values (in degrees) for each point

height:

the matrix of height values (in meters) for each point

Return type:

dict

processing_setting()

Return the corrections performed.

Read the xml file to identify the corrections performed. If a correction is not performed the matrix is filled with zeros.

query_burst(first_time=None, product_name=None, last_time=None, swath=None, geometry=None)

Query the burst catalogue to retrieve the burst matching by time.

Parameters:

• first_time (datetime) – is set to None then set to the first time

• last_time (datetime) – if set to None the last_time = first_time

• product_name (str) – Name of a real S1 product e.g. S1B_IW_SLC__1SDV_20190805T162509_20190805T162…SAFE

• swath (str or list) – list of swathID e.g. ‘IW1’ or [‘IW1’] or [‘IW1’, ‘IW2’]

• geometry (shapely.geometry.[Point, Polygon, ...]) – A shapely geometry for which intersection will be searched

Returns:

Filtered panda dataframe

Return type:

pandas.DataFrame

s1_product_list()

Return the list of S-1 products used to compose the ETAD one.

property grid_sampling

Return the grid spacing in s.

property grid_spacing

Return the grid spacing in meters.

property max_azimuth_time

Return the maximum azimuth time of all bursts in the product.

property max_range_time

Return the maximum range time of all bursts in the product.

property min_azimuth_time

Return the minimum azimuth time of all bursts in the product.

property min_range_time

Return the minimum range time of all bursts in the product.

property number_of_swath

Return the number of swaths in the product.

property swath_list

Return the list of swath identifiers (str) in the product.

property vg

Mean ground velocity [m/s].

class s1etad.product.Sentinel1EtadBurst(nc_group)

Bases: object

Object representing a burst in the S1-ETAD product.

This objects are returned by methods of the Sentinel1EtadSwath class. It is not expected that the user instantiates this objects directly.

geodetic_to_radar(lat, lon, h=0, deg=True)

Convert geodetic coordinates into RADAR coordinates.

Compute the RADAR coordinates (tau, t), i.e. fast time (range time) and slow time (azimuth time expressed in seconds form the reference Sentinel1Etad.min_azimuth_time) corresponding to geodetic coordinates (lat, lon, h):

(lat, lon, h) -> (tau, t)

If deg is True it is assumed that input lat and lon are expressed in degrees, otherwise it is assumed that angles are expressed in radians.

The implementation is approximated and exploits pre-computed grids of latitude, longitude and height values.

The method is not as accurate as solving the range-Doppler equations.

See also

s1etad.geometry.GridGeocoding.

get_burst_grid()

Return the t, tau grid of the burst.

get_correction(name: ECorrectionType | str = ECorrectionType.SUM, set_auto_mask=False, transpose=False, meter=False, direction=None)

Retrieve the correction for the specified correction “name”.

Puts the results in a dict.

Parameters:

• name (ECorrectionType or str) – the desired correction

• set_auto_mask (bool) – requested for netCDF4 to avoid retrieving a masked array

• transpose (bool) – requested to retrieve the correction in array following the numpy convention for dimensions (default: False)

• meter (bool) – transform the result in meters

• direction (str or None) – if set to “x” (for range) or “y” (for “azimuth”) only extracts the specified correction component. By default (None) all available components are returned.

Returns:

a dictionary containing the following items for the requested correction:

x:

correction in range (if applicable)

y:

correction in azimuth (if applicable)

unit:

’m’ or ‘s’

name:

name of the correction

Return type:

dict

get_footprint()

Return the footprint of the bursts as shapely.Polygon.

It gets the lat/lon/height grid and extract the 4 corners.

get_lat_lon_height(transpose=False)

Return the latitude, longitude and height for each point.

Data are returned as (3) matrices (lines x samples). Latitude and longitude are expressed in degrees, height is expressed in meters.

get_polarimetric_channel_offset(channel: str) → dict

Polarimetric channel delay.

Return the electronic delay of the specified polarimetric channel w.r.t. the reference one (see Sentinel1EtadBurst.reference_polarization).

channelstr

the string ID of the requested polarimetric channel: * ‘VV’ or ‘VH’ for DV products * ‘HH’ or ‘HV’ for DH products

get_timing_calibration_constants() → dict

Return the calibration constant for timing.

image_to_radar(line, sample)

Convert image coordinates into RADAR coordinates.

Compute the RADAR coordinates (tau, t), i.e. fast time (range time) and slow time (azimuth time expressed in seconds form the reference Sentinel1Etad.min_azimuth_time) corresponding to image coordinates (line, sample):

(line, sample) -> (t, tau)

intersects(geometry: shapely.geometry.base.BaseGeometry)

Intersect the footprint of the burst with the provided shape.

Parameters:

geometry (shapely.geometry.[Point, Polygon, MultiPolygon, line]) –

Returns:

True if intersects, False otherwise

Return type:

bool

radar_to_geodetic(tau, t, deg=True)

Convert RADAR coordinates into geodetic coordinates.

Compute the geodetic coordinates (lat, lon, h) corresponding to RADAR coordinates (tau, t), i.e. fast time (range time) and slow time (azimuth time expressed in seconds form the reference Sentinel1Etad.min_azimuth_time):

(tau, t) -> (lat, lon, h)

If deg is True the output lat and lon are expressed in degrees, otherwise in radians.

The implementation is approximated and exploits pre-computed grids of latitude, longitude and height values.

The method is not as accurate as solving the range-Doppler equations.

See also

s1etad.geometry.GridGeocoding.

radar_to_image(t, tau)

Convert RADAR coordinates into image coordinates.

Compute the image coordinates (line, sample) corresponding to RADAR coordinates (tau, t), i.e. fast time (range time) and slow time (azimuth time expressed in seconds form the reference Sentinel1Etad.min_azimuth_time):

(tau, t) -> (line, sample)

property burst_id: str

Return the burst identifier.

property burst_index

Return the index (int) of the burst.

property lines

Return the number of lines in the burst.

property product_id: str

Return the S1 product name (str) to which the burst belongs.

property product_index

Return the index of the S1 product to which the burst belongs.

property reference_polarization: str

Reverence polarization (string).

property samples

Return the number of samples in the burst.

property sampling

Return the sampling in seconds used for all bursts of the swath.

A dictionary containing the following keys:

• “x”: range spacing,

• “y”: azimuth spacing,

• “units”: the measurement units used for “x’ and “y”

property sampling_start

Relative sampling start times.

Value in seconds relative to the beginning of the product.

property swath_id: str

Return the swath identifier (str) to which the burst belongs.

property swath_index

Return the index (int) of the swath to which the burst belongs.

property vg: float

Average zero-Doppler ground velocity [m/s].

class s1etad.product.Sentinel1EtadSwath(nc_group)

Bases: object

Object representing a swath in the S1-ETAD product.

This objects are returned by methods of the Sentine1Etad class. It is not expected that the user instantiates this objects directly.

get_footprint(selection=None, merge=False)

Return the footprints of all the bursts as MultiPolygon.

It calls in the back the get_footprint of the Sentinel1EtadBurst class.

Parameters:

• selection (list(int) or pd.Dataframe, optional) – the list of selected bursts or result of a Sentinel1Etad.query_burst query. If the selection is None (default) the iteration is performed on all the burst of the swath.

• merge (bool) – if set to True return a single polygon that is the union of the footprints of all bursts

intersects(geometry: shapely.geometry.base.BaseGeometry)

Return the list of burst indexes intersecting the input geometry.

Computes the intersection of the footprint of the swath (all bursts) with the input Geometry

Parameters:

geometry (shapely.geometry.[Point, Polygon, MultiPolygon, line]) –

Returns:

list of the indexes of all bursts intersecting with the input geometry

Return type:

list

iter_bursts(selection=None)

Iterate over bursts according to the specified selection.

Parameters:

selection (list(int) or pd.Dataframe, optional) – the list of selected bursts or result of a Sentinel1Etad.query_burst query. If the selection is None (default) the iteration is performed on all the burst of the swath.

merge_correction(name: ECorrectionType | str = ECorrectionType.SUM, selection=None, set_auto_mask=True, meter=False, direction=None)

Merge multiple bursts of the specified correction variable.

Data of the selected bursts (typically overlapped) are merged together to form a single data matrix with a consistent (azimuth) time axis.

Note

The current implementation uses a very simple algorithm that iterates over selected bursts and stitches correction data together.

In overlapping regions, new data simply overwrite the old ones. This is an easy algorithm and perfectly correct for atmospheric and geodetic correction.

It is, instead, sub-optimal for system corrections (bi-static, Doppler, FM Rate) which have different values in overlapping regions. In this case results are not correct.

Parameters:

• name (str or CorrectionType) – the name of the desired correction

• selection (list or pandas.DataFrame) – list of selected bursts (by default all bursts are selected)

• set_auto_mask (bool) – requested for netCDF4 to avoid retrieving a masked array

• meter (bool) – transform the result in meters

• direction (str or None) – if set to “x” (for range) or “y” (for “azimuth”) only extracts the specified correction component. By default (None) all available components are returned.

Returns:

a dictionary containing merged data and sampling information:

<burst_var_name>:

merged data for the selected burst_var

first_azimuth_time:

the relative azimuth first time

first_slant_range_time:

the relative (slant) range first time

sampling:

a dictionary containing the sampling along the ‘x’ and ‘y’ directions and the ‘unit’

units:

of the correction (seconds or meters)

lats:

the matrix of latitude values (in degrees) for each point

lons:

the matrix of longitude values (in degrees) for each point

height:

the matrix of height values (in meters) for each point

Return type:

dict

property burst_list

Return the list of burst identifiers of all bursts in the swath.

property number_of_burst

Return the number of bursts in the swath.

property sampling

Return the sampling in seconds used for all bursts of the swath.

A dictionary containing the following keys:

• “x”: range spacing,

• “y”: azimuth spacing,

• “units”: the measurement units used for “x’ and “y”

property sampling_start

Return the relative sampling start times.

property swath_id

Return the swath identifier (str).

property swath_index

Return the swath index (int).