Skip to content

API

Main Implementation

Spectral Analysis: Distributed and Point Target Spectra

Attributes

Classes

Functions:

point_target_spectral_analysis

Python
point_target_spectral_analysis(product: QualityInputProduct, point_targets: list[PointTarget], cropping_size: tuple[int, int] = (128, 128)) -> list[PointTargetSpectraDataOutput]

Function to compute Spectral Analysis for selected Point Targets.

Parameters:

Name Type Description Default
product QualityInputProduct

object satisfying the QualityInputProduct protocol

 required
point_targets list[PointTarget]

list of point targets locations, as PointTarget objects

 required
cropping_size tuple[int, int]

roi cropping size, (number of samples, number of lines), by default (128, 128)

 (128, 128)

Returns:

Type Description
list[PointTargetSpectraDataOutput]

spectral analysis results for each product channel and each Point Target

block_wise_distributed_spectral_analysis

Python
block_wise_distributed_spectral_analysis(product: QualityInputProduct, azimuth_block_size: int = 2000) -> list[DistributedSpectraDataOutput]

Compute Spectral Analysis for each channel of the input product raster, by partitioning the scene in blocks along azimuth. If the product's acquisition mode, bursts are considered as blocks and data is deramped.

Parameters:

Name Type Description Default
product QualityInputProduct

object satisfying the QualityInputProduct protocol

 required
azimuth_block_size int

azimuth block size, by default 2000

 2000

Returns:

Type Description
list[DistributedSpectraDataOutput]

list of Spectral Data for every product channel and every block

Spectral Analysis support functionalities

Attributes

Classes

Functions:

data_deramping

Python
data_deramping(data: ndarray, channel_data: ChannelData, burst: int, roi_center_location_px: tuple[int, int]) -> np.ndarray

Deramping input raster data portion.

Parameters:

Name Type Description Default
data ndarray

raster data portion, with shape (samples, lines)

 required
channel_data ChannelData

channel data manager instance

 required
burst int

current burst number

 required
roi_center_location_px tuple[int, int]

roi center location in pixels, (azimuth pixel, range pixel)

 required

Returns:

Type Description
ndarray

deramped raster data portion

compute_deramping_phase_exponential

Python
compute_deramping_phase_exponential(lines_per_burst: int, lines_step: float, doppler_centroid_axis: NDArray[floating], doppler_rate_axis: NDArray[floating], steering_rate_factor: NDArray[floating] | None = None) -> np.ndarray

Computing deramping exponential phase function. It can be used both for Scansar and Topsar acquisition modes, providing the azimuth steering rate for Topsar mode.

\[ \begin{aligned} & exp \left( \pi i \cdot coeff \cdot \left(t_{burst}^{rel} - \left(t_{mid\_burst}^{rel} - \frac{(f_{DC} - f_{DC_{mid}})}{k_D} \right) \right)^2 \right) \\[10pt] & coeff_{topsar} = -\frac{-k_D \cdot a_r}{a_r - k_D} \\[10pt] & coeff_{scansar} = k_D \\[10pt] \end{aligned} \]

Parameters:

Name Type Description Default
lines_per_burst int

lines per burst

 required
lines_step float

lines step in seconds

 required
doppler_centroid_axis NDArray[floating]

doppler centroid frequency axis, computed for each range sample, with shape (samples,)

 required
doppler_rate_axis NDArray[floating]

doppler rate axis, computed for each range sample, with shape (samples,)

 required
steering_rate_factor NDArray[floating]

azimuth steering rate contribution, computed for each range sample, with shape (samples,)

 None

Returns:

Type Description
ndarray

deramping exponential phase function, with shape (lines per burst, samples)

compute_deramping_azimuth_axis

Python
compute_deramping_azimuth_axis(lines_per_burst: int, lines_step: float, doppler_centroid_axis: NDArray[floating], doppler_rate_axis: NDArray[floating]) -> npt.NDArray[np.floating]

Computing deramping phase burst azimuth relative axis.

\[ t_{burst}^{rel} - \left(t_{mid\_burst}^{rel} - \frac{(f_{DC} - f_{DC_{mid}})}{k_D}\right) \]

