VFS needs a more concise usage definition

[DavidPL1]

I previously have been using VFS to load models at runtime that were supplied as strings (similar as in this discussion #24 (comment)). Since these strings have no path they reside in, every resource within these model strings was supplied with absolute paths and loading did work without errors.

Now I experimented on using VFS with actual model (xml) files and I encountered some issues:

the first issue was that mj_addFileVFS expects the directory to be supplied with a trailing filesystem separator, while, for instance boost::filesystem::path::parent_path(), removes trailing slashes on linux. I think this requirement should either be stated somewhere in the documentation or the function should be able to handle paths where it is missing.

But that is not my main concern, I also found that storing a model that contains an include tag and/or meshes defined with relative paths does not throw an error. However, when you try to load such a model, these relative resources cannot be found.

As an example you can try running the following code with any menagerie model:

int main(int argc, char** argv) {

  std::cout << "Using model: " << argv[1] << std::endl;

  // split parent path and filename
  char *fname = argv[1];
  char *ssc;
  int l = 0;
  int len = strlen(fname);
  ssc = strstr(fname, "/");
  do{
      l = strlen(ssc) + 1;
      fname = &fname[strlen(fname)-l+2];
      ssc = strstr(fname, "/");
  }while(ssc);
  char *path = (char*)malloc(len-strlen(fname)+1);
  strncpy(path, argv[1], (size_t)(len-strlen(fname)));

  mj_defaultVFS(vfs.get());
  int ret = mj_addFileVFS(vfs.get(), path, fname);
  printf("add VFS ret: %d\n", ret);

  if (ret != 0) {
    finish("Error adding file to VFS");
    return;
  }

  char error[1024] = "";
  mjModel *mnew = mj_loadXML(fpath, vfs.get(), error, 1024); 
  mj_deleteModel(mnew);

  if (error[0]) {
    std::printf("%s\n", error);
  }
}

In case of the panda model you'll get the following error message:

Object name = link0_c, id = 0, line = 47, column = -1
Error: resource not found via provider or OS filesystem: 'assets/link0.stl'

So for this to work (without manually adding all required resources) the mj_addFileVFS function should parse all included resources and either add them or replace relative paths with absolute ones.

But the latter option imho somehow defeats the purpose of using VFS in the first place.
The former option begs the question if and how filestructures should be realized within the VFS.

Resource names such as "link0.stl" seem way too generic. A way to avoid filename clashes if more than one model is cached in the VFS would be to prepend the root filename and replace filesystem separators with e.g. underscores to get something like "panda.xml_assets_link0.stl".
At least that was my train of thought until I noticed that from the brief description in the documentation it is not apparent if VFS is even meant to be used in this way. That's why I'm suggesting to clarify what VFS should and shouldn't be used for and maybe come up with some ideas on how to handle this above mentioned case.

tl;dr:

This basically boils down to these questions:

1. Should resources nested in a model file to be cached also be cached automatically or should they be read from the filesystem?
2. When should VFS be used? Or rather what is the intended usage?

[yuvaltassa]

The documentation is here but it can certainly be improved. @kbayes can you address the questions and perhaps improve the documentation if required?

[kbayes]

The first minor issue is a quick fix, so I'll just go ahead and do that.

VFS was created for some Google-internal reasons where the OS filesystem might not be accessible. However, you can see another use case here where we load assets from a Python dictionary. Let me get back to you on the exact intended behavior of the VFS related to your question. I'll also flush out the docs more while I'm at it.

Going forward, I created resource providers, which is a replacement for VFS (in fact VFS is retrofitted to use resource providers). You can try writing a custom provider if that fits your needs.

[DavidPL1]

I see, that clarifies the intention behind VFS a bit more.

I thought of VFS as a means of caching models and their resources to reduce IO, which it kind of is. But it seems for now you designed it to be used explicitly for each resource.

Would it make sense for you to add the functionality that a given model can be parsed recursively for necessary resources to be cached (probably with resource providers)?

[yuvaltassa]

Yes indeed, it very much makes sense and is something we are working on it right now 🙂

It turns out that a very large part of model compilation time is spent in asset handling, so caching processed assets is big win for re-compilation.

Closing for now, though feel free to follow up.

[DavidPL1]

Great! Looking forward for the feature to be released 🙂