An iroh resolver plugin for OpenUSD

[expenses]

Hey guys, thought I'd post the project I've been working on recently, an asset resolver for OpenUSD that resolves iroh:// URIs using an iroh RPC client: https://github.com/expenses/usd-iroh-resolver.

OpenUSD is a very powerful file format and SDK for 3D scenes. USD files can reference other USD files, creating a DAG. By default these references come in the form of filesystem paths, but there's a plugin system that let's you define a resolver for a given set of URI schemes.

The resolver I've written currently handles 4 routes:

• iroh://blob/<hash>: very simple, just tries to load the file associated with the hash from the local store
• iroh://ticket/<blob ticket>: tries to load the file associated with the ticket hash locally, but will then attempt to download it from the given peer if missing.
• iroh://doc/<namespace>/<key>: tries to load the given doc, queries the doc for the latest exact key and loads the file associated with the entrys hash. Note that keys are base32-encoded so that you don't need to worry about trying to represent null or non-utf-8 bytes in the URI.
• iroh://docticket/<doc ticket>/<key>: imports the given doc, queries for the key but if the content isn't available locally it'll subscribe to the doc event stream and wait until a value for the key is available locally.

Note that OpenUSD requires a way to get the extension for the specific asset, and rather write a system that determines or precomputes the MIME-type for a file, I just decided to stick it on the end of the URIs as a piece of metadata, so you have iroh://blob/rajn6rkgc74r3ohwlziypdh54bgqlsusl5cds3jzajs2aucxox5q.usda instead of just iroh://blob/rajn6rkgc74r3ohwlziypdh54bgqlsusl5cds3jzajs2aucxox5q.

This is also a work in progress, especially the document stuff which I think I'll have to make significant changes to.

I've mostly just tested by loading self-contained USD files hosted on another machine that don't need to reference other files, but in the future I want to work on more complex scene graphs.

One edge case is a situation where you load an initial file on node A via a ticket that references node B, but then that file references other files by hash. If the content for those blobs isn't available on node A then it's not obvious where it should be loaded from. Luckily, USD passes both the URI for the file being referenced as well as the URI for the file referencing that (called the anchor). If the anchor is a iroh://ticket URI and the path is a iroh://blob URI then you can extract the components of the ticket for the anchor and rewrite the path into a iroh://ticket URI.

A trickier situation is where node A loads a file with a ticket referencing node B, and that file references node C via a ticket, but node C is offline and the content isn't available on node A. It's possible that node B has the content though so ideally you'd request it from node B after node C. This would probably require constructing a URI like iroh://ticket/<B ticket>/<C ticket> and trying each ticket in reverse order.

If a USD file that you got from a document ticket references a hash then I suppose you could try to download the hash from each peer in syncing the document, but that sounds like a bad idea.

Overall I'm very happy with the way iroh is developing, keep up the great work!

[b5]

(copying from discord):

this is amazing! I've been dreaming of an iroh plugin for USD since I found out about the format. My partner is an architect, and I've been itching to introduce universal scene description + iroh to their office workflow. I will straight up be using this.

This is also a work in progress, especially the document stuff which I think I'll have to make significant changes to.

We definitely need to dig in on the edge cases you've mentioned, and see if the current tools we're giving you are adequite. Iroh takes the fairly strong view that DAGs should be flattened into "arrays" (documents & collections are both flat lists, and the only compound types we provide). It seems here you're in a situation where the host environment might not give you all the information you need to do such flattening up front.

Most of my questions surround how USD handles mutations to the scene graph, and what view of the graph USD gives you as a plugin author. Can you give quick synopsis on what hooks the plugin has to fulfill, or point us at some links?

So pumped.

[expenses]

Most of my questions surround how USD handles mutations to the scene graph, and what view of the graph USD gives you as a plugin author. Can you give quick synopsis on what hooks the plugin has to fulfill, or point us at some links?

Totally! So what I'm dong is defining an asset resolver plugin: https://openusd.org/dev/api/ar_page_front.html. To be honest I don't 100% understand the system yet, and I don't want to do a long writeup of how it works yet because I could be wrong or mistaken in some way, but basically:

1. CreateIdentifier: Asset paths/URIs are combined with an anchor path to produce an 'identifier path'. I believe this is for deduplication, so that two different paths that point to the same asset don't end up loading the asset twice. A filesystem implementation of this step would produce an absolute filesystem path. I do things like turning hash paths into ticket paths provided that the anchor URI is a ticket. Ideally a document + key anchor should combine with a key to create a new document + key path.
2. Resolve: this uuuhhhh I believe is intended to produce the final filesystem path, e.g. if paths are being read of a database. I'm not using it yet and just passing the identifier URI.
3. GetExtension: Gets the file extension. I'm just using the default implementation which takes it from the URI.
4. GetModificationTimestamp: Gets the timestamp, used when reloading the USD stage. For this I can get the timestamp of the document entry, or just set it to 0 for blobs.
5. OpenAsset: takes a resolved path and returns an ArAsset. By default I think this just reads the file at the resolved path.

There are a bunch of *ForNewAsset functions such as https://openusd.org/dev/api/class_ar_resolver.html#ae9bdf8eab4d4ebf70a0d2df3727ff9b8. These are called when creating USD files with the API. I think it should be possible to allow writing to documents using these.

In theory, we could instead have a system that uses the default implemention of OpenAsset where Resolve just resolves to the path to the blob on disk, i.e. ~/.local/share/iroh/blobs.v1/complete/<hash>.data. I don't actually think this is a good idea though as it wouldn't actually make anything easier really and would break if iroh switched to e.g. storing blobs in sqlite or whatever. But it's something I thought I'd just bring up.

[expenses]

I just changed things up so: A) document keys are just treated as URI paths (this means that non utf-8 keys are not accessible atm, but I could just add another route for those). and B) any relative paths inside a document are resolved to a document path. This means that syncing existing scenes just ™️ works ™️ for the most part. Between two machines, I've managed to load the kitchen set from https://openusd.org/release/dl_downloads.html#assets and the esper room scene from https://j-cube.jp/solutions/multiverse/assets/:

I did try syncing the base ALab production scene: https://dpel.aswf.io/alab/ (contains 14191 files totalling 10.02 GiB) but it seemed to stop syncing after a certain point. It when added locally though:

[expenses]

I've now added support for writing assets. Writing the ascii .usda files works perfectly, but writing the binary .usdc files causes a segfault when USD tries to reload the file afterwards. I believe this is because it's doing some funky memory-mapping stuff. The file gets written perfectly fine and can be loaded afterwards though.