Parameters:

Name Type Description Default
lines_per_burst int

lines per burst

 required
lines_step float

lines step in seconds

 required
doppler_centroid_axis NDArray[floating]

doppler centroid frequency axis, computed for each range sample, with shape (samples,)

 required
doppler_rate_axis NDArray[floating]

doppler rate axis, computed for each range sample, with shape (samples,)

 required

Returns:

Type Description
NDArray[floating]

deramping phase burst azimuth relative axis, with shape (lines per burst, samples)

compute_demodulation_phase_exponential

Python
compute_demodulation_phase_exponential(lines_per_burst: int, lines_step: float, doppler_centroid_axis: NDArray[floating], doppler_rate_axis: NDArray[floating]) -> np.ndarray

Computing demodulation exponential phase function.

\[ exp \left( -2 \pi i \cdot f_{DC} t_{burst}^{rel} \right) \]

Parameters:

Name Type Description Default
lines_per_burst int

lines per burst

 required
lines_step float

lines step in seconds

 required
doppler_centroid_axis NDArray[floating]

doppler centroid frequency axis, with shape (samples,)

 required
doppler_rate_axis NDArray[floating]

doppler rate axis, computed for each range sample, with shape (samples,)

 required

Returns:

Type Description
ndarray

demodulation exponential phase function, with shape (lines per burst, samples)

compute_burst_deramping_function

Python
compute_burst_deramping_function(mid_burst_az_time: PreciseDateTime, lines_per_burst: int, lines_step: float, slant_range_axis: NDArray[floating], doppler_centroid_poly: SARCoordinatesFunction, doppler_rate_poly: SARCoordinatesFunction, azimuth_steering_rate_axis: NDArray[floating] | None = None, sensor_velocity_norm_mid_burst: float | None = None, wavelength: float | None = None) -> np.ndarray

Computing the deramping and demodulation phase exponential function for Topsar and Scansar acquisition for a given burst, defined by the mid burst azimuth time.

Azimuth steering rate, Normalized sensor velocity and sensor wavelength are needed only for Topsar deramping phase computation.

Parameters:

Name Type Description Default
mid_burst_az_time PreciseDateTime

azimuth time at mid burst

 required
lines_per_burst int

number of lines of the selected burst

 required
lines_step float

azimuth lines step in seconds

 required
slant_range_axis NDArray[floating]

slant range values

 required
doppler_centroid_poly SARCoordinatesFunction

doppler centroid polynomial

 required
doppler_rate_poly SARCoordinatesFunction

doppler rate polynomial

 required
azimuth_steering_rate_axis NDArray[floating] | None

steering rate axis, needed for Topsar deramping, by default None

 None
sensor_velocity_norm_mid_burst float | None

normalized sensor velocity at mid burst, needed for Topsar deramping, by default None

 None
wavelength float | None

sensor wavelength, needed for Topsar deramping, by default None

 None

Returns:

Type Description
ndarray

deramping and demodulation phase exponential function to be multiplied to the selected burst data

compute_steering_rate_factor

Python
compute_steering_rate_factor(sensor_velocity_norm_mid_burst: float, wavelength: float, azimuth_steering_rate_axis: NDArray[floating]) -> npt.NDArray[np.floating]

Computing steering rate factor for Topsar deramping.

Parameters:

Name Type Description Default
sensor_velocity_norm_mid_burst float

normalized sensor velocity at mid burst

 required
wavelength float

sensor wavelength

 required
azimuth_steering_rate_axis NDArray[floating]

azimuth steering rate axis

 required

Returns:

Type Description
NDArray[floating]

steering rate factor for deramping

recenter_data

Python
recenter_data(data: NDArray[floating]) -> npt.NDArray[np.floating]

Centering target area on point target signal peak.

Parameters:

Name Type Description Default
data NDArray[floating]

target area 2D array

 required

Returns:

Type Description
NDArray[floating]

recentered 2D array

compute_spectrogram_db

Python
compute_spectrogram_db(data: NDArray[floating]) -> tuple[npt.NDArray[np.floating], npt.NDArray[np.floating], npt.NDArray[np.floating]]

