Get rid of show_pixmap + add new sample images
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / Sgrayplot.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-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" version="5.0-subset Scilab" xml:lang="en" xml:id="Sgrayplot">
14     <refnamediv>
15         <refname>Sgrayplot</refname>
16         <refpurpose>smooth 2D plot of a surface using
17             colors
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>Sgrayplot(x,y,z,&lt;opt_args&gt;)
23             Sgrayplot(x,y,z [,strf, rect, nax, zminmax, colminmax, mesh, colout])
24         </synopsis>
25     </refsynopsisdiv>
26     <refsection>
27         <title>Arguments</title>
28         <variablelist>
29             <varlistentry>
30                 <term>x,y</term>
31                 <listitem>
32                     <para>real row vectors of size n1 and n2.</para>
33                 </listitem>
34             </varlistentry>
35             <varlistentry>
36                 <term>z</term>
37                 <listitem>
38                     <para>
39                         real matrix of size (n1,n2). <literal>z(i,j)</literal> is the value
40                         of the surface at the point (x(i),y(j)).
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>&lt;opt_args&gt;</term>
46                 <listitem>
47                     <para>This represents a sequence of statements
48                         <literal>key1=value1,key2=value2</literal>,... where <literal>key1</literal>,
49                         <literal>key2,...</literal> can be one of the following: strf, rect, nax, zminmax, colminmax, mesh, colout.
50                     </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>strf</term>
55                 <listitem>
56                     <para>
57                         is a string of length 3 <literal>"xyz"</literal> (by default
58                         <literal>strf= "081"</literal>)
59                     </para>
60                     <variablelist>
61                         <varlistentry>
62                             <term>x</term>
63                             <listitem>
64                                 <para>controls the display of captions.</para>
65                                 <variablelist>
66                                     <varlistentry>
67                                         <term>x=0</term>
68                                         <listitem>
69                                             <para>no caption.</para>
70                                         </listitem>
71                                     </varlistentry>
72                                     <varlistentry>
73                                         <term>x=1</term>
74                                         <listitem>
75                                             <para>captions are displayed. They are given by the
76                                                 optional argument <literal>leg</literal>.
77                                             </para>
78                                         </listitem>
79                                     </varlistentry>
80                                 </variablelist>
81                             </listitem>
82                         </varlistentry>
83                         <varlistentry>
84                             <term>y</term>
85                             <listitem>
86                                 <para>controls the computation of the actual coordinate ranges
87                                     from the minimal requested values. Actual ranges can be larger
88                                     than minimal requirements.
89                                 </para>
90                                 <variablelist>
91                                     <varlistentry>
92                                         <term>y=0</term>
93                                         <listitem>
94                                             <para>no computation, the plot use the previus (or
95                                                 default) scale
96                                             </para>
97                                         </listitem>
98                                     </varlistentry>
99                                     <varlistentry>
100                                         <term>y=1</term>
101                                         <listitem>
102                                             <para>from the rect arg</para>
103                                         </listitem>
104                                     </varlistentry>
105                                     <varlistentry>
106                                         <term>y=2</term>
107                                         <listitem>
108                                             <para>from the min/max of the x, y data</para>
109                                         </listitem>
110                                     </varlistentry>
111                                     <varlistentry>
112                                         <term>y=3</term>
113                                         <listitem>
114                                             <para>built for an isometric scale from the rect
115                                                 arg
116                                             </para>
117                                         </listitem>
118                                     </varlistentry>
119                                     <varlistentry>
120                                         <term>y=4</term>
121                                         <listitem>
122                                             <para>built for an isometric plot from the min/max of
123                                                 the x, y data
124                                             </para>
125                                         </listitem>
126                                     </varlistentry>
127                                     <varlistentry>
128                                         <term>y=5</term>
129                                         <listitem>
130                                             <para>enlarged for pretty axes from the rect arg</para>
131                                         </listitem>
132                                     </varlistentry>
133                                     <varlistentry>
134                                         <term>y=6</term>
135                                         <listitem>
136                                             <para>enlarged for pretty axes from the min/max of the
137                                                 x, y data
138                                             </para>
139                                         </listitem>
140                                     </varlistentry>
141                                     <varlistentry>
142                                         <term>y=7</term>
143                                         <listitem>
144                                             <para>like y=1 but the previus plot(s) are redrawn to
145                                                 use the new scale
146                                             </para>
147                                         </listitem>
148                                     </varlistentry>
149                                     <varlistentry>
150                                         <term>y=8</term>
151                                         <listitem>
152                                             <para>like y=2 but the previus plot(s) are redrawn to
153                                                 use the new scale
154                                             </para>
155                                         </listitem>
156                                     </varlistentry>
157                                 </variablelist>
158                             </listitem>
159                         </varlistentry>
160                         <varlistentry>
161                             <term>z</term>
162                             <listitem>
163                                 <para>controls the display of information on the frame around
164                                     the plot. If axes are requested, the number of tics can be
165                                     specified by the <literal>nax</literal> optional argument.
166                                 </para>
167                                 <variablelist>
168                                     <varlistentry>
169                                         <term>z=0</term>
170                                         <listitem>
171                                             <para>nothing is drawn around the plot.</para>
172                                         </listitem>
173                                     </varlistentry>
174                                     <varlistentry>
175                                         <term>z=1</term>
176                                         <listitem>
177                                             <para>axes are drawn, the y=axis is displayed on the
178                                                 left.
179                                             </para>
180                                         </listitem>
181                                     </varlistentry>
182                                     <varlistentry>
183                                         <term>z=2</term>
184                                         <listitem>
185                                             <para>the plot is surrounded by a box without tics.</para>
186                                         </listitem>
187                                     </varlistentry>
188                                     <varlistentry>
189                                         <term>z=3</term>
190                                         <listitem>
191                                             <para>axes are drawn, the y=axis is displayed on the
192                                                 right.
193                                             </para>
194                                         </listitem>
195                                     </varlistentry>
196                                     <varlistentry>
197                                         <term>z=4</term>
198                                         <listitem>
199                                             <para>axes are drawn centred in the middle of the frame
200                                                 box, with the box disabled.
201                                             </para>
202                                         </listitem>
203                                     </varlistentry>
204                                     <varlistentry>
205                                         <term>z=5</term>
206                                         <listitem>
207                                             <para>axes are drawn centred in the middle of the frame
208                                                 box, with the box enabled.
209                                             </para>
210                                         </listitem>
211                                     </varlistentry>
212                                 </variablelist>
213                             </listitem>
214                         </varlistentry>
215                     </variablelist>
216                 </listitem>
217             </varlistentry>
218             <varlistentry>
219                 <term>rect</term>
220                 <listitem>
221                     <para>This argument is used when the second character y of argument
222                         <literal>strf</literal> is 1, 3 or 5. It is a row vector of size 4 and
223                         gives the dimension of the frame:
224                         <literal>rect=[xmin,ymin,xmax,ymax]</literal>.
225                     </para>
226                 </listitem>
227             </varlistentry>
228             <varlistentry>
229                 <term>nax</term>
230                 <listitem>
231                     <para>This argument is used when the third character z of argument
232                         <literal>strf</literal> is 1. It is a row vector with four entries
233                         <literal>[nx,Nx,ny,Ny]</literal> where <literal>nx</literal> (<literal>ny</literal>)
234                         is the number of subgraduations on the x (y) axis and
235                         <literal>Nx</literal> (<literal>Ny</literal>) is the number of graduations on
236                         the x (y) axis.
237                     </para>
238                 </listitem>
239             </varlistentry>
240             <varlistentry>
241                 <term>zminmax, colminmax, mesh, colout</term>
242                 <listitem>
243                     <para>
244                         See <link linkend="fec">fec</link>.
245                     </para>
246                 </listitem>
247             </varlistentry>
248         </variablelist>
249     </refsection>
250     <refsection>
251         <title>Description</title>
252         <para>
253             <literal>Sgrayplot</literal> is the same as <literal>grayplot</literal> but the
254             plot is smoothed. The function <literal>fec</literal> is used for smoothing. The
255             surface is plotted assuming that it is linear on a set of triangles built
256             from the grid (here with n1=5, n2=3):
257         </para>
258         <programlisting role=""><![CDATA[ 
259 _____________
260 | /| /| /| /|
261 |/_|/_|/_|/_| 
262 | /| /| /| /| 
263 |/_|/_|/_|/_|
264  ]]></programlisting>
265         <para>
266             The function <link linkend="colorbar">colorbar</link> may be used to see the color scale.
267         </para>
268         <para>
269             The parameter <literal>zminmax</literal> is useful for animation purpose (see an
270             example after) and the parameter <literal>colminmax</literal> lets the user choose a part
271             of the current colormap (see the <link linkend="fec">fec</link> help page).
272         </para>
273         <para>
274             Enter the command <literal>Sgrayplot()</literal> to see a demo.
275         </para>
276     </refsection>
277     <refsection>
278         <title>Sample</title>
279         <scilab:image>Sgrayplot();</scilab:image>
280     </refsection>
281     <refsection>
282         <title>Examples</title>
283         <programlisting role="example"><![CDATA[
284 // example #1
285 x=-10:10; y=-10:10;m =rand(21,21);
286 clf()
287 xset("colormap",hotcolormap(64))
288 Sgrayplot(x,y,m, strf="011", rect=[-20,-20,20,20])
289  ]]></programlisting>
290         <scilab:image>
291             x=-10:10; y=-10:10;m =rand(21,21);
292             clf()
293             xset("colormap",hotcolormap(64))
294             Sgrayplot(x,y,m, strf="011", rect=[-20,-20,20,20])
295         </scilab:image>
296         <programlisting role="example"><![CDATA[
297 // example #2
298 t=-%pi:0.1:%pi; m=sin(t)'*cos(t);
299 clf()
300 xset("colormap",jetcolormap(64))
301 colorbar(-1,1)
302 Sgrayplot(t,t,m, strf="041") 
303 ]]></programlisting>
304         <scilab:image>
305             t=-%pi:0.1:%pi; m=sin(t)'*cos(t);
306             clf()
307             xset("colormap",jetcolormap(64))
308             colorbar(-1,1)
309             Sgrayplot(t,t,m, strf="041") 
310         </scilab:image>
311         <programlisting role="example"><![CDATA[
312 // example #3: an animation display cos(t)*sin(x)sin(y).
313 n = 30;
314 nt = 100;
315 x = linspace(0,2*%pi,n);
316 y = linspace(0,%pi,n/2);
317 z = sin(x')*sin(y);
318 t = linspace(0,4*%pi,nt);
319 show_window(); clf()
320 f=gcf();
321 f.color_map=jetcolormap(64);
322 f.pixmap='on';
323 colorbar(-1,1)
324 Sgrayplot(x,y,cos(t(1))*z, strf="042", zminmax=[-1,1])
325 c=gce(),e=c.children
326 xtitle("Kaa''s eyes")
327 for i = 1:nt
328   e.data(:,3)=matrix(cos(t(i))*z,-1,1);
329 end
330 f.pixmap='off';
331  ]]></programlisting>
332         <scilab:image>
333             n = 30;
334             nt = 100;
335             x = linspace(0,2*%pi,n);
336             y = linspace(0,%pi,n/2);
337             z = sin(x')*sin(y);
338             t = linspace(0,4*%pi,nt);
339             show_window(); clf()
340             f=gcf();
341             f.color_map=jetcolormap(64);
342             f.pixmap='on';
343             colorbar(-1,1)
344             Sgrayplot(x,y,cos(t(1))*z, strf="042", zminmax=[-1,1])
345             c=gce(),e=c.children
346             xtitle("Kaa''s eyes")
347             for i = 1:nt
348             e.data(:,3)=matrix(cos(t(i))*z,-1,1);
349             end
350             f.pixmap='off';
351         </scilab:image>
352     </refsection>
353     <refsection role="see also">
354         <title>See Also</title>
355         <simplelist type="inline">
356             <member>
357                 <link linkend="fec">fec</link>
358             </member>
359             <member>
360                 <link linkend="fgrayplot">fgrayplot</link>
361             </member>
362             <member>
363                 <link linkend="grayplot">grayplot</link>
364             </member>
365             <member>
366                 <link linkend="Sfgrayplot">Sfgrayplot</link>
367             </member>
368             <member>
369                 <link linkend="colorbar">colorbar</link>
370             </member>
371         </simplelist>
372     </refsection>
373 </refentry>