The first step to using FiftyOne is to load your data into a
[dataset](using_datasets.md#using-datasets). FiftyOne supports automatic loading of
datasets stored in various [common formats](#supported-import-formats).
If your dataset is stored in a custom format, don’t worry, FiftyOne also
provides support for easily loading datasets in
[custom formats](#loading-custom-datasets).
Check out the sections below to see which import pattern is the best fit for
your data.
#### NOTE
Did you know? You can import media and/or labels from within the FiftyOne
App by installing the
[@voxel51/io](https://github.com/voxel51/fiftyone-plugins/tree/main/plugins/io)
plugin!
#### NOTE
When you create a [`Dataset`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset), its samples and all of their fields (metadata,
labels, custom fields, etc.) are written to FiftyOne’s backing database.
**Important:** Samples only store the `filepath` to the media, not the
raw media itself. FiftyOne does not create duplicate copies of your data!
## Custom formats
The simplest and most flexible approach to loading your data into FiftyOne is
to iterate over your data in a simple Python loop, create a [`Sample`](../api/fiftyone.core.sample.md#fiftyone.core.sample.Sample) for each
data + label(s) pair, and then add those samples to a [`Dataset`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset).
FiftyOne provides [label types](using_datasets.md#using-labels) for common tasks such as
classification, detection, segmentation, and many more. The examples below
give you a sense of the basic workflow for a few tasks.
Image classification
Object detection
Labeled videos
3D scenes
```python
import glob
import fiftyone as fo
images_patt = "/path/to/images/*"
# Ex: your custom label format
annotations = {
"/path/to/images/000001.jpg": "dog",
....,
}
# Create samples for your data
samples = []
for filepath in glob.glob(images_patt):
sample = fo.Sample(filepath=filepath)
# Store classification in a field name of your choice
label = annotations[filepath]
sample["ground_truth"] = fo.Classification(label=label)
samples.append(sample)
# Create dataset
dataset = fo.Dataset("my-classification-dataset")
dataset.add_samples(samples)
```
```python
import glob
import fiftyone as fo
images_patt = "/path/to/images/*"
# Ex: your custom label format
annotations = {
"/path/to/images/000001.jpg": [
{"bbox": ..., "label": ...},
...
],
...
}
# Create samples for your data
samples = []
for filepath in glob.glob(images_patt):
sample = fo.Sample(filepath=filepath)
# Convert detections to FiftyOne format
detections = []
for obj in annotations[filepath]:
label = obj["label"]
# Bounding box coordinates should be relative values
# in [0, 1] in the following format:
# [top-left-x, top-left-y, width, height]
bounding_box = obj["bbox"]
detections.append(
fo.Detection(label=label, bounding_box=bounding_box)
)
# Store detections in a field name of your choice
sample["ground_truth"] = fo.Detections(detections=detections)
samples.append(sample)
# Create dataset
dataset = fo.Dataset("my-detection-dataset")
dataset.add_samples(samples)
```
```python
import fiftyone as fo
video_path = "/path/to/video.mp4"
# Ex: your custom label format
frame_labels = {
1: {
"weather": "sunny",
"objects": [
{
"label": ...
"bbox": ...
},
...
]
},
...
}
# Create video sample with frame labels
sample = fo.Sample(filepath=video_path)
for frame_number, labels in frame_labels.items():
frame = fo.Frame()
# Store a frame classification
weather = labels["weather"]
frame["weather"] = fo.Classification(label=weather)
# Convert detections to FiftyOne format
detections = []
for obj in labels["objects"]:
label = obj["label"]
# Bounding box coordinates should be relative values
# in [0, 1] in the following format:
# [top-left-x, top-left-y, width, height]
bounding_box = obj["bbox"]
detections.append(
fo.Detection(label=label, bounding_box=bounding_box)
)
# Store object detections
frame["objects"] = fo.Detections(detections=detections)
# Add frame to sample
sample.frames[frame_number] = frame
# Create dataset
dataset = fo.Dataset("my-labeled-video-dataset")
dataset.add_sample(sample)
```
```python
import fiftyone as fo
# Create a 3D scene with a mesh
scene = fo.Scene()
scene.add(fo.GltfMesh("mesh", "mesh.gltf"))
scene.write("/path/to/scene.fo3d")
# Define a 3D cuboid
detection = fo.Detection(
label="vehicle",
location=[0.47, 1.49, 69.44],
dimensions=[2.85, 2.63, 12.34],
rotation=[0, -1.56, 0],
)
# Construct a sample representing the scene
sample = fo.Sample(
filepath="/path/to/scene.fo3d",
ground_truth=fo.Detections(detections=[detection]),
)
# Create dataset
dataset = fo.Dataset("my-3d-dataset")
dataset.add_sample(sample)
```
#### NOTE
Using
[`Dataset.add_samples()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_samples)
to add batches of samples to your datasets can be significantly more
efficient than adding samples one-by-one via
[`Dataset.add_sample()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_sample).
#### NOTE
If you use the same custom data format frequently in your workflows, then
writing a [custom dataset importer](#custom-dataset-importer) is a
great way to abstract and streamline the loading of your data into
FiftyOne.
## Common formats
If your data is stored on disk in one of the
[many common formats](#supported-import-formats) supported natively by
FiftyOne, then you can load your data into a [`Dataset`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) via Python or the CLI
with the following simple pattern:
Python
CLI
You can import a [`Dataset`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) from disk via the
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) factory
method.
If your data is stored in the
[canonical format](#supported-import-formats) of the type you’re
importing, then you can load it by providing the `dataset_dir` and
`dataset_type` parameters:
```python
import fiftyone as fo
# The directory containing the dataset to import
dataset_dir = "/path/to/dataset"
# The type of the dataset being imported
dataset_type = fo.types.COCODetectionDataset # for example
# Import the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=dataset_type,
)
```
Alternatively, when importing labeled datasets in formats such as
[COCO](#cocodetectiondataset-import), you may find it more natural to
provide the `data_path` and `labels_path` parameters to independently
specify the location of the source media on disk and the annotations file
containing the labels to import:
```python
# The directory containing the source images
data_path = "/path/to/images"
# The path to the COCO labels JSON file
labels_path = "/path/to/coco-labels.json"
# Import the dataset
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.COCODetectionDataset,
data_path=data_path,
labels_path=labels_path,
)
```
Many formats like [COCO](#cocodetectiondataset-import) also support
storing absolute filepaths to the source media directly in the labels, in
which case you can provide only the `labels_path` parameter:
```python
# The path to a COCO labels JSON file containing absolute image paths
labels_path = "/path/to/coco-labels.json"
# Import the dataset
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.COCODetectionDataset,
labels_path=labels_path,
)
```
In general, you can pass any parameter for the [`DatasetImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.DatasetImporter) of the
format you’re importing to
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir). For
example, most builtin importers support optional `max_samples`, `shuffle`,
and `seed` parameters, which provide support for importing a small subset
of a potentially large dataset:
```python
# Import a random subset of 10 samples from the dataset
dataset = fo.Dataset.from_dir(
...,
max_samples=10,
shuffle=True,
seed=51,
)
```
You can import a dataset from disk into FiftyOne
[via the CLI](../cli/index.md#cli-fiftyone-datasets-create).
If your data is stored in the
[canonical format](#supported-import-formats) of the type you’re
importing, then you can load it by providing the `--dataset-dir` and
`--type` options:
```shell
# A name for the dataset
NAME=my-dataset
# The directory containing the dataset to import
DATASET_DIR=/path/to/dataset
# The type of the dataset being imported
# Any subclass of `fiftyone.types.Dataset` is supported
TYPE=fiftyone.types.COCODetectionDataset # for example
# Import the dataset
fiftyone datasets create --name $NAME --dataset-dir $DATASET_DIR --type $TYPE
```
Alternatively, when importing labeled datasets in formats such as
[COCO](#cocodetectiondataset-import), you may find it more natural to
provide the `data_path` and `labels_path` parameters via the
[kwargs option](../cli/index.md#cli-fiftyone-datasets-create) to independently
specify the location of the source media on disk and the annotations file
containing the labels to import:
```shell
# The directory containing the source images
DATA_PATH=/path/to/images
# The path to the COCO labels JSON file
LABELS_PATH=/path/to/coco-labels.json
# Import the dataset
fiftyone datasets create --name my-dataset \
--type fiftyone.types.COCODetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
Many formats like [COCO](#cocodetectiondataset-import) also support
storing absolute filepaths to the source media directly in the labels, in
which case you can provide only the `labels_path` parameter:
```shell
# The path to a COCO labels JSON file containing absolute image paths
LABELS_PATH=/path/to/coco-labels.json
# Import the dataset
fiftyone datasets create --name my-dataset \
--type fiftyone.types.COCODetectionDataset \
--kwargs labels_path=$LABELS_PATH
```
In general, you can pass any parameter for the [`DatasetImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.DatasetImporter) of the
format you’re importing via the
[kwargs option](../cli/index.md#cli-fiftyone-datasets-create). For example, most
builtin importers support optional `max_samples`, `shuffle`, and `seed`
parameters, which provide support for importing a small subset of a
potentially large dataset:
```shell
# Import a random subset of 10 samples from the dataset
fiftyone datasets create \
--name $NAME --dataset-dir $DATASET_DIR --type $TYPE \
--kwargs \
max_samples=10 \
shuffle=True \
seed=51
```
#### NOTE
Jump to [this section](#supported-import-formats) to see a full list
of supported import formats.
#### NOTE
Did you know? You can write
[custom importers](#custom-dataset-importer) to streamline import of
data in custom formats.
## Loading media
If you’re just getting started with a project and all you have is a bunch of
media files, you can easily load them into a FiftyOne dataset and start
visualizing them [in the App](app.md#fiftyone-app).
Images
Videos
You can use the
[`Dataset.from_images()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_images),
[`Dataset.from_images_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_images_dir), and
[`Dataset.from_images_patt()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_images_patt)
factory methods to load your images into FiftyOne:
```python
import fiftyone as fo
# Create a dataset from a list of images
dataset = fo.Dataset.from_images(
["/path/to/image1.jpg", "/path/to/image2.jpg", ...]
)
# Create a dataset from a directory of images
dataset = fo.Dataset.from_images_dir("/path/to/images")
# Create a dataset from a glob pattern of images
dataset = fo.Dataset.from_images_patt("/path/to/images/*.jpg")
session = fo.launch_app(dataset)
```
You can also use
[`Dataset.add_images()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_images),
[`Dataset.add_images_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_images_dir), and
[`Dataset.add_images_patt()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_images_patt)
to add images to an existing dataset.
You can use the [fiftyone app view](../cli/index.md#cli-fiftyone-app-view) command
from the CLI to quickly browse images in the App without creating a
(persistent) FiftyOne dataset:
```shell
# View a glob pattern of images in the App
fiftyone app view --images-patt '/path/to/images/*.jpg'
# View a directory of images in the App
fiftyone app view --images-dir '/path/to/images'
```
You can use the
[`Dataset.from_videos()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_videos),
[`Dataset.from_videos_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_videos_dir), and
[`Dataset.from_videos_patt()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_videos_patt)
factory methods to load your videos into FiftyOne:
```python
import fiftyone as fo
# Create a dataset from a list of videos
dataset = fo.Dataset.from_videos(
["/path/to/video1.mp4", "/path/to/video2.mp4", ...]
)
# Create a dataset from a directory of videos
dataset = fo.Dataset.from_videos_dir("/path/to/videos")
# Create a dataset from a glob pattern of videos
dataset = fo.Dataset.from_videos_patt("/path/to/videos/*.mp4")
session = fo.launch_app(dataset)
```
You can also use
[`Dataset.add_videos()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_videos),
[`Dataset.add_videos_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_videos_dir), and
[`Dataset.add_videos_patt()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.add_videos_patt)
to add videos to an existing dataset.
You can use the [fiftyone app view](../cli/index.md#cli-fiftyone-app-view) command
from the CLI to quickly browse videos in the App without creating a
(persistent) FiftyOne dataset:
```shell
# View a glob pattern of videos in the App
fiftyone app view --videos-patt '/path/to/videos/*.mp4'
# View a directory of videos in the App
fiftyone app view --videos-dir '/path/to/videos'
```
## Adding model predictions
Once you’ve created a dataset and ground truth labels, you can easily add model
predictions to take advantage of FiftyOne’s
[evaluation capabilities](evaluation/index.md#evaluating-models).
COCO
YOLO
Other formats
If you have model predictions stored in
[COCO format](#cocodetectiondataset-import), then you can use
[`add_coco_labels()`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.add_coco_labels) to
conveniently add the labels to an existing dataset.
The example below demonstrates a round-trip export and then re-import of
both images-and-labels and labels-only data in COCO format:
```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.utils.coco as fouc
dataset = foz.load_zoo_dataset("quickstart")
classes = dataset.distinct("predictions.detections.label")
# Export images and ground truth labels to disk
dataset.export(
export_dir="/tmp/coco",
dataset_type=fo.types.COCODetectionDataset,
label_field="ground_truth",
classes=classes,
)
# Export predictions
dataset.export(
dataset_type=fo.types.COCODetectionDataset,
labels_path="/tmp/coco/predictions.json",
label_field="predictions",
classes=classes,
)
# Now load ground truth labels into a new dataset
dataset2 = fo.Dataset.from_dir(
dataset_dir="/tmp/coco",
dataset_type=fo.types.COCODetectionDataset,
label_field="ground_truth",
label_types="detections",
)
# And add model predictions
fouc.add_coco_labels(
dataset2,
"predictions",
"/tmp/coco/predictions.json",
classes,
)
# Verify that ground truth and predictions were imported as expected
print(dataset.count("ground_truth.detections"))
print(dataset2.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(dataset2.count("predictions.detections"))
```
#### NOTE
See [`add_coco_labels()`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.add_coco_labels) for
a complete description of the available syntaxes for loading
COCO-formatted predictions to an existing dataset.
If you have model predictions stored in
[YOLO format](#yolov4dataset-import), then you can use
[`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) to
conveniently add the labels to an existing dataset.
The example below demonstrates a round-trip export and then re-import of
both images-and-labels and labels-only data in YOLO format:
```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.utils.yolo as fouy
dataset = foz.load_zoo_dataset("quickstart")
classes = dataset.distinct("predictions.detections.label")
# Export images and ground truth labels to disk
dataset.export(
export_dir="/tmp/yolov4",
dataset_type=fo.types.YOLOv4Dataset,
label_field="ground_truth",
classes=classes,
)
# Export predictions
dataset.export(
dataset_type=fo.types.YOLOv4Dataset,
labels_path="/tmp/yolov4/predictions",
label_field="predictions",
classes=classes,
)
# Now load ground truth labels into a new dataset
dataset2 = fo.Dataset.from_dir(
dataset_dir="/tmp/yolov4",
dataset_type=fo.types.YOLOv4Dataset,
label_field="ground_truth",
)
# And add model predictions
fouy.add_yolo_labels(
dataset2,
"predictions",
"/tmp/yolov4/predictions",
classes,
)
# Verify that ground truth and predictions were imported as expected
print(dataset.count("ground_truth.detections"))
print(dataset2.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(dataset2.count("predictions.detections"))
```
#### NOTE
See [`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) for
a complete description of the available syntaxes for loading
YOLO-formatted predictions to an existing dataset.
Model predictions stored in other formats can always be
[loaded iteratively](#loading-custom-datasets) through a simple Python
loop.
The example below shows how to add object detection predictions to a
dataset, but many [other label types](using_datasets.md#using-labels) are also
supported.
```python
import fiftyone as fo
# Ex: your custom predictions format
predictions = {
"/path/to/images/000001.jpg": [
{"bbox": ..., "label": ..., "score": ...},
...
],
...
}
# Add predictions to your samples
for sample in dataset:
filepath = sample.filepath
# Convert predictions to FiftyOne format
detections = []
for obj in predictions[filepath]:
label = obj["label"]
confidence = obj["score"]
# Bounding box coordinates should be relative values
# in [0, 1] in the following format:
# [top-left-x, top-left-y, width, height]
bounding_box = obj["bbox"]
detections.append(
fo.Detection(
label=label,
bounding_box=bounding_box,
confidence=confidence,
)
)
# Store detections in a field name of your choice
sample["predictions"] = fo.Detections(detections=detections)
sample.save()
```
#### NOTE
If you are in need of a model to run on your dataset, check out the
[FiftyOne Model Zoo](../model_zoo/index.md#model-zoo).
## Built-in formats
FiftyOne provides a variety of built-in importers for common data formats.
Each data format is represented by a subclass of
[`fiftyone.types.Dataset`](../api/fiftyone.types.md#fiftyone.types.Dataset), which is used by the Python library and CLI to
refer to the corresponding dataset format when reading the dataset from disk.
## Image Directory
The [`fiftyone.types.ImageDirectory`](../api/fiftyone.types.md#fiftyone.types.ImageDirectory) type represents a directory of
images.
Datasets of this type are read in the following format:
```text
/
..
```
where files with non-image MIME types are omitted.
By default, the dataset may contain nested subfolders of images, which are
recursively listed.
#### NOTE
See [`ImageDirectoryImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.ImageDirectoryImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a directory of images as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/images-dir"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.ImageDirectory,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/images-dir
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageDirectory
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a directory of images in the FiftyOne App without creating
a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/images-dir
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageDirectory
```
## Video Directory
The [`fiftyone.types.VideoDirectory`](../api/fiftyone.types.md#fiftyone.types.VideoDirectory) type represents a directory of
videos.
Datasets of this type are read in the following format:
```text
/
..
```
where files with non-video MIME types are omitted.
By default, the dataset may contain nested subfolders of videos, which are
recursively listed.
#### NOTE
See [`VideoDirectoryImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.VideoDirectoryImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a directory of videos as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/videos-dir"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.VideoDirectory,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/videos-dir
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VideoDirectory
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a directory of videos in the FiftyOne App without creating
a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/videos-dir
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VideoDirectory
```
## Media Directory
The [`fiftyone.types.MediaDirectory`](../api/fiftyone.types.md#fiftyone.types.MediaDirectory) type represents a directory of media
files.
Datasets of this type are read in the following format:
```text
/
..
```
#### NOTE
All files must have the same media type (image, video, point cloud, etc.)
By default, the dataset may contain nested subfolders of media files, which are
recursively listed.
#### NOTE
See [`MediaDirectoryImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.MediaDirectoryImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a directory of media files as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/media-dir"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.MediaDirectory,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/media-dir
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.MediaDirectory
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a directory of media in the FiftyOne App without creating
a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/media-dir
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.MediaDirectory
```
## Image Classification Dir Tree
The [`fiftyone.types.ImageClassificationDirectoryTree`](../api/fiftyone.types.md#fiftyone.types.ImageClassificationDirectoryTree) type represents a
directory tree whose subfolders define an image classification dataset.
Datasets of this type are read in the following format:
```text
/
/
..
...
/
..
...
...
```
Unlabeled images are stored in a subdirectory named `_unlabeled`.
Each class folder may contain nested subfolders of images.
#### NOTE
See [`ImageClassificationDirectoryTreeImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.ImageClassificationDirectoryTreeImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an image classification directory tree
stored in the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/image-classification-dir-tree"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.ImageClassificationDirectoryTree,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/image-classification-dir-tree
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageClassificationDirectoryTree
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view an image classification directory tree in the FiftyOne App
without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/image-classification-dir-tree
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageClassificationDirectoryTree
```
## Video Classification Dir Tree
The [`fiftyone.types.VideoClassificationDirectoryTree`](../api/fiftyone.types.md#fiftyone.types.VideoClassificationDirectoryTree) type represents a
directory tree whose subfolders define a video classification dataset.
Datasets of this type are read in the following format:
```text
/
/
..
...
/
..
...
...
```
Unlabeled videos are stored in a subdirectory named `_unlabeled`.
Each class folder may contain nested subfolders of videos.
#### NOTE
See [`VideoClassificationDirectoryTreeImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.VideoClassificationDirectoryTreeImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a video classification directory tree
stored in the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/video-classification-dir-tree"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.VideoClassificationDirectoryTree,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/video-classification-dir-tree
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VideoClassificationDirectoryTree
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a video classification directory tree in the FiftyOne App without
creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/video-classification-dir-tree
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VideoClassificationDirectoryTree
```
## FiftyOne Image Classification
The [`fiftyone.types.FiftyOneImageClassificationDataset`](../api/fiftyone.types.md#fiftyone.types.FiftyOneImageClassificationDataset) type represents
a labeled dataset consisting of images and their associated classification
label(s) stored in a simple JSON format.
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels.json
```
In the simplest case, `labels.json` can be a JSON file in the following format:
```text
{
"classes": [
"",
"",
...
],
"labels": {
"": ,
"": ,
...
}
}
```
If the `classes` field is provided, the `target` values are class IDs that are
mapped to class label strings via `classes[target]`. If no `classes` field is
provided, then the `target` values directly store the label strings.
The target value in `labels` for unlabeled images is `None` (or missing).
The UUIDs can also be relative paths like `path/to/uuid`, in which case the
images in `data/` should be arranged in nested subfolders with the
corresponding names, or they can be absolute paths, in which case the images
may or may not be in `data/`.
Alternatively, `labels.json` can contain predictions with associated
confidences and additional attributes in the following format:
```text
{
"classes": [
"",
"",
...
],
"labels": {
"": {
"label": ,
"confidence": ,
"attributes": {
: ,
...
}
},
"": {
"label": ,
"confidence": ,
"attributes": {
: ,
...
}
},
...
}
}
```
You can also load multilabel classifications in this format by storing lists
of targets in `labels.json`:
```text
{
"classes": [
"",
"",
...
],
"labels": {
"": [, , ...],
"": [, , ...],
...
}
}
```
where the target values in `labels` can be class strings, class IDs, or dicts
in the format described above defining class labels, confidences, and optional
attributes.
#### NOTE
See [`FiftyOneImageClassificationDatasetImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.FiftyOneImageClassificationDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an image classification dataset stored
in the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/image-classification-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.FiftyOneImageClassificationDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/image-classification-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneImageClassificationDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view an image classification dataset in the FiftyOne App without
creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/image-classification-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneImageClassificationDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/labels.json"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.FiftyOneImageClassificationDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/labels.json
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.FiftyOneImageClassificationDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the UUIDs in your labels are absolute paths to the source media, then
you can omit the `data_path` parameter from the example above.
## TF Image Classification
The [`fiftyone.types.TFImageClassificationDataset`](../api/fiftyone.types.md#fiftyone.types.TFImageClassificationDataset) type represents a
labeled dataset consisting of images and their associated classification labels
stored as
[TFRecords](https://www.tensorflow.org/tutorials/load_data/tfrecord).
Datasets of this type are read in the following format:
```text
/
tf.records-?????-of-?????
```
where the features of the (possibly sharded) TFRecords are stored in the
following format:
```python
{
# Image dimensions
"height": tf.io.FixedLenFeature([], tf.int64),
"width": tf.io.FixedLenFeature([], tf.int64),
"depth": tf.io.FixedLenFeature([], tf.int64),
# Image filename
"filename": tf.io.FixedLenFeature([], tf.int64),
# The image extension
"format": tf.io.FixedLenFeature([], tf.string),
# Encoded image bytes
"image_bytes": tf.io.FixedLenFeature([], tf.string),
# Class label string
"label": tf.io.FixedLenFeature([], tf.string, default_value=""),
}
```
For unlabeled samples, the TFRecords do not contain `label` features.
#### NOTE
See [`TFImageClassificationDatasetImporter`](../api/fiftyone.utils.tf.md#fiftyone.utils.tf.TFImageClassificationDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an image classification dataset stored
as a directory of TFRecords in the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/tf-image-classification-dataset"
images_dir = "/path/for/images"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.TFImageClassificationDataset,
images_dir=images_dir,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
When the above command is executed, the images in the TFRecords will be
written to the provided `images_dir`, which is required because FiftyOne
datasets must make their images available as individual files on disk.
```shell
NAME=my-dataset
DATASET_DIR=/path/to/tf-image-classification-dataset
IMAGES_DIR=/path/for/images
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.TFImageClassificationDataset \
--kwargs images_dir=$IMAGES_DIR
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
When the above command is executed, the images in the TFRecords will be
written to the provided `IMAGES_DIR`, which is required because FiftyOne
datasets must make their images available as individual files on disk.
To view an image classification dataset stored as a directory of TFRecords
in the FiftyOne App without creating a persistent FiftyOne dataset,
you can execute:
```shell
DATASET_DIR=/path/to/tf-image-classification-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.TFImageClassificationDataset
```
#### NOTE
You can provide the `tf_records_path` argument instead of `dataset_dir` in
the examples above to directly specify the path to the TFRecord(s) to load.
See [`TFImageClassificationDatasetImporter`](../api/fiftyone.utils.tf.md#fiftyone.utils.tf.TFImageClassificationDatasetImporter)
for details.
## COCO
The [`fiftyone.types.COCODetectionDataset`](../api/fiftyone.types.md#fiftyone.types.COCODetectionDataset) type represents a labeled
dataset consisting of images and their associated object detections saved in
[COCO Object Detection Format](https://cocodataset.org/#format-data).
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels.json
```
where `labels.json` is a JSON file in the following format:
```text
{
"info": {...},
"licenses": [
{
"id": 1,
"name": "Attribution-NonCommercial-ShareAlike License",
"url": "http://creativecommons.org/licenses/by-nc-sa/2.0/",
},
...
],
"categories": [
{
"id": 1,
"name": "cat",
"supercategory": "animal",
"keypoints": ["nose", "head", ...],
"skeleton": [[12, 14], [14, 16], ...]
},
...
],
"images": [
{
"id": 1,
"license": 1,
"file_name": ".",
"height": 480,
"width": 640,
"date_captured": null
},
...
],
"annotations": [
{
"id": 1,
"image_id": 1,
"category_id": 1,
"bbox": [260, 177, 231, 199],
"segmentation": [...],
"keypoints": [224, 226, 2, ...],
"num_keypoints": 10,
"score": 0.95,
"area": 45969,
"iscrowd": 0
},
...
]
}
```
See [this page](https://cocodataset.org/#format-data) for a full
specification of the `segmentation` field.
For unlabeled datasets, `labels.json` does not contain an `annotations` field.
The `file_name` attribute of the labels file encodes the location of the
corresponding images, which can be any of the following:
- The filename of an image in the `data/` folder
- A relative path like `data/sub/folder/filename.ext` specifying the relative
path to the image in a nested subfolder of `data/`
- An absolute path to an image, which may or may not be in the `data/` folder
#### NOTE
See [`COCODetectionDatasetImporter`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.COCODetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a COCO detection dataset stored in the
above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/coco-detection-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.COCODetectionDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/coco-detection-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.COCODetectionDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a COCO detection dataset stored in the above format in the FiftyOne
App without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/coco-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.COCODetectionDataset
```
#### NOTE
By default, all supported label types are loaded (detections,
segmentations, and keypoints). However, you can choose specific type(s) to
load by passing the optional `label_types` argument to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir):
```python
# Only load bounding boxes
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.COCODetectionDataset,
label_types=["detections"],
...
)
```
See [`COCODetectionDatasetImporter`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.COCODetectionDatasetImporter)
for complete documentation of the available COCO import options.
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/coco-labels.json"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.COCODetectionDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/coco-labels.json
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.COCODetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the `file_name` key of your labels contains absolute paths to the source
media, then you can omit the `data_path` parameter from the example above.
If you have an existing dataset and corresponding model predictions stored in
COCO format, then you can use
[`add_coco_labels()`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.add_coco_labels) to conveniently
add the labels to the dataset. The example below demonstrates a round-trip
export and then re-import of both images-and-labels and labels-only data in
COCO format:
```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.utils.coco as fouc
dataset = foz.load_zoo_dataset("quickstart")
classes = dataset.distinct("predictions.detections.label")
# Export images and ground truth labels to disk
dataset.export(
export_dir="/tmp/coco",
dataset_type=fo.types.COCODetectionDataset,
label_field="ground_truth",
classes=classes,
)
# Export predictions
dataset.export(
dataset_type=fo.types.COCODetectionDataset,
labels_path="/tmp/coco/predictions.json",
label_field="predictions",
classes=classes,
)
# Now load ground truth labels into a new dataset
dataset2 = fo.Dataset.from_dir(
dataset_dir="/tmp/coco",
dataset_type=fo.types.COCODetectionDataset,
label_field="ground_truth",
)
# And add model predictions
fouc.add_coco_labels(
dataset2,
"predictions",
"/tmp/coco/predictions.json",
classes,
)
# Verify that ground truth and predictions were imported as expected
print(dataset.count("ground_truth.detections"))
print(dataset2.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(dataset2.count("predictions.detections"))
```
#### NOTE
See [`add_coco_labels()`](../api/fiftyone.utils.coco.md#fiftyone.utils.coco.add_coco_labels) for a
complete description of the available syntaxes for loading COCO-formatted
predictions to an existing dataset.
## VOC
The [`fiftyone.types.VOCDetectionDataset`](../api/fiftyone.types.md#fiftyone.types.VOCDetectionDataset) type represents a labeled
dataset consisting of images and their associated object detections saved in
[VOC format](http://host.robots.ox.ac.uk/pascal/VOC).
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels/
.xml
.xml
...
```
where the labels XML files are in the following format:
```xml
image.ext/path/to/dataset-dir/data/image.ext6404803
...
```
where either the `` and/or `` field of the annotations may be
populated to specify the corresponding source image.
Unlabeled images have no corresponding file in `labels/`.
The `data/` and `labels/` files may contain nested subfolders of parallelly
organized images and masks.
#### NOTE
See [`VOCDetectionDatasetImporter`](../api/fiftyone.utils.voc.md#fiftyone.utils.voc.VOCDetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a VOC detection dataset stored in the
above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/voc-detection-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.VOCDetectionDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/voc-detection-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VOCDetectionDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a VOC detection dataset stored in the above format in the FiftyOne
App without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/voc-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.VOCDetectionDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/voc-labels"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.VOCDetectionDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/voc-labels
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.VOCDetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the `` field of your labels are populated with the absolute paths
to the source media, then you can omit the `data_path` parameter from the
example above.
## KITTI
The [`fiftyone.types.KITTIDetectionDataset`](../api/fiftyone.types.md#fiftyone.types.KITTIDetectionDataset) type represents a labeled
dataset consisting of images and their associated object detections saved in
[KITTI format](http://www.cvlibs.net/datasets/kitti/eval_object.php).
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels/
.txt
.txt
...
```
where the labels TXT files are space-delimited files where each row corresponds
to an object and the 15 (and optional 16th score) columns have the following
meanings:
| # of columns | Name | Description | Default |
|--------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
| 1 | type | The object label | |
| 1 | truncated | A float in `[0, 1]`, where 0 is non-truncated and 1 is fully truncated. Here, truncation refers to the object leaving image boundaries | 0 |
| 1 | occluded | An int in `(0, 1, 2, 3)` indicating occlusion state, where:- 0 = fully visible- 1 = partly occluded- 2 = largely occluded- 3 = unknown | 0 |
| 1 | alpha | Observation angle of the object, in `[-pi, pi]` | 0 |
| 4 | bbox | 2D bounding box of object in the image in pixels, in the format `[xtl, ytl, xbr, ybr]` | |
| 1 | dimensions | 3D object dimensions, in meters, in the format `[height, width, length]` | 0 |
| 1 | location | 3D object location `(x, y, z)` in camera coordinates (in meters) | 0 |
| 1 | rotation_y | Rotation around the y-axis in camera coordinates, in `[-pi, pi]` | 0 |
| 1 | score | `(optional)` A float confidence for the detection | |
When reading datasets of this type, all columns after the four `bbox` columns
are optional.
Unlabeled images have no corresponding file in `labels/`.
The `data/` and `labels/` files may contain nested subfolders of parallelly
organized images and masks.
#### NOTE
See [`KITTIDetectionDatasetImporter`](../api/fiftyone.utils.kitti.md#fiftyone.utils.kitti.KITTIDetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a KITTI detection dataset stored in the
above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/kitti-detection-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.KITTIDetectionDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/kitti-detection-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.KITTIDetectionDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a KITTI detection dataset stored in the above format in the
FiftyOne App without creating a persistent FiftyOne dataset, you can
execute:
```shell
DATASET_DIR=/path/to/kitti-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.KITTIDetectionDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/kitti-labels"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.KITTIDetectionDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/kitti-labels
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.KITTIDetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
## YOLOv4
The [`fiftyone.types.YOLOv4Dataset`](../api/fiftyone.types.md#fiftyone.types.YOLOv4Dataset) type represents a labeled dataset
consisting of images and their associated object detections saved in
[YOLOv4 format](https://github.com/AlexeyAB/darknet).
Datasets of this type are read in the following format:
```text
/
obj.names
images.txt
data/
..txt
..txt
...
```
where `obj.names` contains the object class labels:
```text
...
```
and `images.txt` contains the list of images in `data/`:
```text
data/.
data/.
...
```
The image paths in `images.txt` can be specified as either relative (to the
location of file) or as absolute paths. Alternatively, this file can be
omitted, in which case the `data/` directory is listed to determine the
available images.
The TXT files in `data/` are space-delimited files where each row corresponds
to an object in the image of the same name, in one of the following formats:
```text
# Detections
# Instance segmentations or polygons
...
```
where `` is the zero-based integer index of the object class label from
`obj.names`, all coordinates are expressed as relative values in
`[0, 1] x [0, 1]`, and `` is an optional confidence in `[0, 1]`.
Unlabeled images have no corresponding TXT file in `data/`.
The `data/` folder may contain nested subfolders.
#### NOTE
By default, all annotations are loaded as [`Detections`](../api/fiftyone.core.labels.md#fiftyone.core.labels.Detections), converting any
polylines to tight bounding boxes if necessary. However, you can choose to
load YOLO annotations as instance segmentations or polygons by passing the
optional `label_type` argument to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir):
```python
# Load annotations as instance segmentations
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.YOLOv4Dataset,
label_type="instances",
mask_size=(width, height), # optional size for each dense mask
...
)
# Load annotations as polygons
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.YOLOv4Dataset,
label_type="polylines",
...
)
```
See [`YOLOv4DatasetImporter`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.YOLOv4DatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a YOLOv4 dataset stored in the above
format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/yolov4-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.YOLOv4Dataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/yolov4-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.YOLOv4Dataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a YOLOv4 dataset stored in the above format in the FiftyOne App
without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/yolov4-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.YOLOv4Dataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/yolo-labels"
classes = ["list", "of", "classes"]
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.YOLOv4Dataset,
data_path=data_path,
labels_path=labels_path,
classes=classes,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/yolo-labels
OBJECTS_PATH=/path/to/obj.names
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.YOLOv4Dataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH \
objects_path=$OBJECTS_PATH
```
If you have an existing dataset and corresponding model predictions stored in
YOLO format, then you can use
[`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) to conveniently
add the labels to the dataset.
The example below demonstrates a round-trip export and then re-import of both
images-and-labels and labels-only data in YOLO format:
```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.utils.yolo as fouy
dataset = foz.load_zoo_dataset("quickstart")
classes = dataset.distinct("predictions.detections.label")
# Export images and ground truth labels to disk
dataset.export(
export_dir="/tmp/yolov4",
dataset_type=fo.types.YOLOv4Dataset,
label_field="ground_truth",
classes=classes,
)
# Export predictions
dataset.export(
dataset_type=fo.types.YOLOv4Dataset,
labels_path="/tmp/yolov4/predictions",
label_field="predictions",
classes=classes,
)
# Now load ground truth labels into a new dataset
dataset2 = fo.Dataset.from_dir(
dataset_dir="/tmp/yolov4",
dataset_type=fo.types.YOLOv4Dataset,
label_field="ground_truth",
)
# And add model predictions
fouy.add_yolo_labels(
dataset2,
"predictions",
"/tmp/yolov4/predictions",
classes,
)
# Verify that ground truth and predictions were imported as expected
print(dataset.count("ground_truth.detections"))
print(dataset2.count("ground_truth.detections"))
print(dataset.count("predictions.detections"))
print(dataset2.count("predictions.detections"))
```
#### NOTE
See [`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) for a
complete description of the available syntaxes for loading YOLO-formatted
predictions to an existing dataset.
## YOLOv5
The [`fiftyone.types.YOLOv5Dataset`](../api/fiftyone.types.md#fiftyone.types.YOLOv5Dataset) type represents a labeled dataset
consisting of images and their associated object detections saved in
[YOLOv5 format](https://github.com/ultralytics/yolov5).
Datasets of this type are read in the following format:
```text
/
dataset.yaml
images/
train/
..
...
val/
..
...
labels/
train/
.txt
.txt
...
val/
.txt
.txt
...
```
where `dataset.yaml` contains the following information:
```text
path: # optional
train: ./images/train/
val: ./images/val/
names:
0: list
1: of
2: classes
...
```
See [this page](https://docs.ultralytics.com/datasets/detect) for a full
description of the possible format of `dataset.yaml`. In particular, the
dataset may contain one or more splits with arbitrary names, as the specific
split being imported or exported is specified by the `split` argument to
[`fiftyone.utils.yolo.YOLOv5DatasetImporter`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.YOLOv5DatasetImporter). Also, `dataset.yaml` can be
located outside of `` as long as the optional `path` is provided.
#### NOTE
Any relative paths in `dataset.yaml` or per-split TXT files are interpreted
relative to the directory containing these files, not your current working
directory.
The TXT files in `labels/` are space-delimited files where each row corresponds
to an object in the image of the same name, in one of the following formats:
```text
# Detections
# Instance segmentations or polygons
...
```
where `` is the zero-based integer index of the object class label from
`names`, all coordinates are expressed as relative values in `[0, 1] x [0, 1]`,
and `` is an optional confidence in `[0, 1]`.
Unlabeled images have no corresponding TXT file in `labels/`. The label file
path for each image is obtained by replacing `images/` with `labels/` in the
respective image path.
The image and labels directories for a given split may contain nested
subfolders of parallelly organized images and labels.
#### NOTE
By default, all annotations are loaded as [`Detections`](../api/fiftyone.core.labels.md#fiftyone.core.labels.Detections), converting any
polylines to tight bounding boxes if necessary. However, you can choose to
load YOLO annotations as instance segmentations or polygons by passing the
optional `label_type` argument to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir):
```python
# Load annotations as instance segmentations
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.YOLOv5Dataset,
label_type="instances",
mask_size=(width, height), # optional size for each dense mask
...
)
# Load annotations as polygons
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.YOLOv5Dataset,
label_type="polylines",
...
)
```
See [`YOLOv5DatasetImporter`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.YOLOv5DatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a YOLOv5 dataset stored in the above
format as follows:
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/yolov5-dataset"
# The splits to load
splits = ["train", "val"]
# Load the dataset, using tags to mark the samples in each split
dataset = fo.Dataset(name)
for split in splits:
dataset.add_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.YOLOv5Dataset,
split=split,
tags=split,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
If you have an existing dataset and corresponding model predictions stored in
YOLO format, then you can use
[`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) to conveniently
add the labels to the dataset.
The example below demonstrates a round-trip export and then re-import of both
images-and-labels and labels-only data in YOLO format:
```python
import fiftyone as fo
import fiftyone.zoo as foz
import fiftyone.utils.yolo as fouy
dataset = foz.load_zoo_dataset("quickstart")
classes = dataset.distinct("predictions.detections.label")
# YOLOv5 format supports splits, so let's grab only the `validation` split
view = dataset.match_tags("validation")
# Export images and ground truth labels to disk
view.export(
export_dir="/tmp/yolov5",
dataset_type=fo.types.YOLOv5Dataset,
split="validation",
label_field="ground_truth",
classes=classes,
)
# Export predictions
view.export(
dataset_type=fo.types.YOLOv5Dataset,
labels_path="/tmp/yolov5/predictions/validation",
label_field="predictions",
classes=classes,
)
# Now load ground truth labels into a new dataset
dataset2 = fo.Dataset.from_dir(
dataset_dir="/tmp/yolov5",
dataset_type=fo.types.YOLOv5Dataset,
split="validation",
label_field="ground_truth",
)
# And add model predictions
fouy.add_yolo_labels(
dataset2,
"predictions",
"/tmp/yolov5/predictions/validation",
classes,
)
# Verify that ground truth and predictions were imported as expected
print(view.count("ground_truth.detections"))
print(dataset2.count("ground_truth.detections"))
print(view.count("predictions.detections"))
print(dataset2.count("predictions.detections"))
```
#### NOTE
See [`add_yolo_labels()`](../api/fiftyone.utils.yolo.md#fiftyone.utils.yolo.add_yolo_labels) for a
complete description of the available syntaxes for loading YOLO-formatted
predictions to an existing dataset.
## FiftyOne Object Detection
The [`fiftyone.types.FiftyOneImageDetectionDataset`](../api/fiftyone.types.md#fiftyone.types.FiftyOneImageDetectionDataset) type represents a
labeled dataset consisting of images and their associated object detections
stored in a simple JSON format.
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels.json
```
where `labels.json` is a JSON file in the following format:
```text
{
"classes": [
,
,
...
],
"labels": {
: [
{
"label": ,
"bounding_box": [
, , ,
],
"confidence": ,
"attributes": {
: ,
...
}
},
...
],
: [
...
],
...
}
}
```
and where the bounding box coordinates are expressed as relative values in
`[0, 1] x [0, 1]`.
If the `classes` field is provided, the `target` values are class IDs that are
mapped to class label strings via `classes[target]`. If no `classes` field is
provided, then the `target` values directly store the label strings.
The target value in `labels` for unlabeled images is `None` (or missing).
The UUIDs can also be relative paths like `path/to/uuid`, in which case the
images in `data/` should be arranged in nested subfolders with the
corresponding names, or they can be absolute paths, in which case the images
may or may not be in `data/`.
#### NOTE
See [`FiftyOneImageDetectionDatasetImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.FiftyOneImageDetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an image detection dataset stored in the
above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/image-detection-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.FiftyOneImageDetectionDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/image-detection-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneImageDetectionDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view an image detection dataset stored in the above format in the
FiftyOne App without creating a persistent FiftyOne dataset, you
can execute:
```shell
DATASET_DIR=/path/to/image-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneImageDetectionDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/labels.json"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.FiftyOneImageDetectionDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/labels.json
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.FiftyOneImageDetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the UUIDs in your labels are absolute paths to the source media, then
you can omit the `data_path` parameter from the example above.
## FiftyOne Temporal Detection
The [`fiftyone.types.FiftyOneTemporalDetectionDataset`](../api/fiftyone.types.md#fiftyone.types.FiftyOneTemporalDetectionDataset) type represents a
labeled dataset consisting of videos and their associated temporal detections
stored in a simple JSON format.
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels.json
```
where `labels.json` is a JSON file in the following format:
```text
{
"classes": [
"",
"",
...
],
"labels": {
"": [
{
"label": ,
"support": [, ],
"confidence": ,
"attributes": {
: ,
...
}
},
{
"label": ,
"support": [, ],
"confidence": ,
"attributes": {
: ,
...
}
},
...
],
"": [
{
"label": ,
"timestamps": [, ],
"confidence": ,
"attributes": {
: ,
...
}
},
{
"label": ,
"timestamps": [, ],
"confidence": ,
"attributes": {
: ,
...
}
},
],
...
}
}
```
The temporal range of each detection can be specified either via the `support`
key, which should contain the `[first, last]` frame numbers of the detection,
or the `timestamps` key, which should contain the `[start, stop]` timestamps of
the detection in seconds.
If the `classes` field is provided, the `target` values are class IDs that are
mapped to class label strings via `classes[target]`. If no `classes` field is
provided, then the `target` values directly store the label strings.
Unlabeled videos can have a `None` (or missing) key in `labels`.
The UUIDs can also be relative paths like `path/to/uuid`, in which case the
images in `data/` should be arranged in nested subfolders with the
corresponding names, or they can be absolute paths, in which case the images
may or may not be in `data/`.
#### NOTE
See [`FiftyOneTemporalDetectionDatasetImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.FiftyOneTemporalDetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a temporal detection dataset stored in
the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/temporal-detection-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.FiftyOneTemporalDetectionDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/temporal-detection-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneTemporalDetectionDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a temporal detection dataset in the FiftyOne App without creating
a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/temporal-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.FiftyOneTemporalDetectionDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/labels.json"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.FiftyOneTemporalDetectionDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/labels.json
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.FiftyOneTemporalDetectionDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the UUIDs in your labels are absolute paths to the source media, then
you can omit the `data_path` parameter from the example above.
## TF Object Detection
The [`fiftyone.types.TFObjectDetectionDataset`](../api/fiftyone.types.md#fiftyone.types.TFObjectDetectionDataset) type represents a labeled
dataset consisting of images and their associated object detections stored as
[TFRecords](https://www.tensorflow.org/tutorials/load_data/tfrecord) in
[TF Object Detection API format](https://github.com/tensorflow/models/blob/master/research/object_detection).
Datasets of this type are read in the following format:
```text
/
tf.records-?????-of-?????
```
where the features of the (possibly sharded) TFRecords are stored in the
following format:
```python
{
# Image dimensions
"image/height": tf.io.FixedLenFeature([], tf.int64),
"image/width": tf.io.FixedLenFeature([], tf.int64),
# Image filename is used for both of these when writing
"image/filename": tf.io.FixedLenFeature([], tf.string),
"image/source_id": tf.io.FixedLenFeature([], tf.string),
# Encoded image bytes
"image/encoded": tf.io.FixedLenFeature([], tf.string),
# Image format, either `jpeg` or `png`
"image/format": tf.io.FixedLenFeature([], tf.string),
# Normalized bounding box coordinates in `[0, 1]`
"image/object/bbox/xmin": tf.io.FixedLenSequenceFeature(
[], tf.float32, allow_missing=True
),
"image/object/bbox/xmax": tf.io.FixedLenSequenceFeature(
[], tf.float32, allow_missing=True
),
"image/object/bbox/ymin": tf.io.FixedLenSequenceFeature(
[], tf.float32, allow_missing=True
),
"image/object/bbox/ymax": tf.io.FixedLenSequenceFeature(
[], tf.float32, allow_missing=True
),
# Class label string
"image/object/class/text": tf.io.FixedLenSequenceFeature(
[], tf.string, allow_missing=True
),
# Integer class ID
"image/object/class/label": tf.io.FixedLenSequenceFeature(
[], tf.int64, allow_missing=True
),
}
```
The TFRecords for unlabeled samples do not contain `image/object/*` features.
#### NOTE
See [`TFObjectDetectionDatasetImporter`](../api/fiftyone.utils.tf.md#fiftyone.utils.tf.TFObjectDetectionDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an object detection dataset stored as a
directory of TFRecords in the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/tf-object-detection-dataset"
images_dir = "/path/for/images"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.TFObjectDetectionDataset,
images_dir=images_dir,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
When the above command is executed, the images in the TFRecords will be
written to the provided `images_dir`, which is required because FiftyOne
datasets must make their images available as individual files on disk.
```shell
NAME=my-dataset
DATASET_DIR=/path/to/tf-object-detection-dataset
IMAGES_DIR=/path/for/images
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.TFObjectDetectionDataset \
--kwargs images_dir=$IMAGES_DIR
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
When the above command is executed, the images in the TFRecords will be
written to the provided `IMAGES_DIR`, which is required because FiftyOne
datasets must make their images available as individual files on disk.
To view an object detection dataset stored as a directory of TFRecords in
the FiftyOne App without creating a persistent FiftyOne dataset, you can
execute:
```shell
DATASET_DIR=/path/to/tf-object-detection-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.TFObjectDetectionDataset
```
#### NOTE
You can provide the `tf_records_path` argument instead of `dataset_dir` in
the examples above to directly specify the path to the TFRecord(s) to load.
See [`TFObjectDetectionDatasetImporter`](../api/fiftyone.utils.tf.md#fiftyone.utils.tf.TFObjectDetectionDatasetImporter)
for details.
## Image Segmentation Directory
The [`fiftyone.types.ImageSegmentationDirectory`](../api/fiftyone.types.md#fiftyone.types.ImageSegmentationDirectory) type represents a
labeled dataset consisting of images and their associated semantic
segmentations stored as images on disk.
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels/
..
...
```
where `labels/` contains the semantic segmentations stored as images.
Unlabeled images have no corresponding file in `labels/`.
The `data/` and `labels/` files may contain nested subfolders of parallelly
organized images and masks.
#### NOTE
See [`ImageSegmentationDirectoryImporter`](../api/fiftyone.utils.data.importers.md#fiftyone.utils.data.importers.ImageSegmentationDirectoryImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from an image segmentation dataset stored in
the above format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/image-segmentation-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.ImageSegmentationDirectory,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/image-segmentation-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageSegmentationDirectory
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view an image segmentation dataset stored in the above format in the
FiftyOne App without creating a persistent FiftyOne dataset, you
can execute:
```shell
DATASET_DIR=/path/to/image-segmentation-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.ImageSegmentationDirectory
```
You can also independently specify the locations of the masks and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/masks"
# Import dataset by explicitly providing paths to the source media and masks
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.ImageSegmentationDirectory,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/masks
# Import dataset by explicitly providing paths to the source media and masks
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.ImageSegmentationDirectory \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
## CVAT Image
The [`fiftyone.types.CVATImageDataset`](../api/fiftyone.types.md#fiftyone.types.CVATImageDataset) type represents a labeled dataset
consisting of images and their associated tags and object detections stored in
[CVAT image format](https://github.com/opencv/cvat).
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels.xml
```
where `labels.xml` is an XML file in the following format:
```xml
1.10task-name51annotationFalse2017-11-20 11:51:51.000000+00:002017-11-20 11:51:51.000000+00:00
...
00502017-11-20 11:51:51.000000+00:00
...
sedan
...
...
Honda
...
...
yellow
...
...
front_driver_side
...
...
...
...
```
Unlabeled images have no corresponding `image` tag in `labels.xml`.
The `name` field of the `` tags in the labels file encodes the location
of the corresponding images, which can be any of the following:
- The filename of an image in the `data/` folder
- A relative path like `data/sub/folder/filename.ext` specifying the relative
path to the image in a nested subfolder of `data/`
- An absolute path to an image, which may or may not be in the `data/` folder
#### NOTE
See [`CVATImageDatasetImporter`](../api/fiftyone.utils.cvat.md#fiftyone.utils.cvat.CVATImageDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a CVAT image dataset stored in the above
format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/cvat-image-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.CVATImageDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/cvat-image-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.CVATImageDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a CVAT image dataset stored in the above format in the FiftyOne
App without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/cvat-image-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.CVATImageDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/cvat-labels.xml"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.CVATImageDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/cvat-labels.xml
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.CVATImageDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
#### NOTE
If the `name` key of your labels contains absolute paths to the source
media, then you can omit the `data_path` parameter from the example above.
## CVAT Video
The [`fiftyone.types.CVATVideoDataset`](../api/fiftyone.types.md#fiftyone.types.CVATVideoDataset) type represents a labeled dataset
consisting of videos and their associated object detections stored in
[CVAT video format](https://github.com/opencv/cvat).
Datasets of this type are read in the following format:
```text
/
data/
..
...
labels/
.xml
.xml
...
```
where the labels XML files are stored in the following format:
```xml
1.1task-idtask-name51interpolationFalse2017-11-20 11:51:51.000000+00:002017-11-20 11:51:51.000000+00:00
...
00506404802017-11-20 11:51:51.000000+00:00
...
...
```
Unlabeled videos have no corresponding file in `labels/`.
The `data/` and `labels/` files may contain nested subfolders of parallelly
organized images and labels.
#### NOTE
See [`CVATVideoDatasetImporter`](../api/fiftyone.utils.cvat.md#fiftyone.utils.cvat.CVATVideoDatasetImporter)
for parameters that can be passed to methods like
[`Dataset.from_dir()`](../api/fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset.from_dir) to
customize the import of datasets of this type.
You can create a FiftyOne dataset from a CVAT video dataset stored in the above
format as follows:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
dataset_dir = "/path/to/cvat-video-dataset"
# Create the dataset
dataset = fo.Dataset.from_dir(
dataset_dir=dataset_dir,
dataset_type=fo.types.CVATVideoDataset,
name=name,
)
# View summary info about the dataset
print(dataset)
# Print the first few samples in the dataset
print(dataset.head())
```
```shell
NAME=my-dataset
DATASET_DIR=/path/to/cvat-video-dataset
# Create the dataset
fiftyone datasets create \
--name $NAME \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.CVATVideoDataset
# View summary info about the dataset
fiftyone datasets info $NAME
# Print the first few samples in the dataset
fiftyone datasets head $NAME
```
To view a CVAT video dataset stored in the above format in the FiftyOne
App without creating a persistent FiftyOne dataset, you can execute:
```shell
DATASET_DIR=/path/to/cvat-video-dataset
# View the dataset in the App
fiftyone app view \
--dataset-dir $DATASET_DIR \
--type fiftyone.types.CVATVideoDataset
```
You can also independently specify the locations of the labels and the root
directory containing the corresponding media files by providing the
`labels_path` and `data_path` parameters rather than `dataset_dir`:
Python
CLI
```python
import fiftyone as fo
name = "my-dataset"
data_path = "/path/to/images"
labels_path = "/path/to/cvat-labels"
# Import dataset by explicitly providing paths to the source media and labels
dataset = fo.Dataset.from_dir(
dataset_type=fo.types.CVATVideoDataset,
data_path=data_path,
labels_path=labels_path,
name=name,
)
```
```shell
NAME=my-dataset
DATA_PATH=/path/to/images
LABELS_PATH=/path/to/cvat-labels
# Import dataset by explicitly providing paths to the source media and labels
fiftyone datasets create \
--name $NAME \
--type fiftyone.types.CVATVideoDataset \
--kwargs \
data_path=$DATA_PATH \
labels_path=$LABELS_PATH
```
## OpenLABEL Image
The [`fiftyone.types.OpenLABELImageDataset`](../api/fiftyone.types.md#fiftyone.types.OpenLABELImageDataset) type represents a labeled
dataset consisting of images and their associated multitask predictions stored =
in [OpenLABEL format](https://www.asam.net/index.php?eID=dumpFile&t=f&f=3876&token=413e8c85031ae64cc35cf42d0768627514868b2f).
OpenLABEL is a flexible format which allows labels to be stored in a variety of
different ways with respect to the corresponding media files. The following
enumerates the possible structures in which media data and OpenLABEL formatted
label files can be stored in ways that is understood by FiftyOne:
1. One label file per image. Each label contains only the metadata and labels
associated with the image of the same name. In this case, the `labels_path`
argument is expected to be a directory, if provided:
```text
/
data/
..
...
labels/
.json
.json
...
```
1. One label file for all images. The label file contains all of the metadata
and labels associated with every image. In this case, there needs to be
additional information provided in the label file to match labels to
images. Specifically, the image filepath corresponding to a label must be
stored as a stream:
```text
/
data/
..
...
labels.json
```
1. Multiple label files, each corresponding to one or more images. This case is
similar to when there is a single label file, except that the label
information may be spread out over multiple files. Since the filenames
cannot be used to match labels to images, the image filepaths must again be
stored as streams in the labels files:
```text
/
data/
..
...
labels/
.json
.json
...
```
As for the actual structure of the labels files themselves, labels are stored
in one or more JSON files and can follow a variety of formats. In general
following this format:
#### NOTE
All object information stored in the `frames` key is applied to the
corresponding image.
```text
{
"openlabel": {
"metadata": {
"schema_version": "1.0.0",
"uri": "/path/to/.