Formats

Detectools provide a specific classes to wrap detection data (boxes, masks, labels, etc.) depending on the library task mode (detection or instance segmentation). These classes supports lots a basic transformations (crop, pad, indexation, …) to manage targets and predictions data.

class detectools.formats.Annotation(*args, **kwargs)[source]

Return one of the BaseFormat (DetectionAnnotation or SegmentationAnnotation depending on the Task mode).

Returns:

BaseAnnotation instance.

Return type:

BaseAnnotation

class detectools.formats.BatchedFormats(formats: List[BaseFormat])[source]

BatchedFormats wrap multiple Formats in a batch. BaseFormats should be passed in the same order than the images in images batch.

Parameters:: formats (List[BaseFormat]) – List of BaseFormats to batchify.

Attributes:

formats

All BaseFormats contained in a dict with corresponding images index in keys.

Type:: Dict[str, BaseFormat]

spatial_size

Type:: Tuple[int,int]

Methods:

__weakref__: list of weak references to the object (if defined)

apply(method_name: str, *args, **kwargs)[source]

Apply a function to all formats contained in formats attributes. args and kwargs are the parameters of the function to use.

Parameters:: method_name (str) – BaseFormat method name.

clone() → BatchedFormats[source]

Clone a BatchedFormats instance.

Returns:

Cloned BatchedFormats instance.

Return type:

BatchedFormats

get_attributes(attribute: str, *args, **kwargs) → List[Any][source]

Return a list of Format attribute, one for each Format in BatchedFormats.

Parameters:: attribute (str) – Attribute name.
Returns:: List of attribute values for each Format.
Return type:: List[Any]

set_spatial_size()[source]: Check if all internal Formats have the same spatial_size & set this spatial_size as BatchedFormat spatial_size.

split() → List[BaseFormat][source]

Return list of BaseFormats following the order in formats attribute.

Returns:

List of BaseFormats.

Return type:

List[BaseFormat]

class detectools.formats.DetectionAnnotation(spatial_size: Tuple[int], label: Tensor, boxe: Tensor, score: Tensor | None = None)[source]

BaseAnnotation child class for detection task.

Attributes:

boxe

Boxe coordinates in XYWH format.

Type:: BoundingBoxes

label

Class label of object.

Type:: Tensor

spatial_size

Size of corresponding image (H, W)

Type:: Tuple[int, int]

score

Confidence score of the object (for prediction).

Type:: Tensor

Methods:

object_to_coco(annotation_id: int = 1, image_id: int = 1) → Dict[str, Any][source]

Return detection annotation data as COCO like dict.

Parameters:

annotation_id (int, optional) – Id of the annotation. Defaults to 1.
image_id (int, optional) – Id of the corresponding image. Defaults to 1.

Returns:

COCO like dict with Annotation instance data.

Return type:

Dict[str, Any]

class detectools.formats.DetectionFormat(spatial_size: Tensor, labels: Tensor, boxes: Tensor, scores: Tensor | None = None, box_format: Literal['XYWH', 'XYXY', 'CXCYWH'] = 'XYWH')[source]

BaseFormat child class for detection task.

Parameters:

spatial_size (Tensor) – Spatial size (H, W) of corresponding images.
labels (Tensor) – Tensor of shape (N,) with class labels for each object.
boxes (Tensor) – Tensor of shape (N, 4). N for N objects and 4 for boxes coordinates.
scores (Tensor, optional) – Tensor of shape (N,) with objects confidence score. Defaults to None.
box_format (Literal['XYWH', 'XYXY', 'CXCYWH'], optional) – Format of bounding boxes. Defaults to ‘XYWH’.

Attributes:

box_format

Format of bounding boxes.

Type:: Literal["XYWH", "XYXY", "CXCYWH"]

spatial_size

Size of corresponding image (H, W)

Type:: Tuple[int, int]

size

Number of objects in BaseFormat.

Type:: int

data

(Dict[str, Tensor]): Data dict that contains objects informations in it’s keys (labels, boxes, scores).

Type:: Dict[str, torch.Tensor]

Methods:

__getitem__(indexes: int | Tensor) → DetectionFormat[source]

Return a subset DetectionFormat by keeping only elements of data dict values (tensors) at positions of indexes.

Parameters:

indexes (Union[int, Sequence[int]]) – Indexes to slice objects data.

Returns:

DetectionFormat with n objects for n indexes in indexes.

Return type:

DetectionFormat

crop(top: int, left: int, height: int, width: int)[source]

Crop boxes from top corner pixel and update spatial size.

Parameters:

top (int) – Position to crop from top border.
left (int) – Position to crop from left border.
height (int) – height of the crop.
width (int) – Width of the crop.

empty(device: Literal['cpu', 'cuda'] = 'cpu') → DetectionFormat[source]

Return an empty instance DetectionFormat.

Parameters:

spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.
device (Literal["cpu", "cuda"]) – Device to define format on. Default to “cpu”.

Returns:

DetectionFormat instance.

Return type:

DetectionFormat

from_coco(spatial_size: Tuple[int]) → DetectionFormat[source]

Return DetectionFormat from an image COCO data dictionnary.

Parameters:

coco_annotations (List[Dict[str, Any]]) – Coco data dictionnary.
spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.

Returns:

DetectionFormat instance.

Return type:

DetectionFormat

get_object(indice: int) → DetectionAnnotation[source]

Return DetectionAnnotation object at position indice.

Parameters:

indice (int) – Position of object to gather.

Returns:

DetectionAnnotation instance.

Return type:

