047aab6fc29c557a11fe40a0fa82aba1a65ac5a3
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / contour2di.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="contour2di">
14     <refnamediv>
15         <refname>contour2di</refname>
16         <refpurpose>compute level curves of a surface on a 2D plot</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[xc, yc] = contour2di(x, y, z, nz)</synopsis>
21     </refsynopsisdiv>
22     <refsection>
23         <title>Arguments</title>
24         <variablelist>
25             <varlistentry>
26                 <term>x, y</term>
27                 <listitem>
28                     <para>
29                         two real row vectors of size <literal>n1</literal> and <literal>n2</literal>: the grid.
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>z</term>
35                 <listitem>
36                     <para>
37                         a real matrix of size <literal>(n1,n2)</literal>, the
38                         values of the function.
39                     </para>
40                 </listitem>
41             </varlistentry>
42             <varlistentry>
43                 <term>nz</term>
44                 <listitem>
45                     <para>
46                         the level values or the number of levels.
47                     </para>
48                     <variablelist>
49                         <varlistentry>
50                             <term>
51                                 If <literal>nz</literal> is an integer
52                             </term>
53                             <listitem>
54                                 <para>
55                                     its value gives the number of
56                                     level curves  equally spaced from <literal>zmin</literal> 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>
77                                 If <literal>nz</literal> is a vector
78                             </term>
79                             <listitem>
80                                 <para>
81                                     <literal>nz(i)</literal> gives the value of
82                                     the <literal>i</literal>-th level curve.
83                                 </para>
84                             </listitem>
85                         </varlistentry>
86                     </variablelist>
87                 </listitem>
88             </varlistentry>
89             <varlistentry>
90                 <term>xc, yc</term>
91                 <listitem>
92                     <para>
93                         vectors of identical sizes containing the contours definitions. See below for details.
94                     </para>
95                 </listitem>
96             </varlistentry>
97         </variablelist>
98     </refsection>
99     <refsection>
100         <title>Description</title>
101         <para>
102             <function>contour2di</function> computes level curves of a surface
103             <literal>z = f(x, y)</literal> on a 2D plot.  The values of
104             <literal>f(x,y)</literal> are given by the matrix <varname>z</varname>
105             at the grid points defined by <varname>x</varname> and <varname>y</varname>.
106         </para>
107         <para>
108             <literal>xc(1)</literal> contains the level associated with first
109             contour path, <literal>yc(1)</literal> contains the number
110             <literal>N1</literal> of points defining this contour path and
111             (<literal>xc(1+(1:N1))</literal>, <literal>yc(1+(1:N1))</literal> )
112             contain the coordinates of the paths points. The second path begin
113             at <literal>xc(2+N1)</literal> and <literal>yc(2+N1)</literal> and
114             so on.
115         </para>
116     </refsection>
117     <refsection>
118         <title>Examples</title>
119         <programlisting role="example"><![CDATA[ 
120 [xc,yc]=contour2di(1:10,1:10,rand(10,10),5);
121 k=1;n=yc(k);c=1;
122 while k+yc(k)<size(xc,'*')
123   n=yc(k);
124   plot2d(xc(k+(1:n)),yc(k+(1:n)),c)
125   c=c+1;
126   k=k+n+1;
127 end
128  ]]></programlisting>
129     </refsection>
130     <refsection role="see also">
131         <title>See Also</title>
132         <simplelist type="inline">
133             <member>
134                 <link linkend="contour">contour</link>
135             </member>
136             <member>
137                 <link linkend="contour2d">contour2d</link>
138             </member>
139             <member>
140                 <link linkend="plot2d">plot2d</link>
141             </member>
142         </simplelist>
143     </refsection>
144 </refentry>