Radar Generalized Image Quality Equation (RGIQE) methods (sarpy.processing.sicd.rgiqe)

Radar Generalized Image Quality Equation (RGIQE) calculation(s) and tools for application to SICD structures and files.

sarpy.processing.sicd.rgiqe.RNIIRS_FIT_PARAMETERS = array([3.4761, 0.4357])

The RNIIRS calculation parameters determined by empirical data fit, parameters updated on 2022-02-01

sarpy.processing.sicd.rgiqe.get_sigma0_noise(sicd: SICDType) → float

Calculate the absolute noise estimate, in sigma0 power units.

Parameters:

sicd (SICDType) –

Return type:

float

sarpy.processing.sicd.rgiqe.get_default_signal_estimate(sicd: SICDType) → float

Gets default signal for use in the RNIIRS calculation. This will be 1.0 for copolar (or unknown) collections, and 0.25 for cross-pole collections.

Parameters:

sicd (SICDType) –

Return type:

float

sarpy.processing.sicd.rgiqe.get_bandwidth_area(sicd: SICDType) → float

Calculate the bandwidth area.

Parameters:

sicd (SICDType) –

Return type:

float

sarpy.processing.sicd.rgiqe.get_information_density(bandwidth_area: float | ndarray, signal: float | ndarray, noise: float | ndarray) → float | ndarray

Calculate the information density from bandwidth area and signal/noise estimates.

Parameters:

  • bandwidth_area (float|numpy.ndarray) –

  • signal (float|numpy.ndarray) –

  • noise (float|numpy.ndarray) –

Return type:

float|numpy.ndarray

sarpy.processing.sicd.rgiqe.get_rniirs(information_density: float | ndarray) → float | ndarray

Calculate an RNIIRS estimate from the information density or Shannon-Hartley channel capacity.

This mapping has been empirically determined by fitting Shannon-Hartley channel capacity to RNIIRS for some sample images.

The basic model is given by \(rniirs = a_0 + a_1*\log_2(information\_density)\)

To maintain positivity of the estimated rniirs, this transitions to a linear model \(rniirs = slope*information\_density\) with slope given by \(slope = a_1/(iim\_transition*\log(2))\) below the transition point at \(transition = \exp(1 - \log(2)*a_0/a_1)\).

Parameters:

information_density (float|numpy.ndarray) –

Return type:

float|numpy.ndarray

sarpy.processing.sicd.rgiqe.get_information_density_for_rniirs(rniirs: float | ndarray) → float | ndarray

The inverse of get_rniirs(), this determines the information density which yields the given RNIIRS.

New in version 1.2.35.

Parameters:

rniirs (float|numpy.ndarray) –

Return type:

float|numpy.ndarray

sarpy.processing.sicd.rgiqe.snr_to_rniirs(bandwidth_area: float | ndarray, signal: float | ndarray, noise: float | ndarray) → Tuple[float | ndarray, float | ndarray]

Calculate the information_density and RNIIRS estimate from bandwidth area and signal/noise estimates.

It is assumed that geometric effects for signal and noise have been accounted for (i.e. use SigmaZeroSFPoly), and signal and noise have each been averaged to a single pixel value.

This mapping has been empirically determined by fitting Shannon-Hartley channel capacity to RNIIRS for some sample images.

Parameters:

  • bandwidth_area (float) –

  • signal (float) –

  • noise (float) –

Returns:

  • information_density (float)

  • rniirs (float)

sarpy.processing.sicd.rgiqe.rgiqe(sicd: SICDType) → Tuple[float, float]

Calculate the information_density and (default) estimated RNIIRS for the given sicd.

Parameters:

sicd (SICDType) –

Returns:

  • information_density (float)

  • rniirs (float)

sarpy.processing.sicd.rgiqe.populate_rniirs_for_sicd(sicd: SICDType, signal: float | None = None, noise: float | None = None, override: bool = False) → None

This populates the value(s) for RNIIRS and information density in the SICD structure, according to the RGIQE. This modifies the sicd structure in place.

Parameters:

  • sicd (sarpy.io.complex.sicd_elements.SICD.SICDType) –

  • signal (None|float) – The signal value, in sigma zero.

  • noise (None|float) – The noise equivalent sigma zero value.

  • override (bool) – Override the value, if present.

