[doc] champ() page fixed + improved after f94449
[scilab.git] / scilab / modules / graphics / help / en_US / 2d_plot / champ.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2020 - Samuel GOUGEON
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
18           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
19           xml:lang="en" xml:id="champ">
20     <refnamediv>
21         <refname>champ</refname>
22         <refpurpose>plots as arrows a field of 2D vectors</refpurpose>
23     </refnamediv>
24     <refsynopsisdiv>
25         <title>Syntax</title>
26         <synopsis>
27             champ()  // example
28             champ(x, y, fx, fy)
29             champ(x, y, fx, fy, arfact)
30             champ(x, y, fx, fy, arfact, rect)
31             champ(x, y, fx, fy, arfact, rect, strf)
32             champ(x, y, fx, fy, &lt;opt_args&gt;)
33         </synopsis>
34     </refsynopsisdiv>
35     <refsection>
36         <title>Arguments</title>
37         <variablelist>
38             <varlistentry>
39                 <term>x, y</term>
40                 <listitem>
41                     <para>
42                         vectors of decimal numbers, which define the grid of nodes
43                         = coordinates of arrows starting points.
44                     </para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>fx</term>
49                 <listitem>
50                     <para>
51                         a matrix which describes the x component of the vector
52                         field. <literal>fx(i,j)</literal> is the x
53                         component of the vector field at point
54                         <literal>(x(i),y(j))</literal>.
55                     </para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>fy</term>
60                 <listitem>
61                     <para>
62                         a matrix which describes the y component of the vector
63                         field. <literal>fy(i,j)</literal> is the y component of
64                         the vector field at point <literal>(x(i),y(j))</literal>.
65                     </para>
66                 </listitem>
67             </varlistentry>
68             <varlistentry>
69                 <term>&lt;opt_args&gt;</term>
70                 <listitem>
71                     <para>
72                         This represents a sequence of statements
73                         <literal>key1=value1, key2=value2</literal>,... where
74                         <literal>key1</literal>, <literal>key2</literal>,... can
75                         be one of the following: <varname>arfact</varname>,
76                         <varname>rect</varname>, <varname>strf</varname> (see below).
77                     </para>
78                 </listitem>
79             </varlistentry>
80             <varlistentry>
81                 <term>arfact</term>
82                 <listitem>
83                     <para>
84                         an optional argument of type <literal>real</literal>
85                         which gives a scale factor for the display of the arrow
86                         heads on the plot (default value is <literal>1.0</literal>).
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>rect</term>
92                 <listitem>
93                     <para>
94                         a vector <literal>rect=[xmin, ymin, xmax, ymax]</literal>
95                         which gives the boundaries of the graphics frame to use.
96                     </para>
97                 </listitem>
98             </varlistentry>
99             <varlistentry>
100                 <term>strf</term>
101                 <listitem>
102                     <para>
103                         a string of length 3 "xyz" which has the same meaning as
104                         the <varname>strf</varname> parameter of
105                         <function>plot2d</function>. The first  character
106                         <literal>x</literal> has no effect with
107                         <function>champ</function>.
108                     </para>
109                 </listitem>
110             </varlistentry>
111         </variablelist>
112     </refsection>
113     <refsection>
114         <title>Description</title>
115         <para>
116             <literal>champ(…)</literal> plots a field of 2D vectors with arrows.
117         </para>
118         <para>
119             By default, all arrows have the same color, and their length is
120             proportional to the local intensity of the field (norm of vectors).
121             In addition, all lengths are normalized according to the longest arrow.
122         </para>
123         <para>
124             When setting <literal>gce().colored = "on"</literal>,
125             each arrow becomes as long as possible in its cell, and is colored
126             according to the local intensity of the field.
127         </para>
128         <para>
129             After calling <literal>champ(…)</literal>, <literal>gce()</literal>
130             returns the handle of the field of arrows, of type <literal>Champ</literal>,
131             whose <link linkend="champ_properties">properties</link> can be post-processed.
132         </para>
133         <para>
134             Enter the command <literal>champ()</literal> to see an example.
135         </para>
136     </refsection>
137     <refsection>
138         <title>Examples</title>
139         <programlisting role="example"><![CDATA[
140 x = -4:6;
141 X = ndgrid(x);
142 [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
143
144 clf
145 gcf().color_map = jetcolormap(50);
146
147 // Field's intensity = arrows length
148 subplot(2,2,1)
149 champ(x, x, fx, fy)
150
151 // With bigger arrow heads
152 subplot(2,2,2)
153 champ(x, x, fx, fy, arfact=1.7)
154 title("arfact=1.7", "fontsize",3)
155
156 // Field's intensity = arrows color
157 xsetech([0 0.5 0.55 0.5])
158 champ(x, x, fx, fy, arfact=1.7)
159 gce().colored = "on";
160 title("arfact=1.7, .colored=""on""", "fontsize",3)
161 L = sqrt(fx.^2 + fy.^2);
162 colorbar(min(L), max(L));
163
164 // Field's intensity = color, + imposed boundaries
165 subplot(2,2,4)
166 champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
167 gce().colored = "on";
168 title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
169
170 gcf().axes_size = [740 680];
171     ]]></programlisting>
172         <scilab:image>
173             x = -4:6;
174             X = ndgrid(x);
175             [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
176
177             clf
178             gcf().color_map = jetcolormap(50);
179
180             // Field's intensity = arrows length
181             subplot(2,2,1)
182             champ(x, x, fx, fy)
183
184             // With bigger arrow heads
185             subplot(2,2,2)
186             champ(x, x, fx, fy, arfact=1.7)
187             title("arfact=1.7", "fontsize",3)
188
189             // Field's intensity = arrows color
190             xsetech([0 0.5 0.55 0.5])
191             champ(x, x, fx, fy, arfact=1.7)
192             gce().colored = "on";
193             title("arfact=1.7, .colored=""on""", "fontsize",3)
194             L = sqrt(fx.^2 + fy.^2);
195             colorbar(min(L), max(L));
196
197             // Field's intensity = color, + imposed boundaries
198             subplot(2,2,4)
199             champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
200             gce().colored = "on";
201             title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
202
203             gcf().axes_size = [740 680];
204         </scilab:image>
205         <programlisting role="example"><![CDATA[
206 x = -1.2:0.11:0.7;
207 y = -1:0.11:0.5;
208 [X, Y] = ndgrid(x, y);
209 [fx, fy] = (2*X, 2*Y);
210
211 clf
212 xsetech([0 0 0.45 1])
213 champ(x, y, fx, fy)
214 title(".colored = ""off"" (default)", "fontsize",3)
215 xsetech([0.45 0 0.55 1])
216 champ(x, y, fx, fy)
217 title(".colored = ""on""", "fontsize",3)
218 gce().colored = "on";
219
220 gcf().color_map = jetcolormap(100);
221 L = sqrt(fx.^2 + fy.^2);
222 colorbar(min(L), max(L));
223 ]]></programlisting>
224         <scilab:image>
225             x = -1.2:0.11:0.7;
226             y = -1:0.11:0.5;
227             [X, Y] = ndgrid(x, y);
228             [fx, fy] = (2*X, 2*Y);
229
230             clf
231             xsetech([0 0 0.45 1])
232             champ(x, y, fx, fy)
233             title(".colored = ""off"" (default)", "fontsize",3)
234             xsetech([0.45 0 0.55 1])
235             champ(x, y, fx, fy)
236             title(".colored = ""on""", "fontsize",3)
237             gce().colored = "on";
238
239             gcf().color_map = jetcolormap(100);
240             L = sqrt(fx.^2 + fy.^2);
241             colorbar(min(L), max(L));
242
243             gcf().axes_size = [720 340];
244         </scilab:image>
245     </refsection>
246     <refsection role="see also">
247         <title>See also</title>
248         <simplelist type="inline">
249             <member>
250                 <link linkend="champ_properties">champ_properties</link>
251             </member>
252             <member>
253                 <link linkend="fchamp">fchamp</link>
254             </member>
255             <member>
256                 <link linkend="xarrows">xarrows</link>
257             </member>
258             <member>
259                 <link linkend="polyline_properties">Arrowed polyline</link>
260             </member>
261         </simplelist>
262     </refsection>
263 </refentry>