SofaAPAPI-Unity3D Getting Started Features Available SOFA Scene Parsing Object Creation Scene Graph edition Examples Assets Available Release Notes License
     

SOFA simulation scene parsing

SofaContext creation

To be able to use SOFA physical engine inside Unity3D, the first step, whatever API method is used, is to create the object: SofaContext.
This is a Unity3D GameObject representing the SOFA simulation root object which will control the simulation in background. All other object to be simulated by SOFA will be child of this Root object.
This object can be created either using the top menu inside SofaUnity or directly by right clicking in the hierarchy panel.


Access to SofaContext from Top Menu.

Access to SofaContext from Hierarchy panel.

The inspector of the SofaContext GameObject allows to change the gravity in the scene as well as the simulation timestep.
It also allows to activate the message handler in order to get SOFA logs (info, warning and errors) and diseable the simulation if manual control is wanted using the button step.

Note that a root SOFADAGNode as well as a GameObject defaultAnimationLoop will be automatically created.
See next section for more details.


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 This 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 This GameObject will describe which type of FEM or forcefield is used on this mesh. This component is directly linked to the SofaMesh. If the FEM is using classic primitive like triangles, tetrahedra or edges, it can be possible to display its structure.
More information regarding FEM can be found on SOFA webiste: ForceField
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
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.

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.

Liver scene loaded inside Unity3D with the hiearchy display.
Same Liver scene loaded inside runSofa GUI.