fiftyone.utils.yolo#

Utilities for working with datasets in YOLO format.

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

Functions:

`add_yolo_labels`(sample_collection, ...[, ...])	Adds the given YOLO-formatted labels to the collection.
`load_yolo_annotations`(txt_path, classes[, ...])	Loads the YOLO-style annotations from the given TXT file.

Classes:

`YOLOv4DatasetImporter`([dataset_dir, ...])	Importer for YOLOv4 datasets stored on disk.
`YOLOv5DatasetImporter`([dataset_dir, ...])	Importer for YOLOv5 datasets stored on disk.
`YOLOv4DatasetExporter`([export_dir, ...])	Exporter that writes YOLOv4 datasets to disk.
`YOLOv5DatasetExporter`([export_dir, split, ...])	Exporter that writes YOLOv5 datasets to disk.
`YOLOAnnotationWriter`()	Class for writing annotations in YOLO-style TXT format.

fiftyone.utils.yolo.add_yolo_labels(sample_collection, label_field, labels_path, classes, label_type='detections', include_missing=False)#

Adds the given YOLO-formatted labels to the collection.

Each YOLO txt file should be a space-delimited file whose rows define objects in one of the following formats:

# Detections
<target> <x-center> <y-center> <width> <height>
<target> <x-center> <y-center> <width> <height> <confidence>

# Polylines
<target> <x1> <y1> <x2> <y2> <x3> <y3> ...

where target is the zero-based integer index of the object class label from classes and the bounding box coordinates are expressed as relative coordinates in [0, 1] x [0, 1].

Parameters:

sample_collection – a fiftyone.core.collections.SampleCollection
label_field – the label field in which to store the labels. The field will be created if necessary
labels_path –
the YOLO-formatted labels to load. This can be any of the following:
- a dict mapping either image filenames or absolute filepaths to YOLO TXT filepaths. The image filenames/filepaths should match those in sample_collection, in any order
- a list of YOLO TXT filepaths corresponding 1-1 to the samples in sample_collection
- a directory containing YOLO TXT files whose filenames (less extension) correspond to image filenames in sample_collection, in any order
classes – the list of class label strings
label_type ("detections") – the label format to load. The supported values are ("detections", "polylines")
include_missing (False) – whether to insert empty labels for any samples in the input collection whose label_field is None after import

class fiftyone.utils.yolo.YOLOv4DatasetImporter(dataset_dir=None, data_path=None, labels_path=None, images_path=None, objects_path=None, classes=None, label_type='detections', include_all_data=False, shuffle=False, seed=None, max_samples=None)#

Bases: LabeledImageDatasetImporter, ImportPathsMixin

Importer for YOLOv4 datasets stored on disk.

See this page for format details.

Parameters:

dataset_dir (None) – the dataset directory. If omitted, data_path and/or labels_path must be provided
data_path (None) –
an optional parameter that enables explicit control over the location of the media. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of dataset_dir where the media files reside
- an absolute directory path where the media files reside. In this case, the dataset_dir has no effect on the location of the data
If None, this parameter will default to whichever of data/ or data.json exists in the dataset directory
labels_path (None) –
an optional parameter that enables explicit control over the location of the labels. Can be any of the following:
- a folder name like "labels" or "labels/" specifying the location of the labels in dataset_dir
- an absolute filepath to the labels. In this case, dataset_dir has no effect on the location of the labels
If None, the labels are assumed to be in the same folder as the data
images_path (None) –
an optional parameter that enables explicit control over the location of the image listing file. Can be any of the following:
- a filename like "images.txt" specifying the location of the image listing file labels in dataset_dir
- an absolute filepath to the image listing file. In this case, dataset_dir has no effect on the location of the file
If None, the parameter will default to images.txt
objects_path (None) –
an optional parameter that enables explicit control over the location of the object names file. Can be any of the following:
- a filename like "obj.names" specifying the location of the object names file labels in dataset_dir
- an absolute filepath to the object names file. In this case, dataset_dir has no effect on the location of the file
If None, the parameter will default to obj.names
classes (None) – the list of possible class labels. This does not need to be provided if objects_path contains the class labels
label_type ("detections") – the label format to load. The supported values are ("detections", "polylines")
include_all_data (False) – whether to generate samples for all images in the data directory (True) rather than only creating samples for images with labels (False)
shuffle (False) – whether to randomly shuffle the order in which the samples are imported
seed (None) – a random seed to use when shuffling
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

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

