fiftyone.zoo.models¶

fiftyone.zoo.models.torch

Module contents¶

The FiftyOne Model Zoo.

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

Classes:

`HasZooModel`	Mixin class for Config classes of `fiftyone.core.models.Model` instances whose models are stored in the FiftyOne Model Zoo.
`ZooModel`(base_name[, base_filename, …])	Class describing a model in the FiftyOne Model Zoo.
`ZooModelsManifest`([models])	Class that describes the collection of models in the FiftyOne Model Zoo.

Functions:

`delete_zoo_model`(name)	Deletes the zoo model from local disk, if necessary.
`download_zoo_model`(name[, overwrite])	Downloads the model of the given name from the FiftyOne Dataset Zoo.
`ensure_zoo_model_requirements`(name[, …])	Ensures that the package requirements for the zoo model with the given name are satisfied.
`find_zoo_model`(name)	Returns the path to the zoo model on disk.
`get_zoo_model`(name)	Returns the `ZooModel` instance for the model with the given name.
`install_zoo_model_requirements`(name[, …])	Installs any package requirements for the zoo model with the given name.
`is_zoo_model_downloaded`(name)	Determines whether the zoo model of the given name is downloaded.
`list_downloaded_zoo_models`()	Returns information about the zoo models that have been downloaded.
`list_zoo_models`([tags])	Returns the list of available models in the FiftyOne Model Zoo.
`load_zoo_model`(name[, …])	Loads the model of the given name from the FiftyOne Model Zoo.

fiftyone.zoo.models.list_zoo_models(tags=None)¶

Returns the list of available models in the FiftyOne Model Zoo.

Example usage:

import fiftyone as fo
import fiftyone.zoo as foz

#
# List all zoo models
#

names = foz.list_zoo_models()
print(names)

#
# List all zoo models with the specified tag(s)
#

names = foz.list_zoo_models(tags="torch")
print(names)

Parameters: tags (None) – only include models that have the specified tag or list of tags
Returns: a list of model names

fiftyone.zoo.models.list_downloaded_zoo_models()¶

Returns information about the zoo models that have been downloaded.

Returns: a dict mapping model names to (model path, ZooModel) tuples

fiftyone.zoo.models.is_zoo_model_downloaded(name)¶

Determines whether the zoo model of the given name is downloaded.

Parameters: name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used
Returns: True/False

fiftyone.zoo.models.download_zoo_model(name, overwrite=False)¶

Downloads the model of the given name from the FiftyOne Dataset Zoo.

If the model is already downloaded, it is not re-downloaded unless overwrite == True is specified.

Parameters

name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used. Call list_zoo_models() to see the available models
overwrite (False) – whether to overwrite any existing files

Returns

tuple of

model: the ZooModel for the model
model_path: the path to the downloaded model on disk

fiftyone.zoo.models.install_zoo_model_requirements(name, error_level=None)¶

Installs any package requirements for the zoo model with the given name.

Parameters

name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used. Call list_zoo_models() to see the available models
error_level (None) –
the error level to use, defined as:
- 0: raise error if a requirement install fails
- 1: log warning if a requirement install fails
- 2: ignore install fails requirements
By default, fo.config.requirement_error_level is used

fiftyone.zoo.models.ensure_zoo_model_requirements(name, error_level=None, log_success=True)¶

Ensures that the package requirements for the zoo model with the given name are satisfied.

Parameters

name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used. Call list_zoo_models() to see the available models
error_level (None) –
the error level to use when installing/ensuring requirements, defined as:
- 0: raise error if a requirement is not satisfied
- 1: log warning if a requirement is not satisifed
- 2: ignore unsatisifed requirements
By default, fo.config.requirement_error_level is used
log_success (True) – whether to generate a log message when a requirement is satisifed

fiftyone.zoo.models.load_zoo_model(name, download_if_necessary=True, ensure_requirements=True, install_requirements=False, error_level=None, cache=True, **kwargs)¶

Loads the model of the given name from the FiftyOne Model Zoo.

By default, the model will be downloaded if necessary, and any documented package requirements will be checked to ensure that they are installed.

Parameters