sarpy.processing.sicd.rgiqe.get_bandwidth_noise_distribution(sicd: SICDType, alpha: float | ndarray, desired_information_density: float | None = None, desired_rniirs: float | None = None) → Tuple[Tuple[float, float] | ndarray, float | ndarray]

This function determines SICD degradation parameters (nominally symmetric in row/column subaperture degradation) to achieve the desired information density/rniirs.

There is natural one parameter distribution of reducing bandwidth and adding noise to achieve the desired RNIIRS/information density, based on \(\alpha \in [0, 1]\).

The nominal relation is

\[desired\_information\_density = bandwidth\_area*(bw\_mult(\alpha))^2)\cdot\log_2\left( 1 + signal/(noise*noise\_mult(\alpha))\right).\]

For \(\alpha=0\), we add no additional noise (\(bw\_mult(0) = bw\_min,noise\_mult(0)=1\)) and use purely sub-aperture degradation, achieved at

\[desired\_information\_density = bandwidth\_area*(bw\_min)^2)\cdot\log_2(1 + snr).\]

On the other end, at \(\alpha=1\), we have \(bw\_mult(1)=1, noise\_mult(1)=noise\_mult\_max\) and derive the noise multiplier which fulfills the required information density. For intermediate \(0 < \alpha < 1\), we find

\[bw_mult(\alpha) = bw\_min\cdot (1-\alpha)\]

Then, we find \(noise\_multiplier(\alpha)\) which fulfills the required information density.

Note

Choosing subaperture windows is fundamentally a discrete operation, and this carries over to the realities of choosing bandwidth multipliers. See get_bidirectional_bandwidth_multiplier_possibilities() for all feasible values for bandwidth multipliers and associated noise adjustment details.

Refined in version 1.2.35.

Parameters:
Returns:

  • bandwidth_multiplier ((float, float)|numpy.ndarray) – The (row, column) bandwidth multiplier including the discrete nature of this aperture, so the two may not be precisely equal.

  • noise_multiplier (float|numpy.ndarray) – The noise multiplier, indicating how much noise to add before the subaperture processing.

sarpy.processing.sicd.rgiqe.get_dimension_bandwidth_multiplier_possibilities(sicd: SICDType, dimension: int) → Tuple[ndarray, ndarray]

Gets the bandwidth possibilities for all centered subapertures along the given dimension.

Introduced in 1.2.35

Parameters:

  • sicd (SICDType) –

  • dimension (int) – One of {0, 1}.

Returns:

  • aperture_size (numpy.ndarray) – Of shape (N, )

  • bandwidth_multiplier (numpy.ndarray) – Of shape (N, )

sarpy.processing.sicd.rgiqe.get_bidirectional_bandwidth_multiplier_possibilities(sicd: SICDType) → Tuple[ndarray, ndarray]

Gets the bandwidth possibilities for all centered subapertures shrinking along both dimensions symmetrically.

Introduced in 1.2.35

Parameters:

sicd (SICDType) –

Returns:

  • aperture_size (numpy.ndarray) – An array of shape (N, 2) for row/column separately.

  • bandwidth_multiplier (numpy.ndarray) – An array of shape (N, 2) for row/column separately.

sarpy.processing.sicd.rgiqe.quality_degrade(reader: str | SICDTypeReader, index: int = 0, output_file: str | None = None, desired_resolution: Tuple[float, float] | None = None, desired_bandwidth: Tuple[float, float] | None = None, desired_nesz: float | None = None, **kwargs) → FlatSICDReader | None

Create a degraded quality SICD based on the desired resolution (impulse response width) or bandwidth (impulse response bandwidth), and the desired Noise Equivalent Sigma Zero value. The produced SICD will have uniform weighting.

No more than one of desired_resolution and desired_bandwidth can be provided. If None of desired_resolution, desired_bandwidth, or desired_nesz are provided, then the SICD will be re-weighted with uniform weighting - even this will change the noise and RNIIRS values slightly.

Warning

Unless desired_nesz=None, this will fail for a SICD which is not fully Radiometrically calibrated with ‘ABSOLUTE’ noise type.

