0a4487ea024ab42028f8758b4c68d6c96fe4e05f
[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  *
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 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en_US" xml:id="comet">
16     <refnamediv>
17         <refname>comet</refname>
18         <refpurpose>2D comet animated plot. </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Syntax</title>
22         <synopsis>
23             comet(y)
24             comet(x,y)
25             comet(x,fun)
26             comet(x,y,p)
27             comet(x,fun,p)
28             comet(...,"colors",c)
29         </synopsis>
30     </refsynopsisdiv>
31     <refsection>
32         <title>Parameters</title>
33         <variablelist>
34             <varlistentry>
35                 <term>x</term>
36                 <listitem>
37                     <para>
38                         a real vector or matrix. If omitted, it is assumed to be the vector
39                         <literal>1:ny</literal> where <literal>ny</literal> is the
40                         number of curve points (see below).
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>y</term>
46                 <listitem>
47                     <para>
48                         a real vector or matrix of length.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>p</term>
54                 <listitem>
55                     <para>
56                         a real scalar in the interval<literal>[0 1[</literal>. Default value is 0.1.
57                     </para>
58                 </listitem>
59             </varlistentry>
60             <varlistentry>
61                 <term>fun</term>
62                 <listitem>
63                     <para>
64                         a scilab function with syntax <literal>y=fun(x)</literal>.  <varname>fun</varname> can also be a polynomial or a rational fraction.
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>c</term>
70                 <listitem>
71                     <para>
72                         a vector of  <literal>ny</literal> color index.
73                     </para>
74                 </listitem>
75             </varlistentry>
76         </variablelist>
77     </refsection>
78     <refsection>
79         <title>Description</title>
80         <para>
81             If <literal>(x,y)</literal> are two vectors with the same number
82             of elements, this function draws a 2D comet animated plot
83             showing the progression of the curve
84             <literal>(x(1:k),y(1:k))</literal> for <literal>k</literal>
85             varying from <literal>1</literal> to
86             <literal>size(x,'*')</literal>.
87         </para>
88         <para>
89             The plot is made of three parts:
90             <variablelist>
91                 <varlistentry>
92                     <term>a head</term>
93                     <listitem>
94                         <para>
95                             mark that shows the current <literal>(x(i),y(i))</literal> position.
96                         </para>
97                     </listitem>
98                 </varlistentry>
99                 <varlistentry>
100                     <term>a body</term>
101                     <listitem>
102                         <para>
103                             that shows the trailing curve that follows the head: the
104                             <literal>(x(i-k:i),y(i-k:i))</literal> part of the curve.
105                         </para>
106                     </listitem>
107                 </varlistentry>
108                 <varlistentry>
109                     <term>a tail</term>
110                     <listitem>
111                         <para>
112                             that shows the  <literal>(x(1:i-k),y(1:i-k))</literal> part of the curve.
113                         </para>
114                     </listitem>
115                 </varlistentry>
116             </variablelist>
117             <para>
118                 <literal>comet(x,fun,...)</literal> is equivalent to <literal>comet(x,feval(x,fun),...)</literal>.
119             </para>
120             <para>
121                 <literal>comet(...,p)</literal> can be used to set the
122                 relative length of the body. <literal>k</literal> is defined
123                 as <code>k = round(p*ny)</code>.
124             </para>
125             <para>
126                 If <varname>y</varname> is a matrix then animated curves
127                 are drawn for each pair <literal>(x,y(:,l))</literal>.
128                 In this case <literal>ny</literal> is the number of rows
129                 of <varname>y</varname>.
130             </para>
131             <para>
132                 If <varname>x</varname> and <varname>y</varname> are
133                 matrices with identical sizes then animated curves are drawn
134                 for each pair <literal>(x(:,l),y(:,l))</literal>.  In this
135                 case <literal>ny</literal> is the number of rows of
136                 <varname>x</varname> and <varname>y</varname>.
137             </para>
138
139             <para>
140                 <literal>comet(...,"colors",c)</literal> can be used to set the colors of each curves.
141             </para>
142
143         </para>
144     </refsection>
145     <refsection>
146         <title>Examples</title>
147         <programlisting role="example"><![CDATA[
148 t = linspace(0,10*%pi,500);
149 clf();
150 isoview; //set isoview axes
151 comet(t.*sin(t), t.*cos(t))
152     ]]></programlisting>
153         <programlisting role="example"><![CDATA[
154 t = linspace(0,10*%pi,500)';
155 clf();
156 comet(t.*sin(t), [t.*sin(2*t) t.*sin(3*t)])
157     ]]></programlisting>
158         <programlisting role="example"><![CDATA[
159 t = linspace(0,10*%pi,500)';
160 clf();comet(t.*sin(t),[t.*sin(2*t) t.*sin(3*t)],"colors",[3 5])
161     ]]></programlisting>
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         <programlisting role="example"><![CDATA[
170 clf();
171 comet(linspace(-2,4,500), (%s-3)/(%s^3+2*%s^2+1))
172     ]]></programlisting>
173     </refsection>
174     <refsection role="see also">
175         <title>See also</title>
176         <simplelist type="inline">
177             <member>
178                 <link linkend="color">color</link>
179             </member>
180             <member>
181                 <link linkend="comet3d">comet3d</link>
182             </member>
183             <member>
184                 <link linkend="paramfplot2d">paramfplot2d</link>
185             </member>
186         </simplelist>
187     </refsection>
188     <refsection>
189         <title>History</title>
190         <revhistory>
191             <revision>
192                 <revnumber>5.3.2</revnumber>
193                 <revremark>
194                     Function <function>comet</function> introduced.
195                 </revremark>
196             </revision>
197         </revhistory>
198     </refsection>
199 </refentry>