Methods:

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

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

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

property label_cls#

The fiftyone.core.labels.Label class(es) returned by this importer.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the importer is guaranteed to return labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the importer can produce a single label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the importer will return label dictionaries with keys and value-types specified by this dictionary. Not all keys need be present in the imported labels
None. In this case, the importer makes no guarantees about the labels that it may return

setup()#

Performs any necessary setup before importing the first sample in the dataset.

This method is called when the importer’s context manager interface is entered, DatasetImporter.__enter__().

get_dataset_info()#

Returns the dataset info for the dataset.

By convention, this method should be called after all samples in the dataset have been imported.

Returns:: a dict of dataset info

close(*args)#

Performs any necessary actions after the last sample has been imported.

This method is called when the importer’s context manager interface is exited, DatasetImporter.__exit__().

Parameters:: *args – the arguments to DatasetImporter.__exit__()

class fiftyone.utils.yolo.YOLOv5DatasetImporter(dataset_dir=None, yaml_path=None, split='val', label_type='detections', include_all_data=False, shuffle=False, seed=None, max_samples=None)#

Bases: LabeledImageDatasetImporter, ImportPathsMixin

Importer for YOLOv5 datasets stored on disk.

See this page for format details.

Parameters:

dataset_dir (None) – the dataset directory. If omitted, yaml_path must be provided
yaml_path (None) –
an optional parameter that enables explicit control over the location of the dataset YAML file. Can be any of the following:
- a filename like "dataset.yaml" specifying the name of the YAML file in dataset_dir
- an absolute path to the YAML file. In this case, dataset_dir has no effect
If None, the parameter will default to dataset.yaml
split ("val") – the split to load. Typical values are ("train", "val")
label_type ("detections") – the label format to load. The supported values are ("detections", "polylines")
include_all_data (False) – whether to generate samples for all images in the data directory (True) rather than only creating samples for images with labels (False)
shuffle (False) – whether to randomly shuffle the order in which the samples are imported
seed (None) – a random seed to use when shuffling
max_samples (None) – a maximum number of samples to import. By default, all samples are imported

Attributes:

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

Methods:

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

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

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

property label_cls#

The fiftyone.core.labels.Label class(es) returned by this importer.

This can be any of the following:

a fiftyone.core.labels.Label class. In this case, the importer is guaranteed to return labels of this type
a list or tuple of fiftyone.core.labels.Label classes. In this case, the importer can produce a single label field of any of these types
a dict mapping keys to fiftyone.core.labels.Label classes. In this case, the importer will return label dictionaries with keys and value-types specified by this dictionary. Not all keys need be present in the imported labels
None. In this case, the importer makes no guarantees about the labels that it may return

setup()#

Performs any necessary setup before importing the first sample in the dataset.

This method is called when the importer’s context manager interface is entered, DatasetImporter.__enter__().

get_dataset_info()#

Returns the dataset info for the dataset.

By convention, this method should be called after all samples in the dataset have been imported.

Returns:: a dict of dataset info

close(*args)#

Performs any necessary actions after the last sample has been imported.

This method is called when the importer’s context manager interface is exited, DatasetImporter.__exit__().

Parameters:: *args – the arguments to DatasetImporter.__exit__()

class fiftyone.utils.yolo.YOLOv4DatasetExporter(export_dir=None, data_path=None, labels_path=None, objects_path=None, images_path=None, export_media=None, rel_dir=None, classes=None, include_confidence=False, image_format=None)#

Bases: LabeledImageDatasetExporter, ExportPathsMixin

Exporter that writes YOLOv4 datasets to disk.

See this page for format details.

Parameters:

