fiftyone.utils.openlabel¶

Utilities for working with datasets in OpenLABEL format.

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

Classes:

`OpenLABELAnnotations`(media_type)	Annotations parsed from OpenLABEL format able to be converted to FiftyOne labels.
`OpenLABELFrames`(frame_objects)	A collection of `OpenLABELObject` framewise.
`OpenLABELFramesParser`()	Parses and collects `OpenLABELObject` framewise from object dictionaries
`OpenLABELImageDatasetImporter`([dataset_dir, …])	Importer for OpenLABEL image datasets stored on disk.
`OpenLABELMetadata`(metadata_dict)	A parser and storage for OpenLABEL metadata.
`OpenLABELObject`([id, name, type, bboxes, …])	An object parsed from OpenLABEL labels.
`OpenLABELObjects`(objects)	A collection of `OpenLABELObject`.
`OpenLABELObjectsParser`()	Parses and collects `OpenLABELObjects` from object dictionaries.
`OpenLABELParser`()	An interface for `OpenLABELFramesParser` or `OpenLABELObjectsParser`.
`OpenLABELStream`([name, type, description, …])	An OpenLABEL stream corresponding to one uri or file_id.
`OpenLABELStreams`()	A collection of OpenLABEL streams.
`OpenLABELVideoDatasetImporter`([dataset_dir, …])	Importer for OpenLABEL video datasets stored on disk.
`SegmentationType`	The FiftyOne label type to load segmentations into

class fiftyone.utils.openlabel.SegmentationType¶

Bases: enum.Enum

The FiftyOne label type to load segmentations into

Attributes:

`INSTANCE`
`POLYLINE`
`SEMANTIC`

INSTANCE = 1¶

POLYLINE = 2¶

SEMANTIC = 3¶

