0021893: EDF 2133 SMESH : Improvement of 3D extrusion algorithm

doc/salome/gui/SMESH/input/prism_3d_algo.doc

@@ -2,23 +2,65 @@
 
 \page prism_3d_algo_page 3D extrusion meshing algorithm
 
-3D extrusion algorithm can be used for meshing prisms, i.e. <b>3D Shapes</b>
+3D extrusion algorithm can be used for meshing prisms, i.e. 3D shapes
 defined by two opposing faces having the same number of vertices and
-edges and meshed using, for example,  the \ref projection_algos_page
-"2D Projection" algorithm. These two faces should be connected by
-quadrangle "side" faces.
+edges. These two faces should be connected by quadrangle "side" faces.
 
-The opposing faces can be meshed with either quadrangles or triangles,
-while the side faces should be meshed with quadrangles only.
+The prism is allowed to have sides composed of several faces. (A prism
+side is a row of faces (or one face) connecting corresponding edges of
+the top and base faces). But there is a limitation that a prism 
+side is allowed to be split only vertically as indicated in the
+picture below. 
 
-\image html image157.gif "Prism with 3D extrusion meshing".
+\image html prism_ok_ko.png
+In this picture, the left prism is suitable for meshing with 3D
+extrusion algorithm; it has six sides two of which are split
+vertically. And the right prism can't be meshed with this
+algorithm because one of the prism sides is split horizontally (a
+splitting edge is highlighted).
 
-As you can see, the <b>3D extrusion</b> algorithm permits to build and to
-have in the same 3D mesh such elements as hexahedrons, prisms and
+The algorithm can propagate 2D mesh not only between horizontal
+(i.e. base and top) faces of one prism but also between faces of prisms
+organized in a stack and between stacks sharing prism sides.
+
+\image html prism_stack.png
+In this picture, four neighboring prism stacks, each comprising two prisms,
+are shown. The shown sub-mesh is used by the algorithm to mesh
+all the eight prisms in the stacks.
+
+To use <em>3D extrusion</em> algorithm you need to assign algorithms
+and hypotheses of lower dimension as follows.
+
+\b Global algorithms and hypotheses to be chosen at 
+\ref create_mesh_anchor "Creation of a mesh object" are:
+<ul>
+<li> 1D algorithm and hypothesis that will be applied for meshing
+(logically) vertical edges of the prism (these edges connect the top and
+base faces of prism).</li>
+</ul>
+
+\b Local algorithms and hypotheses to be chosen at 
+\ref constructing_submeshes_page "Constructing sub-meshes" are:
+<ul>
+<li> 1D and 2D algorithms and hypotheses that will be applied for
+meshing the top and base prism faces. These faces can be meshed
+with any type of 2D elements: quadrangles, triangles, polygons or
+their mix. It's enough to define a sub-mesh on either top or base face
+only.</li>
+<li> Optionally you can define an 1D sub-mesh on some vertical edges
+of stacked prisms, which will override the global 1D hypothesis mentioned
+above. In the above picture, the vertical division is not equidistant
+on all the length because of a "Number Of Segments" hypothesis with
+Scale Factor=3 assigned to one of edges between the shifted stacks. 
+</li></ul>
+
+\image html image157.gif "Prism with 3D extrusion meshing"
+
+As you can see, the <em>3D extrusion</em> algorithm permits to build
+in the same 3D mesh such elements as hexahedrons, prisms and
 polyhedrons.
 
-\note This algorithm works correctly only if the opposing faces have
-the same (or similar) meshing topography. Otherwise, 3D extrusion
-algorithm can fail to build mesh volumes.
+\sa a sample TUI Script of
+\ref tui_prism_3d_algo "Use 3D extrusion meshing algorithm".
 
 */

doc/salome/gui/SMESH/input/tui_prism_3d_algo.doc

@@ -0,0 +1,78 @@
+/*!
+
+\page tui_prism_3d_algo Use 3D extrusion meshing algorithm
+
+\code
+import salome, smesh, SMESH, geompy
+
+salome.salome_init()
+smesh.SetCurrentStudy( salome.myStudy )
+
+OX = geompy.MakeVectorDXDYDZ(1,0,0)
+OY = geompy.MakeVectorDXDYDZ(0,1,0)
+OZ = geompy.MakeVectorDXDYDZ(0,0,1)
+
+#  Y ^       Make geometry of a "pipe" with the following base (cross section).
+#    |       Big central quadrangles will be meshed with triangles, walls
+#                         of the pipe will be meshed with quadrilaterals
+#   +--+--+--+--+--+--+
+#   |  |  |  |  |  |  |
+#   +--+--+--+--+--+--+
+#   |  |     |     |  |
+#   +--+     |     +--+
+#   |  |     |     |  |
+#   +--+-----+-----+--+
+#   |  |     |     |  |
+#   +--+     |     +--+
+#   |  |     |     |  |
+#   +--+--+--+--+--+--+
+#   |  |  |  |  |  |  |  -->
+#   +--+--+--+--+--+--+   X
+
+quadBig   = geompy.MakeFaceHW( 20,20, 1 )
+quadBig   = geompy.MakeTranslation( quadBig, 15,15,0 )
+quadSmall = geompy.MakeFaceHW( 10,10, 1 )
+smallQuads1 = geompy.MakeMultiTranslation1D( quadSmall, OX, 10, 3 )
+smallQuads2 = geompy.MakeMultiTranslation1D( quadSmall, OY, 10, 3 )
+smallQuads2 = geompy.SubShapeAllSortedCentres( smallQuads2, geompy.ShapeType["FACE"])[1:]
+
+base = geompy.MakeCompound( smallQuads2 + [smallQuads1, quadBig])
+axis = geompy.MakeLine( geompy.MakeVertex( 25,25,0), OZ )
+base = geompy.MultiRotate1DNbTimes( base, axis, 4)
+base = geompy.MakePartition( [base], theName="base")
+path = geompy.MakeSketcher("Sketcher:F 0 0:TT 0 100:R 0:C -90 180:T 0 -150",[0,0,0, 0,-1,0, 1,0,0])
+
+# Make the pipe, each quadrangle of the base turns into a prism with composite wall faces
+pipe   = geompy.MakePipe( base, path )
+prisms = geompy.MakePartition( [pipe], theName="prisms")
+
+
+# get base faces of the prism to define sub-mesh on them
+smallQuad = geompy.GetFaceNearPoint( prisms, geompy.MakeVertex( 0,0,0 ), "smallQuad")
+bigQuad   = geompy.GetFaceNearPoint( prisms, geompy.MakeVertex( 15,15,0 ), "bigQuad")
+
+
+mesh = smesh.Mesh( prisms )
+
+# vertical division
+mesh.Segment().NumberOfSegments(15)
+
+# Extrusion 3D algo
+mesh.Prism()
+
+# mesh smallQuad with quadrilaterals
+mesh.Segment(smallQuad).LocalLength( 3 )
+mesh.Quadrangle(smallQuad)
+
+# mesh bigQuad with triangles
+mesh.Segment(bigQuad).LocalLength( 3 )
+mesh.Triangle(bigQuad)
+
+mesh.Compute()
+
+\endcode
+
+The result mesh id shown below
+\image html prism_tui_sample.png
+
+*/