Computing the spectrogram and its time and frequency axes.

Parameters:

Name Type Description Default
data NDArray[floating]

target area 2D

 required

Returns:

Type Description
NDArray[floating]

spectrogram in dB
NDArray[floating]

spectrogram frequency axis
NDArray[floating]

spectrogram times axis

compute_polynomial_fit

Python
compute_polynomial_fit(profile: NDArray[floating], freq_axis: NDArray[floating], boundaries: tuple[float, float]) -> Polynomial

FItting polynomial on profile portion.

Parameters:

Name Type Description Default
profile NDArray[floating]

profile to be fit

 required
freq_axis NDArray[floating]

frequency axis

 required
boundaries tuple[float, float]

fitting region boundaries

 required

Returns:

Type Description
Polynomial

fitting Polynomial

extract_abs_profiles

Python
extract_abs_profiles(data_fft: NDArray[floating]) -> tuple[list[npt.NDArray[np.floating]], list[npt.NDArray[np.floating]]]

Extract range and azimuth absolute profiles in dB.

Parameters:

Name Type Description Default
data_fft NDArray[floating]

fft of the target area

 required

Returns:

Type Description
list[NDArray[floating]]

3 range absolute profiles in dB
list[NDArray[floating]]

3 azimuth absolute profiles in dB

extract_phase_profiles

Python
extract_phase_profiles(data_fft: NDArray[floating]) -> tuple[list[npt.NDArray[np.floating]], list[npt.NDArray[np.floating]]]

Extract range and azimuth phase profiles in deg.

Parameters:

Name Type Description Default
data_fft NDArray[floating]

fft of the target area

 required

Returns:

Type Description
list[NDArray[floating]]

3 range phase profiles in deg
list[NDArray[floating]]

3 azimuth phase profiles in deg

compute_spectrum_boundaries

Python
compute_spectrum_boundaries(profile: NDArray[floating]) -> tuple[int, int]

Computing relevant spectrum boundaries from profile.

Parameters:

Name Type Description Default
profile NDArray[floating]

profile to be analyzed

 required

Returns:

Type Description
int

start index of spectrum
int

stop index of spectrum

spectral_analysis_profiles_to_netcdf

Python
spectral_analysis_profiles_to_netcdf(data: list[PointTargetSpectraDataOutput] | list[DistributedSpectraDataOutput], out_path: str | Path) -> Path

Saving Spectral Analysis Profiles output data to NetCDF4 file.

Hierarchy::

Point Target Spectral Analysis Hierarchy::

Text Only
root/
├── product_attributes...
└── swath
    └── polarization
        ├── channel_attributes...
        ├── doppler_centroid [at target position]
        ├── phase_value [at target position]
        ├── azimuth_frequency_axis
        ├── range_frequency_axis
        ├── azimuth_profiles_abs
        ├── range_profiles_abs
        ├── azimuth_profiles_phase
        ├── range_profiles_phase
        ├── az_phase_polynomial_coefficients
        └── rng_phase_polynomial_coefficients

Distributed Spectral Analysis Hierarchy::

Text Only
root/
├── product_attributes...
└── swath
    └── polarization
        ├── channel_attributes...
        └── block
            ├── block_attributes...
            ├── azimuth_frequency_axis
            ├── range_frequency_axis
            ├── azimuth_profiles_abs
            └── range_profiles_abs

Parameters:

Name Type Description Default
data list[PointTargetSpectraDataOutput] | list[DistributedSpectraDataOutput]

list of PointTargetSpectraDataOutput | DistributedSpectraDataOutput dataclasses, corresponding to the full output of the radiometric analysis

 required
out_path str | Path

path where to save the NetCDF file

 required

Returns:

Type Description
Path

path to the output NetCDF file

Functions to generate plots for Spectral Analysis

Attributes

COLORS_SET module-attribute

Python
COLORS_SET = ['#282A3E', '#8783D1', '#B0413E']

CMAP module-attribute

Python
CMAP = 'inferno'

GraphType module-attribute

Python
GraphType = Literal['PHASE', 'ABSOLUTE']

Classes

Functions:

spectral_graphs

