Methods for “normalizing” a SICD (sarpy.processing.sicd.normalize_sicd)

Methods for transforming SICD data to a common state.

sarpy.processing.sicd.normalize_sicd.apply_skew_poly(input_data: ndarray, delta_kcoa_poly: ndarray, row_array: ndarray, col_array: ndarray, fft_sgn: int, dimension: int, forward: bool = False) → ndarray

Performs the skew operation on the complex array, according to the provided delta kcoa polynomial.

Parameters:

  • input_data (numpy.ndarray) – The input data.

  • delta_kcoa_poly (numpy.ndarray) – The delta kcoa polynomial to use.

  • row_array (numpy.ndarray) – The row array, should agree with input_data first dimension definition.

  • col_array (numpy.ndarray) – The column array, should agree with input_data second dimension definition.

  • fft_sgn (int) – The fft sign to use.

  • dimension (int) – The dimension to apply along.

  • forward (bool) – If True, this shifts forward (i.e. skews), otherwise applies in inverse (i.e. deskew) direction.

Return type:

numpy.ndarray

sarpy.processing.sicd.normalize_sicd.determine_weight_array(input_data_shape: Tuple[int, ...], weight_array: ndarray, oversample_rate: int | float, dimension: int) → Tuple[ndarray, int, int]

Determine the appropriate resampled weight array and bounds.

Parameters:

  • input_data_shape (tuple) – The shape of the input data, which should be a two element tuple.

  • weight_array (numpy.ndarray) –

  • oversample_rate (int|float) –

  • dimension (int) –

Returns:

  • weight_array (numpy.ndarray) – The weight array assuming nominal sampling. In the presence of oversampling, this is shorter than relevant dimension of the actual data.

  • start_index (int) – The starting index along the given dimension to which to apply weight. This will be 0 if not over-sampled.

  • end_index (int) – The (non-inclusive) final index along the given dimension to apply weight. This will be input_data_shape[dimension] if not oversampled.

sarpy.processing.sicd.normalize_sicd.apply_weight_array(input_data: ndarray, weight_array: ndarray, oversample_rate: int | float, dimension: int, inverse: bool = False) → ndarray

Apply the weight array along the given dimension.

Parameters:

  • input_data (numpy.ndarray) – The complex data array to weight.

  • weight_array (numpy.ndarray) – The weight array.

  • oversample_rate (int|float) – The oversample rate.

  • dimension (int) – Along which dimension to apply the weighting? Must be one of {0, 1}.

  • inverse (bool) – If True, this divides the weight (i.e. de-weight), otherwise it multiplies.

Return type:

numpy.ndarray

sarpy.processing.sicd.normalize_sicd.is_not_skewed(sicd: SICDType, dimension: int) → bool

Check if the sicd structure is not skewed along the provided dimension.

Parameters:

  • sicd (SICDType) –

  • dimension (int) –

Return type:

bool

sarpy.processing.sicd.normalize_sicd.is_uniform_weight(sicd: SICDType, dimension: int) → bool

Check if the sicd structure is has uniform weight along the provided dimension.

Parameters:

  • sicd (SICDType) –

  • dimension (int) –

Return type:

bool

sarpy.processing.sicd.normalize_sicd.is_normalized(sicd: SICDType, dimension: int = 1) → bool

Check if the sicd structure is normalized along the provided dimension.

Parameters:

  • sicd (SICDType) – The SICD structure.

  • dimension (int) – The dimension to test.

Returns:

normalization state in the given dimension

Return type:

bool

class sarpy.processing.sicd.normalize_sicd.DeskewCalculator(reader: SICDTypeReader, dimension: int = 1, index: int = 0, apply_deskew: bool = True, apply_deweighting: bool = False, apply_off_axis: bool = True)

Bases: FullResolutionFetcher

This is a calculator for deskewing/deweighting which requires full resolution in both dimensions.

property dimension: int

The dimension along which to perform the color subaperture split.

Type:

int

