diff --git a/Modules/Simulation/Documentation/doxygen/Manual.dox b/Modules/Simulation/Documentation/doxygen/Manual.dox index c4dce8f8dd..06b217c3af 100644 --- a/Modules/Simulation/Documentation/doxygen/Manual.dox +++ b/Modules/Simulation/Documentation/doxygen/Manual.dox @@ -1,142 +1,126 @@ /** \page SimulationManualPage The MITK Simulation Module The MITK simulation module provides medical simulation capabilities by integrating the Simulation Open Framework Architecture (SOFA) into MITK. \section SimulationManualBuildInstructions Build Instructions -Activate the %CMake option MITK_USE_SOFA to automatically download and build SOFA and the MITK simulation module during the superbuild process. -You can then activate depending simulation-related plugins during MITK build configuration, i.e. activate MITK_BUILD_org.mitk.simulation and MITK_BUILD_org.mitk.gui.qt.simulation options. +Activate the %CMake option MITK_USE_SOFA when configuring the MITK superbuild. +SOFA is automatically downloaded and built during the superbuild (as well as the MITK simulation module, which depends on SOFA). +Simulation-related plugins can be activated when configuring the MITK build, i.e. activate MITK_BUILD_org.mitk.gui.qt.simulation, which will automatically activate MITK_BUILD_org.mitk.simulation in turn. \subsection SimulationManualSOFAPluginBuildInstructions SOFA Plugins SOFA plugins are built automatically during the MITK superbuild if they are located in the right directory and contain a %CMake script to build them. SOFA build configuration is originally qmake-based. However, for seamless MITK superbuild integration a %CMake-based build script is used instead. After you activated the %CMake option MITK_USE_SOFA, SOFA complete with the %CMake-based build script is downloaded during the superbuild. -Following the MITK superbuild convention for external projects it is located in the SOFA-src directory right beneath the top-level MITK build directory. -Following the SOFA convention for plugins in turn, they should be located in applications/plugins. -Hence, create an applications/plugins directory beneath the SOFA-src directory and place your plugin here, i.e. SOFA-src/applications/plugins/myplugin. +Following the MITK superbuild convention for external projects, it is located in the SOFA-src directory right beneath the top-level MITK build directory. +Following the SOFA convention for plugins, they should be located in applications/plugins. +Hence, create an applications/plugins directory in SOFA-src and place your plugin here, i.e. SOFA-src/applications/plugins/myplugin. The second and last step is to create a CMakeLists.txt file inside your plugin directory. -Use the %CMake function add_sofa_library to easily set up your plugin build script. +Use the %CMake function add_sofa_library() to easily set up your plugin build script. Below is an example of a CMakeLists.txt file for a fictional plugin named "myplugin": -
+\code
 set(MYPLUGIN_SOURES
   Topologies/MyTopology.cpp
   MyInteraction.cpp
 )
 
 set(MYPLUGIN_LIBS
   sofa_base_topology
   sofa_user_interaction
 )
 
 add_sofa_library(myplugin NO_PREFIX)
-
+\endcode -Note that the naming of MYPLUGIN_SOURCES and MYPLUGIN_LIBS is crucial for add_sofa_library(myplugin) to find the sources and libraries. +The naming of MYPLUGIN_SOURCES and MYPLUGIN_LIBS is crucial for add_sofa_library(myplugin) to find the sources and libraries. For more information see SOFA-src/CMake/AddSOFALibrary.cmake. -Once your plugin is placed in the right directory and provides a CMakeLists.txt file it is found and built during the MITK superbuild. -The binaries of your plugin are generated together with all other SOFA binaries in the SOFA-build/bin directory. +Once your plugin is placed in the right directory and provides a CMakeLists.txt file it is built during the MITK superbuild. +Binaries of your plugin are placed in SOFA-build/bin. SOFA plugins can be loaded at runtime via the simulation preferences by clicking the Add... button. \image html SimulationPreferences.png The simulation preferences dialog box. \section SimulationManualIntroduction Introduction -It is strongly recommended that you are at least familiar with the basic concepts of SOFA before you proceed reading. - -SOFA is intended to be used as a framework by itself. It is split into the following three parts: +SOFA is split into the following three parts: -While the former two parts make up the actual framework, the latter part is built on top of them and provides end user applications, e.g. runSofa. -The MITK simulation module and plugins conceptionally substitute the application layer and make use of the framework and module layer in terms of a toolkit. +While the former two parts make up the actual framework functionality, the applications part provides end user applications, e.g. runSofa. +The MITK simulation module and plugins replace the applications part of SOFA and make use of the framework and modules parts in terms of a toolkit. +\image html SOFA_MITK.png Conceptional layers and dependencies of SOFA and the MITK simulation module. +\remark While the framework and modules parts of SOFA are LGPL-licensed, the applications part, which is not used by MITK, is GPL-licensed. -\section SimulationManualHowToUpdate How to update SOFA +\section SimulationManualHowToUpdate How to supply SOFA to the MITK Superbuild -SOFA is deployed to the MITK superbuild in three ZIP archives, namely +\remark If you are not a member of the MITK staff you can safely skip this section. - +SOFA build configuration is originally qmake-based. However, for seamless MITK superbuild integration a %CMake-based build script is used instead. +To maintain this script and to ensure that it matches the right revision of SOFA we set up a Git repository at %git\@mitk.org:MITK-SOFA. -where [rev] is a substitute for the SVN revision of SOFA, e.g. 8935. -The follwing process was proven suitable to create these ZIP archives out of a certain SOFA revision. -Since it is a very time-consuming task you should only update SOFA if it is really necessary! - -
    -
  1. Follow the instructions of the SOFA framework download website to check out a recent revsion of the trunk form their SVN server into a newly created directory named SOFA-svn (check the dashboard first to see if that revision is likely to compile properly on all supported platforms). -
  2. To get rid of all SVN files in the source directory use SVN export to export the source code to a separate directory named SOFA-rev[rev]. -
  3. Delete all irrelevant directories and files in SOFA-rev[rev]. Relevant directories and files are: - -
  4. Create sofa-rev[rev].zip out of the SOFA-rev[rev] directory. -
  5. Download the old sofa-rev[old_rev].zip and extract it to SOFA-rev[old_rev]. -
  6. Download the old sofa-rev[old_rev]-cmake.zip and extract it to SOFA-CMake. -
  7. Download the old sofa-rev[old_rev]-gl.zip and extract it to SOFA-GL. -
  8. Download a directory diff tool like DirDiff for Windows and compare sofa-rev[old_rev] with sofa_rev[rev] to get an overview of what has changed. Note that you have to look at the .pro files to see which files were added or removed to the projects. Just looking at the files in a project directory is not sufficient! -
  9. Adapt the CMake files in SOFA-CMake to the changes. -
  10. Copy SOFA-rev[rev] to SOFA-rev[rev]-Test and also copy SOFA-CMake and SOFA-GL into that directory. -
  11. Manually apply the patch for SOFA you find in the MITK source tree (MITK/CMakeExternals/PatchSOFA-rev[old_rev].cmake. -
  12. Try to build SOFA-rev[rev]-Test. Make changes to SOFA-CMake and SOFA-GL files (don't forget to reapply the patch or even change the patch if necessary) until you can build everything successfully. -
  13. Create sofa-rev[rev]-cmake.zip out of SOFA-CMake and sofa-rev[rev]-gl.zip out of SOFA-GL. -
  14. Upload all three ZIP archives to a easily accessible location like your public DropBox folder. -
  15. Update MITK/CMakeExternals/SOFA.cmake to point to the temporary locations and don't forget to update the MD5 hashes and to use an up-to-date patch file, i.e. PatchSOFA-rev[rev].cmake. -
  16. Try to build MITK. Repeat any of the above steps until you are able to compile and use MITK with SOFA on every supprted plattform. -
  17. Upload the new SOFA archives to mitk.org and adapt the URLs in MITK/CMakeExternals/SOFA.cmake. -
+When the repository was updated a package named SOFA_.tar.gz must be created and uploaded to %http://mitk.org/download/thirdparty/. + consists of the last eight digits of the SHA1 ID of the commit. +To use the new package for the MITK superbuild, the URL and MD5 of the package must be updated in CMakeExternals/SOFA.cmake. + +If you need to patch SOFA sources you must append your patch to CMakeExternals/PatchSOFA-rev.cmake. +Make sure that you keep the filename up to date regarding the revision of SOFA and update the filename for the patch command in CMakeExternals/SOFA.cmake too. + +The commit messages of the MITK-SOFA repository contain valuable information on which parts of SOFA must be stripped from a newly checked out revision. +Please continue writing detailed commit messages when updating the repository. + +Updating the repository to a new SOFA revision can be a time-consuming task. +The best way to keep track of changes and additions to the SOFA sources is to use a free folder comparing tool (e.g. dirdiff). +Especially look at .pro files which describe the individual SOFA projects. \section SimulationManualDrawing Drawing +It is recommended that you are at least familiar with the basic concepts of SOFA, e.g. scene graphs and visitors, before you proceed reading. + Drawing is done by SOFA at three different places: These cases are handled by the MITK Simulation Module as follows. \subsection SimulationManualDrawingVisualModel sofa::component::visualmodel One of the most important drawing classes is OglModel since it makes up most of the visual part of a simulation scene. It inherits from VisualModel (which encapsulates all API-independent drawing code) and contains OpenGL-related code to draw the visual model. To hook into the drawing of visual models, the MITK Simulation Module creates an alias in the SOFA object system so that every OglModel and VisualModel node found in a scene file is used to instantiate a MITK SimulationModel class instead. This class creates VTK actors that contain the visual model rather than drawing it directly. The simulation mapper, which is responsible for drawing a simulation scene, utilizes the visitor mechanism of SOFA to collect all VTK actors of the scene tree and finally draws them. \subsection SimulationManualDrawingDrawToolGL sofa::core::visual::DrawTool The abstract class DrawTool and its default OpenGL implementation DrawToolGL provide the interface to draw basic primitives, e.g. points, lines, spheres, arrows, and so forth. It is usually set by a call to sofa::core::visual::VisualParams::defaultInstance()->drawTool() at application initialization. The MITK Simulation Module provide its own VTK-based implementation of DrawTool, namely SimulationDrawTool. This class creates VTK actors instead of drawing anything directly. There is one SimulationDrawTool per simulation scene and the simulation mapper draws all current VTK actors according to which simulation scene is drawn. \subsection SimulationManualDrawingGL sofa::helper::gl Classes and functions in this namespace are problematic since they don't support the SOFA object system and therefore cannot be easily replaced by own implementations. Currently they are not handled by MITK at all and an OpenGL stub is injected into SOFA so that all draw related methods and functions in this namespace do practically nothing. This stub is automatically downloaded during the MITK superbuild process (sofa-rev[rev]-gl.zip). However, a patch is additionally applied by the superbuild script to SOFA which alters a few header files to include the stub header files instead of the original OpenGL/GLUT/GLEW ones. */ \ No newline at end of file diff --git a/Modules/Simulation/Documentation/doxygen/SOFA_MITK.png b/Modules/Simulation/Documentation/doxygen/SOFA_MITK.png new file mode 100644 index 0000000000..e2b4acf44e Binary files /dev/null and b/Modules/Simulation/Documentation/doxygen/SOFA_MITK.png differ