0ddfc517f7c22d66c2b393f3ce095f7ede36a51f
[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>Calling Sequence</title>
12         <synopsis>comet3d(z)</synopsis>
13         <synopsis>comet3d(x,y,z)</synopsis>
14         <synopsis>comet3d(x,y,fun)</synopsis>
15         <synopsis>comet3d(x,y,z,p)</synopsis>
16         <synopsis>comet3d(x,y,fun,p)</synopsis>
17         <synopsis>comet3d(...,"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:nz</literal> where <literal>nz</literal> is the
28                         number of curve points given by the <literal>z</literal>
29                         parameter.
30                     </para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>y</term>
35                 <listitem>
36                     <para>
37                         a real vector or matrix. If omitted, it is assumed to be the vector
38                         <literal>1:nz</literal> where <literal>nz</literal> is the
39                         number of curve points given by the <literal>z</literal>
40                         parameter.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>z</term>
46                 <listitem>
47                     <para>
48                         a real vector of length <literal>nz</literal> or a matrix with  <literal>nz</literal> rows.
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 calling sequence <literal>z=fun(x,y)</literal>.
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,z)</literal> are three vectors with the same number of elements, this function draws a 3D comet
82             animated plot. The plot is made of three parts:
83             <variablelist>
84                 <varlistentry>
85                     <term>ahead</term> 
86                     mark that shows the current <literal>(x(i),y(i),z(i))</literal> position.
87                     <listitem><para>
88                         </para>
89                     </listitem>
90                 </varlistentry>
91                 <varlistentry>
92                     <term>abody</term> that shows the trailing curve that
93                     follows the head: the
94                     <literal>(x(i-k:i),y(i-k:i),z(i-k:i))</literal>) part of the curve.
95                     <listitem><para>
96                         </para>
97                     </listitem>
98                 </varlistentry>
99                 <varlistentry>
100                     <term>atail</term> 
101                     that shows the  <literal>(x(1:i-k),y(1:i-k),z(1:i-k))</literal>  part of the curve.
102                     <listitem><para>
103                         </para>
104                     </listitem>
105                 </varlistentry>
106             </variablelist>
107             <para>
108                 if <literal>z</literal> is a matrix and
109                 <literal>(x,y)</literal> are vectors then animated curves
110                 are drawn for each triple <literal>(x,y,z(:,l))</literal>.
111                 in this case <literal>nz</literal> is the number of rows of
112                 <literal>z</literal>.
113             </para>
114             <para>
115                 if <literal>x,y,z</literal> are matrices with the same dimensions then animated curves
116                 are drawn for each triple <literal>(x(:,l),y(:,l),z(:,l))</literal>.
117             </para>
118             
119             <para>
120                 <literal>comet3d(x,y,fun,...)</literal> computes the
121                 <literal>z</literal> vector as
122                 <literal>z(i)=fun(x(i),y(i))</literal>
123             </para>
124             <para>
125                 <literal>comet3d(...,p)</literal> can be used to set the
126                 relative length of the body. <literal>k</literal> is defined
127                 as <literal>k = round(p*nz)</literal>.
128             </para>
129             
130         </para>
131     </refsection>
132     <refsection>
133         <title>Examples</title>
134         <programlisting role="example"><![CDATA[
135 t = linspace(-%pi,%pi,500);
136 clf();comet3d(sin(5*t),sin(t),t^2)
137     ]]></programlisting>
138         <programlisting role="example"><![CDATA[
139 t = linspace(-%pi,%pi,500)';
140 clf();comet3d(sin(5*t),sin(t),[t^2,ones(t)])
141     ]]></programlisting>
142         <programlisting role="example"><![CDATA[
143 t = linspace(-%pi,%pi,500)';
144 function z=traj(x,y),z=1.5*sin(x^2)*cos(y),endfunction
145 clf();comet3d(cos(t),sin(t),traj)
146     ]]></programlisting>
147     </refsection>
148     <refsection>
149         <title>See Also</title>
150         <simplelist type="inline">
151             <member>
152                 <link linkend="comet">comet</link>
153             </member>
154         </simplelist>
155     </refsection>
156     <refsection>
157         <title>History</title>
158         <revhistory>
159             <revision>
160                 <revnumber>5.3.2</revnumber>
161                 <revremark>Function comet3d introduced.</revremark>
162             </revision>
163         </revhistory>
164     </refsection>
165 </refentry>