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