OmniPVD - PhysX Visual Debugger

Overview

Omniverse PhysX Visual Debugger (OmniPVD) allows the recording of data of a physics simulation for later visual and quantitative inspection. For example, one can record a rigid body box falling onto a ground plane, then replay the recording and inspect the motion of the box frame-by-frame to spot simulation issues. Besides the body transforms, the recording contains further simulation data, such as the values of the linear and angular velocity of the box at each frame.

OmniPVD consist of a shared dynamic library and an extension (omni.physx.pvd). The shared dynamic library is used both by the PhysX SDK simulation engine for the recording and writing of OmniPVD binary files (OVD) and by the omni.physx.pvd Omniverse USD Composer extension to read and parse OVD files.

The are two OVD file recording menus, one is located in the Physics extension in its Physics Debug window and the other is located at the top of the OmniPVD extension tab. One can decide when and where to record OVD files from both of these two locations.

The OmniPVD Omniverse USD Composer extension (omni.physx.pvd) makes it possible to import or load a physics recording in OVD format, transforming it seamlessly into a cached USDA format. Once the OVD file is imported one can time scrub and analyze it as a USD Stage, which is good for debugging, inspecting and visualizing a recorded physics scene, but it stays a pure animation. The OmniPVD gizmos are also then possible to apply to the imported OVD file, for the sake of different visualizations such as collision contacts, bounding box representations, velocities as well as seeing mass and transform reference frames.

The OmniPVD extension has the option to export a single specific frame into the Physics USD format, which allows one to use the exported frame as an initial state when simulating the scene.

Lastly OmniPVD has a PhysX baking feature, for the reading of a physics recording in OVD format and the baking of the transforms of objects, onto Omniverse Physics objects in a separate Edit Layer. This makes for the replacement of the simulated objects with a set kinematic path, still allowing other physics simulated objects (added afterwards) to interact with them, but not affecting them.

Loading the OmniPVD Extension

The OmniPVD extension is called omni.physx.pvd and can be found in the extension browser by searching for “pvd”. Make sure to click on the slider “ENABLED”, to move it into its rightmost position shown as green, to have it be activated and visible.

Recording a Physics Simulation from the Physics Debug Window

To record a physics scene in the OVD format, one must first make sure that the Physics Debug window is enabled and visible or that the OmniPVD extension window is visible, as will be discussed below. This can be done by going into the menu Window > Physics > Debug window and making sure it is marked checked.

Then in the Physics Debug window in the OmniPVD section, one needs to make sure to check “Recording Enabled”.

Just underneath is a button called “Set Recording Directory” which allows one to navigate to the desired OVD recording directory, in which time stamped OVD recordings will be saved. By stepping inside of the directory of choice and by pressing “Select Current”, the OVD output directory is updated and set. Each time the Physics simulation is started and stopped, a new OVD recording is saved out and time stamped into this directory as can be seen in the numerous .ovd recordings.

If the checkbox “Recording Enabled” is both checked and enabled (not grayed out), as soon as the “Play” button is pressed, PhysX is now recording OmniPVD time stamped files into the OVD recording directory.

If the USD Stage is an OmniPVD Stage (it has OmniPVD prims) the checkbox “Recording Enabled” is grayed out, as it’s not possible to record any simulation data from an OmniPVD Prim, as it remains an animation.

Recording a Physics Simulation from the OmniPVD Window

As was shown above one can record a physics scene from the Physics Debug window, but it’s also possible to do it from the OmniPVD extension, by checking “Recording Enabled” as in the screen shot below.

Just as in the Physics Debug window one can also select the recording directory with the button with the same name.

Enabling OmniPVD Recordings from the Command Line for a Headless Composer Session

If one needs to record a PhysX simulation into OVD from a headless Composer session, one can enable OmniPVD recording from the command line by the following Composer settings:

/persistent/physics/omniPvdOvdRecordingDirectory
/physics/omniPvdOutputEnabled

An example console command line (here from Linux and not complete as the Stage would also need to be defined):

bash kit/omni.app.dev.sh --no-window --/windowless=True --/persistent/physics/omniPvdOvdRecordingDirectory=/tmp/ --/physics/omniPvdOutputEnabled=true

