<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="fec">
    <refnamediv>
        <refname>fec</refname>
        <refpurpose>pseudo-color plot of a function defined on a mesh</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>fec(x,y,triangles,func,&lt;opt_args&gt;)
            fec(x,y,triangles,func,[strf,leg,rect,nax,zminmax,colminmax,colout,mesh])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>
                        two vectors of size <literal>n</literal>, <literal>(x(i),y(i))</literal> gives the coordinates of
                        node  <literal>i</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>func</term>
                <listitem>
                    <para>
                        a vector of size <literal>n</literal> : <literal>func(i)</literal> gives the value at node <literal>i</literal>
                        of the function for which we want the pseudo-color plot.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>triangles</term>
                <listitem>
                    <para>
                        is a <literal>[Ntr,N+2]</literal> matrix. Each line of <varname>triangles</varname> specifies a convex polygon
                        of the  mesh <literal>triangles(j) = [number,node1,node2,node3, ..., nodeN, flag]</literal>.
                        <literal>node1,node2,node3, ..., nodeN</literal> are the number of the nodes which constitutes
                        the polygon. number is the number of the polygons and flag is an integer
                        not used in the fec function.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        This represents a sequence of statements <literal>key1=value1, key2=value2</literal>,... where <literal>key1</literal>,
                        <literal>key2,...</literal> can be one of the following: strf, leg, rect, nax, zminmax, colminmax, colout, mesh
                        (see <link linkend="plot2d">plot2d</link> for the 4 first ones).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>strf,leg,rect,nax</term>
                <listitem>
                    <para>see plot2d</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>zminmax</term>
                <listitem>
                    <para>vector with 2 components [zmin zmax] (useful in particular for animation)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>colminmax</term>
                <listitem>
                    <para>vector of 2 positives integers [colmin colmax]</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>colout</term>
                <listitem>
                    <para>vector of 2 integers [under_min_col upper_max_col]</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mesh</term>
                <listitem>
                    <para>boolean scalar, default value %f (must be true if you want also display the mesh)</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>This function is the good one to draw linear finite element solutions, based on polygons
            or simply to display a function defined on a polygon mapping. The color interpolation
            is done through software computation and so it is not too fast.
        </para>
        <para>
            The function <link linkend="colorbar">colorbar</link> may be used to see the color scale (see the example
            section).
        </para>
        <para>
            The <varname>zminmax</varname> argument gives the z values associated with the first and the last
            color (of the current colormap). More exactly if the colormap have nc colors and if we note
            <emphasis>dz = (zmax-zmin)/nc</emphasis>, then the part of the polygon mapping where
            <emphasis>zmin + (i-1)dz &lt;= z &lt; zmin + i dz</emphasis> is filled with the color <emphasis>i</emphasis>).
            By default <emphasis>zmin = min(func)</emphasis> and <emphasis>zmax = max(func)</emphasis>. If you want to do
            an animation with func values that varies in time, take for zmin and zmax the global
            minimum and maximum or something close.
        </para>
        <para>
            The <varname>colout</varname> argument lets the user choosing the colors for the 2 extremes
            regions <emphasis>{func &lt; zmin}</emphasis> and <emphasis>{func &gt; zmax}</emphasis>, <literal>under_min_col</literal> and
            <literal>upper_max_col</literal> may be equal (independently) to:
        </para>
        <variablelist>
            <varlistentry>
                <term>-1</term>
                <listitem>
                    <para>in this case the same color than in the neighbouring zone is used (CAUTION:
                        you do not see that the corresponding limit is crossed), this is the
                        default case.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>0</term>
                <listitem>
                    <para>in this case the extreme region is not painting at all.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k</term>
                <listitem>
                    <para>(k being a valid index to a color of the current colormap) the extreme region
                        is painting in color k.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            If you do not want to use the complete colormap you may use the <varname>colminmax</varname>
            argument with <emphasis>1 &lt;= colmin &lt; colmax &lt;= nc</emphasis> (nc being the number of colors
            of the current colormap) so as to use only the [colmin,colmax]  sub-part of the colormap.
            (by default all the colors of the colormap are used).
        </para>
        <para>
            Note that for historical reasons, the third input argument is called <varname>triangles</varname>, but <function>fec</function> accepts all types of convex polygons.
        </para>
        <para>
            See the demo files <literal>demos/fec</literal>:
        </para>
        <para>
            <literal>fec.ex1</literal> is a simple demo file in which a mesh and a function
            on that mesh is completely built in Scilab syntax
        </para>
        <para>
            <literal>fec.ex2</literal> is an example for which the mesh and the function value where
            computed by an external mesh builder (amdba type mesh) and an external program.
            A set of macros ( provided in file <literal>macros.sci</literal>) can be used to read the
            data files in Scilab and plot the results.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// define a mini triangulation (4 vertices, 2 triangles)
