Skip to content

Common functionalities

Module containing all the signal processing related functions

Classes

Functions:

convert_to_db

Python
convert_to_db(data: ArrayLike, mode: DecibelConversion = DecibelConversion.POWER) -> ArrayLike

Converting input data to decibel.

Parameters:

Name Type Description Default
data ArrayLike

input array or float

 required
mode DecibelConversion

if input data is already in power (abs(data)^2) use DecibelConversion.POWER (factor 10), else use DecibelConversion.AMPLITUDE if input data is just (abs(data)), by default DecibelConversion.POWER

 POWER

Returns:

Type Description
ArrayLike

array of floats or float in decibel

shift_spectrum

Python
shift_spectrum(data: ndarray, shift: ArrayLike, axis: int = 0) -> np.ndarray

Shift the spectrum of time domain signal along the selected axis by applying a time domain modulation.

The shift can be a single value or an array of values with the size of the other axis. This allows to apply a shift that varies along the other axis. For example, in case of an (azimuth, range) signal a range variant azimuth spectral shift can be specified.

shift is normalized: to apply a shift 'df' in Hertz you need to set 'shift' to 'df * dt'.

Parameters:

Name Type Description Default
data ndarray

signal of shape (L, S)

 required
shift ArrayLike

either a constant or an array of shape (L,) or (S,) depending on the specified axis.

 required
axis int

axis along which the spectral shift is applied, by default 0

 0

Returns:

Type Description
ndarray

the modulated signal of shape (L, S)

modulate_data

Python
modulate_data(data: ndarray, mod_freq: ArrayLike) -> np.ndarray

Time domain data modulation to shift a signal in the frequency domain along the selected axis. Signal spectrum is shifted by mod_freq value.

The modulation frequency can be a single value or an array of values with the size of the other axis. This allows to apply frequency shift that varies along the other axis. For example, if the signal is of shape (azimuth, range) you can specify a range variant azimuth shift.

mod_freq is normalized, i.e. to apply a shift df in Hertz you need to set mod_freq = df * dt.

Parameters:

Name Type Description Default
data ndarray

signal of shape (L, S)

 required
mod_freq ArrayLike

either a constant or an array of shape (L,) or (S,) depending on the axis.

 required

Returns:

Type Description
ndarray

the modulated signal of shape (L, S)

linear_best_fit_by_fft

Python
linear_best_fit_by_fft(input_array: ndarray, weights: ndarray, substitute_value: float, nyquist_position: float, interp_factor: int = 16) -> np.ndarray

Computing the line best fit of the input array using fft. This function can be used to extract a circularity-safe line of best fit from an input noisy array. It's a way to smooth the input noisy array and extract only the linear trend by means of an fft. Ensuring circularity means that the last and first value of the line of best fit are equal, to take into account the periodicity of the spectrum (first and last column/row must be processed the same way).

Parameters:

Name Type Description Default
input_array ndarray

input array from which to extract the line of best fit

 required
weights ndarray

weights to be applied to the input array before performing the fft

 required
substitute_value float

if the input array is constant, this is the substitute value used to provide a constant line output

 required
nyquist_position float

half of the sampling frequency

 required
interp_factor int

interpolation factor to be applied in the frequency domain, by default 16

 16

Returns:

Type Description
ndarray

linear fit of the input array

estimate_modulation_frequency

Python
estimate_modulation_frequency(data: ndarray, method: GetFrequencyMethod = GetFrequencyMethod.AUTOCORRELATION, axis: int = 1) -> tuple[float, np.ndarray]

Estimate modulation frequency of the data spectrum using the selected method.

This function estimates the modulation frequency of the frequency spectrum of the input time domain data. This is necessary to down-convert the input signal to baseband, that is to recenter the spectrum in the frequency domain.

This function returns both the constant modulation frequency, determined as a sort of mean from the whole spectrum, and an array with a frequency value for each column of the input array (not averaged). The first output is enough to demodulate simple systems (low resolution sensor) with rectangular spectrum (not so warped) while the second one can be used in complex scenarios where the spectrum is remarkably warped to recenter the spectrum column-wise.

Parameters:

Name Type Description Default
data ndarray

input array in the time domain

 required
method GetFrequencyMethod

method of computation of the local frequency, by default GetFrequencyMethod.AUTOCORRELATION

 AUTOCORRELATION

Returns:

Type Description
float

local frequency
ndarray

local frequency array

Raises:

Type Description
NotImplementedError

FFT method not supported yet
NotImplementedError

POWER_BALANCE method not supported yet

estimate_modulation_frequency2d

Python
estimate_modulation_frequency2d(data: ndarray, method: GetFrequencyMethod = GetFrequencyMethod.AUTOCORRELATION) -> tuple[float, np.ndarray, float, np.ndarray]

Computing the estimate of the modulation frequency along both axes of the input 2D array. This functions applied the estimate_modulation_frequency algorithm along both range and azimuth and returns the modulation frequencies and their arrays (linear best fit).