DetectionAnnotation

pad(left: int, top: int, right: int, bottom: int)[source]

Pad boxes and update spatial size.

Parameters:

left (int) – Pad value on left border.
top (int) – Pad value on top border.
right (int) – Pad value on right border.
bottom (int) – Pad value on bottom border.

class detectools.formats.Format(*args, **kwargs)[source]

Format class send either to DetectionFormat or SegmentationFormat depending on the Task mode.

Returns:

BaseFormat instance.

Return type:

BaseFormat

Methods

empty() → BaseFormat[source]

Return an empty instance of BaseFormat (DetectionFormat or SegmentationFormat depending on the Task mode).

Parameters:

spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.

Returns:

BaseFormat instance.

Return type:

BaseFormat

from_coco(spatial_size: Tuple[int]) → BaseFormat[source]

Return one of the BaseFormats (DetectionFormat or SegmentationFormat depending on the Task mode) from an image COCO data dictionnary.

Parameters:

coco_annotations (List[Dict[str, Any]]) – Coco data dictionnary.
spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.

Returns:

BaseFormat instance.

Return type:

BaseFormat

class detectools.formats.SegmentationAnnotation(spatial_size: Tuple[int], label: Tensor, boxe: Tensor, mask: Tensor, score: Tensor | None = None)[source]

BaseAnnotation child class for SegmentationAnnotation task.

Attributes:

boxe

Boxe coordinates in XYWH format.

Type:: BoundingBoxes

label

Class label of object.

Type:: Tensor

spatial_size

Size of corresponding image (H, W)

Type:: Tuple[int, int]

score

Confidence score of the object (for prediction).

Type:: Tensor

mask

Object segmentation binary mask (H, W).

Type:: Tensor

Methods:

object_to_coco(annotation_id: int = 1, image_id: int = 1) → Dict[str, Any][source]

Return instance segmentation annotation data as COCO like dict.

Parameters:

annotation_id (int, optional) – Id of the annotation. Defaults to 1.
image_id (int, optional) – Id of the corresponding image. Defaults to 1.

Returns:

COCO like dict with annotation instance data.

Return type:

Dict[str, Any]

class detectools.formats.SegmentationFormat(spatial_size: Tensor, labels: Tensor, boxes: Tensor, masks: Tensor, scores: Tensor | None = None, box_format: Literal['XYWH', 'XYXY', 'CXCYWH'] = 'XYWH')[source]

BaseFormat child class for instance segmentation task.

Parameters:

spatial_size (Tensor) – Spatial size (H, W) of corresponding images.
labels (Tensor) – Tensor of shape (N,) with class labels for each object.
boxes (Tensor) – Tensor of shape (N, 4). N for N objects and 4 for boxes coordinates.
scores (Tensor, optional) – Tensor of shape (N,) with objects confidence score. Defaults to None.
box_format (Literal['XYWH', 'XYXY', 'CXCYWH'], optional) – Format of bounding boxes. Defaults to ‘XYWH’.
masks (Tensor) – Tensor of shape (H,W) with values from 0 to N, one value/object.

Attributes:

box_format

Format of bounding boxes.

Type:: Literal["XYWH", "XYXY", "CXCYWH"]

spatial_size

Size of corresponding image (H, W)

Type:: Tuple[int, int]

size

Number of objects in BaseFormat.

Type:: int

data

(Dict[str, Tensor]): Data dict that contains objects informations in it’s keys (labels, boxes, scores, masks).

Type:: Dict[str, torch.Tensor]

Methods:

crop(top: int, left: int, height: int, width: int)[source]

Crop boxes and mask from top corner pixel and update spatial size.

Parameters:

top (int) – Position to crop from top border.
left (int) – Position to crop from left border.
height (int) – height of the crop.
width (int) – Width of the crop.

empty(device: Literal['cpu', 'cuda'] = 'cpu') → SegmentationFormat[source]

Return an empty instance SegmentationFormat.

Parameters:

spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.
device (Literal["cpu", "cuda"]) – Device to define format on. Default to “cpu”.

Returns:

SegmentationFormat instance.

Return type:

SegmentationFormat

from_coco(spatial_size: Tuple[int]) → SegmentationFormat[source]

Return SegmentationFormat from an image COCO data dictionnary.

Parameters:

coco_annotations (List[Dict[str, Any]]) – Coco data dictionnary.
spatial_size (Tuple[int]) – Size (H, W) of the corresponding image.

Returns:

SegmentationFormat instance.

Return type:

SegmentationFormat

get_object(indice: int) → SegmentationAnnotation[source]

Return SegmentationAnnotation object at position indice.

Parameters:

indice (int) – Position of object to gather.

Returns:

SegmentationAnnotation instance.

Return type:

SegmentationAnnotation

pad(left: int, top: int, right: int, bottom: int)[source]

Pad boxes and mask and update spatial size.

Parameters:

left (int) – Pad value on left border.
top (int) – Pad value on top border.
right (int) – Pad value on right border.
bottom (int) – Pad value on bottom border.

rescale_boxes_from_masks()[source]: Iter over objects, for each masks compute all objects contours: - If there is only one contour rescale the box with the mask contour. - If there is more than one object duplicate label to have one mask, box and label for one object.

set(key: str, value: Tensor)[source]

Set a new pair of key/value. Value should be of shape (N, …) with N == self.size. if key is “masks” and value is binary masks (N, H, W), size is N, if value is stacked mask (H,W). size is unstacked_masks.

Parameters:

key (str) – Key of value to set.
value (Tensor) – Data as tensor.