JitterOTFPerturber

class nrtk.impls.perturb_image.pybsm.jitter_otf_perturber.JitterOTFPerturber(sensor: PybsmSensor | None = None, scenario: PybsmScenario | None = None, s_x: float | None = None, s_y: float | None = None, interp: bool = True)

Implements image perturbation using jitter and Optical Transfer Function (OTF).

This class applies realistic perturbations to images based on sensor and scenario configurations, leveraging Optical Transfer Function (OTF) modeling through the pyBSM library. Perturbations include jitter effects that simulate real-world distortions in optical imaging systems.

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 for perturbations.

additional_params (dict):

Additional configuration options for customizing perturbations.

Methods:

perturb(image):

Applies the jitter-based OTF perturbation to the provided image.

get_config():

Returns the configuration for the current instance.

from_config(config_dict):

Instantiates from a configuration dictionary.

Methods

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

__init__(sensor: PybsmSensor | None = None, scenario: PybsmScenario | None = None, s_x: float | None = None, s_y: float | None = None, interp: bool = True) → None

Initializes the JitterOTFPerturber.

Args:

sensor:

pyBSM sensor object.

scenario:

pyBSM scenario object

s_x:

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

s_y:

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

interp:

a boolean determining whether load_database_atmosphere is used with or without interpolation.

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

If neither s_x, s_y, sensor or scenario parameters are provided, the values of s_x and s_y will be the default of 0.0 as that results in a nadir view.

If sensor and scenario parameters are provided, but not s_x and s_y, the values of s_x and s_y will come from the sensor and scenario objects.

If s_x and s_y are ever provided by the user, those values will be used in the otf calculation.

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

An instance of JitterOTFPerturber.

get_config() → dict[str, Any]

Returns the current configuration of the JitterOTFPerturber instance.

Returns:

return dict[str, Any]:

Configuration dictionary with current settings.

classmethod get_default_config() → dict[str, Any]

Retrieves the default configuration for JitterOTFPerturber 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 jitter 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.