name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is downloaded. Call list_zoo_models() to see the available models
download_if_necessary (True) – whether to download the model if it is not found in the specified directory
ensure_requirements (True) – whether to ensure any requirements are installed before loading the model. By default, this is True
install_requirements – whether to install any requirements before loading the model. By default, this is False
error_level (None) –
the error level to use when installing/ensuring requirements, defined as:
- 0: raise error if a requirement is not satisfied
- 1: log warning if a requirement is not satisifed
- 2: ignore unsatisifed requirements
By default, fo.config.requirement_error_level is used
cache (True) – whether to store a weak reference to the model so that running this method again will return the same instance while the model is still in use. If False, no weak reference is stored/used
**kwargs – keyword arguments to inject into the model’s Config instance

Returns

a fiftyone.core.models.Model

fiftyone.zoo.models.find_zoo_model(name)¶

Returns the path to the zoo model on disk.

The model must be downloaded. Use download_zoo_model() to download models.

Parameters: name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used
Returns: the path to the model on disk
Raises: ValueError – if the model does not exist or has not been downloaded

fiftyone.zoo.models.get_zoo_model(name)¶

Returns the ZooModel instance for the model with the given name.

Parameters: name – the name of the zoo model
Returns: a ZooModel

fiftyone.zoo.models.delete_zoo_model(name)¶

Deletes the zoo model from local disk, if necessary.

Parameters: name – the name of the zoo model, which can have @<ver> appended to refer to a specific version of the model. If no version is specified, the latest version of the model is used

class fiftyone.zoo.models.HasZooModel¶

Bases: eta.core.learning.HasPublishedModel

Mixin class for Config classes of fiftyone.core.models.Model instances whose models are stored in the FiftyOne Model Zoo.

This class provides the following functionality:

The model to load can be specified either by:
1. providing a model_name, which specifies the zoo model to load. The model will be downloaded, if necessary
2. providing a model_path, which directly specifies the path to the model to load
fiftyone.core.models.ModelConfig definitions that use zoo models with default deployments will have default values for any unspecified parameters loaded and applied at runtime

Parameters

model_name – the name of the zoo model to load. If this value is provided, model_path does not need to be
model_path – the path to an already downloaded zoo model on disk to load. If this value is provided, model_name does not need to be

Methods:

`download_model_if_necessary`()	Downloads the published model specified by the config, if necessary.
`init`(d)	Initializes the published model config.

download_model_if_necessary()¶

Downloads the published model specified by the config, if necessary.

After this method is called, the model_path attribute will always contain the path to the model on disk.

init(d)¶

Initializes the published model config.

This method should be called by ModelConfig.__init__(), and it performs the following tasks:

Parses the model_name and model_path parameters
Populates any default parameters in the provided ModelConfig dict

Parameters: d – a ModelConfig dict
Returns: a ModelConfig dict with any default parameters populated

class fiftyone.zoo.models.ZooModel(base_name, base_filename=None, manager=None, version=None, description=None, source=None, size_bytes=None, default_deployment_config_dict=None, requirements=None, tags=None, date_added=None)¶

Bases: eta.core.models.Model

Class describing a model in the FiftyOne Model Zoo.

Parameters

base_name – the base name of the model (no version info)
base_filename (None) – the base filename of the model (no version info), if applicable
manager (None) – the fiftyone.core.models.ModelManager instance that describes the remote storage location of the model, if applicable
version (None) – the version of the model
description (None) – the description of the model
source (None) – the source of the model
size_bytes (None) – the size of the model on disk
default_deployment_config_dict (None) – a fiftyone.core.models.ModelConfig dict describing the recommended settings for deploying the model
requirements (None) – the eta.core.models.ModelRequirements for the model
tags (None) – a list of tags for the model
date_added (None) – the datetime that the model was added to the zoo

Methods:

`attributes`()	Returns a list of class attributes to be serialized.
`copy`()	Returns a deep copy of the object.
`custom_attributes`([dynamic, private])	Returns a customizable list of class attributes.
`download_model`(model_path[, force])	Downloads the model to the given local path.
`ensure_requirements`([error_level, log_success])	Ensures that any requirement(s) for this model are satisfied.
`flush_model`(model_path)	Flushes the copy of the model at the given local path, if necessary.
`flush_model_from_dir`(models_dir)	Flushes the copy of the model in the given models directory, if necessary.
`from_dict`(d)	Constructs a Model from a JSON dictionary.
`from_json`(path, args, *kwargs)	Constructs a Serializable object from a JSON file.
`from_str`(s, args, *kwargs)	Constructs a Serializable object from a JSON string.
`get_class_name`()	Returns the fully-qualified class name string of this object.
`get_path_in_dir`(models_dir)	Gets the model path for the model in the given models directory.
`has_tag`(tag)	Whether this model has the given tag.
`has_version_str`(name)	Determines whether the given model name has a version string.
`install_requirements`([error_level])	Installs any necessary requirement(s) for this model.
`is_in_dir`(models_dir)	Determines whether a copy of the model exists in the given models directory.
`is_model_downloaded`(model_path)	Determines whether the model is downloaded to the given location.
`parse_name`(name)	Parses the model name, returning the base name and the version, if any.
`serialize`([reflective])	Serializes the object into a dictionary.
`to_str`([pretty_print])	Returns a string representation of this object.
`write_json`(path[, pretty_print])	Serializes the object and writes it to disk.

