Skip to content

API

Main Implementation

Interferometric Analysis: 2D Coherence computation

Attributes

Classes

Functions:

interferometric_analysis

Python
interferometric_analysis(product: QualityInputProduct, second_product: QualityInputProduct | None = None, config: InterferometricConfig | None = None) -> list[InterferometricCoherenceOutput]

Interferometric analysis of input product based on selected options in configuration. Input product can be an interferogram or a coherence map, it can be merged or separated into bursts.

If a second product is provided, the two input products must be co-registered in order to properly compute coherence.

If the input product contains interferogram data, the coherence map must be computed and therefore the "enable_coherence_computation" flag in configuration should be set to True.

If the input product contains coherence data, "enable_coherence_computation" flag in configuration should be left to its default value of False, to compute just coherence histograms.

Parameters:

Name Type Description Default
product QualityInputProduct

object satisfying the QualityInputProduct protocol

 required
second_product QualityInputProduct | None

object satisfying the QualityInputProduct protocol, by default None

 None
config InterferometricConfig | None

InterferometricConfig configuration dataclass, by default None

 None

Returns:

Type Description
list[InterferometricCoherenceOutput]

an InterferometricCoherenceOutput dataclass for each channel

Interferometric Coherence Analysis support functionalities

Classes

Functions:

coherence_histograms_to_netcdf

Python
coherence_histograms_to_netcdf(data: list[InterferometricCoherenceOutput], output_dir: str | Path) -> Path

Saving Coherence 2D histograms to NetCDF4 file.

Parameters:

Name Type Description Default
data list[InterferometricCoherenceOutput]

list of InterferometricCoherenceOutput dataclass

 required
output_dir str | Path
required

Returns:

Type Description
Path

path to the output netCDF file

coherence_2d_histogram_computation_core

Python
coherence_2d_histogram_computation_core(coherence: NDArray[floating], config: InterferometricConfig) -> InterferometricCoherence2DHistograms

Computing 2D coherence histograms along range and azimuth directions

These discrete histograms are computed by splitting the input coherence array along a direction (azimuth or range) in several blocks and then computing the histogram of coherence for that block with a fixed number of coherence bins in a fixed range (so that all sub-blocks will match the same coherence intervals).

Parameters:

Name Type Description Default
coherence NDArray[floating]

coherence map array

 required
config InterferometricConfig

InterferometricConfig configuration dataclass

 required

Returns:

Type Description
InterferometricCoherence2DHistograms

2D histogram interferometric coherence data

coherence_computation_interferogram_core

Python
coherence_computation_interferogram_core(data: ndarray, kernel_size: int | tuple[int, int] = 15) -> npt.NDArray[np.floating]

Core algorithm to compute coherence by 2D convolution of input interferogram data with a boxcar filter.

Coherence is defined as the ratio between the interferogram convolution with a boxcar filter of the complex data (with phase information) and the same convolution performed on the absolute of the input data.

\[ \hat\gamma = \frac{\sum_{i=1}^{N} u_i}{\sum_{i=1}^{N} |u_i|} \]

Parameters:

Name Type Description Default
data ndarray

interferogram data, with shape (lines, samples)

 required
kernel_size int | tuple[int, int]

size of the boxcar kernel, if an integer is provided, kernel will be a square with a side of that size, while if the input is a tuple, that is the shape of the final kernel, by default 15

 15

Returns:

Type Description
NDArray[floating]

coherence array

coherence_computation_co_registered_core

Python
coherence_computation_co_registered_core(data_1: ndarray, data_2: ndarray, kernel_size: int | tuple[int, int] = 15) -> npt.NDArray[np.floating]

Core algorithm to compute coherence by 2D convolution of input co-registered products with a boxcar filter.

Coherence is defined as the ratio between the interferogram convolution with a boxcar filter of the complex data (with phase information) and the square root of the product of the two input data squared and convoluted.

\[ \hat\gamma = \frac{\sum_{i=1}^{N} u_i v_i^*}{\sqrt{\sum_{i=1}^{N} |u_i|^2 \sum_{i=1}^{N} |v_i|^2}} \]

where \(\hat\gamma\) is the coherence, \(u\) is the first product data and \(v\) is the second co-registered data.

Reference: https://www.esa.int/esapub/tm/tm19/TM-19_ptC.pdf

Parameters:

Name Type Description Default
data_1 ndarray

first co-registered product data

 required
data_2 ndarray

second co-registered product data

 required
kernel_size int | tuple[int, int]

size of the boxcar kernel, if an integer is provided, kernel will be a square with a side of that size, while if the input is a tuple, that is the shape of the final kernel, by default 15

 15

Returns:

Type Description
NDArray[floating]

