802eb113f5249e75b9d605dc64482a4dd454a47e
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / polarplot.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) INRIA
5  * 
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at    
10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
11  *
12  -->
13 <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" version="5.0-subset Scilab" xml:lang="en" xml:id="polarplot">
14     <refnamediv>
15         <refname>polarplot</refname>
16         <refpurpose>Plot polar
17             coordinates
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>polarplot(theta,rho,[style,strf,leg,rect])
23             polarplot(theta,rho,&lt;opt_args&gt;)
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>rho</term>
31                 <listitem>
32                     <para>a vector, the radius values</para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>theta</term>
37                 <listitem>
38                     <para>a vector with same size than rho, the angle values.</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>&lt;opt_args&gt;</term>
43                 <listitem>
44                     <para>
45                         a sequence of statements <literal>key1=value1, key2=value2</literal>, ... where keys may be
46                         <literal>style</literal>,<literal>leg</literal>,<literal>rect</literal>,<literal>strf</literal>
47                         or <literal>frameflag</literal>
48                     </para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>style</term>
53                 <listitem>
54                     <para>is a real row vector of size nc. The style to use for curve
55                         <literal>i</literal> is defined by <literal>style(i)</literal>. The default
56                         style is <literal>1:nc</literal> (1 for the first curve, 2 for the second,
57                         etc.).
58                     </para>
59                     <variablelist>
60                         <varlistentry>
61                             <term>-</term>
62                             <listitem>
63                                 <para>
64                                     if <literal>style(i)</literal> is negative, the curve is plotted
65                                     using the mark with id <literal>abs(style(i))+1</literal>; use
66                                     <literal>xset()</literal> to see the mark ids.
67                                 </para>
68                             </listitem>
69                         </varlistentry>
70                         <varlistentry>
71                             <term>-</term>
72                             <listitem>
73                                 <para>
74                                     if <literal>style(i)</literal> is strictly positive, a plain
75                                     line with color id <literal>style(i)</literal> or a dashed line with
76                                     dash id <literal>style(i)</literal> is used; use <literal>xset()</literal>
77                                     to see the color ids.
78                                 </para>
79                             </listitem>
80                         </varlistentry>
81                         <varlistentry>
82                             <term>-</term>
83                             <listitem>
84                                 <para>
85                                     When only one curve is drawn, <literal>style</literal> can be
86                                     the row vector of size 2 <literal>[sty,pos]</literal> where
87                                     <literal>sty</literal> is used to specify the style and
88                                     <literal>pos</literal> is an integer ranging from 1 to 6 which
89                                     specifies a position to use for the caption. This can be
90                                     useful when a user wants to draw multiple curves on a plot by
91                                     calling the function <literal>plot2d</literal> several times and
92                                     wants to give a caption for each curve.
93                                 </para>
94                             </listitem>
95                         </varlistentry>
96                     </variablelist>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>strf</term>
101                 <listitem>
102                     <para>
103                         is a string of length 3 <literal>"xy0"</literal>.
104                     </para>
105                     <variablelist>
106                         <varlistentry>
107                             <term>default</term>
108                             <listitem>
109                                 <para>
110                                     The default is <literal>"030"</literal>.
111                                 </para>
112                             </listitem>
113                         </varlistentry>
114                         <varlistentry>
115                             <term>x</term>
116                             <listitem>
117                                 <para>controls the display of captions,</para>
118                                 <variablelist>
119                                     <varlistentry>
120                                         <term>x=0</term>
121                                         <listitem>
122                                             <para>no captions.</para>
123                                         </listitem>
124                                     </varlistentry>
125                                     <varlistentry>
126                                         <term>x=1</term>
127                                         <listitem>
128                                             <para>captions are displayed. They are given by the
129                                                 optional argument <literal>leg</literal>.
130                                             </para>
131                                         </listitem>
132                                     </varlistentry>
133                                 </variablelist>
134                             </listitem>
135                         </varlistentry>
136                         <varlistentry>
137                             <term>y</term>
138                             <listitem>
139                                 <para>controls the computation of the frame. same as
140                                     frameflag
141                                 </para>
142                                 <variablelist>
143                                     <varlistentry>
144                                         <term>y=0</term>
145                                         <listitem>
146                                             <para>the current boundaries (set by a previous call to
147                                                 another high level plotting function) are used. Useful
148                                                 when superposing multiple plots.
149                                             </para>
150                                         </listitem>
151                                     </varlistentry>
152                                     <varlistentry>
153                                         <term>y=1</term>
154                                         <listitem>
155                                             <para>
156                                                 the optional argument <literal>rect</literal> is used to
157                                                 specify the boundaries of the plot.
158                                             </para>
159                                         </listitem>
160                                     </varlistentry>
161                                     <varlistentry>
162                                         <term>y=2</term>
163                                         <listitem>
164                                             <para>the boundaries of the plot are computed using min
165                                                 and max values of <literal>x</literal> and
166                                                 <literal>y</literal>.
167                                             </para>
168                                         </listitem>
169                                     </varlistentry>
170                                     <varlistentry>
171                                         <term>y=3</term>
172                                         <listitem>
173                                             <para>
174                                                 like <literal>y=1</literal> but produces isoview
175                                                 scaling.
176                                             </para>
177                                         </listitem>
178                                     </varlistentry>
179                                     <varlistentry>
180                                         <term>y=4</term>
181                                         <listitem>
182                                             <para>
183                                                 like <literal>y=2</literal> but produces isoview
184                                                 scaling.
185                                             </para>
186                                         </listitem>
187                                     </varlistentry>
188                                     <varlistentry>
189                                         <term>y=5</term>
190                                         <listitem>
191                                             <para>
192                                                 like <literal>y=1</literal> but <literal>plot2d</literal> can
193                                                 change the boundaries of the plot and the ticks of the
194                                                 axes to produce pretty graduations. When the zoom button
195                                                 is activated, this mode is used.
196                                             </para>
197                                         </listitem>
198                                     </varlistentry>
199                                     <varlistentry>
200                                         <term>y=6</term>
201                                         <listitem>
202                                             <para>
203                                                 like <literal>y=2</literal> but <literal>plot2d</literal> can
204                                                 change the boundaries of the plot and the ticks of the
205                                                 axes to produce pretty graduations. When the zoom button
206                                                 is activated, this mode is used.
207                                             </para>
208                                         </listitem>
209                                     </varlistentry>
210                                     <varlistentry>
211                                         <term>y=7</term>
212                                         <listitem>
213                                             <para>
214                                                 like <literal>y=5</literal> but the scale of the new
215                                                 plot is merged with the current scale.
216                                             </para>
217                                         </listitem>
218                                     </varlistentry>
219                                     <varlistentry>
220                                         <term>y=8</term>
221                                         <listitem>
222                                             <para>
223                                                 like <literal>y=6</literal> but the scale of the new
224                                                 plot is merged with the current scale.
225                                             </para>
226                                         </listitem>
227                                     </varlistentry>
228                                 </variablelist>
229                             </listitem>
230                         </varlistentry>
231                     </variablelist>
232                 </listitem>
233             </varlistentry>
234             <varlistentry>
235                 <term>leg</term>
236                 <listitem>
237                     <para>a string. It is used when the first character x of argument
238                         <literal>strf</literal> is 1. <literal>leg</literal> has the form
239                         <literal>"leg1@leg2@...."</literal> where <literal>leg1</literal>,
240                         <literal>leg2</literal>, etc. are respectively the captions of the first
241                         curve, of the second curve, etc. The default is <literal>""</literal>.
242                     </para>
243                 </listitem>
244             </varlistentry>
245             <varlistentry>
246                 <term>rect</term>
247                 <listitem>
248                     <para>This argument is used when the second character y of argument
249                         <literal>strf</literal> is 1, 3 or 5. It is a row vector of size 4 and
250                         gives the dimension of the frame:
251                         <literal>rect=[xmin,ymin,xmax,ymax]</literal>.
252                     </para>
253                 </listitem>
254             </varlistentry>
255         </variablelist>
256     </refsection>
257     <refsection>
258         <title>Description</title>
259         <para>polarplot creates a polar coordinate plot of the angle theta versus the
260             radius rho. theta is the angle from the x-axis to the radius vector
261             specified in radians; rho is the length of the radius vector specified in
262             dataspace units. Note that negative rho values cause the corresponding curve points
263             to be reflected across the origin.
264         </para>
265     </refsection>
266     <refsection>
267         <title>Sample</title>
268         <scilab:image>polarplot();</scilab:image>
269     </refsection>
270     <refsection>
271         <title>Example 1</title>
272         <programlisting role="example1"><![CDATA[ 
273 t= 0:.01:2*%pi;
274 clf();polarplot(sin(7*t),cos(8*t))
275
276 clf();polarplot([sin(7*t') sin(6*t')],[cos(8*t') cos(8*t')],[1,2])
277  ]]></programlisting>
278     </refsection>
279     <refsection>
280         <title>Example 2</title>
281         <programlisting role="example2"><![CDATA[ 
282 t= 0:.01:2*%pi;
283
284 clf();polarplot([sin(7*t') sin(6*t')],[cos(8*t') cos(8*t')],[1,2])
285  ]]></programlisting>
286     </refsection>
287     <refsection>
288         <title>Example 3</title>
289         <programlisting role="example3"><![CDATA[ 
290 t = 0:0.01:2*%pi;
291
292 polarplot(t, -1 + sin(t));
293
294  ]]></programlisting>
295     </refsection>
296 </refentry>