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