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