x = [0 1 0 -1];
y = [0 0 1  1];
T = [1 1 2 3 1;
     2 3 4 1 1];
z = [0 1 0 -1];  // values of the func at each vertices
clf()
gcf().color_map = jet(64);
subplot(1,2,1)
  colorbar(-1,1)
  fec(x,y,T,z,strf="040",mesh=%t)
  xtitle("fec example (with the mesh)")
subplot(1,2,2)
  colorbar(-1,1)
  fec(x,y,T,z,strf="040")  // rmq: mesh=%f by default
  xtitle("fec example (without the mesh)")
show_window()
 ]]></programlisting>
        <scilab:image>
            x = [0 1 0 -1];
            y = [0 0 1  1];
            T = [1 1 2 3 1;
            2 3 4 1 1];
            z = [0 1 0 -1];  // values of the func at each vertices
            clf()
            gcf().color_map = jet(64);
            subplot(1,2,1)
            colorbar(-1,1)
            fec(x,y,T,z,strf="040",mesh=%t)
            xtitle("fec example (with the mesh)")
            subplot(1,2,2)
            colorbar(-1,1)
            fec(x,y,T,z,strf="040")  // rmq: mesh=%f by default
            xtitle("fec example (without the mesh)")
            show_window()
        </scilab:image>
        <programlisting role="example"><![CDATA[
// define a mini triangulation (4 vertices, 2 triangles)
x = [0 1 0 -1];
y = [0 0 1  1];
T = [1 1 2 3 1;
     2 3 4 1 1];
z = [0 1 0 -1];  // values of the func at each vertices
// this example shows the effect of zminmax and uses the
// previous example data (you have to execute the it before)
clf()
gcf().color_map = jet(64);
colorbar(-0.5,0.5)  // be careful colorbar must be set by hands !
fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], mesh=%t)
xtitle("fec example : using zminmax argument")
show_window()
 ]]></programlisting>
        <scilab:image>
            x = [0 1 0 -1];
            y = [0 0 1  1];
            T = [1 1 2 3 1;
            2 3 4 1 1];
            z = [0 1 0 -1];  // values of the func at each vertices
            // this example shows the effect of zminmax and uses the
            // previous example data (you have to execute the it before)
            clf()
            gcf().color_map = jet(64);
            colorbar(-0.5,0.5)  // be careful colorbar must be set by hands !
            fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], mesh=%t)
            xtitle("fec example : using zminmax argument")
            show_window()
        </scilab:image>
        <programlisting role="example"><![CDATA[
// define a mini triangulation (4 vertices, 2 triangles)
x = [0 1 0 -1];
y = [0 0 1  1];
T = [1 1 2 3 1;
     2 3 4 1 1];
z = [0 1 0 -1];  // values of the func at each vertices
// this example shows the effect of zminmax and colout. It uses
// also the data of the first example (you have to execute the it before)
clf()
gcf().color_map = jet(64);
subplot(2,2,1)
  colorbar(-0.5,0.5)
  fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 0], mesh=%t)
  xtitle("fec : using zminmax and colout =[0 0]")
subplot(2,2,2)
  colorbar(-0.5,0.5)
  fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[32 32], mesh=%t)
  xtitle("fec : using zminmax and colout =[32 32]")
subplot(2,2,3)
  colorbar(-0.5,0.5)
  fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[-1 0], mesh=%t)
  xtitle("fec : using zminmax and colout =[-1 0]")
subplot(2,2,4)
  colorbar(-0.5,0.5)
  fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 -1], mesh=%t)
  xtitle("fec : using zminmax and colout =[0 -1]")
