<?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
<!DOCTYPE MAN SYSTEM "../../manrev.dtd">
<MAN>
  <LANGUAGE>eng</LANGUAGE>
  <TITLE>fec</TITLE>
  <TYPE>Scilab Function</TYPE>
  <DATE>April 1993</DATE>
  <SHORT_DESCRIPTION name="fec"> pseudo-color plot of a function defined on a triangular mesh</SHORT_DESCRIPTION>
  <CALLING_SEQUENCE>
    <CALLING_SEQUENCE_ITEM>fec(x,y,triangles,func,&lt;opt_args&gt;)  </CALLING_SEQUENCE_ITEM>
    <CALLING_SEQUENCE_ITEM>fec(x,y,triangles,func,[strf,leg,rect,nax,zminmax,colminmax,colout,mesh])  </CALLING_SEQUENCE_ITEM>
  </CALLING_SEQUENCE>
  <PARAM>
    <PARAM_INDENT>
      <PARAM_ITEM>
        <PARAM_NAME>x,y</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: two vectors of size <VERB>n</VERB>, <VERB>(x(i),y(i))</VERB> gives the coordinates of 
                node  <VERB>i</VERB></SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>func</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: a vector of size <VERB>n</VERB> : <VERB>func(i)</VERB> gives the value at node <VERB>i</VERB>
                of the function for which we want the pseudo-color plot.</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>triangles</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: is a <VERB>[Ntr,5]</VERB> matrix. Each line of <VERB>triangles</VERB> specifies a triangle 
                of the  mesh <VERB>triangle(j) = [number,node1,node2,node3,flag]</VERB>. 
                <VERB>node1,node2,node3</VERB> are the number of the nodes which constitutes 
                the triangle. number is the number of the triangle and flag is an integer 
                not used in the fec function</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>

      <PARAM_ITEM>
        <PARAM_NAME>&lt;opt_args&gt;</PARAM_NAME>

        <PARAM_DESCRIPTION>
          <SP>: This represents a sequence of statements <VERB>key1=value1, key2=value2</VERB>,... where <VERB>key1</VERB>,
          <VERB>key2,...</VERB> can be one of the following: strf, leg, rect, nax, zminmax, colminmax, colout, mesh
          (see <LINK>plot2d</LINK> for the 4 first ones).</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>strf,leg,rect,nax</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: see plot2d</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>zminmax</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: vector with 2 components [zmin zmax] (useful in particular for animation)</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>colminmax</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: vector of 2 positives integers [colmin colmax]</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>colout</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: vector of 2 integers [under_min_col upper_max_col]</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
      <PARAM_ITEM>
        <PARAM_NAME>mesh</PARAM_NAME>
        <PARAM_DESCRIPTION>
          <SP>: boolean scalar, default value %f (must be true if you want also display the mesh)</SP>
        </PARAM_DESCRIPTION>
      </PARAM_ITEM>
    </PARAM_INDENT>
  </PARAM>
  <DESCRIPTION>
    <P>This function is the good one to draw linear triangular finite element solutions 
       or simply to display a function defined on a triangulation. The color interpolation
      is done through software computation and so it is not too fast.</P>

    <P>The function <LINK>colorbar</LINK> may be used to see the color scale (see the example
       section).</P>

    <P>    
    The <VERB>zminmax</VERB> 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 
    <EM>dz = (zmax-zmin)/nc</EM>, then the part of the triangulation where  
    <EM>zmin + (i-1)dz &lt;= z &lt; zmin + i dz</EM> is filled with the color <EM>i</EM>). 
    By default <EM>zmin = min(func)</EM> and <EM>zmax = max(func)</EM>. If you want to do 
    an animation with func values that varie in time, take for zmin and zmax the global 
    minimum and maximum or something close.
    </P>
    <P>
    The <VERB>colout</VERB> argument lets the user choosing the colors for the 2 extremes
    regions <EM>{func &lt; zmin}</EM> and <EM>{func &gt; zmax}</EM>, <VERB>under_min_col</VERB> and 
    <VERB>upper_max_col</VERB> may be equal (independantly) to:
    </P>
    <ITEMIZE>
       <ITEM label="-1">
            <SP>: in this case the same color than in the neighbouring zone is used (CAUTION: 
                  you don't see that the corresponding limit is crossed), this is the
                  default case.</SP>
       </ITEM>
       <ITEM label="0">
            <SP>: in this case the extreme region is not painting at all.</SP>
       </ITEM>
       <ITEM label="k">
            <SP>: (k being a valid index to a color of the current colormap) the extreme region
                  is painting in color k.</SP>
       </ITEM>
     </ITEMIZE>
    <P>If you don't want to use the complete colormap you may use the <VERB>colminmax</VERB>
    argument with <EM>1 &lt;= colmin &lt; colmax &lt;= nc</EM> (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).
    </P>
    <P>
    See the demo files <VERB>demos/fec</VERB>:</P>
    <P><VERB>fec.ex1</VERB> is a simple demo file in which a mesh and a function 
    on that mesh is completely built in Scilab syntax</P>
    <P><VERB>fec.ex2</VERB> 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 <VERB>macros.sci</VERB>) can be used to read the 
    data files in Scilab and plot the results.</P>
  </DESCRIPTION>
  <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
xbasc()
xset("colormap",jetcolormap(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)")
xselect()


// this example shows the effect of zminmax and uses the
// previous example datas (you have to execute the it before)
xbasc()
xset("colormap",jetcolormap(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")
xselect()


// this example shows the effect of zminmax and colout. It uses
// also the datas of the first example (you have to execute the it before)
xbasc()
xset("colormap",jetcolormap(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 example : 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 example : 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 example : 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 example : using zminmax and colout =[0 -1]")
xselect()


// this example shows a feature from colminmax:
// playing with 2 colormaps for 2 subplots. It
// uses also the data of the first example.
xbasc()
xset("colormap",[hotcolormap(64);jetcolormap(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")
xselect()
  ]]></EXAMPLE>

  <SEE_ALSO>
    <SEE_ALSO_ITEM>
      <LINK>colorbar</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>Sfgrayplot</LINK>
    </SEE_ALSO_ITEM>
    <SEE_ALSO_ITEM>
      <LINK>Sgrayplot</LINK>
    </SEE_ALSO_ITEM>
  </SEE_ALSO>
</MAN>
