fiftyone.utils.data¶

Module contents¶

Data utilities.

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

Functions:

`parse_images_dir`(dataset_dir[, recursive])	Parses the contents of the given directory of images.
`parse_videos_dir`(dataset_dir[, recursive])	Parses the contents of the given directory of videos.
`parse_image_classification_dir_tree`(dataset_dir)	Parses the contents of the given image classification dataset directory tree, which should have the following format.
`download_image_classification_dataset`(…[, …])	Downloads the classification dataset specified by the given CSV file, which should have the following format.
`download_images`(image_urls, output_dir[, …])	Downloads the images from the given URLs.
`build_dataset_exporter`(dataset_type[, …])	Builds the `DatasetExporter` instance for the given parameters.
`build_dataset_importer`(dataset_type[, …])	Builds the `DatasetImporter` instance for the given parameters.
`convert_dataset`([input_dir, input_type, …])	Converts a dataset stored on disk to another format on disk.
`export_samples`(samples[, export_dir, …])	Exports the given samples to disk.
`write_dataset`(samples, sample_parser, …[, …])	Writes the samples to disk as a dataset in the specified format.
`get_document`(name)	Get a registered Document class by name.
`import_samples`(dataset, dataset_importer[, …])	Adds the samples from the given `DatasetImporter` to the dataset.
`merge_samples`(dataset, dataset_importer[, …])	Merges the samples from the given `DatasetImporter` into the dataset.
`parse_dataset_info`(dataset, info[, overwrite])	Parses the info returned by `DatasetImporter.get_dataset_info()` and stores it on the relevant properties of the dataset.
`add_images`(dataset, samples, sample_parser)	Adds the given images to the dataset.
`add_labeled_images`(dataset, samples, …[, …])	Adds the given labeled images to the dataset.
`add_videos`(dataset, samples, sample_parser)	Adds the given videos to the dataset.
`add_labeled_videos`(dataset, samples, …[, …])	Adds the given labeled videos to the dataset.

Classes:

