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. One can 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 Kit extension to read and parse OmniPVD (OVD) files.
The Physics extension has a recording menu in its Physics Debug window, to decide when and where to record OVD files.
The OmniPVD Kit extension (omni.physx.pvd) makes it possible to import a physics recording in OVD format, transforming it seamlessly into a cached USDA format. Once imported one can do time scrubbing and inspection of an OVD file 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 of a single specific frame of an OmniPVD USD animated Stage recording into the Physics USD format. This 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.
Recording a Physics simulation into an OmniPVD OVD File¶
To record a physics scene in the OmniPVD (OVD) format, one must first make sure that the Physics Debug window is enabled and visible. This can be done by going into the menu Window > Physics > Debug window and making sure it is marked checked, as below.
Then in the Physics Debug window in the OmniPVD section, one needs to make sure to check “OmniPVD Recording Enabled”.
Just underneath is a button called “Set OVD Directory” which allows one to navigate to the desired OVD output 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.
By pressing the button “Explore Latest OVD”, below “Set OVD Directory”, one gets to open the directory and see the recordings including the last one.
If the checkbox “OmniPVD 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 “OmniPVD Recording Enabled” is grayed out, as it’s not possible to record any simulation data from an OmniPVD Prim, as it remains an animation.
Loading the OmniPVD Extension¶
The OmniPVD extension is called omni.physx.pvd and can be found in the extension browser by searching for “pvd”. Just make sure to click on the slider next to “AUTOLOAD” to enable it.
Importing an OmniPVD OVD File Recording¶
Once a simulation is recorded into a time stamped OmniPVD OVD file, one can import it, which will automatically look for a cached version of a corresponding USD Stage (in the Cache directory) and load 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 “Import” button in the file browser, the chosen file goes through the import process. By default the latest OVD recording is chosen and one can then simply click on “Import” to import it quickly.
It is no longer needed to do an explicit USD transformation step (as in previous versions of OmniPVD) as the cached files are time stamped and locked to a certain OVD file.
If one would like to change the USD cache directory, this is possible to change using the “Set Cache Directory” button just below.
The up axis for the USD Stage is automatically derived from the PhysX gravity vector, but can be overriden with the drop down meny (Y or Z).
The OmniPVD Object Tree and OmniPVD Property Widget¶
A recent addition to OmniPVD is the OmniPVD 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 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 coloured, 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.
OmniPVD 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.
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 brin 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.
