<?xml version="1.0" encoding="UTF-8"?>
<refentry version="5.0-subset Scilab" xml:id="gf_mesh_get" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:xi="http://www.w3.org/2001/XInclude"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:html="http://www.w3.org/1999/xhtml"
          xmlns:db="http://docbook.org/ns/docbook">
  <refnamediv>
    <refname>gf_mesh_get</refname>
    <refpurpose>  General mesh inquiry function. All these functions accept also a
  mesh_fem argument instead of a mesh M (in that case, the mesh_fem
  linked mesh will be used). 
</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>d = gf_mesh_get(mesh M, 'dim')</synopsis>
    <synopsis>np = gf_mesh_get(mesh M, 'nbpts')</synopsis>
    <synopsis>nc = gf_mesh_get(mesh M, 'nbcvs')</synopsis>
    <synopsis>P = gf_mesh_get(mesh M, 'pts'[, ivec PIDs])</synopsis>
    <synopsis>Pid = gf_mesh_get(mesh M, 'pid')</synopsis>
    <synopsis>PIDs = gf_mesh_get(mesh M, 'pid in faces', imat CVFIDs)</synopsis>
    <synopsis>PIDs = gf_mesh_get(mesh M, 'pid in cvids', imat CVIDs)</synopsis>
    <synopsis>PIDs = gf_mesh_get(mesh M, 'pid in regions', imat RIDs)</synopsis>
    <synopsis>PIDs = gf_mesh_get(mesh M, 'pid from coords', mat PTS[, scalar radius=0])</synopsis>
    <synopsis>{Pid, IDx} = gf_mesh_get(mesh M, 'pid from cvid'[, imat CVIDs])</synopsis>
    <synopsis>{Pts, IDx} = gf_mesh_get(mesh M, 'pts from cvid'[, imat CVIDs])</synopsis>
    <synopsis>CVid = gf_mesh_get(mesh M, 'cvid')</synopsis>
    <synopsis>m = gf_mesh_get(mesh M, 'max pid')</synopsis>
    <synopsis>m = gf_mesh_get(mesh M, 'max cvid')</synopsis>
    <synopsis>[E,C] = gf_mesh_get(mesh M, 'edges' [, CVLST][, 'merge'])</synopsis>
    <synopsis>[E,C] = gf_mesh_get(mesh M, 'curved edges', int N [, CVLST])</synopsis>
    <synopsis>PIDs = gf_mesh_get(mesh M, 'orphaned pid')</synopsis>
    <synopsis>CVIDs = gf_mesh_get(mesh M, 'cvid from pid', ivec PIDs[, bool share=False])</synopsis>
    <synopsis>CVFIDs = gf_mesh_get(mesh M, 'faces from pid', ivec PIDs)</synopsis>
    <synopsis>CVFIDs = gf_mesh_get(mesh M, 'outer faces'[, CVIDs])</synopsis>
    <synopsis>CVFIDs = gf_mesh_get(mesh M, 'faces from cvid'[, ivec CVIDs][, 'merge'])</synopsis>
    <synopsis>[mat T] = gf_mesh_get(mesh M, 'triangulated surface', int Nrefine [,CVLIST])</synopsis>
    <synopsis>N = gf_mesh_get(mesh M, 'normal of face', int cv, int f[, int nfpt])</synopsis>
    <synopsis>N = gf_mesh_get(mesh M, 'normal of faces', imat CVFIDs)</synopsis>
    <synopsis>Q = gf_mesh_get(mesh M, 'quality'[, ivec CVIDs])</synopsis>
    <synopsis>A = gf_mesh_get(mesh M, 'convex area'[, ivec CVIDs])</synopsis>
    <synopsis>A = gf_mesh_get(mesh M, 'convex radius'[, ivec CVIDs])</synopsis>
    <synopsis>{S, CV2S} = gf_mesh_get(mesh M, 'cvstruct'[, ivec CVIDs])</synopsis>
    <synopsis>{GT, CV2GT} = gf_mesh_get(mesh M, 'geotrans'[, ivec CVIDs])</synopsis>
    <synopsis>RIDs = gf_mesh_get(mesh M, 'boundaries')</synopsis>
    <synopsis>RIDs = gf_mesh_get(mesh M, 'regions')</synopsis>
    <synopsis>RIDs = gf_mesh_get(mesh M, 'boundary')</synopsis>
    <synopsis>CVFIDs = gf_mesh_get(mesh M, 'region', ivec RIDs)</synopsis>
    <synopsis>gf_mesh_get(mesh M, 'save', string filename)</synopsis>
    <synopsis>s = gf_mesh_get(mesh M, 'char')</synopsis>
    <synopsis>gf_mesh_get(mesh M, 'export to vtk', string filename, ... [,'ascii'][,'quality'])</synopsis>
    <synopsis>gf_mesh_get(mesh M, 'export to dx', string filename, ... [,'ascii'][,'append'][,'as',string name,[,'serie',string serie_name]][,'edges'])</synopsis>
    <synopsis>gf_mesh_get(mesh M, 'export to pos', string filename[, string name])</synopsis>
    <synopsis>z = gf_mesh_get(mesh M, 'memsize')</synopsis>
    <synopsis>gf_mesh_get(mesh M, 'display')</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Description</title>
    <para>  General mesh inquiry function. All these functions accept also a
  mesh_fem argument instead of a mesh M (in that case, the mesh_fem
  linked mesh will be used). 