Attributes:

`comp_version`	The version of this model expressed as a distutils.version.LooseVersion intended for comparison operations.
`filename`	The version-aware filename of the model.
`has_manager`	Whether this model has a manager instance.
`has_requirements`	Whether this model has requirements in order to be used.
`has_tags`	Whether this model has tags.
`has_version`	Determines whether the model has a version.
`name`	The version-aware name of the model.
`supports_cpu`	Whether the model supports CPU (True), or not (False), or unknown (None).
`supports_gpu`	Whether the model supports GPU (True), or not (False), or unknown (None).

attributes()¶

Returns a list of class attributes to be serialized.

Returns: a list of class attributes

property comp_version¶

The version of this model expressed as a distutils.version.LooseVersion intended for comparison operations.

Models with no version are given a version of 0.0.0.

copy()¶

Returns a deep copy of the object.

Returns: a Serializable instance

custom_attributes(dynamic=False, private=False)¶

Returns a customizable list of class attributes.

By default, all attributes in vars(self) are returned, minus private attributes (those starting with “_”).

Parameters

dynamic – whether to include dynamic properties, e.g., those defined by getter/setter methods or the @property decorator. By default, this is False
private – whether to include private properties, i.e., those starting with “_”. By default, this is False

Returns

a list of class attributes

download_model(model_path, force=False)¶

Downloads the model to the given local path.

If the download is forced, any existing model is overwritten. If the download is not forced, the model will only be downloaded if it does not already exist locally.

If the model has no manager, nothing is downloaded.

Parameters

model_path – the path to which to download the model
force – whether to force download the model. If True, the model is always downloaded. If False, the model is only downloaded if necessary. The default is False

Raises

ModelError – if model downloading is not currently allowed

ensure_requirements(error_level=0, log_success=False)¶

Ensures that any requirement(s) for this model are satisfied.

Parameters

error_level –
the error level to use, defined as:

0: raise error if a requirement is not satisfied 1: log warning if a requirement is not satisifed 2: ignore unsatisifed requirements
log_success – whether to generate a log message when a requirement is satisifed

property filename¶: The version-aware filename of the model.

flush_model(model_path)¶

Flushes the copy of the model at the given local path, if necessary.

Parameters: model_path – the path on disk for the model

flush_model_from_dir(models_dir)¶

Flushes the copy of the model in the given models directory, if necessary.

Parameters: models_dir – the models directory

classmethod from_dict(d)¶

Constructs a Model from a JSON dictionary.

Parameters: d – a JSON dictionary
Returns: a Model instance

classmethod from_json(path, *args, **kwargs)¶

Constructs a Serializable object from a JSON file.

Subclasses may override this method, but, by default, this method simply reads the JSON and calls from_dict(), which subclasses must implement.

Parameters

path – the path to the JSON file on disk
*args – optional positional arguments for self.from_dict()
**kwargs – optional keyword arguments for self.from_dict()

Returns

an instance of the Serializable class

classmethod from_str(s, *args, **kwargs)¶

Constructs a Serializable object from a JSON string.

Subclasses may override this method, but, by default, this method simply parses the string and calls from_dict(), which subclasses must implement.

Parameters

s – a JSON string representation of a Serializable object
*args – optional positional arguments for self.from_dict()
**kwargs – optional keyword arguments for self.from_dict()

Returns

an instance of the Serializable class

classmethod get_class_name()¶: Returns the fully-qualified class name string of this object.

get_path_in_dir(models_dir)¶

Gets the model path for the model in the given models directory.

Parameters: models_dir – the models directory
Returns: the model path, or None if the model has no manager

