<?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="Matplot">
    <refnamediv>
        <refname>Matplot</refname>
        <refpurpose>
            2D plot of a matrix using colors
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            Matplot(a, [strf, rect, nax])
            Matplot(a, &lt;opt_args&gt;)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>a</term>
                <listitem>
                    <para>
                        a real matrix of size (<literal>n1</literal>, <literal>n2</literal>).
                    </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:
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>rect</term>
                            <listitem>
                                <para>
                                    sets the bounds of the plot. If this key is given and
                                    neither <varname>frameflag</varname> nor <varname>strf</varname> is given
                                    then the <varname>y</varname> character of <varname>strf</varname> is
                                    supposed to be <literal>7</literal>. See below for value.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>nax</term>
                            <listitem>
                                <para>
                                    sets the grids definition. If this key is given and
                                    neither <varname>axesflag</varname> nor <varname>strf</varname> is given
                                    then the <varname>z</varname> character of <varname>strf</varname> is
                                    supposed to be <literal>1</literal>. See below for value.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>frameflag</term>
                            <listitem>
                                <para>
                                    specifies how the frame of the plot is computed. The
                                    value is an integer ranging from <literal>0</literal> to
                                    <literal>8</literal>. It corresponds to the <varname>y</varname>
                                    character of <varname>strf</varname>. See below.
                                </para>
                            </listitem>
                        </varlistentry>
                        <varlistentry>
                            <term>axesflag</term>
                            <listitem>
                                <para>
                                    specifies what kind of axes are drawn around the plot.
                                    The value is an integer ranging from <literal>0</literal> to
                                    <literal>5</literal>. It corresponds to the <varname>z</varname>
                                    character of <varname>strf</varname>. See below.
                                </para>
                            </listitem>
                        </varlistentry>
                    </variablelist>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>strf</term>
                <listitem>
                    <para>
                        is a string of length 3 <literal>"xyz"</literal>.
                    </para>
                    <variablelist>
                        <varlistentry>
                            <term>default</term>
                            <listitem>
                                <para>
                                    the default is <literal>"081"</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 caption.</para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>x=1</term>
                                        <listitem>
                                            <para>
                                                captions are displayed. They are given by the
                                                optional argument <varname>leg</varname>.
                                            </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 <varname>rect</varname> argument.
                                            </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
                                                <varname>rect</varname> argument.
                                            </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
                                                <varname>rect</varname> argument.
                                            </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 <literal>y=1</literal> but the previous plots
                                                are redrawn to use the new scale.
                                            </para>
                                        </listitem>
                                    </varlistentry>
                                    <varlistentry>
                                        <term>y=8</term>
                                        <listitem>
                                            <para>
                                                like <literal>y=2</literal> but the previous plots
                                                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 ticks can be
                                    specified by the <varname>nax</varname> 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 ticks.
                                            </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 <literal>y</literal>
                        of argument <varname>strf</varname> is <literal>1</literal>,
                        <literal>3</literal>, <literal>5</literal> or <literal>7</literal>. 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 <literal>z</literal>
                        of argument <varname>strf</varname> is <literal>1</literal>. 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>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            The entries of matrix <code>int(a)</code> are used as colormap entries
            in the current colormap. The color associated to <literal>a(i,j)</literal>
            is used to draw a small square of size 1 with center at location
            <literal>(x=j, y=(n1-i+1))</literal>.
            If a matrix entry is outside the colormap, the corresponding rectangle is not displayed.
        </para>
        <para>
            <warning>
                To update the Matplot data, the <literal>data</literal> field of the corresponding handle must be used.
            </warning>
            <literal>data</literal> can be a matrix (or an hypermatrix) containing RGB, RGBA, ... data (see <link linkend="Matplot_properties">Matplot_properties</link>).
        </para>
        <para>
            Enter the command <code>Matplot()</code> to see a demo.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
Matplot([1 2 3;4 5 6])
 ]]></programlisting>
        <scilab:image>
            Matplot([1 2 3;4 5 6])
        </scilab:image>
        <programlisting role="example"><![CDATA[
clf()
// draw the current colormap
nbcol = size(gcf().color_map, 1);
Matplot(1:nbcol)
 ]]></programlisting>
        <scilab:image>
            nbcol = size(gcf().color_map, 1);
            Matplot(1:nbcol)
        </scilab:image>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="colormap">colormap</link>
            </member>
            <member>
                <link linkend="plot2d">plot2d</link>
            </member>
            <member>
                <link linkend="Matplot1">Matplot1</link>
            </member>
            <member>
                <link linkend="Matplot_properties">Matplot_properties</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    <literal>data</literal> can now be a matrix (or an hypermatrix) containing RGB, RGBA, ... data (see <link linkend="Matplot_properties">Matplot_properties</link>).
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
