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>