Metrics Assembler

The Metrics Assembler Extension is responsible for fixing scaling issues in USD stages. It ensures that when one USD file is composed into another active stage, its Meter Per Unit (MPU) scale, up-axis orientation and any densities assigned via the UsdPhysics scheme (KPGU or “kilograms per unit”) are adjusted so that they correctly match the MPU and values within the active stage. The Extension runs in the background within Omniverse and detects any user drag-and-drop of USD files into an active stage.

When USD content is added into an active stage via drag-and-drop, the extension actively compares the MPU metadata of both the inbound USD file and the active stage. If there is an MPU mismatch, the extension applies a set of corrective transforms to the inbound USD file to ensure that when it comes into the active stage it matches the active stage’s MPU while also ensuring that the up-axis orientation is the same. This has the practical effect of rescaling and reorienting the inbound model so that its MPU and orientation respect the active stage’s MPU and orientation.

It is important to note that this extension not only analyzes the MPU scale of the USD file (cm vs. m vs. inches, etc.), and its up-axis orientation, but it also adjusts any physics or density-based properties (kilograms per unit or KGPU) that are present within the inbound file. This corrective is applied when physics and mass properties are set up as part of the inbound file, and the Metrics Assembler extension will apply correctives as needed to ensure that objects with density-based properties applied behave as expected when inserted into a stage with a different MPU and simulated.

Note

Metrics Assembler is turned on by default in NVIDIA Omniverse™ USD Explorer and NVIDIA Omniverse™ USD Composer

Usage

The workflow for you is completely transparent and requires no additional effort. The Metrics Assembler extension is active by default, so as you drag and drop USD files from the content browser into your active stage or into the Stage panel it will adjust their scale and density automatically. If the inbound USD file has an MPU, up-axis or KGPU that doesn’t match the active USD stage settings, it will automatically trigger the Metrics Assembler extension to apply the corrective transforms. The default behavior of the extension is to automatically apply the corrective transforms and alert you. But this behavior can be modified in the Preferences -> Metrics Assembler panel if you wish.

When the Metrics Assembler corrective transforms are applied, you are made aware of them in three interconnected locations within Omniverse.

  1. Property Panel: When a USD file with mismatched MPU metadata is composed into an active stage (via drag-and-drop), the Metrics Assembler extension will write one or more corrective transformations to the object so that it appears as expected. It adds new properties as additional unitResolve Transforms directly within the Property Panel.

    • The Rotate:unitsResolve corrective transform will appear if the up-axis defined in the inbound USD file does not match the scene’s default up-axis (defined in the Preferences -> Stage-> Default Up-Axis section)

    • The Scale:unitsResolve corrective transform will appear if the MPU defined in the inbound USD file does not match the stage’s MPU scale (defined in the Preferences -> Stage -> Default Meters Per Unit section).

    Metrics Assembler unitsResolve transforms applied to prim

    The corrective XForms are added at the bottom of the existing Transform panel for its root node. It is strongly recommended that you NOT alter either of those transforms manually unless you understand how units work inside of Omniverse. See the Units primer section for more insights on how different units are handled within typical USD compositions.

  2. Layer Panel: When the Metrics Assembler extension applies corrective transforms to an inbound model with a mismatched MPU, it does so via the addition of a new Layer in the Layer Panel.

    By default, this layer will be hidden from you to help avoid accidental deletion or other confusion, but it can be made visible by clicking on the Layer panel’s hamburger menu in the upper right and selecting the Show MetricsAssembler Layer checkbox.

    "Show Metrics Assembler Layer" Menu in the Layer Panel

    When active, the Metrics Assembler layer appears as follows:

    Metrics Assembler Layer visible in Layer Panel

    This single layer (which is prefixed with UnitsAdjust), is placed in the current authoring layer for the active stage and holds all of the corrective transformations for all mismatched USDs that are composed into the active stage. It is important to note that this layer is generated dynamically each time the active scene is loaded, so you don’t need to manually save this information as a separate USD it in order to preserve the MPU corrections within your Stage.

  3. Notification through Metrics Assembler Operation Mode: Any time you drag and drop a USD with a mismatched MPU into the active stage, the Metrics Assembler has the ability to inform you of this mismatch in one of several ways. These options are set within the Preferences -> Metrics Assembler section. This can take the form of a blue “toast” pop-up window or a modal dialog.

Metrics Assembler Preferences Panel

Metrics Assembler Preferences Panel

Metrics Assembler Operation Mode

This dropdown controls how the Metrics Assembler functions.

  • Auto Resolve: This is the default for how Metrics Assembler operates. All inbound USD files that have mismatched MPUs are automatically corrected upon drag-and-drop, and a blue “toast” pop-up will appear in the lower-right of the viewport to inform you that corrective transforms have been applied.

    Auto Resolve pop-up message

  • Ask to Resolve: This operation mode generates a modal dialog pop-up when you drag and drop a mismatched MPU USD file into the active stage. It provides you with a choice as to whether or not to apply the corrective transformations to the inbound USD file or to simply ignore the MPU mismatch and compose the file as-is. Clicking Resolve will apply the corrective transforms, while clicking Cancel will import the USD file without applying the corrective transforms.

    Ask to Resolve Modal Dialog

Using this mode can be handy when you want to better understand what aspects of the inbound USD file don’t match their current stage metadata. In the example above, the inbound file (fiberdrum_a06) has an MPU of 1.0 and an upAxis = Z, while the active stage has an MPU of 0.01 and an upAxis of Y. So the corrective transforms would be applied to both the MPU and UpAxis orientation on the inbound USD.

  • Warn: This mode simply produces a yellow warning “toast” in the lower-right of the main viewport to indicate to you that the inbound USD file does not match the active Stage’s MPU. The inbound USD file is still composed into the stage, but does not have any corrective transforms applied and may appear wrong in relation to the rest of the scene and it will be up to you to apply any corrective XForms on your own.

    Warning pop-up message

  • Disabled: This mode disables the Metrics Assembler extension from doing anything in regards to the MPU or other metadata of inbound USD files.

Metrics Assembler Parameters Change Listener Enabled

Once a 3D model is dragged-and-dropped into an active stage and the Metrics Assembler has run to correct it, there are certain events that can be subsequently triggered which may still cause a 3D asset to misbehave based on its original MPU and density based metadata (e.g. physics variants being activated at a later time). This checkbox enables a background listener for these new UnitAdjust layers to listen for changes on those paths so that further Metrics Assembler updates can be run as necessary.