afe889baa8c7d13c9d80043cdd76f4a17fc90cac
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / plot3d2.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
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="plot3d2">
14     <refnamediv>
15         <refname>plot3d2</refname>
16         <refpurpose>plot surface defined by rectangular
17             facets
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>plot3d2(X,Y,Z [,vect,theta,alpha,leg,flag,ebox])
23             plot3d2(X,Y,Z, &lt;opt_args&gt;)
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>X, Y, Z:</term>
31                 <listitem>
32                     <para> 3 real matrices defining a data structure.</para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>vect</term>
37                 <listitem>
38                     <para>a real vector.</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>&lt;opt_args&gt;</term>
43                 <listitem>
44                     <para>
45                         This represents a sequence of statements <literal>key1=value1, key2=value2</literal>,... where <literal>key1</literal>,
46                         <literal>key2,...</literal> can be one of the following: theta, alpha
47                         ,leg,flag,ebox (see definition below).
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>theta, alpha</term>
53                 <listitem>
54                     <para>real values giving in degree the spherical coordinates of the
55                         observation point.
56                     </para>
57                 </listitem>
58             </varlistentry>
59             <varlistentry>
60                 <term>leg</term>
61                 <listitem>
62                     <para>string defining the labels for each axis with @ as a field
63                         separator, for example "X@Y@Z".
64                     </para>
65                 </listitem>
66             </varlistentry>
67             <varlistentry>
68                 <term>flag</term>
69                 <listitem>
70                     <para>a real vector of size three.
71                         <literal>flag=[mode,type,box]</literal>.
72                     </para>
73                     <variablelist>
74                         <varlistentry>
75                             <term>mode</term>
76                             <listitem>
77                                 <para>an integer (surface color).</para>
78                                 <variablelist>
79                                     <varlistentry>
80                                         <term>mode&gt;0</term>
81                                         <listitem>
82                                             <para>the surface is painted with color
83                                                 <literal>"mode"</literal> ; the boundary of the facet is drawn
84                                                 with current line style and color.
85                                             </para>
86                                         </listitem>
87                                     </varlistentry>
88                                     <varlistentry>
89                                         <term>mode=0:</term>
90                                         <listitem>
91                                             <para> a mesh of the surface is drawn.</para>
92                                         </listitem>
93                                     </varlistentry>
94                                     <varlistentry>
95                                         <term>mode&lt;0:</term>
96                                         <listitem>
97                                             <para> the surface is painted with color
98                                                 <literal>"-mode"</literal> ; the boundary of the facet is not
99                                                 drawn.
100                                             </para>
101                                             <para>Note that the surface color treatement can be done
102                                                 using <literal>color_mode</literal> and
103                                                 <literal>color_flag</literal> options through the surface
104                                                 entity properties (see
105                                                 <link linkend="surface_properties">surface_properties</link>).
106                                             </para>
107                                         </listitem>
108                                     </varlistentry>
109                                 </variablelist>
110                             </listitem>
111                         </varlistentry>
112                         <varlistentry>
113                             <term>type</term>
114                             <listitem>
115                                 <para>an integer (scaling).</para>
116                                 <variablelist>
117                                     <varlistentry>
118                                         <term>type=0:</term>
119                                         <listitem>
120                                             <para>the plot is made using the current 3D scaling (set
121                                                 by a previous call to <literal>param3d</literal>,
122                                                 <literal>plot3d</literal>, <literal>contour</literal> or
123                                                 <literal>plot3d1</literal>).
124                                             </para>
125                                         </listitem>
126                                     </varlistentry>
127                                     <varlistentry>
128                                         <term>type=1:</term>
129                                         <listitem>
130                                             <para>rescales automatically 3d boxes with extreme aspect
131                                                 ratios, the boundaries are specified by the value of the
132                                                 optional argument <literal>ebox</literal>.
133                                             </para>
134                                         </listitem>
135                                     </varlistentry>
136                                     <varlistentry>
137                                         <term>type=2:</term>
138                                         <listitem>
139                                             <para>rescales automatically 3d boxes with extreme aspect
140                                                 ratios, the boundaries are computed using the given
141                                                 data.
142                                             </para>
143                                         </listitem>
144                                     </varlistentry>
145                                     <varlistentry>
146                                         <term>type=3:</term>
147                                         <listitem>
148                                             <para>3d isometric with box bounds given by optional
149                                                 <literal>ebox</literal>, similarily to
150                                                 <literal>type=1</literal>.
151                                             </para>
152                                         </listitem>
153                                     </varlistentry>
154                                     <varlistentry>
155                                         <term>type=4:</term>
156                                         <listitem>
157                                             <para>3d isometric bounds derived from the data, to
158                                                 similarily<literal>type=2</literal>.
159                                             </para>
160                                         </listitem>
161                                     </varlistentry>
162                                     <varlistentry>
163                                         <term>type=5:</term>
164                                         <listitem>
165                                             <para>3d expanded isometric bounds with box bounds given
166                                                 by optional <literal>ebox</literal>, similarily to
167                                                 <literal>type=1</literal>.
168                                             </para>
169                                         </listitem>
170                                     </varlistentry>
171                                     <varlistentry>
172                                         <term>type=6:</term>
173                                         <listitem>
174                                             <para>3d expanded isometric bounds derived from the data,
175                                                 similarily to <literal>type=2</literal>.
176                                             </para>
177                                             <para>Note that axes boundaries can be customized through
178                                                 the axes entity properties (see
179                                                 <link linkend="axes_properties">axes_properties</link>).
180                                             </para>
181                                         </listitem>
182                                     </varlistentry>
183                                 </variablelist>
184                             </listitem>
185                         </varlistentry>
186                         <varlistentry>
187                             <term>box</term>
188                             <listitem>
189                                 <para>an integer (frame around the plot).</para>
190                                 <variablelist>
191                                     <varlistentry>
192                                         <term>box=0:</term>
193                                         <listitem>
194                                             <para>nothing is drawn around the plot.</para>
195                                         </listitem>
196                                     </varlistentry>
197                                     <varlistentry>
198                                         <term>box=1:</term>
199                                         <listitem>
200                                             <para>unimplemented (like box=0).</para>
201                                         </listitem>
202                                     </varlistentry>
203                                     <varlistentry>
204                                         <term>box=2:</term>
205                                         <listitem>
206                                             <para>only the axes behind the surface are drawn.</para>
207                                         </listitem>
208                                     </varlistentry>
209                                     <varlistentry>
210                                         <term>box=3:</term>
211                                         <listitem>
212                                             <para>a box surrounding the surface is drawn and captions
213                                                 are added.
214                                             </para>
215                                         </listitem>
216                                     </varlistentry>
217                                     <varlistentry>
218                                         <term>box=4:</term>
219                                         <listitem>
220                                             <para>a box surrounding the surface is drawn, captions and
221                                                 axes are added.
222                                             </para>
223                                             <para>Note that axes aspect can also be customized through
224                                                 the axes entity properties (see
225                                                 <link linkend="axes_properties">axes_properties</link>).
226                                             </para>
227                                         </listitem>
228                                     </varlistentry>
229                                 </variablelist>
230                             </listitem>
231                         </varlistentry>
232                     </variablelist>
233                 </listitem>
234             </varlistentry>
235             <varlistentry>
236                 <term>ebox</term>
237                 <listitem>
238                     <para>It specifies the boundaries of the plot as the vector
239                         <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is used
240                         together with <literal>type</literal> in <literal>flag</literal> : if it is set
241                         to <literal>1</literal>, <literal>3</literal> or <literal>5</literal> (see above to
242                         see the corresponding behaviour). If <literal>flag</literal> is missing,
243                         <literal>ebox</literal> is not taken into acoount. 
244                     </para>
245                     <para>
246                         Note that, when specified, the <literal>ebox</literal> argument acts on
247                         the <literal>data_bounds</literal> field that can also be reset through
248                         the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
249                     </para>
250                 </listitem>
251             </varlistentry>
252         </variablelist>
253     </refsection>
254     <refsection>
255         <title>Description</title>
256         <para>
257             <literal>plot3d2</literal> plots a surface defined by rectangular facets.
258             (X,Y,Z) are three matrices which describe a surface. The surface is
259             composed of four sided polygons.
260         </para>
261         <para>
262             The X-coordinates of a facet are given by
263             X(i,j), X(i+1,j), X(i+1,j+1) and X(i,j+1). Similarly Y and Z matrices contain Y and Z-coordinates.
264         </para>
265         <para>
266             The <literal>vect</literal> vector is used when multiple surfaces
267             are coded in the same (X,Y,Z) matrices. <literal>vect(j)</literal> gives the
268             line at which the coding of the jth surface begins. Like in
269             <literal>plot3d</literal>, the same properties are editable (see
270             <link linkend="surface_properties">surface_properties</link> and <link linkend="axes_properties">axes_properties</link>).
271         </para>
272     </refsection>
273     <refsection>
274         <title>Sample</title>
275         <scilab:image>u = linspace(-%pi/2,%pi/2,40);
276             v = linspace(0,2*%pi,20);
277             X = cos(u)'*cos(v);
278             Y = cos(u)'*sin(v);
279             Z = sin(u)'*ones(v);
280             plot3d2(X,Y,Z);
281             e=gce();
282             e.color_mode=4; // change color
283             f=e.data;
284             TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,10*(f.z)+1);
285             e.data=TL;
286             e.color_flag=2;
287         </scilab:image>
288     </refsection>
289     <refsection>
290         <title>Examples</title>
291         <programlisting role="example"><![CDATA[ 
292 u = linspace(-%pi/2,%pi/2,40);
293 v = linspace(0,2*%pi,20);
294 X = cos(u)'*cos(v);
295 Y = cos(u)'*sin(v);
296 Z = sin(u)'*ones(v);
297 plot3d2(X,Y,Z);
298 e=gce();
299 e.color_mode=4; // change color
300 f=e.data;
301 TL = tlist(["3d" "x" "y" "z" "color"],f.x,f.y,f.z,10*(f.z)+1);
302 e.data=TL;
303 e.color_flag=2;
304  ]]></programlisting>
305     </refsection>
306     <refsection role="see also">
307         <title>See Also</title>
308         <simplelist type="inline">
309             <member>
310                 <link linkend="plot3d">plot3d</link>
311             </member>
312             <member>
313                 <link linkend="genfac3d">genfac3d</link>
314             </member>
315         </simplelist>
316     </refsection>
317 </refentry>