fiftyone.utils.lerobot#

LeRobotDataset v3 import and asset resolution utilities.

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

Exceptions:

`UnsupportedLeRobotVersionError`	The referenced LeRobot source declares an unsupported version.
`UnsupportedLeRobotExportModeError`(...)	The requested LeRobot export media mode is unsupported.

Classes:

`LeRobotEpisodeReference`(args, *kwargs)	One episode of a LeRobotDataset v3 source.
`LeRobotSource`(id, root, info)	One LeRobot source: the id its dataset files it under, where it is and what it declares.
`LeRobotDatasetImporter`(dataset_dir[, ...])	Imports logical episodes from a LeRobotDataset v3 source.

exception fiftyone.utils.lerobot.UnsupportedLeRobotVersionError#

Bases: MediaReferenceError

The referenced LeRobot source declares an unsupported version.

Methods:

`add_note`(object, /)	Exception.add_note(note) -- add a note to the exception
`with_traceback`(object, /)	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note(object, /)#: Exception.add_note(note) – add a note to the exception

args#

with_traceback(object, /)#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception fiftyone.utils.lerobot.UnsupportedLeRobotExportModeError(export_media, suggestion)#

Bases: UnsupportedMediaReferenceOperation

The requested LeRobot export media mode is unsupported.

Methods:

`add_note`(object, /)	Exception.add_note(note) -- add a note to the exception
`with_traceback`(object, /)	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note(object, /)#: Exception.add_note(note) – add a note to the exception

args#

with_traceback(object, /)#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class fiftyone.utils.lerobot.LeRobotEpisodeReference(*args, **kwargs)#

Bases: MediaReference

One episode of a LeRobotDataset v3 source.

The coordinates are the episode’s own: an episode is a row range of the source’s data shard and a time window of each of its camera videos, all of which it shares with the other episodes recorded alongside it.

Parameters:

key – <media source id>/<episode index>
data – [chunk index, file index, first row, last row] of the episode’s rows in the source’s tabular data
videos – the episode’s window in each camera’s video, keyed by camera, as [chunk index, file index, from timestamp, to timestamp]
tasks – the tasks the episode demonstrates

Attributes:

`data`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`videos`	A dictionary field that wraps a standard Python dictionary.
`tasks`	A list field that wraps a standard `Field`, allowing multiple instances of the field to be stored as a list in the database.
`episode`	The zero-based episode index within the source.
`display_name`	A human-readable name for the referenced media.
`STRICT`
`field_names`	An ordered tuple of the public fields of this document.
`key`	A unicode string field.
`media_type`	The media type of every reference-backed sample.
`source_id`	The id of the media source on the owning dataset.

Methods:

`key_of`(source_id, episode)	The key naming one episode of a source.
`episode_of`(key)	The episode index a reference key names.
`of`(source_id, episode, **coordinates)	Builds a reference to one episode of a source.
`clean`()	Hook for doing document level data cleaning (usually validation or assignment) before validation is run.
`clear_field`(field_name)	Clears the field from the document.
`copy`()	Returns a deep copy of the document.
`fancy_repr`([class_name, select_fields, ...])	Generates a customizable string representation of the document.
`field_to_mongo`(field_name)
`field_to_python`(field_name, value)
`from_dict`(d[, extended])	Loads the document from a BSON/JSON dictionary.
`from_json`(s)	Loads the document from a JSON string.
`get_field`(field_name)	Gets the field of the document.
`get_text_score`()	Get text score from text query
`has_field`(field_name)	Determines whether the document has a field of the given name.
`iter_fields`()	Returns an iterator over the `(name, value)` pairs of the public fields of the document.
`merge`(doc[, merge_lists, merge_dicts, overwrite])	Merges the contents of the given document into this document.
`set_field`(field_name, value[, create])	Sets the value of a field of the document.
`source_of`(key)	The media source a reference key names.
`to_dict`([extended])	Serializes this document to a BSON/JSON dictionary.
`to_json`([pretty_print])	Serializes the document to a JSON string.
`to_mongo`(args, *kwargs)	Return as SON data ready for use with MongoDB.
`validate`([clean])	Ensure that all fields' values are valid and that required fields are present.

Classes:

my_metaclass

data#

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters:

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

videos#

A dictionary field that wraps a standard Python dictionary.

If this field is not set, its default value is {}.

Parameters:

field (None) – an optional Field instance describing the type of the values in the dict
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

tasks#

A list field that wraps a standard Field, allowing multiple instances of the field to be stored as a list in the database.

If this field is not set, its default value is [].

Parameters:

field (None) – an optional Field instance describing the type of the list elements
description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

static key_of(source_id, episode)#

The key naming one episode of a source.

Parameters:

source_id – the id of the media source on the owning dataset
episode – the zero-based episode index within the source

Returns:

the key

static episode_of(key)#

The episode index a reference key names.

Parameters:: key – a LeRobot episode reference key
Returns:: the zero-based episode index

classmethod of(source_id, episode, **coordinates)#

Builds a reference to one episode of a source.

Parameters:

source_id – the id of the media source on the owning dataset
episode – the zero-based episode index within the source
**coordinates – the episode’s stored coordinates

Returns:

a LeRobotEpisodeReference

property episode#: The zero-based episode index within the source.

property display_name#: A human-readable name for the referenced media.

STRICT = False#

clean()#

Hook for doing document level data cleaning (usually validation or assignment) before validation is run.

Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.

clear_field(field_name)#

Clears the field from the document.

Parameters:: field_name – the field name
Raises:: ValueError – if the field does not exist

copy()#

Returns a deep copy of the document.

