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>