4015b61d985a1d76511b82ff0dbddf428ddcdb6f
[scilab.git] / 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         </para>
327         <para>
328             Enter the command <code>Matplot()</code> to see a demo.
329         </para>
330     </refsection>
331     <refsection>
332         <title>Examples</title>
333         <programlisting role="example"><![CDATA[ 
334 Matplot([1 2 3;4 5 6])
335  ]]></programlisting>
336         <scilab:image>
337             Matplot([1 2 3;4 5 6])
338         </scilab:image>
339         <programlisting role="example"><![CDATA[ 
340 clf()
341 // draw the current colormap 
342 Matplot((1:xget("lastpattern")))
343  ]]></programlisting>
344         <scilab:image>
345             Matplot((1:xget("lastpattern")))
346         </scilab:image>
347     </refsection>
348     <refsection role="see also">
349         <title>See Also</title>
350         <simplelist type="inline">
351             <member>
352                 <link linkend="colormap">colormap</link>
353             </member>
354             <member>
355                 <link linkend="plot2d">plot2d</link>
356             </member>
357             <member>
358                 <link linkend="Matplot1">Matplot1</link>
359             </member>
360             <member>
361                 <link linkend="Matplot_properties">Matplot_properties</link>
362             </member>
363         </simplelist>
364     </refsection>
365 </refentry>