0ee350acc0cfc4377d656bf58a8a0fbd492f9fae
[scilab.git] / 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>