The order of the settings is important, first one must enable the output directory and only then enable the OVD output. If this order is not followed, the OVD recording will try to be written into a predefined directory, which might not exist. The writing operation will not crash but it will produce an error.

It is not required to load the OmniPVD extension to do recordings, one must simply make sure to have the OmniPhysics extension loaded and do the recording from there. The OmniPVD extension is only necessary to import the produced OVD file.

Enabling OmniPVD Recordings via Python in a Composer Session

Similarly to how one can enable OVD recording from the console or command line, one can enable recording in a Python script. This might look like:

settings_ = carb.settings.get_settings()
settings_.set("/persistent/physics/omniPvdOvdRecordingDirectory", "/tmp/pvdout2/")
settings_.set("/physics/omniPvdOutputEnabled", True)

The same rule as above for the console command applies, in that the recording directory has to be set first and only then one can enable the output. It is not required to import the OmniPVD extension in the script to do OVD recordings, one must make sure to have the OmniPhysics extension imported.

The Structure of OVD Recording File Names

In the OmniPVD recording options fro Omniverse Composer listed above, the OVD file names will be based on a time stamp and end in a file type of ovd. Recording is not destructive and always allows new recordings to not overwrite older ones, due to the time stamps being ever increasing, with an extra safety mechanism if ever within the same Omniverse Composer session, two time stamps would be the same.

Loading an OVD File from the OmniPVD Window

Once a simulation is recorded into a time stamped OmniPVD OVD file, one can import or load it. The loading operation automatically looks for a cached version of a corresponding USD Stage (in the Cache directory) and loads that if it’s already created. One can now explore the USD Stage of the imported OVD file in Omniverse USD Composer, inspecting the recorded motion and data. By pressing the “Load Latest” button in the file browser, the chosen file goes through the import process.

If one would like to change the directory from where to load the latest OVD file from one can do so by clicking “Set Import Directory” button just below.

The up axis for the USD Stage is automatically derived from the PhysX gravity vector, but can be overridden with the drop down menu (Y or Z).

Lastly one can set the cache directory where the USD Stages, which are created on loading an OVD file are stored. The next time the same OVD file loaded the USD Stage is directly loaded from there.

The Object Tree and Property Widget

A recent addition to OmniPVD is the Object Tree, while similar to the USD Stage view has some distinct features, namely

Objects are not required to be displayed with the USD Prim names (which have to follow strict SDF path rules), instead they can derive the name from the OmniPVD object name (a string set at the object creation call), a PhysX actor name or a combination of the OmniPVD class name and a unique identifier
Objects have the OmniPVD type displayed in the type column, not the USD Prim type

The Object Tree also has a search bar, which differs from the USD Stage search bar, in some ways

The search bar is not displaying the search results in a flat list, instead if expands the matching objects (based on their OVDTree name and UID) and allows for iterating through the results using the Prev/Next buttons
It’s possible to collapse the view and thus make sure only the root objects in the tree are visible, this is a convenience not to have to collapse all the nodes/objects manually, as every search result accumulates the expansions to the existing ones, for any objects/Prims that match the search criteria

The USD hierarchy in the resulting cached Stage file (that is generated when an OVD file is imported) starts of with a scene, then lists the dynamic rigid bodies, static rigid bodies and then articulations of an OVD recording. For each body, one has an actor or articulation link with accompanying shapes and geometries. Each USD Prim has a set of custom USD attributes, which can be explored in detail and if they change over time, can be scrubbed through the animation and one can see how they are updated.

Another view of the Stage is in the OmniPVD Object Tree, which allows for using of non-SDF compliant name display (as opposed to USD), it mirrors the USD Stage, but displays the Prims with the PhysX derived name, or OmniPVD object name (given at creation time) otherwise with the OmniPVD type. A Unique Identifier (UID) is prepended to all the object, which is connected to the moment an object was created. It follows the creation/removal of objects, so only the objects that are active in the PhysX engine at that specific frame (defined by the timeline interface scrubber) are displayed in the tree. This is to have a more precise visualisation of what was actually simulated in the frame.