</para>
  </refsection>

  <refsection>
    <title>Command list</title>

    <itemizedlist>
    <listitem>
    <para><literal>d = gf_mesh_get(mesh M, 'dim')</literal></para>

    <para>       Get the dimension of the mesh (2 for a 2D mesh, etc).
    </para>
    </listitem>

    <listitem>
    <para><literal>np = gf_mesh_get(mesh M, 'nbpts')</literal></para>

    <para>       Get the number of points of the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>nc = gf_mesh_get(mesh M, 'nbcvs')</literal></para>

    <para>         Get the number of convexes of the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>P = gf_mesh_get(mesh M, 'pts'[, ivec PIDs])</literal></para>

    <para>       Return the list of point coordinates of the mesh.

    Each column of the returned matrix contains the coordinates of one
    point. If the optional argument <literal>PIDs</literal> was given, only the points
    whose #id is listed in this vector are returned. Otherwise, the
    returned matrix will have gf_mesh_get(mesh M, 'max_pid') columns, which might
    be greater than gf_mesh_get(mesh M, 'nbpts') (if some points of the mesh have
    been destroyed and no call to gf_mesh_set(mesh M, 'optimize structure') have
    been issued). The columns corresponding to deleted points will be
    filled with NaN. You can use gf_mesh_get(mesh M, 'pid') to filter such invalid
    points.
    </para>
    </listitem>

    <listitem>
    <para><literal>Pid = gf_mesh_get(mesh M, 'pid')</literal></para>

    <para>       Return the list of points #id of the mesh.

    Note that their numbering is not supposed to be contiguous from
    1 to gf_mesh_get(mesh M, 'nbpts'),
    especially if some points have been removed from the mesh. You
    can use gf_mesh_set(mesh M, 'optimize_structure') to enforce a contiguous
    numbering. 
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_get(mesh M, 'pid in faces', imat CVFIDs)</literal></para>

    <para>       Search point #id listed in <literal>CVFIDs</literal>.

    <literal>CVFIDs</literal> is a two-rows matrix, the first row lists convex #ids,
    and the second lists face numbers. On return, <literal>PIDs</literal> is a
    vector containing points #id.
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_get(mesh M, 'pid in cvids', imat CVIDs)</literal></para>

    <para>         Search point #id listed in <literal>CVIDs</literal>.
      
      <literal>PIDs</literal> is a vector containing points #id.
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_get(mesh M, 'pid in regions', imat RIDs)</literal></para>

    <para>       Search point #id listed in <literal>RIDs</literal>.

    <literal>PIDs</literal> is a vector containing points #id.
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_get(mesh M, 'pid from coords', mat PTS[, scalar radius=0])</literal></para>

    <para>       Search point #id whose coordinates are listed in <literal>PTS</literal>.

    <literal>PTS</literal> is an array containing a list of point coordinates. On
    return, <literal>PIDs</literal> is a vector containing points
    #id for each point found in <literal>eps</literal> range, and -1 for those
    which where not found in the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>{Pid, IDx} = gf_mesh_get(mesh M, 'pid from cvid'[, imat CVIDs])</literal></para>

    <para>       Return the points attached to each convex of the mesh.

    If <literal>CVIDs</literal> is omitted, all the convexes will be considered
    (equivalent to <literal>CVIDs = gf_mesh_get(mesh M, 'max cvid')</literal>). <literal>IDx</literal> is a
    vector, length(IDx) = length(CVIDs)+1. <literal>Pid</literal> is a
    vector containing the concatenated list of #id of
    points of each convex in <literal>CVIDs</literal>. Each entry of <literal>IDx</literal> is the
    position of the corresponding convex point list in <literal>Pid</literal>. Hence,
    for example, the list of #id of points of the second convex is
    Pid(IDx(2):IDx(3)-1).

    If <literal>CVIDs</literal> contains convex #id which do not exist in the mesh,
    their point list will be empty.
    </para>
    </listitem>

    <listitem>
    <para><literal>{Pts, IDx} = gf_mesh_get(mesh M, 'pts from cvid'[, imat CVIDs])</literal></para>

    <para>       Search point listed in <literal>CVID</literal>.

    If <literal>CVIDs</literal> is omitted, all the convexes will be considered
    (equivalent to <literal>CVIDs = gf_mesh_get(mesh M, 'max cvid')</literal>). <literal>IDx</literal> is a
    vector, length(IDx) = length(CVIDs)+1. <literal>Pts</literal> is a
    vector containing the concatenated list of points
    of each convex in <literal>CVIDs</literal>. Each entry of <literal>IDx</literal> is the position
    of the corresponding convex point list in <literal>Pts</literal>. Hence, for
    example, the list of points of the second convex is
    Pts(:,IDx(2):IDx(3)-1).

    If <literal>CVIDs</literal> contains convex #id which do not exist in the mesh,
    their point list will be empty.
    </para>
    </listitem>

    <listitem>
    <para><literal>CVid = gf_mesh_get(mesh M, 'cvid')</literal></para>

    <para>       Return the list of all convex #id.

    Note that their numbering is not supposed to be contiguous from
    1 to gf_mesh_get(mesh M, 'nbcvs'),
    especially if some points have been removed from the mesh. You
    can use gf_mesh_set(mesh M, 'optimize_structure') to enforce a contiguous
    numbering. 
    </para>
    </listitem>

    <listitem>
    <para><literal>m = gf_mesh_get(mesh M, 'max pid')</literal></para>

    <para>         Return the maximum #id of all points in the mesh (see 'max cvid').
    </para>
    </listitem>

    <listitem>
    <para><literal>m = gf_mesh_get(mesh M, 'max cvid')</literal></para>

    <para>         Return the maximum #id of all convexes in the mesh (see 'max pid').
    </para>
    </listitem>

    <listitem>
    <para><literal>[E,C] = gf_mesh_get(mesh M, 'edges' [, CVLST][, 'merge'])</literal></para>

    <para>       [OBSOLETE FUNCTION! will be removed in a future release]

    Return the list of edges of mesh M for the convexes listed in the
    row vector CVLST. E is a 2 x nb_edges matrix containing point
    indices. If CVLST is omitted, then the edges of all convexes are
    returned. If CVLST has two rows then the first row is supposed to
    contain convex numbers, and the second face numbers, of which the
    edges will be returned.  If 'merge' is indicated, all common
    edges of convexes are merged in a single edge.  If the optional
    output argument C is specified, it will contain the convex number
    associated with each edge.
    </para>
    </listitem>

    <listitem>
    <para><literal>[E,C] = gf_mesh_get(mesh M, 'curved edges', int N [, CVLST])</literal></para>

    <para>       [OBSOLETE FUNCTION! will be removed in a future release]

    More sophisticated version of gf_mesh_get(mesh M, 'edges') designed for
    curved elements. This one will return N (N>=2) points of the
    (curved) edges. With N==2, this is equivalent to
    gf_mesh_get(mesh M, 'edges'). Since the points are no more always part of
    the mesh, their coordinates are returned instead of points
    number, in the array E which is a [ mesh_dim x 2 x nb_edges ]
    array.  If the optional output argument C is specified, it will
    contain the convex number associated with each edge.
    </para>
    </listitem>

    <listitem>
    <para><literal>PIDs = gf_mesh_get(mesh M, 'orphaned pid')</literal></para>

    <para>         Search point #id which are not linked to a convex.
    </para>
    </listitem>

    <listitem>
    <para><literal>CVIDs = gf_mesh_get(mesh M, 'cvid from pid', ivec PIDs[, bool share=False])</literal></para>

    <para>       Search convex #ids related with the point #ids given in <literal>PIDs</literal>.
    
    If <literal>share=False</literal>, search convex whose vertex #ids are in <literal>PIDs</literal>.
    If <literal>share=True</literal>, search convex #ids that share the point #ids
    given in <literal>PIDs</literal>. <literal>CVIDs</literal> is a  vector (possibly
    empty).
    </para>
    </listitem>

    <listitem>
    <para><literal>CVFIDs = gf_mesh_get(mesh M, 'faces from pid', ivec PIDs)</literal></para>

    <para>       Return the convex faces whose vertex #ids are in <literal>PIDs</literal>.

    <literal>CVFIDs</literal> is a two-rows matrix, the first row lists convex #ids,
    and the second lists face numbers (local number in the convex).
    For a convex face to be returned, EACH of its points have to be
    listed in <literal>PIDs</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>CVFIDs = gf_mesh_get(mesh M, 'outer faces'[, CVIDs])</literal></para>

    <para>       Return the faces which are not shared by two convexes.

    <literal>CVFIDs</literal> is a two-rows matrix, the first row lists convex #ids,
    and the second lists face numbers (local number in the convex).
    If <literal>CVIDs</literal> is not given, all convexes are considered, and it
    basically returns the mesh boundary. If <literal>CVIDs</literal> is given, it
    returns the boundary of the convex set whose #ids are listed
    in <literal>CVIDs</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>CVFIDs = gf_mesh_get(mesh M, 'faces from cvid'[, ivec CVIDs][, 'merge'])</literal></para>

    <para>       Return a list of convexes faces from a list of convex #id.

    <literal>CVFIDs</literal> is a two-rows matrix, the first row lists convex #ids,
    and the second lists face numbers (local number in the convex).
    If <literal>CVIDs</literal> is not given, all convexes are considered. The optional
    argument 'merge' merges faces shared by the convex of <literal>CVIDs</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>[mat T] = gf_mesh_get(mesh M, 'triangulated surface', int Nrefine [,CVLIST])</literal></para>

    <para>       [DEPRECATED FUNCTION! will be removed in a future release]

    Similar function to gf_mesh_get(mesh M, 'curved edges') : split (if
    necessary, i.e. if the geometric transformation if non-linear)
    each face into sub-triangles and return their coordinates in T
    (see also gf_compute('eval on P1 tri mesh'))
    </para>
    </listitem>

    <listitem>
    <para><literal>N = gf_mesh_get(mesh M, 'normal of face', int cv, int f[, int nfpt])</literal></para>

    <para>       Evaluates the normal of convex <literal>cv</literal>, face <literal>f</literal> at the <literal>nfpt</literal> point of the face.

    If <literal>nfpt</literal> is not specified, then the normal is evaluated at each
    geometrical node of the face.
    </para>
    </listitem>

    <listitem>
    <para><literal>N = gf_mesh_get(mesh M, 'normal of faces', imat CVFIDs)</literal></para>

    <para>       Evaluates (at face centers) the normals of convexes.

    <literal>CVFIDs</literal> is supposed a two-rows matrix, the first row lists convex
    #ids, and the second lists face numbers (local number in the convex).
    </para>
    </listitem>

    <listitem>
    <para><literal>Q = gf_mesh_get(mesh M, 'quality'[, ivec CVIDs])</literal></para>

    <para>       Return an estimation of the quality of each convex (<latex style="text"><![CDATA[0 \leq Q \leq 1]]></latex>).
    </para>
    </listitem>

    <listitem>
    <para><literal>A = gf_mesh_get(mesh M, 'convex area'[, ivec CVIDs])</literal></para>

    <para>       Return an estimate of the area of each convex.
    </para>
    </listitem>

    <listitem>
    <para><literal>A = gf_mesh_get(mesh M, 'convex radius'[, ivec CVIDs])</literal></para>

    <para>       Return an estimate of the radius of each convex.
    </para>
    </listitem>

    <listitem>
    <para><literal>{S, CV2S} = gf_mesh_get(mesh M, 'cvstruct'[, ivec CVIDs])</literal></para>

    <para>       Return an array of the convex structures.

    If <literal>CVIDs</literal> is not given, all convexes are considered. Each convex
    structure is listed once in <literal>S</literal>, and <literal>CV2S</literal> maps the convexes
    indice in <literal>CVIDs</literal> to the indice of its structure in <literal>S</literal>.
    </para>
    </listitem>

    <listitem>
    <para><literal>{GT, CV2GT} = gf_mesh_get(mesh M, 'geotrans'[, ivec CVIDs])</literal></para>

    <para>       Returns an array of the geometric transformations.

    See also gf_mesh_get(mesh M, 'cvstruct').
    </para>
    </listitem>

    <listitem>
    <para><literal>RIDs = gf_mesh_get(mesh M, 'boundaries')</literal></para>

    <para>       DEPRECATED FUNCTION. Use 'regions' instead. 
    </para>
    </listitem>

    <listitem>
    <para><literal>RIDs = gf_mesh_get(mesh M, 'regions')</literal></para>

    <para>       Return the list of valid regions stored in the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>RIDs = gf_mesh_get(mesh M, 'boundary')</literal></para>

    <para>       DEPRECATED FUNCTION. Use 'region' instead. 
    </para>
    </listitem>

    <listitem>
    <para><literal>CVFIDs = gf_mesh_get(mesh M, 'region', ivec RIDs)</literal></para>

    <para>       Return the list of convexes/faces on the regions <literal>RIDs</literal>.

    <literal>CVFIDs</literal> is a two-rows matrix, the first row lists convex #ids,
    and the second lists face numbers (local number in the convex).
    (and 0 when the whole convex is in the
    regions).
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_get(mesh M, 'save', string filename)</literal></para>

    <para>       Save the mesh object to an ascii file.

    This mesh can be restored with gf_mesh('load', filename).
    </para>
    </listitem>

    <listitem>
    <para><literal>s = gf_mesh_get(mesh M, 'char')</literal></para>

    <para>       Output a string description of the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_get(mesh M, 'export to vtk', string filename, ... [,'ascii'][,'quality'])</literal></para>

    <para>       Exports a mesh to a VTK file .

    If 'quality' is specified, an estimation of the quality of each
    convex will be written to the file.

    See also gf_mesh_fem_get(mesh_fem MF, 'export to vtk'), gf_slice_get(slice S, 'export to vtk').
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_get(mesh M, 'export to dx', string filename, ... [,'ascii'][,'append'][,'as',string name,[,'serie',string serie_name]][,'edges'])</literal></para>

    <para>       Exports a mesh to an OpenDX file.

    See also gf_mesh_fem_get(mesh_fem MF, 'export to dx'), gf_slice_get(slice S, 'export to dx').
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_get(mesh M, 'export to pos', string filename[, string name])</literal></para>

    <para>       Exports a mesh to a POS file .

    See also gf_mesh_fem_get(mesh_fem MF, 'export to pos'), gf_slice_get(slice S, 'export to pos').
    </para>
    </listitem>

    <listitem>
    <para><literal>z = gf_mesh_get(mesh M, 'memsize')</literal></para>

    <para>         Return the amount of memory (in bytes) used by the mesh.
    </para>
    </listitem>

    <listitem>
    <para><literal>gf_mesh_get(mesh M, 'display')</literal></para>

    <para>         displays a short summary for a mesh object.
    </para>
    </listitem>

    </itemizedlist>
  </refsection>

  <refsection>
    <title>See Also</title>
    <simplelist type="inline">
      <member><link linkend="getfem_types">getfem types</link></member>
    </simplelist>
  </refsection>

  <refsection>
    <title>Authors</title>
    <para>Y. Collette</para>
  </refsection>

</refentry>
