<!-- # hard line break macro for HTML -->

# fiftyone.utils.tf

TensorFlow utilities.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Functions:**

| [`from_images_dir`](#fiftyone.utils.tf.from_images_dir)(images_dir[, recursive, ...])                      | Creates a `tf.data.Dataset` for the given directory of images.                                              |
|------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
| [`from_images_patt`](#fiftyone.utils.tf.from_images_patt)(images_patt[, force_rgb, ...])                   | Creates a `tf.data.Dataset` for the given glob pattern of images.                                           |
| [`from_images`](#fiftyone.utils.tf.from_images)(image_paths[, force_rgb, ...])                             | Creates a `tf.data.Dataset` for the given list of images.                                                   |
| [`from_image_paths_and_labels`](#fiftyone.utils.tf.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`](#fiftyone.utils.tf.from_image_classification_dir_tree)(dataset_dir) | Creates a `tf.data.Dataset` for the given image classification dataset directory tree.                      |
| [`from_tf_records`](#fiftyone.utils.tf.from_tf_records)(tf_records_patt[, ...])                            | Creates a `tf.data.Dataset` for the TFRecords at the given path(s).                                         |
| [`write_tf_records`](#fiftyone.utils.tf.write_tf_records)(examples, tf_records_path)                       | Writes the given `tf.train.Example` protos to disk as TFRecords.                                            |

**Classes:**

| [`TFRecordsWriter`](#fiftyone.utils.tf.TFRecordsWriter)(tf_records_path[, num_shards])                     | Class for writing TFRecords to disk.                                                                                                                                                                                                                |
|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`TFRecordSampleParser`](#fiftyone.utils.tf.TFRecordSampleParser)([force_rgb])                             | Base class for sample parsers that ingest `tf.train.Example` protos containing labeled images.                                                                                                                                                      |
| [`TFImageClassificationSampleParser`](#fiftyone.utils.tf.TFImageClassificationSampleParser)([force_rgb])   | Parser for image classification samples stored as [TFRecords](https://www.tensorflow.org/tutorials/load_data/tfrecord).                                                                                                                             |
| [`TFObjectDetectionSampleParser`](#fiftyone.utils.tf.TFObjectDetectionSampleParser)([force_rgb])           | Parser for samples in [TF Object Detection API format](https://github.com/tensorflow/models/blob/master/research/object_detection).                                                                                                                 |
| [`TFRecordsLabeledImageDatasetImporter`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter)([...])   | Base class for [`fiftyone.utils.data.importers.LabeledImageDatasetImporter`](fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.LabeledImageDatasetImporter) instances that import `tf.train.Example` protos containing labeled images. |
| [`TFImageClassificationDatasetImporter`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter)([...])   | Importer for TF image classification datasets stored on disk.                                                                                                                                                                                       |
| [`TFObjectDetectionDatasetImporter`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter)([...])           | Importer for TF detection datasets stored on disk.                                                                                                                                                                                                  |
| [`TFRecordsDatasetExporter`](#fiftyone.utils.tf.TFRecordsDatasetExporter)([export_dir, ...])               | Base class for [`fiftyone.utils.data.exporters.LabeledImageDatasetExporter`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.LabeledImageDatasetExporter) instances that export labeled images as TFRecords datasets on disk.        |
| [`TFImageClassificationDatasetExporter`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter)([...])   | Exporter that writes an image classification dataset to disk as TFRecords.                                                                                                                                                                          |
| [`TFObjectDetectionDatasetExporter`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter)([...])           | Exporter that writes an object detection dataset to disk as TFRecords in the TF Object Detection API format.                                                                                                                                        |
| [`TFExampleGenerator`](#fiftyone.utils.tf.TFExampleGenerator)([force_rgb])                                 | Base class for sample writers that emit `tf.train.Example` protos.                                                                                                                                                                                  |
| [`TFImageClassificationExampleGenerator`](#fiftyone.utils.tf.TFImageClassificationExampleGenerator)([...]) | Class for generating `tf.train.Example` protos for samples in TF image classification format.                                                                                                                                                       |
| [`TFObjectDetectionExampleGenerator`](#fiftyone.utils.tf.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](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](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](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](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:

```default
<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](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:

```default
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`](#fiftyone.utils.tf.TFRecordsWriter.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`](fiftyone.utils.data.parsers.md#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`](#fiftyone.utils.tf.TFRecordSampleParser.get_image)()                   | Returns the image from the current sample.                                                                                |
|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [`get_label`](#fiftyone.utils.tf.TFRecordSampleParser.get_label)()                   | Returns the label for the current sample.                                                                                 |
| [`clear_sample`](#fiftyone.utils.tf.TFRecordSampleParser.clear_sample)()             | Clears the current sample.                                                                                                |
| [`get_image_metadata`](#fiftyone.utils.tf.TFRecordSampleParser.get_image_metadata)() | Returns the image metadata for the current sample.                                                                        |
| [`get_image_path`](#fiftyone.utils.tf.TFRecordSampleParser.get_image_path)()         | Returns the image path for the current sample.                                                                            |
| [`with_sample`](#fiftyone.utils.tf.TFRecordSampleParser.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`](#fiftyone.utils.tf.TFRecordSampleParser.current_sample)         | The current sample.                                                                                                                                                         |
|------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`has_image_metadata`](#fiftyone.utils.tf.TFRecordSampleParser.has_image_metadata) | Whether this parser produces [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for samples that it parses. |
| [`has_image_path`](#fiftyone.utils.tf.TFRecordSampleParser.has_image_path)         | Whether this parser produces paths to images on disk for samples that it parses.                                                                                            |
| [`label_cls`](#fiftyone.utils.tf.TFRecordSampleParser.label_cls)                   | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, or a dictionary
  mapping field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
parser.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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()`](#fiftyone.utils.tf.TFRecordSampleParser.clear_sample) before setting the current
sample.

* **Parameters:**
  **sample** – a sample

### *class* fiftyone.utils.tf.TFImageClassificationSampleParser(force_rgb=False)

Bases: [`TFRecordSampleParser`](#fiftyone.utils.tf.TFRecordSampleParser)

Parser for image classification samples stored as
[TFRecords](https://www.tensorflow.org/tutorials/load_data/tfrecord).

This implementation supports samples that are `tf.train.Example` protos
whose features follow the format described in
[this page](../user_guide/import_datasets.md#tfimageclassificationdataset-import).

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

**Attributes:**

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

**Methods:**

| [`get_image_metadata`](#fiftyone.utils.tf.TFImageClassificationSampleParser.get_image_metadata)()   | Returns the image metadata for the current sample.                                                                        |
|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [`clear_sample`](#fiftyone.utils.tf.TFImageClassificationSampleParser.clear_sample)()               | Clears the current sample.                                                                                                |
| [`get_image`](#fiftyone.utils.tf.TFImageClassificationSampleParser.get_image)()                     | Returns the image from the current sample.                                                                                |
| [`get_image_path`](#fiftyone.utils.tf.TFImageClassificationSampleParser.get_image_path)()           | Returns the image path for the current sample.                                                                            |
| [`get_label`](#fiftyone.utils.tf.TFImageClassificationSampleParser.get_label)()                     | Returns the label for the current sample.                                                                                 |
| [`with_sample`](#fiftyone.utils.tf.TFImageClassificationSampleParser.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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
parser.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, or a dictionary
  mapping field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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()`](#fiftyone.utils.tf.TFImageClassificationSampleParser.clear_sample) before setting the current
sample.

* **Parameters:**
  **sample** – a sample

### *class* fiftyone.utils.tf.TFObjectDetectionSampleParser(force_rgb=False)

Bases: [`TFRecordSampleParser`](#fiftyone.utils.tf.TFRecordSampleParser)

Parser for samples in
[TF Object Detection API format](https://github.com/tensorflow/models/blob/master/research/object_detection).

This implementation supports samples that are `tf.train.Example` protos
whose features follow the format described in
[this page](../user_guide/import_datasets.md#tfobjectdetectiondataset-import).

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

**Attributes:**

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

**Methods:**

| [`get_image_metadata`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.get_image_metadata)()   | Returns the image metadata for the current sample.                                                                        |
|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| [`clear_sample`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.clear_sample)()               | Clears the current sample.                                                                                                |
| [`get_image`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.get_image)()                     | Returns the image from the current sample.                                                                                |
| [`get_image_path`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.get_image_path)()           | Returns the image path for the current sample.                                                                            |
| [`get_label`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.get_label)()                     | Returns the label for the current sample.                                                                                 |
| [`with_sample`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
parser.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.metadata.md#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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instance, or a dictionary
  mapping field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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()`](#fiftyone.utils.tf.TFObjectDetectionSampleParser.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`](fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.LabeledImageDatasetImporter), [`ImportPathsMixin`](fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.ImportPathsMixin)

Base class for
[`fiftyone.utils.data.importers.LabeledImageDatasetImporter`](fiftyone.utils.data.importers.md#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`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.has_dataset_info)     | Whether this importer produces a dataset info dictionary.                                                                                                         |
|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`has_image_metadata`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.has_image_metadata) | Whether this importer produces [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each image. |
| [`label_cls`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.label_cls)                   | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this importer.                                       |

**Methods:**

| [`setup`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.setup)()                         | Performs any necessary setup before importing the first sample in the dataset.                      |
|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| [`close`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.close)(\*args)                   | Performs any necessary actions after the last sample has been imported.                             |
| [`get_dataset_info`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.get_dataset_info)()   | Returns the dataset info for the dataset.                                                           |
| [`get_media_sources`](#fiftyone.utils.tf.TFRecordsLabeledImageDatasetImporter.get_media_sources)() | Returns the media-source entries the importing dataset records before any sample is added, or None. |

#### *property* has_dataset_info

Whether this importer produces a dataset info dictionary.

#### *property* has_image_metadata

Whether this importer produces
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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

#### get_media_sources()

Returns the media-source entries the importing dataset records
before any sample is added, or None.

Only importers of media-reference-backed samples provide these; see
[`fiftyone.utils.lerobot.LeRobotDatasetImporter`](fiftyone.utils.lerobot.md#fiftyone.utils.lerobot.LeRobotDatasetImporter).

#### *property* label_cls

The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
importer.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](#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](../user_guide/import_datasets.md#tfimageclassificationdataset-import) 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`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.label_cls)                   | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this importer.                                       |
|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`has_dataset_info`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.has_dataset_info)     | Whether this importer produces a dataset info dictionary.                                                                                                         |
| [`has_image_metadata`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.has_image_metadata) | Whether this importer produces [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each image. |

**Methods:**

| [`close`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.close)(\*args)                   | Performs any necessary actions after the last sample has been imported.                             |
|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| [`get_dataset_info`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.get_dataset_info)()   | Returns the dataset info for the dataset.                                                           |
| [`get_media_sources`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.get_media_sources)() | Returns the media-source entries the importing dataset records before any sample is added, or None. |
| [`setup`](#fiftyone.utils.tf.TFImageClassificationDatasetImporter.setup)()                         | Performs any necessary setup before importing the first sample in the dataset.                      |

#### *property* label_cls

The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
importer.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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

#### get_media_sources()

Returns the media-source entries the importing dataset records
before any sample is added, or None.

Only importers of media-reference-backed samples provide these; see
[`fiftyone.utils.lerobot.LeRobotDatasetImporter`](fiftyone.utils.lerobot.md#fiftyone.utils.lerobot.LeRobotDatasetImporter).

#### *property* has_dataset_info

Whether this importer produces a dataset info dictionary.

#### *property* has_image_metadata

Whether this importer produces
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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`](#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](../user_guide/import_datasets.md#tfobjectdetectiondataset-import) 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`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.label_cls)                   | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this importer.                                       |
|------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`has_dataset_info`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.has_dataset_info)     | Whether this importer produces a dataset info dictionary.                                                                                                         |
| [`has_image_metadata`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.has_image_metadata) | Whether this importer produces [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each image. |

**Methods:**

| [`close`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.close)(\*args)                   | Performs any necessary actions after the last sample has been imported.                             |
|------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| [`get_dataset_info`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.get_dataset_info)()   | Returns the dataset info for the dataset.                                                           |
| [`get_media_sources`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.get_media_sources)() | Returns the media-source entries the importing dataset records before any sample is added, or None. |
| [`setup`](#fiftyone.utils.tf.TFObjectDetectionDatasetImporter.setup)()                         | Performs any necessary setup before importing the first sample in the dataset.                      |

#### *property* label_cls

The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) returned by this
importer.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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

#### get_media_sources()

Returns the media-source entries the importing dataset records
before any sample is added, or None.

Only importers of media-reference-backed samples provide these; see
[`fiftyone.utils.lerobot.LeRobotDatasetImporter`](fiftyone.utils.lerobot.md#fiftyone.utils.lerobot.LeRobotDatasetImporter).

#### *property* has_dataset_info

Whether this importer produces a dataset info dictionary.

#### *property* has_image_metadata

Whether this importer produces
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.LabeledImageDatasetExporter), [`ExportPathsMixin`](fiftyone.utils.data.exporters.md#fiftyone.utils.data.exporters.ExportPathsMixin)

Base class for
[`fiftyone.utils.data.exporters.LabeledImageDatasetExporter`](fiftyone.utils.data.exporters.md#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`](#fiftyone.utils.tf.TFRecordsDatasetExporter.requires_image_metadata)   | Whether this exporter requires [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each sample being exported.   |
|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`label_cls`](#fiftyone.utils.tf.TFRecordsDatasetExporter.label_cls)                               | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this exporter.                                                         |

**Methods:**

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

#### *property* requires_image_metadata

Whether this exporter requires
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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()`](#fiftyone.utils.tf.TFRecordsDatasetExporter.label_cls), or a dictionary mapping
    field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances,
    or `None` if the sample is unlabeled
  * **metadata** (*None*) – a [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata)
    instance for the sample. Only required when
    [`requires_image_metadata()`](#fiftyone.utils.tf.TFRecordsDatasetExporter.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`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this
exporter.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.collections.md#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()`](fiftyone.core.collections.md#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()`](#fiftyone.utils.tf.TFRecordsDatasetExporter.export_sample), then the exporter must
make do without any information about the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`](fiftyone.core.collections.md#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`](#fiftyone.utils.tf.TFRecordsDatasetExporter)

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

See [this page](../user_guide/export_datasets.md#tfimageclassificationdataset-export) 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`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter.label_cls)                             | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this exporter.                                                       |
|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`requires_image_metadata`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter.requires_image_metadata) | Whether this exporter requires [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each sample being exported. |

**Methods:**

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

#### *property* label_cls

The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this
exporter.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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()`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter.label_cls), or a dictionary mapping
    field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances,
    or `None` if the sample is unlabeled
  * **metadata** (*None*) – a [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata)
    instance for the sample. Only required when
    [`requires_image_metadata()`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter.requires_image_metadata) is `True`

#### log_collection(sample_collection)

Logs any relevant information about the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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()`](fiftyone.core.collections.md#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()`](#fiftyone.utils.tf.TFImageClassificationDatasetExporter.export_sample), then the exporter must
make do without any information about the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
  samples will be exported

#### *property* requires_image_metadata

Whether this exporter requires
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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`](#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](../user_guide/export_datasets.md#tfobjectdetectiondataset-export) 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`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter.label_cls)                             | The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this exporter.                                                       |
|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`requires_image_metadata`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter.requires_image_metadata) | Whether this exporter requires [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata) instances for each sample being exported. |

**Methods:**

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

#### *property* label_cls

The [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) class(es) exported by this
exporter.

This can be any of the following:

- a [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#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()`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter.label_cls), or a dictionary mapping
    field names to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label) instances,
    or `None` if the sample is unlabeled
  * **metadata** (*None*) – a [`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#fiftyone.core.metadata.ImageMetadata)
    instance for the sample. Only required when
    [`requires_image_metadata()`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter.requires_image_metadata) is `True`

#### log_collection(sample_collection)

Logs any relevant information about the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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()`](fiftyone.core.collections.md#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()`](#fiftyone.utils.tf.TFObjectDetectionDatasetExporter.export_sample), then the exporter must
make do without any information about the
[`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#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`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) whose
  samples will be exported

#### *property* requires_image_metadata

Whether this exporter requires
[`fiftyone.core.metadata.ImageMetadata`](fiftyone.core.metadata.md#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`](#fiftyone.utils.tf.TFExampleGenerator.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`](fiftyone.core.labels.md#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`](#fiftyone.utils.tf.TFExampleGenerator)

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

See [this page](../user_guide/export_datasets.md#tfimageclassificationdataset-export) for format
details.

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

**Methods:**

| [`make_tf_example`](#fiftyone.utils.tf.TFImageClassificationExampleGenerator.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`](fiftyone.core.labels.md#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`](#fiftyone.utils.tf.TFExampleGenerator)

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

See [this page](../user_guide/export_datasets.md#tfobjectdetectiondataset-export) 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`](#fiftyone.utils.tf.TFObjectDetectionExampleGenerator.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`](fiftyone.core.labels.md#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`