coherence array

boxcar_kernel_setup

Python
boxcar_kernel_setup(kernel_size: int | tuple[int, int]) -> npt.NDArray[np.floating]

Creating the normalized boxcar kernel from its size.

Parameters:

Name Type Description Default
kernel_size int | tuple[int, int]

kernel size

 required

Returns:

Type Description
NDArray[floating]

normalized boxcar kernel of the given size

Functions to generate plots for Interferometric Coherence Analysis

Attributes

Classes

Functions:

generate_coherence_graphs

Python
generate_coherence_graphs(data: InterferometricCoherenceOutput, output_dir: str | Path, mode: str | CoherenceGraphMode = CoherenceGraphMode.MAGNITUDE, config: InterferometricConfig | None = None) -> None

Computing coherence graphs from Quality InterferometricCoherenceOutput coherence computation results.

Parameters:

Name Type Description Default
data InterferometricCoherenceOutput

InterferometricCoherenceOutput dataclass with results from coherence computation

 required
output_dir str | Path

output directory where to save the graph

 required
mode str | CoherenceGraphMode

complex coherence quantity plot, by default CoherenceGraphMode.MAGNITUDE

 MAGNITUDE
config InterferometricConfig | None

interferometric configuration, by default None

 None

coherence_graph_core

Python
coherence_graph_core(coherence: NDArray[floating], histograms: InterferometricCoherence2DHistograms, output_dir: Path, tag: str = '', mode: CoherenceGraphMode = CoherenceGraphMode.MAGNITUDE) -> None

Generating interferogram coherence graph.

Parameters:

Name Type Description Default
coherence InterferometricCoherenceOutput

coherence dataclass

 required
output_dir Path

output directory where to save the graph

 required
tag str

string tag to be added to the plot title and filename, by default ""

 ''
mode CoherenceGraphMode

complex coherence quantity plot, by default CoherenceGraphMode.MAGNITUDE

 MAGNITUDE

Utilities

Definition of Interferometric Coherence Analysis configuration

Classes

InterferometricConfig dataclass

Interferometric analysis configuration

Attributes

enable_coherence_computation class-attribute instance-attribute
Python
enable_coherence_computation: bool = False
coherence_kernel class-attribute instance-attribute
Python
coherence_kernel: int | tuple[int, int] = 15
azimuth_blocks_number class-attribute instance-attribute
Python
azimuth_blocks_number: int | None = None
range_blocks_number class-attribute instance-attribute
Python
range_blocks_number: int | None = None
coherence_bins_number class-attribute instance-attribute
Python
coherence_bins_number: int = 80

Methods:

__init__
Python
__init__(enable_coherence_computation: bool = False, coherence_kernel: int | tuple[int, int] = 15, azimuth_blocks_number: int | None = None, range_blocks_number: int | None = None, coherence_bins_number: int = 80) -> None
from_dict classmethod
Python
from_dict(arg: dict) -> InterferometricConfig

Creating a InterferometricConfig object by conversion from a dictionary.

Args: arg (dict): dictionary with keys equal to the InterferometricConfig ones

Returns: InterferometricConfig: InterferometricConfig object

Definition of Interferometric Coherence Analysis specific dataclasses

Classes

CoherenceGraphMode

Bases: Enum

Coherence graphs complex coherence plot method

Attributes

MAGNITUDE class-attribute instance-attribute
Python
MAGNITUDE = 'magnitude'
PHASE class-attribute instance-attribute
Python
PHASE = 'phase'

InterferometricCoherenceOutput dataclass

Interferometric Coherence computation output

Attributes

channel_name instance-attribute
Python
channel_name: str
swath instance-attribute
Python
swath: str
burst instance-attribute
Python
burst: int
polarization instance-attribute
Python
polarization: SARPolarization
coherence instance-attribute
Python
coherence: NDArray[floating]
coherence_histograms instance-attribute
Python
coherence_histograms: InterferometricCoherence2DHistograms

Methods:

__init__
Python
__init__(channel_name: str, swath: str, burst: int, polarization: SARPolarization, coherence: NDArray[floating], coherence_histograms: InterferometricCoherence2DHistograms) -> None

InterferometricCoherence2DHistograms dataclass

Interferometric Coherence 2D histograms output

Attributes

coherence_bin_edges instance-attribute
Python
coherence_bin_edges: NDArray[floating]
azimuth_histogram instance-attribute
Python
azimuth_histogram: NDArray[floating]
range_histogram instance-attribute
Python
range_histogram: NDArray[floating]

Methods:

__init__
Python
__init__(coherence_bin_edges: NDArray[floating], azimuth_histogram: NDArray[floating], range_histogram: NDArray[floating]) -> None