.. # define a hard line break for HTML .. |br| raw:: html
.. illustrations and other source materials are here: https://drive.google.com/drive/folders/1VO_P_RQYBeXRqYdol5dSJ6bw52tCq3Ox?usp=sharing .. _Physics: ================================ Physics Core ================================ Overview --------------- The |omni_long| Physics simulation extension is powered by the |physx_long|. Below you can find a list of the main features of |physx_short| that are available in |omni|. Physics Core Components ----------------------------- .. toctree:: :titlesonly: ext_physics/rigid-bodies.rst ext_physics/character-controller.rst ext_physics/deformable-bodies.rst ext_physics/physics-particles.rst ext_physics/articulations.rst Getting Started ----------------------------------------- The physics simulation extension *omni.physx.bundle* is enabled in |composer| by default - if you are using another |omni| App, you may enable the physics extension in the **Window > Extensions** window. Explore Physics demos ######################### A great starting point for exploring physics are the demo scenes available in **Window > Simulation > Demo Scenes**: Just load a scene and hit play (see highlighted play button in the screenshot). We introduce the basic elements of a physics simulation with the *Box on a plane* snippet: .. image:: /content/images/ext_physics-core_basic_elements_box_on_plane.png :alt: Basic Physics (UI) Elements Physics Authoring Toolbar ############################ Important to mention is the Physics Authoring Toolbar, which can be used to streamline your physics authoring user experience. Follow the link below to enable and learn more about it. .. toctree:: :titlesonly: ext_physics/support-ui.rst Physics OmniGraph nodes ############################ ``omni.physics.graph`` extension includes a number of OmniGraph nodes to enhance Graphs with advanced Physics functionality. OmniGraph physics nodes can be easily accessed from **Python** by leveraging regular OmniGraph Python API and evaluating the graph at each needed step to extract results from it. .. toctree:: ext_physics/omnigraph-immediate-nodes.rst ext_physics/omnigraph-scene-nodes.rst Setting up physics ############################## There are three key primitives (prims) on the snippet stage: 1. The *physicsScene* prim provides simulation parameters such as gravity direction and magnitude, the simulation time-step size, and advanced solver algorithm settings. 2. The *boxActor* prim is a cube shape that has rigid-body dynamics: it spins and falls under gravity. 3. The *groundPlane* is a simple mesh that is configured as a static collider: It does not move but the box can collide with it. You can configure the three prims, and their physics properties in particular, through the Property window (**Window > Property**). For example, the rigid-body options for the box reveal its initial 180-degree-per-second spin around its x-axis. You can easily recreate the snippet setup with the following steps (you may want to clear the stage first with **File > New**): #. Create the ground plane mesh with **Create > Mesh > Plane**. You can scale it in x and z to make it larger. #. Configure the plane mesh as a static collider by right-clicking it in the viewport or stage tree, and selecting **Add > Physics > Colliders Preset**. #. Create the cube shape with **Create > Shape > Cube** and move it up above the plane, so it can fall. #. Configure the cube as a rigid body analogous to the plane but selecting **Add > Physics > Rigid Body with Colliders Preset**. Set its initial rotational velocity in *x* to 180 deg/s in the property window, see highlight above. #. Create the physics scene with **Create > Physics > Physics Scene**. #. Hit play and watch the cube spin and fall onto the plane. Note that a shortcut to creating the ground plane is **Create > Physics > Ground Plane**. Simulation Control ----------------------------------------- The settings that control your simulation are in four key places: 1. The `property window`_ of the prims that are simulation objects, for example rigid bodies. In the property window, you can add and remove simulation components, and fine-tune properties such as mass, collision-shape approximation, etc. 2. The property window of the `Physics Scene`_ that holds general simulation properties such as gravity and solver parameters. 3. The `Physics Settings`_ window provides per-stage settings saved in USD metadata for portability; for example, settings include a lower bound on the simulation rate and mouse-interaction parameters. 4. The `Physics Preferences`_ in **Edit > Preferences** provide general simulation settings such as the option to en/disable reset on stop. 5. The :ref:`layer metadata ` that USD uses to scale units (e.g. distance). The physics extension considers this scaling when parsing simulation parameters, so you should be aware of what scale you are authoring a simulation in. **Debug visualization** Visualizing for example collision-shape approximations may help you figure out issues with a simulation. There are many visualization and other debug options in the `Physics Debug Window`_ (**Window > Simulation > Debug**). In addition, you can enable feature-specific debug visualization in the *Show/Hide* (Eye) menu in the viewport: .. _debug_viz: .. image:: /content/images/ext_physics-debug_viz_eye.png :alt: Physics Debug Visualization Viewport Eye .. note:: Debug visualization can be slow for large scenes. **Mouse Interaction** Finally, it is fun and may be helpful for testing to *interact* with objects. You can push or grab objects by shift-clicking them in the viewport when the simulation is running. See the related settings and description in the :ref:`Mouse Interaction Settings `. .. _Property Window: Property Window ########################## In the Property Window (**Window > Property**), you can edit the physics properties of a prim, or you can add or remove simulation components (i.e. USD APIs). You can *add* physics components with the **Add** button that shows a list of components that you may add to the selected prim. The list is context-sensitive and only shows physics components that are compatible with the prim and other physics components that the prim already has. Adding a component populates the Property Window with a new rollout that shows the component's properties (i.e. API attributes). .. _AddButton: .. image:: /content/images/ext_physics-property_window_add.png :alt: Property Window Add Button You may *remove* a component from a prim by clicking the red X that is shown with the component rollout: .. image:: /content/images/ext_physics-property_window_remove.png :alt: Property Window Remove Button A hint for editing numeric values: *Ctrl*-Click or double-click lets you edit the current value. If you want to reset values to their default, you can do so by clicking the blue square next to the value: .. image:: /content/images/ext_physics-reset_value_default.png :alt: Property Window Reset to Default .. _Tool Tips: Tool Tips ************** You can hover over the name of a property to reveal a tooltip with further information about a parameter: .. image:: /content/images/ext_physics-property_window_tooltip.png :alt: Property Window Attribute Tooltip .. _Physics Scene: Physics Scene ########################################## The Physics Scene holds simulation settings such as gravity. To create a scene, select **Create > Physics > Physics Scene**. Then, you can configure the scene settings in its property window. For details on the parameters, refer to their `tool tips`_. .. note:: - The extension creates a temporary default scene if simulation objects are detected but a physics scene is missing. You may disable this behavior in the `Physics Preferences`_. - Often it makes sense to create physics objects such as a scene in their own USD layer. Multiple Scenes **************************** Multiple simulation scenes are supported. Each simulation actor, like a rigid body does have a simulationOwner relationship that defines where the actor is simulated. If empty, the first scene found during traversal is used. Multiple simulationOwners can be set for an actor: - For dynamic rigid body, the first simulationOwner rel owns that body and is simulated there as a dynamic body. The rest of the simulationOwners get a mirror of that body. That body is moved as a kinematic body. - For static rigid body all bodies are mirrored into each simulationOwner scene. .. note:: - Actors in different scenes do not interact with each other. Scene Stepping **************************** Physics stepping is determined by several variables. Scene is always stepped with a fixed time step. This is defined on a physics scene primitive - Time Steps Per Second (60 default). However the time provided by the update loop is variable (can be set to fixed in rendering properties). So physics is doing substeps to simulate the given variable delta time. The number of steps is determined from the given variable delta time, the time steps per second on a physics scene and min frame rate setting defined in Physics settings (Window->Simulation->Settings). The required number of steps is equal to the delta time multiplied by the time steps per seconds. However, if the delta would be large, the number of steps would continue to grow. In order to prevent this, the min frame rate does limit the maximum number of steps. Maximum number of step equals to time steps per second divided by the min frame rate. As an example, if the time steps per second is 60, the min frame rate is 30, then the maximum number of steps is two and for any delta that is larger then 1/30 only two substeps are done, with a fixed 1/60 step. .. _PhysicsMaterials: Physics Materials ######################### Materials defining properties of physics objects can be created with **Create > Physics > Physics Material** or added to an already existing Material prim through the **Add > Physics** menu. A physics material can be assigned to a physics object in the *Physics Materials on Selected Models* rollout in the Property window, which binds the material to the prim with the 'physics' purpose. Physics materials follow the same `resolution logic `_ as render materials as they are both based on the same `Material `_ prim type. One may define both render and physics properties on the same Material prim (e.g. to combine the visual and physical properties of rubber in a single material prim) and assign it in the "Materials on selected models" rollout. Another option is to bind a material to the *Physics Scene* prim in the *Physics default material* rollout, and this material is used as a default when a physics object does not have a physics material bound to it after USD material resolve. Note that multiple physics material types (Rigid/Deformable/PBD Particle) can be added to the same material prim, so that the material bound to the *Physics Scene* can define defaults for all physics object types. When parsing physics material properties of a prim the priority is then as follows: 1. Material binding with a 'physics' purpose (physics material). 2. Material binding with no purpose (render material). 3. Material binding with a 'physics' purpose on the *Physics Scene* prim. 4. Default values of material properties. .. _Physics Settings: Physics Settings ###################### Physics Settings are per-stage settings saved in USD metadata. You can view and change them through **Window > Simulation > Settings**. The Physics Settings window should be by default docked behind the Stage tab on the upper-right side. **Update** You can configure what data the simulation writes back to USD (analogous to editing operations). .. list-table:: :widths: 30 70 :header-rows: 0 * - Update to USD - Enables writing object transforms back to USD. Expert setting that should be left enabled. * - Update velocities to USD - Enables writing object velocities back to USD. If you do not need velocity information, you can disable the writeback to save some computational overhead. * - Output Velocities in Local space - Display velocities in local coordinate space. The simulation also expects user changes to velocities (like initial velocity of a body) to be in local/global space according to this setting. * - Update Force Sensors to USD - Enables writing articulation force sensor data back to USD. If you do not need data from sensors in the scene, you can disable the writeback to save some computational overhead. **Simulator** .. list-table:: :widths: 30 70 :header-rows: 0 * - Min Simulation Frame Rate - Sets the minimum simulation update rate in Hertz with respect to render-frame updates. In general, the Physics simulation runs in real (wall) time, so if rendering is slow, the simulation may take many steps at ``Time Steps Per Second`` to keep the Physics simulation state synchronized with wall time. This parameter limits how many steps the simulation may take to keep up synchronization. For example, if ``Min Simulation Frame Rate`` is 30Hz and the PhysicsScene ``Time Steps Per Second`` is 60 (Hz), the simulation takes at most two steps between render frame updates, no matter how long a frame render takes. This is a useful parameter when rendering a Physics scene to keep the simulation updates in lockstep with rendering: Just set ``Min Simulation Frame Rate`` equal to the ``Time Steps Per Second`` value. .. _MouseInteraction: **Mouse Interaction** .. list-table:: :widths: 30 70 :header-rows: 0 * - Mouse Interaction Enabled - Enables interaction with physics objects through shift-click *if the simulation is running*. For advanced physics-based authoring, refer to the `Zero Gravity <../../extensions/zero-gravity.html>`__ extension. * - Mouse Grab - Toggles between grabbing behavior (enabled) and applying a push (disabled). * - Mouse Grab With Force - Toggles between grabbing using a force (enabled) or using a D6 joint (disabled). Both the force and D6 are applied at the click (raycast) location. * - Mouse Grab Force Coefficient - Scales the force used for grabbing. The grabbing force is proportional to the mass of the grabbed object and multiplied with this parameter. * - Mouse Push Acceleration - Scales the push-acceleration applied to the object. .. _Physics Preferences: Physics Preferences ###################### Besides the physics scene and physics settings, the *Physics* tab in **Edit > Preferences** provides global simulation-related settings. **General** .. list-table:: :widths: 30 70 :header-rows: 0 * - Create Temporary Default PhysicsScene When Needed - Controls whether a scene is auto-created when you press Play and simulation objects are present but no PhysicsScene was added to the stage. * - Reset simulation on stop - If enabled, the state (i.e. transforms, velocities) of the simulation objects is reset to the initial state before Play was pressed. * - Use Active CUDA Context - If enabled, the PhysX simulation uses the currently active CUDA context for its GPU computations. If disabled, a new context is created for the simulation. * - Reset Physics Preferences - Use this button to reset the values of the Physics preferences here, and the :ref:`debug-visualization `. **Backward Compatibility** .. list-table:: :widths: 30 70 :header-rows: 0 * - Backward Compatibility Check on Scene Open - Configures the behavior of the physics USD backward compatibility module: In case of opening a scene with deprecated USD schema the extension can either ignore it, print out a warning to console, show a visual prompt to upgrade, or upgrade the scene automatically without prompting. * - Run Backwards Compatibility On Current Stage - Manually trigger a backwards compatibility check and update on current stage. * - Run Backwards Compatibility On Folder - Manually trigger a backwards compatibility check and update on a folder. **Simulator** .. list-table:: :widths: 30 70 :header-rows: 0 * - Num Simulation Threads - The number of simulation threads controls how many background threads are spawned and reserved for simulation. * - Use PhysX CPU Dispatcher - Use internal PhysX task scheduler instead of the default one. Can be more efficient for some scenes. * - Expose PhysX SDK Profiler Data - Adds PhysX SDK profiling zones to the Kit profiler. * - Release Physics Cooked Data - Deletes cooked data (i.e. pre-optimized simulation data for collision meshes, etc.) for all prims on the stage from USD, i.e. deletes the corresponding API and attributes holding the data. Forces re-cooking of the data (if the local mesh cache is cleared as well). **Local Mesh Cache** Enable, set the size of, and release the local (disk) mesh cache that stores results from collision mesh approximations and Physics data cooking for reuse with identical geometry. .. _usdunits: Units ###################### USD supports scaling of units through layer metadata that you may edit in the layer properties, see below. The default unit scaling for new stages can be set in the *Stage* tab of the *Preferences Window*. .. image:: /content/images/ext_physics-layer_metadata_units.png :alt: Layer Units Metadata The Physics extension scales default or auto-computed values by this metadata. For example, if *Meters Per Unit* is 0.01 (i.e. 1cm per unit), as you would set for assets that were authored at a centimeter-scale, the Physics extension sets the gravity magnitude of a newly created scene to 981.0 cm / s\ :sup:`2`. Any property value that you edit is assumed to be in the scale of the layer that it is authored in (see limitations in the note). .. note:: - Time is never scaled and is always in *seconds* (*Time Codes Per Second* is **not** considered for physics simulation). - Automatic reconciliation of unit-scales between different layers is currently not supported, so you must ensure that all layers are authored at the same scale. - In order to run simulations in engineering SI units (except angles), set all scaling to 1.0. Related, you may change the stage up-axis in the layer metadata from graphics-default Y-up to Z-up that is more common in engineering. - Angles are represented in degrees and cannot be set to radians. All physics parameters that refer to rotation are in degrees as well: For example an angular drive of a revolute joint has its stiffness defined in units of torque/degrees. .. _Physics Debug Window: Physics Debug Window ####################### The **Window > Simulation > Debug** window should be the first place to look when physics simulation is generating unexpected results. **Simulation Control** In addition to running and stopping, you can *Step* the simulation one time step at a time, so you can inspect problems that happen very quickly. **Simulation Overrides** You can manually perform updates from USD or release simulation objects, and override the CPU/GPU and solver settings of the PhysicsScene. **Simulation Debug Visualization** You can enable and configure a low-level visualizer that renders directly based on the |physx_short| engine's state, which is useful if for some reason the simulation is not in sync with USD. When you check the Enabled box, the different elements to visualize are presented. Note that data is only visualized *when the simulation is running*. The *Scale* field can be used to adjust the length of some lines and arrows. Note that some data like contact points are generated at the start of an update, and bodies are moved at the end of the update. Shapes are also drawn using their state at the start of an update so they line up with contact points. For this reason the visualization display may appear to lag one frame behind the graphics rendering. **Deformable Debug Visualization** Configure the options for :ref:`deformable bodies `. **Collision Mesh Debug Visualization** In addition to the wireframe debug visualization available in the :ref:`viewport show/hide menu `, you can visualize the collision-mesh approximations using solid render meshes. You may also inspect a convex decomposition using the explode-view distance. **PVD** Enable and configure PVD data logging by the `PhysX PVD logger `_, which can be helpful to inspect the PhysX simulation objects created from USD data. .. _Sleeping: Sleeping ####################### Sleeping is a mechanism in |physx_short| to save on computational resources when dynamic physics objects (e.g. rigid or deformable bodies) are not in motion and do not require simulation updates. If an object is not moving for a short time duration, it may go to sleep until it is woken up either by * the user when they set a property that causes the object to move again, for example applying a force on a rigid body or changing the target position of an articulation joint drive; * or the simulation when another object collides or interacts with the sleeping object, such that the sleeping object may move again. For the different dynamic object types, e.g. rigid bodies, articulations, or deformable bodies, you will find sleep-related properties such as a flag to have the rigid body start a simulation asleep, or the thresholds that |physx_short| uses to determine if an object is not moving and may be put to sleep. If you set those thresholds to zero, you can disable sleeping altogether on the object. .. note:: There is a subtle connection between sleeping and effective solver iterations (e.g. position and velocity iteration settings): In a GPU simulation, it is computationally efficient to apply the same number of iterations to all objects in the scene; and this number will be equal to the maximal iteration setting over all physics objects in the scene **that are not asleep**. Especially for deformable bodies whose dynamics can be affected when the effective iteration count changes, this is important to keep in mind: For example, if you have two deformable bodies with 20 and 40 iterations each in a scene and both are awake, the solver will apply 40 iterations to both. However, if the body with 40 iterations goes to sleep, the other body will only have 20 iterations applied to it, which may change its behavior. .. do not change SDF Collision title because link is used externally .. _sdfcollision: |physx_short| SDF Collision ########################### The Signed-Distance-Field (SDF) collision detection feature allows the simulation of dynamic and kinematic rigid bodies that use high-detail triangle meshes as their collision shape. Demos like *Nuts and Bolts* and *Chair Stacking* leverage the SDF feature to simulate the contact-rich interaction between dynamic objects of highly non-convex shape. SDFs can help to speed up collision detection between dynamic triangle meshes a lot and are a requirement for triangle mesh colliders on dynamic objects. The SDF is computed by |physx_short| on a uniform grid with a grid spacing equal to the mesh's longest AABB extent divided by an SDF Resolution attribute, see instructions below. How to Enable SDF Collision *************************** In the collision mesh Collider rollout, set the Approximation to *SDF Mesh* and set a nonzero SDF Resolution. Setting the SDF Resolution to zero disables SDF collision which is only supported for static colliders. SDFs use quite a bit of memory but help to accelerate the collision detection a lot. To reduce the memory consumption, it is recommended to use sparse SDFs where a lot of distance samples are stored near the triangle mesh's surface but fewer samples further away from the surface. Additionally, quantization of the distance values should be activated for sparse SDFs since this allows to further reduce the memory consumption while still being accurate enough in almost all cases. Quantization can be controlled by adjusting the SDF Bits per Subgrid Pixel in the Advanced section. Sparse SDFs and quantization are enabled by default. Dense SDFs are still available by setting the SDF Subgrid Resolution to zero in the Advanced section. .. image:: /content/images/ext_physics-preview_sdf-mesh-collider.png :alt: Enable SDF on Mesh Collider When you change the SDF resolution or start the simulation, |physx_short| will cook the SDF data which can take a couple of seconds up to a couple minutes for very high SDF resolutions combined with a complex mesh. It is not recommended to use exceedingly high resolutions, as it will waste resources. In most cases, resolutions of 250 already produce good results, resolutions higher than 1000 are very rarely used. It is usually better to split the mesh into multiple smaller parts when working with SDFs on big objects. Debug Visualization and Pre-Computation *************************************** You may inspect the generated SDF using debug visualization available in the `Physics Debug Window`_: .. image:: /content/images/ext_physics-preview_sdf-debug-viz.png :width: 900 :alt: Bolt SDF Debug Visualization After cooking, the generated SDF is stored into a cooked data API, so a subsequent simulation starts up faster, and you can save individual assets with their SDF data pre-computed (which is used in the demos to speedup startup time). .. note:: - SDF collision is currently not supported on static colliders; however, kinematic rigid bodies can be used instead. - Feedback is welcome for this new feature. - Multi-material triangle-mesh colliders are not supported with the SDF collision feature. - For more details, see the paper `Factory: Fast Contact for Robotic Assembly `_ .. _flatcache: |physx_short| Flatcache (also known as Fabric rename in next release) ######################################################################## The Flatcache feature enables bypassing USD to communicate |physx_short| simulation data to the rendering engine, which is more efficient and results in higher combined simulation and rendering performance. The feature currently only supports rigid bodies (excluding point instancer rigid bodies as well). You can enable and test the Flatcache feature as follows: #. Enable the extension *omni.physx.flatcache* #. Enable FPS display in the viewport show/hide menu (eye) *HUD Stats* #. Compare FPS in a scene with many rigid bodies (e.g. ~1k) with and without Flatcache enabled .. note:: - When the extension is enabled small window is displayed showing what the output of a simulation is (USD/Fabric). - Using Fabric means that the data are not available in USD. This will cause USD based functionality to not work. For example debug visualization of physics colliders wont work anymore, because the transformations are not synchronized. - Using a python script to update and get USD state wont work because USD does not have current transformation information. - If scene graph instancing is used together with Fabric, support for that in omni hydra has to be enabled. Enable omni.hydra.ui and enable the scene graph instancing using omni.hydra. Reload your stage.