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
 218   <refsection>
 219     <title>Sample</title>
 220     <scilab:image>surf();</scilab:image>
 221   </refsection>
 222
 223   <refsection>
 224     <title>Examples</title>
 225     <programlisting role="example"><![CDATA[
 226 // Z initialisation
 227
 228 Z= [   0.0001    0.0013    0.0053   -0.0299   -0.1809   -0.2465   -0.1100   -0.0168   -0.0008   -0.0000
 229     0.0005    0.0089    0.0259   -0.3673   -1.8670   -2.4736   -1.0866   -0.1602   -0.0067    0.0000
 230     0.0004    0.0214    0.1739   -0.3147   -4.0919   -6.4101   -2.7589   -0.2779    0.0131    0.0020
 231    -0.0088   -0.0871    0.0364    1.8559    1.4995   -2.2171   -0.2729    0.8368    0.2016    0.0130
 232    -0.0308   -0.4313   -1.7334   -0.1148    3.0731    0.4444    2.6145    2.4410    0.4877    0.0301
 233    -0.0336   -0.4990   -2.3552   -2.1722    0.8856   -0.0531    2.6416    2.4064    0.4771    0.0294
 234    -0.0137   -0.1967   -0.8083    0.2289    3.3983    3.1955    2.4338    1.2129    0.2108    0.0125
 235    -0.0014   -0.0017    0.3189    2.7414    7.1622    7.1361    3.1242    0.6633    0.0674    0.0030
 236     0.0002    0.0104    0.1733    1.0852    2.6741    2.6725    1.1119    0.1973    0.0152    0.0005
 237     0.0000    0.0012    0.0183    0.1099    0.2684    0.2683    0.1107    0.0190    0.0014    0.0000];
 238
 239 //simple surface
 240 surf(Z); // Note that X and Y are determined by Z dimensions
 241
 242 //same surface with red face color and blue edges
 243 scf(2); // new figure number 2
 244 surf(Z,'facecol','red','edgecol','blu")
 245
 246 // X and Y initialisation
 247 // NB: here, X has the same lines and Y the same columns
 248 X = [ -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    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
 253    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
 254    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
 255    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
 256    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000
 257    -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
 258
 259 Y= [   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000   -3.0000
 260    -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333   -2.3333
 261    -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667   -1.6667
 262    -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000   -1.0000
 263    -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333   -0.3333
 264     0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333    0.3333
 265     1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
 266     1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667    1.6667
 267     2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333    2.3333
 268     3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000    3.0000];
 269
 270 // example 1
 271 scf(3)
 272 surf(X,Y,Z)
 273
 274 //example 2
 275 // As you can see, the grid is not necessary rectangular
 276 scf(4)
 277 X(1,4) = -1.5;
 278 Y(1,4) = -3.5;
 279 Z(1,4) = -2;
 280 surf(X,Y,Z)
 281
 282 // example 3
 283 // X and Y are vectors => same behavior as sample 1
 284 // With vectors, the grid is inevitably rectangular
 285 scf(5)// new figure number 5
 286 X=[ -3.0000   -2.3333   -1.6667   -1.0000   -0.3333    0.3333    1.0000    1.6667    2.3333    3.0000];
 287 Y=X;
 288 surf(X,Y,Z)
 289
 290 //LineSpec and GlobalProperty examples:
 291 xdel(winsid()) // destroy all existing figures
 292 surf(Z,Z+5) // color array specified
 293 e=gce();
 294 e.cdata_mapping='direct' // default is 'scaled' relative to the colormap
 295 e.color_flag=3; // interpolated shading mode. The default is 4 ('flat' mode) for surf
 296
 297 scf(2)
 298 surf(X,Y,Z,'colorda',ones(10,10),'edgeco','cya','marker','penta','markersiz',20,'markeredg','yel','ydata',56:65)
 299
 300 scf(3)
 301 surf(Z,'cdatamapping','direct')
 302 scf(4)
 303 surf(Z,'facecol','interp') // interpolated shading mode (color_flag == 3)
 304
 305 scf(10)
 306 axfig10=gca();
 307 scf(11);
 308 surf(axfig10,Z,'ydat',[100:109],'marker','d','markerfac','green','markeredg','yel') // draw onto the axe of figure 10
 309
 310 xdel(winsid())
 311  ]]></programlisting>
 312   </refsection>
 313   <refsection role="see also">
 314     <title>See Also</title>
 315     <simplelist type="inline">
 316       <member>
 317         <link linkend="plot2d">plot2d</link>
 318       </member>
 319       <member>
 320         <link linkend="clf">clf</link>
 321       </member>
 322       <member>
 323         <link linkend="xdel">xdel</link>
 324       </member>
 325       <member>
 326         <link linkend="delete">delete</link>
 327       </member>
 328       <member>
 329         <link linkend="LineSpec">LineSpec</link>
 330       </member>
 331       <member>
 332         <link linkend="GlobalProperty">GlobalProperty</link>
 333       </member>
 334     </simplelist>
 335   </refsection>
 336 </refentry>