Main algorithm to be applied along each direction: - computing fft along an axis of the 2D array - this allows to estimate the demodulation frequency in the other direction - linear fit of the demodulation frequency array

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
method GetFrequencyMethod

method of get_local_frequency application, by default GetFrequencyMethod.AUTOCORRELATION

 AUTOCORRELATION

Returns:

Type Description
float

local frequency range
ndarray

local frequency range array (linear fit)
float

local frequency azimuth
ndarray

local frequency azimuth array (linear fit)

get_frequency_axis

Python
get_frequency_axis(central_freqs: ArrayLike, sampling_freq: float, n_samples: int) -> np.ndarray

Generating a frequency axis from input parameters.

Creating a monotonically increasing frequency axis from 0 to sampling_freq/2 + central_freq, and from -sampling_freq/2 + central_freq to sampling frequency with an abrupt discontinuity. This takes into account the wrapping of frequencies, marking the position of the peak (central_frequency) with the discontinuity point.

Parameters:

Name Type Description Default
central_freqs ArrayLike

central frequencies, a.k.a. modulation frequency

 required
sampling_freq float

sampling frequency

 required
n_samples int

number of samples

 required

Returns:

Type Description
ndarray

frequency axis

parabolic_interp_by_3_closest_samples

Python
parabolic_interp_by_3_closest_samples(array: ndarray) -> tuple[float, float]

Parabolic peak interpolation using the three samples closest to the peak.

Fitting a parabola to the 3-points input array, containing the closest point before the peak, the peak itself and the closest point after the peak.

Considering a parabola written with explicit dependency from the position of its interpolated peak location in bins

\[ y(x)\overset{\Delta}{=}a(x-p)^2+b \]

at the three samples nearest the peak, considering their bins as -1 (before), 0 (peak), 1 (after) we have:

\[ \begin{aligned} & y(-1) = ap^2+2ap+a+b = \alpha \\[10pt] & y(0) = ap^2+b = \beta \\[10pt] & y(1) = ap^2-2ap+a+b = \gamma \end{aligned} \]

meaning that:

\[ \begin{aligned} & \alpha - \gamma = 4ap \\[10pt] & p = \frac{\alpha - \gamma}{4a} \\[10pt] & p = \frac{\alpha - \gamma}{2(\alpha -2\beta +\gamma)} \end{aligned} \]

Parameters:

Name Type Description Default
array ndarray

input array with 3 points, (before peak, peak and after peak)

 required
See Also

https://ccrma.stanford.edu/~jos/sasp/Quadratic_Interpolation_Spectral_Peaks.html

Returns:

Type Description
float

interpolated peak value
float

delta position between the old peak position (second value of input array) and new estimated position

interp1_modulated_data

Python
interp1_modulated_data(data: ndarray, interp_factor: int, demodulation_flag: int, demodulation_frequency: ndarray) -> np.ndarray

Interpolating input data along rows direction.

Input 2D array is interpolated (i.e. oversampled) by a factor interp_factor. If input data is already demodulated, demodulation_flag can be provided <1, otherwise data can be demodulated before interpolation (and than re-modulated back before returning the results) if demodulation_flag is set >=1 and a demodulation frequency array is provided.

Parameters:

Name Type Description Default
data ndarray

2D array

 required
interp_factor int

interpolation factor

 required
demodulation_flag int

modulation flag, if >1 modulation is applied before interpolation (and removed after), otherwise data is left as it is

 required
demodulation_frequency ndarray

modulation frequency values to be used for modulation, if needed

 required

Returns:

Type Description
ndarray

interpolated 2D array

interp2_modulated_data

Python
interp2_modulated_data(data: ndarray, interp_factor_az: int, interp_factor_rng: int, demod_flag_az: bool = False, demod_flag_rng: bool = False) -> np.ndarray

This functions applies the interp1_modulated_data on both axis of the input 2D array. It is used to interpolate both along azimuth and range. It performs also modulation before interpolating data, if needed.

Parameters:

Name Type Description Default
data ndarray

2D array

 required
interp_factor_az int

interpolation factor along azimuth direction

 required
interp_factor_rng int

interpolation factor along range direction

 required
demod_flag_az bool

if True demodulation frequency for azimuth is estimated and data are demodulate before interpolating them. At the end of the operation, if data have been demodulate, they are re-modulated, by default False

 False
demod_flag_rng bool

if True demodulation frequency for range is estimated and data are demodulate before interpolating them. At the end of the operation, if data have been demodulate, they are re-modulated, by default False

 False

Returns:

Type Description
ndarray

interpolated 2D array along both axes

evaluate_irf_resolution

Python
evaluate_irf_resolution(profile: ndarray) -> float

Finding the resolution of the main lobe in pixel.

Parameters:

Name Type Description Default
profile ndarray

profile to be analyzed

 required

Returns:

Type Description
float

resolution of the main lobe in pixel

compute_intensity_background

