Revision of help page for contourf function (en_US).
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / contourf.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) ENPC - Jean-Philippe Chancelier
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:ns3="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="contourf" xml:lang="en">
14     <refnamediv>
15         <refname>contourf</refname>
16         <refpurpose>filled level curves of a surface on a 2D plot</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>
21             contourf(x, y, z, nz, [style, strf, leg, rect, nax])
22         </synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>x, y</term>
29                 <listitem>
30                     <para>
31                         two real row vectors of size <literal>n1</literal> and <literal>n2</literal>: the grid.
32                     </para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>z</term>
37                 <listitem>
38                     <para>
39                         a real matrix of size <literal>(n1,n2)</literal>, the
40                         values of the function.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>nz</term>
46                 <listitem>
47                     <para>the level values or the number of levels.</para>
48                     <variablelist>
49                         <varlistentry>
50                             <term>-</term>
51                             <listitem>
52                                 <para>
53                                     If <varname>nz</varname> is an integer, its
54                                     value gives the number of level curves
55                                     equally spaced from <literal>zmin</literal>
56                                     to <literal>zmax</literal> as follows:
57                                 </para>
58                                 <programlisting role="no-scilab-exec"><![CDATA[ 
59 z= zmin + (1:nz)*(zmax-zmin)/(nz+1)
60  ]]></programlisting>
61                                 <para>
62                                     <note>
63                                     Note: that the <literal>zmin</literal> and
64                                     <literal>zmax</literal> levels are not drawn
65                                     (generically they are reduced to points) but
66                                     they can be added with
67                                     </note>
68                                 </para>
69                                 <programlisting role="no-scilab-exec"><![CDATA[ 
70 [im,jm] = find(z == zmin);     // or zmax 
71 plot2d(x(im)',y(jm)',-9,"000")
72  ]]></programlisting>
73                             </listitem>
74                         </varlistentry>
75                         <varlistentry>
76                             <term>-</term>
77                             <listitem>
78                                 <para>
79                                     If <varname>nz</varname> is a vector,
80                                     <literal>nz(i)</literal> gives the value of
81                                     the <literal>i</literal>-th level curve.
82                                 </para>
83                             </listitem>
84                         </varlistentry>
85                     </variablelist>
86                 </listitem>
87             </varlistentry>
88             <varlistentry>
89                 <term>style, strf, leg, rect, nax</term>
90                 <listitem>
91                     <para>
92                         see <function>plot2d</function>. The argument
93                         <varname>style</varname> gives the colors which are to
94                         be used for level curves. It must have the same size as
95                         the number of levels.
96                     </para>
97                 </listitem>
98             </varlistentry>
99         </variablelist>
100     </refsection>
101     <refsection>
102         <title>Description</title>
103         <para>
104             <function>contourf</function> paints surface between two consecutive
105             level curves of a surface <literal>z=f(x,y)</literal> on a 2D plot.
106             The values of <literal>f(x,y)</literal> are given by the matrix
107             <varname>z</varname> at the grid points defined by
108             <varname>x</varname> and <varname>y</varname>.
109         </para>
110         <para>
111             You can change the format of the floating point number printed on
112             the levels by using <code>xset("fpf",string)</code> where
113             <varname>string</varname> gives the format in C format syntax (for
114             example <code>string="%.3f"</code>). Use <code>string=""</code> to
115             switch back to default format.
116         </para>
117         <para>
118             Enter the command <code>contourf()</code> to see a demo.
119         </para>
120     </refsection>
121     <refsection>
122         <title>Examples</title>
123         <programlisting role="example"><![CDATA[ 
124 contourf(1:10,1:10,rand(10,10),5,1:5,"011"," ",[0,0,11,11])
125  ]]></programlisting>
126         <scilab:image>
127             contourf(1:10,1:10,rand(10,10),5,1:5,"011"," ",[0,0,11,11])
128         </scilab:image>
129         <programlisting role="example"><![CDATA[ 
130 function z=peaks(x,y)
131 x1=x(:).*.ones(1,size(y,'*'));
132 y1=y(:)'.*.ones(size(x,'*'),1);
133 z =  (3*(1-x1).^2).*exp(-(x1.^2) - (y1+1).^2) ... 
134    - 10*(x1/5 - x1.^3 - y1.^5).*exp(-x1.^2-y1.^2) ... 
135    - 1/3*exp(-(x1+1).^2 - y1.^2) 
136 endfunction
137
138 function z=peakit()
139 x=-4:0.1:4;y=x;z=peaks(x,y);
140 endfunction
141
142 z=peakit();
143
144 levels=[-6:-1,-logspace(-5,0,10),logspace(-5,0,10),1:8];
145 m=size(levels,'*');
146 n = fix(3/8*m);
147 r = [(1:n)'/n; ones(m-n,1)];
148 g = [zeros(n,1); (1:n)'/n; ones(m-2*n,1)];
149 b = [zeros(2*n,1); (1:m-2*n)'/(m-2*n)];
150 h = [r g b];
151 xset('colormap',h);
152 xset('fpf',' ');
153 clf();
154 contourf([],[],z,[-6:-1,-logspace(-5,0,10),logspace(-5,0,10),1:8],0*ones(1,m))
155
156 xset('fpf','');
157 clf();
158 contourf([],[],z,[-6:-1,-logspace(-5,0,10),logspace(-5,0,10),1:8]);
159  ]]></programlisting>
160         <scilab:image>
161             function z=peaks(x,y)
162             x1=x(:).*.ones(1,size(y,'*'));
163             y1=y(:)'.*.ones(size(x,'*'),1);
164             z =  (3*(1-x1).^2).*exp(-(x1.^2) - (y1+1).^2) ... 
165             - 10*(x1/5 - x1.^3 - y1.^5).*exp(-x1.^2-y1.^2) ... 
166             - 1/3*exp(-(x1+1).^2 - y1.^2) 
167             endfunction
168             
169             function z=peakit()
170             x=-4:0.1:4;y=x;z=peaks(x,y);
171             endfunction
172             
173             z=peakit();
174             
175             levels=[-6:-1,-logspace(-5,0,10),logspace(-5,0,10),1:8];
176             m=size(levels,'*');
177             n = fix(3/8*m);
178             r = [(1:n)'/n; ones(m-n,1)];
179             g = [zeros(n,1); (1:n)'/n; ones(m-2*n,1)];
180             b = [zeros(2*n,1); (1:m-2*n)'/(m-2*n)];
181             h = [r g b];
182             xset('colormap',h);
183             xset('fpf',' ');
184             clf();
185             contourf([],[],z,[-6:-1,-logspace(-5,0,10),logspace(-5,0,10),1:8],0*ones(1,m))
186             
187         </scilab:image>
188     </refsection>
189     <refsection role="see also">
190         <title>See Also</title>
191         <simplelist type="inline">
192             <member>
193                 <link linkend="contour">contour</link>
194             </member>
195             <member>
196                 <link linkend="contour2d">contour2d</link>
197             </member>
198             <member>
199                 <link linkend="contour2di">contour2di</link>
200             </member>
201             <member>
202                 <link linkend="plot2d">plot2d</link>
203             </member>
204         </simplelist>
205     </refsection>
206 </refentry>