fiftyone.utils.coco

module documentation

(source)

Utilities for working with datasets in COCO format.

Class	`COCODetectionDatasetExporter`	Exporter that writes COCO detection datasets to disk.
Class	`COCODetectionDatasetImporter`	Importer for COCO detection datasets stored on disk.
Class	`COCOObject`	An object in COCO format.
Function	`add_coco_labels`	Adds the given COCO labels to the collection.
Function	`download_coco_dataset_split`	Utility that downloads full or partial splits of the COCO dataset.
Function	`load_coco_detection_annotations`	Loads the COCO annotations from the given JSON file.
Function	`parse_coco_categories`	Parses the COCO categories list.
Variable	`logger`	Undocumented
Variable	`mask_utils`	Undocumented
Function	`_close_contour`	Undocumented
Function	`_coco_objects_to_detections`	Undocumented
Function	`_coco_objects_to_keypoints`	Undocumented
Function	`_coco_objects_to_polylines`	Undocumented
Function	`_coco_segmentation_to_mask`	Undocumented
Function	`_do_download`	Undocumented
Function	`_download_images`	Undocumented
Function	`_get_attributes`	Undocumented
Function	`_get_class_ids`	Undocumented
Function	`_get_existing_ids`	Undocumented
Function	`_get_images_with_classes`	Undocumented
Function	`_get_matching_image_ids`	Undocumented
Function	`_get_matching_objects`	Undocumented
Function	`_get_polygons_for_segmentation`	Undocumented
Function	`_instance_to_coco_segmentation`	Undocumented
Function	`_load_image_ids_csv`	Undocumented
Function	`_load_image_ids_json`	Undocumented
Function	`_load_image_ids_txt`	Undocumented
Function	`_make_coco_keypoints`	Undocumented
Function	`_mask_to_polygons`	Undocumented
Function	`_mask_to_rle`	Undocumented
Function	`_merge_dir`	Undocumented
Function	`_normalize_coco_segmentation`	Undocumented
Function	`_pairwise`	Undocumented
Function	`_parse_categories`	Undocumented
Function	`_parse_coco_detection_annotations`	Undocumented
Function	`_parse_image_ids`	Undocumented
Function	`_parse_include_license`	Undocumented
Function	`_parse_label_types`	Undocumented
Function	`_polyline_to_coco_segmentation`	Undocumented
Function	`_to_classes`	Undocumented
Function	`_to_labels_map_rev`	Undocumented
Function	`_write_partial_annotations`	Undocumented
Constant	`_ANNOTATION_DOWNLOAD_LINKS`	Undocumented
Constant	`_ANNOTATION_PATHS`	Undocumented
Constant	`_CSV_DELIMITERS`	Undocumented
Constant	`_IMAGE_DOWNLOAD_LINKS`	Undocumented
Constant	`_KEYPOINTS_PATHS`	Undocumented
Constant	`_SPLIT_SIZES`	Undocumented
Constant	`_SUPPORTED_LABEL_TYPES`	Undocumented
Constant	`_SUPPORTED_SPLITS`	Undocumented
Constant	`_TEST_INFO_DOWNLOAD_LINKS`	Undocumented
Constant	`_TEST_INFO_PATHS`	Undocumented

def add_coco_labels(sample_collection, label_field, labels_or_path, categories, label_type='detections', coco_id_field=None, include_annotation_id=False, extra_attrs=True, use_polylines=False, tolerance=None): (source) ¶

Adds the given COCO labels to the collection.

The labels_or_path argument can be any of the following:

a list of COCO annotations in the format below
the path to a JSON file containing a list of COCO annotations
the path to a JSON file whose "annotations" key contains a list of COCO annotations

When label_type="detections", the labels should have format:

[
    {
        "id": 1,
        "image_id": 1,
        "category_id": 1,
        "bbox": [260, 177, 231, 199],

        # optional
        "score": 0.95,
        "area": 45969,
        "iscrowd": 0,

        # extra attrs
        ...
    },
    ...
]

When label_type="segmentations", the labels should have format:

[
    {
        "id": 1,
        "image_id": 1,
        "category_id": 1,
        "bbox": [260, 177, 231, 199],
        "segmentation": [...],

        # optional
        "score": 0.95,
        "area": 45969,
        "iscrowd": 0,

        # extra attrs
        ...
    },
    ...
]

When label_type="keypoints", the labels should have format:

[
    {
        "id": 1,
        "image_id": 1,
        "category_id": 1,
        "keypoints": [224, 226, 2, ...],
        "num_keypoints": 10,

        # extra attrs
        ...
    },
    ...
]

See this page for more information about the COCO data format.