Parameters:

  • reader (str|SICDTypeReader) –

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

  • 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.

  • desired_resolution (None|tuple) – The desired ImpRespWid (Row, Col) tuple, which will be mapped to ImpRespBW assuming uniform weighting. You cannot provide both desired_resolution and desired_bandwidth.

  • desired_bandwidth (None|tuple) – The desired ImpRespBW (Row, Col) tuple. You cannot provide both desired_resolution and desired_bandwidth.

  • desired_nesz (None|float) – The desired Noise Equivalent Sigma Zero value in power units, this is after modifications which change the noise due to sub-aperture degradation and/or de-weighting.

  • kwargs – Keyword arguments passed through to sarpy.processing.sicd.normalize_sicd.sicd_degrade_reweight()

Returns:

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

Return type:

None|FlatSICDReader

sarpy.processing.sicd.rgiqe.quality_degrade_resolution(reader: str | SICDTypeReader, index: int = 0, output_file: str | None = None, desired_resolution: Tuple[float, float] | None = None, desired_bandwidth: Tuple[float, float] | None = None, **kwargs) → FlatSICDReader | None

Create a degraded quality SICD based on INCREASING the impulse response width to the desired resolution or DECREASING the impulse response bandwidth to the desired bandwidth.

The produced SICD will have uniform weighting.

Parameters:

  • reader (str|SICDTypeReader) –

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

  • 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.

  • desired_resolution (None|tuple) – The desired ImpRespWid (Row, Col) tuple, which will be mapped to ImpRespBW assuming uniform weighting. Exactly one of desired_resolution and desired_bandwidth must be provided.

  • desired_bandwidth (None|tuple) – The desired ImpRespBW (Row, Col) tuple. Exactly one of desired_resolution and desired_bandwidth must be provided.

  • kwargs – Keyword arguments passed through to sarpy.processing.sicd.normalize_sicd.sicd_degrade_reweight()

Returns:

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

Return type:

None|FlatSICDReader

sarpy.processing.sicd.rgiqe.quality_degrade_noise(reader: str | SICDTypeReader, index: int = 0, output_file: str | None = None, desired_nesz: float | None = None, **kwargs) → FlatSICDReader | None

Create a degraded quality SICD based on INCREASING the noise to the desired Noise Equivalent Sigma Zero value. The produced SICD will have uniform weighting.

Warning

This will fail for a SICD which is not fully Radiometrically calibrated, with ABSOLUTE noise type.

Parameters:

  • reader (str|SICDTypeReader) –

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

  • 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.

  • desired_nesz (None|float) – The desired noise equivalent sigma zero value.

  • kwargs – Keyword arguments passed through to sarpy.processing.sicd.normalize_sicd.sicd_degrade_reweight()

Returns:

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

Return type:

None|FlatSICDReader

sarpy.processing.sicd.rgiqe.quality_degrade_rniirs(reader: str | SICDTypeReader, index: int = 0, output_file: str | None = None, desired_rniirs: float | None = None, alpha: float = 0, **kwargs) → FlatSICDReader | None

Create a degraded quality SICD based on the desired estimated RNIIRS value. The produced SICD will have uniform weighting.

The sicd degradation will be performed as follows:

  • The current information density/current rniirs with respect to uniform weighting will be found.

  • The information density required to produce the desired rniirs will be found.

  • This will be used, along with the \(\alpha\) value, will be used in get_bandwidth_noise_distribution() to determine the best feasible multipliers for bandwidth and noise values.

  • These desired bandwidth and noise values will then be used in conjunction with sicd_degrade_reweight().

Warning

This will fail for a SICD which is not fully Radiometrically calibrated, with ‘ABSOLUTE’ noise type.

Parameters:

  • reader (str|SICDTypeReader) –

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

  • 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.

  • desired_rniirs (None|float) – The desired rniirs value, according to the RGIQE methodology.

  • alpha (float) – This must be a number in the interval [0, 1] defining the (geometric) distribution of variability between required influence from increasing noise and require influence of decreasing bandwidth.

  • kwargs – Keyword arguments passed through to sarpy.processing.sicd.normalize_sicd.sicd_degrade_reweight()

Returns:

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

Return type:

None|FlatSICDReader