property has_manager¶: Whether this model has a manager instance.

property has_requirements¶: Whether this model has requirements in order to be used.

has_tag(tag)¶

Whether this model has the given tag.

Parameters: tag – a tag
Returns: True/False

property has_tags¶: Whether this model has tags.

property has_version¶: Determines whether the model has a version.

static has_version_str(name)¶

Determines whether the given model name has a version string.

Parameters: name – the model name
Returns: True/False

install_requirements(error_level=0)¶

Installs any necessary requirement(s) for this model.

Parameters

error_level –

the error level to use, defined as:

0: raise error if an install fails 1: log warning if an install fails 2: ignore install fails

is_in_dir(models_dir)¶

Determines whether a copy of the model exists in the given models directory.

Parameters: models_dir – the models directory
Returns: True/False, or None if the model has no manager

is_model_downloaded(model_path)¶

Determines whether the model is downloaded to the given location.

If model_path is an archive, this method will also return True if a directory with the same basename as model_path exists.

Parameters: model_path – the path on disk for the model
Returns: True/False, or None if the model has no manager

property name¶: The version-aware name of the model.

static parse_name(name)¶

Parses the model name, returning the base name and the version, if any.

Parameters: name – the name of the model, which can have “@<ver>” appended to refer to a specific version of the model
Returns: the base name of the model version: the version of the model, or None if no version was found
Return type: base_name
Raises: ModelError – if the model name was invalid

serialize(reflective=False)¶

Serializes the object into a dictionary.

Serialization is applied recursively to all attributes in the object, including element-wise serialization of lists and dictionary values.

Parameters: reflective – whether to include reflective attributes when serializing the object. By default, this is False
Returns: a JSON dictionary representation of the object

property supports_cpu¶: Whether the model supports CPU (True), or not (False), or unknown (None).

property supports_gpu¶: Whether the model supports GPU (True), or not (False), or unknown (None).

to_str(pretty_print=True, **kwargs)¶

Returns a string representation of this object.

Parameters

pretty_print – whether to render the JSON in human readable format with newlines and indentations. By default, this is True
**kwargs – optional keyword arguments for self.serialize()

Returns

a string representation of the object

write_json(path, pretty_print=False, **kwargs)¶

Serializes the object and writes it to disk.

Parameters

path – the output path
pretty_print – whether to render the JSON in human readable format with newlines and indentations. By default, this is False
**kwargs – optional keyword arguments for self.serialize()

class fiftyone.zoo.models.ZooModelsManifest(models=None)¶

Bases: eta.core.models.ModelsManifest

Class that describes the collection of models in the FiftyOne Model Zoo.

Parameters: models – a list of ZooModel instances

Methods:

`add_model`(model)	Adds the given model to the manifest.
`attributes`()	Returns a list of class attributes to be serialized.
`copy`()	Returns a deep copy of the object.
`custom_attributes`([dynamic, private])	Returns a customizable list of class attributes.
`dir_has_manifest`(models_dir)	Determines whether the given directory has a models manifest.
`from_dict`(d)	Constructs a ModelsManifest from a JSON dictionary.
`from_dir`(models_dir)	Loads the ModelsManifest from the given models directory.
`from_json`(path, args, *kwargs)	Constructs a Serializable object from a JSON file.
`from_str`(s, args, *kwargs)	Constructs a Serializable object from a JSON string.
`get_class_name`()	Returns the fully-qualified class name string of this object.
`get_latest_model_with_base_name`(base_name)	Gets the Model instance for the latest version of the model with the given base name.
`get_model_with_name`(name)	Gets the model with the given name.
`has_model_with_filename`(filename)	Determines whether this manifest contains a model with the given filename.
`has_model_with_name`(name)	Determines whether this manifest contains the model with the given name.
`make_manifest_path`(models_dir)	Makes the manifest path for the given models directory.
`merge`(models_manifest)	Merges the models manifest into this one.
`remove_model`(name)	Removes the model with the given name from the ModelsManifest.
`serialize`([reflective])	Serializes the object into a dictionary.
`to_str`([pretty_print])	Returns a string representation of this object.
`write_json`(path[, pretty_print])	Serializes the object and writes it to disk.
`write_to_dir`(models_dir)	Writes the ModelsManifest to the given models directory.

add_model(model)¶

Adds the given model to the manifest.