Parameters
sample_collection	a `fiftyone.core.collections.SampleCollection`
label_field	the label field in which to store the labels. The field will be created if necessary
labels_or_path	a list of COCO annotations or the path to a JSON file containing such data on disk
categories	can be any of the following: a list of category dicts in the format of `parse_coco_categories` specifying the classes and their category IDs a dict mapping class IDs to class labels a list of class labels whose 1-based ordering is assumed to correspond to the category IDs in the provided COCO labels
label_type:"detections"	the type of labels to load. Supported values are `("detections", "segmentations", "keypoints")`
coco_id_field:`None`	this parameter determines how to map the predictions onto samples in `sample_collection`. The supported values are: `None` (default): in this case, the `image_id` of the predictions are assumed to be the 1-based positional indexes of samples in `sample_collection` the name of a field of `sample_collection` containing the COCO IDs for the samples that correspond to the `image_id` of the predictions
include_annotation_id:`False`	whether to include the COCO ID of each annotation in the loaded labels
extra_attrs:`True`	whether to load extra annotation attributes onto the imported labels. Supported values are: `True`: load all extra attributes found `False`: do not load extra attributes a name or list of names of specific attributes to load
use_polylines:`False`	whether to represent segmentations as `fiftyone.core.labels.Polylines` instances rather than `fiftyone.core.labels.Detections` with dense masks
tolerance:`None`	a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels

def download_coco_dataset_split(dataset_dir, split, year='2017', label_types=None, classes=None, image_ids=None, num_workers=None, shuffle=None, seed=None, max_samples=None, raw_dir=None, scratch_dir=None): (source) ¶

Utility that downloads full or partial splits of the COCO dataset.

See :ref:`this page <COCODetectionDataset-export>` for the format in which dataset_dir will be arranged.

Any existing files are not re-downloaded.

Parameters
dataset_dir	the directory to download the dataset
split	the split to download. Supported values are `("train", "validation", "test")`
year:"2017"	the dataset year to download. Supported values are `("2014", "2017")`
label_types:`None`	a label type or list of label types to load. The supported values are `("detections", "segmentations")`. By default, all label types are loaded
classes:`None`	a string or list of strings specifying required classes to load. Only samples containing at least one instance of a specified class will be loaded
image_ids:`None`	an optional list of specific image IDs to load. Can be provided in any of the following formats: a list of `<image-id>` ints or strings a list of `<split>/<image-id>` strings the path to a text (newline-separated), JSON, or CSV file containing the list of image IDs to load in either of the first two formats
num_workers:`None`	a suggested number of threads to use when downloading individual images
shuffle:`False`	whether to randomly shuffle the order in which samples are chosen for partial downloads
seed:`None`	a random seed to use when shuffling
max_samples:`None`	a maximum number of samples to load. If `label_types` and/or `classes` are also specified, first priority will be given to samples that contain all of the specified label types and/or classes, followed by samples that contain at least one of the specified labels types or classes. The actual number of samples loaded may be less than this maximum value if the dataset does not contain sufficient samples matching your requirements. By default, all matching samples are loaded
raw_dir:`None`	a directory in which full annotations files may be stored to avoid re-downloads in the future
scratch_dir:`None`	a scratch directory to use to download any necessary temporary files
Returns
a tuple of	num_samples: the total number of downloaded images classes: the list of all classes did_download: whether any content was downloaded (True) or if all necessary files were already downloaded (False)

def load_coco_detection_annotations(json_path, extra_attrs=True): (source) ¶

Loads the COCO annotations from the given JSON file.

See :ref:`this page <COCODetectionDataset-import>` for format details.

Parameters
json_path	the path to the annotations JSON file
extra_attrs:`True`	whether to load extra annotation attributes. Supported values are: `True`: load all extra attributes found `False`: do not load extra attributes a name or list of names of specific attributes to load
Returns
a tuple of	info: a dict of dataset info classes_map: a dict mapping class IDs to labels supercategory_map: a dict mapping class labels to category dicts images: a dict mapping image IDs to image dicts annotations: a dict mapping image IDs to list of `COCOObject` instances, or `None` for unlabeled datasets

def parse_coco_categories(categories): (source) ¶

Parses the COCO categories list.

Parameters
categories	a list of dict of the form: [ ... { "id": 2, "name": "cat", "supercategory": "animal", "keypoints": ["nose", "head", ...], "skeleton": [[12, 14], [14, 16], ...] }, ... ]
Returns
a tuple of	classes_map: a dict mapping class IDs to labels supercategory_map: a dict mapping class labels to category dicts

logger = (source) ¶

Undocumented

mask_utils = (source) ¶

Undocumented

def _close_contour(contour): (source) ¶

Undocumented

def _coco_objects_to_detections(coco_objects, frame_size, classes_map, supercategory_map, load_segmentations, include_id): (source) ¶

Undocumented

def _coco_objects_to_keypoints(coco_objects, frame_size, classes_map, supercategory_map, include_id): (source) ¶

Undocumented

def _coco_objects_to_polylines(coco_objects, frame_size, classes_map, supercategory_map, tolerance, include_id): (source) ¶

Undocumented

def _coco_segmentation_to_mask(segmentation, bbox, frame_size): (source) ¶

Undocumented

def _do_download(args): (source) ¶

Undocumented

def _download_images(images_dir, image_ids, images, num_workers): (source) ¶

