bbox_converter#

Set of functions to import, export or simply convert bounding box numpy arrays or dataframe depending on the convention used.

12 compatible formats, compatible with

  • cAIpy JSON

  • COCO

  • darknet

  • etc…

Functions

column_names_from_format_string

Generate the column names from the format string.

column_names_from_options

Generate the column names from dictionary of options, generated by parse_format_string()

convert_bbox

Convert bounding box from a particular format to another, using a composition of import_bbox() and export_bbox().

export_bbox

Convert bounding boxes in Lours's reference to a desired format.

import_bbox

Convert bounding boxes from a particular format to cAIpy/COCO reference.

parse_format_string

Function used to parse the format string and convert it to a dictionary with options as boolean and an order list
column_names_from_format_string(format_string: str) → list[str][source]#

Generate the column names from the format string.

Essentially, it calls a composition of parse_format_string() and column_names_from_options()

This function is useful when you want to drop these columns from the annotations dataframe in you Dataset object

Parameters:

format_string – short acronym describing the box format

Returns:

List of verbose column names associated to given format.

Return type:

list[str]

column_names_from_options(relative: bool, center: bool, size: bool, point: bool) → list[str][source]#

Generate the column names from dictionary of options, generated by parse_format_string()

This is useful to know what column to take from input dataframe when importing bounding boxes, or what name must be given to output dataframe when exporting bounding boxes

Parameters:

  • relative – Whether the box coordinates are relative to image size (coordinates are usually between 0 and 1) or not (coordinates are in pixels).

  • center – Whether the first xy coordinate are linked to center of box or bottom left corner (in this case, it’s xmin and ymin)

  • size – Whether the second xy coordinates are box width and height or coordinate of top right corner (in this case, it’s xmax and ymax). Note that size cannot be False if center is True.

  • point – Whether the second xy coordinates are expected to be 0 (because it’s only a point) or not.

Returns:

list of column names in the right order

convert_bbox(bounding_boxes: ndarray | DataFrame, images_df: DataFrame, image_ids: Sequence[int] | None = None, input_format: str = 'XYWH', output_format: str = 'cxwcyh') → DataFrame[source]#

Convert bounding box from a particular format to another, using a composition of import_bbox() and export_bbox().

See their documentation for an explanation of format strings

Parameters:

  • bounding_boxes –

    array or dataframe containing the bbox coordinates.

    • If it’s an array, image_ids must be given.

    • If it’s a dataframe, corresponding columns of input_format must be present

  • images_df – dataframe containing image data, and especially image sizes.

  • image_ids – optional list to link every bounding box to its corresponding image with its id. As such, this must be the same length as bounding_boxes array. Note that if bounding_boxes is a dataframe and has a image_id column, this option is not used. Defaults to None.

  • input_format – string defining the expected input format. Defaults to “XYWH”.

  • output_format – string describing the desired bounding box format. Defaults to “XYWH”.

Raises:

ValueError – This error is raised if the input format string is not well formatted or if bounding boxes and image ids shapes are incompatible

Returns:

dataframe containing the bounding box coordinates with the corresponding column names. It will have the same index as bounding_boxes if it is a dataframe.

export_bbox(annotations_df: DataFrame, images_df: DataFrame, input_format: str = 'XYWH', output_format: str = 'XYWH') → DataFrame[source]#

Convert bounding boxes in Lours’s reference to a desired format.

output_format is a format string following the same syntax as input_format in import_bbox().

  • cx stands for x-coordinate of the center of the box

  • first x stands for x-coordinate of the leftmost point of the box (i.e. the minimum x value)

  • second x stands for x-coordinate of the rightmost point of the box (i.e. the maximum x value)

  • w stands for the box width

  • cy stands for the y-coordinates of the center of the box

  • first y stands for y-coordinate of the upper point of the box (i.e. the minimum y value)

  • second y stands for y-coordinate of the bottom point of the box (i.e. the maximum y value)

  • h stands fo the box height

In addition, letters in uppercase indicate that the coordinate are in pixels, while lowercase indicate that they are relative to the image size, i.e. 1 is the full width of height of the image.

Example

cAIpy / COCO:

"XYWH"  # x left, y top, width, height, all in pixels

darknet:

"cxwcyh"  # x center, width, y center, height, all in relative

Note

  • x-coordinates and y-coordinates must follow the same convention. As such, examples like xxYH are not allowed

  • order can be either {x1}{x2}{y1}{y2} or {x1}{y1}{x2}{y2}. Order is important if the output dataframe is expected to be converted to numpy after calling this function

  • center coordinate can only be used with box size. cxxcyy is thus not allowed

  • Finally, only 12 options are allowed options. Here is the list : cxwcyh, xwyh, xxyy, cxcywh, xywh, xyxy, CXWCYH, XWYH, XXYY, CXCYWH, XYWH, XYXY

The created dataframe will have the following column names

  • center coordinates are named box_{x/y}_center

  • extremal coordinated are named box_{x/y}_{min/max}

  • box sizes are named box_{width/height}

  • If coordinates are relative, names get appended the _relative suffix

Example

cAipy / COCO:

"XYWH" # ["box_x_min", "box_y_min", "box_width", "box_height"]

darknet:

