The Graphic User Interface in SOFA

I) An overview of the GUI
II) Structure
III) Viewers
IV) QtOgreViewer

1. An Overview of the GUI
   The main program is divided in two main parts, a rendering window and a control panel. A slider between them sets their dimension.

Common Interactions:

1. ANIM: launch the Simulation. The text field, DTsets the step of time used during the simulation.

2. STEP: the simulation will compute its state at the time: t+DT.

3. Reset Scene: reset the Simulation to the initial time, t=0.

4. Reset View: set your camera at initial configuration found in a view file, or default configuration.

5. Save View: keep in memory the position and orientation of the camera, for the next time you will load the scene.

6. Save Screenshot: take a picture of the current scene.

7. Direct interaction with the scene is possible. To do so, maintain SHIFT button pressed and click on a collision model present in the scene; A Pick Interactor will be created, and attached to the picked collision model, if any, with a spring.

   If you release the mouse button first, the spring is removed.

   If you release the SHIFT button first, the spring is fixed and exists until you pick another point in the scene.

8. Several tabs give more information about the current scene:
   This images were taken for the scene shown above.

   - depending on the viewer, you can control what is displayed, and the way it is.
   - statistical outputs during the simulation (position and velocity for each elements, time passed at each branch of the graph, gnuplot files)
   - the graph of the scene, with all the nodes. You can export this graph into a nice png file.
   - the last tab, Viewer gives the name and information about the possibilities of the current viewer, and the shortcuts.
   Double clicking on a node allows you to modify several values and change dynamically the simulation (here, the TetrahedronFEMForceField node). In some cases, you need to press the `update` button to apply the changes.

2. Structure
   The main interface uses a Qt environment (Qt3.3 for Linux and Qt4 for Windows). The Main window, providing all the interactions possible with the simulation,was created using QtDesigner. The RealGUI contains the viewer which can be selected directly in the main window. The possible choices depends on the configuration file, `sofa-default.cfg`.

   The RealGUI gets a pointer to the root of the scene graph, and controls the application by calling class `sofa::simulation::tree:Simulation`.

   The RealGUI uses an internal timer to repeatedly call method `sofa::simulation::tree:Simulation::animate(GNode* root, double dt)` and then update the viewer.

   To select the viewers:

   sofa-default.cfg located in your Sofa main directory allows to define what kind of viewer you are willing to have.
   By commenting (adding a# in front of the line) or uncommenting (removing the #) lines, you can allow multiple kind of viewer.
   For example, if you want to have the choice to render the scene with QtGLViewer and QtOgreViewer, just modify sofa-default.cfg as below:
   # DEFINES += SOFA_GUI_QT
   DEFINES += SOFA_GUI_QTOGREVIEWER
   DEFINES += SOFA_GUI_QGLVIEWER
   Then, in the main window, you select the kind of viewer you want. Qt will appear in gray, whereas QGLViewer and Ogre will be available.
   Warning, you must reload the scene when this change is made!

3. Viewers

The Viewers available now are:

1. QtViewer: uses openGL, derives a QGLWidget in order to be embedded within Qt. This class will probably not be maintained. Use QtGLViewer instead.

2. QtGLViewer: uses the library QGLViewer. Provides lots of functions to navigate through the scene.
   More information at QGLViewer Website.

3. QtOgreViewer: Embed Ogre within a Qwidget. Allows to get great visuals, through an intensive use of shaders, materials.
   Shadows are provided, but all the controls (show the mechanical objects, force fields...) are disabled.
   Warning: Ogre is not provided by Sofa, you have to previously install Ogre on your computer.
   The support works with Windows, Linux.
   - For Windows, the easiest way to proceed is to download and install the SDK.
   - For Linux, you have to compile from the source. If Ogre's library aren't installed in the default directory /usr/local/lib/Ogre then, you have to set the correct path in YourSofaDirectory/share/config/plugins_unix.cfg
   To get it: Ogre Website

4. QtOgreViewer

   To use this viewer, you must have Ogre installed on your computer.
   The configuration files are located in: YourSofaDirectory/share/config/. plugins.cfg describes the plugins used by Ogre for Windows, and plugins_unix.cfg for... Linux.
   By creating a .scene file with the same name as the simulation, you can provide additional models, lights, visuals to the simulation( see Ogre documentation for mode details ). This won't interact with Sofa, but allows you to get a better render.

   Additional textures, materials, shaders... in Ogre, have to be put in YourSofaDirectory/share/textures or YourSofaDirectory/share/materials or YourSofaDirectory/share/shaders ... They are loaded at the start-up of the viewer.