# fiftyone.utils.openlabel¶

Utilities for working with datasets in OpenLABEL format.

Classes:

 OpenLABELAnnotations(media_type) Annotations parsed from OpenLABEL format able to be converted to FiftyOne labels. OpenLABELFrames(frame_objects) A collection of OpenLABELObject framewise. 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. Parses and collects OpenLABELObjects from object dictionaries. An interface for OpenLABELFramesParser or OpenLABELObjectsParser. OpenLABELStream([name, type, description, …]) An OpenLABEL stream corresponding to one uri or file_id. 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 = 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)

Importer for OpenLABEL image datasets stored on disk.

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. Returns the dataset info for the dataset. 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)

Importer for OpenLABEL video datasets stored on disk.

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. Returns the dataset info for the dataset. 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 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:

 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

Parses and collects OpenLABELObjects from object dictionaries.

Methods:

 add_object_dict(obj_id, obj_d) Parses the given raw object dictionary. 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)

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

Parses and collects OpenLABELObject framewise from object dictionaries

Methods:

 add_object_dict(obj_id, obj_d[, frame_number]) Parses the given raw object dictionary. 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)

Parameters

new_objects – either a dict of framewise :classOpenLABELObjects 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 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. Updates this stream with additional information.
update_stream_dict(d)

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

Returns

An OpenLABELStream

class fiftyone.utils.openlabel.OpenLABELMetadata(metadata_dict)

Bases: object

A parser and storage for OpenLABEL metadata.

Methods:

 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. 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