Detection Interfaces

Here we list and briefly describe the high level algorithm interfaces which SMQTK-Detection provides. Some implementations will require additional dependencies that cannot be packaged with SMQTK-Detection.

Detection Element

Data structure used by detector interfaces to communicate inference predictions.

class smqtk_detection.interfaces.detection_element.DetectionElement(uuid: Hashable)[source]

Representation of a spatial detection.

classmethod from_config(config_dict: Dict[Any, Any], uuid: Hashable, merge_default: bool = True) → DetectionElement[source]

Override of smqtk.utils.configuration.Configurable.from_config() with the added runtime argument uuid. See parent method documentation for details.

Parameters:

config_dict (dict) – JSON compliant dictionary encapsulating a configuration.
uuid (collections.abc.Hashable) – UUID to assign to the produced DetectionElement.
merge_default (bool) – Merge the given configuration on top of the default provided by get_default_config.

Returns:

Constructed instance from the provided config.

Return type:

DetectionElement

abstract get_bbox() → AxisAlignedBoundingBox | None[source]

Returns:: The spatial bounding box of this detection.
Return type:: smqtk.representation.AxisAlignedBoundingBox
Raises:: NoDetectionError – No detection AxisAlignedBoundingBox set yet.

abstract get_classification() → ClassificationElement | None[source]

Returns:: The classification element of this detection.
Return type:: smqtk.representation.ClassificationElement
Raises:: NoDetectionError – No detection ClassificationElement set yet or the element is empty.

classmethod get_default_config() → Dict[str, Any][source]

Generate and return a default configuration dictionary for this class. This will be primarily used for generating what the configuration dictionary would look like for this class without instantiating it.

By default, we observe what this class’s constructor takes as arguments, turning those argument names into configuration dictionary keys. If any of those arguments have defaults, we will add those values into the configuration dictionary appropriately. The dictionary returned should only contain JSON compliant value types.

It is not be guaranteed that the configuration dictionary returned from this method is valid for construction of an instance of this class.

Returns:: Default configuration dictionary for the class.
Return type:: dict

>>> # noinspection PyUnresolvedReferences
>>> class SimpleConfig(Configurable):
...     def __init__(self, a=1, b='foo'):
...         self.a = a
...         self.b = b
...     def get_config(self):
...         return {'a': self.a, 'b': self.b}
>>> self = SimpleConfig()
>>> config = self.get_default_config()
>>> assert config == {'a': 1, 'b': 'foo'}

abstract get_detection() → Tuple[AxisAlignedBoundingBox, ClassificationElement][source]

Returns:: The paired spatial bounding box and classification element of this detection.
Return type:: (smqtk.representation.AxisAlignedBoundingBox, smqtk.representation.ClassificationElement)
Raises:: NoDetectionError – No detection AxisAlignedBoundingBox and ClassificationElement set yet.

abstract has_detection() → bool[source]

Returns:: Whether or not this container currently contains a valid detection bounding box and classification element (must be non-zero).
Return type:: bool

abstract set_detection(bbox: AxisAlignedBoundingBox, classification_element: ClassificationElement) → DetectionElement[source]

Set a bounding box and classification element to this detection element.

Parameters:

bbox (smqtk.representation.AxisAlignedBoundingBox) – Spatial bounding box instance.
classification_element (smqtk.representation.ClassificationElement) – The classification of this detection.

Raises:

ValueError – No, or invalid, AxisAlignedBoundingBox or ClassificationElement was provided.

Returns:

Self

Return type:

DetectionElement

ObjectDetector

This interface defines a method to generate object detections (smqtk_detection.interfaces.detection_element.DetectionElement) over a given smqtk_dataprovider.interfaces.data_element.DataElement.

class smqtk_detection.interfaces.object_detector.ObjectDetector[source]

Abstract interface to an object detection algorithm.

An object detection algorithm is one that can take in data and output zero or more detection elements, where each detection represents a spatial region in the data.

This high level interface only requires detection element returns (spatial bounding-boxes with associated classification elements).

detect_objects(data_element: ~smqtk_dataprovider.interfaces.data_element.DataElement, de_factory: ~smqtk_detection.detection_element_factory.DetectionElementFactory = <smqtk_detection.detection_element_factory.DetectionElementFactory object>, ce_factory: ~smqtk_classifier.classification_element_factory.ClassificationElementFactory = <smqtk_classifier.classification_element_factory.ClassificationElementFactory object>) → Iterator[DetectionElement] | None[source]

