doc/salome/tui/SMESH/sources/static/PluginMeshers.html

   1 <!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en">
   2 <html>
   3 <head>
   4
   5   <meta http-equiv="Content-Type"
   6  content="text/html; charset=iso-8859-1">
   7
   8   <meta name="GENERATOR"
   9  content="Mozilla/4.79 [en] (X11; U; SunOS 5.6 sun4u) [Netscape]">
  10   <title>Main Page</title>
  11
  12   <link href="doxygen.css" rel="stylesheet" type="text/css">
  13 </head>
  14   <body>
  15  &nbsp;
  16 <center>
  17 <table width="96%">
  18  <tbody>
  19     <tr>
  20  <td>
  21       <h1> <a href="http://www.opencascade.com"><img
  22  src="sources/logocorp.gif" border="0" height="46" width="122"
  23  align="left">
  24       </a></h1>
  25  </td>
  26   <td>
  27       <div align="right"><a href="http://www.opencascade.org/SALOME/"><img
  28  src="sources/application.gif" border="0" height="46" width="108"
  29  align="right">
  30       </a></div>
  31  </td>
  32  </tr>
  33
  34   </tbody>
  35 </table>
  36 </center>
  37
  38 <center>
  39 <h1> <a name="page2"></a>How to add your own mesher</h1>
  40 </center>
  41
  42 <center>
  43 <h1> (as a set of hypotheses and algorithms)</h1>
  44 </center>
  45
  46 <center>
  47 <h1> to the application.</h1>
  48 </center>
  49
  50 <h2> <a name="cont"></a>Table of contents</h2>
  51
  52 <ul>
  53  <li> <b><i><a href="#1">1. Introduction</a></i></b></li>
  54   <li> <b><i><a href="#2">2. Implementation steps</a></i></b></li>
  55
  56   <ul>
  57  <li> <b><i><a href="#2_1">2.1. Mesher plugin package</a></i></b></li>
  58     <li>     <b><i><a href="#2_2">2.2. List of available hypotheses and algorithms</a></i></b></li>
  59   <li> <b><i><a href="#2_3">2.3. Build server plugin library</a></i></b></li>
  60
  61     <ul>
  62  <li> <b><i><a href="#2_3_1">2.3.1. Define interface to your hypotheses and
  63 algorithms</a></i></b></li>
  64   <li> <b><i><a href="#2_3_2">2.3.2. Implement functionality of your hypotheses
  65 and algorithms</a></i></b></li>
  66   <li> <b><i><a href="#2_3_3">2.3.3. Implement interface to your hypotheses
  67 and algorithms</a></i></b></li>
  68   <li> <b><i><a href="#2_3_4">2.3.4. Implement being exported method</a></i></b></li>
  69
  70     </ul>
  71   <li> <b><i><a href="#2_4">2.4. Build client (GUI) plugin library</a></i></b></li>
  72
  73     <ul>
  74  <li> <b><i><a href="#2_4_1">2.4.1. Implement the required GUI</a></i></b></li>
  75   <li> <b><i><a href="#2_4_2">2.4.2. Provide icons and messages for your
  76 GUI</a></i></b></li>
  77   <li> <b><i><a href="#2_4_3">2.4.3. Implement your hypotheses creator and
  78 being exported method</a></i></b></li>
  79
  80     </ul>
  81   <li> <b><i><a href="#2_5">2.5. Provide icons for Object Browser</a></i></b></li>
  82     <li> <b><i><a href="#2_6">2.6. Setup SALOME environment</a></i></b></li>
  83     <ul type="square">
  84       <li><b><i><a href="#2_6_1">2.6.1. Set LD_LIBRARY_PATH, PYTHONPATH,
  85 PATH environment variables</a></i></b></li>
  86       <li><b><i><a href="#2_6_2">2.6.2. Set mesher plugin resources environment
  87 variable</a><br>
  88         </i></b></li>
  89     </ul>
  90   </ul>
  91 </ul>
  92
  93 <h2> <a name="1"></a>1. Introduction</h2>
  94  All hypotheses and algorithms are available in SMESH module via plugin mechanism.
  95 Such approach allows easily to introduce new hypotheses and algorithms types
  96 to the application. Also, it makes possible the customization of available
  97 hypotheses and algorithms list for different users without recompilation
  98 of sources.<br>
  99 The goal of this document is to describe the process of creation external
 100 mesher plugins.
 101 <p><i><a href="#cont">Back to the contents</a></i> </p>
 102 <h2> <a name="2"></a>2. Implementation steps</h2>
 103
 104 <h3>
 105 <h3> <a name="2_1"></a>2.1. <small>Mesher plugin package</small></h3>
 106 </h3>
 107 Create your mesher plugin package which will contain the sources files, e.g.
 108 &nbsp;MyMesherPlugin.<br>
 109 <br>
 110 <i><a
 111  href="file:///home/vsr-local/work/SALOME/SALOME2/SMESH_SRC/doc/salome/tui/SMESH/sources/static/PluginMeshers.html#cont">Back
 112 to the contents</a></i><br>
 113 <h3><a name="2_2"></a>2.2. List of available hypotheses and algorithms</h3>
 114 Create XML file to describe all algorithms and hypotheses, provided by your
 115 plugin package (see SMESH_SRC/resources/SMESH_Meshers.xml for example).<br>
 116 <blockquote><small><tt><big>&lt;meshers-group name="MyName"<br>
 117 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;resources="MyResourceKey"<br>
 118 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
 119 server-lib="libMyServerLib.so"<br>
 120 &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;gui-lib="libMyClientLib.so"&gt;<br>
 121 &nbsp; &nbsp; &nbsp;&lt;hypotheses&gt;<br>
 122 &nbsp;&nbsp;&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;&lt;hypothesis type="MyHypType1"<br>
 123 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;
 124 &nbsp;&nbsp;&nbsp; label-id="My beautiful hypothesis name"<br>
 125 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
 126 &nbsp;&nbsp; icon-id="my_hypo_1_icon.png"/&gt;<br>
 127 &nbsp;&nbsp;&nbsp; &nbsp; &nbsp;&nbsp;&nbsp; &lt;/hypotheses&gt;<br>
 128 &nbsp;&nbsp;&nbsp;&nbsp; &lt;algorithms&gt;<br>
 129 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &lt;algorithm type="MyAlgType1"<br>
 130 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;
 131 &nbsp;&nbsp;&nbsp; &nbsp;label-id="My beautiful algorithm name"<br>
 132 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp; &nbsp; &nbsp;&nbsp;&nbsp;&nbsp;
 133 &nbsp;&nbsp;&nbsp; icon-id="my_algo_1_icon.png"/&gt;<br>
 134 &nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp; &lt;/algorithms&gt;<br>
 135 &lt;/meshers-group&gt;<br>
 136   </big></tt></small><br>
 137
 138   <ul>
 139     <li>Attributes of &lt;meshers-group&gt; tag:</li>
 140   </ul>
 141   <blockquote>
 142     <ul type="circle">
 143       <li>value of &lt;name&gt; attribute is used to collect hypotheses/algoritms
 144 in groups; you can also use this attribute for short description of your
 145 mesher plugin.</li>
 146       <li>value of &lt;resources&gt; attribute (MyResourceKey) is used to
 147 access resources (messages and icons) from GUI (see paragraphs <a
 148  href="#2_4_2">2.4.2</a> and <a href="#2_5">2.5</a>); in the current implementation
 149 it should coincide with the name of plugin package; this limitation will
 150 be eliminated in the further development.</li>
 151       <li>value of &lt;server-lib&gt; attribute describes the name of your
 152 mesher's server plugin library (See paragraph <a href="#2_3">2.3</a>)</li>
 153       <li>value of &lt;gui-lib&gt; attribute describes the name of your mesher's
 154 client plugin library (See paragraph <a href="#2_4">2.4</a>)</li>
 155     </ul>
 156   </blockquote>
 157   <ul>
 158     <li>Attributes of &lt;hypothesis/algorithm&gt; tag:</li>
 159   </ul>
 160   <blockquote>
 161     <ul type="circle">
 162       <li>value of &lt;type&gt; attribute is an unique name of the hypothesis/algorithm</li>
 163     </ul>
 164     <ul type="circle">
 165       <ul type="square">
 166         <li>It is a value of _name field of your hypothesis class (see paragraph
 167           <a href="#2_3">2.3</a>, implementation of constructor of StdMeshers_LocalLength
 168 class: _name = "LocalLength")</li>
 169         <li>It is a key to each certain hypothesis class (see paragraph <a
 170  href="#2_3">2.3</a>, implementation of "GetHypothesisCreator()" method in
 171 StdMeshers_i.cxx)</li>
 172         <li>It is a key to each certain hypothesis GUI (see paragraph <a
 173  href="#2_4">2.4</a>, implementation of "StdMeshersGUI_HypothesisCreator::CreateHypothesis()"
 174 and "StdMeshersGUI_HypothesisCreator::EditHypothesis()" methods in StdMeshersGUI.cxx)</li>
 175         <li>It is a key to each certain hypothesis icon in Object Browser
 176 (see paragraph <a href="#2_4_2_1">2.4.2.1</a>)</li>
 177       </ul>
 178     </ul>
 179   </blockquote>
 180   <blockquote>
 181     <ul type="circle">
 182       <li>value of &lt;label-id&gt; attribute is displayed in the GUI in
 183 the list of available hypotheses/algorithms ("Create Hypothesis/Algorithm"
 184 dialog)</li>
 185       <li>value of &lt;icon-id&gt; attribute is a name of icon file, which
 186 is displayed in GUI in the list of available hypotheses/algorithms ("Create
 187 Hypothesis/Algorithm" dialog)</li>
 188     </ul>
 189   </blockquote>
 190 Note: All attributes values are accessible in your GUI via HypothesisData
 191 class (see paragraph <a href="#2_4_1">2.4.1</a>)<br>
 192   <br>
 193 Note: The environment variable SMESH_MeshersList contains the list of plugins
 194 names, separated by colon (":") symbol, e.g.:<br>
 195   <br>
 196   <tt>&nbsp;&nbsp;&nbsp; setenv SMESH_MeshersList StdMeshers:NETGENPlugin</tt><br>
 197   <br>
 198 Please, pay attention that StdMeshers should also be included into this environment
 199 variable, if you want to use standard hypotheses/algorithms, provided with
 200 SMESH module.<br>
 201   <br>
 202 The SALOME automatically locates XML files, searching them in the following
 203 directories:<br>
 204   <tt><br>
 205 &nbsp;&nbsp;&nbsp; ${&lt;PLUGINNAME&gt;_ROOT_DIR}/share/salome/resources<br>
 206 &nbsp;&nbsp;&nbsp; ${SALOME_&lt;PluginName&gt;Resources}<br>
 207 &nbsp;&nbsp;&nbsp; ${HOME}/.salome/resources<br>
 208 &nbsp;&nbsp;&nbsp; ${KERNEL_ROOT_DIR}/share/salome/resources</tt><br>
 209   <br>
 210 where &lt;PluginName&gt; is a name of each mesher plugin package<br>
 211 </blockquote>
 212 <i><a href="#cont">Back to the contents</a></i>
 213 <h3> <a name="2_3"></a>2.3. Build server plugin library &lt;libMyServerLib.so&gt;.</h3>
 214
 215 <h4> <a name="2_3_1"></a>2.3.1. Define interface to your hypotheses and algorithms.</h4>
 216
 217 <blockquote><tt>Example: SMESH_SRC/idl/SMESH_BasicHypothesis.idl<br>
 218 &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NETGENPLUGIN_SRC/src/NETGENPlugin_Algorithm.idl<br>
 219   </tt><tt></tt></blockquote>
 220
 221 <h4> <a name="2_3_2"></a>2.3.2. Implement functionality of your hypotheses
 222 and algorithms.</h4>
 223
 224 <blockquote>Inherit corresponding classes from SMESH.
 225   <p><tt>Example: SMESH_SRC/src/StdMeshers/StdMeshers_*<br>
 226 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NETGENPLUGIN_SRC/src/NETGENPlugin_NETGEN_3D<br>
 227   </tt><tt></tt></p>
 228 </blockquote>
 229
 230 <h4> <a name="2_3_3"></a>2.3.3.Implement interface to your hypotheses and
 231 algorithms.</h4>
 232
 233 <blockquote><tt>Inherit corresponding classes from SMESH_I.</tt>
 234   <p><tt>Example: SMESH_SRC/src/StdMeshers_I/SMESH_*_i<br>
 235 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NETGENPLUGIN_SRC/src/NETGENPlugin_NETGEN_3D_i<br>
 236   </tt><tt></tt></p>
 237 </blockquote>
 238
 239 <h4> <a name="2_3_4"></a>2.3.4. Implement being exported method.</h4>
 240
 241 <blockquote><tt>GenericHypothesisCreator_i* GetHypothesisCreator (const char*
 242 aHypType)</tt>
 243   <p>&lt;aHypType&gt; is a value of &lt;type&gt; attribute in the XML-description
 244 file</p>
 245 </blockquote>
 246
 247 <blockquote><tt>Example: SMESH_SRC/src/StdMeshers_I/StdMeshers_i.cxx<br>
 248 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NETGENPLUGIN_SRC/src/NETGENPlugin_i.cxx<br>
 249   </tt><tt></tt></blockquote>
 250  <i><a href="#cont">Back to the contents</a></i>
 251 <h3> <a name="2_4"></a>2.4. Build client (GUI) plugin library &lt;libMyClientLib.so&gt;.</h3>
 252
 253 <blockquote>This step is required only if your hypotheses/algorithms need
 254 specific GUI for their construction.</blockquote>
 255
 256 <h4> <a name="2_4_1"></a>2.4.1. Implement the required GUI (e.g. construction
 257 dialog boxes).</h4>
 258
 259 <blockquote><tt>Example: SMESH_SRC/src/StdMeshersGUI/StdMeshersGUI_*Dlg</tt>
 260   <p>Note: all data from XML-description files is accessible in your GUI
 261 via HypothesisData class&nbsp; (mySMESHGUI-&gt;GetHypothesisData (aHypType),
 262 see SMESHGUI_Hypotheses.h for HypothesisData definition)</p>
 263 </blockquote>
 264
 265 <h4> <a name="2_4_2"></a>2.4.2. Provide icons and messages for your GUI.</h4>
 266
 267 <h5> <a name="2_4_2_1"></a>2.4.2.1. Implement resource files</h5>
 268
 269 <blockquote><tt>MyResourceKey_icons.po and MyResourceKey_msg_en.po</tt>
 270   <p><tt>Example: SMESH_SRC/src/StdMeshersGUI/StdMeshers_*.po<br>
 271 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; NETGENPLUGIN_SRC/src/NETGENPlugin_icons.po<br>
 272   </tt><br>
 273 Note: ICON_SMESH_TREE_HYPO_MyHypType1 is ID of icon for Object Browser for
 274 hypothesis with type="MyHypType1"; ICON_SMESH_TREE_ALGO_MyAlgType1 is ID
 275 of icon for Object Browser for algorithm with type="MyAlgType1".<br>
 276 See paragraph 2 for definition of MyResourceKey, MyHypType1, MyAlgType1.<tt><br>
 277   </tt></p>
 278 </blockquote>
 279
 280 <h5> <a name="2_4_2_2"></a>2.4.2.2. Define environment variable SALOME_&lt;MyResourceKey&gt;Resources</h5>
 281 <blockquote>It should point to the directory where resources are situated.</blockquote>
 282
 283 <blockquote><tt>Example: setenv SALOME_StdMeshersResources ${SMESH_ROOT_DIR}/share/salome/resources</tt></blockquote>
 284
 285 <h4> <a name="2_4_3"></a>2.4.3. Implement your Hypothesis Creator and being
 286 exported method</h4>
 287
 288 <blockquote><tt>SMESHGUI_GenericHypothesisCreator* GetHypothesisCreator</tt>
 289   <br>
 290   <tt>&nbsp; (QString aHypType, QString aServerLibName, SMESHGUI* aSMESHGUI)</tt>
 291   <p>&lt;aHypType&gt; is to pass a value of &lt;type&gt; attribute in XML-description
 292 file;<br>
 293 &lt;aServerLibName&gt; is to pass a value of &lt;server-lib&gt; attribute
 294 in XML-description file. </p>
 295   <p><tt>Example: SMESH_SRC/src/StdMeshersGUI/StdMeshersGUI.cxx</tt></p>
 296 </blockquote>
 297  <i><a href="#cont">Back to the contents</a></i>
 298 <h3> <a name="2_5"></a>2.5. Provide icons for object browser.</h3>
 299
 300 <blockquote>If your hypotheses/algorithms do not need specific GUI, but you
 301 want to provide icons for object browser, see <a href="#2_4_2">2.4.2</a> paragrath.<br>
 302 </blockquote>
 303 <div align="left">
 304 <p><i><a
 305  href="file:///home/vsr-local/work/SALOME/SALOME2/SMESH_SRC/doc/salome/tui/SMESH/sources/static/PluginMeshers.html#cont">Back
 306 to the contents</a></i> </p>
 307 </div>
 308
 309 <h3> <a name="2_6"></a>2.6. Setup your SALOME environment.</h3>
 310
 311 <h4> <a name="2_6_1"></a>2.6.1.&nbsp; Add your plugin to the LD_LIBRARY_PATH,
 312 PYTHONPATH (and maybe PATH) environment variables.<br>
 313 </h4>
 314 <blockquote><tt>setenv PATH &lt;path-to-my-plugin&gt;/bin/salome:${PATH}<br>
 315 setenv LD_LIBRARY_PATH &lt;path-to-my-plugin&gt;/lib/salome:${LD_LIBRARY_PATH}<br>
 316 Setenv PYTHONPATH &lt;path-to-my-plugin&gt;/lib/python2.2/site-packages/salome:${PYTHONPATH}<br>
 317   </tt>&nbsp;&nbsp; <br>
 318 </blockquote>
 319 <h4> <a name="2_6_2"></a>2.6.2.&nbsp; Set mesher plugin resources environment
 320 variable</h4>
 321 <blockquote>&nbsp;This enviroment variable is used to set meshers plugins
 322 which should be loaded by SMESH module (see <a href="#2_4_2_2">2.4.2.2</a>
 323 paragraph). Add your plugin to this variable. All plugins are separated by
 324 colon (":") symbol.<br>
 325   <br>
 326 Note: If you use runSalome.py script from KERNEL package to launch SALOME,
 327 you may not to set environment variables, because this script sets them itself.
 328 All what you should do is to add &lt;plugin&gt; section to your ${HOME}/.salome/salome.launch
 329 file for SMESH module section:<br>
 330   <tt><br>
 331 ...<br>
 332 &lt;modules-list&gt;<br>
 333 &nbsp;&nbsp;&nbsp; ...<br>
 334 &nbsp;&nbsp;&nbsp; &lt;module name="SMESH"&gt;<br>
 335 &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &lt;plugin name="MyMesher"/&gt;<br>
 336 &nbsp;&nbsp;&nbsp; &lt;/module&gt;<br>
 337 &nbsp;&nbsp;&nbsp; ...<br>
 338 &lt;/modules-list&gt;<br>
 339 ...</tt><br>
 340 </blockquote>
 341 <i><a href="#cont">Back to the contents</a></i> <br>
 342 &nbsp; <br>
 343 </body>
 344 </html>