fab58fb142564c3d2a10bcdb3d458f72a0a635b4
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / param3d.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="param3d" xml:lang="en">
17     <refnamediv>
18         <refname>param3d</refname>
19         <refpurpose>3D plot of a parametric curve</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>param3d(x,y,z,[theta,alpha,leg,flag,ebox])</synopsis>
24     </refsynopsisdiv>
25     <refsection>
26         <title>Arguments</title>
27         <variablelist>
28             <varlistentry>
29                 <term>x,y,z</term>
30                 <listitem>
31                     <para>three vectors of the same size (points of the parametric
32                         curve).
33                     </para>
34                 </listitem>
35             </varlistentry>
36             <varlistentry>
37                 <term>theta, alpha</term>
38                 <listitem>
39                     <para>real values giving in degree the spherical coordinates of the
40                         observation point. <emphasis>The default values are 35 and 45
41                             degree.
42                         </emphasis>
43                     </para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>leg</term>
48                 <listitem>
49                     <para>string defining the labels for each axis with @ as a field
50                         separator, for example "X@Y@Z".
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>flag=[type,box]</term>
56                 <listitem>
57                     <para>
58                         <literal>type</literal> and <literal>box</literal> have the
59                         same meaning as in <literal>plot3d</literal>:
60                     </para>
61                     <variablelist>
62                         <varlistentry>
63                             <term>type</term>
64                             <listitem>
65                                 <para>an integer (scaling).</para>
66                                 <variablelist>
67                                     <varlistentry>
68                                         <term>type=0</term>
69                                         <listitem>
70                                             <para>the plot is made using the current 3D scaling (set
71                                                 by a previous call to <literal>param3d</literal>,
72                                                 <literal>plot3d</literal>, <literal>contour</literal> or
73                                                 <literal>plot3d1</literal>).
74                                             </para>
75                                         </listitem>
76                                     </varlistentry>
77                                     <varlistentry>
78                                         <term>type=1</term>
79                                         <listitem>
80                                             <para>rescales automatically 3d boxes with extreme
81                                                 aspect ratios, the boundaries are specified by the value
82                                                 of the optional argument <literal>ebox</literal>.
83                                             </para>
84                                         </listitem>
85                                     </varlistentry>
86                                     <varlistentry>
87                                         <term>type=2</term>
88                                         <listitem>
89                                             <para>rescales automatically 3d boxes with extreme
90                                                 aspect ratios, the boundaries are computed using the
91                                                 given data. <emphasis>This is the default
92                                                     value.
93                                                 </emphasis>
94                                             </para>
95                                         </listitem>
96                                     </varlistentry>
97                                     <varlistentry>
98                                         <term>type=3</term>
99                                         <listitem>
100                                             <para>3d isometric with box bounds given by optional
101                                                 <literal>ebox</literal>, similarily to
102                                                 <literal>type=1</literal>.
103                                             </para>
104                                         </listitem>
105                                     </varlistentry>
106                                     <varlistentry>
107                                         <term>type=4</term>
108                                         <listitem>
109                                             <para>3d isometric bounds derived from the data,
110                                                 similarily<literal> to type=2</literal>.
111                                             </para>
112                                         </listitem>
113                                     </varlistentry>
114                                     <varlistentry>
115                                         <term>type=5</term>
116                                         <listitem>
117                                             <para>3d expanded isometric bounds with box bounds given
118                                                 by optional <literal>ebox</literal>, similarily to
119                                                 <literal>type=1</literal>.
120                                             </para>
121                                         </listitem>
122                                     </varlistentry>
123                                     <varlistentry>
124                                         <term>type=6</term>
125                                         <listitem>
126                                             <para>3d expanded isometric bounds derived from the
127                                                 data, similarily to <literal>type=2</literal>.Note that
128                                                 axes boundaries can be customized through the axes
129                                                 entity properties (see <link linkend="axes_properties">axes_properties</link>).
130                                             </para>
131                                         </listitem>
132                                     </varlistentry>
133                                 </variablelist>
134                             </listitem>
135                         </varlistentry>
136                         <varlistentry>
137                             <term>box</term>
138                             <listitem>
139                                 <para>an integer (frame around the plot).</para>
140                                 <variablelist>
141                                     <varlistentry>
142                                         <term>box=0</term>
143                                         <listitem>
144                                             <para>nothing is drawn around the plot.</para>
145                                         </listitem>
146                                     </varlistentry>
147                                     <varlistentry>
148                                         <term>box=1</term>
149                                         <listitem>
150                                             <para>unimplemented (like box=0).</para>
151                                         </listitem>
152                                     </varlistentry>
153                                     <varlistentry>
154                                         <term>box=2</term>
155                                         <listitem>
156                                             <para>only the axes behind the surface are drawn.</para>
157                                         </listitem>
158                                     </varlistentry>
159                                     <varlistentry>
160                                         <term>box=3</term>
161                                         <listitem>
162                                             <para>a box surrounding the surface is drawn and
163                                                 captions are added.
164                                             </para>
165                                         </listitem>
166                                     </varlistentry>
167                                     <varlistentry>
168                                         <term>box=4</term>
169                                         <listitem>
170                                             <para>a box surrounding the surface is drawn, captions
171                                                 and axes are added.Note that axes aspect can also be
172                                                 customized through the axes entity properties (see <link linkend="axes_properties">axes_properties</link>).
173                                                 <emphasis>This is the default value.</emphasis>
174                                             </para>
175                                         </listitem>
176                                     </varlistentry>
177                                 </variablelist>
178                             </listitem>
179                         </varlistentry>
180                     </variablelist>
181                 </listitem>
182             </varlistentry>
183             <varlistentry>
184                 <term>ebox</term>
185                 <listitem>
186                     <para>It specifies the boundaries of the plot as the vector
187                         <literal>[xmin,xmax,ymin,ymax,zmin,zmax]</literal>. This argument is
188                         used together with <literal>type</literal> in
189                         <literal>flag</literal> : if it is set to <literal>1</literal>,
190                         <literal>3</literal> or <literal>5</literal> (see above to see the
191                         corresponding behaviour). If <literal>flag</literal> is missing,
192                         <literal>ebox</literal> is not taken into account. Note that, when
193                         specified, the <literal>ebox</literal> argument acts on the
194                         <literal>data_bounds</literal> field that can also be reset through
195                         the axes entity properties (see <link linkend="axes_properties">axes_properties</link>). The ebox default
196                         value is [0,1,0,1,0,1].
197                     </para>
198                 </listitem>
199             </varlistentry>
200         </variablelist>
201     </refsection>
202     <refsection>
203         <title>Description</title>
204         <para>
205             <literal>param3d</literal> is used to plot a 3D curve defined by its
206             coordinates <literal>x</literal>, <literal>y</literal> and
207             <literal>z</literal>. Note that data can also be got or modified through
208             the surface entity properties (see <link linkend="surface_properties">surface_properties</link>).
209         </para>
210         <para>
211             Note that properties like <literal>rotation angles</literal>,
212             <literal>colors</literal> and <literal>thickness</literal> of the plotted
213             curves can also be got or modified through the polyline entity properties
214             (see <link linkend="polyline_properties">polyline_properties</link>).
215         </para>
216         <para>
217             Use <literal>param3d1</literal> to do multiple plots.
218         </para>
219         <para>
220             Enter the command <literal>param3d()</literal> to see a demo.
221         </para>
222     </refsection>
223
224     <refsection>
225         <title>Examples</title>
226         <programlisting role="example"><![CDATA[
227 t=0:0.1:5*%pi;
228 param3d(sin(t),cos(t),t/10,35,45,"X@Y@Z",[2,3])
229
230 e=gce() //the handle on the 3D polyline
231
232 e.foreground=color('red');
233
234 a=gca(); //the handle on the axes
235 a.rotation_angles=[10 70];
236  ]]></programlisting>
237         <scilab:image>
238             t=0:0.1:5*%pi;
239             param3d(sin(t),cos(t),t/10,35,45,"X@Y@Z",[2,3])
240
241             e=gce() //the handle on the 3D polyline
242
243             e.foreground=color('red');
244
245             a=gca(); //the handle on the axes
246             a.rotation_angles=[10 70];
247         </scilab:image>
248     </refsection>
249     <refsection role="see also">
250         <title>See also</title>
251         <simplelist type="inline">
252             <member>
253                 <link linkend="param3d1">param3d1</link>
254             </member>
255             <member>
256                 <link linkend="plot3d">plot3d</link>
257             </member>
258         </simplelist>
259     </refsection>
260 </refentry>