scilab/modules/graphics/help/en_US/2d_plot/Matplot.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) ENPC - Jean-Philippe Chancelier
   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.1-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"  xml:lang="en" xml:id="Matplot">
  14     <refnamediv>
  15         <refname>Matplot</refname>
  16         <refpurpose>
  17             2D plot of a matrix using colors
  18         </refpurpose>
  19     </refnamediv>
  20     <refsynopsisdiv>
  21         <title>Calling Sequence</title>
  22         <synopsis>
  23             Matplot(a, [strf, rect, nax])
  24             Matplot(a, &lt;opt_args&gt;)
  25         </synopsis>
  26     </refsynopsisdiv>
  27     <refsection>
  28         <title>Arguments</title>
  29         <variablelist>
  30             <varlistentry>
  31                 <term>a</term>
  32                 <listitem>
  33                     <para>
  34                         a real matrix of size (<literal>n1</literal>, <literal>n2</literal>).
  35                     </para>
  36                 </listitem>
  37             </varlistentry>
  38             <varlistentry>
  39                 <term>&lt;opt_args&gt;</term>
  40                 <listitem>
  41                     <para>
  42                         this represents a sequence of statements
  43                         <literal>key1=value1, key2=value2, ...</literal>
  44                         where <literal>key1</literal>,
  45                         <literal>key2</literal>, ... can be one of the following:
  46                     </para>
  47                     <variablelist>
  48                         <varlistentry>
  49                             <term>rect</term>
  50                             <listitem>
  51                                 <para>
  52                                     sets the bounds of the plot. If this key is given and
  53                                     neither <varname>frameflag</varname> nor <varname>strf</varname> is given
  54                                     then the <varname>y</varname> character of <varname>strf</varname> is
  55                                     supposed to be <literal>7</literal>. See below for value.
  56                                 </para>
  57                             </listitem>
  58                         </varlistentry>
  59                         <varlistentry>
  60                             <term>nax</term>
  61                             <listitem>
  62                                 <para>
  63                                     sets the grids definition. If this key is given and
  64                                     neither <varname>axesflag</varname> nor <varname>strf</varname> is given
  65                                     then the <varname>z</varname> character of <varname>strf</varname> is
  66                                     supposed to be <literal>1</literal>. See below for value.
  67                                 </para>
  68                             </listitem>
  69                         </varlistentry>
  70                         <varlistentry>
  71                             <term>frameflag</term>
  72                             <listitem>
  73                                 <para>
  74                                     specifies how the frame of the plot is computed. The
  75                                     value is an integer ranging from <literal>0</literal> to
  76                                     <literal>8</literal>. It corresponds to the <varname>y</varname>
  77                                     character of <varname>strf</varname>. See below.
  78                                 </para>
  79                             </listitem>
  80                         </varlistentry>
  81                         <varlistentry>
  82                             <term>axesflag</term>
  83                             <listitem>
  84                                 <para>
  85                                     specifies what kind of axes are drawn around the plot.
  86                                     The value is an integer ranging from <literal>0</literal> to
  87                                     <literal>5</literal>. It corresponds to the <varname>z</varname>
  88                                     character of <varname>strf</varname>. See below.
  89                                 </para>
  90                             </listitem>
  91                         </varlistentry>
  92                     </variablelist>
  93                 </listitem>
  94             </varlistentry>
  95             <varlistentry>
  96                 <term>strf</term>
  97                 <listitem>
  98                     <para>
  99                         is a string of length 3 <literal>"xyz"</literal>.
 100                     </para>
 101                     <variablelist>
 102                         <varlistentry>
 103                             <term>default</term>
 104                             <listitem>
 105                                 <para>
 106                                     the default is <literal>"081"</literal>.
 107                                 </para>
 108                             </listitem>
 109                         </varlistentry>
 110                         <varlistentry>
 111                             <term>x</term>
 112                             <listitem>
 113                                 <para>controls the display of captions.</para>
 114                                 <variablelist>
 115                                     <varlistentry>
 116                                         <term>x=0</term>
 117                                         <listitem>
 118                                             <para>no caption.</para>
 119                                         </listitem>
 120                                     </varlistentry>
 121                                     <varlistentry>
 122                                         <term>x=1</term>
 123                                         <listitem>
 124                                             <para>
 125                                                 captions are displayed. They are given by the
 126                                                 optional argument <varname>leg</varname>.
 127                                             </para>
 128                                         </listitem>
 129                                     </varlistentry>
 130                                 </variablelist>
 131                             </listitem>
 132                         </varlistentry>
 133                         <varlistentry>
 134                             <term>y</term>
 135                             <listitem>
 136                                 <para>
 137                                     controls the computation of the actual coordinate ranges
 138                                     from the minimal requested values. Actual ranges can be larger
 139                                     than minimal requirements.
 140                                 </para>
 141                                 <variablelist>
 142                                     <varlistentry>
 143                                         <term>y=0</term>
 144                                         <listitem>
 145                                             <para>
 146                                                 no computation, the plot use the previous (or
 147                                                 default) scale.
 148                                             </para>
 149                                         </listitem>
 150                                     </varlistentry>
 151                                     <varlistentry>
 152                                         <term>y=1</term>
 153                                         <listitem>
 154                                             <para>
 155                                                 from the <varname>rect</varname> argument.
 156                                             </para>
 157                                         </listitem>
 158                                     </varlistentry>
 159                                     <varlistentry>
 160                                         <term>y=2</term>
 161                                         <listitem>
 162                                             <para>from the min/max of the x, y data.</para>
 163                                         </listitem>
 164                                     </varlistentry>
 165                                     <varlistentry>
 166                                         <term>y=3</term>
 167                                         <listitem>
 168                                             <para>
 169                                                 built for an isometric scale from the
 170                                                 <varname>rect</varname> argument.
 171                                             </para>
 172                                         </listitem>
 173                                     </varlistentry>
 174                                     <varlistentry>
 175                                         <term>y=4</term>
 176                                         <listitem>
 177                                             <para>built for an isometric plot from the min/max of
 178                                                 the x, y data.
 179                                             </para>
 180                                         </listitem>
 181                                     </varlistentry>
 182                                     <varlistentry>
 183                                         <term>y=5</term>
 184                                         <listitem>
 185                                             <para>enlarged for pretty axes from the
 186                                                 <varname>rect</varname> argument.
 187                                             </para>
 188                                         </listitem>
 189                                     </varlistentry>
 190                                     <varlistentry>
 191                                         <term>y=6</term>
 192                                         <listitem>
 193                                             <para>
 194                                                 enlarged for pretty axes from the min/max of the
 195                                                 x, y data.
 196                                             </para>
 197                                         </listitem>
 198                                     </varlistentry>
 199                                     <varlistentry>
 200                                         <term>y=7</term>
 201                                         <listitem>
 202                                             <para>
 203                                                 like <literal>y=1</literal> but the previous plots
 204                                                 are redrawn to use the new scale.
 205                                             </para>
 206                                         </listitem>
 207                                     </varlistentry>
 208                                     <varlistentry>
 209                                         <term>y=8</term>
 210                                         <listitem>
 211                                             <para>
 212                                                 like <literal>y=2</literal> but the previous plots
 213                                                 are redrawn to use the new scale.
 214                                             </para>
 215                                         </listitem>
 216                                     </varlistentry>
 217                                 </variablelist>
 218                             </listitem>
 219                         </varlistentry>
 220                         <varlistentry>
 221                             <term>z</term>
 222                             <listitem>
 223                                 <para>
 224                                     controls the display of information on the frame around
 225                                     the plot. If axes are requested, the number of ticks can be
 226                                     specified by the <varname>nax</varname> optional argument.
 227                                 </para>
 228                                 <variablelist>
 229                                     <varlistentry>
 230                                         <term>z=0</term>
 231                                         <listitem>
 232                                             <para>nothing is drawn around the plot.</para>
 233                                         </listitem>
 234                                     </varlistentry>
 235                                     <varlistentry>
 236                                         <term>z=1</term>
 237                                         <listitem>
 238                                             <para>
 239                                                 axes are drawn, the y-axis is displayed on the
 240                                                 left.
 241                                             </para>
 242                                         </listitem>
 243                                     </varlistentry>
 244                                     <varlistentry>
 245                                         <term>z=2</term>
 246                                         <listitem>
 247                                             <para>
 248                                                 the plot is surrounded by a box without ticks.
 249                                             </para>
 250                                         </listitem>
 251                                     </varlistentry>
 252                                     <varlistentry>
 253                                         <term>z=3</term>
 254                                         <listitem>
 255                                             <para>
 256                                                 axes are drawn, the y-axis is displayed on the
 257                                                 right.
 258                                             </para>
 259                                         </listitem>
 260                                     </varlistentry>
 261                                     <varlistentry>
 262                                         <term>z=4</term>
 263                                         <listitem>
 264                                             <para>
 265                                                 axes are drawn centred in the middle of the frame box,
 266                                                 with the box disabled.
 267                                             </para>
 268                                         </listitem>
 269                                     </varlistentry>
 270                                     <varlistentry>
 271                                         <term>z=5</term>
 272                                         <listitem>
 273                                             <para>
 274                                                 axes are drawn centred in the middle of the frame box,
 275                                                 with the box enabled.
 276                                             </para>
 277                                         </listitem>
 278                                     </varlistentry>
 279                                 </variablelist>
 280                             </listitem>
 281                         </varlistentry>
 282                     </variablelist>
 283                 </listitem>
 284             </varlistentry>
 285             <varlistentry>
 286                 <term>rect</term>
 287                 <listitem>
 288                     <para>
 289                         This argument is used when the second character <literal>y</literal>
 290                         of argument <varname>strf</varname> is <literal>1</literal>,
 291                         <literal>3</literal> or <literal>5</literal>. It is a row vector of
 292                         size 4 and gives the dimension of the frame:
 293                         <literal>rect = [xmin, ymin, xmax, ymax]</literal>.
 294                     </para>
 295                 </listitem>
 296             </varlistentry>
 297             <varlistentry>
 298                 <term>nax</term>
 299                 <listitem>
 300                     <para>
 301                         This argument is used when the third character <literal>z</literal>
 302                         of argument <varname>strf</varname> is <literal>1</literal>. It is
 303                         a row vector with four entries <literal>[nx, Nx, ny, Ny]</literal>
 304                         where <literal>nx</literal> (<literal>ny</literal>)
 305                         is the number of subgraduations on the x (y) axis and
 306                         <literal>Nx</literal> (<literal>Ny</literal>) is the number of graduations on
 307                         the x (y) axis.
 308                     </para>
 309                 </listitem>
 310             </varlistentry>
 311         </variablelist>
 312     </refsection>
 313     <refsection>
 314         <title>Description</title>
 315         <para>
 316             The entries of matrix <code>int(a)</code> are used as colormap entries
 317             in the current colormap. The color associated to <literal>a(i,j)</literal>
 318             is used to draw a small square of size 1 with center at location
 319             <literal>(x=j, y=(n1-i+1))</literal>.
 320             If a matrix entry is outside the colormap, the corresponding rectangle is not displayed.
 321         </para>
 322         <para>
 323             <warning>
 324                 To update the Matplot data, the <literal>data</literal> field of the corresponding handle must be used.
 325             </warning>
 326             <literal>data</literal> can be a matrix (or an hypermatrix) containing RGB, RGBA, ... data (see <link linkend="Matplot_properties">Matplot_properties</link>).
 327         </para>
 328         <para>
 329             Enter the command <code>Matplot()</code> to see a demo.
 330         </para>
 331     </refsection>
 332     <refsection>
 333         <title>Examples</title>
 334         <programlisting role="example"><![CDATA[
 335 Matplot([1 2 3;4 5 6])
 336  ]]></programlisting>
 337         <scilab:image>
 338             Matplot([1 2 3;4 5 6])
 339         </scilab:image>
 340         <programlisting role="example"><![CDATA[
 341 clf()
 342 // draw the current colormap
 343 Matplot((1:xget("lastpattern")))
 344  ]]></programlisting>
 345         <scilab:image>
 346             Matplot((1:xget("lastpattern")))
 347         </scilab:image>
 348     </refsection>
 349     <refsection role="see also">
 350         <title>See Also</title>
 351         <simplelist type="inline">
 352             <member>
 353                 <link linkend="colormap">colormap</link>
 354             </member>
 355             <member>
 356                 <link linkend="plot2d">plot2d</link>
 357             </member>
 358             <member>
 359                 <link linkend="Matplot1">Matplot1</link>
 360             </member>
 361             <member>
 362                 <link linkend="Matplot_properties">Matplot_properties</link>
 363             </member>
 364         </simplelist>
 365     </refsection>
 366     <refsection>
 367         <title>History</title>
 368         <revhistory>
 369             <revision>
 370                 <revnumber>5.5.0</revnumber>
 371                 <revremark>
 372                     <literal>data</literal> can now be a matrix (or an hypermatrix) containing RGB, RGBA, ... data (see <link linkend="Matplot_properties">Matplot_properties</link>).
 373                 </revremark>
 374             </revision>
 375         </revhistory>
 376     </refsection>
 377 </refentry>