Gazebo Fuel_tools

API Reference

4.9.1

High level interface to ignition fuel. More...

#include <FuelClient.hh>

Public Types

using ModelResult = std::tuple< ModelIdentifier, Result >
 

Public Member Functions

 FuelClient ()
 Default constructor. More...
 
 FuelClient (const ClientConfig &_config, const Rest &_rest=Rest(), LocalCache *_cache=nullptr)
 Constructor accepts server and auth configuration. More...
 
 ~FuelClient ()
 Destructor. More...
 
bool CachedModel (const common::URI &_modelUrl)
 Check if a model exists in the cache. More...
 
Result CachedModel (const common::URI &_modelUrl, std::string &_path)
 Check if a model is already present in the local cache. More...
 
Result CachedModelFile (const common::URI &_fileUrl, std::string &_path)
 Check if a file belonging to a model is already present in the local cache. More...
 
bool CachedWorld (const common::URI &_worldUrl)
 Check if a world exists in the cache. More...
 
Result CachedWorld (const common::URI &_worldUrl, std::string &_path)
 Check if a world is already present in the local cache. More...
 
Result CachedWorldFile (const common::URI &_fileUrl, std::string &_path)
 Check if a file belonging to a world is already present in the local cache. More...
 
ClientConfigConfig ()
 Get a mutable reference to the client configuration. More...
 
Result DeleteModel (const ModelIdentifier &_id)
 Remove a model from ignition fuel. More...
 
Result DeleteUrl (const gz::common::URI &_uri, const std::vector< std::string > &_headers)
 Remove a resource, such as a model or world, from Ignition Fuel. More...
 
Result DownloadModel (const common::URI &_modelUrl, std::string &_path)
 Download a model from ignition fuel. This will override an existing local copy of the model. More...
 
Result DownloadModel (const ModelIdentifier &_id)
 Download a model from ignition fuel. This will override an existing local copy of the model. More...
 
Result DownloadModel (const ModelIdentifier &_id, const std::vector< std::string > &_headers)
 Download a model from ignition fuel. This will override an existing local copy of the model. More...
 
Result DownloadModel (const ModelIdentifier &_id, const std::vector< std::string > &_headers, std::vector< ModelIdentifier > &_dependencies)
 Download a model from ignition fuel. This will override an existing local copy of the model. More...
 
std::vector< ModelResultDownloadModels (const std::vector< ModelIdentifier > &_ids, size_t _jobs=2)
 Download a list of models from ignition fuel. More...
 
Result DownloadWorld (const common::URI &_worldUrl, std::string &_path)
 Download a world from ignition fuel. This will override an existing local copy of the world. More...
 
Result DownloadWorld (WorldIdentifier &_id)
 Download a world from Ignition Fuel. This will override an existing local copy of the world. More...
 
Result DownloadWorlds (const std::vector< WorldIdentifier > &_ids, size_t _jobs=2)
 Download a list of mworlds from ignition fuel. More...
 
Result ModelDependencies (const ModelIdentifier &_id, std::vector< ModelIdentifier > &_dependencies)
 Retrieve the list of dependencies for a model. More...
 
Result ModelDependencies (const std::vector< ModelIdentifier > &_id, std::vector< ModelIdentifier > &_dependencies)
 Retrieve the list of dependencies for a list of models. More...
 
Result ModelDetails (const ModelIdentifier &_id, ModelIdentifier &_model) const
 Fetch the details of a model. More...
 
Result ModelDetails (const ModelIdentifier &_id, ModelIdentifier &_model, const std::vector< std::string > &_headers) const
 Fetch the details of a model. More...
 
ModelIter Models (const CollectionIdentifier &_id) const
 Returns an iterator for the models found in a collection. More...
 
ModelIter Models (const ModelIdentifier &_id)
 Returns models matching a given identifying criteria. More...
 
ModelIter Models (const ModelIdentifier &_id) const
 Returns models matching a given identifying criteria. More...
 
ModelIter Models (const ModelIdentifier &_id, bool _checkCache)
 Returns models matching a given identifying criteria. More...
 
ModelIter Models (const ModelIdentifier &_id, bool _checkCache) const
 Returns models matching a given identifying criteria. More...
 
ModelIter Models (const ServerConfig &_server)
 Returns an iterator that can return names of models. More...
 
ModelIter Models (const ServerConfig &_server) const
 Returns an iterator that can return names of models. More...
 
