\page constructing_meshes_page Constructing meshes
-\n Construction of a mesh consists of:
+\n Construction of a mesh on some geometry consists of:
<ul>
-<li>Selecting a geometrical object for meshing</li>
-<li>Applying \ref basic_meshing_algos_page "meshing algorithms" and
-\ref about_hypo_page "hypotheses" which will be used at computation of
-this mesh.</li>
+ <li> \ref create_mesh_anchor "Creating of a mesh object"</li>
+ <li> \ref evaluate_anchor "Evaluating mesh size" (optional)</li>
+ <li> \ref preview_anchor "Previewing the mesh" (optional)</li>
+ <li> \ref submesh_order_anchor "Changing sub-mesh priority" (optional)</li>
+ <li> \ref compute_anchor "Computing the mesh"</li>
+ <li> \ref edit_anchor "Editing the mesh" (optional)</li>
</ul>
+\anchor create_mesh_anchor
+<h2>Creation of a mesh object</h2>
<em>To construct a mesh:</em>
<ol>
-<li>In the \b Mesh menu select <b>Create Mesh</b> or click <em>"Create
-Mesh"</em> button in the toolbar.
+ <li>Select a geometrical object for meshing.</li>
+ <li>In the \b Mesh menu select <b>Create Mesh</b> or click <em>"Create
+ Mesh"</em> button in the toolbar.
-\image html image32.gif
-<center><em>"Create Mesh" button</em></center>
+ <center>
+ \image html image32.png
+ <em>"Create Mesh" button</em>
+ </center>
-The following dialog box will appear:
+ The following dialog box will appear:
-\image html createmesh-inv.png
-</li>
-<li>For example, you need to mesh a 3d object.
-\n First, type the name for your mesh in the "Name" box, by default,
-it is "Mesh_1". Then select the object you wish to mesh in the Object
-Browser and click the "Add" button.
+ \image html createmesh-inv.png
+ <br>
+ </li>
+ <li> To filter off irrelevant meshing algorithms, you can
+ select <b>Mesh Type</b> in the corresponding list from <b>Any,
+ Hexahedral, Tetrahedral, Triangular </b> and \b Quadrilateral (there
+ can be less items for the geometry of lower dimensions).
-\image html image120.gif
-<center><em>"Add" button</em></center>
+ Selection of a mesh type hides all meshing algorithms that cannot
+ generate elements of this type.</li>
-Now you can define 1d Algorithm and 1d Hypotheses, which will be
-applied to the edges of your object. (Note that any object has edges,
-even if their existence is not apparent, for example, a sphere has 4
-edges). Click the <em>"Add Hypothesis"</em> button to add a hypothesis.
+ <li>Apply \subpage basic_meshing_algos_page "meshing algorithms" and
+ \subpage about_hypo_page "hypotheses" which will be used to compute
+ this mesh.
-\image html image121.gif
-<center><em>"Add Hypothesis" button</em></center>
+ "Create mesh" dialog box contains several tab pages titled \b 3D,
+ \b 2D, \b 1D and \b 0D. The title of each page reflects the
+ dimension of the CAD model (geometry) the algorithms listed on
+ this page affect and the maximal dimension of elements the algorithms
+ generate. For example, \b 3D page lists the algorithms that affect
+ 3D geometrical objects (solids) and generate 3D mesh elements
+ (tetrahedra, hexahedra etc.)
-Click the <em>"Edit Hypothesis"</em> button to define values for the
-current hypothesis.
+ \note
+ - Some page(s) can be disabled if the source geometrical
+ object does not include shapes (sub-shapes) of the corresponding
+ dimension(s). For example, if the input object is a geometrical face,
+ \b 3D page is disabled.
+ - Some algorithms affect the geometry of several dimensions,
+ i.e. "1D-2D" or "1D-2D-3D". If such an algorithm is selected by the
+ user, the dialog box pages related to the corresponding lower level
+ dimensions are disabled.
+ - \b 0D page does not refer to the 0D elements, but to 0D
+ geometry (vertices). Mesh module does not provide algorithms that
+ produce 0D elements. Currently \b 0D page provides only one
+ algorithm "Segments around vertex" that allows specyfying the required
+ size of mesh edges about the selected vertex (or vertices).
-\image html image122.gif
-<center><em>"Edit Hypothesis" button</em></center>
+ For example, you need to mesh a 3D object.
-The use of additional hypotheses is optional (i.e. you may leave
-"None" in this box).
+ First, type the name of your mesh in the \b Name box, by default,
+ it is "Mesh_1". Then select the geometrical object you wish to
+ mesh in the Object Browser and click "Select" button near \b Geometry
+ field (if the name of the object has not yet appeared in \b Geometry field).
+ <center>
+ \image html image120.png
+ <em>"Select" button</em>
+ </center>
-Proceed in the same way with 2d and 3d Algorithms and Hypotheses, note
-that the choice of hypotheses depends on the algorithm. There must be
-one Algorithm and one or several Hypotheses for each dimension of your
-object, otherwise you will not get any mesh at all. Of course, if you
-wish to mesh a face, which is a 2d object, you don't need to define 3d
-Algorithm and Hypotheses.
-\n In the <b>Object Browser</b> the structure of the new mesh will be
-displayed as follows:
+ Now you can define 3D Algorithm and 3D Hypotheses, which will be
+ applied to the solids of your geometrical object. Click the <em>"Add
+ Hypothesis"</em> button to add a hypothesis.
+ <center>
+ \image html image121.png
+ <em>"Add Hypothesis" button</em>
+ </center>
+ Click the <em>"Plus"</em> button to enable adding more additional hypotheses.
-\image html image88.jpg
+ Click the <em>"Edit Hypothesis"</em> button to change the values for the
+ current hypothesis.
+ <center>
+ \image html image122.png
+ <em>"Edit Hypothesis" button</em>
+ </center>
-It contains:
+ Most 2D and 3D algorithms can work without hypotheses using
+ default meshing parameters. Some algorithms do not require any
+ hypotheses. After selection of an algorithm "Hypothesis" field of
+ the dialog can contain:
+ <ul>
+ <li> <em>\<Default\></em> if the algorithm can work using default
+ parameters.</li>
+ <li> <em>\<None\></em> if the algorithm requires a hypothesis defining
+ its parameters.</li>
+ <li> If the algorithm does not use hypotheses, this field is grayed.</li>
+ </ul>
+ After selection of an algorithm <b>Add. Hypothesis</b> field can contain:
+ <ul>
+ <li> <em>\<None\></em> if the algorithm can be tuned
+ using an additional hypothesis.</li>
+ <li> If the algorithm does not use additional hypotheses, this field is grayed.</li>
+ </ul>
+
+ Proceed in the same way with 2D and 1D Algorithms and Hypotheses that
+ will be used to mesh faces and edges of your geometry. (Note
+ that any object has edges, even if their existence is not
+ apparent, for example, a sphere has 4 edges). Note that the
+ choice of hypotheses and lower dimension algorithms depends on
+ the higher dimension algorithm.
+
+ If you wish you can select different algorithms and/or hypotheses
+ for meshing some parts of your CAD model by \ref constructing_submeshes_page.
+
+ Some algorithms generate mesh of several dimensions, while others
+ produce mesh of only one dimension. In the latter case there must
+ be one Algorithm and zero or several
+ Hypotheses for each dimension of your object, otherwise you will
+ not get any mesh at all. Of course, if you wish to mesh a face,
+ which is a 2D object, you do not need to define a 3D Algorithm and
+ Hypotheses.
+
+ In the <b>Object Browser</b> the structure of the new mesh will be
+ displayed as follows:
+
+ <center>
+ \image html image88.jpg
+ </center>
+
+ It contains:
+ <ul>
+ <li>a mesh name (<em>Mesh_mechanic</em>);
+ <li>a reference to the geometrical object on the basis of
+ which the mesh has been constructed (\a mechanic);</li>
+ <li><b>Applied hypotheses</b> folder containing the references
+ to the hypotheses applied at the construction of the mesh;</li>
+ <li><b>Applied algorithms</b> folder containing the references
+ to the algorithms applied at the construction of the mesh.</li>
+ </ul>
+
+ There is an alternative way to assign Algorithms and Hypotheses by
+ clicking <b>Assign a set of hypotheses</b> button and selecting among
+ pre-defined sets of hypotheses. In addition to the standard
+ sets of hypotheses, it is possible to create custom sets by editing
+ CustomMeshers.xml file located in the home directory. CustomMeshers.xml
+ file must describe sets of hypotheses in the
+ same way as ${SMESH_ROOT_DIR}/share/salome/resources/smesh/StdMeshers.xml
+ file does (sets of hypotheses are enclosed between <hypotheses-set-group>
+ tags).
+
+ \image html hypo_sets.png
+ List of sets of hypotheses. Tag <em>[custom]</em> is
+ automatically added to the sets defined by the user.
+
+ \note \a "Automatic" in the names of predefined sets of
+ hypotheses came from previous versions of SALOME where
+ \ref automatic_length_anchor "Automatic Length" hypothesis
+ was included in these sets, and not that these sets are suitable for
+ meshing any geometry.
+ </li>
+</ol>
+
+Consider trying a sample script for construction of a mesh from our
+\ref tui_creating_meshes_page "TUI Scripts" section.
+
+\anchor evaluate_anchor
+<h2>Evaluating mesh size</h2>
+
+After the mesh object is created and all hypotheses are assigned and
+before \ref compute_anchor "Compute" operation, it is possible to
+calculate the eventual mesh size. For this, select the mesh in
+the <b>Object Browser</b> and from the \b Mesh menu select \b
+Evaluate. The result of evaluation will be displayed in the following
+information box:
+
+\image html mesh_evaluation_succeed.png
+
+\anchor preview_anchor
+<h2>Previewing the mesh</h2>
+
+Before \ref compute_anchor "the mesh computation", it is also possible
+to see the mesh preview.
+
+For this, select the mesh in the Object Browser. From the \b Mesh menu
+select \b Preview or click "Preview" button in the toolbar or activate
+"Preview" item from the pop-up menu.
+
+<center>
+\image html mesh_precompute.png
+<em>"Preview" button</em>
+</center>
+
+Select <b>1D mesh</b> or <b>2D mesh</b> preview mode in the Preview dialog.
+
+\image html preview_mesh_1D.png "1D mesh preview shows nodes computed on geometry edges"
+<br>
+\image html preview_mesh_2D.png "2D mesh preview shows edge mesh elements, computed on geometry faces"
+
+<b>Compute</b> button computes the whole mesh.
+
+When the Preview dialog is closed, the question about the storage of temporarily
+created mesh elements appears:
+
+\image html preview_tmp_data.png
+
+These elements can be kept in the mesh.
+
+
+\anchor submesh_order_anchor
+<h2>Changing sub-mesh priority</h2>
+
+If the mesh contains concurrent \ref constructing_submeshes_page "sub-meshes",
+it is possible to change the priority of their computation, i.e. to
+change the priority of applying algorithms to the shared sub-shapes of
+the Mesh shape.
+
+<em>To change submesh priority:</em>
+
+Choose "Change submesh priority" from the Mesh menu or a pop-up
+menu. The opened dialog shows a list of submeshes in the order of
+their priority.
+
+There is an example of submesh order modifications taking a Mesh created on a Box
+shape. The main Mesh object:
+<ul>
+ <li><i>1D</i> <b>Wire discretisation</b> with <b>Number of Segments</b>=20</li>
+ <li><i>2D</i> <b>Triangle (Mefisto)</b> with Hypothesis<b>Max Element Area</b>
+ </li>
+</ul>
+The first submesh object <b>Submesh_1</b> created on <b>Face_1</b> is:
+<ul>
+ <li><i>1D</i> <b>Wire discretisation</b> with <b>Number of Segments</b>=4</li>
+ <li><i>2D</i> <b>Triangle (Mefisto)</b> with Hypothesis <b>MaxElementArea</b>=1200</li>
+</ul>
+The second submesh object <b>Submesh_2</b> created on <b>Face_2</b> is:
+<ul>
+ <li><i>1D</i> <b>Wire discretisation</b> with <b>Number of Segments</b>=8</li>
+ <li><i>2D</i> <b>Triangle (Mefisto)</b> with Hypothesis <b>MaxElementArea</b>=1200</li>
+</ul>
+
+And the last submesh object <b>Submesh_3</b> created on <b>Face_3</b> is:
<ul>
-<li>a reference to the geometrical object on the basis of which the mesh has been constructed;</li>
-<li><b>Applied hypotheses</b> folder containing the references to the
-hypotheses applied to the construction of the mesh;</li>
-<li><b>Applied algorithms</b> folder containing the references to the
-algorithms applied to the construction of the mesh.</li>
+ <li><i>1D</i> <b>Wire discretisation</b> with <b>Number of Segments</b>=12</li>
+ <li><i>2D</i> <b>Triangle (Mefisto)</b> with Hypothesis <b>MaxElementArea</b>=1200</li>
</ul>
-There is an alternative way to create a mesh on an object simply by
-clicking <b>Assign a set of hypotheses</b> button and selecting between
-Automatic Tetrahedralization or Hexahedralization. The program will
-automatically generate a 3D mesh with the most appropriate
-settings. In the same way you can apply this functionality for meshing
-2D objects, in which case 3D algorithms are not applied.</li>
-<li>Now, when everything is ready, select your mesh in the <b>Object
-Browser</b>. From the \b Mesh menu select \b Compute or click "Compute" button of the
-toolbar.
+The sub-meshes become concurrent if they share sub-shapes that can be
+meshed with different algorithms (or different hypotheses). In the
+example, we have three submeshes with concurrent algorithms, because
+they have different hypotheses.
+
+The first mesh computation is made with:
+<center>
+\image html mesh_order_123.png
+<em>"Mesh order SubMesh_1, SubMesh_2, SubMesh_3"</em></center>
+<center>
+\image html mesh_order_123_res.png
+<em>"Result mesh with order SubMesh_1, SubMesh_2, SubMesh_3 "</em></center>
+
+The next mesh computation is made with:
+<center>
+\image html mesh_order_213.png
+<em>"Mesh order SubMesh_2, SubMesh_1, SubMesh_3"</em></center>
+<center>
+\image html mesh_order_213_res.png
+<em>"Result mesh with order SubMesh_2, SubMesh_1, SubMesh_3 "</em></center>
+
+And the last mesh computation is made with:
+<center>
+\image html mesh_order_321.png
+<em>"Mesh order SubMesh_3, SubMesh_2, SubMesh_1"</em></center>
+<center>\image html mesh_order_321_res.png
+<em>"Result mesh with order SubMesh_3, SubMesh_2, SubMesh_1 "</em></center>
+
+As we can see, each mesh computation has a different number of result
+elements and a different mesh discretization on the shared edges (the edges
+that are shared between <b>Face_1</b>, <b>Face_2</b> and <b>Face_3</b>)
+
+Additionally, submesh priority (the order of applied algorithms) can
+be modified not only in a separate dialog box, but also in
+the <b>Preview</b>. This helps to preview different mesh results,
+modifying the order of submeshes.
+<center>
+\image html mesh_order_preview.png
+<em>"Preview with submesh priority list box"</em></center>
-\image html image28.gif
-<center><em>"Compute" button</em></center>
+If there are no concurrent submeshes under the Mesh object, the user
+will see the following information.
+<center>
+\image html mesh_order_no_concurrent.png
+<em>"No concurrent submeshes detected"</em></center>
-The Mesh Computation information box appears.
+
+\anchor compute_anchor
+<h2>Computing the mesh</h2>
+
+It is equally possible to skip \ref evaluate_anchor "the Evaluation"
+and \ref preview_anchor "the Preview" and to \b Compute the mesh after
+the hypotheses are assigned. For this, select your mesh in
+the <b>Object Browser</b>. From the \b Mesh menu select \b Compute or
+click "Compute" button of the toolbar.
+
+<center>
+\image html image28.png
+<em>"Compute" button</em>
+</center>
+
+After the mesh computation finishes, the Mesh Computation information
+box appears. In case of a success, the box shows
+information on number of entities of different types in the mesh.
\image html meshcomputationsucceed.png
If the mesh computation failed, the information about the cause of the
-failure is provided.
+failure is provided in \b Errors table.
\image html meshcomputationfail.png
-After you select the error, <b>Show Subshape</b> button allows
-visualizing the mesh elements that cause it.
+After you select the error, <b>Show Sub-shape</b> button allows
+visualizing in magenta the geometrical entity that causes the error.
-\image html failed_computation.png
+\image html failed_computation.png
+<em>3D algorithm failed to compute mesh on a box shown using <b>Show
+ Sub-shape</b> button</em>
-<b>Publish Subshape</b> button allows importing it in a separate MED
-or UNV file.
+<b>Publish Sub-shape</b> button publishes the sub-shape, whose meshing
+has failed, in GEOM component as a child of the mesh geometry, which
+allows analyzing the problem geometry and creating a submesh on it in
+order to locally tune the hypotheses.
-<b>NOTE</b> It is possible to define a 1D or a 2D mesh in a
-python script and then use such submeshes in the construction of a 3D
-mesh. For this, there exist two algorithms: <b>Use existing edges</b> and <b>Use
-existing faces</b>. They are not entirely usable from the GUI, so a
-mesh created using these algorithms should be exported into a python
-script, edited and then imported into the GUi.
+If the failure is caused by an invalid input mesh and the algorithm has
+found which mesh entities are bad, <b>Show bad Mesh</b>
+button appears in the dialog. Clicked, it shows the bad mesh entities in
+the Viewer in magenta. Sometimes the shown mesh entities are too small
+or/and hidden by other mesh elements. They can be seen after
+switching the mesh to Wireframe visualization mode or switching off
+the visualization of faces and volumes (if any).
-Consider trying a sample script for construction of a mesh from our
-\ref tui_creating_meshes_page "TUI Scripts" section.
-</li>
-</ol>
+<b>Bad Mesh to Group</b> button creates groups of bad mesh entities
+to facilitate their analysis.
+
+\image html show_bad_mesh.png
+<em>Edges bounding a hole in the surface are shown in magenta using <b>Show
+ bad Mesh</b> button</em>
+
+\note Mesh Computation Information box does not appear if you set
+"Mesh computation/Show a computation result notification" preference
+to the "Never" value. This option gives the possibility to control mesh
+computation reporting. There are the following possibilities: always
+show the information box, show only if an error occurs or never.
+By default, the information box is always shown after mesh computation operation.
+
+<p><p>
+\anchor edit_anchor
+<h2>Editing the mesh</h2>
+
+It is possible to \ref modifying_meshes_page "edit the mesh" of
+lower dimension before generation of mesh of higher dimension.
+
+For example you can generate 2D mesh, modify it using e.g.
+\ref pattern_mapping_page, and then generate 3D mesh basing on the
+modified 2D mesh. The workflow is following:
+- Define 1D and 2D meshing algorithms.
+- Compute the mesh. 2D mesh is generated.
+- Apply \ref pattern_mapping_page.
+- Define 3D meshing algorithms without modifying 1D and 2D algorithms
+and hypotheses.
+- Compute the mesh. 3D mesh is generated.
+
+\note Nodes and elements added \ref adding_nodes_and_elements_page
+"manually" can't be used in this workflow because the manually created
+entities are not attached to any geometry and thus (usually) can't be
+found by a mesher paving some geometry.
+
+<b>See Also</b> a sample TUI Script demonstrates the possibility of
+\ref tui_editing_while_meshing "Intermediate edition while meshing"
-*/
\ No newline at end of file
+*/