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