fiftyone.utils.tf¶

TensorFlow utilities.

Classes:

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

Functions:

 from_image_classification_dir_tree(dataset_dir) Creates a tf.data.Dataset for the given image classification dataset directory tree. 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_images(image_paths[, force_rgb, …]) Creates a tf.data.Dataset for the given list of images. 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_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.
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
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
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
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)

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:

 Clears the current sample. Returns the image from the current sample. Returns the image metadata for the current sample. Returns the image path for the current sample. 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.
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
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)

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

Methods:

 Clears the current sample. Returns the image from the current sample. Returns the image metadata for the current sample. Returns the image path for the current sample. 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.
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
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)

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

Methods:

 Clears the current sample. Returns the image from the current sample. Returns the image metadata for the current sample. Returns the image path for the current sample. 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.
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
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)

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

Methods:

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

Attributes:

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

Whether this importer produces a dataset info dictionary.

property has_image_metadata

Whether this importer produces fiftyone.core.metadata.ImageMetadata instances for each image.

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)

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.

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

Methods:

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

Attributes:

 has_dataset_info Whether this importer produces a dataset info dictionary. has_image_metadata Whether this importer produces fiftyone.core.metadata.ImageMetadata instances for each image. label_cls The fiftyone.core.labels.Label class(es) returned by this importer.
property 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)

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.

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

Methods:

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

Attributes:

 has_dataset_info Whether this importer produces a dataset info dictionary. has_image_metadata Whether this importer produces fiftyone.core.metadata.ImageMetadata instances for each image. label_cls The fiftyone.core.labels.Label class(es) returned by this importer.
property 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)

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

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. Performs any necessary setup before exporting the first sample in the dataset.

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

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

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

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. Performs any necessary setup before exporting the first sample in the dataset.

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

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

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

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. Performs any necessary setup before exporting the first sample in the dataset.

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

• *args – subclass-specific positional arguments

• **kwargs – subclass-specific keyword arguments

Returns

a tf.train.Example

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

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

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)

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

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`