<h1>Custom size map</h1>
-\image html blsurf_parameters_sizemap.png
+\image html blsurf_parameters_sizemap1.png
-It is possible to define user sizes on faces, edges or verteces.
+User sizes can be defined on faces, edges or vertices.
<ul>
-<li>Those faces, edges and verteces must be sub-shapes (from explode command) of the meshed geometry object.</li>
-<li>Groups of faces, edges and verteces are also handled.</li>
-<li>Multi-selection is possible.</li>
-<li>The sizes are constant values.</li>
+<li>The faces, edges and vertices can belong to the meshed geometrical
+object or to its sub-shapes (created using <b>Explode</b> command).</li>
+<li>Groups of faces, edges and vertices are also handled.</li>
+<li>It is possible to attribute the same size to several geometries using multi-selection.</li>
+<li>The sizes are constant values or python functions.</li>
+<li>In case of a python function, the following rules must be respected:
+<ul>
+<li>The name of the function is f.</li>
+<li>If geometry is a face or a group of faces, the function is f(u,v).</li>
+<li>If geometry is an edge or a group of edges, the function is f(t).</li>
+<li>If geometry is a vertex or a group of vertices, the function is f().</li>
+<li>The function must return a double.</li>
+</ul></li>
</ul>
-<br><b>See Also</b> a sample TUI Script of the \ref tui_blsurf "creation of a BLSurf hypothesis", including size map.
-
\anchor blsurf_sizemap_computation
<h2>Computation of the physical size</h2>
-Here is the detail on the calculation of the size (from BLSurf documentation).
\n
-The size is obtained by querying sizemap functions associated to the input CAD object for surfaces, curves and points.
-Each function can either return a value h (which is then trimmed between the two bounds hphymin and hphymax), or "no answer" (by not assigning a value to h), thus providing great flexibility in the specification of the sizes. The computation depends whether point P is internal to a surface, internal to a curve, or at the end of several curves:
+The physical size is obtained by querying sizemap functions associated to the input CAD object for surfaces, curves and points.
+Each function can either return a value h (which is then trimmed
+between the two bounds hphymin and hphymax), or "no answer" (by not
+assigning a value to h), thus providing great flexibility in the
+specification of the sizes. The computation depends on whether point P is internal to a surface, internal to a curve, or at the end of several curves:
<ul>
<li> If point P is internal to a surface, the CAD surface size function is queried. If no answer is returned, one interpolates with the values at the vertices of the discretized interface curves.</li>
<li> If point P is internal to a curve, the CAD curve size function is queried first. If no answer is returned, the surface size function is queried for every adjacent surface and the mean value of the returned values is computed. If no answer is returned, sizes h1 and h2 at both ends of the curve are considered (see next item) and the interpolated value is computed.</li>
</ul>
In order to compute the mean of several values, the arithmetic mean is used by default, but this can be modified by the parameter \ref blsurf_hmean_flag "hmean flag". In the same way, in order to interpolate two values, a linear interpolation is used by default, but this can be modified by \ref blsurf_hinterpol_flag "hinterpol flag".
+\anchor blsurf_attractor
+<h2>Advanced maps</h2>
+\n
+\image html blsurf_parameters_sizemap2.png
+\n
+More specific size maps can be defined on faces.
+
+<ul>
+<li> <i> Attractors </i> allow to define the size of the mesh elements on a face so that the mesh is the finest on the attractor shape and becomes coarser when getting far from this shape.
+<ul>
+<li> The selected attractor can be a Vertex, an Edge, a Wire or a Compound mixing several entities of those types.</li>
+<li> The attractor doesn't have to be a sub-shape of the shape to mesh.</li>
+<li> The size will grow exponentially (see formula below) but is bounded by gradation, \n so if you want the formula to be strictly respected, you should set the <i>gradation</i>
+to its maximum (2.5) in the <i>arguments</i> tab.
+</ul>
+\n
+<li> Furthermore you can choose to <i> keep the size constant </i> until a certain distance from a shape. This option can be combined or not with an <i>attractor</i> size map described above.
+<ul>
+<li> If the two options are combined the size will remain constant until the distant specified in "constant over" and grow then as prescribed by the attractor function.</li>
+<li> Else the growing is only controled by the standard arguments of BLSURF (gradation ...).</li>
+</ul>
+</ul>
+
+\image html blsurf_attractors2.png "Example of mesh created using attractors, the attractors here are the side edges and the size grow from the side of the surface towards the apex"
+\n
+\image html blsurf_const_size_near_shape2.png "Example of size map with constant size option, the size is kept constant on the left side of the surface until a certain distance"
+\n
+Remark : The validation of the hypothesis might take a few seconds if attractors are defined or the "constant size" option is used because a map of distances has to be built on the whole surface for each face where such an hypothesis has been defined.
+
+<br><b>See Also</b> a sample TUI Script of the \ref tui_blsurf "creation of a BLSurf hypothesis", including size map.
+
+\anchor blsurf_attractor_computation
+<h2>Computation of attractors</h2>
+\n
+The size grow exponentially following the equation : h(d) = User size + (h_start - User Size) * exp( -(d / R)^2 ).
+\n
+Where :
+<ul>
+<li>h_start is the desired size on the given attractor shape</li>
+<li>d is the distance of the current point from the attractor shape. The distance is the geodesic distance (i.e. calculated by following the surface to be meshed) </li>
+<li>R is called the distance of influence and allows controlling the growth rate of the mesh </li>
+</ul>
<h1>Custom enforced vertices</h1>
\image html blsurf_parameters_enforced_vertices.png
-It is possible to define some enforced vertices to BLSurf algorithm without any vertex creation into the CAD.
+It is possible to define some enforced vertices to BLSurf algorithm
+without creating any vertices by CAD algorithms.
<ul>
-<li>Enforced vertices are the projection of a given point defines by its (x,y,z) coordinates on the concerned face.</li>
-<li>It is possible to define several enforced vertices on 1 face.</li>
-<li>Group of faces are also handled.</li>
-<li>If the projection point is on the boundary or outside the face, then it will be ignored.</li>
+<li>The enforced vertex is the projection of a point defined by its
+(x,y,z) coordinates on the selected face.</li>
+<li>It is possible to define several enforced vertices on a face or a group of faces.</li>
+<li>If the projected point is on the boundary or outside of the face, it will be ignored.</li>
</ul>
<br><b>See Also</b> a sample TUI Script of the \ref tui_blsurf "creation of a BLSurf hypothesis", including enforced vertices.
Currently BLSURF plugin has the following limitations.
<ul>
- <li>The created mesh will contain inverted elements if it is based on a shape,
- consisting of more than one face (box, cone, torus...) and if
- the option "Allow Quadrangles (Test)" has been checked before
- computation.</li>
-
- <li>SIGFPE exception is raised at the attempt to compute the mesh
- based on a box when the option "Patch independent" is checked.</li>
-
<li>BLSURF algorithm cannot be used as a local algorithm (on
sub-meshes) or as a provider of a low-level
mesh for some 3D algorithms, because the BLSURF mesher (and
following combinations of algorithms are impossible:
<ul>
<li> global MEFISTO or Quadrangle(mapping) + local BLSURF;</li>
- <li> BLSUFR + Projection 2D from faces meshed by BLSURF;</li>
+ <li> BLSURF + Projection 2D from faces meshed by BLSURF;</li>
<li> local BLSURF + Extrusion 3D;</li>
</ul>
- </li>
+ </li>
</ul>
*/
