TurbulenceApertureOTFPerturber

class nrtk.impls.perturb_image.pybsm.turbulence_aperture_otf_perturber.TurbulenceApertureOTFPerturber(sensor: PybsmSensor | None = None, scenario: PybsmScenario | None = None, mtf_wavelengths: Sequence[float] | None = None, mtf_weights: Sequence[float] | None = None, altitude: float | None = None, slant_range: float | None = None, D: float | None = None, ha_wind_speed: float | None = None, cn2_at_1m: float | None = None, int_time: float | None = None, n_tdi: float | None = None, aircraft_speed: float | None = None, interp: bool = True, box_alignment_mode: str = 'extent')

Implements OTF-based image perturbation with turbulence and aperture effects.

The TurbulenceApertureOTFPerturber class simulates image degradation due to atmospheric turbulence and optical aperture effects, using pyBSM sensor and scenario configurations. It supports adjustable wavelengths, weights, and other environmental parameters for realistic perturbations.

Attributes:: sensor (PybsmSensor | None): Sensor configuration for the perturbation. scenario (PybsmScenario | None): Scenario settings applied during perturbation. mtf_wavelengths (Sequence[float]): Wavelengths used in MTF calculations. mtf_weights (Sequence[float]): Weights associated with each wavelength. altitude (float): Altitude of the imaging platform. slant_range (float): Line-of-sight distance between platform and target. D (float): Effective aperture diameter. ha_wind_speed (float): High-altitude wind speed affecting turbulence profile. cn2_at_1m (float): Refractive index structure parameter at ground level. int_time (float): Integration time for imaging. n_tdi (float): Number of time-delay integration stages. aircraft_speed (float): Apparent atmospheric velocity. interp (bool): Indicates whether to use interpolated atmospheric data.

Methods

`from_config`	Instantiates a TurbulenceApertureOTFPerturber from a configuration dictionary.
`get_config`	Returns the current configuration of the TurbulenceApertureOTFPerturber instance.
`get_default_config`	Provides the default configuration for TurbulenceApertureOTFPerturber instances.
`get_impls`	Discover and return a set of classes that implement the calling class.
`get_type_string`	Returns the fully qualified type string of the PerturbImage class or its subclass.
`is_usable`	Checks if the necessary dependencies (pyBSM and OpenCV) are available.
`perturb`	Applies turbulence and aperture-based perturbation to the provided image.

Initializes the TurbulenceApertureOTFPerturber.

Parameters:

sensor – pyBSM sensor object
scenario – pyBSM scenario object
mtf_wavelengths – a sequence of wavelengths (m)
mtf_weights – a sequence of weights for each wavelength contribution (arb)
altitude – height of the aircraft above the ground (m)
slant_range – line-of-sight range between the aircraft and target (target is assumed to be on the ground) (m)
D – effective aperture diameter (m)
ha_wind_speed – the high altitude windspeed (m/s); used to calculate the turbulence profile
cn2_at_1m – the refractive index structure parameter “near the ground” (e.g. at h = 1 m); used to calculate the turbulence profile
int_time – dwell (i.e. integration) time (seconds)
n_tdi – the number of time-delay integration stages (relevant only when TDI cameras are used. For CMOS cameras, the value can be assumed to be 1.0)
aircraft_speed – apparent atmospheric velocity (m/s); this can just be the windspeed at the sensor position if the sensor is stationary
interp – a boolean determining whether load_database_atmosphere is used with or without interpolation
box_alignment_mode –
Mode for how to handle how bounding boxes change. Should be one of the following options:

extent: a new axis-aligned bounding box that encases the transformed misaligned box extant: a new axis-aligned bounding box that is encased inside the transformed misaligned box median: median between extent and extant

Default value is extent

If both sensor and scenario parameters are absent, then default values will be used for their parameters.

If any of the individual or sensor/scenario parameters are absent, the following values will be set as defaults for the absent values:

mtf_wavelengths = [0.50e-6, 0.66e-6] mtf_weights = [1.0, 1.0] altitude = 250 slant_range = 250 # slant_range = altitude D = 40e-3 #m ha_wind_speed = 0 cn2_at_1m = 1.7e-14 int_time = 30e-3 #s n_tdi = 1.0 aircraft_speed = 0

If sensor and scenario parameters are provided, but not the other individial parameters, the values will come from the sensor and scenario objects.

If individial parameter values are provided by the user, those values will be used in the otf calculation.

Raises:: ImportError if OpenCV is not found,

install via pip install nrtk[graphics] or pip install nrtk[headless]. :raises: ValueError if mtf_wavelengths and mtf_weights are not equal length :raises: ValueError if mtf_wavelengths is empty or mtf_weights is empty :raises: ValueError if cn2at1m <= 0.0

classmethod from_config(config_dict: dict, merge_default: bool = True) → TurbulenceApertureOTFPerturber

Instantiates a TurbulenceApertureOTFPerturber from a configuration dictionary.

Args:: config_dict (dict): Configuration dictionary with initialization parameters. merge_default (bool, optional): Whether to merge with default configuration. Defaults to True.
Returns:: C: An instance of TurbulenceApertureOTFPerturber configured according to config_dict.

get_config() → dict[str, Any]

Returns the current configuration of the TurbulenceApertureOTFPerturber instance.

Returns:: dict[str, Any]: Configuration dictionary with current settings.

classmethod get_default_config() → dict[str, Any]

Provides the default configuration for TurbulenceApertureOTFPerturber instances.

Returns:: dict[str, Any]: A dictionary with the default configuration values.

classmethod is_usable() → bool

Checks if the necessary dependencies (pyBSM and OpenCV) are available.

Returns:: bool: True if both pyBSM and OpenCV are available; False otherwise.

perturb(image: ndarray, boxes: Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None = None, additional_params: dict[str, Any] | None = None) → tuple[ndarray, Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None]

Applies turbulence and aperture-based perturbation to the provided image.

Args:

image (np.ndarray): The image to be perturbed. boxes (Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]], optional): bounding boxes

for detections in input image

additional_params (dict[str, Any], optional): Additional parameters, including ‘img_gsd’.

Returns:

np.ndarray: The perturbed image. Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]]: unmodified bounding boxes

for detections in input image

Raises:

ValueError: If ‘img_gsd’ is not provided in additional_params.