fiftyone.utils.tf¶

TensorFlow utilities.

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

Functions:

`from_images_dir`(images_dir[, recursive, …])	Creates a `tf.data.Dataset` for the given directory of images.
`from_images_patt`(images_patt[, force_rgb, …])	Creates a `tf.data.Dataset` for the given glob pattern of images.
`from_images`(image_paths[, force_rgb, …])	Creates a `tf.data.Dataset` for the given list of images.
`from_image_paths_and_labels`(image_paths, labels)	Creates a `tf.data.Dataset` for an image classification dataset stored as a list of image paths and labels.
`from_image_classification_dir_tree`(dataset_dir)	Creates a `tf.data.Dataset` for the given image classification dataset directory tree.
`from_tf_records`(tf_records_patt[, …])	Creates a `tf.data.Dataset` for the TFRecords at the given path(s).
`write_tf_records`(examples, tf_records_path)	Writes the given `tf.train.Example` protos to disk as TFRecords.

Classes:

`TFRecordsWriter`(tf_records_path[, num_shards])	Class for writing TFRecords to disk.
`TFRecordSampleParser`([force_rgb])	Base class for sample parsers that ingest `tf.train.Example` protos containing labeled images.
`TFImageClassificationSampleParser`([force_rgb])	Parser for image classification samples stored as TFRecords.
`TFObjectDetectionSampleParser`([force_rgb])	Parser for samples in TF Object Detection API format.
`TFRecordsLabeledImageDatasetImporter`([…])	Base class for `fiftyone.utils.data.importers.LabeledImageDatasetImporter` instances that import `tf.train.Example` protos containing labeled images.
`TFImageClassificationDatasetImporter`([…])	Importer for TF image classification datasets stored on disk.
`TFObjectDetectionDatasetImporter`([…])	Importer for TF detection datasets stored on disk.
`TFRecordsDatasetExporter`([export_dir, …])	Base class for `fiftyone.utils.data.exporters.LabeledImageDatasetExporter` instances that export labeled images as TFRecords datasets on disk.
`TFImageClassificationDatasetExporter`([…])	Exporter that writes an image classification dataset to disk as TFRecords.
`TFObjectDetectionDatasetExporter`([…])	Exporter that writes an object detection dataset to disk as TFRecords in the TF Object Detection API format.
`TFExampleGenerator`([force_rgb])	Base class for sample writers that emit `tf.train.Example` protos.
`TFImageClassificationExampleGenerator`([…])	Class for generating `tf.train.Example` protos for samples in TF image classification format.
`TFObjectDetectionExampleGenerator`([…])	Class for generating `tf.train.Example` protos for samples in TF Object Detection API format.

fiftyone.utils.tf.from_images_dir(images_dir, recursive=True, force_rgb=False, num_parallel_calls=None)¶

Creates a tf.data.Dataset for the given directory of images.

Parameters

images_dir – a directory of images
recursive (True) – whether to recursively traverse subdirectories
force_rgb (False) – whether to force convert all images to RGB
num_parallel_calls (None) – the number of samples to read asynchronously in parallel. See https://www.tensorflow.org/api_docs/python/tf/data/Dataset#map for details

Returns

a tf.data.Dataset that emits decoded images

fiftyone.utils.tf.from_images_patt(images_patt, force_rgb=False, num_parallel_calls=None)¶

Creates a tf.data.Dataset for the given glob pattern of images.

Parameters

