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