3f6ef74833323f5f9032d7fd92ac9183ee975cdd
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / fec.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="fec">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>fec</refname>
19     <refpurpose> pseudo-color plot of a function defined on a triangular mesh</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>fec(x,y,triangles,func,&lt;opt_args&gt;)
24 fec(x,y,triangles,func,[strf,leg,rect,nax,zminmax,colminmax,colout,mesh])</synopsis>
25   </refsynopsisdiv>
26   <refsection>
27     <title>Arguments</title>
28     <variablelist>
29       <varlistentry>
30         <term>x,y</term>
31         <listitem>
32           <para>two vectors of size <literal>n</literal>, <literal>(x(i),y(i))</literal> gives the coordinates of 
33                 node  <literal>i</literal></para>
34         </listitem>
35       </varlistentry>
36       <varlistentry>
37         <term>func</term>
38         <listitem>
39           <para>a vector of size <literal>n</literal> : <literal>func(i)</literal> gives the value at node <literal>i</literal>
40                 of the function for which we want the pseudo-color plot.</para>
41         </listitem>
42       </varlistentry>
43       <varlistentry>
44         <term>triangles</term>
45         <listitem>
46           <para>is a <literal>[Ntr,5]</literal> matrix. Each line of <literal>triangles</literal> specifies a triangle 
47                 of the  mesh <literal>triangle(j) = [number,node1,node2,node3,flag]</literal>. 
48                 <literal>node1,node2,node3</literal> are the number of the nodes which constitutes 
49                 the triangle. number is the number of the triangle and flag is an integer 
50                 not used in the fec function</para>
51         </listitem>
52       </varlistentry>
53       <varlistentry>
54         <term>&lt;opt_args&gt;</term>
55         <listitem>
56           <para>This represents a sequence of statements <literal>key1=value1, key2=value2</literal>,... where <literal>key1</literal>,
57           <literal>key2,...</literal> can be one of the following: strf, leg, rect, nax, zminmax, colminmax, colout, mesh
58           (see <link linkend="plot2d">plot2d</link> for the 4 first ones).</para>
59         </listitem>
60       </varlistentry>
61       <varlistentry>
62         <term>strf,leg,rect,nax</term>
63         <listitem>
64           <para>see plot2d</para>
65         </listitem>
66       </varlistentry>
67       <varlistentry>
68         <term>zminmax</term>
69         <listitem>
70           <para>vector with 2 components [zmin zmax] (useful in particular for animation)</para>
71         </listitem>
72       </varlistentry>
73       <varlistentry>
74         <term>colminmax</term>
75         <listitem>
76           <para>vector of 2 positives integers [colmin colmax]</para>
77         </listitem>
78       </varlistentry>
79       <varlistentry>
80         <term>colout</term>
81         <listitem>
82           <para>vector of 2 integers [under_min_col upper_max_col]</para>
83         </listitem>
84       </varlistentry>
85       <varlistentry>
86         <term>mesh</term>
87         <listitem>
88           <para>boolean scalar, default value %f (must be true if you want also display the mesh)</para>
89         </listitem>
90       </varlistentry>
91     </variablelist>
92   </refsection>
93   <refsection>
94     <title>Description</title>
95     <para>This function is the good one to draw linear triangular finite element solutions 
96        or simply to display a function defined on a triangulation. The color interpolation
97       is done through software computation and so it is not too fast.</para>
98     <para>The function <link linkend="colorbar">colorbar</link> may be used to see the color scale (see the example
99        section).</para>
100     <para>    
101     The <literal>zminmax</literal> argument gives the z values associated with the first and the last 
102     color (of the current colormap). More exactly if the colormap have nc colors and if we note 
103     <emphasis>dz = (zmax-zmin)/nc</emphasis>, then the part of the triangulation where  
104     <emphasis>zmin + (i-1)dz &lt;= z &lt; zmin + i dz</emphasis> is filled with the color <emphasis>i</emphasis>). 
105     By default <emphasis>zmin = min(func)</emphasis> and <emphasis>zmax = max(func)</emphasis>. If you want to do 
106     an animation with func values that varie in time, take for zmin and zmax the global 
107     minimum and maximum or something close.
108     </para>
109     <para>
110     The <literal>colout</literal> argument lets the user choosing the colors for the 2 extremes
111     regions <emphasis>{func &lt; zmin}</emphasis> and <emphasis>{func &gt; zmax}</emphasis>, <literal>under_min_col</literal> and 
112     <literal>upper_max_col</literal> may be equal (independantly) to:
113     </para>
114     <variablelist>
115       <varlistentry>
116         <term>-1</term>
117         <listitem>
118           <para>in this case the same color than in the neighbouring zone is used (CAUTION: 
119                   you do not see that the corresponding limit is crossed), this is the
120                   default case.</para>
121         </listitem>
122       </varlistentry>
123       <varlistentry>
124         <term>0</term>
125         <listitem>
126           <para>in this case the extreme region is not painting at all.</para>
127         </listitem>
128       </varlistentry>
129       <varlistentry>
130         <term>k</term>
131         <listitem>
132           <para>(k being a valid index to a color of the current colormap) the extreme region
133                   is painting in color k.</para>
134         </listitem>
135       </varlistentry>
136     </variablelist>
137     <para>If you do not want to use the complete colormap you may use the <literal>colminmax</literal>
138     argument with <emphasis>1 &lt;= colmin &lt; colmax &lt;= nc</emphasis> (nc being the number of colors 
139     of the current colormap) so as to use only the [colmin,colmax]  sub-part of the colormap.
140     (by default all the colors of the colormap are used).
141     </para>
142     <para>
143     See the demo files <literal>demos/fec</literal>:</para>
144     <para><literal>fec.ex1</literal> is a simple demo file in which a mesh and a function 
145     on that mesh is completely built in Scilab syntax</para>
146     <para><literal>fec.ex2</literal> is an example for which the mesh and the function value where 
147     computed by an external mesh builder (amdba type mesh) and an external program.
148     A set of macros ( provided in file <literal>macros.sci</literal>) can be used to read the 
149     data files in Scilab and plot the results.</para>
150   </refsection>
151   <refsection>
152     <title>Examples</title>
153     <programlisting role="example"><![CDATA[ 
154 // define a mini triangulation (4 vertices, 2 triangles)
155 x = [0 1 0 -1];
156 y = [0 0 1  1];
157 T = [1 1 2 3 1;
158      2 3 4 1 1];
159 z = [0 1 0 -1];  // values of the func at each vertices
160 clf()
161 xset("colormap",jetcolormap(64))
162 subplot(1,2,1)
163   colorbar(-1,1)
164   fec(x,y,T,z,strf="040",mesh=%t)
165   xtitle("fec example (with the mesh)")
166 subplot(1,2,2)
167   colorbar(-1,1)
168   fec(x,y,T,z,strf="040")  // rmq: mesh=%f by default
169   xtitle("fec example (without the mesh)")
170 show_window()
171
172 // this example shows the effect of zminmax and uses the
173 // previous example data (you have to execute the it before)
174 clf()
175 xset("colormap",jetcolormap(64))
176 colorbar(-0.5,0.5)  // be careful colorbar must be set by hands !
177 fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], mesh=%t)
178 xtitle("fec example : using zminmax argument")
179 show_window()
180
181 // this example shows the effect of zminmax and colout. It uses
182 // also the data of the first example (you have to execute the it before)
183 clf()
184 xset("colormap",jetcolormap(64))
185 subplot(2,2,1)
186   colorbar(-0.5,0.5)
187   fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 0], mesh=%t)
188   xtitle("fec example : using zminmax and colout =[0 0]")
189 subplot(2,2,2)
190   colorbar(-0.5,0.5)
191   fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[32 32], mesh=%t)
192   xtitle("fec example : using zminmax and colout =[32 32]")
193 subplot(2,2,3)
194   colorbar(-0.5,0.5)
195   fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[-1 0], mesh=%t)
196   xtitle("fec example : using zminmax and colout =[-1 0]")
197 subplot(2,2,4)
198   colorbar(-0.5,0.5)
199   fec(x,y,T,z,strf="040", zminmax=[-0.5 0.5], colout=[0 -1], mesh=%t)
200   xtitle("fec example : using zminmax and colout =[0 -1]")
201 show_window()
202
203 // this example shows a feature from colminmax:
204 // playing with 2 colormaps for 2 subplots. It
205 // uses also the data of the first example.
206 clf()
207 xset("colormap",[hotcolormap(64);jetcolormap(64)])
208 subplot(1,2,1)
209   colorbar(-1,1,[1 64])
210   fec(x,y,T,z,strf="040", colminmax=[1 64], mesh=%t)
211   xtitle("fec using the hot colormap")
212 subplot(1,2,2)
213   colorbar(-1,1,[65 128])
214   fec(x,y,T,z,strf="040", colminmax=[65 128], mesh=%t)
215   xtitle("fec using the jet colormap")
216 show_window()
217  ]]></programlisting>
218   </refsection>
219   <refsection role="see also">
220     <title>See Also</title>
221     <simplelist type="inline">
222       <member>
223         <link linkend="colorbar">colorbar</link>
224       </member>
225       <member>
226         <link linkend="Sfgrayplot">Sfgrayplot</link>
227       </member>
228       <member>
229         <link linkend="Sgrayplot">Sgrayplot</link>
230       </member>
231     </simplelist>
232   </refsection>
233 </refentry>