fiftyone.utils.coco¶

Utilities for working with datasets in COCO format.

Copyright 2017-2021, Voxel51, Inc.
voxel51.com

Classes

`COCODetectionDatasetExporter`(export_dir[, …])	Exporter that writes COCO detection datasets to disk.
`COCODetectionDatasetImporter`(dataset_dir[, …])	Importer for COCO detection datasets stored on disk.
`COCODetectionSampleParser`([classes, …])	Parser for samples in COCO Object Detection Format.
`COCOObject`(id, image_id, category_id, bbox)	An object in COCO detection format.

Functions

`download_coco_dataset_split`(dataset_dir, split)	Downloads and extracts the given split of the COCO dataset to the specified directory.
`load_coco_detection_annotations`(json_path)	Loads the COCO annotations from the given JSON file.
`parse_coco_categories`(categories)	Parses the COCO categories list.

class fiftyone.utils.coco.COCODetectionSampleParser(classes=None, supercategory_map=None, load_segmentations=True, return_polylines=False, tolerance=None)¶

Bases: fiftyone.utils.data.parsers.LabeledImageTupleSampleParser

Parser for samples in COCO Object Detection Format.

This implementation supports samples that are (image_or_path, anno_dict_or_path) tuples, where:

image_or_path is either an image that can be converted to numpy format via np.asarray() or the path to an image on disk
anno_dict_or_path is a list of detections in the following format:
[
    {
        "id": 354728
        "image_id": 183709,
        "category_id": 3,
        "bbox": [45.03, 236.82, 54.79, 30.91],
        "segmentation": [...],
        "area": 1193.6559000000002,
        "iscrowd": 0,
    },
    ...
]
or the path to such a JSON file on disk. It is assumed that all detections correspond to the image in the sample. For unlabeled images, anno_dict_or_path can be None.

See fiftyone.types.dataset_types.COCODetectionDataset for format details.

Parameters

classes (None) – a list of class label strings. If not provided, the category_id of the annotations will be used as labels
supercategory_map (None) – a dict mapping class labels to supercategories. If provided, supercategory attributes will be added to all parsed detections
load_segmentations (True) – whether to load segmentation masks, if available
return_polylines (False) – whether to return fiftyone.core.labels.Polylines instances rather than fiftyone.core.labels.Detections
tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return labels of this type
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the parser will return label dictionaries with keys and value-types specified by this dictionary. Not all keys need be present in the imported labels
None. In this case, the parser makes no guarantees about the labels that it may return

get_label()¶

Returns the label for the current sample.

Returns: a fiftyone.core.labels.Label instance, or a dictionary mapping field names to fiftyone.core.labels.Label instances, or None if the sample is unlabeled

clear_sample()¶

Clears the current sample.

Also clears any cached sample information stored by the parser.

property current_sample¶

The current sample.

Raises: ValueError – if there is no current sample

get_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

property has_image_metadata¶: Whether this parser produces fiftyone.core.metadata.ImageMetadata instances for samples that it parses.

property has_image_path¶: Whether this parser produces paths to images on disk for samples that it parses.

with_sample(sample)¶

Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

Guaranteed to call clear_sample() before setting the current sample.

Parameters: sample – a sample

