2a8d826c2b5361c0d488738094738d47db0bc11e
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / comet.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Add some comments about XML file
4 -->
5 <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">
6     <refnamediv>
7         <refname>comet</refname>
8         <refpurpose>2D comet animated plot. </refpurpose>
9     </refnamediv>
10     <refsynopsisdiv>
11         <title>Calling Sequence</title>
12         <synopsis>comet(y)</synopsis>
13         <synopsis>comet(x,y)</synopsis>
14         <synopsis>comet(x,fun)</synopsis>
15         <synopsis>comet(x,y,p)</synopsis>
16         <synopsis>comet(x,fun,p)</synopsis>
17         <synopsis>comet(...,"colors",c)</synopsis>
18     </refsynopsisdiv>
19     <refsection>
20         <title>Parameters</title>
21         <variablelist>
22             <varlistentry>
23                 <term>x</term>
24                 <listitem>
25                     <para>
26                         a real vector or matrix. If omitted, it is assumed to be the vector
27                         <literal>1:ny</literal> where <literal>ny</literal> is the
28                         number of curve points (see below).
29                     </para>
30                 </listitem>
31             </varlistentry>
32             <varlistentry>
33                 <term>y</term>
34                 <listitem>
35                     <para>
36                         a real vector or matrix of length.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>p</term>
42                 <listitem>
43                     <para>
44                         a real scalar in the interval<literal>[0 1[</literal>. Default value is 0.1.
45                     </para>
46                 </listitem>
47             </varlistentry>
48             <varlistentry>
49                 <term>fun</term>
50                 <listitem>
51                     <para>
52                         a scilab function with calling sequence <literal>y=fun(x)</literal>.  <literal>fun</literal> can also be a polynomial or a rational fraction.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>c</term>
58                 <listitem>
59                     <para>
60                         a vector of  <literal>ny</literal> color index.
61                     </para>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65     </refsection>
66     <refsection>
67         <title>Description</title>
68         <para>
69             If <literal>(x,y)</literal> are two vectors with the same number
70             of elements, this function draws a 2D comet animated plot
71             showing the progession of the curve
72             <literal>(x(1:k),y(1:k))</literal> for <literal>k</literal>
73             varying from <literal>1</literal> to
74             <literal>size(x,'*')</literal>.  
75         </para>
76         <para>
77             The plot is made of three parts:
78             <variablelist>
79                 <varlistentry>
80                     <term>ahead</term> 
81                     mark that shows the current <literal>(x(i),y(i))</literal> position.
82                     <listitem><para>
83                         </para>
84                     </listitem>
85                 </varlistentry>
86                 <varlistentry>
87                     <term>abody</term> that shows the trailing curve that
88                     follows the head: the
89                     <literal>(x(i-k:i),y(i-k:i)</literal>) part of the curve.
90                     <listitem><para>
91                         </para>
92                     </listitem>
93                 </varlistentry>
94                 <varlistentry>
95                     <term>atail</term> 
96                     that shows the  <literal>(x(1:i-k),y(1:i-k))</literal>  part of the curve.
97                     <listitem><para>
98                         </para>
99                     </listitem>
100                 </varlistentry>
101             </variablelist>
102             <para>
103                 <literal>comet(x,fun,...)</literal>  is equivalent to <literal>comet(x,feval(x,fun),...)</literal> 
104             </para>
105             <para>
106                 <literal>comet(...,p)</literal> can be used to set the
107                 relative length of the body. <literal>k</literal> is defined
108                 as <literal>k = round(p*ny)</literal>.
109             </para>
110             <para>
111                 if <literal>y</literal> is a matrix then animated curves are drawn for each pair  <literal>(x,y(:,l))</literal>.
112                 in this case <literal>ny</literal> is the number of rows of <literal>y</literal>.
113             </para>
114             <para>
115                 if <literal>x</literal> and <literal>y</literal> are
116                 matrices with identical sizes then animated curves are drawn
117                 for each pair <literal>(x(:,l),y(:,l))</literal>.  in this
118                 case <literal>ny</literal> is the number of rows of
119                 <literal>x</literal>and  <literal>y</literal>.
120             </para>
121             
122             <para>
123                 <literal>comet(...,"colors",c)</literal> can be used to set the colors of each curves.
124             </para>
125             
126         </para>
127     </refsection>
128     <refsection>
129         <title>Examples</title>
130         <programlisting role="example"><![CDATA[
131 t = linspace(0,10*%pi,500);
132 clf();set(gca(),"isoview","on"); //set isoview axes
133 comet(t.*sin(t),t.*cos(t))
134     ]]></programlisting>
135         <programlisting role="example"><![CDATA[
136 t = linspace(0,10*%pi,500)';
137 clf();comet(t.*sin(t),[t.*sin(2*t) t.*sin(3*t)])
138     ]]></programlisting>
139         <programlisting role="example"><![CDATA[
140 function y=traj(x),y=1.5*sin(x^2),endfunction
141 clf();comet(linspace(0,5,500),traj)
142     ]]></programlisting>
143         <programlisting role="example"><![CDATA[
144 clf();comet(linspace(-2,4,500),(%s-3)/(%s^3+2*%s^2+1))
145     ]]></programlisting>
146     </refsection>
147     <refsection>
148         <title>See Also</title>
149         <simplelist type="inline">
150             <member>
151                 <link linkend="comet3d">comet3d</link>
152             </member>
153             <member>
154                 <link linkend="paramfplot2d">paramfplot2d</link>
155             </member>
156         </simplelist>
157     </refsection>
158     <refsection>
159         <title>History</title>
160         <revhistory>
161             <revision>
162                 <revnumber>5.3.2</revnumber>
163                 <revremark>Function comet introduced.</revremark>
164             </revision>
165         </revhistory>
166     </refsection>
167 </refentry>