justdeepit.utils.ImageAnnotation

class justdeepit.utils.ImageAnnotation(image_path, annotation, annotation_format='auto', class2rgb=None, rgb2class=None)[source]

A container to store image annotations

Class ImageAnnotation is a container that stores image annotations such as file paths, coordinates of bounding boxes and object contours, and object names.

Parameters:

  • image_path (str) – A path to an image.

  • annotation (str) – A path to an annotation file that corresponds to the image image_path.

  • annotation_format (str) – A string to specify an annotation format. If auto is specified, then automatically estimate the annotation format.

  • rgb2class (dict) – A dictionary mapping RGB values to class name.

The image annotations are stored with the following attributes:

image_path

A path to an image.

Type:

str

image

An image data in numpy.ndarray object, which is generated by skimage.io.imread.

Type:

numpy.ndarray

exif_orientation

An integer ranged from 1 until 8 to specify EXIF Orientation.

Type:

int

regions

A list of dictionaries consists of image annotations, and each dictionary consists of keys id, class, bbox, contour, and score. id is an integer that stores the object identifier, and class is a string that stores a class label. bbox is a list consisting of four elements ([xmin, ymin, xmax, ymax]) that represent the coordinates of the bounding box, and contour is a two-dimensional array (e.g., [[x1, y1], [x2, y2], ..., [xn, yn]]) that stores the coordinates of object contours. score is the confidence score of the class, which is usually output from object detection models. If the object is a donut-shaped object (i.e., object with several holes), the holes are also annotated as an object, but the class is set to __background__ in this case.

Type:

list

mask

A mask of image stored in numpy.ndarray.

Type:

numpy.ndarray

class2rgb

A dictionary mapping class name to RGB values.

Type:

dict

rgb2class

A dictionary mapping RGB values to class name.

Type:

dict

Class ImageAnnotation mainly implements methods format and draw for format conversion and image visualization, respectively. By using method format, the annotations can be converted to any format, such as the COCO format and Pascal VOC format. By using method draw, the image is plotted with annotations.

Examples

>>> from justdeepit.utils import ImageAnnotation
>>>
>>> image_fpath = './path/to/image.jpg'
>>> ann_fpath = './path/to/image.json'
>>>
>>> ann = ImageAnnotation(image_fpath, ann_fpath)
format(annotation_format, file_path=None)[source]

Format annotation to specific format

Method format converts class object ImageAnnotation into a specific format. COCO (.json) and Pascal VOC (.xml) are supported formats in the current version of JustDeepIt. Additionally, this method supports the conversion of class object ImageAnnotation into a mask image represented by class object numpy.ndarray.

Parameters:

  • annotation_format (str) – A string to specify the format to be formatted. json, coco, voc, or mask can be specified.

  • file_path (str) – A path to save the converted annotation. If None is given, return the converted annotation in string or dictionary.

Returns:

If file_path is None, return a string (for Pascal VOC format), a dictionary (for COCO), or numpy.ndarray (for image data). Otherwise, save the data in the given path.

Examples

>>> from justdeepit.utils import ImageAnnotation
>>>
>>> image_fpath = './path/to/image.jpg'
>>> ann_fpath = './path/to/image.json'
>>> ann = ImageAnnotation(image_fpath, ann_fpath)
>>>
>>> ann.format('voc', './path/to/image.xml')
draw(fig_type='mask', file_path=None, label=False, score=False, alpha=1.0, class2rgb=None)[source]

Plot an image with annotations

Method draw depicts an image with annotations of class object ImageAnnotation. The output type can be specified by argument fig_type, which can be specified as mask, rgbmask, masked, bbox, or contour. Type mask plots a mask image, whose background is shown in black and the objects are shown in white. Type rgbmask plots an RGB mask image, where the background is shown in black while the objects are shown with different colors, unlike type mask. Objects belonging to the same class are plotted with the same colors according to class2rgb. Type masked plots masked images with black background while the object area is the same as that of the original images. Type bbox plots an image with bounding boxes around objects. Type contour plots the contours of objects. In addition, multiple types can be specified simultaneously, such as mask+bbox and contour+bbox.

Parameters:

  • fig_type (str) – A string to specify the figure type to be plotted. One of mask, rgbmask, masked, bbox, or contour can be specified.

  • file_path (str) – A path to save the converted annotation. If None is given, return the image in numpy.ndarray object.

  • label (bool) – Show class label of object on the image.

  • score (bool) – Show confidence score of object on the image if the score is not None.

  • alpha (float) – A decimal number between 0.0 and 1.0 to specify the transparence of mask.

  • class2rgb (dict) – A dictionary with a key as a class name and value as a RGB value. If None is given, the preset colors will be used.

Returns:

If file_path is None, return the image data in numpy.ndarray object. Otherwise, save the data in the given path.

Examples

>>> import matplotlib.pyplot as plt
>>> from justdeepit.utils import ImageAnnotation
>>>
>>> image_fpath = './path/to/image.jpg'
>>> ann_fpath = './path/to/image.json'
>>>
>>> ann = justdeepit.utils.ImageAnnotation(image_fpath, ann_fpath)
>>>
>>> ann.draw('bbox')