"cxwcyh"
# ["box_x_center_relative", "box_width_relative",
#  "box_y_center_relative", "box_height_relative"]
Parameters:

  • annotations_df – dataframe containing the annotations in Lours format. Must have at least box_x_min, box_width, box_y_min, box_height and image_id columns.

  • images_df – dataframe containing the image sizes in Lours format. Must have at least width, height, and the ids must correspond in the column image_id the annotations dataframe.

  • input_format – string defining the expected input format. Defaults to “XYWH”.

  • output_format – string describing the desired bounding box format (see above). Defaults to “XWYH”.

Returns:

dataframe containing the bounding box coordinates with the corresponding column names. It will have the same index as annotations_df

import_bbox(bounding_boxes: DataFrame | ndarray, images_df: DataFrame, image_ids: Sequence[int] | Series | ndarray | None = None, input_format: str = 'XYWH') → DataFrame[source]#

Convert bounding boxes from a particular format to cAIpy/COCO reference. Essentially, this will convert bounding box coordinates to pixel coordinates with box size.

input_format is a format string following a particular syntax to quickly let the function figure what conversion operation to do.

  • cx stands for x-coordinate of the center of the box

  • first x stands for x-coordinate of the leftmost point of the box (i.e. the minimum x value)

  • second x stands for x-coordinate of the rightmost point of the box (i.e. the maximum x value)

  • w stands for the box width

  • cy stands for the y-coordinates of the center of the box

  • first y stands for y-coordinate of the upper point of the box (i.e. the minimum y value)

  • second y stands for y-coordinate of the bottom point of the box (i.e. the maximum y value)

  • h stands fo the box height

In addition, letters in uppercase indicate that the coordinate are in pixels, while lowercase indicate that they are relative to the image size, i.e. 1 is the full width of height of the image.

Example

cAIpy / COCO:

"XYWH"  # x left, y top, width, height, all in pixels

darknet:

"cxwcyh"  # x center, width, y center, height, all in relative

Note

  • x-coordinates and y-coordinates must follow the same convention. As such, examples like xxYH are not allowed

  • order can be either {x1}{x2}{y1}{y2} or {x1}{y1}{x2}{y2}. If bounding_boxes is a dataframe, it should not change anything as columns are named, but order is important if it is a numpy array instead

  • center coordinate can only be used with box size. cxxcyy is thus not allowed

  • Finally, only 12 options are allowed options. Here is the list : cxwcyh, xwyh, xxyy, cxcywh, xywh, xyxy, CXWCYH, XWYH, XXYY, CXCYWH, XYWH, XYXY

In the case bounding_boxes is a dataframe, columns must correspond to the given format string. The convention is the following:

  • center coordinates are named box_{x/y}_center

  • extremal coordinated are named box_{x/y}_{min/max}

  • box sizes are named box_{width/height}

  • If coordinates are relative, names get appended the _relative suffix

Example

cAipy / COCO:

"XYWH" # ["box_x_min", "box_y_min", "box_width", "box_height"]

darknet:

"cxwcyh"
# ["box_x_center_relative", "box_width_relative",
#  "box_y_center_relative", "box_height_relative"]
Parameters:

  • bounding_boxes –

    array or dataframe containing the bbox coordinates

    • If it’s an array, image_ids must be given, and its shape must be (4, N)

    • If it’s a dataframe, corresponding columns of input_format must be present (see example above)

  • images_df – dataframe containing image data, and especially image sizes.

  • image_ids – optional list to link every bounding box to its corresponding image with its id. As such, this must be the same length as bounding_boxes array. Note that if bounding_boxes is an array and has a image_id column, this option is not used. Defaults to None.

  • input_format – string defining the expected input format. Defaults to “XYWH”.

Raises:

ValueError – This error is raised if the input format string is not well formatted or if bounding boxes and image ids shapes are incompatible

Returns:

DataFrame containing the reference cAIpy format, i.e. with x left, width, y top and height, in pixels. index is the same one os bounding_boxes, and columns are, as described above, box_x_min, box_width, box_y_min and box_height. This is the format expected in the Dataset or Evaluator <lours.evaluation.Evaluator

parse_format_string(format_string: str) → tuple[dict[str, bool], list[int]][source]#

Function used to parse the format string and convert it to a dictionary with options as boolean and an order list

output dictionary keys are:

  • “center”: if the first x or y coordinate is the center of the box or the minimum value (left for x, top for y)

  • “size”: if the second coordinate is the size of the box (width for x, height for y), or the maximum value (right for x, bottom for y)

  • “relative”: if the coordinated are in pixels of normalized with image size (image width for x, image height for y)

order output list is order in which x1, x2, y1, y2 needs to be taken for the input array of bounding boxes. Possible values are [0, 1, 2, 3] (for e.g. xxyy) or [0, 2, 1, 3] (for e.g. xyxy)

Parameters:

format_string – format string describing the convention used for box coordinates can be e.g. XYWH (cAIpy / COCO format), cxwcyh (darknet format) etc. See documentation in import_bbox() and export_bbox() for a breakdown of the syntax.

Raises:

ValueError – raised when the formatstring is not in the 12 allowed values.

Returns:

tuple containing two elements - dictionary of options (see detailed keys above) - list of column positions for x1, x2, y1, y1 in the bbox array