Bug 8611 fixed: Fix path of images in documentation
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / surf.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 Fabrice Leray
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" xml:lang="en" xml:id="surf">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>surf</refname>
19     <refpurpose>3D surface plot</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>surf(Z,&lt;GlobalProperty&gt;)
24 surf(Z,color,&lt;GlobalProperty&gt;)
25 surf(X,Y,Z,&lt;color&gt;,&lt;GlobalProperty&gt;)
26 surf(&lt;axes_handle&gt;,...)</synopsis>
27   </refsynopsisdiv>
28   <refsection>
29     <title>Arguments</title>
30     <variablelist>
31       <varlistentry>
32         <term>Z</term>
33         <listitem>
34           <para>a real matrix defining the surface height. It can not be
35           omitted. The Z data is a<literal> m</literal>x<literal>n</literal> matrix.</para>
36         </listitem>
37       </varlistentry>
38       <varlistentry>
39         <term>X,Y</term>
40         <listitem>
41           <para>two real matrices or vectors: always set together, these data
42           defines a new standard grid. This new <literal>X</literal> and
43           <literal>Y</literal> components of the grid must match <literal>Z</literal>
44           dimensions (see description below).</para>
45         </listitem>
46       </varlistentry>
47       <varlistentry>
48         <term>color</term>
49         <listitem>
50           <para>an optional real matrix defining a color value for each
51           <literal>(X(j),Y(i))</literal> point of the grid (see description
52           below).</para>
53         </listitem>
54       </varlistentry>
55       <varlistentry>
56         <term>&lt;GlobalProperty&gt;</term>
57         <listitem>
58           <para>This optional argument represents a sequence of couple
59           statements <literal>{PropertyName,PropertyValue}</literal> that defines
60           global objects' properties applied to all the curves created by this
61           plot. For a complete view of the available properties (see
62           <link linkend="GlobalProperty">GlobalProperty</link>).</para>
63         </listitem>
64       </varlistentry>
65       <varlistentry>
66         <term>&lt;axes_handle&gt;</term>
67         <listitem>
68           <para>This optional argument forces the plot to appear inside the
69           selected axes given by <literal>axes_handle</literal> rather than the
70           current axes (see <link linkend="gca">gca</link>).</para>
71         </listitem>
72       </varlistentry>
73     </variablelist>
74   </refsection>
75   <refsection>
76     <title>Description</title>
77     <para><literal>surf</literal> draws a colored parametric surface using a
78     rectangular grid defined by <literal>X</literal> and <literal>Y</literal> coordinates
79     (if <literal>{X,Y}</literal> are not specified, this grid is determined using
80     the dimensions of the <literal>Z</literal> matrix) ; at each point of this grid,
81     a Z coordinate is given using the <literal>Z</literal> matrix (only obligatory
82     data). <literal>surf</literal> has been created to better handle Matlab syntax.
83     To improve graphical compatibility, Matlab users should use
84     <literal>surf</literal> (rather than <link linkend="plot3d">plot3d</link>).</para>
85     <para>Data entry specification :</para>
86     <para>In this paragraph and to be more clear, we won't mention
87     <literal>GlobalProperty</literal> optional arguments as they do not interfer
88     with entry data (except for <literal>"Xdata"</literal>, <literal>"Ydata"</literal> and
89     <literal>"Zdata"</literal> property, see <link linkend="GlobalProperty">GlobalProperty</link>). It is
90     assumed that all those optional arguments could be present too.</para>
91     <para>If <literal>Z</literal> is the only matrix specified, surf(Z) plots the
92     matrix <literal>Z</literal> versus the grid defined by <literal>1:size(Z,2)</literal>
93     along the x axis and <literal>1:size(Z,1)</literal> along the y axis.</para>
94     <para>If a <literal>{X,Y,Z}</literal> triplet is given, <literal>Z</literal> must be a
95     matrix with size(<literal>Z</literal>)= [<literal>m</literal>x<literal>n</literal>],
96     <literal>X</literal> or <literal>Y</literal> can be :</para>
97     <itemizedlist>
98       <listitem>
99         <para>a) a vector : if <literal>X</literal> is a vector,
100         length(<literal>X</literal>)=<literal>n</literal>. Respectively, if <literal>Y</literal>
101         is a vector, length(<literal>Y</literal>)=<literal>m</literal>.</para>
102         <para>b) a matrix : in this case, size(<literal>X</literal>) (or
103         size(<literal>Y</literal>)) must equal size(<literal>Z</literal>).</para>
104       </listitem>
105     </itemizedlist>
106     <para>Color entry specification :</para>
107     <para>As stated before, the surface is created over a rectangular grid
108     support. Let consider two independant variables <literal>i</literal> and
109     <literal>j</literal> such as :</para>
110     <para>
111       <inlinemediaobject>
112         <imageobject>
113           <imagedata fileref="../../images/surf_01.gif"/>
114         </imageobject>
115       </inlinemediaobject>
116     </para>
117     <para>This imaginary rectangular grid is used to build the real surface
118     support onto the <literal>XY</literal> plane. Indeed,
119     <literal>X</literal>,<literal>Y</literal> and <literal>Z</literal> data have the same size
120     (even if <literal>X</literal> or <literal>Y</literal> is vector, see below) and can be
121     considered as 3 functions <literal>x(i,j)</literal>, <literal>y(i,j)</literal> and
122     <literal>z(i,j)</literal> specifying the desired surface. If <literal>X</literal> or
123     <literal>Y</literal> are vectors, they are internally treated to produce good
124     matrices matching the <literal>Z</literal> matrix dimension (and the grid is
125     forcibly a rectangular region).</para>
126     <para>Considering the 3 functions <literal>x(i,j)</literal>, <literal>y(i,j)</literal>
127     and <literal>z(i,j)</literal>, the portion of surface defining between two
128     consecutive <literal>i</literal> and <literal>j</literal> is called a patch.</para>
129     <para>By default, when no color matrix is added to a surf call, the color
130     parameter is linked to the <literal>Z</literal> data. When a <literal>color</literal>
131     matrix is given, it can be applied to the patch in two different ways : at
132     the vertices or at the center of each patch.</para>
133     <para>That is why, if <literal>Z</literal> is a [<literal>m</literal>x<literal>n</literal>]
134     matrix, the <literal>C color</literal> matrix dimension can be
135     [<literal>m</literal>x<literal>n</literal>] (one color defined per vertex) or
136     [<literal>m-1</literal>x<literal>n-1</literal>] (one color per patch).</para>
137     <para>Color representation also varies when specifying some
138     GlobalPropery:</para>
139     <para>The <literal>FaceColor</literal> property sets the shading mode : it can
140     be<literal> 'interp'</literal> or <literal>'flat'</literal> (default mode). When
141     <literal>'interp'</literal> is selected, we perform a bilinear color
142     interpolation onto the patch. If size(<literal>C</literal>) equals
143     size(<literal>Z</literal>)-1 (i.e. we provided only one color per patch) then
144     the color of the vertices defining the patch is set to the given color of
145     the patch.</para>
146     <para>When <literal>'flat'</literal> (default mode) is enabled we use a color
147     faceted representation (one color per patch). If size(<literal>C</literal>)
148     equals size(<literal>Z</literal>) (i.e. we provided only one color per
149     vertices), the last row and column of <literal>C</literal> are ignored.</para>
150     <para/>
151     <para>The <literal>GlobalProperty</literal> arguments sould be used to customize
152     the surface. Here is a brief description on how it works:</para>
153     <variablelist>
154       <varlistentry>
155         <term>GlobalProperty</term>
156         <listitem>
157           <para>This option may be used to specify how all the surfaces are
158         drawn. It must always be a couple statement constituted of a string
159         defining the <literal>PropertyName</literal>, and its associated value
160         <literal>PropertyValue</literal> (which can be a string or an integer or...
161         as well depending on the type of the <literal>PropertyName</literal>). Note
162         that you can set multiple properties : the face &amp; edge color,
163         color data, color data mapping, marker color (foreground and
164         background), the visibility, clipping and thickness of the edges of
165         the surface... (see <link linkend="GlobalProperty">GlobalProperty</link> )</para>
166           <para>Note that all these properties can be (re-)set throught the surface
167         entity properties (see <link linkend="surface_properties">surface_properties</link>).</para>
168         </listitem>
169       </varlistentry>
170     </variablelist>
171   </refsection>
172   <refsection>
173     <title>Remarks</title>
174     <para>By default, successive surface plots are superposed. To clear the
175     previous plot, use <literal>clf()</literal>. To enable <literal>auto_clear</literal>
176     mode as the default mode, edit your default axes doing:</para>
177     <para>da=gda();</para>
178     <para>da.auto_clear = 'on'</para>
179     <para>Enter the command <literal>surf</literal> to see a demo.</para>
180   </refsection>
181   <refsection>
182     <title>Examples</title>
183     <programlisting role="example"><![CDATA[ 
184 // Z initialisation 
185
186 Z= [   0.0001    0.0013    0.0053   -0.0299   -0.1809   -0.2465   -0.1100   -0.0168   -0.0008   -0.0000
187     0.0005    0.0089    0.0259   -0.3673   -1.8670   -2.4736   -1.0866   -0.1602   -0.0067    0.0000
188     0.0004    0.0214    0.1739   -0.3147   -4.0919   -6.4101   -2.7589   -0.2779    0.0131    0.0020
189    -0.0088   -0.0871    0.0364    1.8559    1.4995   -2.2171   -0.2729    0.8368    0.2016    0.0130
190    -0.0308   -0.4313   -1.7334   -0.1148    3.0731    0.4444    2.6145    2.4410    0.4877    0.0301
191    -0.0336   -0.4990   -2.3552   -2.1722    0.8856   -0.0531    2.6416    2.4064    0.4771    0.0294
192    -0.0137   -0.1967   -0.8083    0.2289    3.3983    3.1955    2.4338    1.2129    0.2108    0.0125
193    -0.0014   -0.0017    0.3189    2.7414    7.1622    7.1361    3.1242    0.6633    0.0674    0.0030
194     0.0002    0.0104    0.1733    1.0852    2.6741    2.6725    1.1119    0.1973    0.0152    0.0005
195     0.0000    0.0012    0.0183    0.1099    0.2684    0.2683    0.1107    0.0190    0.0014    0.0000];
196
197 //simple surface
198 surf(Z); // Note that X and Y are determined by Z dimensions
199
200 //same surface with red face color and blue edges
201 scf(2); // new figure number 2
202 surf(Z,'facecol','red','edgecol','blu")
203
204 // X and Y initialisation
205 // NB: here, X has the same lines and Y the same columns
206 X = [ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
207    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
208    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
209    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
210    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
211    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
212    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
213    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
214    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
215    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
216
217 Y= [   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000
218    -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333
219    -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667
220    -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000
221    -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333
222     0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333
223     1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
224     1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667
225     2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333
226     3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000];
227
228 // example 1
229 scf(3)
230 surf(X,Y,Z)
231
232 //example 2
233 // As you can see, the grid is not necessary rectangular
234 scf(4)
235 X(1,4) = -1.5;
236 Y(1,4) = -3.5;
237 Z(1,4) = -2;
238 surf(X,Y,Z)
239
240 // example 3
241 // X and Y are vectors => same behavior as sample 1
242 // With vectors, the grid is inevitably rectangular
243 scf(5)// new figure number 5
244 X=[ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
245 Y=X;
246 surf(X,Y,Z)
247
248 //LineSpec and GlobalProperty examples:
249 xdel(winsid()) // destroy all existing figures
250 surf(Z,Z+5) // color array specified
251 e=gce();
252 e.cdata_mapping='direct' // default is 'scaled' relative to the colormap
253 e.color_flag=3; // interpolated shading mode. The default is 4 ('flat' mode) for surf
254
255 scf(2)
256 surf(X,Y,Z,'colorda',ones(10,10),'edgeco','cya','marker','penta','markersiz',20,'markeredg','yel','ydata',56:65)
257
258 scf(3)
259 surf(Z,'cdatamapping','direct')
260 scf(4)
261 surf(Z,'facecol','interp') // interpolated shading mode (color_flag == 3)
262
263 scf(10)
264 axfig10=gca();
265 scf(11);
266 surf(axfig10,Z,'ydat',[100:109],'marker','d','markerfac','green','markeredg','yel') // draw onto the axe of figure 10
267
268 xdel(winsid())
269  ]]></programlisting>
270   </refsection>
271   <refsection>
272     <title>See Also</title>
273     <simplelist type="inline">
274       <member>
275         <link linkend="plot2d">plot2d</link>
276       </member>
277       <member>
278         <link linkend="clf">clf</link>
279       </member>
280       <member>
281         <link linkend="xdel">xdel</link>
282       </member>
283       <member>
284         <link linkend="delete">delete</link>
285       </member>
286       <member>
287         <link linkend="LineSpec">LineSpec</link>
288       </member>
289       <member>
290         <link linkend="GlobalProperty">GlobalProperty</link>
291       </member>
292     </simplelist>
293   </refsection>
294   <refsection>
295     <title>Authors</title>
296     <para>F.Leray</para>
297   </refsection>
298 </refentry>