doc/salome/PluginMeshers.txt

   1 #######################################################################################
   2 # File   : PluginMeshers.txt
   3 # Author : Julia DOROVSKIKH
   4 # Module : SMESH
   5 # $Header$
   6 #######################################################################################
   7 #
   8 # How to add your own mesher (as a set of hypotheses and algorithms) to the application
   9 #
  10 #######################################################################################
  11
  12 1. Create mesher plugin package, e.g. MyMesher.
  13
  14 2. Create XML file to describe all algorithms and hypotheses, provided by plugin package
  15    (see SMESH_SRC/resources/SMESH_Meshers.xml for example).
  16
  17    <meshers-group name="MyName"
  18                   resources="MyResourceKey"
  19                   server-lib="libMyServerLib.so"
  20                   gui-lib="libMyClientLib.so">
  21      <hypotheses>
  22        <hypothesis type="MyHypType1"
  23                    label-id="My beautiful hypothesis name"
  24                    icon-id="my_hypo_1_icon.png"/>
  25      </hypotheses>
  26      <algorithms>
  27        <algorithm type="MyAlgType1"
  28                   label-id="My beautiful algorithm name"
  29                   icon-id="my_algo_1_icon.png"/>
  30      </algorithms>
  31    </meshers-group>
  32
  33    Attributes of <meshers-group> tag:
  34
  35         - value of <name> attribute is used to collect hypotheses/algoritms in groups;
  36           you can also use this attribute for short description of your mesher plugin
  37
  38         - value of <resources> attribute (MyResourceKey) is used to access resources
  39           (messages and icons) from GUI (see paragraphs 4.2 and 5);
  40           currently it should coincide with the name of plugin package; this limitation
  41           will be eliminated in the further development.
  42
  43         - value of <server-lib> attribute describes the name of your mesher's
  44           server plugin library (See paragraph 3)
  45
  46         - value of <gui-lib> attribute describes the name of your mesher's
  47           client plugin library (See paragraph 4)
  48
  49    Attributes of <hypothesis/algorithm> tag:
  50
  51         - value of <type> attribute is an unique name of the hypothesis/algorithm
  52
  53           * It is a value of _name field of your hypothesis class
  54             (see paragraph 3, implementation of constructor of
  55              StdMeshers_LocalLength class: _name = "LocalLength")
  56
  57           * It is a key to each certain hypothesis class
  58             (see paragraph 3, implementation of "GetHypothesisCreator()" method in StdMeshers_i.cxx)
  59
  60           * It is a key to each certain hypothesis GUI
  61             (see paragraph 4, implementation of "StdMeshersGUI_HypothesisCreator::CreateHypothesis()"
  62              and "StdMeshersGUI_HypothesisCreator::EditHypothesis()" methods in StdMeshersGUI.cxx)
  63
  64           * It is a key to each certain hypothesis icon in Object Browser
  65             (see paragraph 4.2.1)
  66
  67         - value of <label-id> attribute is displayed in the GUI in the list
  68           of available hypotheses/algorithms ("Create Hypothesis/Algorithm" dialog)
  69
  70         - value of <icon-id> attribute is a name of icon file, which is displayed in GUI
  71           in the list of available hypotheses/algorithms ("Create Hypothesis/Algorithm" dialog)
  72
  73    Note: All attributes values are accessible in your GUI via HypothesisData class
  74          (see paragraph 4.1)
  75
  76    Note: The environment variable SMESH_MeshersList contains the list of plugins names,
  77          separated by colon (":") symbol, e.g.:
  78
  79          setenv SMESH_MeshersList StdMeshers:NETGENPlugin
  80
  81          Please, pay attention that StdMeshers should also be included into this environment variable,
  82          if you want to use standard hypotheses/algorithms, provided with SMESH module.
  83
  84          The SALOME automatically locates XML files, searching them in the following directories:
  85
  86          ${<PLUGINNAME>_ROOT_DIR}/share/salome/resources
  87          ${SALOME_<PluginName>Resources}
  88          ${HOME}/.salome/resources
  89          ${KERNEL_ROOT_DIR}/share/salome/resources
  90
  91          where <PluginName> is a name of each mesher plugin package
  92
  93 3. Build server plugin library <libMyServerLib.so>.
  94
  95    3.1. Define interface to your hypotheses and algorithms.
  96
  97         Example: SMESH_SRC/idl/SMESH_BasicHypothesis.idl
  98                  NETGENPLUGIN_SRC/src/NETGENPlugin_Algorithm.idl
  99
 100    3.2. Implement functionality of your hypotheses and algorithms.
 101         Inherit corresponding classes from SMESH.
 102
 103         Example: SMESH_SRC/src/StdMeshers/StdMeshers_*
 104                  NETGENPLUGIN_SRC/src/NETGENPlugin_NETGEN_3D
 105
 106    3.3. Implement interface to your hypotheses and algorithms.
 107         Inherit corresponding classes from SMESH_I.
 108
 109         Example: SMESH_SRC/src/StdMeshers_I/SMESH_*_i
 110                  NETGENPLUGIN_SRC/src/NETGENPlugin_NETGEN_3D_i
 111
 112    3.4. Implement being exported method.
 113
 114         GenericHypothesisCreator_i* GetHypothesisCreator (const char* aHypType)
 115
 116         <aHypType> is a value of <type> attribute in the XML-description file
 117
 118         Example: SMESH_SRC/src/StdMeshers_I/StdMeshers_i.cxx
 119                  NETGENPLUGIN_SRC/src/NETGENPlugin_i.cxx
 120
 121 4. Build client (GUI) plugin library <libMyClientLib.so>.
 122    This step is required only if your hypotheses/algorithms need specific GUI for their construction.
 123
 124    4.1. Implement the required GUI (e.g. construction dialog boxes).
 125
 126         Example: SMESH_SRC/src/StdMeshersGUI/StdMeshersGUI_*Dlg
 127
 128         Note: all data from XML-description files is accessible in your GUI via HypothesisData class
 129               (mySMESHGUI->GetHypothesisData (aHypType),
 130               see SMESHGUI_Hypotheses.h for HypothesisData definition)
 131
 132    4.2. Provide icons and messages for your GUI.
 133
 134         4.2.1. Implement resource files
 135                MyResourceKey_icons.po and MyResourceKey_msg_en.po
 136
 137                Example: SMESH_SRC/src/StdMeshersGUI/StdMeshers_*.po
 138                         NETGENPLUGIN_SRC/src/NETGENPlugin_icons.po
 139
 140                Note: ICON_SMESH_TREE_HYPO_MyHypType1 is ID of icon for Object Browser
 141                      for hypothesis with type="MyHypType1".
 142
 143                      ICON_SMESH_TREE_ALGO_MyAlgType1 is ID of icon for Object Browser
 144                      for algorithm with type="MyAlgType1".
 145
 146                See paragraph 2 for definition of MyResourceKey, MyHypType1, MyAlgType1.
 147
 148         4.2.2. Define environment variable SALOME_<MyResourceKey>Resources to point to the
 149                directory where resources are situated.
 150
 151                Example: setenv SALOME_StdMeshersResources ${SMESH_ROOT_DIR}/share/salome/resources
 152
 153    4.3. Implement your Hypothesis Creator and being exported method
 154
 155         SMESHGUI_GenericHypothesisCreator* GetHypothesisCreator
 156           (QString aHypType, QString aServerLibName, SMESHGUI* aSMESHGUI)
 157
 158         <aHypType> is to pass a value of <type> attribute in XML-description file;
 159         <aServerLibName> is to pass a value of <server-lib> attribute in XML-description file.
 160
 161         Example: SMESH_SRC/src/StdMeshersGUI/StdMeshersGUI.cxx
 162
 163 5. If your hypotheses/algorithms do not need specific GUI,
 164    but you want to provide icons for object browser, see 4.2 paragrath
 165
 166 6. Setup your SALOME environment.
 167
 168    6.1. Add your plugin to the LD_LIBRARY_PATH, PYTHONPATH (and maybe PATH) environment variables, e.g.:
 169
 170       setenv PATH <path-to-my-plugin>/bin/salome:${PATH}
 171       setenv LD_LIBRARY_PATH <path-to-my-plugin>/lib/salome:${LD_LIBRARY_PATH}
 172       setenv PYTHONPATH <path-to-my-plugin>/lib/python2.2/site-packages/salome:${PYTHONPATH}
 173
 174    6.2. Set mesher plugin resources environment variable (see 4.2.2 paragraph)
 175
 176 Note: If you use runSalome.py script from KERNEL package to launch SALOME, you may not to set
 177       environment variables, because this script sets them itself. All what you should do is
 178       to add <plugin> section to your ${HOME}/.salome/salome.launch file for SMESH module section:
 179
 180       ...
 181       <modules-list>
 182           ...
 183           <module name="SMESH">
 184               <plugin name="MyMesher"/>
 185           </module>
 186           ...
 187       </modules-list>
 188       ...