bool ParseCollectionUrl (const common::URI &_url, CollectionIdentifier &_id)
 Parse Collection identifer from URL. More...
 
bool ParseModelFileUrl (const common::URI &_modelFileUrl, ModelIdentifier &_id, std::string &_filePath)
 Parse model file identifier from model file URL. More...
 
bool ParseModelUrl (const common::URI &_modelUrl, ModelIdentifier &_id)
 Parse model identifier from model URL or unique name. More...
 
bool ParseWorldFileUrl (const common::URI &_worldFileUrl, WorldIdentifier &_id, std::string &_filePath)
 Parse world file identifier from world file URL. More...
 
bool ParseWorldUrl (const common::URI &_worldUrl, WorldIdentifier &_id)
 Parse world identifier from world URL or unique name. More...
 
Result PatchModel (const ModelIdentifier &_model, const std::vector< std::string > &_headers)
 Update a model using a PATCH request. More...
 
Result PatchModel (const ModelIdentifier &_model, const std::vector< std::string > &_headers, const std::string &_pathToModelDir)
 Update a model using a PATCH request. More...
 
void PopulateLicenses (const ServerConfig &_server)
 This function requests the available licenses from the Fuel server and stores this information locally. More...
 
Result UploadModel (const std::string &_pathToModelDir, const ModelIdentifier &_id, const std::vector< std::string > &_headers, bool _private=false)
 Upload a directory as a new model. More...
 
Result WorldDetails (const WorldIdentifier &_id, WorldIdentifier &_world) const
 Fetch the details of a world. More...
 
WorldIter Worlds (const CollectionIdentifier &_id) const
 Returns an iterator for the worlds found in a collection. More...
 
WorldIter Worlds (const ServerConfig &_server) const
 Returns an iterator that can return information of worlds. More...
 
WorldIter Worlds (const WorldIdentifier &_id) const
 Returns worlds matching a given identifying criteria. More...
 

Detailed Description

High level interface to ignition fuel.

Member Typedef Documentation

◆ ModelResult

Constructor & Destructor Documentation

◆ FuelClient() [1/2]

Default constructor.

◆ FuelClient() [2/2]

FuelClient ( const ClientConfig _config,
const Rest _rest = Rest(),
LocalCache _cache = nullptr 
)

Constructor accepts server and auth configuration.

Parameters
[in]_configconfiguration about servers to connect to
[in]_restA REST request.
[in]_cacheTest hook. Pointer to a local cache. The FuelClient will take ownership of the pointer and free it when destructed. If set to nullptr the client will instantiate it's own cache.
Remarks
the client saves a copy of the config passed into it

◆ ~FuelClient()

~FuelClient ( )

Destructor.

Member Function Documentation

◆ CachedModel() [1/2]

bool CachedModel ( const common::URI _modelUrl)

Check if a model exists in the cache.

Parameters
[in]_modelUrlThe unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer
Returns
True if the model exists in the cache, false otherwise.

◆ CachedModel() [2/2]

Result CachedModel ( const common::URI _modelUrl,
std::string _path 
)

Check if a model is already present in the local cache.

Parameters
[in]_modelUrlThe unique URL of the model on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer
[out]_pathLocal path where the model can be found.
Returns
FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedModelFile()

Result CachedModelFile ( const common::URI _fileUrl,
std::string _path 
)

Check if a file belonging to a model is already present in the local cache.

Parameters
[in]_fileUrlThe unique URL of the file on a Fuel server. E.g.: https://server.org/1.0/owner/models/model/files/meshes/mesh.dae
[out]_pathLocal path where the file can be found.
Returns
FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedWorld() [1/2]

bool CachedWorld ( const common::URI _worldUrl)

Check if a world exists in the cache.

Parameters
[in]_worldUrlThe unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty
Returns
True if the world exists in the cache, false otherwise.

◆ CachedWorld() [2/2]

Result CachedWorld ( const common::URI _worldUrl,
std::string _path 
)

Check if a world is already present in the local cache.

Parameters
[in]_worldUrlThe unique URL of the world on a Fuel server. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty
[out]_pathLocal path where the world can be found.
Returns
FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ CachedWorldFile()

Result CachedWorldFile ( const common::URI _fileUrl,
std::string _path 
)

Check if a file belonging to a world is already present in the local cache.