export_dir (None) – the directory to write the export. This has no effect if data_path, objects_path, and images_path are absolute paths
data_path (None) –
an optional parameter that enables explicit control over the location of the exported data and labels. Can be any of the following:
- a folder name like "data" or "data/" specifying a subfolder of export_dir in which to export the data and labels
- an absolute directory path in which to export the data and labels. In this case, the export_dir has no effect on the location of the data
If None, the data will be written into export_dir using the default folder name
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a folder name like "labels" or "labels/" specifying the location in export_dir in which to export the labels
- an absolute folder path to which to export the labels. In this case, the export_dir has no effect on the location of the labels
If None, the labels will be written into the same directory as the exported media
objects_path (None) –
an optional parameter that enables explicit control over the location of the object names file. Can be any of the following:
- a filename like "obj.names" specifying the location in export_dir in which to export the object names
- an absolute filepath to which to export the object names. In this case, the export_dir has no effect on the location of the object names
If None, the object names will be written into export_dir using the default filename, unless no media is being exported, in which case this file will not be written
images_path (None) –
an optional parameter that enables explicit control over the location of the image listing file. Can be any of the following:
- a filename like "images.txt" specifying the location in export_dir in which to export the image listing
- an absolute filepath to which to export the image listing. In this case, the export_dir has no effect on the location of the image listing
If None, the image listing will be written into export_dir using the default filename, unless no media is being exported, in which case this file will not be written
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with data_path and labels_path to generate output paths for each exported image and labels file. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
classes (None) – the list of possible class labels
include_confidence (False) – whether to include detection confidences in the export, if they exist
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used

Attributes:

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

Methods:

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

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

property label_cls#

The fiftyone.core.labels.Label class(es) exported by this exporter.

This can be any of the following:

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

setup()#

Performs any necessary setup before exporting the first sample in the dataset.

This method is called when the exporter’s context manager interface is entered, DatasetExporter.__enter__().

export_sample(image_or_path, label, metadata=None)#

Exports the given sample to the dataset.

Parameters:

image_or_path – an image or the path to the image on disk
label – an instance of label_cls(), or a dictionary mapping field names to fiftyone.core.labels.Label instances, or None if the sample is unlabeled
metadata (None) – a fiftyone.core.metadata.ImageMetadata instance for the sample. Only required when requires_image_metadata() is True

close(*args)#

Performs any necessary actions after the last sample has been exported.

This method is called when the exporter’s context manager interface is exited, DatasetExporter.__exit__().

Parameters:: *args – the arguments to DatasetExporter.__exit__()

log_collection(sample_collection)#

Logs any relevant information about the fiftyone.core.collections.SampleCollection whose samples will be exported.

Subclasses can optionally implement this method if their export format can record information such as the fiftyone.core.collections.SampleCollection.info() of the collection being exported.

By convention, this method must be optional; i.e., if it is not called before the first call to export_sample(), then the exporter must make do without any information about the fiftyone.core.collections.SampleCollection (which may not be available, for example, if the samples being exported are not stored in a collection).

Parameters:: sample_collection – the fiftyone.core.collections.SampleCollection whose samples will be exported

class fiftyone.utils.yolo.YOLOv5DatasetExporter(export_dir=None, split='val', data_path=None, labels_path=None, yaml_path=None, export_media=None, rel_dir=None, classes=None, include_confidence=False, image_format=None, include_path=True)#

Bases: LabeledImageDatasetExporter, ExportPathsMixin

Exporter that writes YOLOv5 datasets to disk.

See this page for format details.

Parameters:

