fiftyone.utils.tf#

TensorFlow utilities.

Copyright 2017-2025, Voxel51, Inc.

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:
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:
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: 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: 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: 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: LabeledImageDatasetImporter, 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: 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: 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: LabeledImageDatasetExporter, 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:
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: 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:
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: 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:
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: 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: 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