Python
compute_intensity_background(data: ndarray, resolutions_px: tuple[float, float], roi: tuple[float, float], margin: int = 10) -> tuple[float, list]

Compute image intensity background.

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
resolutions_px tuple[float, float]

range[0] and azimuth[1] pixel resolutions

 required
roi tuple[float, float]

roi size, range [0] and azimuth[1]

 required
margin int

margin from array borders, by default 10

 10

Returns:

Type Description
float

intensity background
list

list of range and azimuth positions

compute_integrated_peak_intensity

Python
compute_integrated_peak_intensity(data: ndarray, peak_position: ndarray, resolutions_px: tuple[float, float], interp_factor: int = 8, margin: int = 20) -> tuple[float, list]

Computing the integrated peak intensity of the input array as sum of values inside a calculated roi.

Parameters:

Name Type Description Default
data ndarray

input array

 required
peak_position ndarray

peak position inside array [row, col]

 required
resolutions_px tuple[float, float]

resolution [range, azimuth] in pixels

 required
interp_factor int

interpolation factor, by default 8

 8
margin int

roi margin from the array borders, by default 20

 20

Returns:

Type Description
float

integrated peak intensity over roi
list

list of peak roi corners

padded_hamming_windowing

Python
padded_hamming_windowing(num_points: int, alpha: float, zero_pad_side_len: int = 0, top_plateau_len: int = 0) -> np.ndarray

Padded hamming windowing. Hamming window with the possibility to add zeroes on sides and extend the peak with a plateau of ones.

Parameters:

Name Type Description Default
num_points int

number of points of un-padded hamming window

 required
alpha float

alpha hamming parameter

 required
zero_pad_side_len int

zeroes padding length on each side, by default 0

 0
top_plateau_len int

ones padding length for peak extension, by default 0

 0

Returns:

Type Description
ndarray

padded hamming window

locate_max_2d

Python
locate_max_2d(data: ndarray) -> tuple[int, int]

Function used to determine the indexes of the maximum value in a 2D array.

Parameters:

Name Type Description Default
data ndarray

input array where to find the maximum

 required

Returns:

Type Description
int

row max index
int

column max index

locate_max_2d_interp

Python
locate_max_2d_interp(data: ndarray, interp_factor: int = 8, demod_flag_az: bool = True, demod_flag_rng: bool = True) -> tuple[float, float, float]

This function shifts the input data by modulating it, compute an FFT, oversamples the data to find the peak coordinates with sub-pixel accuracy.

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
interp_factor int

interpolating factor, by default 8

 8
demod_flag_az bool

if True demodulation frequency for azimuth is estimated and data are demodulate before interpolating them. At the end of the operation, if data have been demodulate, they are re-modulated, by default True

 True
demod_flag_rng bool

if True demodulation frequency for range is estimated and data are demodulate before interpolating them. At the end of the operation, if data have been demodulate, they are re-modulated, by default True

 True

Returns:

Type Description
float

peak value
float

row peak coordinate (subpixel)
float

column peak coordinate (subpixel)

shift_array

Python
shift_array(data: ndarray, row_shift: float, col_shift: float, integer_shift_tolerance: float = 0.001) -> np.ndarray

Shift data in the time domain.

A rigid shift and a zero padding or a phase ramp in frequency, depending if the shift is approximately an integer.

Parameters:

Name Type Description Default
data ndarray

input 2D array to be shifted

 required
row_shift float

shift expressed in samples

 required
col_shift float

shift expressed in lines

 required

Returns:

Type Description
ndarray

shifted 2D array

crop_array_2d

Python
crop_array_2d(data: ndarray, crop_size: tuple, indexes: tuple[int | None, int | None] = (None, None)) -> np.ndarray

Cropping the input 2D array around specific indexes (if provided, otherwise the center of the array) with cropping length and width equal to the specified values crop_size.

Parameters:

Name Type Description Default
data ndarray

input 2D array to be cropped

 required
crop_size tuple

cropping size, one value for each axis

 required
indexes tuple

if provided, cropping around these indexes, otherwise cropping around center of array, by default (None, None)

 (None, None)

Returns:

Type Description
ndarray

cropped array

Raises:

Type Description
ValueError

Cropping size out of array boundaries

radiometric_correction

Python
radiometric_correction(data: ndarray, incidence_angle: ndarray, input_quantity: SARRadiometricQuantity, output_quantity: SARRadiometricQuantity, exp_power: float = 0.5) -> np.ndarray

Data radiometric correction based on data acquisition type and desired output type, choosing between Beta, Sigma and Gamma Nought.

Parameters:

Name Type Description Default
data ndarray

input array whose data need to be converted from a type to another, array should be in the form (samples, lines)

 required
incidence_angle ndarray

incidence angle array, same size as range axis of input data or same data size: (n_rng,) or (n_rng, n_az)

 required
input_quantity SARRadiometricQuantity

input radiometric quantity

 required
output_quantity SARRadiometricQuantity

output radiometric quantity

 required
exp_power float

exponential power correction in computing different radiometric corrections, by default 0.5

 0.5

Returns:

Type Description
ndarray

corrected data array, in the form (samples, lines)

Raises:

Type Description
ValueError

input_quantity and output_quantity not of the proper enum type
ValueError

data and incidence_angle do not have the same shape

compute_doppler_rate_theoretical

Python
compute_doppler_rate_theoretical(trajectory: Trajectory, azimuth_time: PreciseDateTime, coords: ndarray, fc_hz: float) -> np.ndarray

Compute theoretical doppler rate.

Parameters:

Name Type Description Default
trajectory Trajectory

sensor trajectory

 required
azimuth_time PreciseDateTime

azimuth time when to evaluate the doppler rate

 required
coords ndarray

ground point coordinates

 required
fc_hz float

signal carrier frequency

 required

Returns:

Type Description
ndarray

theoretical doppler rate

compute_steering_doppler_frequency

Python
compute_steering_doppler_frequency(trajectory: Trajectory, azimuth_time: PreciseDateTime, az_mid_burst_time: PreciseDateTime, doppler_rate: float, az_steering_rate_rad_s: float, fc_hz: float) -> float

Compute doppler frequency related to the antenna electrical steering.

Parameters:

Name Type Description Default
trajectory Trajectory

sensor trajectory

 required
azimuth_time PreciseDateTime

azimuth time at which compute the steering frequency

 required
az_mid_burst_time PreciseDateTime

azimuth mid burst time

 required
doppler_rate float

sensor doppler rate

 required
az_steering_rate_rad_s float

azimuth steering rate in rad/s

 required
fc_hz float

signal carrier frequency

 required

Returns:

Type Description
float

steering doppler frequency

compute_point_target_ambiguity_ratio_db

Python
compute_point_target_ambiguity_ratio_db(point_target_roi: ndarray, right_ambiguity_roi: ndarray, left_ambiguity_roi: ndarray, interp_factor: int) -> float

Computing the Point Target Ambiguity Ratio (PTAR).

This parameter is computed using the following formula:

\[ PTAR = 20\log_{10}\left(\frac{{|I_{amb_{left}}| + |I_{amb_{right}}|}}{2|I_{pt}|}\right) \]

Parameters:

Name Type Description Default
point_target_roi ndarray

raster data portion centered on the point target location, with shape (samples, lines)

 required
right_ambiguity_roi ndarray

raster data portion centered on the point target right ambiguity, with shape (samples, lines)

 required
left_ambiguity_roi ndarray

raster data portion centered on the point target left ambiguity, with shape (samples, lines)

 required
interp_factor int

interpolation factor

 required

Returns:

Type Description
float

Point Target Ambiguity Ratio

compute_distributed_target_ambiguity_ratio_db

Python
compute_distributed_target_ambiguity_ratio_db(distributed_target_roi: ndarray, right_ambiguity_roi: ndarray, left_ambiguity_roi: ndarray) -> float

Computing the Distributed Target Ambiguity Ratio (DTAR).

This parameter is computed using the following formula:

\[ DTAR = \frac{E(\Sigma |amb_{left}|^2) + E(\Sigma |amb_{right}|^2)}{2*E(\Sigma |target|^2)} \]

Parameters:

Name Type Description Default
distributed_target_roi ndarray

raster data portion centered on the point target location, with shape (samples, lines)

 required
right_ambiguity_roi ndarray

raster data portion centered on the point target right ambiguity, with shape (samples, lines)

 required
left_ambiguity_roi ndarray

raster data portion centered on the point target left ambiguity, with shape (samples, lines)

 required

Returns:

Type Description
float

Distributed Target Ambiguity Ratio

compute_equivalent_number_of_looks

Python
compute_equivalent_number_of_looks(intensity_data: ndarray) -> float

Computing Equivalent Number of Looks (ENL) from input roi data.

\[ ENL = \frac{I_{mean}^2}{I_{std}^2} \]

Parameters:

Name Type Description Default
intensity_data ndarray

intensity of 2D roi data image (abs ** 2), with shape (samples, lines)

 required

Returns:

Type Description
float

Equivalent Number of Looks (ENL) for the given data region

Data masking operations for PSLR, ISLR and SSLR computation

Attributes

Classes

Functions:

generate_peak_mask

Python
generate_peak_mask(data: ndarray) -> np.ndarray

Generating a mask of the input array to isolate the main lobe from the background, filling with 1s where the main lobe region lies. Masking centered on main lobe and covering it whole up to first zeroes.

Parameters:

Name Type Description Default
data ndarray

2D array

 required

Returns:

Type Description
ndarray

2D mask array of 0s and 1s

generate_peak_mask_lobes

Python
generate_peak_mask_lobes(data: ndarray, side_lobes_directions: SideLobesDirections) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Generating a mask of the input array to isolate the main lobe from the background, filling with 1s where the main lobe region lies. Masking centered on main lobe and covering it whole up to first zeroes.

