cvtk.format.coco

cvtk.format.coco.crop(input: str | list[str], output: str)[source]

Crop objects from images based on COCO annotations.

The function crops objects from images based on COCO annotations. The cropped objects will be saved to the output directory.

Parameters:

  • input – The COCO annotation file or list of COCO annotation files.

  • output – The directory to save the cropped objects.

cvtk.format.coco.combine(input: str | list[str], output: str | None = None, ensure_ascii: bool = False, indent: int | None = 4) → dict[source]

Merge multiple COCO annotation files into one file.

The function will merge the images, annotations, and categories from multiple COCO annotation files into one file. The IDs of the images, annotations, and categories will be re-indexed.

Parameters:

  • inputs – List of file paths to COCO annotation files to be merged.

  • output – The merged COCO annotation data will be saved to the file if the file path is given.

  • ensure_ascii – If True, the output is guaranteed to have all incoming non-ASCII characters escaped.

  • indent – If a non-negative integer is provided, the output JSON data will be formatted with the given indentation.

Returns:

Merged COCO annotation data.

Return type:

dict

Examples

>>> merged_coco = merge(['annotations1.json', 'annotations2.json', 'annotations3.json'],
                        'merged_annotations.json')
cvtk.format.coco.split(input: str | dict, output: str | None = None, ratios: list[float] | tuple[float] = [0.8, 0.1, 0.1], shuffle: bool = True, reindex: bool = True, random_seed: int | None = None, ensure_ascii=False, indent=4) → list[dict][source]

Split a COCO annotation file into several subsets

The function splits the COCO annotation data into several subsets based on the given ratios. The images will be shuffled before splitting if the shuffle parameter is set to True.

Parameters:

  • input – The COCO annotation data to be split.

  • output – The split COCO annotation data will be saved to the file if the file path. The output file name will be appended with the index of the split subset.

  • ratios – Ratios of the train, validation, and test sets.

  • reindex – If True, the IDs of the images, categories, and annotations will be re-indexed.

  • shuffle – If True, the images will be shuffled before splitting.

  • random_seed – The random seed for shuffling the images.

  • ensure_ascii – If True, the output is guaranteed to have all incoming non-ASCII characters escaped.

  • indent – If a non-negative integer is provided, the output JSON data will be formatted with the given indentation.

Examples

>>> subsets = split('annotations.json', [0.8, 0.1, 0.1])
>>> len(subsets)
3
>>> subsets[0]['images']
[{'id': 1, 'file_name': 'image1.jpg', 'height': 480, 'width': 640}, ...]
cvtk.format.coco.reindex(input: str | dict, output: str | None = None, image_id=True, category_id=True, ensure_ascii=False, indent=4) → dict[source]

Re-index the IDs of images, categories, and annotations in a COCO annotation file.

Parameters:

  • input – The COCO annotation data to be re-indexed.

  • output – The re-indexed COCO annotation data will be saved to the file if the file path is given.

  • image_id – If True, the image IDs will be re-indexed.

  • category_id – If True, the category IDs will be re-indexed.

  • ensure_ascii – If True, the output is guaranteed to have all incoming non-ASCII characters escaped.

  • indent – If a non-negative integer is provided, the output JSON data will be formatted with the given indentation.

cvtk.format.coco.remove(input: str | dict, output: str | None = None, images: list | None = None, categories: list | None = None, annotations: list | None = None, ensure_ascii=False, indent=4) → dict[source]

Remove specific items from COCO format data

This function remove the specific images, categories, or annotations from COCO format data. The IDs of deleted image, category, and annotation will disappear. The remaining IDs will not be sorted.

Parameters:

  • input – The COCO annotation data to be re-indexed.

  • output – The re-indexed COCO annotation data will be saved to the file if the file path is given.

  • images – Remove images from coco format data by image ID if the items of list is intenger or by image name if the items of the list is string.

  • categories – Remove images from coco format data by image ID if the items of list is intenger or by image name if the items of the list is string.

  • annotations – Remove images from coco format data by image ID if the items of list is intenger or by image name if the items of the list is string.

  • ensure_ascii – If True, the output is guaranteed to have all incoming non-ASCII characters escaped.

  • indent – If a non-negative integer is provided, the output JSON data will be formatted with the given indentation.

cvtk.format.coco.stats(input: str | dict, output: str | None = None, ensure_ascii: bool = False, indent: int | None = 4) → dict[source]

Calculate statistics of a COCO annotation file.

Parameters:

  • input – The COCO annotation data to be analyzed.

  • output – The statistics of the COCO annotation data will be saved to the file if the file path

  • ensure_ascii – If True, the output is guaranteed to have all incoming non-ASCII characters escaped.

  • indent – If a non-negative integer is provided, the output JSON data will be formatted with the given indentation.

Returns:

A dictionary containing the statistics of the COCO annotation data.

Return type:

dict

Examples

>>> stats = cocostats('annotations.json')
cvtk.format.coco.calc_stats(gt: str | dict, pred: str | dict, image_by: str = 'id', category_by='id', iouType: str = 'bbox', metrics_labels=None) → dict[source]

Calculate prediction performance metrics for object detection and instance segmentation tasks

The function calculates the prediction performance metrics for object detection and instance segmentation tasks, using the COCO evaluation API from pycocotools. The ground truth and predicted annotations can be provided as file paths or dict objects of COCO annotations. The image IDs between the ground truth and prediction can be different; the function provides an option to map them by filepath or filename by specifying the image_by parameter. In addition, the category IDs between the ground truth and prediction can be different; the function provides an option to map them by category name by specifying the category_by parameter.

Parameters:

  • gt (str|dict) – Annotations of ground truth. It can be a path to a COCO annotation file or a dict object of COCO annotation.

  • pred (str|dict) – The predicted annotations. It can be a path to a COCO annotation file or a dict object of COCO annotation.

  • image_by (str) – The attribute to map image ID between ground truth and prediction. Default is ‘id’.

  • category_by (str) – The attribute to map category ID between ground truth and prediction. Default is ‘id’.

  • iouType (str) – The type of IoU calculation. Default is ‘bbox’, but ‘segm’ is also available.

Returns:

A dictionary containing the prediction performance metrics.

Return type:

dict

Examples

>>> calculate_map('ground_truth.json', 'predictions.json')