* Bug 15392 fixed: comet() comet3d() with named|#RRGGBB|[r g b] colors
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / comet.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-2019 - 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="comet">
19     <refnamediv>
20         <refname>comet</refname>
21         <refpurpose>2D comet animated plot</refpurpose>
22     </refnamediv>
23     <refsynopsisdiv>
24         <title>Syntax</title>
25         <synopsis>
26             comet(y)
27             comet(x, y)
28             comet(x, y, Lf)
29             comet(x, fun)
30             comet(x, fun, Lf)
31             comet(..., "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. If omitted, it is assumed to be the vector
41                     <literal>1:np</literal> where <literal>np</literal> is the total number of
42                     curve points (see below). As a matrix, each column defines the abscissae
43                     of the trace of a separate comet.
44                     <para/>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>y</term>
49                 <listitem>
50                     a real vector or matrix. As a matrix, each column defines the  ordinates
51                     of the trace of a separate comet.
52                     <literal>nc=size(y,"c")</literal> is the number of comets simultaneously drawn.
53                     <para/>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>Lf</term>
58                 <listitem>
59                     a real scalar in the interval<literal>[0,1[</literal>. Default value is 0.1:
60                     It defines the Leading fraction of the comet's trace.
61                     The <literal>k=Lf*np</literal> most recent points are plotted in thicker line.
62                     <para/>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>fun</term>
67                 <listitem>
68                     a scilab function with syntax <literal>y = fun(x)</literal>.
69                     <varname>fun</varname> can also be a polynomial or a rational fraction.
70                     <para/>
71                 </listitem>
72             </varlistentry>
73             <varlistentry>
74                 <term>c</term>
75                 <listitem>
76                     <literal>nc</literal> colors of the <literal>nc</literal> comets traces.
77                     They may be specified as a vector of <literal>nc</literal> color indices or
78                     <link linkend="color_list">color names</link> or "#RRGGBB" hexadecimal
79                     color codes. Or by a matrix (ncx3) of <literal>[r,g,b]</literal> vectors of
80                     Red-Green-Blue intensities in the [0,1] interval.
81                     <para/>
82                 </listitem>
83             </varlistentry>
84         </variablelist>
85     </refsection>
86     <refsection>
87         <title>Description</title>
88         <para>
89             If <literal>(x,y)</literal> are two vectors, this function draws a 2D comet animated
90             plot showing the progression of the curve <literal>(x(1:m),y(1:m))</literal> for
91             <literal>m</literal> varying from <literal>1</literal> to
92             <literal>np=length(x)</literal>.
93         </para>
94         <para>
95             The plot is made of three parts:
96             <table>
97                 <tr><td><emphasis role="bold">a head</emphasis></td>
98                     <td>
99                         mark that shows the current <literal>(x(i),y(i))</literal> position.
100                     </td>
101                 </tr>
102                 <tr><td><emphasis role="bold">a body</emphasis></td>
103                     <td>consisting in the <literal>k=round(Lf*np)</literal> most recent points
104                         of the trajectory, displayed as a thicker part of the trace.
105                     </td>
106                 </tr>
107                 <tr><td><emphasis role="bold">a tail</emphasis></td>
108                     <td>
109                         that shows the  <literal>(x(1:i-k),y(1:i-k))</literal> part of the curve.
110                     </td>
111                 </tr>
112             </table>
113             <para>
114                 <literal>comet(x,fun,...)</literal> is equivalent to
115                 <literal>comet(x, feval(x,fun),...)</literal>.
116             </para>
117             <para>
118                 If <varname>x</varname> and <varname>y</varname> are matrices with identical sizes,
119                 then animated curves are drawn for each pair <literal>(x(:,j),y(:,j))</literal>.
120                 In this case <literal>np</literal> is the number of rows of
121                 <varname>x</varname> and <varname>y</varname>.
122             </para>
123             <para>
124                 <literal>comet(...,"colors",c)</literal> can be used to set the colors of each
125                 trajectory.
126             </para>
127         </para>
128     </refsection>
129     <refsection>
130         <title>Examples</title>
131         <programlisting role="example"><![CDATA[
132 // One comet in spiral:
133 t = linspace(0, 10*%pi, 500);
134 clf, isoview
135 comet(t.*sin(t), t.*cos(t), "colors", "orange")
136     ]]></programlisting>
137         <inlinemediaobject>
138             <imageobject>
139                 <imagedata fileref="../../images/comet_1.png"/>
140             </imageobject>
141         </inlinemediaobject>
142         <para/>
143         <programlisting role="example"><![CDATA[
144 // Two simultaneous comets with default colors:
145 t = linspace(0, 10*%pi, 500)';
146 clf
147 comet(t.*sin(t), [t.*sin(2*t) t.*sin(3*t)])
148     ]]></programlisting>
149         <para/>
150         <programlisting role="example"><![CDATA[
151 // Chosen colors:
152 t = linspace(0, 10*%pi, 500)';
153 clf
154 comet(t.*sin(t), [t.*cos(t) t.*sin(2*t)], "colors", ["orange" "mag"])
155     ]]></programlisting>
156         <inlinemediaobject>
157             <imageobject>
158                 <imagedata fileref="../../images/comet_2.png"/>
159             </imageobject>
160         </inlinemediaobject>
161         <para/>
162         <programlisting role="example"><![CDATA[
163 function y = traj(x)
164     y = 1.5*sin(x^2)
165 endfunction
166 clf
167 comet(linspace(0,5,500),traj)
168     ]]></programlisting>
169         <para/>
170         <programlisting role="example"><![CDATA[
171 clf
172 comet(linspace(-2,4,500), (%s-3)/(%s^3+2*%s^2+1))
173     ]]></programlisting>
174     </refsection>
175     <refsection role="see also">
176         <title>See also</title>
177         <simplelist type="inline">
178             <member>
179                 <link linkend="comet3d">comet3d</link>
180             </member>
181             <member>
182                 <link linkend="paramfplot2d">paramfplot2d</link>
183             </member>
184             <member>
185                 <link linkend="realtime">realtime</link>
186             </member>
187             <member>
188                 <link linkend="color_list">colors names</link>
189             </member>
190         </simplelist>
191     </refsection>
192     <refsection>
193         <title>History</title>
194         <revhistory>
195             <revision>
196                 <revnumber>5.3.2</revnumber>
197                 <revremark>
198                     Function comet() introduced.
199                 </revremark>
200             </revision>
201             <revision>
202                 <revnumber>6.1.0</revnumber>
203                 <revremark>
204                     Colors can now be specified also by their name, or by their "#RRGGBB" hexadecimal
205                     code, or by their [r g b] Red-Green-Blue intensities.
206                 </revremark>
207             </revision>
208         </revhistory>
209     </refsection>
210 </refentry>