export_dir (None) – the directory to write the export. This has no effect if data_path, labels_path, and yaml_path are absolute paths
split ("val") – the split being exported. Typical values are ("train", "val")
data_path (None) –
an optional parameter that enables explicit control over the location of the exported media. Can be any of the following:
- a folder name like "images" or "images/" specifying a subfolder of export_dir in which to export the images
- an absolute directory path in which to export the images. In this case, the export_dir has no effect on the location of the images
If None, the data will be written into export_dir using the default folder name
labels_path (None) –
an optional parameter that enables explicit control over the location of the exported labels. Can be any of the following:
- a folder name like "labels" or "labels/" specifying the location in export_dir in which to export the labels
- an absolute folder path to which to export the labels. In this case, the export_dir has no effect on the location of the labels
If None, the labels will be written into export_dir using the default folder name
yaml_path (None) –
an optional parameter that enables explicit control over the location of the dataset YAML file. Can be any of the following:
- a filename like "dataset.yaml" specifying the location in export_dir to write the YAML file
- an absolute filepath to which to write the YAML file. In this case, the export_dir has no effect on the location of the image listing
If None, the dataset YAML file will be written into export_dir using the default filename, unless no media is being exported, in which case this file will not be written
export_media (None) –
controls how to export the raw media. The supported values are:
- True: copy all media files into the output directory
- False: don’t export media
- "move": move all media files into the output directory
- "symlink": create symlinks to the media files in the output directory
If None, the default value of this parameter will be chosen based on the value of the data_path parameter
rel_dir (None) – an optional relative directory to strip from each input filepath to generate a unique identifier for each image. When exporting media, this identifier is joined with data_path and labels_path to generate output paths for each exported image and labels file. This argument allows for populating nested subdirectories that match the shape of the input paths. The path is converted to an absolute path (if necessary) via fiftyone.core.storage.normalize_path()
classes (None) – the list of possible class labels
include_confidence (False) – whether to include detection confidences in the export, if they exist
image_format (None) – the image format to use when writing in-memory images to disk. By default, fiftyone.config.default_image_ext is used
include_path (True) – whether to include the directory name containing the YAML file in the path key of the exported YAML

Attributes:

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

Methods:

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

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

property label_cls#

The fiftyone.core.labels.Label class(es) exported by this exporter.

This can be any of the following:

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

setup()#

Performs any necessary setup before exporting the first sample in the dataset.

This method is called when the exporter’s context manager interface is entered, DatasetExporter.__enter__().

export_sample(image_or_path, label, metadata=None)#

Exports the given sample to the dataset.

Parameters:

image_or_path – an image or the path to the image on disk
label – an instance of label_cls(), or a dictionary mapping field names to fiftyone.core.labels.Label instances, or None if the sample is unlabeled
metadata (None) – a fiftyone.core.metadata.ImageMetadata instance for the sample. Only required when requires_image_metadata() is True

close(*args)#

Performs any necessary actions after the last sample has been exported.

This method is called when the exporter’s context manager interface is exited, DatasetExporter.__exit__().

Parameters:: *args – the arguments to DatasetExporter.__exit__()

log_collection(sample_collection)#

Logs any relevant information about the fiftyone.core.collections.SampleCollection whose samples will be exported.

Subclasses can optionally implement this method if their export format can record information such as the fiftyone.core.collections.SampleCollection.info() of the collection being exported.

By convention, this method must be optional; i.e., if it is not called before the first call to export_sample(), then the exporter must make do without any information about the fiftyone.core.collections.SampleCollection (which may not be available, for example, if the samples being exported are not stored in a collection).

Parameters:: sample_collection – the fiftyone.core.collections.SampleCollection whose samples will be exported

class fiftyone.utils.yolo.YOLOAnnotationWriter#

Bases: object

Class for writing annotations in YOLO-style TXT format.

Methods:

write(label, txt_path, labels_map_rev[, ...])

Writes the labels to disk.

write(label, txt_path, labels_map_rev, dynamic_classes=False, include_confidence=False)#

Writes the labels to disk.

Parameters:

label – a fiftyone.core.labels.Detections or fiftyone.core.labels.Polylines
txt_path – the path to write the annotation TXT file
labels_map_rev – a dictionary mapping class label strings to target integers
dynamic_classes (False) – whether to dynamically add new labels to labels_map_rev
include_confidence (False) – whether to include confidences in the export, if they exist

fiftyone.utils.yolo.load_yolo_annotations(txt_path, classes, label_type='detections')#

Loads the YOLO-style annotations from the given TXT file.

The txt file should be a space-delimited file where each row corresponds to an object in one the following formats:

# Detections
<target> <x-center> <y-center> <width> <height>
<target> <x-center> <y-center> <width> <height> <confidence>

# Polylines
<target> <x1> <y1> <x2> <y2> <x3> <y3> ...

where target is the zero-based integer index of the object class label from classes and all coordinates are expressed as relative values in [0, 1] x [0, 1].

Parameters:

txt_path – the path to the annotations TXT file
classes – the list of class label strings
label_type ("detections") – the label format to load. The supported values are ("detections", "polylines")

Returns:

a fiftyone.core.labels.Detections or fiftyone.core.labels.Polylines