Parameters
[in]_fileUrlThe unique URL of the file on a Fuel server. E.g.: https://server.org/1.0/owner/worlds/world/files/name.world
[out]_pathLocal path where the file can be found.
Returns
FETCH_ERROR if not cached, FETCH_ALREADY_EXISTS if cached.

◆ Config()

ClientConfig& Config ( )

Get a mutable reference to the client configuration.

Returns
Mutable reference to the client configuration.

◆ DeleteModel()

Result DeleteModel ( const ModelIdentifier _id)

Remove a model from ignition fuel.

Parameters
[in]_idThe model identifier.
Returns
Result of the delete operation Deprecate this function in ign-fuel-tools5. DeleteUrl replaces this function.

◆ DeleteUrl()

Result DeleteUrl ( const gz::common::URI &  _uri,
const std::vector< std::string > &  _headers 
)

Remove a resource, such as a model or world, from Ignition Fuel.

Parameters
[in]_uriThe full URI of the resource, e.g: https://fuel.gazebosim.org/1.0/openrobotcs/model/my_model
[in]_headersHeaders to set on the HTTP request.
Returns
Result of the delete operation

◆ DownloadModel() [1/4]

Result DownloadModel ( const common::URI _modelUrl,
std::string _path 
)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters
[in]_modelUrlThe unique URL of the model to download. E.g.: https://fuel.gazebosim.org/1.0/caguero/models/Beer
[out]_pathPath where the model was downloaded.
Returns
Result of the download operation.

◆ DownloadModel() [2/4]

Result DownloadModel ( const ModelIdentifier _id)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters
[in]_idThe model identifier.
Returns
Result of the download operation

◆ DownloadModel() [3/4]

Result DownloadModel ( const ModelIdentifier _id,
const std::vector< std::string > &  _headers 
)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters
[in]_idThe model identifier.
[in]_headersHeaders to set on the HTTP request.
Returns
Result of the download operation

◆ DownloadModel() [4/4]

Result DownloadModel ( const ModelIdentifier _id,
const std::vector< std::string > &  _headers,
std::vector< ModelIdentifier > &  _dependencies 
)

Download a model from ignition fuel. This will override an existing local copy of the model.

Parameters
[in]_idThe model identifier.
[in]_headersHeaders to set on the HTTP request.
[out]_dependenciesList of models that this model depends on.
Returns
Result of the download operation

◆ DownloadModels()

std::vector<ModelResult> DownloadModels ( const std::vector< ModelIdentifier > &  _ids,
size_t  _jobs = 2 
)

Download a list of models from ignition fuel.

Parameters
[in]_idsThe list of model ids to download. This will also find all recursive dependencies of the models
[in]_jobsNumber of parallel jobs to use to download models
Returns
Result of the download operation.

◆ DownloadWorld() [1/2]

Result DownloadWorld ( const common::URI _worldUrl,
std::string _path 
)

Download a world from ignition fuel. This will override an existing local copy of the world.

Parameters
[in]_worldUrlThe unique URL of the world to download. E.g.: https://fuel.gazebosim.org/1.0/OpenRobotics/worlds/Empty
[out]_pathPath where the world was downloaded.
Returns
Result of the download operation.

◆ DownloadWorld() [2/2]

Result DownloadWorld ( WorldIdentifier _id)

Download a world from Ignition Fuel. This will override an existing local copy of the world.

Parameters
[out]_idThe world identifier, with local path updated.
Returns
Result of the download operation

◆ DownloadWorlds()

Result DownloadWorlds ( const std::vector< WorldIdentifier > &  _ids,
size_t  _jobs = 2 
)

Download a list of mworlds from ignition fuel.

Parameters
[in]_idsThe list of world ids to download.
[in]_jobsNumber of parallel jobs to use to download worlds.
Returns
Result of the download operation.

◆ ModelDependencies() [1/2]

Result ModelDependencies ( const ModelIdentifier _id,
std::vector< ModelIdentifier > &  _dependencies 
)

Retrieve the list of dependencies for a model.

Parameters
[in]_idThe model identifier.
[out]_dependenciesThe list of dependencies.
Returns
Result of the operation

◆ ModelDependencies() [2/2]

Result ModelDependencies ( const std::vector< ModelIdentifier > &  _id,
std::vector< ModelIdentifier > &  _dependencies 
)

Retrieve the list of dependencies for a list of models.

