/*!

\page pattern_mapping_page Pattern mapping

<br><h2>About patterns</h2>

The pattern describes a mesh to generate: positions of nodes within a
geometrical domain and nodal connectivity of elements. A
pattern also specifies the so-called key-points, i.e. the nodes that will be
located at geometrical vertices. The pattern description is stored in
\<pattern_name\>.smp file.

The smp file contains 4 sections:

-# The first line indicates the total number of pattern nodes (N).
-# The next N lines describe nodes coordinates. Each line contains 2
node coordinates for a 2D pattern or 3 node cordinates for a 3D pattern.
Note, that node coordinates of a 3D pattern can be defined only by relative values in range [0;1].
-# The key-points line contains the indices of the nodes to be mapped on geometrical
vertices (for a 2D pattern only). Index n refers to the node described 
on the n-th line of section 2. The index of the first node zero. For a 3D pattern the key points are not specified.
-# The remaining lines describe nodal connectivity of elements, one line
for each element. Each line holds indices of nodes forming an element.
Index n refers to the node described on the n-th line of section 2.
The first node index is zero. There must be 3 or 4 indices on each
line for a 2D pattern (only 2d elements are allowed) and 4, 5, 6 or 8
indices for a 3D pattern (only 3d elements are allowed).

A 2D pattern must contain at least one element and at least one
key-point. All key-points must lie on boundaries.

A 3D pattern must contain at least one element.

An example of a simple 2D pattern smp file:

\code
!!! SALOME 2D mesh pattern file
!!!
!!! Nb of points:
9
        200     0       !- 0
        100     0       !- 1
          0     0       !- 2
          0  -100       !- 3
          0  -200       !- 4
        100  -200       !- 5
        200  -200       !- 6
        200  -100       !- 7
        100  -100       !- 8
!!! Indices of 4 key-points
 2 0 4 6
!!! Indices of points of 6 elements
 0 1 8
 8 5 6 7
 2 3 8
 8 3 4 5
 8 7 0
 8 1 2
\endcode

The image below provides a preview of the above pattern:

\image html pattern2d.png

An example of a simple 3D pattern smp file:

\code
!!! SALOME 3D mesh pattern file
!!!
!!! Nb of points:
9
        0        0        0   !- 0
        1        0        0   !- 1
        0        1        0   !- 2
        1        1        0   !- 3
        0        0        1   !- 4
        1        0        1   !- 5
        0        1        1   !- 6
        1        1        1   !- 7
      0.5      0.5      0.5   !- 8
!!! Indices of points of 6 elements:
 0 1 5 4 8
 7 5 1 3 8
 3 2 6 7 8
 2 0 4 6 8
 0 2 3 1 8
 4 5 7 6 8
\endcode

<br><h2>Application of pattern mapping</h2>

<em>To apply pattern mapping to a geometrical object:</em>

From the \b Modification menu choose the <b>Pattern Mapping</b> item or click 
<em>"Pattern mapping"</em> button in the toolbar.

\image html image98.png
<center><em>"Pattern mapping" button</em></center>

The following dialog box will appear:

\n <b>2D pattern</b>

\image html patternmapping1.png

In this dialog you should specify:

<ul>
   <li> A face with the number of vertices equal to the number of
     key-points in the pattern; the number of key-points on internal
     boundaries of the pattern must also be equal to the number of vertices
     on internal boundaries of the face;</li>
   <li> A vertex to which the first key-point should be mapped;</li>
   <li> If the order of key-points is reversed or not. (The order of vertices of
     a face is counterclockwise looking from the outside).</li>
</ul>

\n <b>3D pattern</b>

\image html patternmapping2.png

In this dialog you should specify:
<ul>
   <li> A 3D block (Solid) object;</li>
   <li> Two vertices that specify the order of nodes in the resulting mesh.</li>
</ul>

Then you either load a .smp pattern file previously created manually
by clicking on the <em>"Load pattern"</em> button, or click on the \b
New button for automatic generation of the pattern.

For automatic generation you should specify a geometrical face (for a
2D pattern) or a solid (for a 3D pattern) with a mesh built on it. Mesh nodes lying on
face vertices become key-points of the pattern. Additionally, for a 2D
pattern you may choose the way of getting nodes coordinates by
<b>projecting nodes on the face</b> instead of using
"positions on face" generated by mesher (if there is any). Faces
having a seam edge can't be used for automatic pattern creation.

When creating a pattern from an existing mesh, there are two possible
cases:

- A sub-mesh on face/solid is selected. A pattern is created from the 2d/3d
elements bound to a face/solid by mesher. For 2D pattern, node coordinates are either
"positions on face" computed by mesher, or coordinates got by node
projection on a geometrical surface, according to the user choice. For
3D pattern, nodes coordinates correspond to the nodes computed by mesher.
- A mesh where the main shape is a face/solid, is selected. A pattern is
created from all the 2d/3d elements in a mesh. In addition, for 2D
pattern, if all mesh elements are build by mesher, the user can select
the way of getting nodes coordinates, else all nodes are projected on
a face surface.

\image html a-patterntype.png

<center><b> 2D Pattern Creation dialog box</b></center>

\image html a-patterntype1.png

<center><b> 3D Pattern Creation dialog box</b></center>

<br><h2>Mapping algorithm</h2>

The mapping algorithm for 2D case is as follows:

- Key-points are set in the order that they are encountered when
  walking along a pattern boundary so that elements are on the left. The
  first key-point is preserved.
- Find geometrical vertices corresponding to key-points by vertices
  order in a face boundary; here, "Reverse order of key-points" flag is
  taken into account. \image html image95.gif
- Boundary nodes of a pattern are mapped onto edges of a face: a
  node located between certain key-points on a pattern boundary is
  mapped on a geometrical edge limited by corresponding geometrical
  vertices. Node position on an edge reflects its distance from two
  key-points. \image html image96.gif
- Coordinates of a non-boundary node in a parametric space of a face
 are defined as following. In a parametric space of a pattern, a node
 lays at the intersection of two iso-lines, each of which intersects a
 pattern boundary at least at two points. Knowing mapped positions of
 boundary nodes, we find where isoline-boundary intersection points are
 mapped to, and hence we can find mapped isolines direction and then,
 two node positions on two mapped isolines. The eventual mapped
 position of a node is found as an average of positions on mapped
 isolines. \image html image97.gif

For 3D case the algorithm is similar.

<b>See Also</b> a sample TUI Script of a 
\ref tui_pattern_mapping "Pattern Mapping" operation.

*/