SofaUnity - Principles - SOFA Scene Parsing

Sofa-Context Creation

To utilize the SOFA physics engine within Unity3D, the first essential step is to create a SofaContext object. This Unity3D GameObject acts as the root of the SOFA simulation, managing the simulation’s operations in the background. All other objects that are part of the SOFA simulation will be children of this root object. You can create the SofaContext object by using the top menu within SofaUnity or by right-clicking in the Hierarchy panel.

You can create the SofaContext object by using the top menu within Tools/SofaUnity or by right-clicking in the Hierarchy panel.

Sofa-Context Inspector

The Inspector of the SofaContext GameObject offers several key functionalities:

Gravity and Timestep Adjustment: Allows you to modify the gravity settings and the simulation timestep directly from the Inspector.
Message Handling: Provides options to enable a message handler, which lets you receive SOFA logs, including information, warnings, and errors.
Manual Simulation Control: Enables you to disable automatic simulation and use the step button to manually progress through the simulation.
Loading SOFA Scenes: Supports loading SOFA scene files in both .scn and Python formats.
SOFA Plugin Management: Includes a list of SOFA plugins that can be loaded. Important Note: Plugins must be selected before loading any scene that requires them.

When a SofaContext is created, it automatically generates a root SOFADAGNode and a default AnimationLoop GameObject, which are crucial for setting up and controlling the simulation environment.

Lastly, the Transform component of the Unity GameObject containing the SofaContext can be used to position and scale the SOFA frame (3D world) within the Unity 3D scene.

SOFA scene parsing

First approach to create a SOFA simulation scene inside Unity3D is to load an existing SOFA simulation scene. This is an XML file with .scn extension describing the graph architecture and the components.

First thing to do is always to create the SofaContext GameObject. Then, use the Load Scene button to import a scn file. Note that the gravity and timestep parameters will be overwritten by the values loaded from the scene file. But it is possible change those value again after the load.
Last thing important to notice is that Unity and Sofa have the X axis inverted. Thus to have the same view of the scene from Sofa and Unity, Scale “-1 1 1” should be applyed in the SofaContext.

Once loaded, every Node of the SOFA graph will be transposed as SofaDAGNode and the component into SofaUnity GameObjects.

SOFA components to SofaUnity GameObjects

Since the version 1.0 of SofaAPAPI-Unity3D several components from SOFA are mapped as Unity3D specialized GameObject. The others are created as SofaComponent generic GameObject. The generic implementation of SofaComponent only allows to interact with the SOFA component parameters. Those parameters correspond to the SOFA Data of a component. Whereas the component specialization allow to add more complexe behavior. Like for example the display of FEM or collision model. For more details, check section Scene Graph edition

Here is the list of Unity3D specific GameObject used to define SOFA simulation scene.component categories particularly handled in :

SofaAnimationLoop

his GameObject correspond to SOFA AnimationLoop. This is a key component in charge of ruling the simulation and the mechanical resolution system.
See the corresponding documentation on SOFA webiste: AnimationLoop

SofaCollisionModel

This GameObject correspond to type of collision element used in SOFA to compute primitive intersection. It is usually either Spheres, Triangle, Edges or Points. This component is directly linked to the SofaMesh.
See the corresponding documentation on SOFA webiste: IntersectionMethod

SofaConstraint

This GameObject will describe some constraint applyed to the current system. It is only there to help describing the simulation scene. It could be either projective or lagrange constraints.
check more information regarding constraint on SOFA webiste: Projective Constraint

SofaFEMForceField

SofaLoader

This GameObject is for the moment only used to display the type of mesh used. Several formats are handled in SOFA. The more known are: obj, vtk, stl or gmsh.

SofaMass

This GameObject correspond to the Mass component applied to this mesh. This component can be used to change the total mass of the object or its mass density.
More information regarding Mass can be found on SOFA webiste: Mass

SofaMass

SofaMechanicalMapping

This GameObject is used to inform if a mechanical mapping is used between different mesh object. The link to the input and ouput mesh will be displayed.
This is a particular mechanism of SOFA which is explained into details here: mappings

SofaMesh

This GameObject is one of the main component. It corresponds to the mesh used in used SOFA. This component will retrieve the number of points as well as their positions in 3D space but also the complete topology of the object.
This GameOject is the main container used to fill MeshFilter or other algorithms. More information regarding Topology can be found on SOFA webiste: topology

SofaSolver

This GameObject is used to inform which type of integration scheme is used as well as the linear solver used to resolve it.
More information regarding the mechanical system resolution can be fond on SOFA website in the Integration Schemes section and Linear Solvers section

SofaVisualModel

This GameObject is used to map SOFA output position from an OglModel/VisualModel to Unity3D rendering. A MeshFilter and a Mesh renderer will be created and linked to SOFA side.

SofaDAGNode scope

SOFA simulation is using a Directed Acyclic Graph concept to design hiearchy structures, similar to what can be seen in Unity3D Hierarchy panel. The GameObjects SofaDAGNode are used to retrieve this scene Node architecture.

It is highly advise to be familliar with the SOFA scene graph structure descrived here.

For example in the scene CollisionSimple. The root Node is embedded inside the GameObject SofaContext and the two others objects are identified by the SofaNode: Cube and Cylinder.

Finally, the SofaDAGNode inspector allows to see the number of components handled and allows also to translate, rotate and scale the object in the SOFA world.

Liver scene loaded inside Unity3D with the hiearchy display.

Same Liver scene loaded inside runSofa GUI..