Converting Between Layer Formats

Converting Between Layer Formats


Setup Python

Ensure that you have configured your python environment, this is described in the USD Tutorials document.


This tutorial will walk you through converting a layer file between the different native USD file formats. USD includes three native file formats:

  • .usda files – human-readable text format
  • .usdc files – binary format
  • .usd files – either of the above formats

The usdcat tool is useful for inspecting these files, but can also be used to convert files between the different formats using the -o option and supplying a filename with the extension of the desired output format. We'll walk through some examples of how to do this.

Table of Contents

Converting between .usda/.usdc and .usd

A .usd file can be either a text or binary format file. When given a .usd file, USD will detect the underlying format and handle the file appropriately. Converting between .usda/.usdc and .usd is just a matter of changing the extension on the file. For example:

  • Given a text format file Sphere.usda, you can simply rename this to Sphere.usd. When given the .usd file, USD will detect it is a text format file. This holds true for .usdc files.
  • Given a .usd file Sphere.usd that uses the text format, you can rename the file to Sphere.usda.
  • Given a .usd file Sphere.usd that uses the binary format, you can rename the file to Sphere.usdc.

Converting between .usda and .usdc Files

We'll start with a simple .usda file, Sphere.usda in the USD/extras/usd/tutorials/convertingLayerFormats folder. This is a text format file, so it can be examined in any text editor or via usdcat.

$ usdcat Sphere.usda

#usda 1.0
def Sphere "sphere"

To convert this file to a binary format file, we can simply specify an output filename with the .usdc extension:

$ usdcat -o NewSphere.usdc Sphere.usda

This will produce a binary format file named Sphere.usdc in your current directory that contains the same contents as Sphere.usd, which we can verify using the usddiff tool:

$ usddiff Sphere.usda NewSphere.usdc

Converting from a binary format file to a text format file and verifying the contents match can be done in the same way:

$ usdcat -o NewSphere.usda NewSphere.usdc
$ usddiff NewSphere.usdc NewSphere.usda

Converting between .usd Files of Different Formats

If you have a .usda or .usdc file and want to make that a .usd file without changing the underlying format, you do not need to go through usdcat. See the "Converting between .usda/.usdc and .usd" section above

If you have a .usd file of a particular format and want to convert it to a .usd file using a different format, we need to pass some additional information to usdcat via the --usdFormat option. We'll start with Sphere.usd in the USD/extras/usd/tutorials/convertingLayerFormats folder, which is a text format file. To convert this to a .usd file using the binary format:

$ usdcat -o NewSphere_binary.usd --usdFormat usdc Sphere.usd

We can then verify the contents of this binary .usd file match the contents of the original text .usd file:

$ usddiff Sphere.usd NewSphere_binary.usd

Converting a binary .usd file to a text .usd file and verifying the contents match can be done in the same way:

$ usdcat -o NewSphere_text.usd --usdFormat usda NewSphere_binary.usd
$ usddiff NewSphere_binary.usd NewSphere_text.usd