skbot.ignition.get_fuel_model

skbot.ignition.get_fuel_model(url, *, file_path='model.sdf', user_cache=None, use_internal_cache=True, use_file_cache=True, update_file_cache=True, update_internal_cache=True, update_user_cache=None, file_cache_dir='~/.ignition/fuel')[source]

Get a model file from the Fuel server.

Parameters
urlstr

The URL of the model. This is the same as the URL used for include elements in SDF files.

file_pathstr

The path - relative to model root - to the file that should be downloaded. Defaults to the model’s primary SDF at “model.sdf”.

user_cacheCallable[[str, str], Union[str, None]]

User supplied caching logic. It is a callable that expects two strings (url and file_path) and returns either a string (the file) or None. If user_cache returns a string it is considered a cache hit; if user_cache returns None this is interpreted as a cache miss. If user_cache is None it always misses.

use_internal_cachebool

If True (default), use scikit-bot’s internal cache. This is a in-memory cache that evicts files after 24 hours, or when scikit-bot is unloaded. If False, the internal cache always misses.

use_file_cachebool

If True (default), check the local filesystem for a copy of the model file.

update_file_cachestr

If not None, update the file cache at file_cache_dir on file cache misses.

update_internal_cachebool

If True (default) update the internal cache if it missed.

update_user_cacheCallable[[str, str, str], None]

If not None and user_cache missed (returns None or is None), update_user_cache is called with the signature update_user_cache(url, file_path, sdf_string). The expected behavior is that this call will update the user supplied caching mechanism.

file_cache_dirstr

The folder to use for the file cache. It follows the same layout as ignition’s fuel-tools; see the Notes for more information. The default is ~/.ignition/fuel, which is the default location for ignition.

Returns
sdf_stringstr

A string containing the content of the model’s primary SDF (./model.sdf)

Notes

Caches are tiered and the order in which they are checked (from first to last) is: (1) user_cache, (2) internal_cache, (3) file_cache. Updates are done in reverse order. Further, a cache is only updated if it would have been used, i.e., if user_cache hits then neither the internal_cache nor the file_cache are updated since they are never evaluated, even if they would have produced a miss.

You can manually reset the internal caches by calling:

skbot.ignition.fuel.model_cache.clear()
skbot.ignition.fuel.world_cache.clear()

The file_cache stores models on your local filesystem. It never evicts, so you should manually delete outdated models. The format of the cache is:

file_cache_dir/fuel.ignitionrobotics.org/{owner}/models/{model_name}/{version}

Examples

>>> import skbot.ignition as ign
>>> sdf_string = ign.get_fuel_model(
...     "https://fuel.ignitionrobotics.org/1.0/OpenRobotics/models/Construction%20Cone"
... )
>>> sdf_string[:75]+" ..."
'<?xml version="1.0" ?>\n<sdf version="1.5">\n  <model name="Construction Cone ...'
>>> # Notice that (by default) the entire model is cached. Subsequent calls to
>>> # model files thus happen at least at filesystem speed
>>> model_config = ign.get_fuel_model(
...     "https://fuel.ignitionrobotics.org/1.0/OpenRobotics/models/Construction%20Cone",
...     file_path="model.config"
... )
>>> model_config[:75]+" ..."
'<?xml version="1.0"?>\n\n<model>\n  <name>Construction Cone</name>\n  <version> ...'
Return type

str