Parameters
[in]_idThe list of model identifiers.
[out]_dependenciesThe list of dependencies.
Returns
Result of the operation

◆ ModelDetails() [1/2]

Result ModelDetails ( const ModelIdentifier _id,
ModelIdentifier _model 
) const

Fetch the details of a model.

Parameters
[in]_ida partially filled out identifier used to fetch models
Remarks
Fulfills Get-One requirement
Parameters
[out]_modelThe requested model
Returns
Result of the fetch operation.

◆ ModelDetails() [2/2]

Result ModelDetails ( const ModelIdentifier _id,
ModelIdentifier _model,
const std::vector< std::string > &  _headers 
) const

Fetch the details of a model.

Parameters
[in]_ida partially filled out identifier used to fetch models
Remarks
Fulfills Get-One requirement
Parameters
[out]_modelThe requested model
Returns
Result of the fetch operation.

◆ Models() [1/7]

ModelIter Models ( const CollectionIdentifier _id) const

Returns an iterator for the models found in a collection.

Parameters
[in]_ida partially filled out identifier used to fetch a collection.
Returns
An iterator of models in the collection.

◆ Models() [2/7]

ModelIter Models ( const ModelIdentifier _id)

Returns models matching a given identifying criteria.

Parameters
[in]_ida partially filled out identifier used to fetch models
Remarks
Fulfills Get-One requirement
Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.
Returns
An iterator of models with names matching the criteria

◆ Models() [3/7]

ModelIter Models ( const ModelIdentifier _id) const

Returns models matching a given identifying criteria.

Parameters
[in]_ida partially filled out identifier used to fetch models
Remarks
Fulfills Get-One requirement
Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.
Returns
An iterator of models with names matching the criteria

◆ Models() [4/7]

ModelIter Models ( const ModelIdentifier _id,
bool  _checkCache 
)

Returns models matching a given identifying criteria.

Parameters
[in]_ida partially filled out identifier used to fetch models
[in]_checkCacheWhether to check the cache.
Remarks
Fulfills Get-One requirement
Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.
Returns
An iterator of models with names matching the criteria

◆ Models() [5/7]

ModelIter Models ( const ModelIdentifier _id,
bool  _checkCache 
) const

Returns models matching a given identifying criteria.

Parameters
[in]_ida partially filled out identifier used to fetch models
[in]_checkCacheWhether to check the cache.
Remarks
Fulfills Get-One requirement
Model names are unique to the owner, so this API allows the possibility of getting multiple models with the same name if the owner is not specified.
Returns
An iterator of models with names matching the criteria

◆ Models() [6/7]

ModelIter Models ( const ServerConfig _server)

Returns an iterator that can return names of models.

Remarks
Fulfills Get-All requirement
an iterator instead of a list of names is returned in case the model names api supports pagination in the future. The iterator may fetch more names if code continues to request it. The initial API appears to return all of the models, so right now this iterator stores a list of names internally.
Parameters
[in]_serverThe server to request the operation.
Returns
A model iterator

◆ Models() [7/7]

ModelIter Models ( const ServerConfig _server) const

Returns an iterator that can return names of models.

Remarks
Fulfills Get-All requirement
an iterator instead of a list of names is returned in case the model names api supports pagination in the future. The iterator may fetch more names if code continues to request it. The initial API appears to return all of the models, so right now this iterator stores a list of names internally.
Parameters
[in]_serverThe server to request the operation.
Returns
A model iterator

◆ ParseCollectionUrl()

bool ParseCollectionUrl ( const common::URI _url,
CollectionIdentifier _id 
)

Parse Collection identifer from URL.

Parameters
[in]_urlThe unique URL of a collection. It may also be a unique name, which is a URL without the server version.
[out]_idThe collection identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.
Returns
True if parsed successfully.

◆ ParseModelFileUrl()

bool ParseModelFileUrl ( const common::URI _modelFileUrl,
ModelIdentifier _id,
std::string _filePath 
)

Parse model file identifier from model file URL.

Parameters
[in]_modelFileUrlThe unique URL of a model file. It may also be a unique name, which is a URL without the server version.
[out]_idThe model identifier. It may contain incomplete information based on the passed URL and the current client config.
[out]_filePathPath to the file from the model's root directory, such as "meshes/mesh.dae" or "model.sdf".
Returns
True if parsed successfully.

◆ ParseModelUrl()

