annotations module

This module defines classes for representing bounding boxes and keypoints associated with objects in images.

It also provides helper functions for constructing these objects from YOLO formatted labels.

class utilities.annotations.Point(x: float, y: float)

Bases: object

The Point class is a struct which contains an x and y value for a point.

Attributes :

x (float):

The x coordinate for the point.

y (float):

The y coordinate for the point.

class utilities.annotations.BoundingBox(category: str, left: float, top: float, right: float, bottom: float)

Bases: object

The BoundingBox class represents a bounding box around an object in an image.

Attributes :

category (str):

The category of the object within the bounding box.

left (float):

The x-coordinate of the top-left corner of the bounding box.

top (float):

The y-coordinate of the top-left corner of the bounding box.

right (float):

The x-coordinate of the bottom-right corner of the bounding box.

bottom (float):

The y-coordinate of the bottom-right corner of the bounding box.

Constructors :

from_yolo(yolo_line: str, image_width: int, image_height: int, int_to_category: Dict[int, str]):

Constructs a BoundingBox from a line in a YOLO formatted labels file. It requires the original image dimensions and a dictionary mapping category IDs to category names.

from_coco(coco_annotation: Dict, categories: List[Dict]):

Constructs a BoundingBox from an annotation in a COCO data JSON file. It requires the annotation dictionary and a list of category dictionaries.

Properties :

center (Tuple[int]):

A tuple containing the (x, y) coordinates of the bounding box’s center.

box (List[int]):

A list containing the bounding box coordinates as [left, top, right, bottom].

Methods :

to_yolo(image_width: int, image_height: int, category_to_int: Dict[str, int]) -> str:

Writes a yolo formatted string using this bounding box’s data.

validate_box_values(cls, left: float, top: float, right: float, bottom: float) -> None:

Validates the box parameters and throws a value error if left > right or top > bottom. Also issues a warning for the case when left == right or top == bottom letting the user know that they are constructing a degenerate rectangle.

category: str

left: float

top: float

right: float

bottom: float

static from_yolo(yolo_line: str, image_width: int, image_height: int, id_to_category: Dict[int, str])

Constructs a BoundingBox from a line in a yolo formatted labels file.

Because the yolo format stores data in normalized xywh format (from 0 to 1), this method requires the original image’s width and height.

Args :

yolo_line (str):

A string in the yolo label format (c x y w h).

image_width (int):

The original image’s width.

image_height (int):

The original image’s height.

id_to_category (Dict):

A dictionary that maps the number id in the label to the category.

Returns:

A BoundingBox object containing the yolo_line’s data.

static from_coco(coco_annotation: Dict, categories: List[Dict])

Constructs a BoundingBox from an annotation in a coco data json file.

Args :

coco_annotation (Dict): A bounding box annotation from the ‘annotations’ section. categories (List[Dict]): A list of dictionaries containing their numeric ids and categories.

Returns:

A BoundingBox object containing the coco annotation’s data.

classmethod validate_box_values(left: float, top: float, right: float, bottom: float) → None

Validates the coordinates of a rectangle (bounding box).

This classmethod ensures that the left coordinate is less than the right coordinate, and the top coordinate is less than the bottom coordinate. It raises a ValueError if these conditions are not met, indicating an invalid box configuration. If the left coordinate is equal to the right coordinate or if the top coordinate is equal to the bottom coordinate, this method issues a warning.

Parameters:

• left (float) – The left x-coordinate of the box.

• top (float) – The top y-coordinate of the box.

• right (float) – The right x-coordinate of the box.

• bottom (float) – The bottom y-coordinate of the box.

Raises:

ValueError – If left > right or top > bottom.

property center: Tuple[float]

This BoundingBox’s center.

property box: List[int]

A list containing this BoundingBox’s [left, top, right, bottom].

set_box(new_left: int, new_top: int, new_right: int, new_bottom: int)

Sets this BoundingBox’s values for left, top, right, bottom.

Args :

new_left (int):

The new left side for the box.

new_top (int):

The new top side for the box.

new_right (int):

The new right side for the box.

new_bottom (int):

The new bottom side for the box.

to_yolo(image_width: int, image_height: int, category_to_id: Dict[str, int], precision: int = 8) → str

Writes the data from this BoundingBox into a yolo formatted string.

Args :

image_width (int):

The image’s width that this boundingbox belongs to.

image_height (int):

The image’s height that this boundingbox belongs to.

category_to_id (Dict[str, int]):

A dictionary that maps the category string to an id (integer).

precision (int):

The number of decimal places to round yolo output to. Defaults to 8 decimal places. If more precision is needed, increase this value.

Returns:

A string that encodes this BoundingBox’s data for a single line in a yolo label file.

class utilities.annotations.Keypoint(keypoint: Point, bounding_box: BoundingBox)

Bases: object

The Keypoint class represents a keypoint associated with an object in an image.