Python
spectral_graphs(data: list[PointTargetSpectraDataOutput] | list[DistributedSpectraDataOutput], output_dir: str | Path) -> None

Generating spectral analysis graphs.

Parameters:

Name Type Description Default
data list[PointTargetSpectraDataOutput] | list[DistributedSpectraDataOutput]

list of spectral profiles and data portions to be plotted for each swath id and target/block

 required
output_dir str | Path

Path to the output folder where to save the files

 required

spectral_graph_core

Python
spectral_graph_core(data: PointTargetSpectraDataOutput | DistributedSpectraDataOutput, graph_mode: GraphType, out_dir: Path) -> None

Spectral graphs generator core functionality.

Parameters:

Name Type Description Default
data PointTargetSpectraDataOutput | DistributedSpectraDataOutput

spectral profiles and data portions to be plotted for a given swath id, block or target

 required
graph_mode GraphType

graph mode, absolute or phase plots

 required
out_dir Path

Path to the output folder where to save the files

 required

Utilities

Definition of Spectral Analysis specific dataclasses

Classes

SpectralAnalysisProductGeneralInfo dataclass

General info for the analyzed product

Attributes

product instance-attribute
Python
product: str
channel instance-attribute
Python
channel: str
swath instance-attribute
Python
swath: str
polarization instance-attribute
Python
polarization: str
sensor instance-attribute
Python
sensor: str
product_type instance-attribute
Python
product_type: str
acquisition_mode instance-attribute
Python
acquisition_mode: str
orbit_direction instance-attribute
Python
orbit_direction: str
acquisition_start_time instance-attribute
Python
acquisition_start_time: datetime

Methods:

__init__
Python
__init__(product: str, channel: str, swath: str, polarization: str, sensor: str, product_type: str, acquisition_mode: str, orbit_direction: str, acquisition_start_time: datetime) -> None

SpectralAnalysisCoreInfo dataclass

Output core results for single Target Spectral Analysis

Attributes

azimuth_frequency_axis class-attribute instance-attribute
Python
azimuth_frequency_axis: NDArray[floating] | None = None
range_frequency_axis class-attribute instance-attribute
Python
range_frequency_axis: NDArray[floating] | None = None
spectrum_db class-attribute instance-attribute
Python
spectrum_db: NDArray[floating] | None = None
spectrum_deg class-attribute instance-attribute
Python
spectrum_deg: NDArray[floating] | None = None
spectrogram_db class-attribute instance-attribute
Python
spectrogram_db: NDArray[floating] | None = None
spectrogram_frequencies class-attribute instance-attribute
Python
spectrogram_frequencies: NDArray[floating] | None = None
spectrogram_times class-attribute instance-attribute
Python
spectrogram_times: NDArray[floating] | None = None
range_profiles_db class-attribute instance-attribute
Python
range_profiles_db: list[NDArray[floating]] | None = None
azimuth_profiles_db class-attribute instance-attribute
Python
azimuth_profiles_db: list[NDArray[floating]] | None = None
range_profiles_deg class-attribute instance-attribute
Python
range_profiles_deg: list[NDArray[floating]] | None = None
azimuth_profiles_deg class-attribute instance-attribute
Python
azimuth_profiles_deg: list[NDArray[floating]] | None = None

Methods:

__init__
Python
__init__(azimuth_frequency_axis: NDArray[floating] | None = None, range_frequency_axis: NDArray[floating] | None = None, spectrum_db: NDArray[floating] | None = None, spectrum_deg: NDArray[floating] | None = None, spectrogram_db: NDArray[floating] | None = None, spectrogram_frequencies: NDArray[floating] | None = None, spectrogram_times: NDArray[floating] | None = None, range_profiles_db: list[NDArray[floating]] | None = None, azimuth_profiles_db: list[NDArray[floating]] | None = None, range_profiles_deg: list[NDArray[floating]] | None = None, azimuth_profiles_deg: list[NDArray[floating]] | None = None) -> None

SpectralAnalysisTargetInfo dataclass

Bases: SpectralAnalysisCoreInfo

Storing data for Point Target Spectral Analysis graphs

Attributes