Parameters:

Name Type Description Default
data ndarray

array with a peak to be masked

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required

Returns:

Type Description
ndarray

range filled indexes
ndarray

azimuth filled indexes
ndarray

2D mask array of 0s and 1s

generate_rectangular_mask

Python
generate_rectangular_mask(x_axis: ndarray, y_axis: ndarray, size_x: float, size_y: float) -> np.ndarray

Generate rectangular mask of specified size starting from given axes.

Parameters:

Name Type Description Default
x_axis ndarray

x axis

 required
y_axis ndarray

y axis

 required
size_x float

mask size along x

 required
size_y float

mask size along y

 required

Returns:

Type Description
ndarray

2D mask of 1s of the given size

generate_resolution_mask

Python
generate_resolution_mask(x_axis: ndarray, y_axis: ndarray, res_x: float, res_y: float, multiplier_x: float, multiplier_y: float) -> np.ndarray

Generate a rectangular mask with size equal to res * multiplier.

Parameters:

Name Type Description Default
x_axis ndarray

x axis

 required
y_axis ndarray

y axis

 required
res_x float

resolution along x axis

 required
res_y float

resolution along y axis

 required
multiplier_x float

size of the mask for x axis in number of resolution cells

 required
multiplier_y float

size of the mask for y axis in number of resolution cells

 required

Returns:

Type Description
ndarray

2D mask array

generate_resolution_mask_lobes

Python
generate_resolution_mask_lobes(x_axis: ndarray, y_axis: ndarray, res_x: float, res_y: float, multiplier_x: float, multiplier_y: float, side_lobes_directions: SideLobesDirections) -> tuple[np.ndarray, np.ndarray, np.ndarray]

Generate a mask containing the data to the first resolution cell in both directions taking into account the side lobes directions.

Parameters:

Name Type Description Default
x_axis ndarray

x axis

 required
y_axis ndarray

y axis

 required
res_x float

resolution along x axis

 required
res_y float

resolution along y axis

 required
multiplier_x float

size of the mask for x axis in number of resolution cells

 required
multiplier_y float

size of the mask for y axis in number of resolution cells

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required

Returns:

Type Description
ndarray

range filled index
ndarray

azimuth filled indexes
ndarray

2D mask array

get_interpolated_lobes_cuts

Python
get_interpolated_lobes_cuts(x_axis: ndarray, y_axis: ndarray, values: ndarray, side_lobes_directions: SideLobesDirections, method: str = 'linear') -> tuple[np.ndarray, np.ndarray]

Extract range and azimuth cut/profiles by interpolation of input data for IRF analysis in case of squinted data, a.k.a. side lobes directions.

Parameters:

Name Type Description Default
x_axis ndarray

x axis array

 required
y_axis ndarray

y axis array

 required
values ndarray

2D array where to extract the profiles

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required
method str

interpolation method using RegularGridInterpolator, by default "linear"

 'linear'

Returns:

Type Description
ndarray

range cut
ndarray

azimuth cut

pslr_masking

Python
pslr_masking(data: ndarray, mask_flag: MaskingMethod, resolution: tuple[float, float], peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections, number_res_cells_az: int = 10, number_res_cells_rng: int = 10) -> np.ndarray

Masking input data to select only side lobes (up to a given extent) and remove the rest (main lobe and furthest lobes) for PSLR computation.

Parameters:

Name Type Description Default
data ndarray

input image 2d array

 required
mask_flag MaskingMethod

masking flag from one of MaskingMethod options

 required
resolution tuple[float, float]

resolution along range [0] and azimuth [1]

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required
number_res_cells_az int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in azimuth direction, by default 10

 10
number_res_cells_rng int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in range direction, by default 10

 10

Returns:

Type Description
ndarray

2D data mask

pslr_profile_cutting

Python
pslr_profile_cutting(masked_data: ndarray, peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections) -> tuple[np.ndarray, np.ndarray]

Extracting profile cuts both for range and azimuth from the masked input 2D array for PSLR computation.

Parameters:

Name Type Description Default
masked_data ndarray

masked 2D array

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required

Returns:

Type Description
ndarray

range profile cut
ndarray

azimuth profile cut

islr_masking

Python
islr_masking(data: ndarray, mask_flag: MaskingMethod, resolution: tuple[float, float], peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections, number_res_cells_az: int = 20, number_res_cells_rng: int = 20) -> tuple[np.ndarray, np.ndarray]

Masking input data to extract only data relevant to ISLR computation. Two masks are built: one extracting just the main lobe up to the first zeroes, and a second one to isolate only side lobes up to a given extent in terms of resolution cells both in range and azimuth.

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
mask_flag MaskingMethod

masking flag from one of MaskingMethod options

 required
resolution tuple[float, float]

resolution along range [0] and azimuth [1]

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required
number_res_cells_az int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in azimuth direction, by default 20

 20
number_res_cells_rng int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in range direction, by default 20

 20