Attributes :

keypoint (Tuple[float]):

A tuple containing the (x, y) coordinates of the keypoint relative to the top-left corner of the image.

bounding_box (BoundingBox):

A BoundingBox object that defines the bounding box around the object containing the keypoint.

Constructors :

from_yolo(yolo_line: str, image_width: int, image_height: int, id_to_category: Dict[int, str]):

Constructs a Keypoint from a line in a YOLO formatted labels file. It requires the original image dimensions and a dictionary mapping category IDs to category names. Note: This method ignores the “visibility” information (denoted by ‘v’) in the YOLO format.

Properties :

category (str):

The category of the object the keypoint belongs to (inherited from the bounding_box).

center (Tuple[float]):

The (x, y) coordinates of the bounding box’s center (inherited from the bounding_box).

box (Tuple[float]):

A list containing the bounding box coordinates as [left, top, right, bottom] (inherited from the bounding_box).

Methods :

to_yolo(self, image_width: int, image_height: int, category_to_id: Dict[str, int]) -> str:

Generates a YOLO formatted string representation of this Keypoint object. It requires the image dimensions and a dictionary mapping category strings to integer labels.

validate_keypoint(cls, bounding_box: BoundingBox, keypoint: Point) -> None:

Validates that a keypoint lies within the specified bounding box. Raises a ValueError if the keypoint is outside the bounding box.

keypoint: Point

bounding_box: BoundingBox

static from_yolo(yolo_line: str, image_width: int, image_height: int, id_to_category: Dict[int, str])

Constructs a Keypoint from a line in a yolo formatted labels file.

Because the yolo format stores data in normalized xywh format (from 0 to 1), this method requires the original image’s width and height. The ‘visible’ data is optional, and is not read to create the object.

Args :

yolo_line (str):

A string in the yolo label format (c x y w h kpx kpy v).

image_width (int):

The original image’s width.

image_height (int):

The original image’s height.

id_to_category (Dict):

A dictionary that maps the id number in the label to the category.

Returns:

A BoundingBox object containing the yolo_line’s data.

classmethod validate_keypoint(bounding_box: BoundingBox, keypoint: Point) → None

Validates that a keypoint lies within the specified bounding box.

This classmethod ensures that the keypoint (represented by a Point object) falls within the confines of the provided bounding_box (represented by a BoundingBox object). It checks both the x and y coordinates of the keypoint against the left, top, right, and bottom boundaries of the bounding box.

Parameters:

• bounding_box – The BoundingBox object representing the enclosing region.

• keypoint – The Point object representing the keypoint to be validated.

Raises:

ValueError – If the keypoint’s coordinates are not within the bounding box.

property category: str

This Keypoint’s category.

property center: Tuple[float]

This Keypoint’s boundingbox center.

property box: Tuple[float]

This keypoints boundingbox’s [left, top, right, bottom].

set_box_and_keypoint(new_left: int, new_top: int, new_right: int, new_bottom: int, new_kp_x: int, new_kp_y: int) → Keypoint

Sets this keypoint’s box and keypoint to new values.

This exists because setting the box to a new location will cause an exception when the new box would not contain the old keypoint.

Parameters:

• new_left (int) – The new left side for the box.

• new_top (int) – The new top side for the box.

• new_right (int) – The new right side for the box.

• new_bottom (int) – The new bottom side for the box.

• new_kp_x (int) – The new x value for the Keypoint.

• new_kp_y (int) – The new y value for the Keypoint.

Returns: A new Keypoint with a new bounding box and keypoint.

set_box(new_left: int, new_top: int, new_right: int, new_bottom: int) → BoundingBox

Sets this Keypoints’s BoundingBox’s values for left, top, right, bottom.

Parameters:

• new_left (int) – The new left side for the box.

• new_top (int) – The new top side for the box.

• new_right (int) – The new right side for the box.

• new_bottom (int) – The new bottom side for the box.

Returns: A new Keypoint with a new bounding box.

set_keypoint(new_x: int, new_y: int) → Keypoint

Sets this Keypoint’s Keypoint to a new point.

Parameters:

• new_x (int) – The new x value for the Keypoint.

• new_y (int) – The new y value for the Keypoint.

Returns: A new Keypoint with a new Point as its keypoint.

to_yolo(image_width: int, image_height: int, category_to_id: Dict[str, int], precision: int = 8) → str

Writes the data from this Keypoint into a yolo formatted string.

Args :

image_width (int):

The image’s width that this Keypoint belongs to.

image_height (int):

The image’s height that this Keypoint belongs to.

category_to_id (Dict[str, int]):

A dictionary that maps the category string to an id (int).

precision (int):

The number of decimal places to round yolo output to. Defaults to 8 decimal places. If more precision is needed, increase this value.

Returns:

A string that encodes this Keypoint’s data for a single line in a yolo label file.