class fiftyone.utils.openlabel.OpenLABELImageDatasetImporter(dataset_dir=None, data_path=None, labels_path=None, label_types=None, use_polylines=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledImageDatasetImporter, fiftyone.utils.data.importers.ImportPathsMixin

Importer for OpenLABEL image datasets stored on disk.

See this page for format details.

Parameters

dataset_dir (None) – the dataset directory. If omitted, data_path and/or labels_path must be provided
data_path (None) –
an optional parameter that enables explicit control over the location of the media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of dataset_dir where the media files reside
- an absolute directory path where the media files reside. In this case, the dataset_dir has no effect on the location of the data
- a filename like "data.json" specifying the filename of the JSON data manifest file in dataset_dir
- an absolute filepath specifying the location of the JSON data manifest. In this case, dataset_dir has no effect on the location of the data
- a dict mapping file_ids to absolute filepaths
If None, this parameter will default to whichever of data/ or data.json exists in the dataset directory
labels_path (None) –
an optional parameter that enables explicit control over the location of the labels. Can be any of the following:
- a filename like "labels.json" specifying the location of the labels in dataset_dir
- a folder name like "labels" or "labels/" specifying a subfolder of dataset_dir where the multiple label files reside
- an absolute filepath to the labels. In this case, dataset_dir has no effect on the location of the labels
If None, the parameter will default to looking for labels.json and label/
label_types (None) – a label type or list of label types to load. The supported values are ("detections", "segmentations", "keypoints"). By default, all labels are loaded
use_polylines (False) – whether to represent segmentations as fiftyone.core.labels.Polylines instances rather than fiftyone.core.labels.Detections with dense masks
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 load

Methods:

`close`(*args)	Performs any necessary actions after the last sample has been imported.
`get_dataset_info`()	Returns the dataset info for the dataset.
`setup`()	Performs any necessary setup before importing the first sample in the dataset.

Attributes:

`has_dataset_info`	Whether this importer produces a dataset info dictionary.
`has_image_metadata`	Whether this importer produces `fiftyone.core.metadata.ImageMetadata` instances for each image.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the importer can produce a single label field of any of these types
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.openlabel.OpenLABELVideoDatasetImporter(dataset_dir=None, data_path=None, labels_path=None, label_types=None, use_polylines=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledVideoDatasetImporter, fiftyone.utils.data.importers.ImportPathsMixin

Importer for OpenLABEL video datasets stored on disk.

See this page for format details.

Parameters

dataset_dir (None) – the dataset directory. If omitted, data_path and/or labels_path must be provided
data_path (None) –
an optional parameter that enables explicit control over the location of the media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of dataset_dir where the media files reside
- an absolute directory path where the media files reside. In this case, the dataset_dir has no effect on the location of the data
- a filename like "data.json" specifying the filename of the JSON data manifest file in dataset_dir
- an absolute filepath specifying the location of the JSON data manifest. In this case, dataset_dir has no effect on the location of the data
- a dict mapping file_ids to absolute filepaths
If None, this parameter will default to whichever of data/ or data.json exists in the dataset directory
labels_path (None) –
an optional parameter that enables explicit control over the location of the labels. Can be any of the following:
- a filename like "labels.json" specifying the location of the labels in dataset_dir
- a folder name like "labels" or "labels/" specifying a subfolder of dataset_dir where the multiple label files reside
- an absolute filepath to the labels. In this case, dataset_dir has no effect on the location of the labels
If None, the parameter will default to looking for labels.json and labels/
label_types (None) – a label type or list of label types to load. The supported values are ("detections", "segmentations", "keypoints"). By default, all labels are loaded
use_polylines (False) – whether to represent segmentations as fiftyone.core.labels.Polylines instances rather than fiftyone.core.labels.Detections with dense masks
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 load

Methods:

`close`(*args)	Performs any necessary actions after the last sample has been imported.
`get_dataset_info`()	Returns the dataset info for the dataset.
`setup`()	Performs any necessary setup before importing the first sample in the dataset.

Attributes:

`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer within the frame labels that it produces.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.
`has_video_metadata`	Whether this importer produces `fiftyone.core.metadata.VideoMetadata` instances for each video.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer within the sample-level labels that it produces.

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

property has_video_metadata¶: Whether this importer produces fiftyone.core.metadata.VideoMetadata instances for each video.

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this importer within the sample-level labels that it produces.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the importer is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the importer can produce a single sample-level label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the importer will return sample-level 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 sample-level 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__()

property frame_labels_cls¶

The fiftyone.core.labels.Label class(es) returned by this importer within the frame labels that it produces.

This can be any of the following:

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

class fiftyone.utils.openlabel.OpenLABELAnnotations(media_type)¶

Bases: object

Annotations parsed from OpenLABEL format able to be converted to FiftyOne labels.

Parameters: media_type – whether the annotations correspond to images (fiftyone.core.media.IMAGE) or videos (fiftyone.core.media.VIDEO)

Methods:

`get_objects`(uri)	Get the `OpenLABELObjects` or `OpenLABELFrames` corresponding to a given uri.
`get_stream`(uri)	Get the `OpenLABELStream` corresponding to a given uri.
`parse_labels`(base_dir, labels_path)	Parses a single OpenLABEL labels file.

parse_labels(base_dir, labels_path)¶

Parses a single OpenLABEL labels file.

Parameters

base_dir – path to the directory containing the labels file
labels_path – path to the labels json file

Returns

a list of potential file_ids that the parsed labels correspond to

get_objects(uri)¶

Get the OpenLABELObjects or OpenLABELFrames corresponding to a given uri.

Parameters: uri – the uri of the media for which to get objects
Returns: the OpenLABELObjects or OpenLABELFrames corresponding to the given uri

get_stream(uri)¶

Get the OpenLABELStream corresponding to a given uri.

Parameters: uri – the uri of the media for which to get the stream
Returns: the OpenLABELStream corresponding to the given uri

class fiftyone.utils.openlabel.OpenLABELParser¶

Bases: object

An interface for OpenLABELFramesParser or OpenLABELObjectsParser.

Methods:

to_stream_objects_map()

Get the parsed objects for each stream.

to_stream_objects_map()¶

Get the parsed objects for each stream.

Returns: a dict mapping streams to openLABEL objects or frames

class fiftyone.utils.openlabel.OpenLABELObjectsParser¶

Bases: fiftyone.utils.openlabel.OpenLABELParser

Parses and collects OpenLABELObjects from object dictionaries.

Methods:

`add_object_dict`(obj_id, obj_d)	Parses the given raw object dictionary.
`to_stream_objects_map`()	Get the parsed objects for each stream.

add_object_dict(obj_id, obj_d)¶

Parses the given raw object dictionary.

Parameters

obj_id – the string id of the given object
obj_d – a dict containing object information to parse

to_stream_objects_map()¶

Get the parsed objects for each stream.

Returns: a dict mapping streams to openLABEL objects or frames

class fiftyone.utils.openlabel.OpenLABELObjects(objects)¶

Bases: object

A collection of OpenLABELObject.

Parameters: objects – a list of OpenLABELObject

Methods:

`add_objects`(new_objects)	Adds additional OpenLABEL objects to this collection.
`to_labels`(frame_size, label_types[, seg_type])	Converts the stored `OpenLABELObject` to FiftyOne labels.

add_objects(new_objects)¶

Adds additional OpenLABEL objects to this collection.

Parameters: new_objects – either a list of OpenLABELObject or a different OpenLABELObjects

to_labels(frame_size, label_types, seg_type=<SegmentationType.INSTANCE: 1>)¶

Converts the stored OpenLABELObject to FiftyOne labels.

Parameters

frame_size – the size of the image frame in pixels (width, height)
label_types – a list of label types to load
seg_type (SegmentationType.INSTANCE) – the type to use to store segmentations

Returns

a dict mapping the specified label types to FiftyOne labels

class fiftyone.utils.openlabel.OpenLABELFramesParser¶

Bases: fiftyone.utils.openlabel.OpenLABELParser

Parses and collects OpenLABELObject framewise from object dictionaries

Methods:

`add_object_dict`(obj_id, obj_d[, frame_number])	Parses the given raw object dictionary.
`to_stream_objects_map`()	Get the parsed objects for each stream.

add_object_dict(obj_id, obj_d, frame_number=None)¶

Parses the given raw object dictionary.

Parameters

obj_id – the string id of the given object
obj_d – a dict containing object information to parse
frame_number (None) – the frame number corresponding to the given object

to_stream_objects_map()¶

Get the parsed objects for each stream.

Returns: a dict mapping streams to openLABEL objects or frames

class fiftyone.utils.openlabel.OpenLABELFrames(frame_objects)¶

Bases: object

A collection of OpenLABELObject framewise.

Parameters: frame_objects – a dict mapping frame numbers to OpenLABELObject

Methods:

`add_objects`(new_objects)	Adds additional OpenLABEL frames to this collection.
`to_labels`(frame_size, label_types[, seg_type])	Converts the stored `OpenLABELObject` to FiftyOne labels

to_labels(frame_size, label_types, seg_type=<SegmentationType.POLYLINE: 2>)¶

Converts the stored OpenLABELObject to FiftyOne labels

Parameters

frame_size – the size of the image frame in pixels (width, height)
label_types – a list of label types to load
seg_type (SegmentationType.INSTANCE) – the type to use to store segmentations

Returns

a dict mapping frame numbers to dicts mapping the specified label types to FiftyOne labels

add_objects(new_objects)¶

Adds additional OpenLABEL frames to this collection.

Parameters: new_objects – either a dict of framewise :class`OpenLABELObjects` or a different OpenLABELFrames

class fiftyone.utils.openlabel.OpenLABELStreams¶

Bases: object

A collection of OpenLABEL streams.

Methods:

`add_stream_dict`(stream_name, stream_d)	Parses the given raw stream dictionary.
`get_one_stream`(uri)	Get the OpenLABELStream corresponding to a given uri or file_id.

Attributes:

uris

The list of uris or file_ids corresponding to the streams in this collection

property uris¶: The list of uris or file_ids corresponding to the streams in this collection

add_stream_dict(stream_name, stream_d)¶

Parses the given raw stream dictionary.

Parameters

stream_name – the name of the stream being parsed
stream_d – a dict containing stream information to parse

get_one_stream(uri)¶

Get the OpenLABELStream corresponding to a given uri or file_id.

Parameters: uri – the uri or file_id for which to get the stream
Returns: An OpenLABELStream

class fiftyone.utils.openlabel.OpenLABELStream(name=None, type=None, description=None, uri=None, properties=None)¶

Bases: object

An OpenLABEL stream corresponding to one uri or file_id.

Parameters

name (None) – the name of the stream
type (None) – the type of the stream
description (None) – a string description for this stream
uri (None) – the uri or file_id of the media corresponding to this stream
properties (None) – a dict of properties for this stream

Methods:

`from_anno_dict`(stream_name, d)	Create an OpenLABEL stream from the stream information dictionary.
`update_stream_dict`(d)	Updates this stream with additional information.

update_stream_dict(d)¶

Updates this stream with additional information.

Parameters: d – a dict containing additional stream information

classmethod from_anno_dict(stream_name, d)¶

Create an OpenLABEL stream from the stream information dictionary.

Parameters

stream_name – the name of the stream
d – a dict containing information about this stream

Returns

An OpenLABELStream

class fiftyone.utils.openlabel.OpenLABELMetadata(metadata_dict)¶

Bases: object

A parser and storage for OpenLABEL metadata.

Methods:

parse_potential_file_ids()

Parses metadata for any fields that may correspond to a label-wide media file_id.

parse_potential_file_ids()¶

Parses metadata for any fields that may correspond to a label-wide media file_id.

Returns: a list of potential file_id strings

class fiftyone.utils.openlabel.OpenLABELObject(id=None, name=None, type=None, bboxes=None, segmentations=None, keypoints=None, stream=None, attributes=None)¶

Bases: object

An object parsed from OpenLABEL labels.

Parameters

id (None) – the OpenLABEL id string for this object
name (None) – the name string of the object
type (None) – the type string of the object
bboxes ([]) – a list of absolute bounding box coordinates for this object
segmentations ([]) – a list of aboslute polygon segmentations for this object
keyponts ([]) – a list of absolute keypoint coordinates for this object
stream (None) – the OpenLABELStream this object corresponds to
attributes ({}) – a dict of attributes and their values for this object

Methods:

`from_anno_dict`(anno_id, d)	Create an `OpenLABELObject` from the raw label dictionary.
`to_detections`(frame_size)	Converts the bounding boxes in this object to `fiftyone.core.labels.Detection` objects.
`to_keypoints`(frame_size)	Converts the keypoints in this object to `fiftyone.core.labels.Keypoint` objects.
`to_polylines`(frame_size)	Converts the segmentations in this object to `fiftyone.core.labels.Polyline` objects.
`update_object_dict`(d)	Updates this `OpenLABELObject` given the raw label dictionary.

to_detections(frame_size)¶

Converts the bounding boxes in this object to fiftyone.core.labels.Detection objects.

Parameters: frame_size – the size of the frame in pixels (width, height)
Returns: a list of fiftyone.core.labels.Detection objects for each bounding box in this object

to_polylines(frame_size)¶

Converts the segmentations in this object to fiftyone.core.labels.Polyline objects.

Parameters: frame_size – the size of the frame in pixels (width, height)
Returns: a list of fiftyone.core.labels.Polyline objects for each polyline in this object

to_keypoints(frame_size)¶

Converts the keypoints in this object to fiftyone.core.labels.Keypoint objects.

Parameters: frame_size – the size of the frame in pixels (width, height)
Returns: a list of fiftyone.core.labels.Keypoint objects for each keypoint in this object

classmethod from_anno_dict(anno_id, d)¶

Create an OpenLABELObject from the raw label dictionary.

Parameters

anno_id – id of the object
d – dict containing the information for this object

Returns

a tuple containing the OpenLABELObject and the frame numbers the object corresponds to, if any.

update_object_dict(d)¶

Updates this OpenLABELObject given the raw label dictionary.

Parameters: d – dict containing the information for this object
Returns: newly parsed frame numbers the object corresponds to, if any