images_patt – a glob pattern of images like /path/to/images/*.jpg
force_rgb (False) – whether to force convert all images to RGB
num_parallel_calls (None) – the number of samples to read asynchronously in parallel. See https://www.tensorflow.org/api_docs/python/tf/data/Dataset#map for details

Returns

a tf.data.Dataset that emits decoded images

fiftyone.utils.tf.from_images(image_paths, force_rgb=False, num_parallel_calls=None)¶

Creates a tf.data.Dataset for the given list of images.

Parameters

image_paths – an iterable of image paths
force_rgb (False) – whether to force convert all images to RGB
num_parallel_calls (None) – the number of samples to read asynchronously in parallel. See https://www.tensorflow.org/api_docs/python/tf/data/Dataset#map for details

Returns

a tf.data.Dataset that emits decoded images

fiftyone.utils.tf.from_image_paths_and_labels(image_paths, labels, force_rgb=False, num_parallel_calls=None)¶

Creates a tf.data.Dataset for an image classification dataset stored as a list of image paths and labels.

Parameters

image_paths – an iterable of image paths
labels – an iterable of labels
force_rgb (False) – whether to force convert all images to RGB
num_parallel_calls (None) – the number of samples to read asynchronously in parallel. See https://www.tensorflow.org/api_docs/python/tf/data/Dataset#map for details

Returns

a tf.data.Dataset that emits (img, label) pairs

fiftyone.utils.tf.from_image_classification_dir_tree(dataset_dir, force_rgb=False, num_parallel_calls=None)¶

Creates a tf.data.Dataset for the given image classification dataset directory tree.

The directory should have the following format:

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

Parameters

dataset_dir – the dataset directory
force_rgb (False) – whether to force convert all images to RGB
num_parallel_calls (None) – the number of samples to read asynchronously in parallel. See https://www.tensorflow.org/api_docs/python/tf/data/Dataset#map for details

Returns

a tuple of

dataset: a tf.data.Dataset` that emits ``(img, label) pairs
classes: a list of class label strings

fiftyone.utils.tf.from_tf_records(tf_records_patt, buffer_size=None, num_parallel_reads=None)¶

Creates a tf.data.Dataset for the TFRecords at the given path(s).

Parameters

tf_records_patt – the path (or glob pattern of paths) to the TFRecords file(s) to load
buffer_size (None) – an optional buffer size, in bytes, to use when reading the records. Reasonable values are 1-100MBs
num_parallel_reads (None) – an optional number of files to read in parallel. If a negative value is passed, this parameter is set to the number of CPU cores on the host machine. By default, the files are read in series

Returns

a tf.data.Dataset that emits tf.train.Example protos

fiftyone.utils.tf.write_tf_records(examples, tf_records_path, num_shards=None)¶

Writes the given tf.train.Example protos to disk as TFRecords.

Parameters

examples – an iterable that emits tf.train.Example protos
tf_records_path – the path to write the .tfrecords file. If sharding is requested -%%05d-of-%%05d is appended to the path
num_shards (None) – an optional number of shards to split the records into (using a round robin strategy)

class fiftyone.utils.tf.TFRecordsWriter(tf_records_path, num_shards=None)¶

Bases: object

Class for writing TFRecords to disk.

Example Usage:

with TFRecordsWriter("/path/for/tf.records", num_shards=5) as writer:
    for tf_example in tf_examples:
        writer.write(tf_example)

Parameters

tf_records_path – the path to write the .tfrecords file. If sharding is requested -%%05d-of-%%05d is appended to the path
num_shards (None) – an optional number of shards to split the records into (using a round robin strategy). If omitted, no sharding is used

Methods:

write(tf_example)

Writres the tf.train.Example proto to disk.

write(tf_example)¶

Writres the tf.train.Example proto to disk.

Parameters: tf_example – a tf.train.Example proto

class fiftyone.utils.tf.TFRecordSampleParser(force_rgb=False)¶

Bases: fiftyone.utils.data.parsers.LabeledImageSampleParser

Base class for sample parsers that ingest tf.train.Example protos containing labeled images.

Parameters: force_rgb (False) – whether to force convert all images to RGB

Methods:

`get_image`()	Returns the image from 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.
`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.

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.

get_image()¶

Returns the image from the current sample.

Returns: a numpy image

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

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.

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.tf.TFImageClassificationSampleParser(force_rgb=False)¶

Bases: fiftyone.utils.tf.TFRecordSampleParser

Parser for image classification samples stored as TFRecords.

This implementation supports samples that are tf.train.Example protos whose features follow the format described in this page.

Parameters: force_rgb (False) – whether to force convert all images to RGB

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`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_metadata`()	Returns the image metadata for the current sample.
`clear_sample`()	Clears the current sample.
`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.
`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

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

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

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.tf.TFObjectDetectionSampleParser(force_rgb=False)¶

Bases: fiftyone.utils.tf.TFRecordSampleParser

Parser for samples in TF Object Detection API format.

This implementation supports samples that are tf.train.Example protos whose features follow the format described in this page.

Parameters: force_rgb (False) – whether to force convert all images to RGB

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this parser.
`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_metadata`()	Returns the image metadata for the current sample.
`clear_sample`()	Clears the current sample.
`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.
`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

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

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

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.tf.TFRecordsLabeledImageDatasetImporter(dataset_dir=None, tf_records_path=None, images_dir=None, image_format=None, force_rgb=False, max_samples=None)¶

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

Base class for fiftyone.utils.data.importers.LabeledImageDatasetImporter instances that import tf.train.Example protos containing labeled images.

This class assumes that the input TFRecords only contain the images themselves and not their paths on disk, and, therefore, the images are read in-memory and written to the provided images_dir during import.

Parameters

dataset_dir (None) – the dataset directory. If omitted, tf_records_path must be provided
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" or glob pattern like "*.records-*-of-*" specifying the location of the records in dataset_dir
- an absolute filepath or glob pattern for the records. In this case, dataset_dir has no effect on the location of the records
If None, the parameter will default to *record*
images_dir (None) – the directory in which the images will be written. If not provided, the images will be unpacked into dataset_dir
image_format (None) – the image format to use to write the images to disk. By default, fiftyone.config.default_image_ext is used
force_rgb (False) – whether to force convert all images to RGB
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.

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

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

class fiftyone.utils.tf.TFImageClassificationDatasetImporter(dataset_dir=None, tf_records_path=None, images_dir=None, image_format=None, force_rgb=False, max_samples=None)¶

Bases: fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter

Importer for TF image classification datasets stored on disk.

This class assumes that the input TFRecords only contain the images themselves and not their paths on disk, and, therefore, the images are read in-memory and written to the provided images_dir during import.

See this page for format details.

Parameters

dataset_dir (None) – the dataset directory. If omitted, tf_records_path must be provided
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" or glob pattern like "*.records-*-of-*" specifying the location of the records in dataset_dir
- an absolute filepath or glob pattern for the records. In this case, dataset_dir has no effect on the location of the records
If None, the parameter will default to *record*
images_dir (None) – the directory in which the images will be written. If not provided, the images will be unpacked into dataset_dir
image_format (None) – the image format to use to write the images to disk. By default, fiftyone.config.default_image_ext is used
force_rgb (False) – whether to force convert all images to RGB
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer.
`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:

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

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

class fiftyone.utils.tf.TFObjectDetectionDatasetImporter(dataset_dir=None, tf_records_path=None, images_dir=None, image_format=None, force_rgb=False, max_samples=None)¶

Bases: fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter

Importer for TF detection datasets stored on disk.

This class assumes that the input TFRecords only contain the images themselves and not their paths on disk, and, therefore, the images are read in-memory and written to the provided images_dir during import.

See this page for format details.

Parameters

dataset_dir (None) – the dataset directory. If omitted, tf_records_path must be provided
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" or glob pattern like "*.records-*-of-*" specifying the location of the records in dataset_dir
- an absolute filepath or glob pattern for the records. In this case, dataset_dir has no effect on the location of the records
If None, the parameter will default to *record*
images_dir (None) – the directory in which the images will be written. If not provided, the images will be unpacked into dataset_dir
image_format (None) – the image format to use to write the images to disk. By default, fiftyone.config.default_image_ext is used
force_rgb (False) – whether to force convert all images to RGB
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

`label_cls`	The `fiftyone.core.labels.Label` class(es) returned by this importer.
`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:

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

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

class fiftyone.utils.tf.TFRecordsDatasetExporter(export_dir=None, tf_records_path=None, num_shards=None, image_format=None, force_rgb=False)¶

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

Base class for fiftyone.utils.data.exporters.LabeledImageDatasetExporter instances that export labeled images as TFRecords datasets on disk.

Parameters

export_dir (None) – the directory to write the export. This has no effect if tf_records_path is an absolute path
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" specifying the location of the records in export_dir
- an absolute filepath for the records. In this case, export_dir has no effect on the location of the records
If None, the parameter will default to tf.records
num_shards (None) – an optional number of shards to split the records into (using a round robin strategy). If specified, -%%05d-of-%%05d is appended to the records 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
force_rgb (False) – whether to force convert all images to RGB

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.

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

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

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.tf.TFImageClassificationDatasetExporter(export_dir=None, tf_records_path=None, num_shards=None, image_format=None, force_rgb=False)¶

Bases: fiftyone.utils.tf.TFRecordsDatasetExporter

Exporter that writes an image classification dataset to disk as TFRecords.

See this page for format details.

Parameters

export_dir (None) – the directory to write the export. Can be omitted if tf_records_path is provided
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" specifying the location of the records in export_dir
- an absolute filepath for the records. In this case, export_dir has no effect on the location of the records
If None, the parameter will default to tf.records
num_shards (None) – an optional number of shards to split the records into (using a round robin strategy). If specified, -%%05d-of-%%05d is appended to the records 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
force_rgb (False) – whether to force convert all images to RGB

Attributes:

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

Methods:

`close`(*args)	Performs any necessary actions after the last sample has been exported.
`export_sample`(image_or_path, label[, metadata])	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.

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

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

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

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

class fiftyone.utils.tf.TFObjectDetectionDatasetExporter(export_dir=None, tf_records_path=None, num_shards=None, image_format=None, force_rgb=False, classes=None)¶

Bases: fiftyone.utils.tf.TFRecordsDatasetExporter

Exporter that writes an object detection dataset to disk as TFRecords in the TF Object Detection API format.

See this page for format details.

Parameters

export_dir (None) – the directory to write the export. Can be omitted if tf_records_path is provided
tf_records_path (None) –
an optional parameter that enables explicit control over the location of the TF records. Can be any of the following:
- a filename like "tf.records" specifying the location of the records in export_dir
- an absolute filepath for the records. In this case, export_dir has no effect on the location of the records
If None, the parameter will default to tf.records
num_shards (None) – an optional number of shards to split the records into (using a round robin strategy). If specified, -%%05d-of-%%05d is appended to the records 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
force_rgb (False) – whether to force convert all images to RGB
classes (None) – the list of possible class labels

Attributes:

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

Methods:

`close`(*args)	Performs any necessary actions after the last sample has been exported.
`export_sample`(image_or_path, label[, metadata])	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.

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

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

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

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

class fiftyone.utils.tf.TFExampleGenerator(force_rgb=False)¶

Bases: object

Base class for sample writers that emit tf.train.Example protos.

Parameters: force_rgb (False) – whether to force convert all images to RGB

Methods:

make_tf_example(image_or_path, label, *args, …)

Makes a tf.train.Example for the given data.

make_tf_example(image_or_path, label, *args, **kwargs)¶

Makes a tf.train.Example for the given data.

Parameters

image_or_path – an image or the path to the image on disk
label – a fiftyone.core.labels.Label
*args – subclass-specific positional arguments
**kwargs – subclass-specific keyword arguments

Returns

a tf.train.Example

class fiftyone.utils.tf.TFImageClassificationExampleGenerator(force_rgb=False)¶

Bases: fiftyone.utils.tf.TFExampleGenerator

Class for generating tf.train.Example protos for samples in TF image classification format.

See this page for format details.

Parameters: force_rgb (False) – whether to force convert all images to RGB

Methods:

make_tf_example(image_or_path, classification)

Makes a tf.train.Example for the given data.

make_tf_example(image_or_path, classification, filename=None)¶

Makes a tf.train.Example for the given data.

Parameters

image_or_path – an image or the path to the image on disk
classification – a fiftyone.core.labels.Classification instance, or None
filename (None) – a filename for the image. Required when image_or_path is an image, in which case the extension of this filename determines the encoding used. If image_or_path is the path to an image, this is optional; by default, the basename of image_path is used

Returns

a tf.train.Example

class fiftyone.utils.tf.TFObjectDetectionExampleGenerator(force_rgb=False, classes=None)¶

Bases: fiftyone.utils.tf.TFExampleGenerator

Class for generating tf.train.Example protos for samples in TF Object Detection API format.

See this page for format details.

Parameters

force_rgb (False) – whether to force convert all images to RGB
classes (None) – the list of possible class labels

Methods:

make_tf_example(image_or_path, detections[, …])

Makes a tf.train.Example for the given data.

make_tf_example(image_or_path, detections, filename=None)¶

Makes a tf.train.Example for the given data.

Parameters

image_or_path – an image or the path to the image on disk
detections – a fiftyone.core.labels.Detections instance, or None
filename (None) – a filename for the image. Required when image_or_path is an image, in which case the extension of this filename determines the encoding used. If image_or_path is the path to an image, this is optional; by default, the basename of image_path is used

Returns

a tf.train.Example