PybsmPerturber

class nrtk.impls.perturb_image.optical.PybsmPerturber(*, reflectance_range: ndarray[Any, Any] = array([0.05, 0.5]), seed: int | None = None, is_static: bool = False, sensor_name: str = 'Sensor', D: float = 0.275, f: float = 4, p_x: float = 8e-06, p_y: float | None = None, opt_trans_wavelengths: ndarray[Any, Any] = array([5.0e-07, 6.6e-07]), optics_transmission: ndarray[Any, Any] | None = None, eta: float = 0.0, w_x: float | None = None, w_y: float | None = None, int_time: float = 1.0, n_tdi: float = 1.0, dark_current: float = 0.0, read_noise: float = 0.0, max_n: int = 100000000, bit_depth: float = 100.0, max_well_fill: float = 1.0, s_x: float = 0.0, s_y: float = 0.0, qe_wavelengths: ndarray[Any, Any] | None = None, qe: ndarray[Any, Any] | None = None, scenario_name: str = 'Scenario', ihaze: int = 1, altitude: float = 9000, ground_range: float = 0, aircraft_speed: float = 0.0, target_reflectance: float = 0.15, target_temperature: float = 295.0, background_reflectance: float = 0.07, background_temperature: float = 293.0, ha_wind_speed: float = 21.0, cn2_at_1m: float = 1.7e-14, interp: bool = True)

Implements image perturbation using pyBSM sensor and scenario configurations.

The PybsmPerturber class applies realistic perturbations to images by leveraging pyBSM’s simulation functionalities. It takes in a sensor and scenario, along with other optional parameters, to simulate environmental effects on the image.

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

Attributes:

reflectance_range (np.ndarray):

Default reflectance range for image simulation.

seed (int | None):

Random seed for reproducibility. None for non-deterministic behavior.

is_static (bool):

If True, recreates simulator after each call for consistent results.

Methods

from_config	Instantiate a new instance of this class given the configuration JSON-compliant dictionary encapsulating initialization arguments.
get_config	Get current configuration including perturber-specific parameters.
get_default_config	Retrieves the default configuration for PybsmPerturber instances.
get_impls	Discover plugins, skipping any entrypoints that fail to load.
get_type_string	Returns the fully qualified type string of the PerturbImage class or its subclass.
is_usable	Check whether this class is available for use.
perturb	Apply the OTF-based perturbation to the provided image.

__init__(*, reflectance_range: ndarray[Any, Any] = array([0.05, 0.5]), seed: int | None = None, is_static: bool = False, sensor_name: str = 'Sensor', D: float = 0.275, f: float = 4, p_x: float = 8e-06, p_y: float | None = None, opt_trans_wavelengths: ndarray[Any, Any] = array([5.0e-07, 6.6e-07]), optics_transmission: ndarray[Any, Any] | None = None, eta: float = 0.0, w_x: float | None = None, w_y: float | None = None, int_time: float = 1.0, n_tdi: float = 1.0, dark_current: float = 0.0, read_noise: float = 0.0, max_n: int = 100000000, bit_depth: float = 100.0, max_well_fill: float = 1.0, s_x: float = 0.0, s_y: float = 0.0, qe_wavelengths: ndarray[Any, Any] | None = None, qe: ndarray[Any, Any] | None = None, scenario_name: str = 'Scenario', ihaze: int = 1, altitude: float = 9000, ground_range: float = 0, aircraft_speed: float = 0.0, target_reflectance: float = 0.15, target_temperature: float = 295.0, background_reflectance: float = 0.07, background_temperature: float = 293.0, ha_wind_speed: float = 21.0, cn2_at_1m: float = 1.7e-14, interp: bool = True) → None

Initializes the PybsmPerturber.

Args:

reflectance_range:

Array of reflectances that correspond to pixel values.

seed:

Random seed for reproducible results. Defaults to None for non-deterministic behavior.

is_static:

If True and seed is provided, recreates simulator after each perturb call for consistent results across multiple calls (useful for video frame processing).

sensor_name:

name of the sensor

D:

effective aperture diameter (m)

f:

focal length (m)

p_x:

detector center-to-center spacings (pitch) in the x and y directions (meters); if p_y is not provided, it is assumed equal to p_x

opt_trans_wavelengths:

specifies the spectral bandpass of the camera (m); at minimum, specify a start and end wavelength

optics_transmission:

full system in-band optical transmission (unitless); do not include loss due to any telescope obscuration in this optical transmission array

eta:

relative linear obscuration (unitless); obscuration of the aperture commonly occurs within telescopes due to secondary mirror or spider supports

p_y:

detector center-to-center spacings (pitch) in the x and y directions (meters); if p_y is not provided, it is assumed equal to p_x

w_x:

detector width in the x and y directions (m); if set equal to p_x and p_y, this corresponds to an assumed full pixel fill factor. In general, w_x and w_y are less than p_x and p_y due to non-photo-sensitive area (typically transistors) around each pixel.

w_y:

detector width in the x and y directions (m); if set equal to p_x and p_y, this corresponds to an assumed full pixel fill factor. In general, w_x and w_y are less than p_x and p_y due to non-photo-sensitive area (typically transistors) around each pixel.

int_time:

maximum integration time (s)

qe:

quantum efficiency as a function of wavelength (e-/photon)

qe_wavelengths:

wavelengths corresponding to the array qe (m)

dark_current:

detector dark current (e-/s); dark current is the relatively small electric current that flows through photosensitive devices even when no photons enter the device

read_noise:

amount of noise generated by electronics as the charge present in the pixels

max_n:

detector electron well capacity (e-); the default 100 million initializes to a large number so that, in the absence of better information, it doesn’t affect outcomes

bit_depth:

resolution of the detector ADC in bits (unitless); default of 100 is a sufficiently large number so that in the absence of better information, it doesn’t affect outcomes

n_tdi:

number of TDI stages (unitless)

max_well_fill:

maximum amount of charge an individual pixel can hold before it becomes saturated

s_x:

root-mean-squared jitter amplitudes in the x direction (rad)

s_y:

root-mean-squared jitter amplitudes in the y direction (rad)

scenario_name:

name of the scenario

ihaze:

MODTRAN code for visibility, valid options are ihaze = 1 (Rural extinction with 23 km visibility) or ihaze = 2 (Rural extinction with 5 km visibility)

altitude:

sensor height above ground level in meters; the database includes the following altitude options: 2 32.55 75 150 225 500 meters, 1000 to 12000 in 1000 meter steps, and 14000 to 20000 in 2000 meter steps, 24500

ground_range:

projection of line of sight between the camera and target along on the ground in meters; the distance between the target and the camera is given by sqrt(altitude^2 + ground_range^2). The following ground ranges are included in the database at each altitude until the ground range exceeds the distance to the spherical earth horizon: 0 100 500 1000 to 20000 in 1000 meter steps, 22000 to 80000 in 2000 m steps, and 85000 to 300000 in 5000 meter steps.

aircraft_speed:

ground speed of the aircraft (m/s)

target_reflectance:

object reflectance (unitless); the default 0.15 is the giqe standard

target_temperature:

object temperature (Kelvin); 282 K is used for GIQE calculation

background_reflectance:

background reflectance (unitless)

background_temperature:

background temperature (Kelvin); 280 K used for GIQE calculation

ha_wind_speed:

the high altitude wind speed (m/s) used to calculate the turbulence profile; the default, 21.0, is the HV 5/7 profile value

cn2_at_1m:

the refractive index structure parameter “near the ground” (e.g. at h = 1 m) used to calculate the turbulence profile; the default, 1.7e-14, is the HV 5/7 profile value

interp:

A flag to indicate whether atmospheric interpolation should be used. Defaults to False.

Raises:

ValueError:

If reflectance_range length != 2

ValueError:

If reflectance_range not strictly ascending

__repr__() → str

Returns a representation of the perturber including sensor and scenario names.

__str__() → str

Returns a string representation combining sensor and scenario names.

get_config() → dict[str, Any]

Get current configuration including perturber-specific parameters.

classmethod get_default_config() → dict[str, Any]

Retrieves the default configuration for PybsmPerturber instances.