bool ParseModelUrl ( const common::URI _modelUrl,
ModelIdentifier _id 
)

Parse model identifier from model URL or unique name.

Parameters
[in]_modelUrlThe unique URL of a model. It may also be a unique name, which is a URL without the server version.
[out]_idThe model identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.
Returns
True if parsed successfully.

◆ ParseWorldFileUrl()

bool ParseWorldFileUrl ( const common::URI _worldFileUrl,
WorldIdentifier _id,
std::string _filePath 
)

Parse world file identifier from world file URL.

Parameters
[in]_worldFileUrlThe unique URL of a world file. It may also be a unique name, which is a URL without the server version.
[out]_idThe world identifier. It may contain incomplete information based on the passed URL and the current client config.
[out]_filePathPath to the file from the world's root directory, such as "name.world"
Returns
True if parsed successfully.

◆ ParseWorldUrl()

bool ParseWorldUrl ( const common::URI _worldUrl,
WorldIdentifier _id 
)

Parse world identifier from world URL or unique name.

Parameters
[in]_worldUrlThe unique URL of a world. It may also be a unique name, which is a URL without the server version.
[out]_idThe world identifier. It may contain incomplete information based on the passed URL and the current client config. The server version will be overridden if that server is in the config file.
Returns
True if parsed successfully.

◆ PatchModel() [1/2]

Result PatchModel ( const ModelIdentifier _model,
const std::vector< std::string > &  _headers 
)

Update a model using a PATCH request.

Model fields that are patched by this function:

  • private
Parameters
[in]_modelThe model to patch. The contents of this model will be sent in the PATCH request.
[in]_headersHeaders to set on the HTTP request.
Returns
Result of the patch operation.

◆ PatchModel() [2/2]

Result PatchModel ( const ModelIdentifier _model,
const std::vector< std::string > &  _headers,
const std::string _pathToModelDir 
)

Update a model using a PATCH request.

Model fields that are patched by this function:

  • private
  • Model files contained in _pathToModelDir.
  • Description, tags, license, and other attributes found in the metadata.pbtxt or model.config file.
Parameters
[in]_modelThe model to patch. The contents of this model will be sent in the PATCH request.
[in]_headersHeaders to set on the HTTP request.
[in]_pathToModelDira path to a directory containing a model.
Returns
Result of the patch operation.

◆ PopulateLicenses()

void PopulateLicenses ( const ServerConfig _server)

This function requests the available licenses from the Fuel server and stores this information locally.

The UploadModel function can use this information to set appropriate license information based on a model's metadata.pbtxt file. If license information is not available, then the UploadModel function will default to the "Creative Commons - Public Domain" license.

Parameters
[in]_serverInformation about the server that provides license information.

◆ UploadModel()

Result UploadModel ( const std::string _pathToModelDir,
const ModelIdentifier _id,
const std::vector< std::string > &  _headers,
bool  _private = false 
)

Upload a directory as a new model.

Parameters
[in]_pathToModelDira path to a directory containing a model
[in]_idAn identifier to assign to this new model
[in]_headersHeaders to set on the HTTP request.
[in]_privateTrue to make the model private.
Returns
Result of the upload operation

◆ WorldDetails()

Result WorldDetails ( const WorldIdentifier _id,
WorldIdentifier _world 
) const

Fetch the details of a world.

Parameters
[in]_ida partially filled out identifier used to fetch worlds
[out]_worldThe requested world
Returns
Result of the fetch operation.

◆ Worlds() [1/3]

WorldIter Worlds ( const CollectionIdentifier _id) const

Returns an iterator for the worlds found in a collection.

Parameters
[in]_ida partially filled out identifier used to fetch a collection.
Returns
An iterator of words in the collection.

◆ Worlds() [2/3]

WorldIter Worlds ( const ServerConfig _server) const

Returns an iterator that can return information of worlds.

Remarks
An iterator instead of a list of names, to be able to handle pagination. The iterator may fetch more names if code continues to request it.
Parameters
[in]_serverThe server to request the operation.
Returns
A world iterator

◆ Worlds() [3/3]

WorldIter Worlds ( const WorldIdentifier _id) const

Returns worlds matching a given identifying criteria.

Parameters
[in]_idA partially filled out identifier used to fetch worlds
Returns
An iterator of worlds with names matching the criteria

The documentation for this class was generated from the following file: