* Bug 6155 fixed: param3d() & param3d1() pages merged & rewritten
[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  * Copyright (C) 2018 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org"  xml:id="param3d" xml:lang="en">
21     <refnamediv>
22         <refname>param3d</refname>
23         <refpurpose>plots a single curve in a 3D cartesian frame</refpurpose>
24     </refnamediv>
25     <refnamediv xml:id="param3d1">
26         <refname>param3d1</refname>
27         <refpurpose>plots a set of curves in a 3D cartesian frame. 1D mesh plot</refpurpose>
28     </refnamediv>
29     <refsynopsisdiv>
30         <title>Syntax</title>
31         <synopsis>
32             param3d(x, y, z)
33             param3d(x, y, z, [theta, alpha, leg, flag, ebox])
34             param3d   // demo
35
36             param3d1(X, Y, Z)
37             param3d1(X, Y, list(Z, styles))
38             param3d1(.., [theta, alpha, leg, flag, ebox])
39             param3d1  // demo
40         </synopsis>
41     </refsynopsisdiv>
42     <refsection>
43         <title>Arguments</title>
44         <variablelist>
45             <varlistentry>
46                 <term>x, y, z</term>
47                 <listitem>
48                     <para>3 vectors of the same length: cartesian coordinates of the curve's points.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>X, Y, Z</term>
54                 <listitem>
55                     <para>matrices of the same size (nl,nc).
56                      Each column #i of the matrices provides the coordinates of the points for the
57                      ith curve.
58                     </para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>styles</term>
63                 <listitem>
64                     <para>
65                         vector of nc=size(Z,"c") integers specifying the style -- line color or mark
66                         style -- of each curve. When it is specified, it must be bundled with
67                         <varname>Z</varname> into a list, using <literal>list(Z, styles)</literal>.
68                     </para>
69                     <para>
70                         By default, lines are drawn with colors indexed from 1 to nc in the current
71                         color map, without mark.
72                     </para>
73                     <para>
74                         If <literal>styles(i)&lt;0</literal>, the curve #i is plotted only with
75                         marks of style #|styles(i)|, without line.
76                     </para>
77                     <para>
78                         Otherwise (<literal>styles(i)>0</literal>), the curve #i is rendered as a
79                         solid line of color #styles(i), without marks.
80                     </para>
81                 </listitem>
82             </varlistentry>
83             <varlistentry>
84                 <term>theta</term>
85                 <listitem>
86                     <para>Polar angle of the (OP) observation point to the north pole (Oz+), in degrees,
87                         from 0 to 180. Default = 35°.
88                     </para>
89                 </listitem>
90             </varlistentry>
91             <varlistentry>
92                 <term>alpha</term>
93                 <listitem>
94                     <para>
95                         Azimuth angle of the (OP) observation point, around the (OZ+) axis,
96                         in degrees. Default = 45°.
97                     </para>
98                 </listitem>
99             </varlistentry>
100             <varlistentry>
101                 <term>leg</term>
102                 <listitem>
103                     <para>single string setting the labels for the 3 axes. "@" is used as a labels
104                         separator. Default = "X@Y@Z"
105                     </para>
106                 </listitem>
107             </varlistentry>
108             <varlistentry>
109                 <term>flag = [type, box]</term>
110                 <listitem>
111                     <para>
112                         <literal>type</literal> and <literal>box</literal> have the
113                         same meaning as in <literal>plot3d</literal>:
114                     </para>
115                     <variablelist>
116                         <varlistentry>
117                             <term>type</term>
118                             <listitem>
119                                 <para>Sets the axes scaling and bounding modes. Default = 2.</para>
120                                 <para>
121                                 <table border="1">
122                                 <tr>
123                                     <th>type</th>
124                                     <th>gca().isoview</th>
125                                     <th>data bounds</th>
126                                 </tr>
127                                 <tr>
128                                     <th>0</th>
129                                     <td  align="center">off</td>
130                                     <td  align="center">[0,1, 0,1, -1,1]</td>
131                                 </tr>
132                                 <tr>
133                                     <th>1</th>
134                                     <td  align="center">off</td>
135                                     <td  align="center">in <literal>ebox</literal></td>
136                                 </tr>
137                                 <tr>
138                                     <th>2</th>
139                                     <td  align="center">off</td>
140                                     <td  align="center">from data points</td>
141                                 </tr>
142                                 <tr>
143                                     <th>3</th>
144                                     <td  align="center">on</td>
145                                     <td  align="center">in <literal>ebox</literal></td>
146                                 </tr>
147                                 <tr>
148                                     <th>4</th>
149                                     <td  align="center">on</td>
150                                     <td  align="center">from data points</td>
151                                 </tr>
152                                 <tr>
153                                     <th>5</th>
154                                     <td  align="center">on</td>
155                                     <td  align="center">in <literal>ebox</literal></td>
156                                 </tr>
157                                 <tr>
158                                     <th>6</th>
159                                     <td  align="center">on</td>
160                                     <td  align="center">from data points</td>
161                                 </tr>
162                                 </table>
163                                 </para>
164                                                                 <note>
165                                                                         Isometrical modes are rendered with <literal>gca().cube_scaling="off"</literal>.
166                                                                 </note>
167                             </listitem>
168                         </varlistentry>
169                         <varlistentry>
170                             <term>box</term>
171                             <listitem>
172                                 <para>
173                                     an integer controlling the display of the axes frame (default = 4).
174                                 </para>
175                                 <para>
176                                     <table border="1">
177                                         <tr>
178                                             <th>Value</th>
179                                             <th>Displayed axes</th>
180                                             <th>Axes legends</th>
181                                             <th>gca().box</th>
182                                             <th>gca().axes_visible</th>
183                                         </tr>
184                                         <tr>
185                                             <th>0</th>
186                                             <td>none. No frame.</td>
187                                             <td align="center">yes</td>
188                                             <td align="center">"off"</td>
189                                             <td align="center">"off"</td>
190                                         </tr>
191                                         <tr>
192                                             <th>1</th>
193                                             <td>not implemented. Like 0. Please use 0.</td>
194                                             <td></td>
195                                             <td></td>
196                                             <td></td>
197                                         </tr>
198                                         <tr>
199                                             <th>2</th>
200                                             <td>only axes lines on the back</td>
201                                             <td align="center">NO</td>
202                                             <td align="center">"hidden_axes"</td>
203                                             <td align="center">"off"</td>
204                                         </tr>
205                                         <tr>
206                                             <th>3</th>
207                                             <td>full ungraduated box</td>
208                                             <td align="center">yes</td>
209                                             <td align="center">"on"</td>
210                                             <td align="center">"off"</td>
211                                         </tr>
212                                         <tr>
213                                             <th>4</th>
214                                             <td>full box + 3 graduated axes</td>
215                                             <td align="center">yes</td>
216                                             <td align="center">"on"</td>
217                                             <td align="center">"on"</td>
218                                         </tr>
219                                     </table>
220                                 </para>
221                             </listitem>
222                         </varlistentry>
223                     </variablelist>
224                 </listitem>
225             </varlistentry>
226             <varlistentry>
227                 <term>ebox</term>
228                 <listitem>
229                     <para>
230                         Vector <literal>[xmin,xmax, ymin,ymax, zmin,zmax]</literal> of axes bounds,
231                         used and assigned to <literal>gca().data_bounds</literal> when the
232                         <varname>flag</varname> option is used with the <varname>type</varname>=1|3|5.
233                         By default set to [0,1, 0,1, 0,1].
234                     </para>
235                 </listitem>
236             </varlistentry>
237         </variablelist>
238     </refsection>
239     <refsection>
240         <title>Description</title>
241         <para>
242             <literal>param3d()</literal> is used to plot a single 3D curve defined by its coordinates
243             <literal>x</literal>, <literal>y</literal> and <literal>z</literal>.
244         </para>
245         <para>
246             The curve is an object of <literal>polyline</literal> type. When it is used just after
247             <literal>param3d()</literal>, <function>gce</function>() returns the curve's identifier,
248             from which all the curve's properties may be changed: color, line style, thickness,
249             mark style and colors, etc.
250         </para>
251         <para>
252             <literal>param3d1()</literal> is used to plot a set of 3D curves, all having the
253             same number of points. Then, <function>gce</function><literal>().children</literal>
254             returns the vector of identifiers of the whole set of curves.
255             <note>
256                 The graphical identifier of the curve #i is <literal>gce().children($-i+1)</literal>.
257             </note>
258         </para>
259     </refsection>
260
261     <refsection>
262         <title>Examples</title>
263         <programlisting role="example"><![CDATA[
264 t = 0:0.1:5*%pi;
265 r = (max(t)-t)/10;
266
267 clf
268 param3d(r.*sin(t), r.*cos(t), t/10, 30, 72,"X@Y@Z",[4,4])
269
270 curve = gce();
271 curve.mark_mode = "on";
272 curve.mark_style = 10;
273 curve.mark_foreground = color("magenta");
274  ]]></programlisting>
275         <scilab:image>
276         t =  0:0.1:5*%pi;
277         r = (max(t)-t)/10;
278         clf
279         param3d(r.*sin(t), r.*cos(t), t/10, 30, 72,"X@Y@Z",[4,4])
280
281         curve = gce();
282         curve.mark_mode = "on";
283         curve.mark_style = 10;
284         curve.mark_foreground = color("magenta");
285         // ----------------------------
286         gca().sub_ticks = [4 4 4];
287         gcf().axes_size = [620 410];
288         </scilab:image>
289         <para/>
290         <para>
291             <emphasis role="bold">box parameter </emphasis> illustrated with
292             <emphasis role="bold">param3d1()</emphasis> used for a single curve :
293         </para>
294         <programlisting role="example"><![CDATA[
295 t = (0:0.1:5*%pi)';
296 r = (max(t)-t)/10;
297 x = r.*sin(t); y = r.*cos(t); z = list(t/10, color("orange"));
298 Box = [0 2 3 4];
299
300 clf
301 for i = 1:4
302    subplot(2,2,i)
303    param3d1(x, y, z, 31, 72,"X legend@Y legend@Z legend",[4, Box(i)])
304    title(msprintf("box = %d",Box(i)), "fontsize", 4)
305 end
306 gcf().children.children.thickness = 2; // for the 4 curves in a once
307 gca().sub_ticks = [4 4 4];             // only for the last axes
308  ]]></programlisting>
309         <scilab:image>
310 t = (0:0.1:5*%pi)';
311 r = (max(t)-t)/10;
312 x = r.*sin(t); y = r.*cos(t); z = list(t/10, color("orange"));
313 Box = [0 2 3 4];
314 clf
315 for i = 1:4
316    subplot(2,2,i)
317    param3d1(x, y, z, 31, 72,"X legend@Y legend@Z legend",[4, Box(i)])
318    title(msprintf("box = %d",Box(i)), "fontsize", 4)
319 end
320 gcf().children.children.thickness = 2;
321 // -------------------
322 gcf().axes_size = [820 470];
323 gca().sub_ticks = [4 4 4];
324         </scilab:image>
325         <para/>
326         <para>
327             <emphasis role="bold">param3d1() used for an actual set of curves:</emphasis>
328         </para>
329         <programlisting role="example"><![CDATA[
330 [X, Y] = ndgrid(-11:0.5:9);
331 R = sqrt(X.*X + Y.*Y) + %eps;
332 Z = sin(R)./R;
333
334 clf
335 subplot(1,3,1)
336 param3d1(X, Y, Z, 150, 85, flag=[2,4])
337
338 subplot(1,3,2)
339 param3d1(X, Y, Z, 150, 85, flag=[2,4])
340 gce().children.foreground = color("green");
341
342 subplot(1,3,3)
343 param3d1(X, Y, Z, 150, 85, flag=[2,4])
344 curves = gce().children;
345 curves(1:2:$).foreground = color("orange");
346 gca().box = "back_half";
347
348 gcf().children.foreground = color("grey70"); // box & ticks color for the 3 figures
349  ]]></programlisting>
350         <scilab:image>
351         [X, Y] = ndgrid(-11:0.5:9);
352         R = sqrt(X.*X + Y.*Y) + %eps;
353         Z = sin(R)./R;
354
355         clf
356         subplot(1,3,1)
357         param3d1(X, Y, Z, 150, 85, flag=[2,4])
358
359         subplot(1,3,2)
360         param3d1(X, Y, Z, 150, 85, flag=[2,4])
361         gce().children.foreground = color("green");
362
363         subplot(1,3,3)
364         param3d1(X, Y, Z, 150, 85, flag=[2,4])
365         curves = gce().children;
366         curves(1:2:$).foreground = color("orange");
367         gca().box = "back_half";
368
369         gcf().children.foreground = color("grey70"); // box and ticks color for the 3 figures
370         // ----------
371         gcf().children.sub_ticks = [4 4 4];
372         gcf().axes_size = [940 350];
373         </scilab:image>
374         <para/>
375         <programlisting role="example"><![CDATA[
376 [X, Y] = ndgrid(-11:0.5:9, -7:0.5:6); // x is the long side, y the short one
377 // => X has constant rows. Y has constant columns
378
379 clf
380
381 // Meshing lines at constant Y values
382 subplot(1, 3, 1)
383 R = sqrt(X.*X + Y.*Y) + %eps;
384 Z = sin(R)./R;
385 param3d1(X, Y, Z, 150, 85, flag=[2,4])
386
387 // Meshing lines at constant X values, with transposed X and Y:
388 subplot(1, 3, 2)
389 R = sqrt(X'.*X' + Y'.*Y') + %eps;
390 Z = sin(R)./R;
391 param3d1(X', Y', Z, 150, 85, flag=[2,4])
392
393 // With a curtain and filled curves to avoid messed overlaying parts
394 subplot(1, 3, 3)
395 [Xo, Yo] = ndgrid(-10:0.5:10);
396 R = sqrt(Xo.*Xo + Yo.*Yo) + %eps;
397 Zo = sin(R)./R;
398     // we add the curtain on starting and ending sides
399 nc = size(Xo,"c");
400 zmin = min(Zo);
401 X = [Xo(1,:) ; Xo ; Xo($,:)];
402 Y = [Yo(1,:) ; Yo ; Yo($,:)];
403 Z = [zmin*ones(1,nc) ; Zo ; zmin*ones(1,nc)];
404     // Rendering
405 param3d1(X, Y, Z, 150, 85, flag=[2,4])
406 e = gce();
407 e.children.fill_mode = "on";
408
409 // grey box for all axes:
410 gcf().children.foreground = color("grey70");
411  ]]></programlisting>
412         <scilab:image>
413                 [X, Y] = ndgrid(-11:0.5:9, -7:0.5:6); // x is the long side, y the short one
414                 // => X has constant rows. Y has constant columns
415
416                 clf
417
418                 // Meshing lines at constant Y values
419                 subplot(1, 3, 1)
420                 R = sqrt(X.*X + Y.*Y) + %eps;
421                 Z = sin(R)./R;
422                 param3d1(X, Y, Z, 150, 85, flag=[2,4])
423
424                 // Meshing lines at constant X values, with transposed X and Y:
425                 subplot(1, 3, 2)
426                 R = sqrt(X'.*X' + Y'.*Y') + %eps;
427                 Z = sin(R)./R;
428                 param3d1(X', Y', Z, 150, 85, flag=[2,4])
429
430                 // With a curtain and filled curves to avoid messed overlaying parts
431                 subplot(1, 3, 3)
432                 [Xo, Yo] = ndgrid(-10:0.5:10);
433                 R = sqrt(Xo.*Xo + Yo.*Yo) + %eps;
434                 Zo = sin(R)./R;
435                         // we add the curtain on starting and ending sides
436                 nc = size(Xo,"c");
437                 zmin = min(Zo);
438                 X = [Xo(1,:) ; Xo ; Xo($,:)];
439                 Y = [Yo(1,:) ; Yo ; Yo($,:)];
440                 Z = [zmin*ones(1,nc) ; Zo ; zmin*ones(1,nc)];
441                         // Rendering
442                 param3d1(X, Y, Z, 150, 87, flag=[2,4])
443                 e = gce();
444                 e.children.fill_mode = "on";
445
446                 // grey box for all axes:
447                 gcf().children.foreground = color("grey70");
448         // ----------------------------
449         gcf().axes_size = [900 260];
450         </scilab:image>
451     </refsection>
452     <refsection role="see also">
453         <title>See also</title>
454         <simplelist type="inline">
455             <member>
456                 <link linkend="plot3d">plot3d</link>
457             </member>
458             <member>
459                 <link linkend="plot3d3">plot3d3</link>
460             </member>
461             <member>
462                 <link linkend="scatter3">scatter 3D</link>
463             </member>
464             <member>
465                 <link linkend="axes_properties">axes_properties</link>
466             </member>
467             <member>
468                 <link linkend="polyline_properties">polyline_properties</link>
469             </member>
470         </simplelist>
471     </refsection>
472 </refentry>