<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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" xml:id="polarplot">
    <refnamediv>
        <refname>polarplot</refname>
        <refpurpose>Plot polar
            coordinates
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>polarplot(theta,rho,[style,strf,leg,rect])
            polarplot(theta,rho,&lt;opt_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>rho</term>
                <listitem>
                    <para>a vector, the radius values</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>theta</term>
                <listitem>
                    <para>a vector with same size than rho, the angle values.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        a sequence of statements <literal>key1=value1, key2=value2</literal>, ... where keys may be
                        <literal>style</literal>,<literal>leg</literal>,<literal>rect</literal>,<literal>strf</literal>
                        or <literal>frameflag</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>style</term>
                <listitem>
                    <para>is a real row vector of size nc. The style to use for curve
                        <literal>i</literal> is defined by <literal>style(i)</literal>. The default
                        style is <literal>1:nc</literal> (1 for the first curve, 2 for the second,
                        etc.).
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>-</term>
                            <listitem>
                                <para>
                                    if <literal>style(i)</literal> is negative, the curve is plotted
                                    using the mark with id <literal>abs(style(i))+1</literal>.
                                    See <link linkend="polyline_properties">polyline properties</link>
                                    to see the mark ids.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>-</term>
                            <listitem>
                                <para>
                                    if <literal>style(i)</literal> is strictly positive, a plain
                                    line with color id <literal>style(i)</literal> or a dashed line with
                                    dash id <literal>style(i)</literal> is used.
                                    See <link linkend="polyline_properties">polyline properties</link>
                                    to see the line style ids.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>-</term>
                            <listitem>
                                <para>
                                    When only one curve is drawn, <literal>style</literal> can be
                                    the row vector of size 2 <literal>[sty,pos]</literal> where
                                    <literal>sty</literal> is used to specify the style and
                                    <literal>pos</literal> is an integer ranging from 1 to 6 which
                                    specifies a position to use for the caption. This can be
                                    useful when a user wants to draw multiple curves on a plot by
                                    calling the function <literal>plot2d</literal> several times and
                                    wants to give a caption for each curve.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>strf</term>
                <listitem>
                    <para>
                        is a string of length 3 <literal>"xy0"</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>default</term>
                            <listitem>
                                <para>
                                    The default is <literal>"030"</literal>.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>x</term>
                            <listitem>
                                <para>controls the display of captions,</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>x=0</term>
                                        <listitem>
                                            <para>no captions.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>x=1</term>
                                        <listitem>
                                            <para>captions are displayed. They are given by the
                                                optional argument <literal>leg</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>y</term>
                            <listitem>
                                <para>controls the computation of the frame. same as
                                    frameflag
                                </para>
                                <variablelist>
                                    <varlistentry>
                                        <term>y=0</term>
                                        <listitem>
                                            <para>the current boundaries (set by a previous call to
                                                another high level plotting function) are used. Useful
                                                when superposing multiple plots.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=1</term>
                                        <listitem>
                                            <para>
                                                the optional argument <literal>rect</literal> is used to
                                                specify the boundaries of the plot.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=2</term>
                                        <listitem>
                                            <para>the boundaries of the plot are computed using min
                                                and max values of <literal>x</literal> and
                                                <literal>y</literal>.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=3</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=1</literal> but produces isoview
                                                scaling.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=4</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=2</literal> but produces isoview
                                                scaling.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=5</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=1</literal> but <literal>plot2d</literal> can
                                                change the boundaries of the plot and the ticks of the
                                                axes to produce pretty graduations. When the zoom button
                                                is activated, this mode is used.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=6</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=2</literal> but <literal>plot2d</literal> can
                                                change the boundaries of the plot and the ticks of the
                                                axes to produce pretty graduations. When the zoom button
                                                is activated, this mode is used.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=7</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=5</literal> but the scale of the new
                                                plot is merged with the current scale.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=8</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=6</literal> but the scale of the new
                                                plot is merged with the current scale.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>leg</term>
                <listitem>
                    <para>a string. It is used when the first character x of argument
                        <literal>strf</literal> is 1. <literal>leg</literal> has the form
                        <literal>"leg1@leg2@...."</literal> where <literal>leg1</literal>,
                        <literal>leg2</literal>, etc. are respectively the captions of the first
                        curve, of the second curve, etc. The default is <literal>""</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rect</term>
                <listitem>
                    <para>This argument is used when the second character y of argument
                        <literal>strf</literal> is 1, 3 or 5. It is a row vector of size 4 and
                        gives the dimension of the frame:
                        <literal>rect=[xmin,ymin,xmax,ymax]</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>polarplot creates a polar coordinate plot of the angle theta versus the
            radius rho. theta is the angle from the x-axis to the radius vector
            specified in radians; rho is the length of the radius vector specified in
            dataspace units. Note that negative rho values cause the corresponding curve points
            to be reflected across the origin.
        </para>
    </refsection>
    <refsection>
        <title>Example 1</title>
        <programlisting role="example"><![CDATA[
clf
t = 0:.01:2*%pi;
polarplot(sin(7*t),cos(8*t))
 ]]></programlisting>
        <scilab:image>
            t= 0:.01:2*%pi;
            polarplot(sin(7*t),cos(8*t))
        </scilab:image>

    </refsection>
    <refsection>
        <title>Example 2</title>
        <programlisting role="example"><![CDATA[
t = 0:.01:2*%pi;
clf
polarplot([sin(7*t') sin(6*t')],[cos(8*t') cos(8*t')],[1,2])
 ]]></programlisting>
        <scilab:image>
            t= 0:.01:2*%pi;
            clf();polarplot([sin(7*t') sin(6*t')],[cos(8*t') cos(8*t')],[1,2])
        </scilab:image>
    </refsection>
    <refsection>
        <title>Example 3</title>
        <programlisting role="example"><![CDATA[
t = 0:0.01:2*%pi;
polarplot(t, -1 + sin(t));

 ]]></programlisting>
        <scilab:image>
            t = 0:0.01:2*%pi;
            polarplot(t, -1 + sin(t));
        </scilab:image>
    </refsection>
    <refsection>
        <title>Example 4</title>
        <programlisting role="example"><![CDATA[
clf
theta = [0:0.02:2*%pi]';
rho = 1+0.2*cos(theta.^2);
polarplot(theta,rho,style=5)
gca().data_bounds = [-1.2,-1.2;1.2,01.2];
 ]]></programlisting>
        <scilab:image>
            theta=[0:0.02:2*%pi]';
            rho=1+0.2*cos(theta.^2)
            polarplot(theta,rho,style=5)
            isoview()
            gca().data_bounds=[-1.2,-1.2;1.2,01.2]
        </scilab:image>
    </refsection>
</refentry>