Returns:: a SerializableDocument

fancy_repr(class_name=None, select_fields=None, exclude_fields=None, **kwargs)#

Generates a customizable string representation of the document.

Parameters:

class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation

Returns:

a string representation of the document

property field_names#: An ordered tuple of the public fields of this document.

field_to_mongo(field_name)#

field_to_python(field_name, value)#

classmethod from_dict(d, extended=False)#

Loads the document from a BSON/JSON dictionary.

Parameters:

d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs

Returns:

a SerializableDocument

classmethod from_json(s)#

Loads the document from a JSON string.

Returns:: a SerializableDocument

get_field(field_name)#

Gets the field of the document.

Parameters:: field_name – the field name
Returns:: the field value
Raises:: AttributeError – if the field does not exist

get_text_score()#: Get text score from text query

has_field(field_name)#

Determines whether the document has a field of the given name.

Parameters:: field_name – the field name
Returns:: True/False

iter_fields()#

Returns an iterator over the (name, value) pairs of the public fields of the document.

Returns:: an iterator that emits (name, value) tuples

key#

A unicode string field.

Parameters:

description (None) – an optional description
info (None) – an optional info dict
read_only (False) – whether the field is read-only
created_at (None) – the datetime the field was created

property media_type#: The media type of every reference-backed sample. A sample of one modality names its media by filepath; a reference is what multimodal media is named by.

merge(doc, merge_lists=True, merge_dicts=True, overwrite=True)#

Merges the contents of the given document into this document.

Parameters:

doc – a SerializableDocument of same type as this document
merge_lists (True) – whether to merge the elements of top-level list fields rather than treating the list as a single value
merge_dicts (True) – whether to recursively merge the contents of top-level dict fields rather than treating the dict as a single value
overwrite (True) – whether to overwrite (True) or skip (False) existing fields

my_metaclass#: alias of DocumentMetaclass

set_field(field_name, value, create=True)#

Sets the value of a field of the document.

Parameters:

field_name – the field name
value – the field value
create (True) – whether to create the field if it does not exist

Raises:

ValueError – if field_name is not an allowed field name or does not exist and create == False

property source_id#: The id of the media source on the owning dataset.

static source_of(key)#

The media source a reference key names.

Parameters:: key – a media reference key
Returns:: the source id

to_dict(extended=False)#

Serializes this document to a BSON/JSON dictionary.

Parameters:: extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
Returns:: a dict

to_json(pretty_print=False)#

Serializes the document to a JSON string.

Parameters:: pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
Returns:: a JSON string

to_mongo(*args, **kwargs)#: Return as SON data ready for use with MongoDB.

validate(clean=True)#

Ensure that all fields’ values are valid and that required fields are present.

Raises ValidationError if any of the fields’ values are found to be invalid.

class fiftyone.utils.lerobot.LeRobotSource(id: str, root: str, info: dict)#

Bases: object

One LeRobot source: the id its dataset files it under, where it is and what it declares.

Attributes:

`id`
`root`
`info`

id: str#

root: str#

info: dict#

class fiftyone.utils.lerobot.LeRobotDatasetImporter(dataset_dir, episodes=None, shuffle=False, seed=None, max_samples=None)#

Bases: GenericSampleDatasetImporter

Imports logical episodes from a LeRobotDataset v3 source.

Reads meta/info.json and the episode-metadata shards, nothing else: no data shard, video, or statistics file is opened. Samples are produced one shard at a time, each carrying only its episode’s key; the dataset records the source once.

An episode’s sample names its media by media_reference rather than filepath, and a reference only resolves through a source the dataset records. Build these datasets from a directory, not by adding samples:

import fiftyone as fo
import fiftyone.types as fot

# one source, one dataset
dataset = fo.Dataset.from_dir(
    dataset_dir="/data/lerobot/pick-place",
    dataset_type=fot.LeRobotDataset,
)

# more sources into the same dataset; each records itself as it
# arrives, so every episode stays resolvable
dataset.add_dir(
    dataset_dir="/data/lerobot/sort-nuts",
    dataset_type=fot.LeRobotDataset,
)

add_samples cannot be used to introduce a new source: a sample whose reference names a source the dataset does not record is refused, because nothing would say where its bytes are.

Parameters:

dataset_dir – the LeRobot dataset root, local or remote
episodes (None) – optional episode indexes to import
shuffle (False) – whether to randomly shuffle selected episodes
seed (None) – a random seed to use when shuffling
max_samples (None) – a maximum number of episodes to import

Attributes:

`has_dataset_info`	Whether this importer produces a dataset info dictionary.
`has_sample_field_schema`	Whether this importer produces a sample field schema.

Methods:

`get_sample_field_schema`()	Returns a dictionary describing the field schema of the samples loaded by this importer.
`get_dataset_info`()	Returns the dataset info for the dataset.
`get_media_sources`()	The media source the importing dataset records before any sample is added, so every sample's reference resolves from the start.
`setup`()	Performs any necessary setup before importing the first sample in the dataset.
`close`(*args)	Performs any necessary actions after the last sample has been imported.

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

property has_sample_field_schema#: Whether this importer produces a sample field schema.

get_sample_field_schema()#

Returns a dictionary describing the field schema of the samples loaded by this importer.

Returns:: a dict mapping field names to fiftyone.core.fields.Field instances or str(field) representations of them

get_dataset_info()#

Returns the dataset info for the dataset.

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

Returns:: a dict of dataset info

get_media_sources()#: The media source the importing dataset records before any sample is added, so every sample’s reference resolves from the start.

setup()#

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

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

close(*args)#

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

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

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