DetectorOTFPerturber

class nrtk.impls.perturb_image.pybsm.detector_otf_perturber.DetectorOTFPerturber(sensor: PybsmSensor | None = None, scenario: PybsmScenario | None = None, w_x: float | None = None, w_y: float | None = None, f: float | None = None, interp: bool = True, box_alignment_mode: str = 'extent')

Implements OTF-based image perturbation using detector specifications and atmospheric conditions.

The DetectorOTFPerturber class uses sensor and scenario configurations to apply realistic perturbations to images. This includes adjusting for detector width, focal length, and atmospheric conditions using OpenCV and pyBSM functionalities.

Attributes:

sensor (PybsmSensor | None): The sensor configuration used to define perturbation parameters. scenario (PybsmScenario | None): Scenario configuration providing environmental context. w_x (float | None): Detector width in the x direction (meters). w_y (float | None): Detector width in the y direction (meters). f (float | None): Focal length of the detector (meters). interp (bool): Indicates whether atmospheric database should use interpolation.

Methods

from_config	Instantiates a DetectorOTFPerturber from a configuration dictionary.
get_config	Returns the current configuration of the DetectorOTFPerturber instance.
get_default_config	Provides the default configuration for DetectorOTFPerturber 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 the OTF-based perturbation to the provided image.

__init__(sensor: PybsmSensor | None = None, scenario: PybsmScenario | None = None, w_x: float | None = None, w_y: float | None = None, f: float | None = None, interp: bool = True, box_alignment_mode: str = 'extent') → None

Initializes the DetectorOTFPerturber.

Parameters:

• sensor – pyBSM sensor object.

• scenario – pyBSM scenario object.

• w_x – Detector width in the x direction (m).

• w_y – Detector width in the y direction (m).

• f – Focal length (m).

• 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 a value is provided for w_x, w_y and/or f that value(s) will be used in the otf calculation.

If both sensor and scenario parameters are provided, but not w_x, w_y and/or f, the value(s) of w_x, w_y and/or f will come from the sensor and scenario objects.

If either sensor or scenario parameters are absent, default values will be used for both sensor and scenario parameters (except for w_x/w_y/f, as defined below).

If any of w_x, w_y, or f are absent and sensor/scenario objects are also absent, the absent value(s) will default to 4um for w_x/w_y and 50mm for f

Raises:

ImportError if OpenCV or pyBSM is not found,

install via pip install nrtk[pybsm,graphics] or pip install nrtk[pybsm,headless].

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

Instantiates a DetectorOTFPerturber 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 DetectorOTFPerturber configured according to config_dict.

get_config() → dict[str, Any]

Returns the current configuration of the DetectorOTFPerturber instance.

Returns:

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

classmethod get_default_config() → dict[str, Any]

Provides the default configuration for DetectorOTFPerturber 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 the OTF-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 present in additional_params.