target_name class-attribute instance-attribute
Python
target_name: str | None = None
burst class-attribute instance-attribute
Python
burst: int | None = None
roi_size_azimuth class-attribute instance-attribute
Python
roi_size_azimuth: int | None = None
roi_size_range class-attribute instance-attribute
Python
roi_size_range: int | None = None
target_azimuth_pixel class-attribute instance-attribute
Python
target_azimuth_pixel: float | None = None
target_range_pixel class-attribute instance-attribute
Python
target_range_pixel: float | None = None
azimuth_time class-attribute instance-attribute
Python
azimuth_time: PreciseDateTime | None = None
range_time class-attribute instance-attribute
Python
range_time: float | None = None
range_profiles_norm_deg class-attribute instance-attribute
Python
range_profiles_norm_deg: list[NDArray[floating]] | None = None
azimuth_profiles_norm_deg class-attribute instance-attribute
Python
azimuth_profiles_norm_deg: list[NDArray[floating]] | None = None
target_phase_value_deg class-attribute instance-attribute
Python
target_phase_value_deg: float | None = None
target_doppler_centroid_Hz class-attribute instance-attribute
Python
target_doppler_centroid_Hz: float | None = None
range_polynomial_fit class-attribute instance-attribute
Python
range_polynomial_fit: Polynomial | None = None
azimuth_polynomial_fit class-attribute instance-attribute
Python
azimuth_polynomial_fit: Polynomial | None = None
rng_spectrum_boundaries class-attribute instance-attribute
Python
rng_spectrum_boundaries: tuple[float, float] | None = None
az_spectrum_boundaries class-attribute instance-attribute
Python
az_spectrum_boundaries: tuple[float, float] | None = None
azimuth_frequency_axis class-attribute instance-attribute
Python
azimuth_frequency_axis: NDArray[floating] | None = None
range_frequency_axis class-attribute instance-attribute
Python
range_frequency_axis: NDArray[floating] | None = None
spectrum_db class-attribute instance-attribute
Python
spectrum_db: NDArray[floating] | None = None
spectrum_deg class-attribute instance-attribute
Python
spectrum_deg: NDArray[floating] | None = None
spectrogram_db class-attribute instance-attribute
Python
spectrogram_db: NDArray[floating] | None = None
spectrogram_frequencies class-attribute instance-attribute
Python
spectrogram_frequencies: NDArray[floating] | None = None
spectrogram_times class-attribute instance-attribute
Python
spectrogram_times: NDArray[floating] | None = None
range_profiles_db class-attribute instance-attribute
Python
range_profiles_db: list[NDArray[floating]] | None = None
azimuth_profiles_db class-attribute instance-attribute
Python
azimuth_profiles_db: list[NDArray[floating]] | None = None
range_profiles_deg class-attribute instance-attribute
Python
range_profiles_deg: list[NDArray[floating]] | None = None
azimuth_profiles_deg class-attribute instance-attribute
Python
azimuth_profiles_deg: list[NDArray[floating]] | None = None

Methods:

__init__
Python
__init__(azimuth_frequency_axis: NDArray[floating] | None = None, range_frequency_axis: NDArray[floating] | None = None, spectrum_db: NDArray[floating] | None = None, spectrum_deg: NDArray[floating] | None = None, spectrogram_db: NDArray[floating] | None = None, spectrogram_frequencies: NDArray[floating] | None = None, spectrogram_times: NDArray[floating] | None = None, range_profiles_db: list[NDArray[floating]] | None = None, azimuth_profiles_db: list[NDArray[floating]] | None = None, range_profiles_deg: list[NDArray[floating]] | None = None, azimuth_profiles_deg: list[NDArray[floating]] | None = None, target_name: str | None = None, burst: int | None = None, roi_size_azimuth: int | None = None, roi_size_range: int | None = None, target_azimuth_pixel: float | None = None, target_range_pixel: float | None = None, azimuth_time: PreciseDateTime | None = None, range_time: float | None = None, range_profiles_norm_deg: list[NDArray[floating]] | None = None, azimuth_profiles_norm_deg: list[NDArray[floating]] | None = None, target_phase_value_deg: float | None = None, target_doppler_centroid_Hz: float | None = None, range_polynomial_fit: Polynomial | None = None, azimuth_polynomial_fit: Polynomial | None = None, rng_spectrum_boundaries: tuple[float, float] | None = None, az_spectrum_boundaries: tuple[float, float] | None = None) -> None

