Units in USD
How units are defined inside of USD is important to understand when it comes to how individual USD files get composed together into an active stage. Having that foundation knowledge will help you understand what the USD runtime is doing when composing content from various sources.
Understanding Units
Users create 3D assets in various applications (like Blender, Houdini, Revit, or Creo) and at various unit scales. Some 3D assets are built in a metric scale (m or mm, etc.), while others use imperial measurements (inches or feet, etc.). Once these various 3D models are exported to USD (either manually, or through an Omniverse Connector), being able to add them into one coherent composed USD stage is vital. This is where USD’s meters per unit metadata comes into play.
This metadata is referred to as MPU (meters per unit) and it is set as a numerical value within each USD file. If a USD file’s MPU is set to 0.01, it means the contents within that USD are encoded in centimeters (literally the scale is “0.01 meters per unit”). Likewise, if the MPU of a given file is equal to 1.0, that means the USD’s scale is encoded in meters (again - the scale is 1.0 meters per unit). The MPU metadata can be set to any value, and it defines the user’s intent for the ratio between the scale of the contents as they relate to a baseline meter. Some common MPU values include:
Metric |
MPU |
|---|---|
Kilometers |
1000 |
Meters |
1 |
Centimeters |
0.01 |
Millimeters |
0.001 |
Metric |
MPU |
|---|---|
Inches |
0.0254 |
Feet |
0.3048 |
Miles |
1609.34 |
All USD files that contain geometry Prims should have MPU metadata defined, but in cases where the MPU is omitted, USD has a fallback to an MPU = 0.01 (centimeters). This value can be inspected by opening the USD file in Pixar’s UsdView application, or in a text editor if the file is in ASCII format (USDA)
Additionally, some USD files will also include density metadata called KGPU (Kilograms Per Unit), and it helps determine the density (mass in kilograms per meter cubed) of geometry Prims that it is assigned to. By default, the KGPU is defined within the UsdPhysics schema, and if it is not explicitly defined in a USD file, it is configured to represent a density of 1 kilogram per unit. It is important to note that the MPU and KPGU metadata are not implicitly connected values as the scale of the object can be managed separately from that same object’s density metadata.
metersPerUnit: This value is the MPU metadata for the USD file. In this example, the model has been built at meter scale (MPU = 1).
In regard to stage composition, these elements are analyzed when a USD file is added into an active USD stage.
The question that arises is: “If you have a stage with a scale set to an MPU = 0.01 (centimeters), and you reference in a model that was built and exported with an MPU = 1.0 (meters), what happens to the inbound 3D data when it is added to the stage?”
Currently, the USD runtime itself does not take MPU into account when resolving final transforms, geometric positions, etc.. Per the Pixar USD documentation:
As with Encoding Stage UpAxis, we restrict the encoding of linear units to be stage-wide; if assembling assets of different metrics, it is the assembler’s responsibility to apply suitable correctives to the referenced data to bring it into the referencing stage’s metric.
The practical result is that by default a 6-meter tall tree (MPU = 1.0) will compose into a centimeter-based stage (MPU = 0.01) as 6-centimeters tall, which is 100x too small because the USD runtime does not do that work for the user. Simply put, it is up to you as the user to then apply the suitable correctives to the inbound USD file to make its scale match that of the active USD stage.
Omniverse Solution
Obviously this can be disconcerting for anyone who doesn’t understand this concept, so in order to make the composition experience more predictable, NVIDIA has developed the Metrics Assembler extension for Omniverse which solves this limitation and the scaling issues for you.
To learn more about how you can set and verify your scene MPU and up-axis in Omniverse, see the Preferences -> Stage documentation.
To learn more about how the Metrics Assembler Extension works, please check out the Metrics Assembler User Guide.