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)

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.

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

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	Retrieves 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 detector 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) → None

Initializes the DetectorOTFPerturber.

Args:

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.

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:

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

Instantiates a DetectorOTFPerturber 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 DetectorOTFPerturber:

An instance of DetectorOTFPerturber.

get_config() → dict[str, Any]

Returns the current configuration of the DetectorOTFPerturber instance.

Returns:

return dict[str, Any]:

Configuration dictionary with current settings.

classmethod get_default_config() → dict[str, Any]

Retrieves the default configuration for DetectorOTFPerturber 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 the detector OTF-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.