SpectralAnalysisBlockInfo dataclass

Bases: SpectralAnalysisCoreInfo

Block-wise Spectral Analysis info

Attributes

block_num class-attribute instance-attribute
Python
block_num: int | None = None
first_az_line_block class-attribute instance-attribute
Python
first_az_line_block: int | None = None
lines_block class-attribute instance-attribute
Python
lines_block: int | None = None
samples_block class-attribute instance-attribute
Python
samples_block: int | None = None
doppler_centroid_mid_block class-attribute instance-attribute
Python
doppler_centroid_mid_block: float | None = None
azimuth_frequency_axis class-attribute instance-attribute
Python
azimuth_frequency_axis: NDArray[floating] | None = None
range_frequency_axis class-attribute instance-attribute
Python
range_frequency_axis: NDArray[floating] | None = None
spectrum_db class-attribute instance-attribute
Python
spectrum_db: NDArray[floating] | None = None
spectrum_deg class-attribute instance-attribute
Python
spectrum_deg: NDArray[floating] | None = None
spectrogram_db class-attribute instance-attribute
Python
spectrogram_db: NDArray[floating] | None = None
spectrogram_frequencies class-attribute instance-attribute
Python
spectrogram_frequencies: NDArray[floating] | None = None
spectrogram_times class-attribute instance-attribute
Python
spectrogram_times: NDArray[floating] | None = None
range_profiles_db class-attribute instance-attribute
Python
range_profiles_db: list[NDArray[floating]] | None = None
azimuth_profiles_db class-attribute instance-attribute
Python
azimuth_profiles_db: list[NDArray[floating]] | None = None
range_profiles_deg class-attribute instance-attribute
Python
range_profiles_deg: list[NDArray[floating]] | None = None
azimuth_profiles_deg class-attribute instance-attribute
Python
azimuth_profiles_deg: list[NDArray[floating]] | None = None

Methods:

__init__
Python
__init__(azimuth_frequency_axis: NDArray[floating] | None = None, range_frequency_axis: NDArray[floating] | None = None, spectrum_db: NDArray[floating] | None = None, spectrum_deg: NDArray[floating] | None = None, spectrogram_db: NDArray[floating] | None = None, spectrogram_frequencies: NDArray[floating] | None = None, spectrogram_times: NDArray[floating] | None = None, range_profiles_db: list[NDArray[floating]] | None = None, azimuth_profiles_db: list[NDArray[floating]] | None = None, range_profiles_deg: list[NDArray[floating]] | None = None, azimuth_profiles_deg: list[NDArray[floating]] | None = None, block_num: int | None = None, first_az_line_block: int | None = None, lines_block: int | None = None, samples_block: int | None = None, doppler_centroid_mid_block: float | None = None) -> None

PointTargetSpectraDataOutput dataclass

Storing data for Point Target Spectral Analysis graphs

Attributes

general_info class-attribute instance-attribute
Python
general_info: SpectralAnalysisProductGeneralInfo | None = None
targets_info class-attribute instance-attribute
Python
targets_info: list[SpectralAnalysisTargetInfo] | None = None

Methods:

__init__
Python
__init__(general_info: SpectralAnalysisProductGeneralInfo | None = None, targets_info: list[SpectralAnalysisTargetInfo] | None = None) -> None

DistributedSpectraDataOutput dataclass

Storing data for Distributed Spectral Analysis graphs

Attributes

general_info class-attribute instance-attribute
Python
general_info: SpectralAnalysisProductGeneralInfo | None = None
blocks_info class-attribute instance-attribute
Python
blocks_info: list[SpectralAnalysisBlockInfo] | None = None

Methods:

__init__
Python
__init__(general_info: SpectralAnalysisProductGeneralInfo | None = None, blocks_info: list[SpectralAnalysisBlockInfo] | None = None) -> None