<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ENPC - Jean-Philippe Chancelier
 *
 * 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="Sgrayplot">
    <refnamediv>
        <refname>Sgrayplot</refname>
        <refpurpose>smooth 2D plot of a surface using
            colors
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>Sgrayplot(x,y,z,&lt;opt_args&gt;)
            Sgrayplot(x,y,z [,strf, rect, nax, zminmax, colminmax, mesh, colout])
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>x,y</term>
                <listitem>
                    <para>real row vectors of size n1 and n2.</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 (x(i),y(j)).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>This represents a sequence of statements
                        <literal>key1=value1,key2=value2</literal>,... where <literal>key1</literal>,
                        <literal>key2,...</literal> can be one of the following: strf, rect, nax, zminmax, colminmax, mesh, colout.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>strf</term>
                <listitem>
                    <para>
                        is a string of length 3 <literal>"xyz"</literal> (by default
                        <literal>strf= "081"</literal>)
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>x</term>
                            <listitem>
                                <para>controls the display of captions.</para>
                                <variablelist>
                                    <varlistentry>
                                        <term>x=0</term>
                                        <listitem>
                                            <para>no caption.</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 actual coordinate ranges
                                    from the minimal requested values. Actual ranges can be larger
                                    than minimal requirements.
                                </para>
                                <variablelist>
                                    <varlistentry>
                                        <term>y=0</term>
                                        <listitem>
                                            <para>no computation, the plot use the previous (or
                                                default) scale
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=1</term>
                                        <listitem>
                                            <para>from the rect arg</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=2</term>
                                        <listitem>
                                            <para>from the min/max of the x, y data</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=3</term>
                                        <listitem>
                                            <para>built for an isometric scale from the rect
                                                arg
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=4</term>
                                        <listitem>
                                            <para>built for an isometric plot from the min/max of
                                                the x, y data
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=5</term>
                                        <listitem>
                                            <para>enlarged for pretty axes from the rect arg</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=6</term>
                                        <listitem>
                                            <para>enlarged for pretty axes from the min/max of the
                                                x, y data
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=7</term>
                                        <listitem>
                                            <para>like y=1 but the previous plot(s) are redrawn to
                                                use the new scale
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=8</term>
                                        <listitem>
                                            <para>like y=2 but the previous plot(s) are redrawn to
                                                use the new scale
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>z</term>
                            <listitem>
                                <para>controls the display of information on the frame around
                                    the plot. If axes are requested, the number of tics can be
                                    specified by the <literal>nax</literal> optional argument.
                                </para>
                                <variablelist>
                                    <varlistentry>
                                        <term>z=0</term>
                                        <listitem>
                                            <para>nothing is drawn around the plot.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>z=1</term>
                                        <listitem>
                                            <para>axes are drawn, the y=axis is displayed on the
                                                left.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>z=2</term>
                                        <listitem>
                                            <para>the plot is surrounded by a box without tics.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>z=3</term>
                                        <listitem>
                                            <para>axes are drawn, the y=axis is displayed on the
                                                right.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>z=4</term>
                                        <listitem>
                                            <para>axes are drawn centred in the middle of the frame
                                                box, with the box disabled.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>z=5</term>
                                        <listitem>
                                            <para>axes are drawn centred in the middle of the frame
                                                box, with the box enabled.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                </variablelist>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </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>
            <varlistentry>
                <term>nax</term>
                <listitem>
                    <para>This argument is used when the third character z of argument
                        <literal>strf</literal> is 1. It is a row vector with four entries
                        <literal>[nx,Nx,ny,Ny]</literal> where <literal>nx</literal> (<literal>ny</literal>)
                        is the number of subgraduations on the x (y) axis and
                        <literal>Nx</literal> (<literal>Ny</literal>) is the number of graduations on
                        the x (y) axis.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>zminmax, colminmax, mesh, colout</term>
                <listitem>
                    <para>
                        See <link linkend="fec">fec</link>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>Sgrayplot</literal> is the same as <literal>grayplot</literal> but the
            plot is smoothed. The function <literal>fec</literal> is used for smoothing. The
            surface is plotted assuming that it is linear on a set of triangles built
            from the grid (here with n1=5, n2=3):
        </para>
        <programlisting role=""><![CDATA[
_____________
| /| /| /| /|
|/_|/_|/_|/_|
| /| /| /| /|
|/_|/_|/_|/_|
 ]]></programlisting>
        <para>
            The function <link linkend="colorbar">colorbar</link> may be used to see the color scale.
        </para>
        <para>
            The parameter <literal>zminmax</literal> is useful for animation purpose (see an
            example after) and the parameter <literal>colminmax</literal> lets the user choose a part
            of the current colormap (see the <link linkend="fec">fec</link> help page).
        </para>
        <para>
            Enter the command <literal>Sgrayplot()</literal> to see a demo.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// example #1
x=-10:10; y=-10:10;m =rand(21,21);
clf()
gcf().color_map = hot(64);
Sgrayplot(x,y,m, strf="011", rect=[-20,-20,20,20])
 ]]></programlisting>
        <scilab:image>
            x=-10:10; y=-10:10;m =rand(21,21);
            clf()
            gcf().color_map = hot(64);
            Sgrayplot(x,y,m, strf="011", rect=[-20,-20,20,20])
        </scilab:image>
        <programlisting role="example"><![CDATA[
// example #2
t=-%pi:0.1:%pi; m=sin(t)'*cos(t);
clf()
gcf().color_map = jet(64);
colorbar(-1,1)
Sgrayplot(t,t,m, strf="041")
]]></programlisting>
        <scilab:image>
            t=-%pi:0.1:%pi; m=sin(t)'*cos(t);
            clf()
            gcf().color_map = jet(64);
            colorbar(-1,1)
            Sgrayplot(t,t,m, strf="041")
        </scilab:image>
        <programlisting role="example"><![CDATA[
// example #3: an animation display cos(t)*sin(x)sin(y).
n = 30;
nt = 100;
x = linspace(0,2*%pi,n);
y = linspace(0,%pi,n/2);
z = sin(x')*sin(y);
t = linspace(0,4*%pi,nt);
show_window(); clf()
f=gcf();
f.color_map=jet(64);
colorbar(-1,1)
Sgrayplot(x,y,cos(t(1))*z, strf="042", zminmax=[-1,1])
c=gce(),e=c.children
xtitle("Kaa''s eyes")
for i = 1:nt
  e.data(:,3)=matrix(cos(t(i))*z,-1,1);
end
 ]]></programlisting>
        <scilab:image>
            n = 30;
            nt = 100;
            x = linspace(0,2*%pi,n);
            y = linspace(0,%pi,n/2);
            z = sin(x')*sin(y);
            t = linspace(0,4*%pi,nt);
            show_window(); clf()
            f=gcf();
            f.color_map=jet(64);
            colorbar(-1,1)
            Sgrayplot(x,y,cos(t(1))*z, strf="042", zminmax=[-1,1])
            c=gce(),e=c.children
            xtitle("Kaa''s eyes")
            for i = 1:nt
            e.data(:,3)=matrix(cos(t(i))*z,-1,1);
            end
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="fec">fec</link>
            </member>
            <member>
                <link linkend="fgrayplot">fgrayplot</link>
            </member>
            <member>
                <link linkend="grayplot">grayplot</link>
            </member>
            <member>
                <link linkend="Sfgrayplot">Sfgrayplot</link>
            </member>
            <member>
                <link linkend="colorbar">colorbar</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