show_window()
 ]]></programlisting>
        <scilab:image>
            // define a mini triangulation (4 vertices, 2 triangles)
            x = [0 1 0 -1];
            y = [0 0 1  1];
            T = [1 1 2 3 1;
            2 3 4 1 1];
            z = [0 1 0 -1];  // values of the func at each vertices
            // this example shows the effect of zminmax and colout. It uses
            // also the data of the first example (you have to execute the it before)
            clf()
            gcf().color_map = jet(64);
            subplot(2,2,1)
            colorbar(-0.5,0.5)
            fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 0], mesh=%t)
            xtitle("fec : using zminmax and colout =[0 0]")
            subplot(2,2,2)
            colorbar(-0.5,0.5)
            fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[32 32], mesh=%t)
            xtitle("fec : using zminmax and colout =[32 32]")
            subplot(2,2,3)
            colorbar(-0.5,0.5)
            fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[-1 0], mesh=%t)
            xtitle("fec : using zminmax and colout =[-1 0]")
            subplot(2,2,4)
            colorbar(-0.5,0.5)
            fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 -1], mesh=%t)
            xtitle("fec : using zminmax and colout =[0 -1]")
            show_window()
        </scilab:image>
        <programlisting role="example"><![CDATA[
// define a mini triangulation (4 vertices, 2 triangles)
x = [0 1 0 -1];
y = [0 0 1  1];
T = [1 1 2 3 1;
     2 3 4 1 1];
z = [0 1 0 -1];  // values of the func at each vertices

// this example shows a feature from colminmax:
// playing with 2 colormaps for 2 subplots. It
// uses also the data of the first example.
clf()
gcf().color_map = [hot(64); jet(64)];
subplot(1,2,1)
  colorbar(-1,1,[1 64])
  fec(x,y,T,z,strf="040", colminmax=[1 64], mesh=%t)
  xtitle("fec using the hot colormap")
subplot(1,2,2)
  colorbar(-1,1,[65 128])
  fec(x,y,T,z,strf="040", colminmax=[65 128], mesh=%t)
  xtitle("fec using the jet colormap")
show_window()
 ]]></programlisting>
        <scilab:image>
            // define a mini triangulation (4 vertices, 2 triangles)
            x = [0 1 0 -1];
            y = [0 0 1  1];
            T = [1 1 2 3 1;
            2 3 4 1 1];
            z = [0 1 0 -1];  // values of the func at each vertices

            // this example shows a feature from colminmax:
            // playing with 2 colormaps for 2 subplots. It
            // uses also the data of the first example.
            clf()
            gcf().color_map = [hot(64); jet(64)];
            subplot(1,2,1)
            colorbar(-1,1,[1 64])
            fec(x,y,T,z,strf="040", colminmax=[1 64], mesh=%t)
            xtitle("fec using the hot colormap")
            subplot(1,2,2)
            colorbar(-1,1,[65 128])
            fec(x,y,T,z,strf="040", colminmax=[65 128], mesh=%t)
            xtitle("fec using the jet colormap")
            show_window()
        </scilab:image>
        <programlisting role="example"><![CDATA[
// define a mapping with one quadrangle (4 vertices, 1 quadrangle)
x = [1 2 2 1];
y = [1 1 2 2];
T = [1 1 2 3 4 0];
z = [-1; -1; 1; 1];  // values of the func at each vertices

clf()
f = gcf();
f.color_map = jet(12);
colorbar(-1,1);
fec(x,y,T,z,mesh=%t)
xtitle("fec using the hot colormap, composed by one quadrangle")
 ]]></programlisting>
        <scilab:image>
            // define a mapping with one quadrangle (4 vertices, 1 quadrangle)
            x = [1 2 2 1];
            y = [1 1 2 2];
            T = [1 1 2 3 4 0];
            z = [-1 -1 1 1];  // values of the func at each vertices

            clf()
            f = gcf();
            f.color_map = jet(12);
            colorbar(-1,1);
            fec(x,y,T,z,mesh=%t)
            xtitle("fec using the hot colormap, composed by one quadrangle")
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="colorbar">colorbar</link>
            </member>
            <member>
                <link linkend="Sfgrayplot">Sfgrayplot</link>
            </member>
            <member>
                <link linkend="Sgrayplot">Sgrayplot</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.2</revnumber>
                <revremark>
                    <para>
                        Mapping is not limited on triangles anymore. All types of convex polygons are acceptable.
                    </para>
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