property apply_deskew: bool

Apply deskew to calculated value. This is for API completeness.

Type:

bool

property apply_deweighting: bool

Apply deweighting to calculated values.

Type:

bool

property block_size: float | None

The approximate processing block size in MB, where None represents processing in a single block.

Type:

None|float

property block_size_in_bytes: int | None

The approximate processing block size in bytes.

Type:

None|int

property data_size: Tuple[int, ...]

The data size for the reader at the given index.

Type:

Tuple[int, …]

static extract_blocks(the_range: slice | Tuple[int, int, int], index_block_size: None | int | float) → Tuple[List[Tuple[int, int, int]], List[Tuple[int, int]]]

Convert the single range definition into a series of range definitions in keeping with fetching of the appropriate block sizes.

Parameters:

  • the_range (slice|Tuple[int, int, int]) – The input (off processing axis) range.

  • index_block_size (None|int|float) – The size of blocks (number of indices).

Returns:

  • range_definitions (List[Tuple[int, int, int]]) – The sequence of range definitions (start index, stop index, step) relative to the overall image.

  • limit_indices (List[Tuple[int, int]]) – The sequence of start/stop indices for positioning of the given range relative to the original range.

get_fetch_block_size(start_element: int, stop_element: int) → int

Gets the fetch block size for the given full resolution section. This assumes that the fetched data will be 8 bytes per pixel, in accordance with single band complex64 data.

Parameters:

  • start_element (int) –

  • stop_element (int) –

Return type:

int

property index: int

The index of the reader.

Type:

int

property reader: SICDTypeReader

The reader instance.

Type:

SICDTypeReader

property sicd: SICDType

The sicd structure.

Type:

SICDType

sarpy.processing.sicd.normalize_sicd.aperture_dimension_limits(sicd: SICDType, dimension: int, dimension_limits: Tuple[int | float, int | float] | None = None, aperture_limits: Tuple[int | float, int | float] | None = None) → Tuple[Tuple[int, int], Tuple[int, int]]

This is a helper method to determine the “correct” effective limits for aperture processing along the given dimension, considering the ImpRespBW values.

Parameters:

  • sicd (SICDType) –

  • dimension (int) – One of {0, 1}, for the processing dimension

  • dimension_limits (None|Tuple[int|float, int|float]) – The base limits along the given dimension, will default to (0, rows) for dimension=0 or (0, columns) for dimension=1, if not provided.

  • aperture_limits (None|Tuple[int|float, int|float]) – The desired aperture limits, relative to dimension_limits.

Returns:

  • dimension_limits (Tuple[int, int]) – The explicitly populated effective limits along the given dimension.

  • aperture_limits (Tuple[int, int]) – The valid aperture limits, relative to dimension_limits, after considerations of the impulse response bandwidth along the dimension.

sarpy.processing.sicd.normalize_sicd.aperture_dimension_params(sicd: SICDType, dimension: int, dimension_limits: Tuple[int | float, int | float] | None = None, aperture_limits: Tuple[int, int] | None = None, new_weight_function: ndarray | None = None)

Gets the aperture processing parameters along the given dimension.

Parameters:

  • sicd (SICDType) –

  • dimension (int) – One of {0, 1}, for the processing dimension

  • dimension_limits (None|tuple[int|float, int|float]) – The base limits along the given dimension, will default to (0, rows) for dimension=0 or (0, columns) for dimension=1, if not provided.

  • aperture_limits (tuple[int, int]) – The valid aperture limits, relative to dimension_limits, after considerations of the impulse response bandwidth along the dimension.

  • new_weight_function (None|numpy.ndarray) – The new weight function. This will default to the current weight function if not provided.

Returns:

  • dimension_limits (tuple[int, int]) – The explicitly populated effective limits along the given dimension.

  • cur_aperture_limits (tuple[int, int]) – The current valid aperture limits, relative to dimension_limits, after considerations of the impulse response bandwidth along the dimension.

  • cur_aperture_weighting (numpy.ndarray)

  • new_aperture_limits (tuple[int, int]) – The new valid aperture limits, relative to dimension_limits, after considerations of the impulse response bandwidth along the dimension.

  • new_aperture_weighting (numpy.ndarray)