Returns:

Type Description
ndarray

main lobe mask 2D array
ndarray

side lobes mask 2D array

islr_profile_cutting

Python
islr_profile_cutting(data: ndarray, main_lobe_mask: ndarray, islr_mask: ndarray, peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections) -> tuple[tuple[np.ndarray, np.ndarray], tuple[np.ndarray, np.ndarray]]

Extracting profile cuts both for range and azimuth divided by main lobe and side lobe coverage after applying the masks to the input 2D array for ISLR computation.

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
main_lobe_mask ndarray

main lobe boolean 2D mask

 required
islr_mask ndarray

islr boolean 2D mask

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required
side_lobes_directions SideLobesDirections

range and azimuth cuts angular coefficients in samples

 required

Returns:

Type Description
tuple[ndarray, ndarray]

main lobe range and azimuth cuts
tuple[ndarray, ndarray]

side lobes range and azimuth cuts

sslr_masking

Python
sslr_masking(data: ndarray, resolution: tuple[float, float], peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections, number_res_cells_az: int = 10, number_res_cells_rng: int = 10) -> np.ndarray

Masking input data 2D array to select only intermediate intensity lobes, removing most of the energy inside the image for SSLR computation.

Parameters:

Name Type Description Default
data ndarray

input 2D array

 required
resolution tuple[float, float]

resolution along range [0] and azimuth [1]

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required
side_lobes_directions ndarray

range and azimuth cuts angular coefficients in samples

 required
number_res_cells_az int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in azimuth direction, by default 10

 10
number_res_cells_rng int

number of resolution cells to be taken for the mask size. this determines the extent of the mask and therefore the number of lobes selected in range direction, by default 10

 10

Returns:

Type Description
ndarray

2D intermediate lobes mask array

sslr_profile_cutting

Python
sslr_profile_cutting(masked_data: ndarray, peak_pos: tuple[int, int], side_lobes_directions: SideLobesDirections) -> tuple[np.ndarray | float, np.ndarray | float]

Extracting profile cuts both for range and azimuth from the masked input 2D array for SSLR computation.

Parameters:

Name Type Description Default
masked_data ndarray

masked 2D array

 required
side_lobes_directions ndarray

range and azimuth cuts angular coefficients in samples

 required
peak_pos tuple[int, int]

peak position as max row [0] and max col [0] in input array

 required

Returns:

Type Description
ndarray | float

range profile cut (or its max in case of side lobes)
ndarray | float

azimuth profile cut (or its max in case of side lobes)

masking_outliers

Python
masking_outliers(data: ndarray, kernel_size: tuple[int, int] = (5, 5), filter_size: tuple[int, int] = (10, 10), percentile_boundaries: tuple[float, float] = (20, 90)) -> np.ndarray

Masking operation or removing outliers by specified percentile thresholds from input data. Values outside boundaries are set to nan.

Parameters:

Name Type Description Default
data ndarray

input 2D array to be masked

 required
kernel_size tuple[int, int]

size of convolution kernel, by default (5, 5)

 (5, 5)
filter_size tuple[int, int]

size of filter convolution kernel, by default (10, 10)

 (10, 10)
percentile_boundaries tuple[float, float]

percentile boundaries above and below which data are to be removed, by default (20, 90)

 (20, 90)

Returns:

Type Description
ndarray

masked 2D array containing nans where values have been removed

Common utilities across different analyses

Classes

Functions:

check_targets_visibility

Python
check_targets_visibility(product: QualityInputProduct, point_targets: list[PointTarget]) -> pd.DataFrame

Checking if a set of targets is seen by the sensor in the recorded swath.

Parameters:

Name Type Description Default
product ProductManager

product folder ProductManager instance

 required
point_targets list[PointTarget]

list of PointTarget objects

 required

Returns:

Type Description
DataFrame

pandas dataframe collecting all visible points

blocks_partitioning

Python
blocks_partitioning(azimuth_axis: ndarray, range_axis: NDArray[floating], lines_per_burst: ndarray, default_block_size: int) -> tuple[np.ndarray, int, list[tuple[int, int]]]

Defining the blocks partitioning of the whole scene.

Parameters:

Name Type Description Default
azimuth_axis ndarray

azimuth axis of the whole scene

 required
range_axis NDArray[floating]

range axis of the whole scene

 required
lines_per_burst ndarray

lines per burst array

 required
default_block_size int

default block size value, needed for stripmap case

 required

Returns:

Type Description
ndarray

size of each block
int

number of partitioning blocks
list[tuple[int, int]]

pixel coordinates of blocks centers (azimuth and range pixel values)

detect_burst_from_pixel

Python
detect_burst_from_pixel(lines_per_burst: ndarray, azimuth_px: int) -> int

Detect the burst belonging to the selected azimuth pixel value.

Parameters:

Name Type Description Default
lines_per_burst ndarray

lines per burst

 required
azimuth_px int

selected azimuth pixel

 required

Returns:

Type Description
int

