fiftyone.core.metadata#

Metadata stored in dataset samples.

Copyright 2017-2025, Voxel51, Inc.

Classes:

Metadata(*args,ย **kwargs)

Base class for storing metadata about generic samples.

ImageMetadata(*args,ย **kwargs)

Class for storing metadata about image samples.

VideoMetadata(*args,ย **kwargs)

Class for storing metadata about video samples.

SceneMetadata(*args,ย **kwargs)

Class for storing metadata about 3D scene samples.

Functions:

compute_sample_metadata(sample[,ย overwrite,ย ...])

Populates the metadata field of the sample.

get_metadata_cls(media_type)

Get the metadata class for a media_type

compute_metadata(sample_collection[,ย ...])

Populates the metadata field of all samples in the collection.

get_image_info(f)

Retrieves the dimensions and number of channels of the given image from a file-like object that is streaming its contents.

class fiftyone.core.metadata.Metadata(*args, **kwargs)#

Bases: DynamicEmbeddedDocument

Base class for storing metadata about generic samples.

Parameters:
  • size_bytes (None) โ€“ the size of the media, in bytes

  • mime_type (None) โ€“ the MIME type of the media

Attributes:

size_bytes

A 32 bit integer field.

mime_type

A unicode string field.

STRICT

field_names

An ordered tuple of the public fields of this document.

Methods:

build_for(path_or_url[,ย mime_type])

Builds a Metadata object for the given file.

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.

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

alias of DocumentMetaclass

size_bytes#

A 32 bit integer 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

mime_type#

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

classmethod build_for(path_or_url, mime_type=None)#

Builds a Metadata object for the given file.

Parameters:
  • path_or_url โ€“ the path to the data on disk or a URL

  • mime_type (None) โ€“ the MIME type of the file. If not provided, it will be guessed

Returns:

a Metadata

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

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

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.core.metadata.ImageMetadata(*args, **kwargs)#

Bases: Metadata

Class for storing metadata about image samples.

Parameters:
  • size_bytes (None) โ€“ the size of the image on disk, in bytes

  • mime_type (None) โ€“ the MIME type of the image

  • width (None) โ€“ the width of the image, in pixels

  • height (None) โ€“ the height of the image, in pixels

  • num_channels (None) โ€“ the number of channels in the image

Attributes:

width

A 32 bit integer field.

height

A 32 bit integer field.

num_channels

A 32 bit integer field.

STRICT

field_names

An ordered tuple of the public fields of this document.

mime_type

A unicode string field.

size_bytes

A 32 bit integer field.

Methods:

build_for(img_or_path_or_url[,ย mime_type])

Builds an ImageMetadata object for the given image.

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.

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

alias of DocumentMetaclass

width#

A 32 bit integer 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

height#

A 32 bit integer 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

num_channels#

A 32 bit integer 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

classmethod build_for(img_or_path_or_url, mime_type=None)#

Builds an ImageMetadata object for the given image.

Parameters:
  • img_or_path_or_url โ€“ an image, an image path on disk, or a URL

  • mime_type (None) โ€“ the MIME type of the image. If not provided, it will be guessed

Returns:

an ImageMetadata

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

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

mime_type#

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

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

size_bytes#

A 32 bit integer 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

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.core.metadata.VideoMetadata(*args, **kwargs)#

Bases: Metadata

Class for storing metadata about video samples.

Parameters:
  • size_bytes (None) โ€“ the size of the video on disk, in bytes

  • mime_type (None) โ€“ the MIME type of the video

  • frame_width (None) โ€“ the width of the video frames, in pixels

  • frame_height (None) โ€“ the height of the video frames, in pixels

  • frame_rate (None) โ€“ the frame rate of the video

  • total_frame_count (None) โ€“ the total number of frames in the video

  • duration (None) โ€“ the duration of the video, in seconds

  • encoding_str (None) โ€“ the encoding string for the video

Attributes:

frame_width

A 32 bit integer field.

frame_height

