<table class="fo-notebook-links" align="left">
    <td>
        <a target="_blank" href="https://colab.research.google.com/github/voxel51/fiftyone/blob/main/docs/source/recipes/fiftyone_torch_dataloader.ipynb">
            <img src="https://cdn.voxel51.com/colab-logo-256px.png"> &nbsp; Run in Google Colab
        </a>
    </td>
    <td>
        <a target="_blank" href="https://github.com/voxel51/fiftyone/blob/main/docs/source/recipes/fiftyone_torch_dataloader.ipynb">
            <img src="https://cdn.voxel51.com/github-logo-256px.png"> &nbsp; View source on GitHub
        </a>
    </td>
    <td>
        <a target="_blank" href="https://raw.githubusercontent.com/voxel51/fiftyone/main/docs/source/recipes/fiftyone_torch_dataloader.ipynb" download>
            <img src="https://cdn.voxel51.com/cloud-icon-256px.png"> &nbsp; Download notebook
        </a>
    </td>
</table>

# Data Loading with FiftyOneTorchDataset

This recipe demonstrates how to load samples from a FiftyOne dataset into **PyTorch** using [FiftyOneTorchDataset](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.FiftyOneTorchDataset) and custom [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) definitions. This is useful when you want to train or evaluate models in Torch while flexibly choosing which fields (such as filepaths, labels, or detections) to include.
Specifically, it covers:

- Loading an example dataset from the [Dataset Zoo](https://docs.voxel51.com/user_guide/dataset_zoo/index.html)
- Defining custom [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) classes to map dataset fields into Torch-ready formats
- Creating a [FiftyOneTorchDataset](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.FiftyOneTorchDataset) and using it with a PyTorch `DataLoader`
- Retrieving custom batches of samples for training and visualization

**API references:** [FiftyOneTorchDataset](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.FiftyOneTorchDataset) · [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem)

## Setup

If you haven’t already, install FiftyOne:

In this tutorial, we’ll use [PyTorch](https://pytorch.org/) for working with tensors and inspecting sample data. To follow along, you’ll need to install `torch` and `torchvision`, if necessary:

## Import Libraries

## Load Dataset

## GetItem

A [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) defines how each sample is transformed into model input. It declares which fields it needs via `required_keys`, and implements the transformation in `__call__`.

## FiftyOneTorchDataset

Pass any [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) to `.to_torch()` on a dataset or view to get a [FiftyOneTorchDataset](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.FiftyOneTorchDataset) — a standard `torch.utils.data.Dataset` compatible with any `DataLoader`.

## Field Mapping

The `field_mapping` argument on [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) connects the keys declared in `required_keys` to actual field names in your dataset. This lets you reuse the same [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem) across datasets that use different field names.

With this, you can load batches of samples directly from any FiftyOne dataset or view using PyTorch, while customizing exactly which fields are retrieved via [GetItem](https://docs.voxel51.com/api/fiftyone.utils.torch.html#fiftyone.utils.torch.GetItem).