`defaultdict`	defaultdict(default_factory=None, /, […]) –> dict with default factory
`FiftyOneLabeledImageSampleParser`(label_field)	Parser for `fiftyone.core.sample.Sample` instances that contain labeled images.
`FiftyOneLabeledVideoSampleParser`([…])	Parser for `fiftyone.core.sample.Sample` instances that contain labeled videos.
`FiftyOneUnlabeledImageSampleParser`([…])	Parser for `fiftyone.core.sample.Sample` instances that contain images.
`FiftyOneUnlabeledMediaSampleParser`([…])	Parser for `fiftyone.core.sample.Sample` instances that contain unlabeled media.
`FiftyOneUnlabeledVideoSampleParser`([…])	Parser for `fiftyone.core.sample.Sample` instances that contain videos.
`ImageClassificationSampleParser`([classes])	Generic parser for image classification(s) samples whose labels are represented as `fiftyone.core.labels.Classification` instances.
`ImageSampleParser`()	Sample parser that parses unlabeled image samples.
`ExportPathsMixin`()	Mixin for `DatasetExporter` classes that provides convenience methods for parsing the `data_path`, `labels_path`, and `export_media` parameters supported by many exporters.
`MediaExporter`(export_mode[, export_path, …])	Base class for `DatasetExporter` utilities that provide support for populating a directory or manifest of media files.
`ImageExporter`(*args[, default_ext])	Utility class for `DatasetExporter` instances that export images.
`VideoExporter`(*args[, default_ext])	Utility class for `DatasetExporter` instances that export videos.
`DatasetExporter`([export_dir])	Base interface for exporting datasets.
`BatchDatasetExporter`([export_dir])	Base interface for exporters that export entire `fiftyone.core.collections.SampleCollection` instances in a single batch.
`GenericSampleDatasetExporter`([export_dir])	Interface for exporting datasets of arbitrary `fiftyone.core.sample.Sample` instances.
`GroupDatasetExporter`([export_dir])	Interface for exporting grouped datasets.
`UnlabeledImageDatasetExporter`([export_dir])	Interface for exporting datasets of unlabeled image samples.
`UnlabeledVideoDatasetExporter`([export_dir])	Interface for exporting datasets of unlabeled video samples.
`UnlabeledMediaDatasetExporter`([export_dir])	Interface for exporting datasets of unlabeled samples.
`LabeledImageDatasetExporter`([export_dir])	Interface for exporting datasets of labeled image samples.
`LabeledVideoDatasetExporter`([export_dir])	Interface for exporting datasets of labeled video samples.
`LegacyFiftyOneDatasetExporter`(export_dir[, …])	Legacy exporter that writes an entire FiftyOne dataset to disk in a serialized JSON format along with its source media.
`FiftyOneDatasetExporter`(export_dir[, …])	Exporter that writes an entire FiftyOne dataset to disk in a serialized JSON format along with its source media.
`ImageDirectoryExporter`(export_dir[, …])	Exporter that writes a directory of images to disk.
`VideoDirectoryExporter`(export_dir[, …])	Exporter that writes a directory of videos to disk.
`MediaDirectoryExporter`(export_dir[, …])	Exporter that writes a directory of media files of arbitrary type to disk.
`FiftyOneImageClassificationDatasetExporter`([…])	Exporter that writes an image classification dataset to disk in a simple JSON format.
`ImageClassificationDirectoryTreeExporter`(…)	Exporter that writes an image classification directory tree to disk.
`VideoClassificationDirectoryTreeExporter`(…)	Exporter that writes a video classification directory tree to disk.
`FiftyOneImageDetectionDatasetExporter`([…])	Exporter that writes an image detection dataset to disk in a simple JSON format.
`FiftyOneTemporalDetectionDatasetExporter`([…])	Exporter that writes a temporal video detection dataset to disk in a simple JSON format.
`ImageSegmentationDirectoryExporter`([…])	Exporter that writes an image segmentation dataset to disk.
`FiftyOneImageLabelsDatasetExporter`(export_dir)	Exporter that writes a labeled image dataset to disk with labels stored in ETA ImageLabels format.
`FiftyOneVideoLabelsDatasetExporter`(export_dir)	Exporter that writes a labeled video dataset with labels stored in ETA VideoLabels format.
`datetime`(year, month, day[, hour[, minute[, …)	The year, month and day arguments are required.
`Sample`(filepath[, tags, metadata])	A sample in a `fiftyone.core.dataset.Dataset`.
`FiftyOneImageClassificationSampleParser`([…])	Parser for samples in FiftyOne image classification datasets.
`FiftyOneTemporalDetectionSampleParser`([…])	Parser for samples in FiftyOne temporal detection datasets.
`FiftyOneImageDetectionSampleParser`([classes])	Parser for samples in FiftyOne image detection datasets.
`FiftyOneImageLabelsSampleParser`([prefix, …])	Parser for samples in FiftyOne image labels datasets.
`FiftyOneVideoLabelsSampleParser`([prefix, …])	Parser for samples in FiftyOne video labels datasets.
`ImportPathsMixin`()	Mixin for `DatasetImporter` classes that provides convenience methods for parsing the `data_path` and `labels_path` parameters supported by many importers.
`DatasetImporter`([dataset_dir, shuffle, …])	Base interface for importing datasets stored on disk into FiftyOne.
`BatchDatasetImporter`([dataset_dir, shuffle, …])	Base interface for importers that load all of their samples in a single call to `import_samples()`.
`GenericSampleDatasetImporter`([dataset_dir, …])	Interface for importing datasets that contain arbitrary `fiftyone.core.sample.Sample` instances.
`GroupDatasetImporter`([dataset_dir, shuffle, …])	Interface for importing datasets that contain arbitrary grouped `fiftyone.core.sample.Sample` instances.
`UnlabeledImageDatasetImporter`([dataset_dir, …])	Interface for importing datasets of unlabeled image samples.
`UnlabeledVideoDatasetImporter`([dataset_dir, …])	Interface for importing datasets of unlabeled video samples.
`UnlabeledMediaDatasetImporter`([dataset_dir, …])	Interface for importing datasets of unlabeled media samples.
`LabeledImageDatasetImporter`([dataset_dir, …])	Interface for importing datasets of labeled image samples.
`LabeledVideoDatasetImporter`([dataset_dir, …])	Interface for importing datasets of labeled video samples.
`LegacyFiftyOneDatasetImporter`(dataset_dir[, …])	Legacy importer for FiftyOne datasets stored on disk in a serialized JSON format.
`FiftyOneDatasetImporter`(dataset_dir[, …])	Importer for FiftyOne datasets stored on disk in serialized JSON format.
`ImageDirectoryImporter`(dataset_dir[, …])	Importer for a directory of images stored on disk.
`VideoDirectoryImporter`(dataset_dir[, …])	Importer for a directory of videos stored on disk.
`MediaDirectoryImporter`(dataset_dir[, …])	Importer for a directory of media files stored on disk.
`FiftyOneImageClassificationDatasetImporter`([…])	Importer for image classification datasets stored on disk in a simple JSON format.
`ImageClassificationDirectoryTreeImporter`(…)	Importer for an image classification directory tree stored on disk.
`VideoClassificationDirectoryTreeImporter`(…)	Importer for a viideo classification directory tree stored on disk.
`FiftyOneImageDetectionDatasetImporter`([…])	Importer for image detection datasets stored on disk in a simple JSON format.
`FiftyOneTemporalDetectionDatasetImporter`([…])	Importer for temporal video detection datasets stored on disk in a simple JSON format.
`ImageSegmentationDirectoryImporter`([…])	Importer for image segmentation datasets stored on disk.
`FiftyOneImageLabelsDatasetImporter`(dataset_dir)	Importer for labeled image datasets whose labels are stored in ETA ImageLabels format.
`FiftyOneVideoLabelsDatasetImporter`(dataset_dir)	Importer for labeled video datasets whose labels are stored in ETA VideoLabels format.
`ImageIngestor`(dataset_dir[, image_format])	Mixin for `fiftyone.utils.data.importers.DatasetImporter` instances that ingest images into the provided `dataset_dir` during import.
`UnlabeledImageDatasetIngestor`(dataset_dir, …)	Dataset importer that ingests unlabeled images into the provided `dataset_dir` during import.
`LabeledImageDatasetIngestor`(dataset_dir, …)	Dataset importer that ingests labeled images into the provided `dataset_dir` during import.
`VideoIngestor`(dataset_dir)	Mixin for `fiftyone.utils.data.importers.DatasetImporter` instances that ingest videos into the provided `dataset_dir` during import.
`UnlabeledVideoDatasetIngestor`(dataset_dir, …)	Dataset importer that ingests unlabeled videos into the provided `dataset_dir` during import.
`LabeledVideoDatasetIngestor`(dataset_dir, …)	Dataset importer that ingests labeled videos into the provided `dataset_dir` during import.
`SampleParser`()	Base interface for sample parsers.
`UnlabeledImageSampleParser`()	Interface for `SampleParser` instances that parse unlabeled image samples.
`UnlabeledVideoSampleParser`()	Interface for `SampleParser` instances that parse unlabeled video samples.
`UnlabeledMediaSampleParser`()	Interface for `SampleParser` instances that parse unlabeled media samples.
`VideoSampleParser`()	Sample parser that parses unlabeled video samples.
`MediaSampleParser`()	Sample parser that parses unlabeled media samples.
`LabeledImageSampleParser`()	Interface for `SampleParser` instances that parse labeled image samples.
`LabeledVideoSampleParser`()	Interface for `SampleParser` instances that parse labeled video samples.
`LabeledImageTupleSampleParser`()	Generic sample parser that parses samples that are `(image_or_path, label)` tuples, where:
`ImageDetectionSampleParser`([label_field, …])	Generic parser for image detection samples whose labels are represented as `fiftyone.core.labels.Detections` instances.
`ImageLabelsSampleParser`([prefix, …])	Generic parser for multitask image prediction samples whose labels are stored in `eta.core.image.ImageLabels` format.
`VideoLabelsSampleParser`([prefix, …])	Generic parser for labeled video samples whose labels are represented in `eta.core.video.VideoLabels` format.
`ExtractClipsMixin`([compute_metadata, …])	Mixin for sample parsers that extract clips from `fiftyone.core.clips.ClipView` instances.

fiftyone.utils.data.parse_images_dir(dataset_dir, recursive=True)¶

Parses the contents of the given directory of images.

Parameters

dataset_dir – the dataset directory
recursive (True) – whether to recursively traverse subdirectories

Returns

a list of image paths

fiftyone.utils.data.parse_videos_dir(dataset_dir, recursive=True)¶

Parses the contents of the given directory of videos.

Parameters

dataset_dir – the dataset directory
recursive (True) – whether to recursively traverse subdirectories

Returns

a list of video paths

fiftyone.utils.data.parse_image_classification_dir_tree(dataset_dir)¶

Parses the contents of the given image classification dataset directory tree, which should have the following format:

<dataset_dir>/
    <classA>/
        <image1>.<ext>
        <image2>.<ext>
        ...
    <classB>/
        <image1>.<ext>
        <image2>.<ext>
        ...

Parameters: dataset_dir – the dataset directory
Returns: a list of (image_path, target) pairs classes: a list of class label strings
Return type: samples

fiftyone.utils.data.download_image_classification_dataset(csv_path, dataset_dir, classes=None, num_workers=None)¶

Downloads the classification dataset specified by the given CSV file, which should have the following format:

<label1>,<image_url1>
<label2>,<image_url2>
...

The image filenames are the basenames of the URLs, which are assumed to be unique.

The dataset is written to disk in fiftyone.types.FiftyOneImageClassificationDataset format.

Parameters

csv_path – a CSV file containing the labels and image URLs
dataset_dir – the directory to write the dataset
classes (None) – an optional list of classes. By default, this will be inferred from the contents of csv_path
num_workers (None) – a suggested number of threads to use to download images

fiftyone.utils.data.download_images(image_urls, output_dir, num_workers=None)¶

Downloads the images from the given URLs.

The filenames in output_dir are the basenames of the URLs, which are assumed to be unique.

Parameters

image_urls – a list of image URLs to download
output_dir – the directory to write the images
num_workers (None) – a suggested number of threads to use

Returns

the list of downloaded image paths

fiftyone.utils.data.build_dataset_exporter(dataset_type, strip_none=True, warn_unused=True, **kwargs)¶

Builds the DatasetExporter instance for the given parameters.

Parameters

dataset_type – the fiftyone.types.Dataset type
strip_none (True) – whether to exclude None-valued items from kwargs
warn_unused (True) – whether to issue warnings for any non-None unused parameters encountered
**kwargs – keyword arguments to pass to the dataset exporter’s constructor via DatasetExporter(**kwargs)

Returns

the DatasetExporter instance
a dict of unused keyword arguments

Return type

a tuple of

fiftyone.utils.data.build_dataset_importer(dataset_type, strip_none=True, warn_unused=True, name=None, **kwargs)¶

Builds the DatasetImporter instance for the given parameters.

Parameters

dataset_type – the fiftyone.types.Dataset type
strip_none (True) – whether to exclude None-valued items from kwargs
warn_unused (True) – whether to issue warnings for any non-None unused parameters encountered
name (None) – the name of the dataset being imported into, if known
**kwargs – keyword arguments to pass to the dataset importer’s constructor via DatasetImporter(**kwargs)

Returns

the DatasetImporter instance
a dict of unused keyword arguments

Return type

a tuple of

fiftyone.utils.data.convert_dataset(input_dir=None, input_type=None, input_kwargs=None, dataset_importer=None, output_dir=None, output_type=None, output_kwargs=None, dataset_exporter=None, overwrite=False)¶

Converts a dataset stored on disk to another format on disk.

The input dataset may be specified by providing either an input_dir and a corresponding input_type or by providing a dataset_importer.

The output dataset may be specified by providing either an output_dir and a corresponding output_type or by providing a dataset_exporter.

Parameters

input_dir (None) – the input dataset directory
input_type (None) – the fiftyone.types.Dataset type of the dataset in input_dir
input_kwargs (None) – optional kwargs dict to pass to the constructor of the fiftyone.utils.data.importers.DatasetImporter for the input_type you specify
dataset_importer (None) – a fiftyone.utils.data.importers.DatasetImporter to use to import the input dataset
output_dir (None) – the directory to which to write the output dataset
output_type (None) – the fiftyone.types.Dataset type to write to output_dir
output_kwargs (None) – optional kwargs dict to pass to the constructor of the fiftyone.utils.data.exporters.DatasetExporter for the output_type you specify
dataset_exporter (None) – a fiftyone.utils.data.exporters.DatasetExporter to use to export the dataset
overwrite (False) – whether to delete existing directories before performing the export (True) or to merge the export with existing files and directories (False)

class fiftyone.utils.data.defaultdict¶

Bases: dict

defaultdict(default_factory=None, /, […]) –> dict with default factory

The default factory is called without arguments to produce a new value when a key is not present, in __getitem__ only. A defaultdict compares equal to a dict with the same items. All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.

Methods:

`clear`()
`copy`()
`fromkeys`([value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(k[,d])	If key is not found, default is returned if given, otherwise KeyError is raised
`popitem`()	Remove and return a (key, value) pair as a 2-tuple.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()

Attributes:

default_factory

Factory for default value called by __missing__().

clear() → None. Remove all items from D.¶

copy() → a shallow copy of D.¶

default_factory¶: Factory for default value called by __missing__().

fromkeys(value=None, /)¶: Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)¶: Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D’s items¶

keys() → a set-like object providing a view on D’s keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, default is returned if given, otherwise KeyError is raised

popitem()¶

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)¶

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.¶: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D’s values¶

class fiftyone.utils.data.FiftyOneLabeledImageSampleParser(label_field, label_fcn=None, compute_metadata=False)¶

Bases: fiftyone.utils.data.parsers.LabeledImageSampleParser

Parser for fiftyone.core.sample.Sample instances that contain labeled images.

Parameters

label_field – the name of the label field to parse, or a dictionary mapping label field names to keys for the return label dictionaries
label_fcn (None) – an optional function or dictionary mapping label field names to functions (must match label_field) to apply to each label before returning it
compute_metadata (False) – whether to compute fiftyone.core.metadata.ImageMetadata instances on-the-fly if get_image_metadata() is called and no metadata is available

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

get_image_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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

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.data.FiftyOneLabeledVideoSampleParser(label_field=None, frame_labels_field=None, label_fcn=None, frame_labels_fcn=None, compute_metadata=False, write_clips=True, clip_dir=None, video_format=None)¶

Bases: fiftyone.utils.data.parsers.ExtractClipsMixin, fiftyone.utils.data.parsers.LabeledVideoSampleParser

Parser for fiftyone.core.sample.Sample instances that contain labeled videos.

This class also supports fiftyone.core.clips.ClipView instances.

Parameters

label_field (None) – the name of a label field to parse, or a dictionary mapping label field names to output keys to use in the returned sample-level labels dictionary
frame_labels_field (None) – the name of a frame label field to parse, or a dictionary mapping field names to output keys describing the frame label fields to export
label_fcn (None) – an optional function or dictionary mapping label field names to functions (must match label_field) to apply to each sample label before returning it
frame_labels_fcn (None) – an optional function or dictionary mapping frame label field names to functions (must match frame_labels_field) to apply to each frame label before returning it
compute_metadata (False) – whether to compute fiftyone.core.metadata.VideoMetadata instances on-the-fly if get_video_metadata() is called and no metadata is available
write_clips (True) – whether to write clips when get_video_path() is called
clip_dir (None) – a directory to write clips. Only applicable when parsing fiftyone.core.clips.ClipView instances
video_format (None) – the video format to use when writing video clips to disk. By default, fiftyone.config.default_video_ext is used

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the sample-level labels that it produces.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the frame labels that it produces.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`get_label`()	Returns the sample-level labels for the current sample.
`get_frame_labels`()	Returns the frame labels for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser 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 parser is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the sample-level labels that it may return

property frame_labels_cls¶

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

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the frame labels that it may return

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

get_label()¶

Returns the sample-level labels 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 has no sample-level labels

get_frame_labels()¶

Returns the frame labels for the current sample.

Returns: a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame, or None if the sample has no frame labels

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

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.data.FiftyOneUnlabeledImageSampleParser(compute_metadata=False)¶

Bases: fiftyone.utils.data.parsers.UnlabeledImageSampleParser

Parser for fiftyone.core.sample.Sample instances that contain images.

Parameters: compute_metadata (False) – whether to compute fiftyone.core.metadata.ImageMetadata instances on-the-fly if get_image_metadata() is called and no metadata is available

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

get_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

get_image_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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

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.data.FiftyOneUnlabeledMediaSampleParser(compute_metadata=False)¶

Bases: fiftyone.utils.data.parsers.MediaSampleParser

Parser for fiftyone.core.sample.Sample instances that contain unlabeled media.

Parameters: compute_metadata (False) – whether to compute fiftyone.core.metadata.Metadata instances on-the-fly if get_metadata() is called and no metadata is available

Attributes:

`has_metadata`	Whether this parser produces `fiftyone.core.metadata.Metadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_media_path`()	Returns the media path for the current sample.
`get_metadata`()	Returns the metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_media_path()¶

Returns the media path for the current sample.

Returns: the path to the media on disk

get_metadata()¶

Returns the metadata for the current sample.

Returns: a fiftyone.core.metadata.Metadata instance

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

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.data.FiftyOneUnlabeledVideoSampleParser(compute_metadata=False, write_clips=True, clip_dir=None, video_format=None)¶

Bases: fiftyone.utils.data.parsers.ExtractClipsMixin, fiftyone.utils.data.parsers.UnlabeledVideoSampleParser

Parser for fiftyone.core.sample.Sample instances that contain videos.

This class also supports fiftyone.core.clips.ClipView instances.

Parameters

compute_metadata (False) – whether to compute fiftyone.core.metadata.VideoMetadata instances on-the-fly if get_video_metadata() is called and no metadata is available
write_clips (True) – whether to write clips when get_video_path() is called
clip_dir (None) – a directory to write clips. Only applicable when parsing fiftyone.core.clips.ClipView instances
video_format (None) – the video format to use when writing video clips to disk. By default, fiftyone.config.default_video_ext is used

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.VideoMetadata instance

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

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.data.ImageClassificationSampleParser(classes=None)¶

Bases: fiftyone.utils.data.parsers.LabeledImageTupleSampleParser

Generic parser for image classification(s) samples whose labels are represented as fiftyone.core.labels.Classification instances.

This implementation supports samples that are (image_or_path, target) 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
target can be any of the following:
None, for unlabeled images

a label string or list of label strings

a class ID or list of class IDs, if classes is provided
a dict or list of dicts of the following form:
{
    "label": <label-or-target>,
    "confidence": <confidence>,
    "attributes": <optional-attributes>,
}
a fiftyone.core.labels.Classification or fiftyone.core.labels.Classifications instance

Parameters: classes (None) – an optional list of class label strings. If provided, it is assumed that target contains class ID that should be mapped to label strings via classes[target]

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.

Methods:

`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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.

Parameters: sample – the sample
Returns: a fiftyone.core.labels.Classification instance

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.data.ImageSampleParser¶

Bases: fiftyone.utils.data.parsers.UnlabeledImageSampleParser

Sample parser that parses unlabeled image samples.

This implementation assumes that the provided sample is either an image that can be converted to numpy format via np.asarray() or the path to an image on disk.

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`clear_sample`()	Clears the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

get_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

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_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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

fiftyone.utils.data.export_samples(samples, export_dir=None, dataset_type=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, dataset_exporter=None, label_field=None, frame_labels_field=None, progress=None, num_samples=None, **kwargs)¶

Exports the given samples to disk.

You can perform exports with this method via the following basic patterns:

Provide export_dir and dataset_type to export the content to a directory in the default layout for the specified format, as documented in this page
Provide dataset_type along with data_path, labels_path, and/or export_media to directly specify where to export the source media and/or labels (if applicable) in your desired format. This syntax provides the flexibility to, for example, perform workflows like labels-only exports
Provide a dataset_exporter to which to feed samples to perform a fully-customized export

In all workflows, the remaining parameters of this method can be provided to further configure the export.

See this page for more information about the available export formats and examples of using this method.

See this guide for more details about exporting datasets in custom formats by defining your own fiftyone.utils.data.exporters.DatasetExporter.

This method will automatically coerce the data to match the requested export in the following cases:

When exporting in either an unlabeled image or image classification format, if a spatial label field is provided (fiftyone.core.labels.Detection, fiftyone.core.labels.Detections, fiftyone.core.labels.Polyline, or fiftyone.core.labels.Polylines), then the image patches of the provided samples will be exported
When exporting in labeled image dataset formats that expect list-type labels (fiftyone.core.labels.Classifications, fiftyone.core.labels.Detections, fiftyone.core.labels.Keypoints, or fiftyone.core.labels.Polylines), if a label field contains labels in non-list format (e.g., fiftyone.core.labels.Classification), the labels will be automatically upgraded to single-label lists
When exporting in labeled image dataset formats that expect fiftyone.core.labels.Detections labels, if a fiftyone.core.labels.Classification field is provided, the labels will be automatically upgraded to detections that span the entire images

Parameters

samples – a fiftyone.core.collections.SampleCollection
export_dir (None) – the directory to which to export the samples in format dataset_type
dataset_type (None) – the fiftyone.types.Dataset type to write
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media for certain export formats. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the media
- an absolute directory path in which to export the media. In this case, the export_dir has no effect on the location of the data
- a filename like "data.json" specifying the filename of a JSON manifest file in export_dir generated when export_media is "manifest"
- an absolute filepath specifying the location to write the JSON manifest file when export_media is "manifest". In this case, export_dir has no effect on the location of the data
If None, a default value of this parameter will be chosen based on the value of the export_media parameter. Note that this parameter is not applicable to certain export formats such as binary types like TF records
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Only applicable when exporting in certain labeled dataset formats. Can be any of the following:
- a type-specific folder name like "labels" or "labels/" or a filename like "labels.json" or "labels.xml" specifying the location in export_dir in which to export the labels
- an absolute directory or filepath in which to export the labels. In this case, the export_dir has no effect on the location of the labels
For labeled datasets, the default value of this parameter will be chosen based on the export format so that the labels will be exported into export_dir
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media. This option is only useful when exporting labeled datasets whose label format stores sufficient information to locate the associated media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
If None, an appropriate default value of this parameter will be chosen based on the value of the data_path parameter. Note that some dataset formats may not support certain values for this parameter (e.g., when exporting in binary formats such as TF records, “symlink” is not an option)
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each media. When exporting media, this identifier is joined with data_path to generate an output path for each exported media. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
dataset_exporter (None) – a DatasetExporter to use to write the dataset
label_field (None) – the name of the label field to export, or a dictionary mapping field names to output keys describing the label fields to export. Only applicable if dataset_exporter is a LabeledImageDatasetExporter or LabeledVideoDatasetExporter, or if you are exporting image patches
frame_labels_field (None) – the name of the frame label field to export, or a dictionary mapping field names to output keys describing the frame label fields to export. Only applicable if dataset_exporter is a LabeledVideoDatasetExporter
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead
num_samples (None) – the number of samples in samples. If omitted, this is computed (if possible) via len(samples) if needed for progress tracking
**kwargs – optional keyword arguments to pass to the dataset exporter’s constructor. If you are exporting image patches, this can also contain keyword arguments for fiftyone.utils.patches.ImagePatchesExtractor

fiftyone.utils.data.write_dataset(samples, sample_parser, dataset_exporter, sample_collection=None, progress=None, num_samples=None)¶

Writes the samples to disk as a dataset in the specified format.

Parameters

samples – an iterable of samples that can be parsed by sample_parser
sample_parser – a fiftyone.utils.data.parsers.SampleParser to use to parse the samples
dataset_exporter – a DatasetExporter to use to write the dataset
sample_collection (None) – the fiftyone.core.collections.SampleCollection from which samples were extracted. If samples is itself a fiftyone.core.collections.SampleCollection, this parameter defaults to samples. This parameter is optional and is only passed to DatasetExporter.log_collection()
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead
num_samples (None) – the number of samples in samples. If omitted, this is computed (if possible) via len(samples) if needed for progress tracking

class fiftyone.utils.data.ExportPathsMixin¶

Bases: object

Mixin for DatasetExporter classes that provides convenience methods for parsing the data_path, labels_path, and export_media parameters supported by many exporters.

class fiftyone.utils.data.MediaExporter(export_mode, export_path=None, rel_dir=None, chunk_size=None, supported_modes=None, default_ext=None, ignore_exts=False)¶

Bases: object

Base class for DatasetExporter utilities that provide support for populating a directory or manifest of media files.

This class is designed for populating a single, flat directory or manifest of media files, and automatically takes care of things like name clashes as necessary.

The export strategy used is defined by the export_mode parameter, and users of this class can restrict the available options via the supported_modes parameter.

Parameters

export_mode –
the export mode to use. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media. This option is only useful when exporting labeled datasets whose label format stores sufficient information to locate the associated media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
export_path (None) –
the location to export the media. Can be any of the following:
- When export_media is True, “move”, or “symlink”, a directory in which to export the media
- When export_mode is “manifest”, the path to write a JSON file mapping UUIDs to input filepaths
- When export_media is False, this parameter has no effect
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each media. When exporting media, this identifier is joined with export_path to generate an output path for each exported media. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
chunk_size (None) – an optional chunk size to use when exporting media files. If provided, media files will be nested in subdirectories of the output directory with at most this many media files per subdirectory. Has no effect if a rel_dir is provided
supported_modes (None) – an optional tuple specifying a subset of the export_mode values that are allowed
default_ext (None) – the file extension to use when generating default output paths
ignore_exts (False) – whether to omit file extensions when generating UUIDs for files

Methods:

`setup`()	Performs necessary setup to begin exporting media.
`export`(media_or_path[, outpath])	Exports the given media.
`close`()	Performs any necessary actions to complete the export.

setup()¶

Performs necessary setup to begin exporting media.

DatasetExporter classes using this class should invoke this method in DatasetExporter.setup().

export(media_or_path, outpath=None)¶

Exports the given media.

Parameters

media_or_path – the media or path to the media on disk
outpath (None) – a manually-specified location to which to export the media. By default, the media will be exported into export_path

Returns

the path to the exported media
the UUID of the exported media

Return type

a tuple of

close()¶: Performs any necessary actions to complete the export.

class fiftyone.utils.data.ImageExporter(*args, default_ext=None, **kwargs)¶

Bases: fiftyone.utils.data.exporters.MediaExporter

Utility class for DatasetExporter instances that export images.

See MediaExporter for details.

Methods:

`close`()	Performs any necessary actions to complete the export.
`export`(media_or_path[, outpath])	Exports the given media.
`setup`()	Performs necessary setup to begin exporting media.

close()¶: Performs any necessary actions to complete the export.

export(media_or_path, outpath=None)¶

Exports the given media.

Parameters

media_or_path – the media or path to the media on disk
outpath (None) – a manually-specified location to which to export the media. By default, the media will be exported into export_path

Returns

the path to the exported media
the UUID of the exported media

Return type

a tuple of

setup()¶

Performs necessary setup to begin exporting media.

DatasetExporter classes using this class should invoke this method in DatasetExporter.setup().

class fiftyone.utils.data.VideoExporter(*args, default_ext=None, **kwargs)¶

Bases: fiftyone.utils.data.exporters.MediaExporter

Utility class for DatasetExporter instances that export videos.

See MediaExporter for details.

Methods:

`close`()	Performs any necessary actions to complete the export.
`export`(media_or_path[, outpath])	Exports the given media.
`setup`()	Performs necessary setup to begin exporting media.

close()¶: Performs any necessary actions to complete the export.

export(media_or_path, outpath=None)¶

Exports the given media.

Parameters

media_or_path – the media or path to the media on disk
outpath (None) – a manually-specified location to which to export the media. By default, the media will be exported into export_path

Returns

the path to the exported media
the UUID of the exported media

Return type

a tuple of

setup()¶

Performs necessary setup to begin exporting media.

DatasetExporter classes using this class should invoke this method in DatasetExporter.setup().

class fiftyone.utils.data.DatasetExporter(export_dir=None)¶

Bases: object

Base interface for exporting datasets.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`export_sample`(args, *kwargs)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.

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() 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(*args, **kwargs)¶

Exports the given sample to the dataset.

Parameters

*args – subclass-specific positional arguments
**kwargs – subclass-specific keyword arguments

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.data.BatchDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Base interface for exporters that export entire fiftyone.core.collections.SampleCollection instances in a single batch.

This interface allows for greater efficiency for export formats that handle aggregating over the samples themselves.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Methods:

`export_sample`(args, *kwargs)	Exports the given sample to the dataset.
`export_samples`(sample_collection[, progress])	Exports the given sample collection.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

export_sample(*args, **kwargs)¶

Exports the given sample to the dataset.

Parameters

*args – subclass-specific positional arguments
**kwargs – subclass-specific keyword arguments

export_samples(sample_collection, progress=None)¶

Exports the given sample collection.

Parameters

sample_collection – a fiftyone.core.collections.SampleCollection
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

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__()

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() 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

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__().

class fiftyone.utils.data.GenericSampleDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of arbitrary fiftyone.core.sample.Sample instances.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Methods:

`export_sample`(sample)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

export_sample(sample)¶

Exports the given sample to the dataset.

Parameters: sample – a fiftyone.core.sample.Sample

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__()

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() 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

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__().

class fiftyone.utils.data.GroupDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting grouped datasets.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Methods:

`export_sample`(args, *kwargs)	Exports the given sample to the dataset.
`export_group`(group)	Exports the given group to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

export_sample(*args, **kwargs)¶

Exports the given sample to the dataset.

Parameters

*args – subclass-specific positional arguments
**kwargs – subclass-specific keyword arguments

export_group(group)¶

Exports the given group to the dataset.

Parameters: group – a dict mapping group slice names to fiftyone.core.sample.Sample instances

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__()

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() 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

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__().

class fiftyone.utils.data.UnlabeledImageDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of unlabeled image samples.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Attributes:

requires_image_metadata

Whether this exporter requires fiftyone.core.metadata.ImageMetadata instances for each sample being exported.

Methods:

`export_sample`(image_or_path[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

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

export_sample(image_or_path, metadata=None)¶

Exports the given sample to the dataset.

Parameters

image_or_path – an image or the path to the image on disk
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__()

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() 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

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__().

class fiftyone.utils.data.UnlabeledVideoDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of unlabeled video samples.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Attributes:

requires_video_metadata

Whether this exporter requires fiftyone.core.metadata.VideoMetadata instances for each sample being exported.

Methods:

`export_sample`(video_path[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

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

export_sample(video_path, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video on disk
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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__()

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() 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

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__().

class fiftyone.utils.data.UnlabeledMediaDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of unlabeled samples.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Attributes:

requires_metadata

Whether this exporter requires fiftyone.core.metadata.Metadata instances for each sample being exported.

Methods:

`export_sample`(filepath[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

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

export_sample(filepath, metadata=None)¶

Exports the given sample to the dataset.

Parameters

filepath – a media path
metadata (None) – a fiftyone.core.metadata.Metadata instance for the sample. Only required when requires_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__()

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() 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

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__().

class fiftyone.utils.data.LabeledImageDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of labeled image samples.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`export_sample`(image_or_path, label[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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

export_sample(image_or_path, label, 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__()

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() 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

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__().

class fiftyone.utils.data.LabeledVideoDatasetExporter(export_dir=None)¶

Bases: fiftyone.utils.data.exporters.DatasetExporter

Interface for exporting datasets of labeled video samples.

See this page for information about implementing/using dataset exporters.

Parameters: export_dir (None) – the directory to write the export. This may be optional for some exporters

Attributes:

`requires_video_metadata`	Whether this exporter requires `fiftyone.core.metadata.VideoMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported at the sample-level.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported by this exporter at the frame-level.

Methods:

`export_sample`(video_path, label, frames[, …])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`setup`()	Performs any necessary setup before exporting the first sample in the dataset.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) that can be exported at the sample-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export 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 exporter can export multiple label fields with value-types specified by this dictionary. Not all keys need be present in the exported sample-level labels
None. In this case, the exporter makes no guarantees about the sample-level labels that it can export

property frame_labels_cls¶

The fiftyone.core.labels.Label class(es) that can be exported by this exporter at the frame-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single frame label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the exporter can export multiple frame label fields with value-types specified by this dictionary. Not all keys need be present in the exported frame labels
None. In this case, the exporter makes no guarantees about the frame labels that it can export

export_sample(video_path, label, frames, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video 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 has no sample-level labels
frames – a dictionary mapping frame numbers to dictionaries that map field names to fiftyone.core.labels.Label instances, or None if the sample has no frame-level labels
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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__()

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() 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

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__().

class fiftyone.utils.data.LegacyFiftyOneDatasetExporter(export_dir, export_media=None, rel_dir=None, chunk_size=None, abs_paths=False, export_saved_views=True, export_runs=True, export_workspaces=True, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.GenericSampleDatasetExporter

Legacy exporter that writes an entire FiftyOne dataset to disk in a serialized JSON format along with its source media.

Warning

The fiftyone.types.FiftyOneDataset format was upgraded in fiftyone==0.8 and this exporter is now deprecated. The new exporter is FiftyOneDatasetExporter.

Parameters

export_dir – the directory to write the export
export_media (None) –
defines how to export the raw media contained in the dataset. The supported values are:
- True (default): copy all media files into the export directory
- False: don’t export media
- "move": move media files into the export directory
- "symlink": create symlinks to each media file in the export directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each media. When exporting media, this identifier is joined with export_dir to generate an output path for each exported media. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
chunk_size (None) – an optional chunk size to use when exporting media files. If provided, media files will be nested in subdirectories of the output directory with at most this many media files per subdirectory. Has no effect if a rel_dir is provided
abs_paths (False) – whether to store absolute paths to the media in the exported labels
export_saved_views (True) – whether to include saved views in the export. Only applicable when exporting full datasets
export_runs (True) – whether to include annotation/brain/evaluation runs in the export. Only applicable when exporting full datasets
export_workspaces (True) – whether to include saved workspaces in the export. Only applicable when exporting full datasets
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`export_sample`(sample)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.

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() 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(sample)¶

Exports the given sample to the dataset.

Parameters: sample – a fiftyone.core.sample.Sample

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.data.FiftyOneDatasetExporter(export_dir, export_media=None, rel_dir=None, chunk_size=None, export_saved_views=True, export_runs=True, export_workspaces=True, use_dirs=False, ordered=True)¶

Bases: fiftyone.utils.data.exporters.BatchDatasetExporter

Exporter that writes an entire FiftyOne dataset to disk in a serialized JSON format along with its source media.

See this page for format details.

Parameters

export_dir – the directory to write the export
export_media (None) –
defines how to export the raw media contained in the dataset. The supported values are:
- True (default): copy all media files into the export directory
- False: don’t export media
- "move": move media files into the export directory
- "symlink": create symlinks to each media file in the export directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each media. When exporting media, this identifier is joined with export_dir to generate an output path for each exported media. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
chunk_size (None) – an optional chunk size to use when exporting media files. If provided, media files will be nested in subdirectories of the output directory with at most this many media files per subdirectory. Has no effect if a rel_dir is provided
export_saved_views (True) – whether to include saved views in the export. Only applicable when exporting full datasets
export_runs (True) – whether to include annotation/brain/evaluation runs in the export. Only applicable when exporting full datasets
export_workspaces (True) – whether to include saved workspaces in the export. Only applicable when exporting full datasets
use_dirs (False) – whether to export metadata into directories of per sample/frame files
ordered (True) – whether to preserve the order of the exported collections

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_samples`(sample_collection[, progress])	Exports the given sample collection.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`export_sample`(args, *kwargs)	Exports the given sample to the dataset.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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__().

export_samples(sample_collection, progress=None)¶

Exports the given sample collection.

Parameters

sample_collection – a fiftyone.core.collections.SampleCollection
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

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__()

export_sample(*args, **kwargs)¶

Exports the given sample to the dataset.

Parameters

*args – subclass-specific positional arguments
**kwargs – subclass-specific keyword arguments

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() 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

class fiftyone.utils.data.ImageDirectoryExporter(export_dir, export_media=None, rel_dir=None, image_format=None)¶

Bases: fiftyone.utils.data.exporters.UnlabeledImageDatasetExporter

Exporter that writes a directory of images to disk.

See this page for format details.

The filenames of input image paths will be maintained in the export directory, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
defines how to export the raw media contained in the dataset. The supported values are:
- True (default): copy all media files into the export directory
- "move": move media files into the export directory
- "symlink": create symlinks to each media file in the export directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with export_dir to generate an output path for each exported image. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used

Attributes:

requires_image_metadata

Whether this exporter requires fiftyone.core.metadata.ImageMetadata instances for each sample being exported.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(image_or_path[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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

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__().

export_sample(image_or_path, metadata=None)¶

Exports the given sample to the dataset.

Parameters

image_or_path – an image or the path to the image on disk
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__()

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() 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

class fiftyone.utils.data.VideoDirectoryExporter(export_dir, export_media=None, rel_dir=None)¶

Bases: fiftyone.utils.data.exporters.UnlabeledVideoDatasetExporter

Exporter that writes a directory of videos to disk.

See this page for format details.

The filenames of the input videos will be maintained in the export directory, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
defines how to export the raw media contained in the dataset. The supported values are:
- True (default): copy all media files into the export directory
- "move": move media files into the export directory
- "symlink": create symlinks to each media file in the export directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each video. When exporting media, this identifier is joined with export_dir to generate an output path for each exported video. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()

Attributes:

requires_video_metadata

Whether this exporter requires fiftyone.core.metadata.VideoMetadata instances for each sample being exported.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(video_path[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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

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__().

export_sample(video_path, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video on disk
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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__()

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() 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

class fiftyone.utils.data.MediaDirectoryExporter(export_dir, export_media=None, rel_dir=None)¶

Bases: fiftyone.utils.data.exporters.UnlabeledMediaDatasetExporter

Exporter that writes a directory of media files of arbitrary type to disk.

See this page for format details.

The filenames of the input media files will be maintained in the export directory, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
defines how to export the raw media contained in the dataset. The supported values are:
- True (default): copy all media files into the export directory
- "move": move media files into the export directory
- "symlink": create symlinks to each media file in the export directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each output file. This identifier is joined with export_dir to generate an output path for each exported media. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()

Attributes:

requires_metadata

Whether this exporter requires fiftyone.core.metadata.Metadata instances for each sample being exported.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(filepath[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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

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__().

export_sample(filepath, metadata=None)¶

Exports the given sample to the dataset.

Parameters

filepath – a media path
metadata (None) – a fiftyone.core.metadata.Metadata instance for the sample. Only required when requires_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__()

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() 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

class fiftyone.utils.data.FiftyOneImageClassificationDatasetExporter(export_dir=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, abs_paths=False, include_confidence=False, include_attributes=False, classes=None, image_format=None, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter, fiftyone.utils.data.exporters.ExportPathsMixin

Exporter that writes an image classification dataset to disk in a simple JSON format.

See this page for format details.

If the path to an image is provided, the image is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir (None) – the directory to write the export. This has no effect if data_path and labels_path are absolute paths
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the media
- an absolute directory path in which to export the media. In this case, the export_dir has no effect on the location of the data
- a JSON filename like "data.json" specifying the filename of the manifest file in export_dir generated when export_media is "manifest"
- an absolute filepath specifying the location to write the JSON manifest file when export_media is "manifest". In this case, export_dir has no effect on the location of the data
If None, the default value of this parameter will be chosen based on the value of the export_media parameter
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a filename like "labels.json" specifying the location in export_dir in which to export the labels
- an absolute filepath to which to export the labels. In this case, the export_dir has no effect on the location of the labels
If None, the labels will be exported into export_dir using the default filename
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with data_path to generate an output path for each exported image. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
abs_paths (False) – whether to store absolute paths to the images in the exported labels
include_confidence (False) –
whether to include classification confidences in the export. The supported values are:
- False (default): do not include confidences
- True: always include confidences
- None: include confidences only if they exist
include_attributes (False) –
whether to include dynamic attributes of the classifications in the export. Supported values are:
- False (default): do not include attributes
- True: always include a (possibly empty) attributes dict
- None: include attributes only if they exist
- a name or iterable of names of specific attributes to include
classes (None) – the list of possible class labels
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(image_or_path, label[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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__().

export_sample(image_or_path, label, 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__()

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() 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

class fiftyone.utils.data.ImageClassificationDirectoryTreeExporter(export_dir, export_media=None, rel_dir=None, image_format=None)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter

Exporter that writes an image classification directory tree to disk.

See this page for format details.

The filenames of the input images are maintained, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
controls how to export the raw media. The supported values are:
- True (default): copy all media files into the output directory
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with export_dir to generate an output path for each exported image. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(image_or_path, classification)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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__().

export_sample(image_or_path, classification, 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__()

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() 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

class fiftyone.utils.data.VideoClassificationDirectoryTreeExporter(export_dir, export_media=None, rel_dir=None)¶

Bases: fiftyone.utils.data.exporters.LabeledVideoDatasetExporter

Exporter that writes a video classification directory tree to disk.

See this page for format details.

The filenames of the input images are maintained, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
controls how to export the raw media. The supported values are:
- True (default): copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each video. When exporting media, this identifier is joined with export_dir to generate an output path for each exported video. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()

Attributes:

`requires_video_metadata`	Whether this exporter requires `fiftyone.core.metadata.VideoMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported at the sample-level.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported by this exporter at the frame-level.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(video_path, classification, _)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) that can be exported at the sample-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export 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 exporter can export multiple label fields with value-types specified by this dictionary. Not all keys need be present in the exported sample-level labels
None. In this case, the exporter makes no guarantees about the sample-level labels that it can export

property frame_labels_cls¶

The fiftyone.core.labels.Label class(es) that can be exported by this exporter at the frame-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single frame label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the exporter can export multiple frame label fields with value-types specified by this dictionary. Not all keys need be present in the exported frame labels
None. In this case, the exporter makes no guarantees about the frame 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__().

export_sample(video_path, classification, _, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video 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 has no sample-level labels
frames – a dictionary mapping frame numbers to dictionaries that map field names to fiftyone.core.labels.Label instances, or None if the sample has no frame-level labels
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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__()

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() 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

class fiftyone.utils.data.FiftyOneImageDetectionDatasetExporter(export_dir=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, abs_paths=False, classes=None, include_confidence=None, include_attributes=None, image_format=None, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter, fiftyone.utils.data.exporters.ExportPathsMixin

Exporter that writes an image detection dataset to disk in a simple JSON format.

See this page for format details.

If the path to an image is provided, the image is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir (None) – the directory to write the export. This has no effect if data_path and labels_path are absolute paths
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the media
- an absolute directory path in which to export the media. In this case, the export_dir has no effect on the location of the data
- a JSON filename like "data.json" specifying the filename of the manifest file in export_dir generated when export_media is "manifest"
- an absolute filepath specifying the location to write the JSON manifest file when export_media is "manifest". In this case, export_dir has no effect on the location of the data
If None, the default value of this parameter will be chosen based on the value of the export_media parameter
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a filename like "labels.json" specifying the location in export_dir in which to export the labels
- an absolute filepath to which to export the labels. In this case, the export_dir has no effect on the location of the labels
If None, the labels will be exported into export_dir using the default filename
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with data_path to generate an output path for each exported image. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
abs_paths (False) – whether to store absolute paths to the images in the exported labels
classes (None) – the list of possible class labels
include_confidence (None) –
whether to include detection confidences in the export. The supported values are:
- None (default): include confidences only if they exist
- True: always include confidences
- False: do not include confidences
include_attributes (None) –
whether to include dynamic attributes of the detections in the export. Supported values are:
- None (default): include attributes only if they exist
- True: always include a (possibly empty) attributes dict
- False: do not include attributes
- a name or iterable of names of specific attributes to include
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(image_or_path, detections[, …])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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__().

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__()

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() 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

class fiftyone.utils.data.FiftyOneTemporalDetectionDatasetExporter(export_dir=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, abs_paths=False, use_timestamps=False, classes=None, include_confidence=None, include_attributes=None, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.LabeledVideoDatasetExporter, fiftyone.utils.data.exporters.ExportPathsMixin

Exporter that writes a temporal video detection dataset to disk in a simple JSON format.

See this page for format details.

Each input video is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir (None) – the directory to write the export. This has no effect if data_path and labels_path are absolute paths
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the media
- an absolute directory path in which to export the media. In this case, the export_dir has no effect on the location of the data
- a JSON filename like "data.json" specifying the filename of the manifest file in export_dir generated when export_media is "manifest"
- an absolute filepath specifying the location to write the JSON manifest file when export_media is "manifest". In this case, export_dir has no effect on the location of the data
If None, the default value of this parameter will be chosen based on the value of the export_media parameter
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a filename like "labels.json" specifying the location in export_dir in which to export the labels
- an absolute filepath to which to export the labels. In this case, the export_dir has no effect on the location of the labels
If None, the labels will be exported into export_dir using the default filename
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each video. When exporting media, this identifier is joined with data_path to generate an output path for each exported video. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
abs_paths (False) – whether to store absolute paths to the videos in the exported labels
use_timestamps (False) – whether to export the support of each temporal detection in seconds rather than frame numbers
classes (None) – the list of possible class labels
include_confidence (None) –
whether to include detection confidences in the export. The supported values are:
- None (default): include confidences only if they exist
- True: always include confidences
- False: do not include confidences
include_attributes (None) –
whether to include dynamic attributes of the detections in the export. Supported values are:
- None (default): include attributes only if they exist
- True: always include a (possibly empty) attributes dict
- False: do not include attributes
- a name or iterable of names of specific attributes to include
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Attributes:

`requires_video_metadata`	Whether this exporter requires `fiftyone.core.metadata.VideoMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported at the sample-level.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported by this exporter at the frame-level.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(video_path, temporal_detections, _)	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) that can be exported at the sample-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export 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 exporter can export multiple label fields with value-types specified by this dictionary. Not all keys need be present in the exported sample-level labels
None. In this case, the exporter makes no guarantees about the sample-level labels that it can export

property frame_labels_cls¶

The fiftyone.core.labels.Label class(es) that can be exported by this exporter at the frame-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single frame label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the exporter can export multiple frame label fields with value-types specified by this dictionary. Not all keys need be present in the exported frame labels
None. In this case, the exporter makes no guarantees about the frame 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__().

export_sample(video_path, temporal_detections, _, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video 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 has no sample-level labels
frames – a dictionary mapping frame numbers to dictionaries that map field names to fiftyone.core.labels.Label instances, or None if the sample has no frame-level labels
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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__()

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() 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

class fiftyone.utils.data.ImageSegmentationDirectoryExporter(export_dir=None, data_path=None, labels_path=None, export_media=None, rel_dir=None, image_format=None, mask_format='.png', mask_size=None, mask_targets=None, thickness=1)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter, fiftyone.utils.data.exporters.ExportPathsMixin

Exporter that writes an image segmentation dataset to disk.

See this page for format details.

If the path to an image is provided, the image is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir (None) – the directory to write the export. This has no effect if data_path and labels_path are absolute paths
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the media
- an absolute directory path in which to export the media. In this case, the export_dir has no effect on the location of the data
- a JSON filename like "data.json" specifying the filename of the manifest file in export_dir generated when export_media is "manifest"
- an absolute filepath specifying the location to write the JSON manifest file when export_media is "manifest". In this case, export_dir has no effect on the location of the data
If None, the default value of this parameter will be chosen based on the value of the export_media parameter
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a folder name like "labels" or "labels/" specifying the location in export_dir in which to export the masks
- an absolute directory in which to export the masks. In this case, the export_dir has no effect on the location of the masks
If None, the masks will be exported into export_dir using the default folder name
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
- "manifest": create a data.json in the output directory that maps UUIDs used in the labels files to the filepaths of the source media, rather than exporting the actual media
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with data_path and labels_path to generate output paths for each exported image and mask. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
mask_format (".png") – the image format to use when writing masks to disk
mask_size (None) – the (width, height) at which to render segmentation masks when exporting instances or polylines. If not provided, masks will be rendered to match the resolution of each input image
mask_targets (None) – a dict mapping integer pixel values in [0, 255] to label strings defining which object classes to render and which pixel values to use for each class. If omitted, all objects are rendered with pixel value 255
thickness (1) – the thickness, in pixels, at which to render (non-filled) polylines

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`export_sample`(image_or_path, label[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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__().

export_sample(image_or_path, label, 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__()

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() 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

class fiftyone.utils.data.FiftyOneImageLabelsDatasetExporter(export_dir, export_media=None, rel_dir=None, image_format=None, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.LabeledImageDatasetExporter

Exporter that writes a labeled image dataset to disk with labels stored in ETA ImageLabels format.

See this page for format details.

If the path to an image is provided, the image is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
controls how to export the raw media. The supported values are:
- True (default): copy all media files into the output directory
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with export_dir to generate an output path for each exported image. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Attributes:

`requires_image_metadata`	Whether this exporter requires `fiftyone.core.metadata.ImageMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) exported by this exporter.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`export_sample`(image_or_path, labels[, metadata])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single label field of any of these types
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() 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, labels, 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.data.FiftyOneVideoLabelsDatasetExporter(export_dir, export_media=None, rel_dir=None, pretty_print=False)¶

Bases: fiftyone.utils.data.exporters.LabeledVideoDatasetExporter

Exporter that writes a labeled video dataset with labels stored in ETA VideoLabels format.

See this page for format details.

If the path to a video is provided, the video is directly copied to its destination, maintaining the original filename, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

export_dir – the directory to write the export
export_media (None) –
controls how to export the raw media. The supported values are:
- True (default): copy all media files into the output directory
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each video. When exporting media, this identifier is joined with export_dir to generate an output path for each exported video. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations

Attributes:

`requires_video_metadata`	Whether this exporter requires `fiftyone.core.metadata.VideoMetadata` instances for each sample being exported.
`label_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported at the sample-level.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) that can be exported by this exporter at the frame-level.

Methods:

`setup`()	Performs any necessary setup before exporting the first sample in the dataset.
`log_collection`(sample_collection)	Logs any relevant information about the `fiftyone.core.collections.SampleCollection` whose samples will be exported.
`export_sample`(video_path, label, frames[, …])	Exports the given sample to the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been exported.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) that can be exported at the sample-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export 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 exporter can export multiple label fields with value-types specified by this dictionary. Not all keys need be present in the exported sample-level labels
None. In this case, the exporter makes no guarantees about the sample-level labels that it can export

property frame_labels_cls¶

The fiftyone.core.labels.Label class(es) that can be exported by this exporter at the frame-level.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the exporter directly exports frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the exporter can export a single frame label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the exporter can export multiple frame label fields with value-types specified by this dictionary. Not all keys need be present in the exported frame labels
None. In this case, the exporter makes no guarantees about the frame 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() 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(video_path, label, frames, metadata=None)¶

Exports the given sample to the dataset.

Parameters

video_path – the path to a video 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 has no sample-level labels
frames – a dictionary mapping frame numbers to dictionaries that map field names to fiftyone.core.labels.Label instances, or None if the sample has no frame-level labels
metadata (None) – a fiftyone.core.metadata.VideoMetadata instance for the sample. Only required when requires_video_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.data.datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])¶

Bases: datetime.date

The year, month and day arguments are required. tzinfo may be None, or an instance of a tzinfo subclass. The remaining arguments may be ints.

Attributes:

`hour`
`minute`
`second`
`microsecond`
`tzinfo`
`fold`
`day`
`max`
`min`
`month`
`resolution`
`year`

Methods:

`fromtimestamp`	timestamp[, tz] -> tz’s local time from POSIX timestamp.
`utcfromtimestamp`	Construct a naive UTC datetime from a POSIX timestamp.
`now`()	Returns new datetime object representing current time local to tz.
`utcnow`	Return a new datetime representing UTC day and time.
`combine`	date, time -> datetime with same date and time fields
`fromisoformat`	string -> datetime from datetime.isoformat() output
`timetuple`	Return time tuple, compatible with time.localtime().
`timestamp`	Return POSIX timestamp as float.
`utctimetuple`	Return UTC time tuple, compatible with time.localtime().
`date`	Return date object with same year, month and day.
`time`	Return time object with same time but with tzinfo=None.
`timetz`	Return time object with same time and tzinfo.
`replace`	Return datetime with new specified fields.
`astimezone`	tz -> convert to local time in new timezone tz
`ctime`	Return ctime() style string.
`isoformat`	[sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM].
`strptime`	string, format -> new datetime parsed from a string (like time.strptime()).
`utcoffset`	Return self.tzinfo.utcoffset(self).
`tzname`	Return self.tzinfo.tzname(self).
`dst`	Return self.tzinfo.dst(self).
`fromisocalendar`	int, int, int -> Construct a date from the ISO year, week number and weekday.
`fromordinal`	int -> date corresponding to a proleptic Gregorian ordinal.
`isocalendar`	Return a named tuple containing ISO year, week number, and weekday.
`isoweekday`	Return the day of the week represented by the date.
`strftime`	format -> strftime() style string.
`today`	Current date or datetime: same as self.__class__.fromtimestamp(time.time()).
`toordinal`	Return proleptic Gregorian ordinal.
`weekday`	Return the day of the week represented by the date.

hour¶

minute¶

second¶

microsecond¶

tzinfo¶

fold¶

fromtimestamp()¶: timestamp[, tz] -> tz’s local time from POSIX timestamp.

utcfromtimestamp()¶: Construct a naive UTC datetime from a POSIX timestamp.

now()¶

Returns new datetime object representing current time local to tz.

tz
Timezone object.

If no tz is specified, uses local timezone.

utcnow()¶: Return a new datetime representing UTC day and time.

combine()¶: date, time -> datetime with same date and time fields

fromisoformat()¶: string -> datetime from datetime.isoformat() output

timetuple()¶: Return time tuple, compatible with time.localtime().

timestamp()¶: Return POSIX timestamp as float.

utctimetuple()¶: Return UTC time tuple, compatible with time.localtime().

date()¶: Return date object with same year, month and day.

time()¶: Return time object with same time but with tzinfo=None.

timetz()¶: Return time object with same time and tzinfo.

replace()¶: Return datetime with new specified fields.

astimezone()¶: tz -> convert to local time in new timezone tz

ctime()¶: Return ctime() style string.

isoformat()¶: [sep] -> string in ISO 8601 format, YYYY-MM-DDT[HH[:MM[:SS[.mmm[uuu]]]]][+HH:MM]. sep is used to separate the year from the time, and defaults to ‘T’. The optional argument timespec specifies the number of additional terms of the time to include. Valid options are ‘auto’, ‘hours’, ‘minutes’, ‘seconds’, ‘milliseconds’ and ‘microseconds’.

strptime()¶: string, format -> new datetime parsed from a string (like time.strptime()).

utcoffset()¶: Return self.tzinfo.utcoffset(self).

tzname()¶: Return self.tzinfo.tzname(self).

dst()¶: Return self.tzinfo.dst(self).

day¶

fromisocalendar()¶

int, int, int -> Construct a date from the ISO year, week number and weekday.

This is the inverse of the date.isocalendar() function

fromordinal()¶: int -> date corresponding to a proleptic Gregorian ordinal.

isocalendar()¶: Return a named tuple containing ISO year, week number, and weekday.

isoweekday()¶: Return the day of the week represented by the date. Monday == 1 … Sunday == 7

max = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999)¶

min = datetime.datetime(1, 1, 1, 0, 0)¶

month¶

resolution = datetime.timedelta(microseconds=1)¶

strftime()¶: format -> strftime() style string.

today()¶: Current date or datetime: same as self.__class__.fromtimestamp(time.time()).

toordinal()¶: Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.

weekday()¶: Return the day of the week represented by the date. Monday == 0 … Sunday == 6

year¶

fiftyone.utils.data.get_document(name)¶: Get a registered Document class by name.

class fiftyone.utils.data.Sample(filepath, tags=None, metadata=None, **kwargs)¶

Bases: fiftyone.core.sample._SampleMixin, fiftyone.core.document.Document

A sample in a fiftyone.core.dataset.Dataset.

Samples store all information associated with a particular piece of data in a dataset, including basic metadata about the data, one or more sets of labels (ground truth, user-provided, or FiftyOne-generated), and additional features associated with subsets of the data and/or label sets.

Note

Sample instances that are in datasets are singletons, i.e., dataset[sample_id] will always return the same Sample instance.

Parameters

filepath – the path to the data on disk. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
tags (None) – a list of tags for the sample
metadata (None) – a fiftyone.core.metadata.Metadata instance
**kwargs – additional fields to dynamically set on the sample

Methods:

`reload`([hard])	Reloads the sample from the database.
`save`()	Saves the sample to the database.
`from_frame`(frame[, filepath])	Creates a sample from the given frame.
`from_doc`(doc[, dataset])	Creates a sample backed by the given document.
`from_dict`(d)	Loads the sample from a JSON dictionary.
`add_labels`(labels[, label_field, …])	Adds the given labels to the sample.
`clear_field`(field_name)	Clears the value of a field of the document.
`compute_metadata`([overwrite, skip_failures])	Populates the `metadata` field of the sample.
`copy`([fields, omit_fields])	Returns a deep copy of the sample that has not been added to the database.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the value of a field of the document.
`has_field`(field_name)	Determines whether the document has the given field.
`iter_fields`([include_id, include_timestamps])	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(sample[, fields, omit_fields, …])	Merges the fields of the given sample into this sample.
`set_field`(field_name, value[, create, …])	Sets the value of a field of the document.
`to_dict`([include_frames, include_private])	Serializes the sample to a JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo_dict`([include_id])	Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database.
`update_fields`(fields_dict[, expand_schema, …])	Sets the dictionary of fields on the document.

Attributes:

`dataset`	The dataset to which this document belongs, or `None` if it has not been added to a dataset.
`dataset_id`
`field_names`	An ordered tuple of the public field names of this document.
`filename`	The basename of the media’s filepath.
`in_dataset`	Whether the document has been added to a dataset.
`media_type`	The media type of the sample.

reload(hard=False)¶

Reloads the sample from the database.

Parameters: hard (False) – whether to reload the sample’s schema in addition to its field values. This is necessary if new fields may have been added to the dataset schema

save()¶: Saves the sample to the database.

classmethod from_frame(frame, filepath=None)¶

Creates a sample from the given frame.

Parameters

frame – a fiftyone.core.frame.Frame
filepath (None) – the path to the corresponding image frame on disk, if not available

Returns

a Sample

classmethod from_doc(doc, dataset=None)¶

Creates a sample backed by the given document.

Parameters

doc – a fiftyone.core.odm.sample.DatasetSampleDocument or fiftyone.core.odm.sample.NoDatasetSampleDocument
dataset (None) – the fiftyone.core.dataset.Dataset that the sample belongs to

Returns

a Sample

classmethod from_dict(d)¶

Loads the sample from a JSON dictionary.

The returned sample will not belong to a dataset.

Returns: a Sample

add_labels(labels, label_field=None, confidence_thresh=None, expand_schema=True, validate=True, dynamic=False)¶

Adds the given labels to the sample.

The provided labels can be any of the following:

A fiftyone.core.labels.Label instance, in which case the labels are directly saved in the specified label_field
A dict mapping keys to fiftyone.core.labels.Label instances. In this case, the labels are added as follows:
```
for key, value in labels.items():
    sample[label_key(key)] = value
```
A dict mapping frame numbers to fiftyone.core.labels.Label instances. In this case, the provided labels are interpreted as frame-level labels that should be added as follows:
```
sample.frames.merge(
    {
        frame_number: {label_field: label}
        for frame_number, label in labels.items()
    }
)
```

A dict mapping frame numbers to dicts mapping keys to fiftyone.core.labels.Label instances. In this case, the provided labels are interpreted as frame-level labels that should be added as follows:

sample.frames.merge(
    {
        frame_number: {
            label_key(key): value
            for key, value in frame_dict.items()
        }
        for frame_number, frame_dict in labels.items()
    }
)

In the above, the label_key function maps label dict keys to field names, and is defined from label_field as follows:

if isinstance(label_field, dict):
    label_key = lambda k: label_field.get(k, k)
elif label_field is not None:
    label_key = lambda k: label_field + "_" + k
else:
    label_key = lambda k: k

Parameters

labels – a fiftyone.core.labels.Label or dict of labels per the description above
label_field (None) – the sample field, prefix, or dict defining in which field(s) to save the labels
confidence_thresh (None) – an optional confidence threshold to apply to any applicable labels before saving them
expand_schema (True) – whether to dynamically add new fields encountered to the dataset schema. If False, an error is raised if any fields are not in the dataset schema
validate (True) – whether to validate values for existing fields
dynamic (False) – whether to declare dynamic attributes

clear_field(field_name)¶

Clears the value of a field of the document.

Parameters: field_name – the name of the field to clear
Raises: AttributeError – if the field does not exist

compute_metadata(overwrite=False, skip_failures=False)¶

Populates the metadata field of the sample.

Parameters

overwrite (False) – whether to overwrite existing metadata
skip_failures (False) – whether to gracefully continue without raising an error if metadata cannot be computed

copy(fields=None, omit_fields=None)¶

Returns a deep copy of the sample that has not been added to the database.

Parameters

fields (None) – an optional field or iterable of fields to which to restrict the copy. This can also be a dict mapping existing field names to new field names
omit_fields (None) – an optional field or iterable of fields to exclude from the copy

Returns

a Sample

property dataset¶: The dataset to which this document belongs, or None if it has not been added to a dataset.

property dataset_id¶

property field_names¶: An ordered tuple of the public field names of this document.

property filename¶: The basename of the media’s filepath.

classmethod from_json(s)¶

Loads the document from a JSON string.

The returned document will not belong to a dataset.

Parameters: s – the JSON string
Returns: a Document

get_field(field_name)¶

Gets the value of a field of the document.

Parameters: field_name – the field name
Returns: the field value
Raises: AttributeError – if the field does not exist

has_field(field_name)¶

Determines whether the document has the given field.

Parameters: field_name – the field name
Returns: True/False

property in_dataset¶: Whether the document has been added to a dataset.

iter_fields(include_id=False, include_timestamps=False)¶

Returns an iterator over the (name, value) pairs of the public fields of the document.

Parameters

include_id (False) – whether to include the id field
include_timestamps (False) – whether to include the created_at and last_modified_at fields

Returns

an iterator that emits (name, value) tuples

property media_type¶: The media type of the sample.

merge(sample, fields=None, omit_fields=None, merge_lists=True, overwrite=True, expand_schema=True, validate=True, dynamic=False)¶

Merges the fields of the given sample into this sample.

The behavior of this method is highly customizable. By default, all top-level fields from the provided sample are merged in, overwriting any existing values for those fields, with the exception of list fields (e.g., tags) and label list fields (e.g., fiftyone.core.labels.Detections fields), in which case the elements of the lists themselves are merged. In the case of label list fields, labels with the same id in both samples are updated rather than duplicated.

To avoid confusion between missing fields and fields whose value is None, None-valued fields are always treated as missing while merging.

This method can be configured in numerous ways, including:

Whether new fields can be added to the dataset schema
Whether list fields should be treated as ordinary fields and merged as a whole rather than merging their elements
Whether to merge only specific fields, or all but certain fields
Mapping input sample fields to different field names of this sample

Parameters

sample – a fiftyone.core.sample.Sample
fields (None) – an optional field or iterable of fields to which to restrict the merge. May contain frame fields for video samples. This can also be a dict mapping field names of the input sample to field names of this sample
omit_fields (None) – an optional field or iterable of fields to exclude from the merge. May contain frame fields for video samples
merge_lists (True) – whether to merge the elements of list fields (e.g., tags) and label list fields (e.g., fiftyone.core.labels.Detections fields) rather than merging the entire top-level field like other field types. For label lists fields, existing fiftyone.core.label.Label elements are either replaced (when overwrite is True) or kept (when overwrite is False) when their id matches a label from the provided sample
overwrite (True) – whether to overwrite (True) or skip (False) existing fields and label elements
expand_schema (True) – whether to dynamically add new fields encountered to the dataset schema. If False, an error is raised if any fields are not in the dataset schema
validate (True) – whether to validate values for existing fields
dynamic (False) – whether to declare dynamic embedded document fields

set_field(field_name, value, create=True, validate=True, dynamic=False)¶

Sets the value of a field of the document.

Parameters

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist
validate (True) – whether to validate values for existing fields
dynamic (False) – whether to declare dynamic embedded document fields

Raises

ValueError – if field_name is not an allowed field name
AttributeError – if the field does not exist and create == False

to_dict(include_frames=False, include_private=False)¶

Serializes the sample to a JSON dictionary.

Parameters

include_frames (False) – whether to include the frame labels for video samples
include_private (False) – whether to include private fields

Returns

a JSON dict

to_json(pretty_print=False)¶

Serializes the document to a JSON string.

The document ID and private fields are excluded in this representation.

Parameters: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns: a JSON string

to_mongo_dict(include_id=False)¶

Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database.

Parameters: include_id (False) – whether to include the document ID
Returns: a BSON dict

update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)¶

Sets the dictionary of fields on the document.

Parameters

fields_dict – a dict mapping field names to values
expand_schema (True) – whether to dynamically add new fields encountered to the document schema. If False, an error is raised if any fields are not in the document schema
validate (True) – whether to validate values for existing fields
dynamic (False) – whether to declare dynamic embedded document fields

Raises

AttributeError – if expand_schema == False and a field does not exist

class fiftyone.utils.data.FiftyOneImageClassificationSampleParser(classes=None)¶

Bases: fiftyone.utils.data.parsers.ImageClassificationSampleParser

Parser for samples in FiftyOne image classification datasets.

See this page for format details.

Parameters: classes (None) – an optional list of class label strings. If provided, it is assumed that target is a class ID that should be mapped to a label string via classes[target]

Methods:

`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_label`()	Returns the label for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

Attributes:

`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.

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

get_label()¶

Returns the label for the current sample.

Parameters: sample – the sample
Returns: a fiftyone.core.labels.Classification instance

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.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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

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.data.FiftyOneTemporalDetectionSampleParser(classes=None, compute_metadata=False)¶

Bases: fiftyone.utils.data.parsers.LabeledVideoSampleParser

Parser for samples in FiftyOne temporal detection datasets.

See this page for format details.

Parameters

classes (None) – an optional list of class label strings. If provided, it is assumed that target is a class ID that should be mapped to a label string via classes[target]
compute_metadata (False) – whether to compute fiftyone.core.metadata.VideoMetadata instances on-the-fly if get_video_metadata() is called and no metadata is available

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the sample-level labels that it produces.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the frame labels that it produces.
`current_sample`	The current sample.

Methods:

`with_sample`(sample[, metadata])	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.
`get_video_path`()	Returns the video path for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`get_label`()	Returns the sample-level labels for the current sample.
`get_frame_labels`()	Returns the frame labels for the current sample.
`clear_sample`()	Clears the current sample.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser 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 parser is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the sample-level labels that it may return

property frame_labels_cls¶

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

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the frame labels that it may return

with_sample(sample, metadata=None)¶

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

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

get_label()¶

Returns the sample-level labels 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 has no sample-level labels

get_frame_labels()¶

Returns the frame labels for the current sample.

Returns: a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame, or None if the sample has no frame labels

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

class fiftyone.utils.data.FiftyOneImageDetectionSampleParser(classes=None)¶

Bases: fiftyone.utils.data.parsers.ImageDetectionSampleParser

Parser for samples in FiftyOne image detection datasets.

See this page for format details.

Parameters: classes (None) – an optional list of class label strings. If provided, it is assumed that the target values are class IDs that should be mapped to label strings via classes[target]

Methods:

`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_label`()	Returns the label for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

Attributes:

`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.

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

get_label()¶

Returns the label for the current sample.

Returns: a fiftyone.core.labels.Detections instance

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.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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

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.data.FiftyOneImageLabelsSampleParser(prefix=None, labels_dict=None, multilabel=False, skip_non_categorical=False)¶

Bases: fiftyone.utils.data.parsers.ImageLabelsSampleParser

Parser for samples in FiftyOne image labels datasets.

See this page for format details.

Parameters

prefix (None) – a string prefix to prepend to each label name in the expanded label dictionary
labels_dict (None) – a dictionary mapping names of attributes/objects in the image labels to field names into which to expand them
multilabel (False) – whether to store attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical attributes (True) or cast them to strings (False)

Methods:

`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_label`()	Returns the label for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

Attributes:

`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.

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

get_label()¶

Returns the label for the current sample.

Returns: a labels dictionary

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.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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

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.data.FiftyOneVideoLabelsSampleParser(prefix=None, labels_dict=None, frame_labels_dict=None, multilabel=False, skip_non_categorical=False)¶

Bases: fiftyone.utils.data.parsers.VideoLabelsSampleParser

Parser for samples in FiftyOne video labels datasets.

See this page for format details.

Parameters

expand (True) – whether to expand the labels for each frame into separate fiftyone.core.labels.Label instances
prefix (None) – a string prefix to prepend to each label name in the expanded frame label dictionaries
labels_dict (None) – a dictionary mapping names of attributes/objects in the frame labels to field names into which to expand them
multilabel (False) – whether to store attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical attributes (True) or cast them to strings (False)

Methods:

`clear_sample`()	Clears the current sample.
`get_frame_labels`()	Returns the frame labels for the current sample.
`get_label`()	Returns the sample-level labels for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`get_video_path`()	Returns the video path for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

Attributes:

`current_sample`	The current sample.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the frame labels that it produces.
`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the sample-level labels that it produces.

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

property frame_labels_cls¶

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

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the frame labels that it may return

get_frame_labels()¶

Returns the frame labels for the current sample.

Returns: a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame, or None if the sample has no frame labels

get_label()¶

Returns the sample-level labels 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 has no sample-level labels

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

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

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser 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 parser is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the sample-level labels that it may return

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

fiftyone.utils.data.import_samples(dataset, dataset_importer, label_field=None, tags=None, expand_schema=True, dynamic=False, add_info=True, progress=None)¶

Adds the samples from the given DatasetImporter to the dataset.

See this guide for more details about importing datasets in custom formats by defining your own DatasetImporter.

Parameters

dataset – a fiftyone.core.dataset.Dataset
dataset_importer – a DatasetImporter
label_field (None) – controls the field(s) in which imported labels are stored. Only applicable if dataset_importer is a LabeledImageDatasetImporter or LabeledVideoDatasetImporter. If the importer produces a single fiftyone.core.labels.Label instance per sample/frame, this argument specifies the name of the field to use; the default is "ground_truth". If the importer produces a dictionary of labels per sample, this argument can be either a string prefix to prepend to each label key or a dict mapping label keys to field names; the default in this case is to directly use the keys of the imported label dictionaries as field names
tags (None) – an optional tag or iterable of tags to attach to each sample
expand_schema (True) – whether to dynamically add new sample fields encountered to the dataset schema. If False, an error is raised if a sample’s schema is not a subset of the dataset schema
dynamic (False) – whether to declare dynamic attributes of embedded document fields that are encountered
add_info (True) – whether to add dataset info from the importer (if any) to the dataset
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

fiftyone.utils.data.merge_samples(dataset, dataset_importer, label_field=None, tags=None, key_field='filepath', key_fcn=None, skip_existing=False, insert_new=True, fields=None, omit_fields=None, merge_lists=True, overwrite=True, expand_schema=True, dynamic=False, add_info=True, progress=None)¶

Merges the samples from the given DatasetImporter into the dataset.

See this guide for more details about importing datasets in custom formats by defining your own DatasetImporter.

By default, samples with the same absolute filepath are merged, but you can customize this behavior via the key_field and key_fcn parameters. For example, you could set key_fcn = lambda sample: os.path.basename(sample.filepath) to merge samples with the same base filename.

The behavior of this method is highly customizable. By default, all top-level fields from the imported samples are merged in, overwriting any existing values for those fields, with the exception of list fields (e.g., tags) and label list fields (e.g., fiftyone.core.labels.Detections fields), in which case the elements of the lists themselves are merged. In the case of label list fields, labels with the same id in both collections are updated rather than duplicated.

To avoid confusion between missing fields and fields whose value is None, None-valued fields are always treated as missing while merging.

This method can be configured in numerous ways, including:

Whether existing samples should be modified or skipped
Whether new samples should be added or omitted
Whether new fields can be added to the dataset schema
Whether list fields should be treated as ordinary fields and merged as a whole rather than merging their elements
Whether to merge only specific fields, or all but certain fields
Mapping input fields to different field names of this dataset

Parameters

dataset – a fiftyone.core.dataset.Dataset
dataset_importer – a DatasetImporter
label_field (None) – controls the field(s) in which imported labels are stored. Only applicable if dataset_importer is a LabeledImageDatasetImporter or LabeledVideoDatasetImporter. If the importer produces a single fiftyone.core.labels.Label instance per sample/frame, this argument specifies the name of the field to use; the default is "ground_truth". If the importer produces a dictionary of labels per sample, this argument can be either a string prefix to prepend to each label key or a dict mapping label keys to field names; the default in this case is to directly use the keys of the imported label dictionaries as field names
tags (None) – an optional tag or iterable of tags to attach to each sample
key_field ("filepath") – the sample field to use to decide whether to join with an existing sample
key_fcn (None) – a function that accepts a fiftyone.core.sample.Sample instance and computes a key to decide if two samples should be merged. If a key_fcn is provided, key_field is ignored
skip_existing (False) – whether to skip existing samples (True) or merge them (False)
insert_new (True) – whether to insert new samples (True) or skip them (False)
fields (None) – an optional field or iterable of fields to which to restrict the merge. If provided, fields other than these are omitted from samples when merging or adding samples. One exception is that filepath is always included when adding new samples, since the field is required. This can also be a dict mapping field names of the input collection to field names of this dataset
omit_fields (None) – an optional field or iterable of fields to exclude from the merge. If provided, these fields are omitted from imported samples, if present. One exception is that filepath is always included when adding new samples, since the field is required
merge_lists (True) – whether to merge the elements of list fields (e.g., tags) and label list fields (e.g., fiftyone.core.labels.Detections fields) rather than merging the entire top-level field like other field types. For label lists fields, existing fiftyone.core.label.Label elements are either replaced (when overwrite is True) or kept (when overwrite is False) when their id matches a label from the provided samples
overwrite (True) – whether to overwrite (True) or skip (False) existing fields and label elements
expand_schema (True) – whether to dynamically add new fields encountered to the dataset schema. If False, an error is raised if a sample’s schema is not a subset of the dataset schema
dynamic (False) – whether to declare dynamic attributes of embedded document fields that are encountered
add_info (True) – whether to add dataset info from the importer (if any) to the dataset
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

fiftyone.utils.data.parse_dataset_info(dataset, info, overwrite=True)¶

Parses the info returned by DatasetImporter.get_dataset_info() and stores it on the relevant properties of the dataset.

Parameters

dataset – a fiftyone.core.dataset.Dataset
info – an info dict
overwrite (True) – whether to overwrite existing dataset info fields

class fiftyone.utils.data.ImportPathsMixin¶

Bases: object

Mixin for DatasetImporter classes that provides convenience methods for parsing the data_path and labels_path parameters supported by many importers.

class fiftyone.utils.data.DatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: object

Base interface for importing datasets stored on disk into FiftyOne.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns: subclass-specific information for the sample
Raises: StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

has_dataset_info

Whether this importer produces a dataset info dictionary.

Methods:

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

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

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.data.BatchDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Base interface for importers that load all of their samples in a single call to import_samples().

This interface allows for greater efficiency for import formats that handle aggregating over the samples themselves.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

has_dataset_info

Whether this importer produces a dataset info dictionary.

Methods:

`import_samples`(dataset[, tags, progress])	Imports the samples into the given dataset.
`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.

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

import_samples(dataset, tags=None, progress=None)¶

Imports the samples into the given dataset.

Parameters

dataset – a fiftyone.core.dataset.Dataset
tags (None) – an optional list of tags to attach to each sample
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

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__()

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

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__().

class fiftyone.utils.data.GenericSampleDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets that contain arbitrary fiftyone.core.sample.Sample instances.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns: a fiftyone.core.sample.Sample instance
Raises: StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`has_sample_field_schema`	Whether this importer produces a sample field schema.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

Methods:

`get_sample_field_schema`()	Returns a dictionary describing the field schema of the samples loaded by this importer.
`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.

property has_sample_field_schema¶: Whether this importer produces a sample field schema.

get_sample_field_schema()¶

Returns a dictionary describing the field schema of the samples loaded by this importer.

Returns: a dict mapping field names to fiftyone.core.fields.Field instances or str(field) representations of them

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__()

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

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

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__().

class fiftyone.utils.data.GroupDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.GenericSampleDatasetImporter

Interface for importing datasets that contain arbitrary grouped fiftyone.core.sample.Sample instances.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported across all group slices.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next group in the dataset.

Returns: a dict mapping slice names to fiftyone.core.sample.Sample instances
Raises: StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`group_field`	The name of the group field to populate on each sample.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.
`has_sample_field_schema`	Whether this importer produces a sample field schema.

Methods:

`close`(*args)	Performs any necessary actions after the last sample has been imported.
`get_dataset_info`()	Returns the dataset info for the dataset.
`get_sample_field_schema`()	Returns a dictionary describing the field schema of the samples loaded by this importer.
`setup`()	Performs any necessary setup before importing the first sample in the dataset.

property group_field¶: The name of the group field to populate on each sample.

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__()

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

get_sample_field_schema()¶

Returns a dictionary describing the field schema of the samples loaded by this importer.

Returns: a dict mapping field names to fiftyone.core.fields.Field instances or str(field) representations of them

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

property has_sample_field_schema¶: Whether this importer produces a sample field schema.

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__().

class fiftyone.utils.data.UnlabeledImageDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets of unlabeled image samples.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns

an (image_path, image_metadata) tuple, where

image_path: the path to the image on disk
image_metadata: an fiftyone.core.metadata.ImageMetadata instances for the image, or None if has_image_metadata() is False

Raises

StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`has_image_metadata`	Whether this importer produces `fiftyone.core.metadata.ImageMetadata` instances for each image.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

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.

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

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__()

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

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

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__().

class fiftyone.utils.data.UnlabeledVideoDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets of unlabeled video samples.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns

an (video_path, video_metadata) tuple, where

video_path: the path to the video on disk
video_metadata: an fiftyone.core.metadata.VideoMetadata instances for the video, or None if has_video_metadata() is False

Raises

StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`has_video_metadata`	Whether this importer produces `fiftyone.core.metadata.VideoMetadata` instances for each video.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

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.

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

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__()

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

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

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__().

class fiftyone.utils.data.UnlabeledMediaDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets of unlabeled media samples.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns

an (filepath, metadata) tuple, where

filepath: the path to the media on disk
metadata: a fiftyone.core.metadata.Metadata instance for the media, or None if has_metadata() is False

Raises

StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`has_metadata`	Whether this importer produces `fiftyone.core.metadata.Metadata` instances for each sample.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

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.

property has_metadata¶: Whether this importer produces fiftyone.core.metadata.Metadata instances for each sample.

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__()

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

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

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__().

class fiftyone.utils.data.LabeledImageDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets of labeled image samples.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns

an (image_path, image_metadata, label) tuple, where

image_path: the path to the image on disk
image_metadata: an fiftyone.core.metadata.ImageMetadata instances for the image, or None if has_image_metadata() is False
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

Raises

StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

`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.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

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.

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

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__()

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

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

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__().

class fiftyone.utils.data.LabeledVideoDatasetImporter(dataset_dir=None, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.DatasetImporter

Interface for importing datasets of labeled video samples.

Typically, dataset importers should implement the parameters documented on this class, although this is not mandatory.

See this page for information about implementing/using dataset importers.

__len__()¶

The total number of samples that will be imported.

Raises: TypeError – if the total number is not known

__next__()¶

Returns information about the next sample in the dataset.

Returns

an (video_path, video_metadata, labels, frames) tuple, where

video_path: the path to the video on disk
video_metadata: an fiftyone.core.metadata.VideoMetadata instances for the video, or None if has_video_metadata() is False
labels: sample-level labels for the video, which can be any of the following:
- a fiftyone.core.labels.Label instance
- a dictionary mapping label fields to fiftyone.core.labels.Label instances
- None if the sample has no sample-level labels
frames: frame-level labels for the video, which can be any of the following:
- a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame
- None if the sample has no frame-level labels

Raises

StopIteration – if there are no more samples to import

Parameters

dataset_dir (None) – the dataset directory. This may be optional for some importers
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

Attributes:

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

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.

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

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

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__()

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

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

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__().

class fiftyone.utils.data.LegacyFiftyOneDatasetImporter(dataset_dir, rel_dir=None, import_saved_views=True, import_runs=True, import_workspaces=True, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.GenericSampleDatasetImporter

Legacy importer for FiftyOne datasets stored on disk in a serialized JSON format.

Warning

The fiftyone.types.FiftyOneDataset format was upgraded in fiftyone==0.8 and this importer is now deprecated.

However, to maintain backwards compatibility, FiftyOneDatasetImporter will check for instances of datasets of this type at runtime and defer to this class to load them.

Parameters

dataset_dir – the dataset directory
rel_dir (None) – a relative directory to prepend to each filepath if it is not absolute. This path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
import_saved_views (True) – whether to include saved views in the import. Only applicable when importing full datasets
import_runs (True) – whether to include annotation/brain/evaluation runs in the import. Only applicable when importing full datasets
import_workspaces (True) – whether to include saved workspaces in the import. Only applicable when importing full datasets
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

Attributes:

`has_sample_field_schema`	Whether this importer produces a sample field schema.
`has_dataset_info`	Whether this importer produces a dataset info dictionary.

Methods:

`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`get_sample_field_schema`()	Returns a dictionary describing the field schema of the samples loaded by this importer.
`get_dataset_info`()	Returns the dataset info for the dataset.
`import_extras`(sample_collection)
`close`(*args)	Performs any necessary actions after the last sample has been imported.

property has_sample_field_schema¶: Whether this importer produces a sample field schema.

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

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_sample_field_schema()¶

Returns a dictionary describing the field schema of the samples loaded by this importer.

Returns: a dict mapping field names to fiftyone.core.fields.Field instances or str(field) representations of them

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

import_extras(sample_collection)¶

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.data.FiftyOneDatasetImporter(dataset_dir, rel_dir=None, import_saved_views=True, import_runs=True, import_workspaces=True, ordered=True, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.BatchDatasetImporter

Importer for FiftyOne datasets stored on disk in serialized JSON format.

See this page for format details.

Parameters

dataset_dir – the dataset directory
rel_dir (None) – a relative directory to prepend to the filepath of each sample if the filepath is not absolute. This path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
import_saved_views (True) – whether to include saved views in the import. Only applicable when importing full datasets
import_runs (True) – whether to include annotation/brain/evaluation runs in the import. Only applicable when importing full datasets
import_workspaces (True) – whether to include saved workspaces in the import. Only applicable when importing full datasets
ordered (True) – whether to preserve document order 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

Methods:

`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`import_samples`(dataset[, tags, progress])	Imports the samples into the given dataset.
`close`(*args)	Performs any necessary actions after the last sample has been imported.
`get_dataset_info`()	Returns the dataset info for the dataset.

Attributes:

has_dataset_info

Whether this importer produces a dataset info dictionary.

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__().

import_samples(dataset, tags=None, progress=None)¶

Imports the samples into the given dataset.

Parameters

dataset – a fiftyone.core.dataset.Dataset
tags (None) – an optional list of tags to attach to each sample
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

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__()

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

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

class fiftyone.utils.data.ImageDirectoryImporter(dataset_dir, recursive=True, compute_metadata=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.UnlabeledImageDatasetImporter

Importer for a directory of images stored on disk.

See this page for format details.

Parameters

dataset_dir – the dataset directory
recursive (True) – whether to recursively traverse subdirectories
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image 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

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.

Methods:

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

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.

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__().

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__()

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

class fiftyone.utils.data.VideoDirectoryImporter(dataset_dir, recursive=True, compute_metadata=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.UnlabeledVideoDatasetImporter

Importer for a directory of videos stored on disk.

See this page for format details.

Parameters

dataset_dir – the dataset directory
recursive (True) – whether to recursively traverse subdirectories
compute_metadata (False) – whether to produce fiftyone.core.metadata.VideoMetadata instances for each video 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

Attributes:

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

Methods:

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

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.

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__().

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__()

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

class fiftyone.utils.data.MediaDirectoryImporter(dataset_dir, recursive=True, compute_metadata=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.UnlabeledMediaDatasetImporter

Importer for a directory of media files stored on disk.

See this page for format details.

Parameters

dataset_dir – the dataset directory
recursive (True) – whether to recursively traverse subdirectories
compute_metadata (False) – whether to produce fiftyone.core.metadata.Metadata instances for each media file 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

Attributes:

`has_dataset_info`	Whether this importer produces a dataset info dictionary.
`has_metadata`	Whether this importer produces `fiftyone.core.metadata.Metadata` instances for each sample.

Methods:

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

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

property has_metadata¶: Whether this importer produces fiftyone.core.metadata.Metadata instances for each sample.

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__().

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__()

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

class fiftyone.utils.data.FiftyOneImageClassificationDatasetImporter(dataset_dir=None, data_path=None, labels_path=None, compute_metadata=False, include_all_data=False, shuffle=False, seed=None, max_samples=None)¶

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

Importer for image classification datasets stored on disk in a simple JSON format.

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 filenames 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
- 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 labels.json
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image when importing
include_all_data (False) – whether to generate samples for all images in the data directory (True) rather than only creating samples for images with labels (False)
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

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.

Methods:

`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`get_dataset_info`()	Returns the dataset info for the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been 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 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.data.ImageClassificationDirectoryTreeImporter(dataset_dir, compute_metadata=False, classes=None, unlabeled='_unlabeled', shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledImageDatasetImporter

Importer for an image classification directory tree stored on disk.

See this page for format details.

Parameters

dataset_dir – the dataset directory
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image when importing
classes (None) – an optional string or list of strings specifying a subset of classes to load
unlabeled ("_unlabeled") – the name of the subdirectory containing unlabeled images
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

Attributes:

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

Methods:

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

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

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

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.data.VideoClassificationDirectoryTreeImporter(dataset_dir, compute_metadata=False, classes=None, unlabeled='_unlabeled', shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledVideoDatasetImporter

Importer for a viideo classification directory tree stored on disk.

See this page for format details.

Parameters

dataset_dir – the dataset directory
compute_metadata (False) – whether to produce fiftyone.core.metadata.VideoMetadata instances for each video when importing
classes (None) – an optional string or list of strings specifying a subset of classes to load
unlabeled ("_unlabeled") – the name of the subdirectory containing unlabeled images
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

Attributes:

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

Methods:

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

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

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

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

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

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.data.FiftyOneImageDetectionDatasetImporter(dataset_dir=None, data_path=None, labels_path=None, compute_metadata=False, include_all_data=False, shuffle=False, seed=None, max_samples=None)¶

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

Importer for image detection datasets stored on disk in a simple JSON format.

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 filenames 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
- 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 labels.json
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image when importing
include_all_data (False) – whether to generate samples for all images in the data directory (True) rather than only creating samples for images with labels (False)
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

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.

Methods:

`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`get_dataset_info`()	Returns the dataset info for the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been 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 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.data.FiftyOneTemporalDetectionDatasetImporter(dataset_dir=None, data_path=None, labels_path=None, compute_metadata=False, include_all_data=False, shuffle=False, seed=None, max_samples=None)¶

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

Importer for temporal video detection datasets stored on disk in a simple JSON format.

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 filenames 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
- 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 labels.json
compute_metadata (False) – whether to produce fiftyone.core.metadata.VideoMetadata instances for each video when importing
include_all_data (False) – whether to generate samples for all videos in the data directory (True) rather than only creating samples for videos with labels (False)
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

Attributes:

`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.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer within the frame labels that it produces.

Methods:

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

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

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

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.data.ImageSegmentationDirectoryImporter(dataset_dir=None, data_path=None, labels_path=None, load_masks=False, force_grayscale=False, compute_metadata=False, include_all_data=False, shuffle=False, seed=None, max_samples=None)¶

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

Importer for image segmentation 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 filenames 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 folder name like "labels" or "labels/" specifying the location of the labels in dataset_dir
- 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 labels/
load_masks (False) – whether to load the masks into the database (True) or simply record the paths to the masks (False)
force_grayscale (False) – whether to load RGB masks as grayscale by storing only the first channel
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image when importing
include_all_data (False) – whether to generate samples for all images in the data directory (True) rather than only creating samples for images with masks (False)
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

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.

Methods:

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

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__().

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__()

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

class fiftyone.utils.data.FiftyOneImageLabelsDatasetImporter(dataset_dir, compute_metadata=False, prefix=None, labels_dict=None, multilabel=False, skip_non_categorical=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledImageDatasetImporter

Importer for labeled image datasets whose labels are stored in ETA ImageLabels format.

See this page for format details.

Parameters

dataset_dir – the dataset directory
compute_metadata (False) – whether to produce fiftyone.core.metadata.ImageMetadata instances for each image when importing
prefix (None) – a string prefix to prepend to each label name in the expanded label dictionary
labels_dict (None) – a dictionary mapping names of attributes/objects in the image labels to field names into which to expand them
multilabel (False) – whether to store frame attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical frame attributes (True) or cast them to strings (False)
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

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.

Methods:

`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`get_dataset_info`()	Returns the dataset info for the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been 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 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.data.FiftyOneVideoLabelsDatasetImporter(dataset_dir, compute_metadata=False, prefix=None, labels_dict=None, frame_labels_dict=None, multilabel=False, skip_non_categorical=False, shuffle=False, seed=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledVideoDatasetImporter

Importer for labeled video datasets whose labels are stored in ETA VideoLabels format.

See this page for format details.

Parameters

dataset_dir – the dataset directory
compute_metadata (False) – whether to produce fiftyone.core.metadata.VideoMetadata instances for each video when importing
prefix (None) – a string prefix to prepend to each label name in the expanded sample/frame label dictionaries
labels_dict (None) – a dictionary mapping names of attributes/objects in the sample labels to field names into which to expand them. By default, all sample labels are loaded
frame_labels_dict (None) – a dictionary mapping names of attributes/objects in the frame labels to field names into which to expand them. By default, all frame labels are loaded
multilabel (False) – whether to store frame attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical frame attributes (True) or cast them to strings (False)
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

Attributes:

`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.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer within the frame labels that it produces.

Methods:

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

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

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

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.data.ImageIngestor(dataset_dir, image_format=None)¶

Bases: object

Mixin for fiftyone.utils.data.importers.DatasetImporter instances that ingest images into the provided dataset_dir during import.

Parameters

dataset_dir – the directory where input images will be ingested into
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used

class fiftyone.utils.data.UnlabeledImageDatasetIngestor(dataset_dir, samples, sample_parser, image_format=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.UnlabeledImageDatasetImporter, fiftyone.utils.data.ingestors.ImageIngestor

Dataset importer that ingests unlabeled images into the provided dataset_dir during import.

The source images are parsed from the provided samples using the provided fiftyone.utils.data.parsers.UnlabeledImageSampleParser.

If an image path is available via fiftyone.utils.data.parsers.UnlabeledImageSampleParser.get_image_path(), then the image is directly copied from its source location into dataset_dir. In this case, the original filename is maintained, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

If no image path is available, the image is read in-memory via fiftyone.utils.data.parsers.UnlabeledImageSampleParser.get_image() and written to dataset_dir in the following format:

<dataset_dir>/<image_count><image_format>

where image_count is the number of files in dataset_dir.

Parameters

dataset_dir – the directory where input images will be ingested into
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – an fiftyone.utils.data.parsers.UnlabeledImageSampleParser to use to parse the samples
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

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.

Methods:

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

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.

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__().

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__()

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

class fiftyone.utils.data.LabeledImageDatasetIngestor(dataset_dir, samples, sample_parser, image_format=None, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledImageDatasetImporter, fiftyone.utils.data.ingestors.ImageIngestor

Dataset importer that ingests labeled images into the provided dataset_dir during import.

The source images and labels are parsed from the provided samples using the provided fiftyone.utils.data.parsers.LabeledImageSampleParser.

If an image path is available via fiftyone.utils.data.parsers.LabeledImageSampleParser.get_image_path(), then the image is directly copied from its source location into dataset_dir. In this case, the original filename is maintained, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

If no image path is available, the image is read in-memory via fiftyone.utils.data.parsers.LabeledImageSampleParser.get_image() and written to dataset_dir in the following format:

<dataset_dir>/<image_count><image_format>

where image_count is the number of files in dataset_dir.

Parameters

dataset_dir – the directory where input images will be ingested into
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – an fiftyone.utils.data.parsers.LabeledImageSampleParser to use to parse the samples
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

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.

Methods:

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

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__().

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__()

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

class fiftyone.utils.data.VideoIngestor(dataset_dir)¶

Bases: object

Mixin for fiftyone.utils.data.importers.DatasetImporter instances that ingest videos into the provided dataset_dir during import.

Parameters: dataset_dir – the directory where input videos will be ingested into

class fiftyone.utils.data.UnlabeledVideoDatasetIngestor(dataset_dir, samples, sample_parser, max_samples=None)¶

Bases: fiftyone.utils.data.importers.UnlabeledVideoDatasetImporter, fiftyone.utils.data.ingestors.VideoIngestor

Dataset importer that ingests unlabeled videos into the provided dataset_dir during import.

The source videos are parsed from the provided samples using the provided fiftyone.utils.data.parsers.UnlabeledVideoSampleParser.

The source videos are directly copied from their source locations into dataset_dir, maintaining the original filenames, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

dataset_dir – the directory where input videos will be ingested into
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – an fiftyone.utils.data.parsers.UnlabeledVideoSampleParser to use to parse the samples
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

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

Methods:

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

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.

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__().

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__()

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

class fiftyone.utils.data.LabeledVideoDatasetIngestor(dataset_dir, samples, sample_parser, max_samples=None)¶

Bases: fiftyone.utils.data.importers.LabeledVideoDatasetImporter, fiftyone.utils.data.ingestors.VideoIngestor

Dataset importer that ingests labeled videos into the provided dataset_dir during import.

The source videos and labels are parsed from the provided samples using the provided fiftyone.utils.data.parsers.LabeledVideoSampleParser.

The source videos are directly copied from their source locations into dataset_dir, maintaining the original filenames, unless a name conflict would occur, in which case an index of the form "-%d" % count is appended to the base filename.

Parameters

dataset_dir – the directory where input videos will be ingested into
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – an fiftyone.utils.data.parsers.LabeledVideoSampleParser to use to parse the samples
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

`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.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer within the frame labels that it produces.

Methods:

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

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

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

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__().

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__()

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

fiftyone.utils.data.add_images(dataset, samples, sample_parser, tags=None, progress=None)¶

Adds the given images to the dataset.

This operation does not read the images.

See this guide for more details about adding images to a dataset by defining your own UnlabeledImageSampleParser.

Parameters

dataset – a fiftyone.core.dataset.Dataset
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – a UnlabeledImageSampleParser instance to use to parse the samples
tags (None) – an optional tag or iterable of tags to attach to each sample
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

fiftyone.utils.data.add_labeled_images(dataset, samples, sample_parser, label_field=None, tags=None, expand_schema=True, dynamic=False, progress=None)¶

Adds the given labeled images to the dataset.

This operation will iterate over all provided samples, but the images will not be read (unless the sample parser requires it in order to compute image metadata).

See this guide for more details about adding labeled images to a dataset by defining your own LabeledImageSampleParser.

Parameters

dataset – a fiftyone.core.dataset.Dataset
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – a LabeledImageSampleParser instance to use to parse the samples
label_field (None) – controls the field(s) in which imported labels are stored. If the parser produces a single fiftyone.core.labels.Label instance per sample, this argument specifies the name of the field to use; the default is "ground_truth". If the parser produces a dictionary of labels per sample, this argument can be either a string prefix to prepend to each label key or a dict mapping label keys to field names; the default in this case is to directly use the keys of the imported label dictionaries as field names
tags (None) – an optional tag or iterable of tags to attach to each sample
expand_schema (True) – whether to dynamically add new sample fields encountered to the dataset schema. If False, an error is raised if a sample’s schema is not a subset of the dataset schema
dynamic (False) – whether to declare dynamic attributes of embedded document fields that are encountered
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

fiftyone.utils.data.add_videos(dataset, samples, sample_parser, tags=None, progress=None)¶

Adds the given videos to the dataset.

This operation does not read the videos.

See this guide for more details about adding videos to a dataset by defining your own UnlabeledVideoSampleParser.

Parameters

dataset – a fiftyone.core.dataset.Dataset
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – a UnlabeledVideoSampleParser instance to use to parse the samples
tags (None) – an optional tag or iterable of tags to attach to each sample
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

fiftyone.utils.data.add_labeled_videos(dataset, samples, sample_parser, label_field=None, tags=None, expand_schema=True, dynamic=False, progress=None)¶

Adds the given labeled videos to the dataset.

This operation will iterate over all provided samples, but the videos will not be read/decoded/etc.

See this guide for more details about adding labeled videos to a dataset by defining your own LabeledVideoSampleParser.

Parameters

dataset – a fiftyone.core.dataset.Dataset
samples – an iterable of samples that can be parsed by sample_parser
sample_parser – a LabeledVideoSampleParser instance to use to parse the samples
label_field (None) – controls the field(s) in which imported labels are stored. If the parser produces a single fiftyone.core.labels.Label instance per sample/frame, this argument specifies the name of the field to use; the default is "ground_truth". If the parser produces a dictionary of labels per sample/frame, this argument can be either a string prefix to prepend to each label key or a dict mapping label keys to field names; the default in this case is to directly use the keys of the imported label dictionaries as field names
tags (None) – an optional tag or iterable of tags to attach to each sample
expand_schema (True) – whether to dynamically add new sample fields encountered to the dataset schema. If False, an error is raised if a sample’s schema is not a subset of the dataset schema
dynamic (False) – whether to declare dynamic attributes of embedded document fields that are encountered
progress (None) – whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

Returns

a list of IDs of the samples that were added to the dataset

class fiftyone.utils.data.SampleParser¶

Bases: object

Base interface for sample parsers.

SampleParser instances are used to parse samples emitted by dataset iterators when ingesting them into fiftyone.core.dataset.Dataset instances.

The general recipe for using SampleParser instances is as follows:

sample_parser = SampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    field = sample_parser.get_<field>()

where field is a subclass specific field to parse from the sample.

Attributes:

current_sample

The current sample.

Methods:

`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.
`clear_sample`()	Clears the current sample.

property current_sample¶

The current sample.

Raises: ValueError – if there is no current sample

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

clear_sample()¶

Clears the current sample.

Also clears any cached sample information stored by the parser.

class fiftyone.utils.data.UnlabeledImageSampleParser¶

Bases: fiftyone.utils.data.parsers.SampleParser

Interface for SampleParser instances that parse unlabeled image samples.

Instances of this class must return images in numpy format.

The general recipe for using UnlabeledImageSampleParser instances is as follows:

sample_parser = UnlabeledImageSampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    img = sample_parser.get_image()
    if sample_parser.has_image_path:
        image_path = sample_parser.get_image_path()

    if sample_parser.has_image_metadata:
        image_metadata = sample_parser.get_image_metadata()

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

get_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

get_image_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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

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.data.UnlabeledVideoSampleParser¶

Bases: fiftyone.utils.data.parsers.SampleParser

Interface for SampleParser instances that parse unlabeled video samples.

The general recipe for using UnlabeledVideoSampleParser instances is as follows:

sample_parser = UnlabeledVideoSampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    video_path = sample_parser.get_video_path()
    video_metadata = sample_parser.get_video_metadata()

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.VideoMetadata instance

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

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.data.UnlabeledMediaSampleParser¶

Bases: fiftyone.utils.data.parsers.SampleParser

Interface for SampleParser instances that parse unlabeled media samples.

The general recipe for using UnlabeledMediaSampleParser instances is as follows:

sample_parser = UnlabeledMediaSampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    filepath = sample_parser.get_media_path()
    metadata = sample_parser.get_metadata()

Attributes:

`has_metadata`	Whether this parser produces `fiftyone.core.metadata.Metadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_media_path`()	Returns the media path for the current sample.
`get_metadata`()	Returns the metadata for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_media_path()¶

Returns the media path for the current sample.

Returns: the path to the media on disk

get_metadata()¶

Returns the metadata for the current sample.

Returns: a fiftyone.core.metadata.Metadata instance

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

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.data.VideoSampleParser¶

Bases: fiftyone.utils.data.parsers.UnlabeledVideoSampleParser

Sample parser that parses unlabeled video samples.

This implementation assumes that the provided sample is a path to a video on disk.

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`clear_sample`()	Clears the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

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_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.VideoMetadata instance

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.data.MediaSampleParser¶

Bases: fiftyone.utils.data.parsers.UnlabeledMediaSampleParser

Sample parser that parses unlabeled media samples.

This implementation assumes that the provided sample is a path to a media file on disk.

Attributes:

`has_metadata`	Whether this parser produces `fiftyone.core.metadata.Metadata` instances for samples that it parses.
`current_sample`	The current sample.

Methods:

`get_media_path`()	Returns the media path for the current sample.
`clear_sample`()	Clears the current sample.
`get_metadata`()	Returns the metadata for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

get_media_path()¶

Returns the media path for the current sample.

Returns: the path to the media on disk

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_metadata()¶

Returns the metadata for the current sample.

Returns: a fiftyone.core.metadata.Metadata instance

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.data.LabeledImageSampleParser¶

Bases: fiftyone.utils.data.parsers.SampleParser

Interface for SampleParser instances that parse labeled image samples.

Instances of this class must return images in numpy format and labels as fiftyone.core.labels.Label instances.

The general recipe for using LabeledImageSampleParser instances is as follows:

sample_parser = LabeledImageSampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    img = sample_parser.get_image()
    label = sample_parser.get_label()

    if sample_parser.has_image_path:
        image_path = sample_parser.get_image_path()

    if sample_parser.has_image_metadata:
        image_metadata = sample_parser.get_image_metadata()

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

get_image_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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

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.data.LabeledVideoSampleParser¶

Bases: fiftyone.utils.data.parsers.SampleParser

Interface for SampleParser instances that parse labeled video samples.

The general recipe for using LabeledVideoSampleParser instances is as follows:

sample_parser = LabeledVideoSampleParser(...)

for sample in samples:
    sample_parser.with_sample(sample)
    video_path = sample_parser.get_video_path()
    label = sample_parser.get_label()
    frames = sample_parser.get_frame_labels()

    if sample_parser.has_video_metadata:
        video_metadata = sample_parser.get_video_metadata()

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the sample-level labels that it produces.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the frame labels that it produces.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`get_label`()	Returns the sample-level labels for the current sample.
`get_frame_labels`()	Returns the frame labels for the current sample.
`clear_sample`()	Clears the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser 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 parser is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the sample-level labels that it may return

property frame_labels_cls¶

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

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the frame labels that it may return

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

get_label()¶

Returns the sample-level labels 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 has no sample-level labels

get_frame_labels()¶

Returns the frame labels for the current sample.

Returns: a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame, or None if the sample has no frame labels

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

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.data.LabeledImageTupleSampleParser¶

Bases: fiftyone.utils.data.parsers.LabeledImageSampleParser

Generic sample parser that parses samples that are (image_or_path, label) 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

label is a fiftyone.core.labels.Label instance

This implementation provides a _current_image() property that caches the image for the current sample, for efficiency in case multiple getters require access to the image (e.g., to normalize coordinates, compute metadata, etc).

See the following subclasses of this parser for implementations that parse labels for common tasks:

Image classification: ImageClassificationSampleParser

Object detection: ImageDetectionSampleParser

Multitask image prediction: ImageLabelsSampleParser

Attributes:

`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.

Methods:

`get_image`()	Returns the image from the current sample.
`get_image_path`()	Returns the image path for the current sample.
`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

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

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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_image()¶

Returns the image from the current sample.

Returns: a numpy image

get_image_path()¶

Returns the image path for the current sample.

Returns: the path to the image on disk

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_metadata()¶

Returns the image metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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.data.ImageDetectionSampleParser(label_field='label', bounding_box_field='bounding_box', confidence_field=None, attributes_field=None, classes=None, normalized=True)¶

Bases: fiftyone.utils.data.parsers.LabeledImageTupleSampleParser

Generic parser for image detection samples whose labels are represented as fiftyone.core.labels.Detections instances.

This implementation supports samples that are (image_or_path, detections_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
detections_or_path can be any of the following:
None, for unlabeled images
a list of detections in the following format:
[
    {
        "<label_field>": <label-or-target>,
        "<bounding_box_field>": [
            <top-left-x>, <top-left-y>, <width>, <height>
        ],
        "<confidence_field>": <optional-confidence>,
        "<attributes_field>": {
            <optional-name>: <optional-value>,
            ...
        }
    },
    ...
]
In the above, label-or-target is either a class ID (if classes is provided) or a label string, and the bounding box coordinates can either be relative coordinates in [0, 1] (if normalized == True) or absolute pixels coordinates (if normalized == False). The confidence and attributes fields are optional for each sample.

The input field names can be configured as necessary when instantiating the parser.
the path on disk to a file in the above format

a fiftyone.core.labels.Detections instance

Parameters

label_field ("label") – the name of the object label field in the target dicts
bounding_box_field ("bounding_box") – the name of the bounding box field in the target dicts
confidence_field (None) – the name of the optional confidence field in the target dicts
attributes_field (None) – the name of the optional attributes field in the target dicts
classes (None) – an optional list of class label strings. If provided, it is assumed that the target values are class IDs that should be mapped to label strings via classes[target]
normalized (True) – whether the bounding box coordinates are absolute pixel coordinates (False) or relative coordinates in [0, 1] (True)

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.

Methods:

`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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.Detections instance

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.data.ImageLabelsSampleParser(prefix=None, labels_dict=None, multilabel=False, skip_non_categorical=False)¶

Bases: fiftyone.utils.data.parsers.LabeledImageTupleSampleParser

Generic parser for multitask image prediction samples whose labels are stored in eta.core.image.ImageLabels format.

This implementation provided by this class supports samples that are (image_or_path, image_labels_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

image_labels_or_path is an eta.core.image.ImageLabels instance, an eta.core.frames.FrameLabels instance, a serialized dict representation of either, or the path to either on disk

Parameters

prefix (None) – a string prefix to prepend to each label name in the expanded label dictionary
labels_dict (None) – a dictionary mapping names of attributes/objects in the image labels to field names into which to expand them
multilabel (False) – whether to store attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical attributes (True) or cast them to strings (False)

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`current_sample`	The current sample.
`has_image_metadata`	Whether this parser produces `fiftyone.core.metadata.ImageMetadata` instances for samples that it parses.
`has_image_path`	Whether this parser produces paths to images on disk for samples that it parses.

Methods:

`get_label`()	Returns the label for the current sample.
`clear_sample`()	Clears the current sample.
`get_image`()	Returns the image from the current sample.
`get_image_metadata`()	Returns the image metadata for the current sample.
`get_image_path`()	Returns the image path for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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 list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 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 labels dictionary

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.data.VideoLabelsSampleParser(prefix=None, labels_dict=None, frame_labels_dict=None, multilabel=False, skip_non_categorical=False)¶

Bases: fiftyone.utils.data.parsers.LabeledVideoSampleParser

Generic parser for labeled video samples whose labels are represented in eta.core.video.VideoLabels format.

This implementation provided by this class supports samples that are (video_path, video_labels_or_path) tuples, where:

video_path is the path to a video on disk

video_labels_or_path is an eta.core.video.VideoLabels instance, a serialized dict representation of one, or the path to one on disk

Parameters

prefix (None) – a string prefix to prepend to each label name in the expanded sample/frame label dictionaries
labels_dict (None) – a dictionary mapping names of attributes/objects in the sample labels to field names into which to expand them. By default, all sample labels are loaded
frame_labels_dict (None) – a dictionary mapping names of attributes/objects in the frame labels to field names into which to expand them. By default, all frame labels are loaded
multilabel (False) – whether to store attributes in a single fiftyone.core.labels.Classifications instance
skip_non_categorical (False) – whether to skip non-categorical attributes (True) or cast them to strings (False)

Attributes:

`has_video_metadata`	Whether this parser produces `fiftyone.core.metadata.VideoMetadata` instances for samples that it parses.
`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the sample-level labels that it produces.
`frame_labels_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser within the frame labels that it produces.
`current_sample`	The current sample.

Methods:

`get_video_path`()	Returns the video path for the current sample.
`get_label`()	Returns the sample-level labels for the current sample.
`get_frame_labels`()	Returns the frame labels for the current sample.
`clear_sample`()	Clears the current sample.
`get_video_metadata`()	Returns the video metadata for the current sample.
`with_sample`(sample)	Sets the current sample so that subsequent calls to methods of this parser will return information from the given sample.

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

property label_cls¶

The fiftyone.core.labels.Label class(es) returned by this parser 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 parser is guaranteed to return sample-level labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the sample-level labels that it may return

property frame_labels_cls¶

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

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the parser is guaranteed to return frame labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the parser 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 parser 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 parser makes no guarantees about the frame labels that it may return

get_video_path()¶

Returns the video path for the current sample.

Returns: the path to the video on disk

get_label()¶

Returns the sample-level labels 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 has no sample-level labels

get_frame_labels()¶

Returns the frame labels for the current sample.

Returns: a dictionary mapping frame numbers to dictionaries that map label fields to fiftyone.core.labels.Label instances for each video frame, or None if the sample has no frame labels

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_video_metadata()¶

Returns the video metadata for the current sample.

Returns: a fiftyone.core.metadata.ImageMetadata instance

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.data.ExtractClipsMixin(compute_metadata=False, write_clips=True, clip_dir=None, video_format=None)¶

Bases: object

Mixin for sample parsers that extract clips from fiftyone.core.clips.ClipView instances.

Parameters

compute_metadata (False) – whether to compute fiftyone.core.metadata.VideoMetadata instances on-the-fly when no pre-computed metadata is available
write_clips (True) – whether to write clips when their paths are requested
clip_dir (None) – a directory to write clips. Only applicable when parsing fiftyone.core.clips.ClipView instances
video_format (None) – the video format to use when writing video clips to disk. By default, fiftyone.config.default_video_ext is used