15. USD

MiEx export out worlds into USD (Universal Scene Description). This is done as a post-process. MiEx first exports the world out into a custom intermediate file format (allowing it to keep memory usage down even when export really large worlds) and then it converts that into USD files. This also makes it possible to add in support for exporting to different file formats.

General structure of the USD files

MiEx will generate multiple USD files in the following structure:

- <name>.usd
- <name>_materials.usd
- <name>_chunks
| - banners
| | - banner_<banner_id>.png
| | - ...
| - <region_name>_chunk_<chunkX>_<chunkZ>.usd
| - <region_name>_chunk_<chunkX>_<chunkZ>_render.usd
| - <region_name>_chunk_<chunkX>_<chunkZ>_anim.usd
| - <region_name>_chunk_<chunkX>_<chunkZ>_anim.topology.usd
| - <region_name>_chunk_<chunkX>_<chunkZ>_anim.manifest.usd
| - ...

<name>.usd is the main file that is to be referenced into your scene. <name>_materials.usd contains all of the materials generated from the USD material templates. <name>_chunks in a folder that holds all of the chunk USD files. <region_name>_chunk_<chunkX>_<chunkZ>.usd contains the main chunk data including the proxy meshes. <region_name>_chunk_<chunkX>_<chunkZ>_render.usd contains render data, like the optimised-for-raytracing meshes. <region_name>_chunk_<chunkX>_<chunkZ>_anim.usd contains the animated geometry for that chunk. banners contains composited banner textures used by banners that were exported.

Each chunk is payloaded into the main USD file, so that artists can specify which chunks they want to be loaded in and which one not. This allows them to keep their applications interactive. The render USD files are payloaded in behind a variant set called MiEx_LOD. If no variant is selected (default), then only the proxy meshes are loaded in. If the render variant is selected, then the render USD files get payloaded in. There is also a proxy variant which does nothing and is the same as having no variant selected, but is there in case an application doesn't allow you to unselect a variant.

The structure of the composed USD stage for the exported world looks like the following:

def Xform "world"{
    def Scope "individualBlocksBaseMeshes"{
        class Xform "_class_<block name>"{
            Meshes
        },
        ...
    },
    def Scope "materials"{
        def Material "MAT_<texture name>"{
            Shading nodes
        },
        ...
    },
    def Xform "foreground"{
        def Xform "<region_name>_chunk_<chunkX>_<chunkZ>"{
            def Xform "<texture name>" ( purpose = "render" ){
                Individual meshes with that texture, coming from the render USD file for the chunk.
            },
            def Mesh "<texture name>_proxy" ( purpose = "proxy" ){
                Proxy mesh coming from the normal USD file for the chunk.
            },
            ...
            Instances inheriting from the individual block base meshes classes
        },
        ...
    },
    def Xform "background"{
        Same as foreground Xform but then holding all of the background chunks.
    }
}

The root world prim contains the variant set MiEx_LOD that allows you to choose to bring in the render USD files.

USDCAT

Because MiEx is written in Java, it does not have direct access to the USD libraries, which prevents it from exporting out into USD Crate files. USD files can be of two kinds: USD ASCII and USD Crate. USD ASCII is text based and USD Crate is binary. USD Crate is much faster than USD ASCII, but MiEx by default has to export into USD ASCII. To still be able to create USD Crate files, MiEx can use the usdcat tool found in USD to convert the exported USD ASCII to USD Crate.

Some applications with USD support (like Houdini or Maya) already provide usdcat, and all that you need to do is to tell MiEx where the usdcat executable is located. You can do this using the MIEX_USDCAT_EXE environment variable or the -usdcatExe <path> command-line argument. With these you specify the path to the executable itself. In other cases, you might need to compile USD yourself in order to get usdcat. Keep in mind that in some cases usdcat needs additional folders to be available in the PATH environment variable. Often usdcat will be located in a /bin folder, but there's also a /lib folder which needs to be added to the PATH environment variable. If all files that usdcat needs are located in the same folder as usdcat, then in theory it should be able to access them without the PATH environment variable needing to be edited.