8d0cb24078b6fa1563eaa80f7e8ac49971eefb0c
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / plot3d.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.1-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:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:id="plot3d" xml:lang="en">
14     <refnamediv>
15         <refname>plot3d</refname>
16         <refpurpose>3D plot of a surface</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])
21             plot3d(x,y,z,&lt;opt_args&gt;)
22             
23             plot3d(xf,yf,zf,[theta,alpha,leg,flag,ebox])
24             plot3d(xf,yf,zf,&lt;opt_args&gt;)
25             
26             plot3d(xf,yf,list(zf,colors),[theta,alpha,leg,flag,ebox])
27             plot3d(xf,yf,list(zf,colors),&lt;opt_args&gt;)
28
29             plot3d(z)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x,y</term>
37                 <listitem>
38                     <para>row vectors of sizes n1 and n2 (x-axis and y-axis
39                         coordinates). These coordinates must be monotone.
40                     </para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>z</term>
45                 <listitem>
46                     <para>
47                         matrix of size (n1,n2). <literal>z(i,j)</literal> is the value
48                         of the surface at the point (x(i),y(j)).
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>xf,yf,zf</term>
54                 <listitem>
55                     <para>matrices of size (nf,n). They define the facets used to draw
56                         the surface. There are <literal>n</literal> facets. Each facet
57                         <literal>i</literal> is defined by a polygon with
58                         <literal>nf</literal> points. The x-axis, y-axis and z-axis
59                         coordinates of the points of the ith facet are given respectively by
60                         <literal>xf(:,i)</literal>, <literal>yf(:,i)</literal> and
61                         <literal>zf(:,i)</literal>.
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>colors</term>
67                 <listitem>
68                     <para>a vector of size n giving the color of each facets or a matrix
69                         of size (nf,n) giving color near each facet boundary (facet color is
70                         interpolated ).
71                     </para>
72                 </listitem>
73             </varlistentry>
74             <varlistentry>
75                 <term>&lt;opt_args&gt;</term>
76                 <listitem>
77                     <para>
78                         This represents a sequence of statements <literal>key1=value1,
79                             key2=value2
80                         </literal>
81                         ,... where <literal>key1</literal>,
82                         <literal>key2,...</literal> can be one of the following: theta,
83                         alpha ,leg,flag,ebox (see definition below).
84                     </para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>theta, alpha</term>
89                 <listitem>
90                     <para>real values giving in degree the spherical coordinates of the
91                         observation point (by default, <varname>alpha</varname>=35° and <varname>theta</varname>=45°).
92                     </para>
93                 </listitem>
94             </varlistentry>
95             <varlistentry>
96                 <term>leg</term>
97                 <listitem>
98                     <para>string defining the labels for each axis with @ as a field
99                         separator, for example "X@Y@Z" (by default, axis have no label).
100                     </para>
101                 </listitem>
102             </varlistentry>
103             <varlistentry>
104                 <term>flag</term>
105                 <listitem>
106                     <para>a real vector of size three.
107                         <literal>flag=[mode,type,box]</literal>(by default <varname>flag</varname>=[2,8,4]).
108                     </para>
109                     <variablelist>
110                         <varlistentry>
111                             <term>mode</term>
112                             <listitem>
113                                 <para>an integer (surface color).</para>
114                                 <variablelist>
115                                     <varlistentry>
116                                         <term>mode&gt;0</term>
117                                         <listitem>
118                                             <para>the surface is painted with color
119                                                 <literal>"mode"</literal> ; the boundary of the facet is
120                                                 drawn with current line style and color.
121                                             </para>
122                                         </listitem>
123                                     </varlistentry>
124                                     <varlistentry>
125                                         <term>mode=0:</term>
126                                         <listitem>
127                                             <para>a mesh of the surface is drawn.</para>
128                                         </listitem>
129                                     </varlistentry>
130                                     <varlistentry>
131                                         <term>mode&lt;0:</term>
132                                         <listitem>
133                                             <para>the surface is painted with color
134                                                 <literal>"-mode"</literal> ; the boundary of the facet
135                                                 is not drawn.
136                                             </para>
137                                             <para>Note that the surface color treatement can be done
138                                                 using <literal>color_mode</literal> and
139                                                 <literal>color_flag</literal> options through the
140                                                 surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
141                                             </para>
142                                         </listitem>
143                                     </varlistentry>
144                                 </variablelist>
145                             </listitem>
146                         </varlistentry>
147                         <varlistentry>
148                             <term>type</term>
149                             <listitem>
150                                 <para>an integer (scaling).</para>
151                                 <variablelist>
152                                     <varlistentry>
153                                         <term>type=0:</term>
154                                         <listitem>
155                                             <para>the plot is made using the current 3D scaling (set
156                                                 by a previous call to <literal>param3d</literal>,
157                                                 <literal>plot3d</literal>, <literal>contour</literal> or
158                                                 <literal>plot3d1</literal>).
159                                             </para>
160                                         </listitem>
161                                     </varlistentry>
162                                     <varlistentry>
163                                         <term>type=1:</term>
164                                         <listitem>
165                                             <para>rescales automatically 3d boxes with extreme
166                                                 aspect ratios, the boundaries are specified by the value
167                                                 of the optional argument <literal>ebox</literal>.
168                                             </para>
169                                         </listitem>
170                                     </varlistentry>
171                                     <varlistentry>
172                                         <term>type=2:</term>
173                                         <listitem>
174                                             <para>rescales automatically 3d boxes with extreme
175                                                 aspect ratios, the boundaries are computed using the
176                                                 given data.
177                                             </para>
178                                         </listitem>
179                                     </varlistentry>
180                                     <varlistentry>
181                                         <term>type=3:</term>
182                                         <listitem>
183                                             <para>3d isometric with box bounds given by optional
184                                                 <literal>ebox</literal>, similarily to
185                                                 <literal>type=1</literal>.
186                                             </para>
187                                         </listitem>
188                                     </varlistentry>
189                                     <varlistentry>
190                                         <term>type=4:</term>
191                                         <listitem>
192                                             <para>3d isometric bounds derived from the data, to
193                                                 similarily<literal>type=2</literal>.
194                                             </para>
195                                         </listitem>
196                                     </varlistentry>
197                                     <varlistentry>
198                                         <term>type=5:</term>
199                                         <listitem>
200                                             <para>3d expanded isometric bounds with box bounds given
201                                                 by optional <literal>ebox</literal>, similarily to
202                                                 <literal>type=1</literal>.
203                                             </para>
204                                         </listitem>
205                                     </varlistentry>
206                                     <varlistentry>
207                                         <term>type=6:</term>
208                                         <listitem>
209                                             <para>3d expanded isometric bounds derived from the
210                                                 data, similarily to <literal>type=2</literal>.
211                                             </para>
212                                             <para>Note that axes boundaries can be customized
213                                                 through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
214                                             </para>
215                                         </listitem>
216                                     </varlistentry>
217                                 </variablelist>
218                             </listitem>
219                         </varlistentry>
220                         <varlistentry>
221                             <term>box</term>
222                             <listitem>
223                                 <para>an integer (frame around the plot).</para>
224                                 <variablelist>
225                                     <varlistentry>
226                                         <term>box=0:</term>
227                                         <listitem>
228                                             <para>nothing is drawn around the plot.</para>
229                                         </listitem>
230                                     </varlistentry>
231                                     <varlistentry>
232                                         <term>box=1:</term>
233                                         <listitem>
234                                             <para>unimplemented (like box=0).</para>
235                                         </listitem>
236                                     </varlistentry>
237                                     <varlistentry>
238                                         <term>box=2:</term>
239                                         <listitem>
240                                             <para>only the axes behind the surface are drawn.</para>
241                                         </listitem>
242                                     </varlistentry>
243                                     <varlistentry>
244                                         <term>box=3:</term>
245                                         <listitem>
246                                             <para>a box surrounding the surface is drawn and
247                                                 captions are added.
248                                             </para>
249                                         </listitem>
250                                     </varlistentry>
251                                     <varlistentry>
252                                         <term>box=4:</term>
253                                         <listitem>
254                                             <para>a box surrounding the surface is drawn, captions
255                                                 and axes are added.
256                                             </para>
257                                             <para>Note that axes aspect can also be customized
258                                                 through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
259                                             </para>
260                                         </listitem>
261                                     </varlistentry>
262                                 </variablelist>
263                             </listitem>
264                         </varlistentry>
265                     </variablelist>
266                 </listitem>
267             </varlistentry>
268             <varlistentry>
269                 <term>ebox</term>
270                 <listitem>
271                     <para>It specifies the boundaries of the plot as the vector
272                         <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is
273                         used together with <literal>type</literal> in
274                         <literal>flag</literal> : if it is set to <literal>1</literal>,
275                         <literal>3</literal> or <literal>5</literal> (see above to see the
276                         corresponding behaviour). If <literal>flag</literal> is missing,
277                         <literal>ebox</literal> is not taken into acoount (by default <varname>ebox</varname> is missing).
278                     </para>
279                     <para>
280                         Note that, when specified, the <literal>ebox</literal>
281                         argument acts on the <literal>data_bounds</literal> field that can
282                         also be reset through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
283                     </para>
284                 </listitem>
285             </varlistentry>
286         </variablelist>
287     </refsection>
288     <refsection>
289         <title>Description</title>
290         <para>
291             <literal>plot3d(z)</literal> draws the parametric surface <literal>z=f(x,y)</literal> where
292             <literal>x=1:m</literal>, <literal>y=1:n</literal> and <literal>[m,n]=size(z)</literal>.
293         </para>
294         <para>
295             <literal>plot3d(x,y,z,[theta,alpha,leg,flag,ebox])</literal> draws
296             the parametric surface <literal>z=f(x,y)</literal>.
297         </para>
298         <para>
299             <literal>plot3d(xf,yf,zf,[theta,alpha,leg ,flag,ebox])</literal>
300             draws a surface defined by a set of facets. You can draw multiple plots by
301             replacing <literal>xf</literal>, <literal>yf</literal> and
302             <literal>zf</literal> by multiple matrices assembled by rows as
303             <literal>[xf1 xf2 ...]</literal>, <literal>[yf1 yf2 ...]</literal> and
304             <literal>[zf1 zf2 ...]</literal>. Note that data can also be set or get
305             through the surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
306         </para>
307         <para/>
308         <para>You can give a specific color for each facet by using
309             <literal>list(zf,colors)</literal> instead of <literal>zf</literal>, where
310             <literal>colors</literal> is a vector of size <literal>n</literal>. If
311             <literal>colors(i)</literal> is positive it gives the color of facet
312             <literal>i</literal> and the boundary of the facet is drawn with current
313             line style and color. If <literal>colors(i)</literal> is negative, color
314             id <literal>-colors(i)</literal> is used and the boundary of the facet is
315             not drawn.
316         </para>
317         <para/>
318         <para>It is also possible to get interpolated color for facets. For that
319             the color argument must be a matrix of size nfxn giving the color near
320             each boundary of each facets. In this case positive values for colors mean
321             that the boundary are not drawn. Note that colors can also be set through
322             the surface entity properties (via <literal>tlist</literal> affectations)
323             and edited using <literal>color_flag</literal> option (see <link linkend="surface_properties">surface_properties</link>).
324         </para>
325         <para/>
326         <para>
327             The optional arguments <literal>theta, alpha, leg ,flag,
328                 ebox
329             </literal>
330             ,can be passed by a sequence of statements
331             <literal>key1=value1, key2=value2</literal>, ... In this case, the order
332             has no special meaning. Note that all these optional arguments except
333             <literal>flag</literal> can be customized through the axes entity
334             properties (see <link linkend="axes_properties">axes_properties</link>).
335             As described before, the <literal>flag</literal> option deals with surface
336             entity properties for <literal>mode</literal> (see <link linkend="surface_properties">surface_properties</link>) and axes
337             properties for <literal>type</literal> and <literal>box</literal> (see
338             <link linkend="axes_properties">axes_properties</link>).
339         </para>
340         <para/>
341         <para>
342             You can use the function <literal>genfac3d</literal> to compute four
343             sided facets from the surface <literal>z=f(x,y)</literal>.
344             <literal>eval3dp</literal> can also be used.
345         </para>
346         <para/>
347         <para>
348             Enter the command <literal>plot3d()</literal> to see a demo.
349         </para>
350     </refsection>
351     <refsection>
352         <title>Examples</title>
353         <programlisting role="example"><![CDATA[
354 // simple plot using z=f(x,y)
355 t=[0:0.3:2*%pi]';
356 z=sin(t)*cos(t');
357 plot3d(t,t,z)
358  ]]></programlisting>
359         
360         <scilab:image>
361             t=[0:0.3:2*%pi]';
362             z=sin(t)*cos(t');
363             plot3d(t,t,z)
364         </scilab:image>
365         
366         <programlisting role="example"><![CDATA[
367 t=[0:0.3:2*%pi]';
368 z=sin(t)*cos(t');
369 // same plot using facets computed by genfac3d
370 [xx,yy,zz]=genfac3d(t,t,z);
371 plot3d(xx,yy,zz)
372  ]]></programlisting>
373         
374         <scilab:image>
375             t=[0:0.3:2*%pi]';
376             z=sin(t)*cos(t');
377             // same plot using facets computed by genfac3d
378             [xx,yy,zz]=genfac3d(t,t,z);
379             plot3d(xx,yy,zz)
380         </scilab:image>
381         
382         <programlisting role="example"><![CDATA[
383 // multiple plots
384 t=[0:0.3:2*%pi]';
385 z=sin(t)*cos(t');
386 // same plot using facets computed by genfac3d
387 [xx,yy,zz]=genfac3d(t,t,z);
388 plot3d([xx xx],[yy yy],[zz 4+zz])
389  ]]></programlisting>
390         
391         <scilab:image>
392             // multiple plots
393             t=[0:0.3:2*%pi]';
394             z=sin(t)*cos(t');
395             // same plot using facets computed by genfac3d
396             [xx,yy,zz]=genfac3d(t,t,z);
397             plot3d([xx xx],[yy yy],[zz 4+zz])
398         </scilab:image>
399         
400         <programlisting role="example"><![CDATA[
401 // multiple plots using colors
402 t=[0:0.3:2*%pi]';
403 z=sin(t)*cos(t');
404 // same plot using facets computed by genfac3d
405 [xx,yy,zz]=genfac3d(t,t,z);
406 plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
407  ]]></programlisting>
408         
409         <scilab:image>
410             t=[0:0.3:2*%pi]';
411             z=sin(t)*cos(t');
412             // same plot using facets computed by genfac3d
413             [xx,yy,zz]=genfac3d(t,t,z);
414             plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
415         </scilab:image>
416         
417         <programlisting role="example"><![CDATA[
418 // simple plot with viewpoint and captions
419 plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3])
420  ]]></programlisting>
421         
422         <scilab:image>
423             plot3d(1:10,1:20,10*rand(10,20),alpha=35,theta=45,flag=[2,2,3])
424         </scilab:image>
425         <programlisting role="example"><![CDATA[
426 // plot of a sphere using facets computed by eval3dp
427 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
428      "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
429      "z=r*sin(alp)+orig(3)*ones(tet)"]);
430 r=1; orig=[0 0 0];
431 [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
432 clf();plot3d(xx,yy,zz)
433  ]]></programlisting>
434         
435         <scilab:image>
436             deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
437             "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
438             "z=r*sin(alp)+orig(3)*ones(tet)"]);
439             r=1; orig=[0 0 0];
440             [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
441             clf();plot3d(xx,yy,zz)
442         </scilab:image>
443         
444         <programlisting role="example"><![CDATA[
445 f=gcf();
446 f.color_map = hotcolormap(128);
447 r=0.3;orig=[1.5 0 0];
448 deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
449      "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
450      "z=r*sin(alp)+orig(3)*ones(tet)"]);
451 [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
452 [xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
453 cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32;
454 clf();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
455  ]]></programlisting>
456         
457         <scilab:image>
458             f=gcf();
459             f.color_map = hotcolormap(128);
460             r=0.3;orig=[1.5 0 0];
461             deff("[x,y,z]=sph(alp,tet)",["x=r*cos(alp).*cos(tet)+orig(1)*ones(tet)";..
462             "y=r*cos(alp).*sin(tet)+orig(2)*ones(tet)";..
463             "z=r*sin(alp)+orig(3)*ones(tet)"]);
464             [xx,yy,zz]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
465             [xx1,yy1,zz1]=eval3dp(sph,linspace(-%pi/2,%pi/2,40),linspace(0,%pi*2,20));
466             cc=(xx+zz+2)*32;cc1=(xx1-orig(1)+zz1/r+2)*32;
467             clf();plot3d1([xx xx1],[yy yy1],list([zz,zz1],[cc cc1]),theta=70,alpha=80,flag=[5,6,3])
468         </scilab:image>
469         
470         <programlisting role="example"><![CDATA[
471 t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
472 [xx,yy,zz]=genfac3d(t,t,z);
473 plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
474 e=gce();
475 f=e.data;
476 TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,6*rand(f.z)); // random color matrix
477 e.data = TL;
478 TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // random color vector
479 e.data = TL2;
480 TL3 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,[20*ones(1,400) 6*ones(1,400)]);
481 e.data = TL3;
482 TL4 = tlist(["3d" "x" "y" "z"],f.x,f.y,f.z); // no color
483 e.data = TL4;
484 e.color_flag=1 // color index proportional to altitude (z coord.)
485 e.color_flag=2; // back to default mode
486 e.color_flag= 3; // interpolated shading mode (based on blue default color)
487 clf()
488 plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
489 h=gce(); //get handle on current entity (here the surface)
490 a=gca(); //get current axes
491 a.rotation_angles=[40,70];
492 a.grid=[1 1 1]; //make grids
493 a.data_bounds=[-6,0,-1;6,6,5];
494 a.axes_visible="off"; //axes are hidden
495 a.axes_bounds=[.2 0 1 1];
496 h.color_flag=1; //color according to z
497 h.color_mode=-2;  //remove the facets boundary by setting color_mode to white color
498 h.color_flag=2; //color according to given colors
499 h.color_mode = -1; // put the facets boundary back by setting color_mode to black color
500 f=gcf();//get the handle of the parent figure
501 f.color_map=hotcolormap(512);
502 c=[1:400,1:400];
503 TL.color = [c;c+1;c+2;c+3];
504 h.data = TL;
505 h.color_flag=3; // interpolated shading mode
506  ]]></programlisting>
507         
508         <scilab:image>
509             t=[0:0.3:2*%pi]'; z=sin(t)*cos(t');
510             [xx,yy,zz]=genfac3d(t,t,z);
511             plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
512             e=gce();
513             f=e.data;
514             TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,6*rand(f.z)); // random color matrix
515             e.data = TL;
516             TL2 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,4*rand(1,800)); // random color vector
517             e.data = TL2;
518             TL3 = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,[20*ones(1,400) 6*ones(1,400)]);
519             e.data = TL3;
520             TL4 = tlist(["3d" "x" "y" "z"],f.x,f.y,f.z); // no color
521             e.data = TL4;
522             e.color_flag=1 // color index proportional to altitude (z coord.)
523             e.color_flag=2; // back to default mode
524             e.color_flag= 3; // interpolated shading mode (based on blue default color)
525             clf()
526             plot3d([xx xx],[yy yy],list([zz zz+4],[4*ones(1,400) 5*ones(1,400)]))
527             h=gce(); //get handle on current entity (here the surface)
528             a=gca(); //get current axes
529             a.rotation_angles=[40,70];
530             a.grid=[1 1 1]; //make grids
531             a.data_bounds=[-6,0,-1;6,6,5];
532             a.axes_visible="off"; //axes are hidden
533             a.axes_bounds=[.2 0 1 1];
534             h.color_flag=1; //color according to z
535             h.color_mode=-2;  //remove the facets boundary by setting color_mode to white color
536             h.color_flag=2; //color according to given colors
537             h.color_mode = -1; // put the facets boundary back by setting color_mode to black color
538             f=gcf();//get the handle of the parent figure
539             f.color_map=hotcolormap(512);
540             c=[1:400,1:400];
541             TL.color = [c;c+1;c+2;c+3];
542             h.data = TL;
543             h.color_flag=3; // interpolated shading mode
544         </scilab:image>
545         <para>We can use the plot3d function to plot a set of patches (triangular,
546             quadrangular, etc).
547         </para>
548         <programlisting role="example"><![CDATA[
549 // The plot3d function to draw patches:
550 // patch(x,y,[z])
551 // patch(x,y,[list(z,c)])
552 // The size of x : number of points in the patches x number of patches
553 // y and z have the same sizes as x
554 // c:
555 // - a vector of size number of patches: the color of the patches
556 // - a matrix of size number of points in the patches x number of
557 //   patches: the color of each points of each patches
558
559 // Example 1: a set of triangular patches
560
561 x = [0 0;
562      0 1;
563      1 1];
564
565 y = [1 1;
566      2 2;
567      2 1];
568
569 z = [1 1;
570      1 1;
571      1 1];
572
573 tcolor = [2 3]';
574
575 subplot(2,2,1);
576 plot3d(x,y,list(z,tcolor));
577 xtitle('A triangle set of patches');
578 // Example 2: a mixture of triangular and quadrangular patches
579
580 xquad = [5, 0;
581          10,0;
582          15,5;
583          10,5];
584
585 yquad = [15,0;
586          20,10;
587          15,15;
588          10,5];
589
590 zquad = ones(4,2);
591
592 xtri = [ 0,10,10, 5, 0;
593         10,20,20, 5, 0;
594         20,20,15,10,10];
595
596 ytri = [ 0,10,20, 5,10;
597         10,20,20,15,20;
598          0, 0,15,10,20];
599
600 ztri = zeros(3,5);
601
602 subplot(2,2,3);
603 plot3d(xquad,yquad,zquad);
604 plot3d(xtri,ytri,ztri);
605 xtitle('Mixing triangle and quadrangle set of patches');
606
607 // Example 3: some rabbits
608
609 rabxtri = [ 5,  5, 2.5,  7.5, 10;
610             5, 15, 5,   10,   10;
611            15, 15, 5,   10,   15];
612
613 rabytri = [10, 10, 9.5,  2.5, 0;
614            20, 10, 12,   5,   5;
615            10   0   7    0    0];
616 rabztri = [0,0,0,0,0;
617            0,0,0,0,0;
618            0,0,0,0,0];
619
620 rabtricolor_byface = [2 2 2 2 2];
621
622 rabtricolor = [2,2,2,2,2;
623                3,3,3,3,3;
624                4,4,4,4,4];
625
626 rabxquad = [0, 1;
627             0, 6;
628             5,11;
629             5, 6];
630
631 rabyquad = [18,23;
632             23,28;
633             23,28;
634             18,23];
635
636 rabzquad = [1,1;
637             1,1;
638             1,1;
639             1,1];
640
641 rabquadcolor_byface = [2 2];
642
643 rabquadcolor = [2,2;
644                 3,3;
645                 4,4;
646                 5,5];
647
648 subplot(2,2,2);
649 plot3d(rabxtri, rabytri, list(rabztri,rabtricolor));
650 plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor));
651 h = gcf();
652 h.children(1).background = 1;
653 xtitle('A psychedelic rabbit set of patches');
654
655 subplot(2,2,4);
656 plot3d(rabxtri, rabytri, list(rabztri,rabtricolor_byface));
657 plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor_byface));
658 h = gcf();
659 h.children(1).background = 1;
660 xtitle('A standard rabbit set of patches');
661  ]]></programlisting>
662         
663         <scilab:image>
664             
665             x = [0 0;
666             0 1;
667             1 1];
668             
669             y = [1 1;
670             2 2;
671             2 1];
672             
673             z = [1 1;
674             1 1;
675             1 1];
676             
677             tcolor = [2 3]';
678             
679             subplot(2,2,1);
680             plot3d(x,y,list(z,tcolor));
681             xtitle('A triangle set of patches');
682             // Example 2: a mixture of triangular and quadrangular patches
683             
684             xquad = [5, 0;
685             10,0;
686             15,5;
687             10,5];
688             
689             yquad = [15,0;
690             20,10;
691             15,15;
692             10,5];
693             
694             zquad = ones(4,2);
695             
696             xtri = [ 0,10,10, 5, 0;
697             10,20,20, 5, 0;
698             20,20,15,10,10];
699             
700             ytri = [ 0,10,20, 5,10;
701             10,20,20,15,20;
702             0, 0,15,10,20];
703             
704             ztri = zeros(3,5);
705             
706             subplot(2,2,3);
707             plot3d(xquad,yquad,zquad);
708             plot3d(xtri,ytri,ztri);
709             xtitle('Mixing triangle and quadrangle set of patches');
710             
711             // Example 3: some rabbits
712             
713             rabxtri = [ 5,  5, 2.5,  7.5, 10;
714             5, 15, 5,   10,   10;
715             15, 15, 5,   10,   15];
716             
717             rabytri = [10, 10, 9.5,  2.5, 0;
718             20, 10, 12,   5,   5;
719             10   0   7    0    0];
720             rabztri = [0,0,0,0,0;
721             0,0,0,0,0;
722             0,0,0,0,0];
723             
724             rabtricolor_byface = [2 2 2 2 2];
725             
726             rabtricolor = [2,2,2,2,2;
727             3,3,3,3,3;
728             4,4,4,4,4];
729             
730             rabxquad = [0, 1;
731             0, 6;
732             5,11;
733             5, 6];
734             
735             rabyquad = [18,23;
736             23,28;
737             23,28;
738             18,23];
739             
740             rabzquad = [1,1;
741             1,1;
742             1,1;
743             1,1];
744             
745             rabquadcolor_byface = [2 2];
746             
747             rabquadcolor = [2,2;
748             3,3;
749             4,4;
750             5,5];
751             
752             subplot(2,2,2);
753             plot3d(rabxtri, rabytri, list(rabztri,rabtricolor));
754             plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor));
755             h = gcf();
756             h.children(1).background = 1;
757             xtitle('A psychedelic rabbit set of patches');
758             
759             subplot(2,2,4);
760             plot3d(rabxtri, rabytri, list(rabztri,rabtricolor_byface));
761             plot3d(rabxquad,rabyquad,list(rabzquad,rabquadcolor_byface));
762             h = gcf();
763             h.children(1).background = 1;
764             xtitle('A standard rabbit set of patches');
765         </scilab:image>
766         
767         <para>We can also use the plot3d function to plot a set of patches using
768             vertex and faces.
769         </para>
770         <programlisting role="example"><![CDATA[
771 // Vertex / Faces example: 3D example
772
773 // The vertex list contains the list of unique points composing each patch
774 // The points common to 2 patches are not repeated in the vertex list
775
776 vertex = [0 1 1;
777           0 2 2;
778           1 2 3;
779           1 1 4];
780
781 // The face list indicates which points are composing the patch.
782 face = [1 2 3;
783         1 3 4];
784
785 tcolor = [2 3]';
786
787 // The formula used to translate the vertex / face representation into x, y, z lists
788
789 xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
790 yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
791 zvf = matrix(vertex(face,3),size(face,1),length(vertex(face,1))/size(face,1))';
792
793 scf();
794 subplot(2,1,1);
795 plot3d(xvf,yvf,list(zvf,tcolor));
796 xtitle('A triangle set of patches - vertex / face mode - 3d');
797
798 // 2D test
799 // We use the 3D representation with a 0 Z values and then switch to 2D representation
800
801 // Vertex / Faces example: 3D example
802
803 // The vertex list contains the list of unique points composing each patch
804 // The points common to 2 patches are not repeated in the vertex list
805
806 vertex = [0 1;
807           0 2;
808           1 2;
809           1 1];
810
811 // The face list indicates which points are composing the patch.
812 face = [1 2 3;
813         1 3 4];
814
815 // The formula used to translate the vertex / face representation into x, y, z lists
816
817 xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
818 yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
819 zvf = matrix(zeros(vertex(face,2)),size(face,1),length(vertex(face,1))/size(face,1))';
820 tcolor = [2 3]';
821
822 subplot(2,1,2);
823 plot3d(xvf,yvf,list(zvf,tcolor));
824 xtitle('A triangle set of patches - vertex / face mode - 2D');
825 a = gca();
826 a.view = '2d';
827  ]]></programlisting>
828         <scilab:image>
829             
830             vertex = [0 1 1;
831             0 2 2;
832             1 2 3;
833             1 1 4];
834             
835             // The face list indicates which points are composing the patch.
836             face = [1 2 3;
837             1 3 4];
838             
839             tcolor = [2 3]';
840             
841             // The formula used to translate the vertex / face representation into x, y, z lists
842             
843             xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
844             yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
845             zvf = matrix(vertex(face,3),size(face,1),length(vertex(face,1))/size(face,1))';
846             
847             scf();
848             subplot(2,1,1);
849             plot3d(xvf,yvf,list(zvf,tcolor));
850             xtitle('A triangle set of patches - vertex / face mode - 3d');
851             
852             // 2D test
853             // We use the 3D representation with a 0 Z values and then switch to 2D representation
854             
855             // Vertex / Faces example: 3D example
856             
857             // The vertex list contains the list of unique points composing each patch
858             // The points common to 2 patches are not repeated in the vertex list
859             
860             vertex = [0 1;
861             0 2;
862             1 2;
863             1 1];
864             
865             // The face list indicates which points are composing the patch.
866             face = [1 2 3;
867             1 3 4];
868             
869             // The formula used to translate the vertex / face representation into x, y, z lists
870             
871             xvf = matrix(vertex(face,1),size(face,1),length(vertex(face,1))/size(face,1))';
872             yvf = matrix(vertex(face,2),size(face,1),length(vertex(face,1))/size(face,1))';
873             zvf = matrix(zeros(vertex(face,2)),size(face,1),length(vertex(face,1))/size(face,1))';
874             tcolor = [2 3]';
875             
876             subplot(2,1,2);
877             plot3d(xvf,yvf,list(zvf,tcolor));
878             xtitle('A triangle set of patches - vertex / face mode - 2D');
879             a = gca();
880             a.view = '2d';
881         </scilab:image>
882         <para> How to set manually some ticks </para>
883         <programlisting role="example"><![CDATA[
884 plot3d();
885 h = gca();
886 h.x_ticks = tlist(['ticks','locations','labels'],[-2,-1,0,1,2],['-2','-1','0','1','2']);
887 h.y_ticks = tlist(['ticks','locations','labels'],[-4,-3,-2,-1,0,1,2,3,4],['-4','-3','-2','-1','0','1','2','3','4']);
888 h.z_ticks = tlist(['ticks','locations','labels'],[-1,0,1],['Point 1','Point 2','Point 3']);
889  ]]></programlisting>
890         <scilab:image>
891             plot3d();
892             h = gca();
893             h.x_ticks = tlist(['ticks','locations','labels'],[-2,-1,0,1,2],['-2','-1','0','1','2']);
894             h.y_ticks = tlist(['ticks','locations','labels'],[-4,-3,-2,-1,0,1,2,3,4],['-4','-3','-2','-1','0','1','2','3','4']);
895             h.z_ticks = tlist(['ticks','locations','labels'],[-1,0,1],['Point 1','Point 2','Point 3']);
896         </scilab:image>
897         
898         <para/>
899     </refsection>
900     <refsection role="see also">
901         <title>See Also</title>
902         <simplelist type="inline">
903             <member>
904                 <link linkend="eval3dp">eval3dp</link>
905             </member>
906             <member>
907                 <link linkend="genfac3d">genfac3d</link>
908             </member>
909             <member>
910                 <link linkend="geom3d">geom3d</link>
911             </member>
912             <member>
913                 <link linkend="param3d">param3d</link>
914             </member>
915             <member>
916                 <link linkend="plot3d1">plot3d1</link>
917             </member>
918             <member>
919                 <link linkend="clf">clf</link>
920             </member>
921             <member>
922                 <link linkend="gca">gca</link>
923             </member>
924             <member>
925                 <link linkend="gcf">gcf</link>
926             </member>
927             <member>
928                 <link linkend="xdel">xdel</link>
929             </member>
930             <member>
931                 <link linkend="delete">delete</link>
932             </member>
933             <member>
934                 <link linkend="axes_properties">axes_properties</link>
935             </member>
936         </simplelist>
937     </refsection>
938 </refentry>