burst

angles_computation_setup

Python
angles_computation_setup(trajectory: Trajectory, azimuth_time: PreciseDateTime, range_values: NDArray[floating], look_direction: str, altitude: float = 0.0) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating]]

Setting up the stage to compute incidence and look angles by computing sensor position, ground points and nadir direction.

Parameters:

Name Type Description Default
trajectory Trajectory

sensor trajectory

 required
azimuth_time PreciseDateTime

azimuth time at which compute the output

 required
range_values NDArray[floating]

range values for which compute values

 required
look_direction str

sensor look direction

 required
altitude float

altitude over WGS84 ellipsoid, by default 0.0

 0.0

Returns:

Type Description
NDArray[floating]

sensor position
NDArray[floating]

ground points
NDArray[floating]

nadir direction

Utilities

Collecting generic purpose dataclasses and enum classes used in the Quality module

Attributes

SideLobesDirections module-attribute

Python
SideLobesDirections = tuple[float, float]

Classes

SAROrbitDirection

Bases: Enum

Sensor orbit direction

Attributes

ASCENDING class-attribute instance-attribute
Python
ASCENDING = auto()
DESCENDING class-attribute instance-attribute
Python
DESCENDING = auto()
NOT_AVAILABLE class-attribute instance-attribute
Python
NOT_AVAILABLE = auto()

SARPolarization

Bases: Enum

Polarization enum class

Attributes

HH class-attribute instance-attribute
Python
HH = 'H/H'
VV class-attribute instance-attribute
Python
VV = 'V/V'
HV class-attribute instance-attribute
Python
HV = 'H/V'
VH class-attribute instance-attribute
Python
VH = 'V/H'

SARAcquisitionMode

Bases: Enum

Acquisition mode enum class

Attributes

SCANSAR class-attribute instance-attribute
Python
SCANSAR = auto()
SPOTLIGHT class-attribute instance-attribute
Python
SPOTLIGHT = auto()
STRIPMAP class-attribute instance-attribute
Python
STRIPMAP = auto()
TOPSAR class-attribute instance-attribute
Python
TOPSAR = auto()
WAVE class-attribute instance-attribute
Python
WAVE = auto()
ELEVATION_NOTCH class-attribute instance-attribute
Python
ELEVATION_NOTCH = auto()
UNKNOWN class-attribute instance-attribute
Python
UNKNOWN = auto()

CoordinatesType

Bases: Enum

Enum class for nominal point target coordinates type

Attributes

LLH class-attribute instance-attribute
Python
LLH = 0
ECEF class-attribute instance-attribute
Python
ECEF = 1
NORMALIZED class-attribute instance-attribute
Python
NORMALIZED = 2

DecibelConversion

Bases: Enum

Enum class for decibel multiplying factor setting

Attributes

AMPLITUDE class-attribute instance-attribute
Python
AMPLITUDE = auto()
POWER class-attribute instance-attribute
Python
POWER = auto()

SARProjection

Bases: Enum

Enum class for managing swath projection of product folder

Attributes

SLANT_RANGE class-attribute instance-attribute
Python
SLANT_RANGE = 'SLANT RANGE'
GROUND_RANGE class-attribute instance-attribute
Python
GROUND_RANGE = 'GROUND RANGE'

TargetDataType

Bases: Enum

Enum class for IRF data type labelling

Attributes

DETECTED class-attribute instance-attribute
Python
DETECTED = auto()
COMPLEX class-attribute instance-attribute
Python
COMPLEX = auto()

MaskingMethod

Bases: Enum

Enum class for masking method IRF setting

Attributes

PEAK class-attribute instance-attribute
Python
PEAK = auto()
RESOLUTION class-attribute instance-attribute
Python
RESOLUTION = auto()

GetFrequencyMethod

Bases: Enum

Enum class for get local frequency settings

Attributes

AUTOCORRELATION class-attribute instance-attribute
Python
AUTOCORRELATION = auto()
FFT class-attribute instance-attribute
Python
FFT = auto()
POWER_BALANCE class-attribute instance-attribute
Python
POWER_BALANCE = auto()

SARSideLooking

Bases: Enum

Enum class for sensor side looking direction

Attributes

RIGHT_LOOKING class-attribute instance-attribute
Python
RIGHT_LOOKING = 'RIGHT'
LEFT_LOOKING class-attribute instance-attribute
Python
LEFT_LOOKING = 'LEFT'

SARImageType

Bases: Enum

Enum class for image type

Attributes

RAW class-attribute instance-attribute
Python
RAW = auto()
RGC class-attribute instance-attribute
Python
RGC = auto()
SLC class-attribute instance-attribute
Python
SLC = auto()
GRD class-attribute instance-attribute
Python
GRD = auto()
NESZ_MAP class-attribute instance-attribute
Python
NESZ_MAP = auto()
INT class-attribute instance-attribute
Python
INT = auto()
OCN class-attribute instance-attribute
Python
OCN = auto()
MSLC class-attribute instance-attribute
Python
MSLC = auto()
COHERENCE class-attribute instance-attribute
Python
COHERENCE = auto()