sarpy.processing.sicd.normalize_sicd.noise_scaling(cur_ap_limits: Tuple[int, int], cur_weighting: ndarray, new_ap_limits: Tuple[int, int], new_weighting: ndarray) → float

Gets noise scaling due to sub-aperture degradation and re-weighting along one dimension.

Parameters:

  • cur_ap_limits (Tuple[int, int]) –

  • cur_weighting (numpy.ndarray) –

  • new_ap_limits (Tuple[int, int]) –

  • new_weighting (numpy.ndarray) –

Returns:

noise_multiplier

Return type:

float

sarpy.processing.sicd.normalize_sicd.sicd_degrade_reweight(reader: SICDTypeReader, output_file: str | None = None, index: int = 0, row_limits: Tuple[int, int] | None = None, column_limits: Tuple[int, int] | None = None, row_aperture: Tuple[int, int] | None = None, row_weighting: Dict | None = None, column_aperture: Tuple[int, int] | None = None, column_weighting: Dict | None = None, add_noise: float | None = None, pixel_threshold: int | None = 2250000, check_existence: bool = True, check_older_version: bool = False, repopulate_rniirs: bool = True) → FlatSICDReader | None

Given input, create a SICD (file or reader) with modified weighting/subaperture parameters. Any additional noise will be added before performing any sub-aperture degradation processing.

Recall that reducing the size of the impulse response bandwidth via sub-aperture degradation in a single direction by by \(ratio\), actually decreases the magnitude of the noise in pixel power by \(ratio\), or subtracts \(10*\log_{10}(ratio)\) from the noise given in dB.

Warning

To ensure correctness of metadata, if the Noise Polynomial is present, then then the NoiseLevelType must be ‘ABSOLUTE’. Otherwise an exception will be raised.

Parameters:

  • reader (str|SICDTypeReader) – A sicd type reader.

  • output_file (None|str) – If None, an in-memory SICD reader instance will be returned. Otherwise, this is the path for the produced output SICD file.

  • index (int) – The reader index to be used.

  • row_limits (None|(int, int)) – Row limits for the underlying data.

  • column_limits (None|(int, int)) – Column limits for the underlying data.

  • row_aperture (None|tuple) – None (no row subaperture), or integer valued start_row, end_row for the row subaperture definition. This is with respect to row values AFTER considering row_limits. Note that this will reduce the noise, so the noise polynomial (if it is populated) will be modified.

  • row_weighting (None|dict) – None (no row weighting change), or the new row weighting parameters {‘WindowName’: <name>, ‘Parameters: {}, ‘WgtFunct’: array}.

  • column_aperture (None|tuple) – None (no column subaperture), or integer valued start_col, end_col for the column sub-aperture definition. This is with respect to row values AFTER considering column_limits. Note that this will reduce the noise, so the noise polynomial (if it is populated) will be modified.

  • column_weighting (None|dict) – None (no columng weighting change), or the new column weighting parameters {‘WindowName’: <name>, ‘Parameters: {}, ‘WgtFunct’: array}.

  • add_noise (None|float) – If provided, Gaussian white noise of pixel power add_noise will be added, prior to any subbaperture processing. Note that performing subaperture processing actually reduces the resulting noise, which will also be considered.

  • pixel_threshold (None|int) – Approximate pixel area threshold for performing this directly in memory.

  • check_existence (bool) – Should we check if the given file already exists, and raise an exception if so?

  • check_older_version (bool) – Try to use a less recent version of SICD (1.1), for possible application compliance issues?

  • repopulate_rniirs (bool) – Should we try to repopulate the estimated RNIIRS value?

Returns:

No return if output_file is provided, otherwise the returns the in-memory reader object.

Return type:

None|FlatSICDReader