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)

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.

See https://pybsm.readthedocs.io/en/latest/explanation.html for image formation concepts and parameter details.

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

__init__(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) → None

Initializes the TurbulenceApertureOTFPerturber.

Args:

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

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:

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[str, Any], merge_default: bool = True) → Self

Instantiates a TurbulenceApertureOTFPerturber from a configuration dictionary.

Args:

config_dict:

Configuration dictionary with initialization parameters.

merge_default:

Whether to merge with default configuration. Defaults to True.

Returns:

return TurbulenceApertureOTFPerturber:

An instance of TurbulenceApertureOTFPerturber.

get_config() → dict[str, Any]

Returns the current configuration of the TurbulenceApertureOTFPerturber instance.

Returns:

return dict[str, Any]:

Configuration dictionary with current settings.

classmethod get_default_config() → dict[str, Any]

Retrieves the default configuration for TurbulenceApertureOTFPerturber instances.

Returns:

return 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:

return bool:

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

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

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

Args:

image:

The image to be perturbed.

boxes:

Bounding boxes for detections in input image.

additional_params:

Dictionary containing:

• “img_gsd” (float): GSD is the distance between the centers of two adjacent

  pixels in an image, measured on the ground.

Returns:

return tuple[np.ndarray, Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None]:

The perturbed image and bounding boxes scaled to perturbed image shape.

Raises:

raises ValueError:

If ‘img_gsd’ is not provided in additional_params.