* Bug 15392 fixed: comet() comet3d() with named|#RRGGBB|[r g b] colors
[scilab.git] / scilab / modules / graphics / help / en_US / 3d_plot / comet3d.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) Serge Steer
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2018 - Samuel GOUGEON
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 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
16           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
17           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
18           xml:lang="en_US" xml:id="comet3d">
19     <refnamediv>
20         <refname>comet3d</refname>
21         <refpurpose>3D comet animated plot</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26             comet3d(z)
27             comet3d(x, y, z)
28             comet3d(x, y, z, Lf)
29             comet3d(x, y, fun)
30             comet3d(x, y, fun, Lf)
31             comet3d(...,"colors", c)
32         </synopsis>
33     </refsynopsisdiv>
34     <refsection>
35         <title>Parameters</title>
36         <variablelist>
37             <varlistentry>
38                 <term>x</term>
39                 <listitem>
40                     a real vector or matrix. Default = <literal>1:np</literal>,
41                     <literal>np</literal> being the number of points of the trajectory.
42                     As a matrix, each column defines the x coordinates of the trace of an
43                     individual comet.
44                     <para/>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>y</term>
49                 <listitem>
50                     a real vector (default value = <literal>1:np</literal>) or matrix.
51                     As a matrix, each column defines the y coordinates of the trace of an
52                     individual comet.
53                     <para/>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>z</term>
58                 <listitem>
59                     a real vector of length <literal>np</literal>, or a matrix with
60                     <literal>np</literal> rows. As a matrix, each column defines the z
61                     coordinates of the trace of an individual comet.
62                     <literal>nc=size(z,"c")</literal> is the number of comets simultaneously drawn.
63                     <para/>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>Lf</term>
68                 <listitem>
69                     a real scalar in the interval<literal>[0,1[</literal>. Default value is 0.1:
70                     It defines the Leading fraction of the comet's trace.
71                     The <literal>k=Lf*np</literal> most recent points are plotted in thicker line.
72                     <para/>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>fun</term>
77                 <listitem>
78                     a scilab function with syntax <literal>z=fun(x,y)</literal>.
79                     <para/>
80                 </listitem>
81             </varlistentry>
82             <varlistentry>
83                 <term>c</term>
84                 <listitem>
85                     <literal>nc</literal> colors of the <literal>nc</literal> comets traces.
86                     They may be specified as a vector of <literal>nc</literal> color indices or
87                     <link linkend="color_list">color names</link> or "#RRGGBB" hexadecimal
88                     color codes. Or by a matrix (ncx3) of <literal>[r,g,b]</literal> vectors of
89                     Red-Green-Blue intensities in the [0,1] interval.
90                     <para/>
91                 </listitem>
92             </varlistentry>
93         </variablelist>
94     </refsection>
95     <refsection>
96         <title>Description</title>
97         <para>
98             If <literal>(x,y,z)</literal> are three vectors with the same number of elements, this
99             function draws a 3D comet animated plot. The plot is made of three parts:
100             <table>
101                 <tr><td><emphasis role="bold">a head</emphasis></td>
102                     <td>
103                         mark that shows the current <literal>(x(i),y(i),z(i))</literal> position.
104                     </td>
105                 </tr>
106                 <tr><td><emphasis role="bold">a body</emphasis></td>
107                     <td>consisting in the <literal>k=round(Lf*np)</literal> most recent points
108                         of the trajectory, displayed as a thicker part of the trace.
109                     </td>
110                 </tr>
111                 <tr><td><emphasis role="bold">a tail</emphasis></td>
112                     <td>
113                     that shows the  <literal>[x(1:i-k), y(1:i-k), z(1:i-k)]</literal> part of the curve.
114                     </td>
115                 </tr>
116             </table>
117             <para>
118                 if <literal>z</literal> is a matrix and <literal>x</literal> and <literal>y</literal>
119                 are vectors, then animated curves are drawn for each triple
120                 <literal>(x, y, z(:,j))</literal>.
121             </para>
122             <para>
123                 if <literal>x,y,z</literal> are matrices with the same dimensions then animated curves
124                 are drawn for each triple <literal>(x(:,j), y(:,j), z(:,j))</literal>.
125             </para>
126             <para>
127                 <literal>comet3d(x, y, fun,...)</literal> computes the <literal>z</literal> vector as
128                 <literal>z(i)=fun(x(i),y(i))</literal>.
129             </para>
130             <para>
131                 <literal>comet3d(..,"colors",c)</literal> can be used to set the colors of each
132                 trajectory.
133             </para>
134         </para>
135     </refsection>
136     <refsection>
137         <title>Examples</title>
138         <programlisting role="example"><![CDATA[
139 t = linspace(-%pi,%pi,500);
140 clf
141 comet3d(sin(5*t), sin(t), t.^2)
142     ]]></programlisting>
143         <programlisting role="example"><![CDATA[
144 t = linspace(-%pi,%pi,500)';
145 clf
146 comet3d(sin(5*t), sin(t), [t.^2,ones(t)])
147     ]]></programlisting>
148         <programlisting role="example"><![CDATA[
149 // Chosen colors:
150 t = linspace(0, 10*%pi, 500)';
151 clf, gca().rotation_angles = [26, 112];
152 comet3d(t.*sin(t), t, [t.*sin(2*t) t.*sin(3*t)], "colors", ["orange" "red"])
153     ]]></programlisting>
154         <programlisting role="example"><![CDATA[
155 t = linspace(-%pi,%pi,500)';
156 function z = traj(x,y), z = 1.5*sin(x^2)*cos(y), endfunction
157 clf
158 comet3d(cos(t),sin(t),traj)
159     ]]></programlisting>
160     </refsection>
161     <refsection role="see also">
162         <title>See also</title>
163         <simplelist type="inline">
164             <member>
165                 <link linkend="comet">comet</link>
166             </member>
167             <member>
168                 <link linkend="paramfplot2d">paramfplot2d</link>
169             </member>
170             <member>
171                 <link linkend="realtime">realtime</link>
172             </member>
173             <member>
174                 <link linkend="color_list">colors names</link>
175             </member>
176         </simplelist>
177     </refsection>
178     <refsection>
179         <title>History</title>
180         <revhistory>
181             <revision>
182                 <revnumber>5.3.2</revnumber>
183                 <revremark>Function comet3d() introduced.</revremark>
184             </revision>
185             <revision>
186                 <revnumber>6.1.0</revnumber>
187                 <revremark>
188                     Colors can now be specified also by their name, or by their "#RRGGBB" hexadecimal
189                     code, or by their [r g b] Red-Green-Blue intensities.
190                 </revremark>
191             </revision>
192         </revhistory>
193     </refsection>
194 </refentry>