Selection in the viewport will select the Prim geometries but will make sure that selection affects the PxActors that are above the geometries in the OVD Tree. This is to make sure that selection is a smooth and intuitive operation and does not break the existing interaction paradigm of the USD Stage.

One can also search in the names of the OmniPVD objects or the UID, as opposed to the search bar in the USD Stage (which only allows for search in the Prim path and Prim name), and one also gets the resulting searches expanded and colored, with the possibility to walk over the results using the Next and Prev buttons. The “Collapse All” button, does what one would expect and collapses all expanded nodes of the tree, which is useful to do if one has done many searches as each search continues to expand nodes each time, resulting ultimately to the expansion of all nodes if one searches for a string that is part of all object names.

Below the Object Tree, is the Property window and inside the Physics widget lives the OmniPVD Property widget, which displays the OmniPVD attributes in a pretty printed form. The attributes in the widget get updated with the timeline changes in the USD Stage.

Visualization Gizmos

There are several ways to augment the imported OVD file with OmniPVD gizmos, they are mainly set to None, All or Selected from the menu below. The drop down menus with the scaling values attached allows to scaled each type of gizmo either independently or together globally. As here below the velocity gizmos are set to Selected and their individual scale to 0.2 while the global scale is 3.8, leading to a combined scaled of 3.8 x 0.2 for the velocities.

Selection can either done from the viewport, which also ends up selecting them in the Stage and OmniPVD Object Tree windows both. Selection is multi-directional between the viewport, the Stage and the OmniPVD Object Tree. It’s for example possible to see bounding boxes which are the same axis aligned bounding boxes that PhysX uses internally to delineate the actors.

The contacts with the reference frame along with the mass reference frame are shown for the selected actors below. What is interesting is that the cone has a differently aligned mass reference frame from its transform frame.

One can also view joints (such as D6, distance, gear, prismatic, rack and pinion and others) as for example this rope made out of D6 joints

Or for example this distance joint.

Or this gear joint

Or this spherical joint.

Using these gizmos one increases the ability to drill down into debug data.

Transforming a Single OmniPVD USD Animation Keyframe into a Physics USD Stage

One can also transform a single keyframe of the imported OVD file into a PhysX USD stage, which can then be simulated and can be useful for isolating a certain problematic frame in your simulation. It can then be fed back into physics and be simulated again so that one can tweak the parameters to one’s liking to get the desired effect.

If the current Stage is an OmniPVD Stage, by pressing the “Transform OmniPVD USD to PhysX USD” button, one outputs a new time stamped stage into the output Directory in the test field right below.

Overlaying an OmniPVD OVD File onto a USD Stage - Physics Baking

One can, as a last feature, overlay an OmniPVD simulation recording onto a USD Stage, thereby baking the physics simulation as an animation track, the purpose being repeatable motion with all render materials intact.

This is useful for amortizing the cost of a long and complex physics simulation to treat it as a time scrubbed animation, instead of a full-blown simulation. The PVD data animated bodies can still interact with other dynamic physics objects in the scene, as they are converted to kinematic rigid bodies.

The first step is to have a Physics simulation stage ready and to record it’s OVD file as below. Making sure to press Play, then Stop simulation to have a new OVD file.

The second step after having simulated and recorded the OVD, is to re-open the stage with a New Edit Layer.

OmniPVD Physics Baking Open with Edit Layer

Making sure that the Edit Layer is selected in the Layer window and so that it is the current Authoring Layer.

Once the New Edit Layer is the Authoring Layer, one can now press on the “Bake PhysX Transform into the Active Edit Layer” which will bring up a selection menu to chose from the latest OVD recordings. Pressing “Select Current” in this window will close it and transform the chosen OVD into the Authoring Layer, thereby “baking” the recorded simulation into the Stage. The selected OVD will end up in the “Overlay OVD” text field just below.

The final “baked” Stage now contains the same materials and geometries as before but also makes sure that the PhysX actors that are involved get a “Kinematic Enabled” flag set to checked, making so that if other elements that are simulated are added into the stage, they will also now react to these actors. One can for example simulate a large warehouse (as was done) and then to add flow simulations on top.