Detect objects in the given data.

UUIDs of detections are based on the hash produced from the combination of:

Detection bounding-box bounding coordinates
Classification label set predicted for a bounding box.

Parameters:

data_element (smqtk.representation.DataElement) – Source data from which to detect objects within.
de_factory (smqtk.representation.DetectionElementFactory) – Factory for generating DetectionElement instances. The default factory yields MemoryClassificationElement instances.
ce_factory (smqtk.representation.ClassificationElementFactory) – Factory for generating ClassificationElement instances for detections. The default factory yields MemoryClassificationElement instances.

Raises:

ValueError – Given data element content was not of a valid content type that this class reports as valid for object detection.

Returns:

Iterator over result DetectionElement instances as generated by the given DetectionElementFactory, containing classification elements as generated by the given ClassificationElementFactory.

Return type:

collections.abc.Iterable[smqtk.representation.DetectionElement]

ImageMatrixObjectDetector

class smqtk_detection.interfaces.object_detector.ImageMatrixObjectDetector(image_reader: ImageReader)[source]

Class of object detectors that operate over the pixel matrix of an image.

This sub abstract class standardizes the use of an smqtk.algorithms.ImageReader algorithm to read an image file’s pixels as well as determine which image formats are valid input elements. There is a special exception of MatrixDataElement types as they directly provide a matrix.

We define an alternate abstract method for implementing classes to define: _detect_objects_matrix. This method is given a numpy ndarray instance for the implementing class to utilize. The return requirements are the same as the _detect_objects method.

classmethod from_config(config_dict: dict, merge_default: bool = True) → ImMatObDet[source]

Instantiate a new instance of this class given the configuration JSON-compliant dictionary encapsulating initialization arguments.

This method should not be called via super unless an instance of the class is desired.

Parameters:

config_dict (dict) – JSON compliant dictionary encapsulating a configuration.
merge_default (bool) – Merge the given configuration on top of the default provided by get_default_config.

Returns:

Constructed instance from the provided config.

Return type:

ImageMatrixObjectDetector

abstract get_config() → dict[source]

Return a JSON-compliant dictionary that could be passed to this class’s from_config method to produce an instance with identical configuration.

In the most cases, this involves naming the keys of the dictionary based on the initialization argument names as if it were to be passed to the constructor via dictionary expansion. In some cases, where it doesn’t make sense to store some object constructor parameters are expected to be supplied at as configuration values (i.e. must be supplied at runtime), this method’s returned dictionary may leave those parameters out. In such cases, the object’s from_config class-method would also take additional positional arguments to fill in for the parameters that this returned configuration lacks.

Returns:: JSON type compliant configuration dictionary.
Return type:: dict

classmethod get_default_config() → dict[source]

Generate and return a default configuration dictionary for this class. This will be primarily used for generating what the configuration dictionary would look like for this class without instantiating it.

By default, we observe what this class’s constructor takes as arguments, turning those argument names into configuration dictionary keys. If any of those arguments have defaults, we will add those values into the configuration dictionary appropriately. The dictionary returned should only contain JSON compliant value types.

It is not be guaranteed that the configuration dictionary returned from this method is valid for construction of an instance of this class.

Returns:: Default configuration dictionary for the class.
Return type:: dict

is_valid_element(data_element: DataElement) → bool[source]

Check if the given DataElement instance reports a content type that matches one of the MIME types reported by valid_content_types.

This override uses our stored ImageReader algorithm instance to define what DataElement instances are valid.

Parameters:: data_element (smqtk.representation.DataElement) – Data element instance to check.
Returns:: True if the given element has a valid content type as reported by valid_content_types, and False if not.
Return type:: bool

valid_content_types() → Set[str][source]

Returns:: A set valid MIME types that are “valid” within the implementing class’ context.
Return type:: set[str]

DetectImageObjects

class smqtk_detection.interfaces.detect_image_objects.DetectImageObjects[source]

Algorithm that generates object bounding boxes and classification maps for a set of input image matricies as numpy.ndarray type arrays.

abstract detect_objects(img_iter: Iterable[ndarray]) → Iterable[Iterable[Tuple[AxisAlignedBoundingBox, Dict[Hashable, float]]]][source]

Generate paired bounding boxes and classification maps for detected objects in the given set of images.

Parameters:: img_iter – Iterable of input images as numpy arrays.
Returns:: Iterable of sets of paired bounding boxes and classification maps. Each set is the collection of detections for the corresponding input image.