Parameters: model – a Model instance
Raises: ModelError – if the model conflicts with an existing model in the manifest

attributes()¶

Returns a list of class attributes to be serialized.

This method is called internally by serialize() to determine the class attributes to serialize.

Subclasses can override this method, but, by default, all attributes in vars(self) are returned, minus private attributes, i.e., those starting with “_”. The order of the attributes in this list is preserved when serializing objects, so a common pattern is for subclasses to override this method if they want their JSON files to be organized in a particular way.

Returns: a list of class attributes to be serialized

copy()¶

Returns a deep copy of the object.

Returns: a Serializable instance

custom_attributes(dynamic=False, private=False)¶

Returns a customizable list of class attributes.

By default, all attributes in vars(self) are returned, minus private attributes (those starting with “_”).

Parameters

dynamic – whether to include dynamic properties, e.g., those defined by getter/setter methods or the @property decorator. By default, this is False
private – whether to include private properties, i.e., those starting with “_”. By default, this is False

Returns

a list of class attributes

static dir_has_manifest(models_dir)¶

Determines whether the given directory has a models manifest.

Parameters: models_dir – the models directory
Returns: True/False

classmethod from_dict(d)¶

Constructs a ModelsManifest from a JSON dictionary.

Parameters: d – a JSON dictionary
Returns: a ModelsManifest

classmethod from_dir(models_dir)¶

Loads the ModelsManifest from the given models directory.

Parameters: models_dir – the models directory
Returns: a ModelsManifest

classmethod from_json(path, *args, **kwargs)¶

Constructs a Serializable object from a JSON file.

Subclasses may override this method, but, by default, this method simply reads the JSON and calls from_dict(), which subclasses must implement.

Parameters

path – the path to the JSON file on disk
*args – optional positional arguments for self.from_dict()
**kwargs – optional keyword arguments for self.from_dict()

Returns

an instance of the Serializable class

classmethod from_str(s, *args, **kwargs)¶

Constructs a Serializable object from a JSON string.

Subclasses may override this method, but, by default, this method simply parses the string and calls from_dict(), which subclasses must implement.

Parameters

s – a JSON string representation of a Serializable object
*args – optional positional arguments for self.from_dict()
**kwargs – optional keyword arguments for self.from_dict()

Returns

an instance of the Serializable class

classmethod get_class_name()¶: Returns the fully-qualified class name string of this object.

get_latest_model_with_base_name(base_name)¶

Gets the Model instance for the latest version of the model with the given base name.

Parameters: base_name – the base name of the model
Returns: the Model instance
Raises: ModelError – if the model was not found

get_model_with_name(name)¶

Gets the model with the given name.

Parameters: name – the name of the model
Returns: the Model instance
Raises: ModelError – if the model was not found

has_model_with_filename(filename)¶

Determines whether this manifest contains a model with the given filename.

Parameters: filename – the filename
Returns: True/False

has_model_with_name(name)¶

Determines whether this manifest contains the model with the given name.

Parameters: name – the model name
Returns: True/False

static make_manifest_path(models_dir)¶

Makes the manifest path for the given models directory.

Parameters: models_dir – the models directory
Returns: the manifest path

merge(models_manifest)¶

Merges the models manifest into this one.

Parameters: models_manifest – a ModelsManifest

remove_model(name)¶

Removes the model with the given name from the ModelsManifest.

Parameters: name – the name of the model
Raises: ModelError – if the model was not found

serialize(reflective=False)¶

Serializes the object into a dictionary.

Serialization is applied recursively to all attributes in the object, including element-wise serialization of lists and dictionary values.

Parameters: reflective – whether to include reflective attributes when serializing the object. By default, this is False
Returns: a JSON dictionary representation of the object

to_str(pretty_print=True, **kwargs)¶

Returns a string representation of this object.

Parameters

pretty_print – whether to render the JSON in human readable format with newlines and indentations. By default, this is True
**kwargs – optional keyword arguments for self.serialize()

Returns

a string representation of the object

write_json(path, pretty_print=False, **kwargs)¶

Serializes the object and writes it to disk.

Parameters

path – the output path
pretty_print – whether to render the JSON in human readable format with newlines and indentations. By default, this is False
**kwargs – optional keyword arguments for self.serialize()

write_to_dir(models_dir)¶

Writes the ModelsManifest to the given models directory.

Parameters: models_dir – the models directory