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

# fiftyone.core.frame

Video frames.

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

**Functions:**

| [`get_default_frame_fields`](#fiftyone.core.frame.get_default_frame_fields)([include_private, ...])   | Returns the default fields present on all frames.   |
|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------|

**Classes:**

| [`Frames`](#fiftyone.core.frame.Frames)(sample)                                  | An ordered dictionary of [`Frame`](#fiftyone.core.frame.Frame) instances keyed by frame number representing the frames of a video [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample).                 |
|----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [`FramesView`](#fiftyone.core.frame.FramesView)(sample_view)                     | An ordered dictionary of [`FrameView`](#fiftyone.core.frame.FrameView) instances keyed by frame number representing the frames of a video [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView). |
| [`Frame`](#fiftyone.core.frame.Frame)(\*\*kwargs)                                | A frame in a video [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample).                                                                                                                                |
| [`FrameView`](#fiftyone.core.frame.FrameView)(doc, view[, selected_fields, ...]) | A view into a [`Frame`](#fiftyone.core.frame.Frame) in a video dataset.                                                                                                                                                                 |

### fiftyone.core.frame.get_default_frame_fields(include_private=False, use_db_fields=False)

Returns the default fields present on all frames.

* **Parameters:**
  * **include_private** (*False*) – whether to include fields starting with `_`
  * **use_db_fields** (*False*) – whether to return database fields rather than
    user-facing fields, when applicable
* **Returns:**
  a tuple of field names

### *class* fiftyone.core.frame.Frames(sample)

Bases: `object`

An ordered dictionary of [`Frame`](#fiftyone.core.frame.Frame) instances keyed by frame number
representing the frames of a video [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample).

[`Frames`](#fiftyone.core.frame.Frames) instances behave like `defaultdict(Frame)` instances; an
empty [`Frame`](#fiftyone.core.frame.Frame) instance is returned when accessing a new frame
number.

[`Frames`](#fiftyone.core.frame.Frames) instances should never be created manually; they are
instantiated automatically when video [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample)
instances are created.

* **Parameters:**
  **sample** – the [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample) to which the frames
  are attached

**Attributes:**

| [`field_names`](#fiftyone.core.frame.Frames.field_names)   | An ordered tuple of the names of the fields on the frames.   |
|------------------------------------------------------------|--------------------------------------------------------------|

**Methods:**

| [`first`](#fiftyone.core.frame.Frames.first)()                                          | Returns the first [`Frame`](#fiftyone.core.frame.Frame) for the sample.                                         |
|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| [`last`](#fiftyone.core.frame.Frames.last)()                                            | Returns the last [`Frame`](#fiftyone.core.frame.Frame) for the sample.                                          |
| [`head`](#fiftyone.core.frame.Frames.head)([num_frames])                                | Returns a list of the first few frames for the sample.                                                          |
| [`tail`](#fiftyone.core.frame.Frames.tail)([num_frames])                                | Returns a list of the last few frames for the sample.                                                           |
| [`keys`](#fiftyone.core.frame.Frames.keys)()                                            | Returns an iterator over the frame numbers with labels in the sample.                                           |
| [`items`](#fiftyone.core.frame.Frames.items)()                                          | Returns an iterator over the frame numberes and [`Frame`](#fiftyone.core.frame.Frame) instances for the sample. |
| [`values`](#fiftyone.core.frame.Frames.values)()                                        | Returns an iterator over the [`Frame`](#fiftyone.core.frame.Frame) instances for the sample.                    |
| [`add_frame`](#fiftyone.core.frame.Frames.add_frame)(frame_number, frame[, ...])        | Adds the frame to this instance.                                                                                |
| [`delete_frame`](#fiftyone.core.frame.Frames.delete_frame)(frame_number)                | Deletes the given frame number from this instance.                                                              |
| [`update`](#fiftyone.core.frame.Frames.update)(frames[, overwrite, expand_schema, ...]) | Adds the frame labels to this instance.                                                                         |
| [`merge`](#fiftyone.core.frame.Frames.merge)(frames[, fields, omit_fields, ...])        | Merges the given frames into this instance.                                                                     |
| [`clear`](#fiftyone.core.frame.Frames.clear)()                                          | Removes all frames from this sample.                                                                            |
| [`save`](#fiftyone.core.frame.Frames.save)()                                            | Saves all frames for the sample to the database.                                                                |
| [`reload`](#fiftyone.core.frame.Frames.reload)([hard])                                  | Reloads all frames for the sample from the database.                                                            |

#### *property* field_names

An ordered tuple of the names of the fields on the frames.

#### first()

Returns the first [`Frame`](#fiftyone.core.frame.Frame) for the sample.

* **Returns:**
  a [`Frame`](#fiftyone.core.frame.Frame)

#### last()

Returns the last [`Frame`](#fiftyone.core.frame.Frame) for the sample.

* **Returns:**
  a [`Frame`](#fiftyone.core.frame.Frame)

#### head(num_frames=3)

Returns a list of the first few frames for the sample.

If fewer than `num_frames` frames exist, only the available frames
are returned.

* **Parameters:**
  **num_frames** (*3*) – the number of frames
* **Returns:**
  a list of [`Frame`](#fiftyone.core.frame.Frame) objects

#### tail(num_frames=3)

Returns a list of the last few frames for the sample.

If fewer than `num_frames` frames exist, only the available frames
are returned.

* **Parameters:**
  **num_frames** (*3*) – the number of frames
* **Returns:**
  a list of [`Frame`](#fiftyone.core.frame.Frame) objects

#### keys()

Returns an iterator over the frame numbers with labels in the
sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits frame numbers

#### items()

Returns an iterator over the frame numberes and [`Frame`](#fiftyone.core.frame.Frame)
instances for the sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits `(frame_number, Frame)` tuples

#### values()

Returns an iterator over the [`Frame`](#fiftyone.core.frame.Frame) instances for the
sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits [`Frame`](#fiftyone.core.frame.Frame) instances

#### add_frame(frame_number, frame, expand_schema=True, validate=True, dynamic=False)

Adds the frame to this instance.

If an existing frame with the same frame number exists, it is
overwritten.

If the provided frame is a [`Frame`](#fiftyone.core.frame.Frame) instance that does not belong
to a dataset, it is updated in-place to reflect its membership in this
dataset. Otherwise, the provided frame is not modified.

* **Parameters:**
  * **frame_number** – the frame number
  * **frame** – a [`Frame`](#fiftyone.core.frame.Frame) or [`FrameView`](#fiftyone.core.frame.FrameView)
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### delete_frame(frame_number)

Deletes the given frame number from this instance.

* **Parameters:**
  **frame_number** – the frame number

#### update(frames, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Adds the frame labels to this instance.

* **Parameters:**
  * **frames** – 

    can be any of the following
    - a [`Frames`](#fiftyone.core.frame.Frames) instance
    - a dictionary mapping frame numbers to [`Frame`](#fiftyone.core.frame.Frame)
      instances
    - a dictionary mapping frame numbers to dictionaries mapping
      label fields to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
      instances
  * **overwrite** (*True*) – whether to overwrite existing frames
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### merge(frames, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Merges the given frames into this instance.

The behavior of this method is highly customizable. By default, all
top-level fields from the provided frames are merged into existing
frames with the same frame numbers (and new frames created as
necessary), overwriting any existing values for those fields, with the
exception of list fields (e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both frames are updated rather
than duplicated.

To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.

This method can be configured in numerous ways, including:

- Whether new fields can be added to the frame schema
- Whether list fields should be treated as ordinary fields and merged
  as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input frame fields to different field names of this frame

* **Parameters:**
  * **frames** – 

    can be any of the following
    - a [`Frames`](#fiftyone.core.frame.Frames) instance
    - a dictionary mapping frame numbers to [`Frame`](#fiftyone.core.frame.Frame)
      instances
    - a dictionary mapping frame numbers to dictionaries mapping
      label fields to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
      instances
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the merge. This can also be a dict mapping field names
    of the input frame to field names of this frame
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the merge
  * **merge_lists** (*True*) – whether to merge the elements of list fields
    (e.g., `tags`) and label list fields (e.g.,
    [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
    merging the entire top-level field like other field types.
    For label lists fields, existing
    `fiftyone.core.label.Label` elements are either replaced
    (when `overwrite` is True) or kept (when `overwrite` is
    False) when their `id` matches a label from the provided
    frames
  * **merge_embedded_docs** (*False*) – whether to merge the attributes of
    embedded documents (True) rather than merging the entire
    top-level field (False)
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields and label elements
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### clear()

Removes all frames from this sample.

#### save()

Saves all frames for the sample to the database.

#### reload(hard=False)

Reloads all frames for the sample from the database.

* **Parameters:**
  **hard** (*False*) – whether to reload the frame schema in addition to the
  field values for the frames. This is necessary if new fields
  may have been added to the dataset’s frame schema

### *class* fiftyone.core.frame.FramesView(sample_view)

Bases: [`Frames`](#fiftyone.core.frame.Frames)

An ordered dictionary of [`FrameView`](#fiftyone.core.frame.FrameView) instances keyed by frame
number representing the frames of a video
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView).

[`FramesView`](#fiftyone.core.frame.FramesView) instances behave like `defaultdict(FrameView)`
instances; an empty [`FrameView`](#fiftyone.core.frame.FrameView) instance is returned when accessing
a new frame number.

[`FramesView`](#fiftyone.core.frame.FramesView) instances should never be created manually; they are
instantiated automatically when video
[`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) instances are created.

* **Parameters:**
  **sample_view** – the [`fiftyone.core.sample.SampleView`](fiftyone.core.sample.md#fiftyone.core.sample.SampleView) to which the
  frames are attached

**Attributes:**

| [`field_names`](#fiftyone.core.frame.FramesView.field_names)   | An ordered tuple of the names of the fields on the frames.   |
|----------------------------------------------------------------|--------------------------------------------------------------|

**Methods:**

| [`add_frame`](#fiftyone.core.frame.FramesView.add_frame)(frame_number, frame[, ...])        | Adds the frame to this instance.                                                                                |
|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|
| [`reload`](#fiftyone.core.frame.FramesView.reload)()                                        | Reloads the view into the frames of the attached sample.                                                        |
| [`save`](#fiftyone.core.frame.FramesView.save)()                                            | Saves all frames for the sample to the database.                                                                |
| [`clear`](#fiftyone.core.frame.FramesView.clear)()                                          | Removes all frames from this sample.                                                                            |
| [`delete_frame`](#fiftyone.core.frame.FramesView.delete_frame)(frame_number)                | Deletes the given frame number from this instance.                                                              |
| [`first`](#fiftyone.core.frame.FramesView.first)()                                          | Returns the first [`Frame`](#fiftyone.core.frame.Frame) for the sample.                                         |
| [`head`](#fiftyone.core.frame.FramesView.head)([num_frames])                                | Returns a list of the first few frames for the sample.                                                          |
| [`items`](#fiftyone.core.frame.FramesView.items)()                                          | Returns an iterator over the frame numberes and [`Frame`](#fiftyone.core.frame.Frame) instances for the sample. |
| [`keys`](#fiftyone.core.frame.FramesView.keys)()                                            | Returns an iterator over the frame numbers with labels in the sample.                                           |
| [`last`](#fiftyone.core.frame.FramesView.last)()                                            | Returns the last [`Frame`](#fiftyone.core.frame.Frame) for the sample.                                          |
| [`merge`](#fiftyone.core.frame.FramesView.merge)(frames[, fields, omit_fields, ...])        | Merges the given frames into this instance.                                                                     |
| [`tail`](#fiftyone.core.frame.FramesView.tail)([num_frames])                                | Returns a list of the last few frames for the sample.                                                           |
| [`update`](#fiftyone.core.frame.FramesView.update)(frames[, overwrite, expand_schema, ...]) | Adds the frame labels to this instance.                                                                         |
| [`values`](#fiftyone.core.frame.FramesView.values)()                                        | Returns an iterator over the [`Frame`](#fiftyone.core.frame.Frame) instances for the sample.                    |

#### *property* field_names

An ordered tuple of the names of the fields on the frames.

#### add_frame(frame_number, frame, expand_schema=True, validate=True, dynamic=False)

Adds the frame to this instance.

If an existing frame with the same frame number exists, it is
overwritten.

Unlike [`Frames.add_frame`](#fiftyone.core.frame.Frames.add_frame), the provided frame is never modified
in-place. Instead, a new [`FrameView`](#fiftyone.core.frame.FrameView) is constructed internally
with the contents of the provided frame.

* **Parameters:**
  * **frame_number** – the frame number
  * **frame** – a [`Frame`](#fiftyone.core.frame.Frame) or [`FrameView`](#fiftyone.core.frame.FrameView)
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### reload()

Reloads the view into the frames of the attached sample.

Calling this method has the following effects:

- Clears the in-memory cache of [`FrameView`](#fiftyone.core.frame.FrameView) instances that you
  have loaded via this object. Any frames that you subsequently
  access will be loaded directly from the database
- Any additions, modifications, or deletions to frame views that you
  have loaded from this instance but not committed to the database by
  calling [`save()`](#fiftyone.core.frame.FramesView.save) will be discarded

#### NOTE
[`FrameView`](#fiftyone.core.frame.FrameView) objects are not singletons, so calling this
method will not have any effect on [`FrameView`](#fiftyone.core.frame.FrameView) instances
that you have **previously** loaded via this object

* **Parameters:**
  **hard** (*False*) – whether to reload the frame schema in addition to the
  field values for the frames. This is necessary if new fields
  may have been added to the dataset’s frame schema

#### save()

Saves all frames for the sample to the database.

#### clear()

Removes all frames from this sample.

#### delete_frame(frame_number)

Deletes the given frame number from this instance.

* **Parameters:**
  **frame_number** – the frame number

#### first()

Returns the first [`Frame`](#fiftyone.core.frame.Frame) for the sample.

* **Returns:**
  a [`Frame`](#fiftyone.core.frame.Frame)

#### head(num_frames=3)

Returns a list of the first few frames for the sample.

If fewer than `num_frames` frames exist, only the available frames
are returned.

* **Parameters:**
  **num_frames** (*3*) – the number of frames
* **Returns:**
  a list of [`Frame`](#fiftyone.core.frame.Frame) objects

#### items()

Returns an iterator over the frame numberes and [`Frame`](#fiftyone.core.frame.Frame)
instances for the sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits `(frame_number, Frame)` tuples

#### keys()

Returns an iterator over the frame numbers with labels in the
sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits frame numbers

#### last()

Returns the last [`Frame`](#fiftyone.core.frame.Frame) for the sample.

* **Returns:**
  a [`Frame`](#fiftyone.core.frame.Frame)

#### merge(frames, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Merges the given frames into this instance.

The behavior of this method is highly customizable. By default, all
top-level fields from the provided frames are merged into existing
frames with the same frame numbers (and new frames created as
necessary), overwriting any existing values for those fields, with the
exception of list fields (e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both frames are updated rather
than duplicated.

To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.

This method can be configured in numerous ways, including:

- Whether new fields can be added to the frame schema
- Whether list fields should be treated as ordinary fields and merged
  as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input frame fields to different field names of this frame

* **Parameters:**
  * **frames** – 

    can be any of the following
    - a [`Frames`](#fiftyone.core.frame.Frames) instance
    - a dictionary mapping frame numbers to [`Frame`](#fiftyone.core.frame.Frame)
      instances
    - a dictionary mapping frame numbers to dictionaries mapping
      label fields to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
      instances
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the merge. This can also be a dict mapping field names
    of the input frame to field names of this frame
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the merge
  * **merge_lists** (*True*) – whether to merge the elements of list fields
    (e.g., `tags`) and label list fields (e.g.,
    [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
    merging the entire top-level field like other field types.
    For label lists fields, existing
    `fiftyone.core.label.Label` elements are either replaced
    (when `overwrite` is True) or kept (when `overwrite` is
    False) when their `id` matches a label from the provided
    frames
  * **merge_embedded_docs** (*False*) – whether to merge the attributes of
    embedded documents (True) rather than merging the entire
    top-level field (False)
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields and label elements
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### tail(num_frames=3)

Returns a list of the last few frames for the sample.

If fewer than `num_frames` frames exist, only the available frames
are returned.

* **Parameters:**
  **num_frames** (*3*) – the number of frames
* **Returns:**
  a list of [`Frame`](#fiftyone.core.frame.Frame) objects

#### update(frames, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Adds the frame labels to this instance.

* **Parameters:**
  * **frames** – 

    can be any of the following
    - a [`Frames`](#fiftyone.core.frame.Frames) instance
    - a dictionary mapping frame numbers to [`Frame`](#fiftyone.core.frame.Frame)
      instances
    - a dictionary mapping frame numbers to dictionaries mapping
      label fields to [`fiftyone.core.labels.Label`](fiftyone.core.labels.md#fiftyone.core.labels.Label)
      instances
  * **overwrite** (*True*) – whether to overwrite existing frames
  * **expand_schema** (*True*) – whether to dynamically add new frame fields
    encountered to the dataset schema. If False, an error is raised
    if the frame’s schema is not a subset of the dataset schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields

#### values()

Returns an iterator over the [`Frame`](#fiftyone.core.frame.Frame) instances for the
sample.

The frames are traversed in ascending order.

* **Returns:**
  a generator that emits [`Frame`](#fiftyone.core.frame.Frame) instances

### *class* fiftyone.core.frame.Frame(\*\*kwargs)

Bases: [`Document`](fiftyone.core.document.md#fiftyone.core.document.Document)

A frame in a video [`fiftyone.core.sample.Sample`](fiftyone.core.sample.md#fiftyone.core.sample.Sample).

Frames store all information associated with a particular frame of a video,
including one or more sets of labels (ground truth, user-provided, or
FiftyOne-generated) as well as additional features associated with subsets
of the data and/or label sets.

#### NOTE
[`Frame`](#fiftyone.core.frame.Frame) instances that are attached to samples **in datasets**
are singletons, i.e.,  `sample.frames[frame_number]` will always
return the same [`Frame`](#fiftyone.core.frame.Frame) instance.

* **Parameters:**
  **\*\*kwargs** – frame fields and values

**Attributes:**

| [`dataset_id`](#fiftyone.core.frame.Frame.dataset_id)   |                                                                                              |
|---------------------------------------------------------|----------------------------------------------------------------------------------------------|
| [`sample_id`](#fiftyone.core.frame.Frame.sample_id)     |                                                                                              |
| [`dataset`](#fiftyone.core.frame.Frame.dataset)         | The dataset to which this document belongs, or `None` if it has not been added to a dataset. |
| [`field_names`](#fiftyone.core.frame.Frame.field_names) | An ordered tuple of the public field names of this document.                                 |
| [`in_dataset`](#fiftyone.core.frame.Frame.in_dataset)   | Whether the document has been added to a dataset.                                            |

**Methods:**

| [`save`](#fiftyone.core.frame.Frame.save)()                                                    | Saves the frame to the database.                                                                                    |
|------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`clear_field`](#fiftyone.core.frame.Frame.clear_field)(field_name)                            | Clears the value of a field of the document.                                                                        |
| [`copy`](#fiftyone.core.frame.Frame.copy)([fields, omit_fields])                               | Returns a deep copy of the document that has not been added to the database.                                        |
| [`from_dict`](#fiftyone.core.frame.Frame.from_dict)(d)                                         | Loads the document from a JSON dictionary.                                                                          |
| [`from_doc`](#fiftyone.core.frame.Frame.from_doc)(doc[, dataset])                              | Creates a document backed by the given database document.                                                           |
| [`from_json`](#fiftyone.core.frame.Frame.from_json)(s)                                         | Loads the document from a JSON string.                                                                              |
| [`get_field`](#fiftyone.core.frame.Frame.get_field)(field_name)                                | Gets the value of a field of the document.                                                                          |
| [`has_field`](#fiftyone.core.frame.Frame.has_field)(field_name)                                | Determines whether the document has the given field.                                                                |
| [`iter_fields`](#fiftyone.core.frame.Frame.iter_fields)([include_id, include_timestamps])      | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                            |
| [`merge`](#fiftyone.core.frame.Frame.merge)(document[, fields, omit_fields, ...])              | Merges the fields of the document into this document.                                                               |
| [`reload`](#fiftyone.core.frame.Frame.reload)([hard])                                          | Reloads the document from the database.                                                                             |
| [`set_field`](#fiftyone.core.frame.Frame.set_field)(field_name, value[, create, ...])          | Sets the value of a field of the document.                                                                          |
| [`to_dict`](#fiftyone.core.frame.Frame.to_dict)([include_private])                             | Serializes the document to a JSON dictionary.                                                                       |
| [`to_json`](#fiftyone.core.frame.Frame.to_json)([pretty_print])                                | Serializes the document to a JSON string.                                                                           |
| [`to_mongo_dict`](#fiftyone.core.frame.Frame.to_mongo_dict)([include_id])                      | Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database. |
| [`update_fields`](#fiftyone.core.frame.Frame.update_fields)(fields_dict[, expand_schema, ...]) | Sets the dictionary of fields on the document.                                                                      |

#### *property* dataset_id

#### *property* sample_id

#### save()

Saves the frame to the database.

#### clear_field(field_name)

Clears the value of a field of the document.

* **Parameters:**
  **field_name** – the name of the field to clear
* **Raises:**
  **AttributeError** – if the field does not exist

#### copy(fields=None, omit_fields=None)

Returns a deep copy of the document that has not been added to the
database.

* **Parameters:**
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the copy. This can also be a dict mapping existing
    field names to new field names
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the copy
* **Returns:**
  a `Document`

#### *property* dataset

The dataset to which this document belongs, or `None` if it has
not been added to a dataset.

#### *property* field_names

An ordered tuple of the public field names of this document.

#### *classmethod* from_dict(d)

Loads the document from a JSON dictionary.

The returned document will not belong to a dataset.

* **Returns:**
  a `Document`

#### *classmethod* from_doc(doc, dataset=None)

Creates a document backed by the given database document.

* **Parameters:**
  * **doc** – a [`fiftyone.core.odm.document.Document`](fiftyone.core.odm.document.md#fiftyone.core.odm.document.Document)
  * **dataset** (*None*) – the [`fiftyone.core.dataset.Dataset`](fiftyone.core.dataset.md#fiftyone.core.dataset.Dataset) that
    the document belongs to, if any
* **Returns:**
  a `Document`

#### *classmethod* from_json(s)

Loads the document from a JSON string.

The returned document will not belong to a dataset.

* **Parameters:**
  **s** – the JSON string
* **Returns:**
  a `Document`

#### get_field(field_name)

Gets the value of a field of the document.

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

#### has_field(field_name)

Determines whether the document has the given field.

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

#### *property* in_dataset

Whether the document has been added to a dataset.

#### iter_fields(include_id=False, include_timestamps=False)

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

* **Parameters:**
  * **include_id** (*False*) – whether to include the `id` field
  * **include_timestamps** (*False*) – whether to include the `created_at`
    and `last_modified_at` fields
* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(document, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Merges the fields of the document into this document.

The behavior of this method is highly customizable. By default, all
top-level fields from the provided document are merged in, overwriting
any existing values for those fields, with the exception of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both documents are updated
rather than duplicated.

To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.

This method can be configured in numerous ways, including:

- Whether new fields can be added to the document schema
- Whether list fields should be treated as ordinary fields and merged
  as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input document fields to different field names of this
  document

* **Parameters:**
  * **document** – a `Document` or `DocumentView` of the same
    type
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the merge. This can also be a dict mapping field names
    of the input document to field names of this document
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the merge
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields (e.g., `tags`) and label list fields (e.g.,
    [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
    merging the entire top-level field like other field types.
    For label lists fields, existing
    `fiftyone.core.label.Label` elements are either replaced
    (when `overwrite` is True) or kept (when `overwrite` is
    False) when their `id` matches a label from the provided
    document
  * **merge_embedded_docs** (*False*) – whether to merge the attributes of
    embedded documents (True) rather than merging the entire
    top-level field (False)
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields and label elements
  * **expand_schema** (*True*) – whether to dynamically add new fields
    encountered to the document schema. If False, an error is
    raised if any fields are not in the document schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  **AttributeError** – if `expand_schema == False` and a field does not
      exist

#### reload(hard=False)

Reloads the document from the database.

* **Parameters:**
  **hard** (*False*) – whether to reload the document’s schema in addition
  to its field values. This is necessary if new fields may have
  been added to the document schema

#### set_field(field_name, value, create=True, validate=True, dynamic=False)

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
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  * **ValueError** – if `field_name` is not an allowed field name
  * **AttributeError** – if the field does not exist and `create == False`

#### to_dict(include_private=False)

Serializes the document to a JSON dictionary.

* **Parameters:**
  **include_private** (*False*) – whether to include private fields
* **Returns:**
  a JSON dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

The document ID and private fields are excluded in this representation.

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

#### to_mongo_dict(include_id=False)

Serializes the document to a BSON dictionary equivalent to the
representation that would be stored in the database.

* **Parameters:**
  **include_id** (*False*) – whether to include the document ID
* **Returns:**
  a BSON dict

#### update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)

Sets the dictionary of fields on the document.

* **Parameters:**
  * **fields_dict** – a dict mapping field names to values
  * **expand_schema** (*True*) – whether to dynamically add new fields
    encountered to the document schema. If False, an error is
    raised if any fields are not in the document schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  **AttributeError** – if `expand_schema == False` and a field does not
      exist

### *class* fiftyone.core.frame.FrameView(doc, view, selected_fields=None, excluded_fields=None, filtered_fields=None)

Bases: [`DocumentView`](fiftyone.core.document.md#fiftyone.core.document.DocumentView)

A view into a [`Frame`](#fiftyone.core.frame.Frame) in a video dataset.

Like [`Frame`](#fiftyone.core.frame.Frame) instances, the fields of a [`FrameView`](#fiftyone.core.frame.FrameView) instance
can be modified, new fields can be created, and any changes can be saved to
the database.

[`FrameView`](#fiftyone.core.frame.FrameView) instances differ from [`Frame`](#fiftyone.core.frame.Frame) instances in the
following ways:

- A frame view may contain only a subset of the fields of its source
  frame, either by selecting and/or excluding specific fields
- A frame view may contain array fields or embedded array fields that
  have been filtered, thus containing only a subset of the array elements
  from the source frame
- Excluded fields of a frame view may not be accessed or modified

#### NOTE
[`FrameView.save()`](#fiftyone.core.frame.FrameView.save) will not delete any excluded fields or filtered
array elements from the source frame.

Frame views should never be created manually; they are generated when
accessing the frames in a [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView).

* **Parameters:**
  * **doc** – a [`fiftyone.core.odm.frame.DatasetFrameDocument`](fiftyone.core.odm.frame.md#fiftyone.core.odm.frame.DatasetFrameDocument)
  * **view** – the [`fiftyone.core.view.DatasetView`](fiftyone.core.view.md#fiftyone.core.view.DatasetView) that the frame
    belongs to
  * **selected_fields** (*None*) – a set of field names that this frame view is
    restricted to, if any
  * **excluded_fields** (*None*) – a set of field names that are excluded from
    this frame view, if any
  * **filtered_fields** (*None*) – a set of field names of list fields that are
    filtered in this frame view, if any

**Attributes:**

| [`dataset_id`](#fiftyone.core.frame.FrameView.dataset_id)                     |                                                                                                                                      |
|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| [`sample_id`](#fiftyone.core.frame.FrameView.sample_id)                       |                                                                                                                                      |
| [`dataset`](#fiftyone.core.frame.FrameView.dataset)                           | The dataset to which this document belongs, or `None` if it has not been added to a dataset.                                         |
| [`excluded_field_names`](#fiftyone.core.frame.FrameView.excluded_field_names) | The set of field names that are excluded on this document view, or `None` if no fields are explicitly excluded.                      |
| [`field_names`](#fiftyone.core.frame.FrameView.field_names)                   | An ordered tuple of field names of this document view.                                                                               |
| [`filtered_field_names`](#fiftyone.core.frame.FrameView.filtered_field_names) | The set of field names or `embedded.field.names` that have been filtered on this document view, or `None` if no fields are filtered. |
| [`in_dataset`](#fiftyone.core.frame.FrameView.in_dataset)                     | Whether the document has been added to a dataset.                                                                                    |
| [`selected_field_names`](#fiftyone.core.frame.FrameView.selected_field_names) | The set of field names that are selected on this document view, or `None` if no fields are explicitly selected.                      |

**Methods:**

| [`clear_field`](#fiftyone.core.frame.FrameView.clear_field)(field_name)                            | Clears the value of a field of the document.                                                                        |
|----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| [`copy`](#fiftyone.core.frame.FrameView.copy)([fields, omit_fields])                               | Returns a deep copy of the document that has not been added to the database.                                        |
| [`get_field`](#fiftyone.core.frame.FrameView.get_field)(field_name)                                | Gets the value of a field of the document.                                                                          |
| [`has_field`](#fiftyone.core.frame.FrameView.has_field)(field_name)                                | Determines whether the document has the given field.                                                                |
| [`iter_fields`](#fiftyone.core.frame.FrameView.iter_fields)([include_id, include_timestamps])      | Returns an iterator over the `(name, value)` pairs of the public fields of the document.                            |
| [`merge`](#fiftyone.core.frame.FrameView.merge)(document[, fields, omit_fields, ...])              | Merges the fields of the document into this document.                                                               |
| [`save`](#fiftyone.core.frame.FrameView.save)()                                                    | Saves the document view to the database.                                                                            |
| [`set_field`](#fiftyone.core.frame.FrameView.set_field)(field_name, value[, create, ...])          | Sets the value of a field of the document.                                                                          |
| [`to_dict`](#fiftyone.core.frame.FrameView.to_dict)([include_private])                             | Serializes the document to a JSON dictionary.                                                                       |
| [`to_json`](#fiftyone.core.frame.FrameView.to_json)([pretty_print])                                | Serializes the document to a JSON string.                                                                           |
| [`to_mongo_dict`](#fiftyone.core.frame.FrameView.to_mongo_dict)([include_id])                      | Serializes the document to a BSON dictionary equivalent to the representation that would be stored in the database. |
| [`update_fields`](#fiftyone.core.frame.FrameView.update_fields)(fields_dict[, expand_schema, ...]) | Sets the dictionary of fields on the document.                                                                      |

#### *property* dataset_id

#### *property* sample_id

#### clear_field(field_name)

Clears the value of a field of the document.

* **Parameters:**
  **field_name** – the name of the field to clear
* **Raises:**
  **AttributeError** – if the field does not exist

#### copy(fields=None, omit_fields=None)

Returns a deep copy of the document that has not been added to the
database.

* **Parameters:**
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the copy. This can also be a dict mapping existing
    field names to new field names
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the copy
* **Returns:**
  a `Document`

#### *property* dataset

The dataset to which this document belongs, or `None` if it has
not been added to a dataset.

#### *property* excluded_field_names

The set of field names that are excluded on this document view, or
`None` if no fields are explicitly excluded.

#### *property* field_names

An ordered tuple of field names of this document view.

This may be a subset of all fields of the document if fields have been
selected or excluded.

#### *property* filtered_field_names

The set of field names or `embedded.field.names` that have been
filtered on this document view, or `None` if no fields are filtered.

#### get_field(field_name)

Gets the value of a field of the document.

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

#### has_field(field_name)

Determines whether the document has the given field.

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

#### *property* in_dataset

Whether the document has been added to a dataset.

#### iter_fields(include_id=False, include_timestamps=False)

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

* **Parameters:**
  * **include_id** (*False*) – whether to include the `id` field
  * **include_timestamps** (*False*) – whether to include the `created_at`
    and `last_modified_at` fields
* **Returns:**
  an iterator that emits `(name, value)` tuples

#### merge(document, fields=None, omit_fields=None, merge_lists=True, merge_embedded_docs=False, overwrite=True, expand_schema=True, validate=True, dynamic=False)

Merges the fields of the document into this document.

The behavior of this method is highly customizable. By default, all
top-level fields from the provided document are merged in, overwriting
any existing values for those fields, with the exception of list fields
(e.g., `tags`) and label list fields (e.g.,
[`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields), in which case the
elements of the lists themselves are merged. In the case of label list
fields, labels with the same `id` in both documents are updated
rather than duplicated.

To avoid confusion between missing fields and fields whose value is
`None`, `None`-valued fields are always treated as missing while
merging.

This method can be configured in numerous ways, including:

- Whether new fields can be added to the document schema
- Whether list fields should be treated as ordinary fields and merged
  as a whole rather than merging their elements
- Whether to merge only specific fields, or all but certain fields
- Mapping input document fields to different field names of this
  document

* **Parameters:**
  * **document** – a `Document` or `DocumentView` of the same
    type
  * **fields** (*None*) – an optional field or iterable of fields to which to
    restrict the merge. This can also be a dict mapping field names
    of the input document to field names of this document
  * **omit_fields** (*None*) – an optional field or iterable of fields to
    exclude from the merge
  * **merge_lists** (*True*) – whether to merge the elements of top-level list
    fields (e.g., `tags`) and label list fields (e.g.,
    [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections) fields) rather than
    merging the entire top-level field like other field types.
    For label lists fields, existing
    `fiftyone.core.label.Label` elements are either replaced
    (when `overwrite` is True) or kept (when `overwrite` is
    False) when their `id` matches a label from the provided
    document
  * **merge_embedded_docs** (*False*) – whether to merge the attributes of
    embedded documents (True) rather than merging the entire
    top-level field (False)
  * **overwrite** (*True*) – whether to overwrite (True) or skip (False)
    existing fields and label elements
  * **expand_schema** (*True*) – whether to dynamically add new fields
    encountered to the document schema. If False, an error is
    raised if any fields are not in the document schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  **AttributeError** – if `expand_schema == False` and a field does not
      exist

#### save()

Saves the document view to the database.

#### *property* selected_field_names

The set of field names that are selected on this document view, or
`None` if no fields are explicitly selected.

#### set_field(field_name, value, create=True, validate=True, dynamic=False)

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
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  * **ValueError** – if `field_name` is not an allowed field name
  * **AttributeError** – if the field does not exist and `create == False`

#### to_dict(include_private=False)

Serializes the document to a JSON dictionary.

* **Parameters:**
  **include_private** (*False*) – whether to include private fields
* **Returns:**
  a JSON dict

#### to_json(pretty_print=False)

Serializes the document to a JSON string.

The document ID and private fields are excluded in this representation.

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

#### to_mongo_dict(include_id=False)

Serializes the document to a BSON dictionary equivalent to the
representation that would be stored in the database.

* **Parameters:**
  **include_id** (*False*) – whether to include the document ID
* **Returns:**
  a BSON dict

#### update_fields(fields_dict, expand_schema=True, validate=True, dynamic=False)

Sets the dictionary of fields on the document.

* **Parameters:**
  * **fields_dict** – a dict mapping field names to values
  * **expand_schema** (*True*) – whether to dynamically add new fields
    encountered to the document schema. If False, an error is
    raised if any fields are not in the document schema
  * **validate** (*True*) – whether to validate values for existing fields
  * **dynamic** (*False*) – whether to declare dynamic embedded document
    fields
* **Raises:**
  **AttributeError** – if `expand_schema == False` and a field does not
      exist