class fiftyone.utils.coco.COCODetectionDatasetImporter(dataset_dir, load_segmentations=True, return_polylines=False, tolerance=None, skip_unlabeled=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledImageDatasetImporter

Importer for COCO detection datasets stored on disk.

See fiftyone.types.dataset_types.COCODetectionDataset for format details.

Parameters

dataset_dir – the dataset directory
load_segmentations (True) – whether to load segmentation masks, if available
return_polylines (False) – whether to return fiftyone.core.labels.Polylines instances rather than fiftyone.core.labels.Detections
tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels
skip_unlabeled (False) – whether to skip unlabeled images when importing
shuffle (False) – whether to randomly shuffle the order in which the samples are imported
seed (None) – a random seed to use when shuffling
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

property has_dataset_info¶: Whether this importer produces a dataset info dictionary.

property has_image_metadata¶: Whether this importer produces fiftyone.core.metadata.ImageMetadata instances for each image.

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this importer.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the importer is guaranteed to return labels of this type
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the importer will return label dictionaries with keys and value-types specified by this dictionary. Not all keys need be present in the imported labels
None. In this case, the importer makes no guarantees about the labels that it may return

setup()¶

Performs any necessary setup before importing the first sample in the dataset.

This method is called when the importer’s context manager interface is entered, DatasetImporter.__enter__().

get_dataset_info()¶

Returns the dataset info for the dataset.

By convention, this method should be called after all samples in the dataset have been imported.

Returns: a dict of dataset info

close(*args)¶

Performs any necessary actions after the last sample has been imported.

This method is called when the importer’s context manager interface is exited, DatasetImporter.__exit__().

Parameters: *args – the arguments to DatasetImporter.__exit__()

class fiftyone.utils.coco.COCODetectionDatasetExporter(export_dir, classes=None, info=None, image_format=None, tolerance=None)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter

Exporter that writes COCO detection datasets to disk.

See fiftyone.types.dataset_types.COCODetectionDataset for format details.

Parameters

export_dir – the directory to write the export
classes (None) – the list of possible class labels. If not provided, this list will be extracted when log_collection() is called, if possible
info (None) – a dict of info as returned by load_coco_detection_annotations(). If not provided, this info will be extracted when log_collection() is called, if possible
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels

property requires_image_metadata¶: Whether this exporter requires fiftyone.core.metadata.ImageMetadata instances for each sample being exported.

property label_cls¶

The fiftyone.core.labels.Label class(es) exported by this exporter.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports labels of this type
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the exporter can handle label dictionaries with value-types specified by this dictionary. Not all keys need be present in the exported label dicts
None. In this case, the exporter makes no guarantees about the labels that it can export

setup()¶

Performs any necessary setup before exporting the first sample in the dataset.

This method is called when the exporter’s context manager interface is entered, DatasetExporter.__enter__().

log_collection(sample_collection)¶

Logs any relevant information about the fiftyone.core.collections.SampleCollection whose samples will be exported.

Subclasses can optionally implement this method if their export format can record information such as the fiftyone.core.collections.SampleCollection.info() or fiftyone.core.collections.SampleCollection.classes() of the collection being exported.

By convention, this method must be optional; i.e., if it is not called before the first call to export_sample(), then the exporter must make do without any information about the fiftyone.core.collections.SampleCollection (which may not be available, for example, if the samples being exported are not stored in a collection).

Parameters: sample_collection – the fiftyone.core.collections.SampleCollection whose samples will be exported

export_sample(image_or_path, detections, metadata=None)¶

Exports the given sample to the dataset.

Parameters

image_or_path – an image or the path to the image on disk
label – an instance of label_cls(), or a dictionary mapping field names to fiftyone.core.labels.Label instances, or None if the sample is unlabeled
metadata (None) – a fiftyone.core.metadata.ImageMetadata instance for the sample. Only required when requires_image_metadata() is True

close(*args)¶

Performs any necessary actions after the last sample has been exported.

This method is called when the exporter’s context manager interface is exited, DatasetExporter.__exit__().

Parameters: *args – the arguments to DatasetExporter.__exit__()

class fiftyone.utils.coco.COCOObject(id, image_id, category_id, bbox, segmentation=None, area=None, iscrowd=None)¶

Bases: object

An object in COCO detection format.

Parameters

id – the ID of the annotation
image_id – the ID of the image in which the annotation appears
category_id – the category ID of the object
bbox – a bounding box for the object in [xmin, ymin, width, height] format
segmentation (None) – the segmentation data for the object
area (None) – the area of the bounding box, in pixels
iscrowd (None) – whether the detection is a crowd

to_polyline(frame_size, classes=None, supercategory_map=None, tolerance=None)¶

Returns a fiftyone.core.labels.Polyline representation of the object.

Parameters

frame_size – the (width, height) of the image
classes (None) – the list of classes
supercategory_map (None) – a dict mapping class names to supercategories
tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels

Returns

a fiftyone.core.labels.Polyline

to_detection(frame_size, classes=None, supercategory_map=None, load_segmentation=False)¶

Returns a fiftyone.core.labels.Detection representation of the object.

Parameters

frame_size – the (width, height) of the image
classes (None) – the list of classes
supercategory_map (None) – a dict mapping class names to supercategories
load_segmentation (False) – whether to load the segmentation mask for the object, if available

Returns

a fiftyone.core.labels.Detection

to_anno_dict()¶

Returns a COCO annotation dictionary representation of the object.

Returns: a COCO annotation dict

classmethod from_detection(detection, metadata, labels_map_rev=None, tolerance=None)¶

Creates a COCOObject from a fiftyone.core.labels.Detection.

Parameters

detection – a fiftyone.core.labels.Detection
metadata – a fiftyone.core.metadata.ImageMetadata for the image
labels_map_rev (None) – an optional dict mapping labels to category IDs
tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels

Returns

a COCOObject

classmethod from_anno_dict(d)¶

Creates a COCOObject from a COCO annotation dict.

Parameters: d – a COCO annotation dict
Returns: a COCOObject

fiftyone.utils.coco.load_coco_detection_annotations(json_path)¶

Loads the COCO annotations from the given JSON file.

See fiftyone.types.dataset_types.COCODetectionDataset for format details.

Parameters

json_path – the path to the annotations JSON file

Returns

a tuple of

info: a dict of dataset info
classes: a list of classes
supercategory_map: a dict mapping class labels to supercategories
images: a dict mapping image filenames to image dicts
annotations: a dict mapping image IDs to list of COCOObject instances, or None for unlabeled datasets

fiftyone.utils.coco.parse_coco_categories(categories)¶

Parses the COCO categories list.

The returned classes contains all class IDs from [0, max_id], inclusive.

Parameters

categories –

a dict of the form:

[
    ...
    {
        "id": 2,
        "name": "cat",
        "supercategory": "animal"
    },
    ...
]

Returns

a tuple of

classes: a list of classes
supercategory_map: a dict mapping class labels to supercategories

fiftyone.utils.coco.download_coco_dataset_split(dataset_dir, split, year='2017', cleanup=True)¶

Downloads and extracts the given split of the COCO dataset to the specified directory.

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")
cleanup (True) – whether to cleanup the zip files after extraction

Returns

a tuple of

images_dir: the path to the directory containing the extracted images
anno_path: the path to the annotations JSON file