303442ca6967daf44d47bb89c7ff8a4a3f1ef014
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / param3d1.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:ns5="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="param3d1" xml:lang="en">
14     <refnamediv>
15         <refname>param3d1</refname>
16         <refpurpose>3D plot of parametric curves</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>param3d1(x,y,z,[theta,alpha,leg,flag,ebox])
21             param3d1(x,y,list(z,colors),[theta,alpha,leg,flag,ebox])
22         </synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>x,y,z</term>
29                 <listitem>
30                     <para>matrices of the same size (nl,nc).</para>
31                     <para>Each column i of the matrices corresponds to the coordinates
32                         of the ith curve. You can give a specific color for each curve by
33                         using <literal>list(z,colors)</literal> instead of
34                         <literal>z</literal>, where <literal>colors</literal> is a vector of
35                         size <literal>nc</literal>. If <literal>color(i)</literal> is
36                         negative the curve is plotted using the mark with id
37                         <literal>abs(style(i))</literal>; if <literal>style(i)</literal> is
38                         strictly positive, a plain line with color id
39                         <literal>style(i)</literal> or a dashed line with dash id
40                         <literal>style(i)</literal> is used.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>theta,alpha</term>
46                 <listitem>
47                     <para>real values giving in degree the spherical coordinates of the
48                         observation point. <emphasis>The default values are 35 and 45
49                             degree.
50                         </emphasis>
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>leg</term>
56                 <listitem>
57                     <para>string defining the captions for each axis with @ as a field
58                         separator, for example "X@Y@Z".
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>flag=[type,box]</term>
64                 <listitem>
65                     <para>
66                         <literal>type</literal> and <literal>box</literal> have the
67                         same meaning as in <literal>plot3d</literal>:
68                     </para>
69                     <variablelist>
70                         <varlistentry>
71                             <term>type</term>
72                             <listitem>
73                                 <para>an integer (scaling).</para>
74                                 <variablelist>
75                                     <varlistentry>
76                                         <term>type=0</term>
77                                         <listitem>
78                                             <para>the plot is made using the current 3D scaling (set
79                                                 by a previous call to <literal>param3d</literal>,
80                                                 <literal>plot3d</literal>, <literal>contour</literal> or
81                                                 <literal>plot3d1</literal>).
82                                             </para>
83                                         </listitem>
84                                     </varlistentry>
85                                     <varlistentry>
86                                         <term>type=1</term>
87                                         <listitem>
88                                             <para>rescales automatically 3d boxes with extreme
89                                                 aspect ratios, the boundaries are specified by the value
90                                                 of the optional argument <literal>ebox</literal>.
91                                             </para>
92                                         </listitem>
93                                     </varlistentry>
94                                     <varlistentry>
95                                         <term>type=2 </term>
96                                         <listitem>
97                                             <para>rescales automatically 3d boxes with extreme
98                                                 aspect ratios, the boundaries are computed using the
99                                                 given data. <emphasis>This is the default
100                                                     value.
101                                                 </emphasis>
102                                             </para>
103                                         </listitem>
104                                     </varlistentry>
105                                     <varlistentry>
106                                         <term>type=3</term>
107                                         <listitem>
108                                             <para>3d isometric with box bounds given by optional
109                                                 <literal>ebox</literal>, similarily to
110                                                 <literal>type=1</literal>.
111                                             </para>
112                                         </listitem>
113                                     </varlistentry>
114                                     <varlistentry>
115                                         <term>type=4</term>
116                                         <listitem>
117                                             <para>3d isometric bounds derived from the data,
118                                                 similarily<literal> to type=2</literal>.
119                                             </para>
120                                         </listitem>
121                                     </varlistentry>
122                                     <varlistentry>
123                                         <term>type=5</term>
124                                         <listitem>
125                                             <para>3d expanded isometric bounds with box bounds given
126                                                 by optional <literal>ebox</literal>, similarily to
127                                                 <literal>type=1</literal>.
128                                             </para>
129                                         </listitem>
130                                     </varlistentry>
131                                     <varlistentry>
132                                         <term>type=6</term>
133                                         <listitem>
134                                             <para>3d expanded isometric bounds derived from the
135                                                 data, similarily to <literal>type=2</literal>.Note that
136                                                 axes boundaries can be customized through the axes
137                                                 entity properties (see <link linkend="axes_properties">axes_properties</link>).
138                                             </para>
139                                         </listitem>
140                                     </varlistentry>
141                                 </variablelist>
142                             </listitem>
143                         </varlistentry>
144                         <varlistentry>
145                             <term>box</term>
146                             <listitem>
147                                 <para>an integer (frame around the plot).</para>
148                                 <variablelist>
149                                     <varlistentry>
150                                         <term>box=0</term>
151                                         <listitem>
152                                             <para>nothing is drawn around the plot.</para>
153                                         </listitem>
154                                     </varlistentry>
155                                     <varlistentry>
156                                         <term>box=1</term>
157                                         <listitem>
158                                             <para>unimplemented (like box=0).</para>
159                                         </listitem>
160                                     </varlistentry>
161                                     <varlistentry>
162                                         <term>box=2</term>
163                                         <listitem>
164                                             <para>only the axes behind the surface are drawn.</para>
165                                         </listitem>
166                                     </varlistentry>
167                                     <varlistentry>
168                                         <term>box=3</term>
169                                         <listitem>
170                                             <para>a box surrounding the surface is drawn and
171                                                 captions are added.
172                                             </para>
173                                         </listitem>
174                                     </varlistentry>
175                                     <varlistentry>
176                                         <term>box=4</term>
177                                         <listitem>
178                                             <para>a box surrounding the surface is drawn, captions
179                                                 and axes are added.Note that axes aspect can also be
180                                                 customized through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
181                                                 <emphasis>This is the default value.</emphasis>
182                                             </para>
183                                         </listitem>
184                                     </varlistentry>
185                                 </variablelist>
186                             </listitem>
187                         </varlistentry>
188                     </variablelist>
189                 </listitem>
190             </varlistentry>
191             <varlistentry>
192                 <term>ebox</term>
193                 <listitem>
194                     <para>It specifies the boundaries of the plot as the vector
195                         <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is
196                         used together with <literal>type</literal> in
197                         <literal>flag</literal> : if it is set to <literal>1</literal>,
198                         <literal>3</literal> or <literal>5</literal> (see above to see the
199                         corresponding behaviour). If <literal>flag</literal> is missing,
200                         <literal>ebox</literal> is not taken into acount. Note that, when
201                         specified, the <literal>ebox</literal> argument acts on the
202                         <literal>data_bounds</literal> field that can also be reset through
203                         the axes entity properties (see <link linkend="axes_properties">axes_properties</link>). The
204                         <literal>ebox</literal> default value is
205                         <literal>[0,1,0,1,0,1]</literal>.
206                     </para>
207                 </listitem>
208             </varlistentry>
209         </variablelist>
210     </refsection>
211     <refsection>
212         <title>Description</title>
213         <para>
214             <literal>param3d1</literal> is used to plot 3D curves defined by
215             their coordinates <literal>x</literal>, <literal>y</literal> and
216             <literal>z</literal>. Note that data can also be got or modified through
217             the surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
218         </para>
219         <para>
220             Note that properties like <literal>rotation angles</literal>,
221             <literal>colors</literal> and <literal>thickness</literal> of the plotted
222             curves can also be got or modified through the polyline entity properties
223             (see <link linkend="polyline_properties">polyline_properties</link>).
224         </para>
225         <para>
226             Enter the command <literal>param3d1()</literal> to see a
227             demo.
228         </para>
229     </refsection>
230     <refsection>
231         <title>Examples</title>
232         <programlisting role="example"><![CDATA[ 
233 xset('window',20) // create a window number 20
234 t=[0:0.1:5*%pi]';
235 param3d1([sin(t),sin(2*t)],[cos(t),cos(2*t)],..
236          list([t/10,sin(t)],[3,2]),35,45,"X@Y@Z",[2,3])
237
238 xdel(20);
239 a=get("current_axes");//get the handle of the newly created axes
240 t=[0:0.1:5*%pi]';
241 param3d1([sin(t),sin(2*t)],[cos(t),cos(2*t)],[t/10,sin(t)])
242 a.rotation_angles=[65,75]; 
243 a.data_bounds=[-1,-1,-1;1,1,2]; //boundaries given by data_bounds
244 a.thickness = 2;
245 h=a.children //get the handle of the param3d entity: an Compound composed of 2 curves
246 h.children(1).foreground = 3 // first curve
247 curve2 = h.children(2);
248 curve2.foreground = 6;
249 curve2.mark_style = 2;
250  ]]></programlisting>
251         <scilab:image>param3d1();</scilab:image>
252     </refsection>
253     <refsection role="see also">
254         <title>See Also</title>
255         <simplelist type="inline">
256             <member>
257                 <link linkend="param3d">param3d</link>
258             </member>
259             <member>
260                 <link linkend="plot3d">plot3d</link>
261             </member>
262             <member>
263                 <link linkend="plot2d">plot2d</link>
264             </member>
265             <member>
266                 <link linkend="gca">gca</link>
267             </member>
268             <member>
269                 <link linkend="xdel">xdel</link>
270             </member>
271             <member>
272                 <link linkend="delete">delete</link>
273             </member>
274         </simplelist>
275     </refsection>
276 </refentry>