8f1c26fdbeca18f80650c497f4c6d9011074338b
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / contour2d.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: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="contour2d">
14     <refnamediv>
15         <refname>contour2d</refname>
16         <refpurpose>level curves of a surface on a 2D
17             plot
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>contour2d(x,y,z,nz,[style,strf,leg,rect,nax])
23             contour2d(x,y,z,nz,&lt;opt_args&gt;)
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>x,y</term>
31                 <listitem>
32                     <para>two real row vectors of size n1 and n2: the grid.</para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>z</term>
37                 <listitem>
38                     <para>real matrix of size (n1,n2), the values of the function on the
39                         grid or a  Scilab function which defines the surface  <literal>z=f(x,y)</literal>. 
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>nz</term>
45                 <listitem>
46                     <para>the level values or the number of levels.</para>
47                     <variablelist>
48                         <varlistentry>
49                             <term/>
50                             <listitem>
51                                 <para>
52                                     If <literal>nz</literal> is an integer, its value gives the
53                                     number of level curves equally spaced from zmin to zmax as
54                                     follows:
55                                 </para>
56                                 <programlisting role=""><![CDATA[ 
57 z= zmin + (1:nz)*(zmax-zmin)/(nz+1) 
58  ]]></programlisting>
59                                 <para>
60                                     Note that the <literal>zmin</literal> and <literal>zmax</literal>
61                                     levels are not drawn (generically they are reduced to points)
62                                     but they can be added with
63                                 </para>
64                                 <programlisting role=""><![CDATA[ 
65 [im,jm] = find(z == zmin); // or zmax
66 plot2d(x(im)',y(jm)',-9,"000")
67  ]]></programlisting>
68                             </listitem>
69                         </varlistentry>
70                         <varlistentry>
71                             <term/>
72                             <listitem>
73                                 <para>
74                                     If <literal>nz</literal> is a vector, <literal>nz(i)</literal> gives
75                                     the value of the ith level curve.
76                                 </para>
77                             </listitem>
78                         </varlistentry>
79                     </variablelist>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>&lt;opt_args&gt;</term>
84                 <listitem>
85                     <para>This represents a sequence of statements 
86                         <literal>key1=value1,key2=value2</literal>,... where <literal>key1</literal>,
87                         <literal>key2,...</literal> can be one of the following: style, leg, rect,
88                         nax, strf or axesflag and frameflag (see <link linkend="plot2d">plot2d</link>)
89                     </para>
90                 </listitem>
91             </varlistentry>
92             <varlistentry>
93                 <term>style,strf,leg,rect,nax</term>
94                 <listitem>
95                     <para>
96                         see <link linkend="plot2d">plot2d</link>. The argument <literal>style</literal> gives
97                         the dash styles or colors which are to be used for level curves. It
98                         must have the same size as the number of levels.
99                     </para>
100                 </listitem>
101             </varlistentry>
102         </variablelist>
103     </refsection>
104     <refsection>
105         <title>Description</title>
106         <para>
107             <literal>contour2d</literal> draws level curves of a surface
108             <literal>z=f(x,y)</literal> on a 2D plot. The values of <literal>f(x,y)</literal> are
109             given by the matrix <literal>z</literal> at the grid points defined by
110             <literal>x</literal> and <literal>y</literal>.
111         </para>
112         <para>You can change the format of the floating point number printed on the
113             levels by using <literal>xset("fpf",string)</literal> where <literal>string</literal>
114             gives the format in C format syntax (for example
115             <literal>string="%.3f"</literal>). Use <literal>string=""</literal> to switch back to
116             default format and Use <literal>string=" "</literal> to suppress printing. This
117             last feature is useful in conjunction with <link linkend="legends">legends</link> to display
118             the level numbers in a legend and not directly onto the level curves as 
119             usual (see Examples).
120         </para>
121         <para>
122             The optional arguments <literal>style,strf,leg,rect,nax</literal>, can be
123             passed by a sequence of statements <literal>key1=value1, key2=value2</literal>,
124             ... where keys may be
125             <literal>style</literal>,<literal>strf</literal>,<literal>leg</literal>,<literal>rect</literal>,<literal>nax</literal>.
126             In this case, the order has no special meaning.
127         </para>
128         <para>
129             Use <literal>contour</literal> to draw levels curves on a 3D surface.
130         </para>
131     </refsection>
132     <refsection>
133         <title>Examples</title>
134         <programlisting role="example"><![CDATA[
135 contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11])
136 // changing the format of the printing of the levels
137 xset("fpf","%.2f")
138  ]]></programlisting>
139         <scilab:image>
140             contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11]);
141             xset("fpf","%.2f")
142         </scilab:image>
143         <programlisting role="example"><![CDATA[
144 clf()
145 contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11])
146   ]]></programlisting>
147         <scilab:image>
148             contour2d(1:10,1:10,rand(10,10),5,rect=[0,0,11,11])
149         </scilab:image>
150         <programlisting role="example"><![CDATA[
151 // now an example with level numbers drawn in a legend
152 // Caution there are a number of tricks...
153 x = linspace(0,4*%pi,80);
154 z = cos(x')*cos(x);
155
156 clf(); f=gcf();
157 xset("fpf"," ")
158
159 // trick 1: this implies that the level numbers are not
160 //          drawn on the level curves
161 f.color_map=jetcolormap(7);
162
163 // trick 2: to be able to put the legend on the right without
164 //          interfering with the level curves use rect with a xmax
165 //          value large enough
166 contour2d(x,x,z,-0.75:0.25:0.75,frameflag=3,rect=[0,0,5*%pi,4*%pi])
167
168 // trick 3: use legends (note that the more practical legend function
169 //          will not work as soon as one of the level is formed by 2 curves)
170 legends(string(-0.75:0.25:0.75),1:7,"lr");
171 xtitle("Some level curves of the function cos(x)cos(y)")
172  ]]></programlisting>
173         <scilab:image>
174             x = linspace(0,4*%pi,80);
175             z = cos(x')*cos(x);
176             
177             clf(); f=gcf();
178             xset("fpf"," ")
179             
180             f.color_map=jetcolormap(7);
181             
182             contour2d(x,x,z,-0.75:0.25:0.75,frameflag=3,rect=[0,0,5*%pi,4*%pi])
183             
184             legends(string(-0.75:0.25:0.75),1:7,"lr");
185             xtitle("Some level curves of the function cos(x)cos(y)")
186         </scilab:image>
187     </refsection>
188     <refsection role="see also">
189         <title>See Also</title>
190         <simplelist type="inline">
191             <member>
192                 <link linkend="contour">contour</link>
193             </member>
194             <member>
195                 <link linkend="contour2di">contour2di</link>
196             </member>
197             <member>
198                 <link linkend="plot2d">plot2d</link>
199             </member>
200         </simplelist>
201     </refsection>
202 </refentry>