Undocumented

def _get_attributes(label, extra_attrs): (source) ¶

Undocumented

def _get_class_ids(classes, classes_map): (source) ¶

Undocumented

def _get_existing_ids(images_dir, images, image_ids): (source) ¶

Undocumented

def _get_images_with_classes(image_ids, annotations, target_classes, classes_map): (source) ¶

Undocumented

def _get_matching_image_ids(classes_map, images, annotations, image_ids=None, classes=None, shuffle=False, seed=None, max_samples=None): (source) ¶

Undocumented

def _get_matching_objects(coco_objects, class_ids): (source) ¶

Undocumented

def _get_polygons_for_segmentation(segmentation, frame_size, tolerance): (source) ¶

Undocumented

def _instance_to_coco_segmentation(detection, frame_size, iscrowd='iscrowd', tolerance=None): (source) ¶

Undocumented

def _load_image_ids_csv(csv_path): (source) ¶

Undocumented

def _load_image_ids_json(json_path): (source) ¶

Undocumented

def _load_image_ids_txt(txt_path): (source) ¶

Undocumented

def _make_coco_keypoints(keypoint, frame_size): (source) ¶

Undocumented

def _mask_to_polygons(mask, tolerance): (source) ¶

Undocumented

def _mask_to_rle(mask): (source) ¶

Undocumented

def _merge_dir(indir, outdir): (source) ¶

Undocumented

def _normalize_coco_segmentation(segmentation): (source) ¶

Undocumented

def _pairwise(x): (source) ¶

Undocumented

def _parse_categories(categories, classes=None): (source) ¶

Undocumented

def _parse_coco_detection_annotations(d, extra_attrs=True): (source) ¶

Undocumented

def _parse_image_ids(raw_image_ids, images, split=None): (source) ¶

Undocumented

def _parse_include_license(include_license): (source) ¶

Undocumented

def _parse_label_types(label_types): (source) ¶

Undocumented

def _polyline_to_coco_segmentation(polyline, frame_size, iscrowd='iscrowd'): (source) ¶

Undocumented

def _to_classes(classes_map): (source) ¶

Undocumented

def _to_labels_map_rev(classes): (source) ¶

Undocumented

def _write_partial_annotations(d, outpath, split, filenames): (source) ¶

Undocumented

_ANNOTATION_DOWNLOAD_LINKS: dict[str, str] = (source) ¶

Undocumented

Value

{'2014': 'http://images.cocodataset.org/annotations/annotations_trainval2014.zip'↵
,
 '2017': 'http://images.cocodataset.org/annotations/annotations_trainval2017.zip'↵
}

_ANNOTATION_PATHS: dict = (source) ¶

Undocumented

Value

{'2014': {'train': 'annotations/instances_train2014.json',
          'validation': 'annotations/instances_val2014.json'},
 '2017': {'train': 'annotations/instances_train2017.json',
          'validation': 'annotations/instances_val2017.json'}}

_CSV_DELIMITERS: list[str] = (source) ¶

Undocumented

Value

[',', ';', ':', ' ', '\t', '\n']

_IMAGE_DOWNLOAD_LINKS: dict = (source) ¶

Undocumented

Value

{'2014': {'train': 'http://images.cocodataset.org/zips/train2014.zip',
          'validation': 'http://images.cocodataset.org/zips/val2014.zip',
          'test': 'http://images.cocodataset.org/zips/test2014.zip'},
 '2017': {'train': 'http://images.cocodataset.org/zips/train2017.zip',
          'validation': 'http://images.cocodataset.org/zips/val2017.zip',
          'test': 'http://images.cocodataset.org/zips/test2017.zip'}}

_KEYPOINTS_PATHS: dict = (source) ¶

Undocumented

Value

{'2014': {'train': 'annotations/person_keypoints_train2014.json',
          'validation': 'annotations/person_keypoints_val2014.json'},
 '2017': {'train': 'annotations/person_keypoints_train2017.json',
          'validation': 'annotations/person_keypoints_val2017.json'}}

_SPLIT_SIZES: dict = (source) ¶

Undocumented

Value

{'2014': {'train': 82783, 'test': 40775, 'validation': 40504},
 '2017': {'train': 118287, 'test': 40670, 'validation': 5000}}

_SUPPORTED_LABEL_TYPES: list[str] = (source) ¶

Undocumented

Value

['detections', 'segmentations', 'keypoints']

_SUPPORTED_SPLITS: list[str] = (source) ¶

Undocumented

Value

['train', 'validation', 'test']

_TEST_INFO_DOWNLOAD_LINKS: dict[str, str] = (source) ¶

Undocumented

Value

{'2014': 'http://images.cocodataset.org/annotations/image_info_test2014.zip',
 '2017': 'http://images.cocodataset.org/annotations/image_info_test2017.zip'}

_TEST_INFO_PATHS: dict[str, str] = (source) ¶

Undocumented

Value

{'2014': 'annotations/image_info_test2014.json',
 '2017': 'annotations/image_info_test2017.json'}