Interfaces

The NRTK API consists of object-oriented functor interfaces for image perturbation. The PerturbImage interface defines the contract for applying perturbations to images, and the PerturbImageFactory interface defines the contract for easily varying specified parameters of a particular perturber.

These interfaces are based on the plugin and configuration features provided by SMQTK-Core, to allow convenient hooks into implementation, discoverability, and factory generation from runtime configuration. This allows for both opaque discovery of interface implementations from a class-method on the interface class object, as well as instantiation of a concrete instance via a JSON-like configuration fed in from an outside resource.

Figure 1: Abstract Interface Inheritance.

Image Perturbation

Interface: PerturbImage

class nrtk.interfaces.PerturbImage

Algorithm that generates a perturbed image for given input image stimulus as a numpy.ndarray type array.

__call__(*, image: ndarray[Any, Any], boxes: Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None = None, **kwargs: Any) → tuple[ndarray[Any, Any], Iterable[tuple[AxisAlignedBoundingBox, dict[Hashable, float]]] | None]

Calls perturb() with the given input image.

__init__() → None

Initializes the PerturbImage.

get_config() → dict[str, Any]

Returns the current configuration of the PerturbImage instance.

classmethod get_type_string() → str

Returns the fully qualified type string of the PerturbImage class or its subclass.

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

Generate a perturbed image for the given image stimulus.

Note perturbers that resize, rotate, or similarly affect the dimensions of an image may impact scoring if bounding boxes are not similarly transformed.

Args:

image:

Input image as a numpy array.

boxes:

Input bounding boxes as a Iterable of tuples containing bounding boxes. This is the single image output from DetectImageObjects.detect_objects

kwargs:

Implementation-specific keyword arguments.

Returns:

Perturbed image as numpy array, including matching dtype. Implementations should impart no side

effects upon the input image.

Iterable of tuples containing the bounding boxes for detections in the image. If an implementation

modifies the size of an image, it is expected to modify the bounding boxes as well.

Perturbation Factory

Interface: PerturbImageFactory

class nrtk.interfaces.PerturbImageFactory(*, perturber: type[PerturbImage], theta_key: str, perturber_kwargs: dict[str, Any] | None = None)

Factory class for producing PerturbImage instances of a specified type and configuration.

Attributes:

perturber (type[PerturbImage]): python implementation type of the PerturbImage interface to produce theta_key (str): perturber parameter to vary between instances

__getitem__(idx: int) → PerturbImage

Get the perturber for a specific index.

Args:

idx: Index of desired perturber (supports negative indices).

__init__(*, perturber: type[PerturbImage], theta_key: str, perturber_kwargs: dict[str, Any] | None = None) → None

Initialize the factory to produce PerturbImage instances of the given type.

Initialize the factory to produce PerturbImage instances of the given type, varying the given theta_key parameter.

Args:

perturber:

Python implementation type of the PerturbImage interface to produce.

theta_key:

Perturber parameter to vary between instances.

perturber_kwargs:

Default kwargs to be used by the perturber. Defaults to {}.

Raises:

TypeError:

Given a perturber instance instead of type.

__iter__() → Iterator[PerturbImage]

Return an iterator for this factory.

__len__() → int

Return the number of perturber instances this factory will generate.

__next__() → PerturbImage

Return the next perturber instance.

Raises:

StopIteration:

Iterator exhausted.

classmethod from_config(config_dict: dict[str, Any], merge_default: bool = True) → Self

Instantiates a PerturbImageFactory from a configuration dictionary.

Args:

config_dict: Configuration dictionary with parameters for instantiation. merge_default: Whether to merge with default configuration. Defaults to True.

Returns:

An instance of the PerturbImageFactory class.

get_config() → dict[str, Any]

Returns the configuration of the factory instance.

classmethod get_default_config() → dict[str, Any]

Returns the default configuration for the PerturbImageFactory.

This method retrieves a default configuration dictionary, specifying default values for key parameters in the factory. It can be used to create an instance of the factory with preset configurations.

Returns:

dict[str, Any]: A dictionary containing default configuration parameters.

property theta_key: str

Get the perturber parameter to vary between instances.

abstract property thetas: Sequence[Any]

Get the sequence of theta values this factory will iterate over.