Methods:

from_str staticmethod
Python
from_str(label: str) -> SARImageType

Generating a Enum SAR Image Type from input string.

Parameters:

Name Type Description Default
label str

label string

 required

Returns:

Type Description
SARImageType

SARImageType enum type corresponding to input string

Raises:

Type Description
NotImplementedError

if input string is not in the implemented enum types, this raise an error

SARRadiometricQuantity

Bases: Enum

Enum class for radiometric analysis input/output quantity types

Attributes

BETA_NOUGHT class-attribute instance-attribute
Python
BETA_NOUGHT = auto()
SIGMA_NOUGHT class-attribute instance-attribute
Python
SIGMA_NOUGHT = auto()
GAMMA_NOUGHT class-attribute instance-attribute
Python
GAMMA_NOUGHT = auto()

SARSamplingFrequencies dataclass

SAR signal sampling frequencies

Attributes

range_freq_hz instance-attribute
Python
range_freq_hz: float
range_bandwidth_freq_hz instance-attribute
Python
range_bandwidth_freq_hz: float
azimuth_freq_hz instance-attribute
Python
azimuth_freq_hz: float
azimuth_bandwidth_freq_hz instance-attribute
Python
azimuth_bandwidth_freq_hz: float

Methods:

__init__
Python
__init__(range_freq_hz: float, range_bandwidth_freq_hz: float, azimuth_freq_hz: float, azimuth_bandwidth_freq_hz: float) -> None

SARCoordinates dataclass

SAR Coordinates dataclass to gather azimuth and range index and times in swath

Attributes

azimuth class-attribute instance-attribute
Python
azimuth: PreciseDateTime = None
range class-attribute instance-attribute
Python
range: float = None
azimuth_index_subpx class-attribute instance-attribute
Python
azimuth_index_subpx: float = None
range_index_subpx class-attribute instance-attribute
Python
range_index_subpx: float = None
burst class-attribute instance-attribute
Python
burst: int = None

Methods:

__init__
Python
__init__(azimuth: PreciseDateTime = None, range: float = None, azimuth_index_subpx: float = None, range_index_subpx: float = None, burst: int = None) -> None

PointTargetVisibility dataclass

Point Target Visibility dataclass containing burst and swath association

Attributes

id instance-attribute
Python
id: str
channel instance-attribute
Python
channel: int
burst instance-attribute
Python
burst: list[int] | int
swath instance-attribute
Python
swath: str
polarization instance-attribute
Python
polarization: str

Methods:

__init__
Python
__init__(id: str, channel: int, burst: list[int] | int, swath: str, polarization: str) -> None

LocationData dataclass

Location Manager class satisfying the LocationData protocol

Attributes

abs_azimuth_time instance-attribute
Python
abs_azimuth_time: PreciseDateTime
abs_range_time instance-attribute
Python
abs_range_time: float
incidence_angle instance-attribute
Python
incidence_angle: float
look_angle instance-attribute
Python
look_angle: float
ground_velocity instance-attribute
Python
ground_velocity: float
azimuth_step_m instance-attribute
Python
azimuth_step_m: float
range_step_m instance-attribute
Python
range_step_m: float
ground_range_step_m instance-attribute
Python
ground_range_step_m: float

Methods:

__init__
Python
__init__(abs_azimuth_time: PreciseDateTime, abs_range_time: float, incidence_angle: float, look_angle: float, ground_velocity: float, azimuth_step_m: float, range_step_m: float, ground_range_step_m: float) -> None

Functions:

convert_to_enum_field

Python
convert_to_enum_field(fld: Any, *, enum_type: Type) -> Enum

Function to convert a string value to its corresponding Enum attribute.

Parameters:

Name Type Description Default
fld Any

field name, string or Enum type already

 required
enum_type Type

Enum type class of conversion

 required

Returns:

Type Description
Enum

Enum type attribute corresponding to the input name

Raises:

Type Description
ValueError

if the input value is not in the target Enum class, this error is raised

Custom errors definition for better troubleshooting

Attributes

known_errors module-attribute

Python
known_errors = [AzimuthExceedsBoundariesError, RangeExceedsBoundariesError]

Classes

AzimuthExceedsBoundariesError

Bases: ValueError

Selected Azimuth index in ROI extraction from Swath exceeds boundaries

RangeExceedsBoundariesError

Bases: ValueError

Selected Range index in ROI extraction from Swath exceeds boundaries

SideLobesDirectionsEstimationError

Bases: RuntimeError

Could not evaluate the side lobes directions values

CoordinatesOutOfBounds

Bases: RuntimeError

Input pixel/time coordinate is out of swath bounds

TargetAreaRecenteringError

Bases: RuntimeError

Error raised when recentering operation on input data fails

InvalidBurstIdError

Bases: ValueError

Provided burst id is invalid