A 32 bit integer field.

frame_rate

A floating point number field.

total_frame_count

A 32 bit integer field.

duration

A floating point number field.

encoding_str

A unicode string field.

STRICT

field_names

An ordered tuple of the public fields of this document.

mime_type

A unicode string field.

size_bytes

A 32 bit integer field.

Methods:

build_for(video_path_or_url[,ย mime_type])

Builds an VideoMetadata object for the given video.

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.

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

alias of DocumentMetaclass

frame_width#

A 32 bit integer 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

frame_height#

A 32 bit integer 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

frame_rate#

A floating point number 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

total_frame_count#

A 32 bit integer 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

duration#

A floating point number 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

encoding_str#

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

classmethod build_for(video_path_or_url, mime_type=None)#

Builds an VideoMetadata object for the given video.

Parameters:
  • video_path_or_url โ€“ the path to a video on disk or a URL

  • mime_type (None) โ€“ the MIME type of the image. If not provided, it will be guessed

Returns:

a VideoMetadata

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

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

mime_type#

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

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

size_bytes#

A 32 bit integer 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

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.core.metadata.SceneMetadata(*args, **kwargs)#

Bases: Metadata

Class for storing metadata about 3D scene samples.

Parameters:
  • size_bytes (None) โ€“ the size of scene definition and all children assets on disk, in bytes

  • mime_type (None) โ€“ the MIME type of the scene

  • asset_counts (None) โ€“ dict of child asset file type to count

Attributes:

asset_counts

A dictionary field that wraps a standard Python dictionary.

STRICT

field_names

An ordered tuple of the public fields of this document.

mime_type

A unicode string field.

size_bytes

A 32 bit integer field.

Methods:

build_for(scene_path[,ย mime_type,ย _cache])

Builds a SceneMetadata object for the given 3D scene.

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.

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

alias of DocumentMetaclass

asset_counts#

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

classmethod build_for(scene_path, mime_type=None, _cache=None)#

Builds a SceneMetadata object for the given 3D scene.

Parameters:
  • scene_path โ€“ a scene path

  • mime_type (None) โ€“ the MIME type of the scene. If not provided, defaults to application/octet-stream

Returns:

a SceneMetadata

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

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

mime_type#

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

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

size_bytes#

A 32 bit integer 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

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.

fiftyone.core.metadata.compute_sample_metadata(sample, overwrite=False, skip_failures=False)#

Populates the metadata field of the sample.

Parameters:
  • sample โ€“ a fiftyone.core.sample.Sample

  • overwrite (False) โ€“ whether to overwrite existing metadata

  • skip_failures (False) โ€“ whether to gracefully continue without raising an error if metadata cannot be computed

fiftyone.core.metadata.get_metadata_cls(media_type)#

Get the metadata class for a media_type

Parameters:

media_type (str) โ€“ a media type value

Returns:

a Metadata class

fiftyone.core.metadata.compute_metadata(sample_collection, overwrite=False, num_workers=None, skip_failures=True, warn_failures=False, progress=None)#

Populates the metadata field of all samples in the collection.

Any samples with existing metadata are skipped, unless overwrite == True.

Parameters:
  • sample_collection โ€“ a fiftyone.core.collections.SampleCollection

  • overwrite (False) โ€“ whether to overwrite existing metadata

  • num_workers (None) โ€“ a suggested number of threads to use

  • skip_failures (True) โ€“ whether to gracefully continue without raising an error if metadata cannot be computed for a sample

  • warn_failures (False) โ€“ whether to log a warning if metadata cannot be computed for a sample

  • progress (None) โ€“ whether to render a progress bar (True/False), use the default value fiftyone.config.show_progress_bars (None), or a progress callback function to invoke instead

fiftyone.core.metadata.get_image_info(f)#

Retrieves the dimensions and number of channels of the given image from a file-like object that is streaming its contents.

Parameters:

f โ€“ a file-like object that supports read(), seek(), tell()

Returns:

(width, height, num_channels)