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