<?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="graypolarplot">
    <refnamediv>
        <refname>graypolarplot</refname>
        <refpurpose>Polar 2D plot of a surface using
            colors
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>graypolarplot(theta,rho,z,[strf,rect])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>theta</term>
                <listitem>
                    <para>a vector with size n1, the discretization of the the
                        angle in radian.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rho</term>
                <listitem>
                    <para>a vector with size n2, the discretization of the radius</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>z</term>
                <listitem>
                    <para>
                        real matrix of size (n1,n2). <literal>z(i,j)</literal> is the value
                        of the surface at the point (theta(i),rho(j)).
                    </para>
                </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.</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>
            Takes a 2D plot of the surface given by <literal>z</literal> on a polar
            coordinate grid defined by <literal>rho</literal> and <literal>theta</literal>. Each
            grid region if filled with a gray or color level depending on the average
            value of <literal>z</literal> on the corners of the grid.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
rho=1:0.1:4;theta=(0:0.02:1)*2*%pi;
z=30+round(theta'*(1+rho.^2));
f=gcf();
f.color_map= hot(128);
clf();graypolarplot(theta,rho,z)
 ]]></programlisting>
        <scilab:image>rho=1:0.1:4;theta=(0:0.02:1)*2*%pi;
            z=30+round(theta'*(1+rho.^2));
            f=gcf();
            f.color_map= hot(128);
            graypolarplot(theta,rho,z)
        </scilab:image>
    </refsection>
</refentry>
