fiftyone.utils.coco¶
Utilities for working with datasets in COCO format.
Classes
|
Exporter that writes COCO detection datasets to disk. |
|
Importer for COCO detection datasets stored on disk. |
|
Parser for samples in COCO Object Detection Format. |
|
An object in COCO detection format. |
Functions
|
Downloads and extracts the given split of the COCO dataset to the specified directory. |
|
Loads the COCO annotations from the given JSON file. |
|
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 vianp.asarray()
or the path to an image on diskanno_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 beNone
.
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 labelssupercategory_map (None) – a dict mapping class labels to supercategories. If provided,
supercategory
attributes will be added to all parsed detectionsload_segmentations (True) – whether to load segmentation masks, if available
return_polylines (False) – whether to return
fiftyone.core.labels.Polylines
instances rather thanfiftyone.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 typea 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 labelsNone
. 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 tofiftyone.core.labels.Label
instances, orNone
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 thanfiftyone.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 typea 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 labelsNone
. 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 possibleinfo (None) – a dict of info as returned by
load_coco_detection_annotations()
. If not provided, this info will be extracted whenlog_collection()
is called, if possibleimage_format (None) – the image format to use when writing in-memory images to disk. By default,
fiftyone.config.default_image_ext
is usedtolerance (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 typea 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 dictsNone
. 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()
orfiftyone.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 thefiftyone.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 tofiftyone.core.labels.Label
instances, orNone
if the sample is unlabeledmetadata (None) – a
fiftyone.core.metadata.ImageMetadata
instance for the sample. Only required whenrequires_image_metadata()
isTrue
-
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]
formatsegmentation (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 imageclasses (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
-
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 imageclasses (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
-
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 afiftyone.core.labels.Detection
.- Parameters
detection – a
fiftyone.core.labels.Detection
metadata – a
fiftyone.core.metadata.ImageMetadata
for the imagelabels_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
-
classmethod
from_anno_dict
(d)¶ Creates a
COCOObject
from a COCO annotation dict.- Parameters
d – a COCO annotation dict
- Returns
-
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, orNone
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