[doc] champ() page fixed + improved after f94449 70/21470/6
Samuel GOUGEON [Sat, 23 May 2020 14:58:39 +0000 (16:58 +0200)]
  * Description improved.
  * Images champ_1.png and champ_2.png did not match the code:
    their displayed arrows were not oriented with fx>0 and fy>0.
    Example improved.
  * Examples with colored arrows added (after obsoleteing champ1()).
  * See also: + champ_properties
  * Other page improvements.

Change-Id: Id7562b0e5aabfbc9a6514716ef87e3bd5f4d0b05

scilab/modules/graphics/help/en_US/2d_plot/champ.xml
scilab/modules/graphics/help/ja_JP/2d_plot/champ.xml
scilab/modules/graphics/help/pt_BR/2d_plot/champ.xml
scilab/modules/graphics/help/ru_RU/2d_plot/champ.xml
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/champ_1.png
scilab/modules/helptools/images/champ_2.png
scilab/modules/helptools/images/champ_3.png [deleted file]

index a9c07e0..d89c212 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ENPC - Jean-Philippe Chancelier
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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="champ">
+<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="champ">
     <refnamediv>
         <refname>champ</refname>
-        <refpurpose>2D vector field plot</refpurpose>
+        <refpurpose>plots as arrows a field of 2D vectors</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
         <synopsis>
-            champ(x, y, fx, fy, [arfact, rect, strf])
+            champ()  // example
+            champ(x, y, fx, fy)
+            champ(x, y, fx, fy, arfact)
+            champ(x, y, fx, fy, arfact, rect)
+            champ(x, y, fx, fy, arfact, rect, strf)
             champ(x, y, fx, fy, &lt;opt_args&gt;)
         </synopsis>
     </refsynopsisdiv>
             <varlistentry>
                 <term>x, y</term>
                 <listitem>
-                    <para>two vectors which define the grid.</para>
+                    <para>
+                        vectors of decimal numbers, which define the grid of nodes
+                        = coordinates of arrows starting points.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
@@ -73,8 +83,7 @@
                     <para>
                         an optional argument of type <literal>real</literal>
                         which gives a scale factor for the display of the arrow
-                        heads on the plot (default value is
-                        <literal>1.0</literal>).
+                        heads on the plot (default value is <literal>1.0</literal>).
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Description</title>
         <para>
-            <function>champ</function> draws a 2D vector field. The length of
-            the arrows is proportional to the intensity of the field.
+            <literal>champ(…)</literal> plots a field of 2D vectors with arrows.
+        </para>
+        <para>
+            By default, all arrows have the same color, and their length is
+            proportional to the local intensity of the field (norm of vectors).
+            In addition, all lengths are normalized according to the longest arrow.
         </para>
         <para>
-            If you want colored arrows with the color of the arrows depending on
-            the intensity of the field, set <literal>gce().colored = "on"</literal>.
+            When setting <literal>gce().colored = "on"</literal>,
+            each arrow becomes as long as possible in its cell, and is colored
+            according to the local intensity of the field.
         </para>
         <para>
-            Enter the command <code>champ()</code> to see a demo.
+            After calling <literal>champ(…)</literal>, <literal>gce()</literal>
+            returns the handle of the field of arrows, of type <literal>Champ</literal>,
+            whose <link linkend="champ_properties">properties</link> can be post-processed.
         </para>
         <para>
-            Be cautioned about the fact that using <link linkend="meshgrid">meshgrid</link> function before
-            using <code>champ</code> requires adjustment. For more details, see the last example below.
+            Enter the command <literal>champ()</literal> to see an example.
         </para>
     </refsection>
     <refsection>
         <title>Examples</title>
         <programlisting role="example"><![CDATA[
-// using rect as plot boundaries
-champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2)
- ]]></programlisting>
+x = -4:6;
+X = ndgrid(x);
+[fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+clf
+gcf().color_map = jetcolormap(50);
+
+// Field's intensity = arrows length
+subplot(2,2,1)
+champ(x, x, fx, fy)
+
+// With bigger arrow heads
+subplot(2,2,2)
+champ(x, x, fx, fy, arfact=1.7)
+title("arfact=1.7", "fontsize",3)
+
+// Field's intensity = arrows color
+xsetech([0 0.5 0.55 0.5])
+champ(x, x, fx, fy, arfact=1.7)
+gce().colored = "on";
+title("arfact=1.7, .colored=""on""", "fontsize",3)
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+
+// Field's intensity = color, + imposed boundaries
+subplot(2,2,4)
+champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+gce().colored = "on";
+title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+gcf().axes_size = [740 680];
+    ]]></programlisting>
         <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2);
+            x = -4:6;
+            X = ndgrid(x);
+            [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+            clf
+            gcf().color_map = jetcolormap(50);
+
+            // Field's intensity = arrows length
+            subplot(2,2,1)
+            champ(x, x, fx, fy)
+
+            // With bigger arrow heads
+            subplot(2,2,2)
+            champ(x, x, fx, fy, arfact=1.7)
+            title("arfact=1.7", "fontsize",3)
+
+            // Field's intensity = arrows color
+            xsetech([0 0.5 0.55 0.5])
+            champ(x, x, fx, fy, arfact=1.7)
+            gce().colored = "on";
+            title("arfact=1.7, .colored=""on""", "fontsize",3)
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            // Field's intensity = color, + imposed boundaries
+            subplot(2,2,4)
+            champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+            gce().colored = "on";
+            title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+            gcf().axes_size = [740 680];
         </scilab:image>
         <programlisting role="example"><![CDATA[
-// using (x,y) to get boundaries
-clf()
-champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
- ]]></programlisting>
-        <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
-        </scilab:image>
-        <programlisting role="example"><![CDATA[
-// using meshgrid to get fx and fy
-clf()
-x = linspace(-1,1,30);
-y = linspace(-1,1,30);
-[X,Y] = meshgrid(x,y);
-fy = 2.*Y;
-fx = 2.*X;
-champ(x,y,fx',fy'); //here we have transposed fx and fy
+x = -1.2:0.11:0.7;
+y = -1:0.11:0.5;
+[X, Y] = ndgrid(x, y);
+[fx, fy] = (2*X, 2*Y);
+
+clf
+xsetech([0 0 0.45 1])
+champ(x, y, fx, fy)
+title(".colored = ""off"" (default)", "fontsize",3)
+xsetech([0.45 0 0.55 1])
+champ(x, y, fx, fy)
+title(".colored = ""on""", "fontsize",3)
+gce().colored = "on";
+
+gcf().color_map = jetcolormap(100);
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
 ]]></programlisting>
         <scilab:image>
-            x = linspace(-1,1,30);
-            y = linspace(-1,1,30);
-            [X,Y] = meshgrid(x,y);
-            fy = 2.*Y;
-            fx = 2.*X;
-            champ(x,y,fx',fy');
+            x = -1.2:0.11:0.7;
+            y = -1:0.11:0.5;
+            [X, Y] = ndgrid(x, y);
+            [fx, fy] = (2*X, 2*Y);
+
+            clf
+            xsetech([0 0 0.45 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""off"" (default)", "fontsize",3)
+            xsetech([0.45 0 0.55 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""on""", "fontsize",3)
+            gce().colored = "on";
+
+            gcf().color_map = jetcolormap(100);
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            gcf().axes_size = [720 340];
         </scilab:image>
     </refsection>
     <refsection role="see also">
         <title>See also</title>
         <simplelist type="inline">
             <member>
+                <link linkend="champ_properties">champ_properties</link>
+            </member>
+            <member>
                 <link linkend="fchamp">fchamp</link>
             </member>
             <member>
index 9e6cbf9..9ac1b1e 100644 (file)
@@ -1,15 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
 <!--
-
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-
  * Copyright (C) ENPC - Jean-Philippe Chancelier
-
- *
-
-
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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="ja" xml:id="champ">
-
+<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="ja" xml:id="champ">
     <refnamediv>
-
         <refname>champ</refname>
-
         <refpurpose>2次元ベクトルフィールドのプロット</refpurpose>
-
     </refnamediv>
-
     <refsynopsisdiv>
-
         <title>呼び出し手順</title>
-
         <synopsis>
-
-            champ(x,y,fx,fy,[arfact,rect,strf])
-
-            champ(x,y,fx,fy,&lt;opt_args&gt;)
-
+            champ()  // example
+            champ(x, y, fx, fy)
+            champ(x, y, fx, fy, arfact)
+            champ(x, y, fx, fy, arfact, rect)
+            champ(x, y, fx, fy, arfact, rect, strf)
+            champ(x, y, fx, fy, &lt;opt_args&gt;)
         </synopsis>
-
     </refsynopsisdiv>
-
     <refsection>
-
         <title>引数</title>
-
         <variablelist>
-
             <varlistentry>
-
                 <term>x,y</term>
-
                 <listitem>
-
-                    <para>グリッドを定義するベクトル.</para>
-
+                    <para>
+                        vectors of decimal numbers, which define the grid of nodes
+                        = coordinates of arrows starting points.
+                    </para>
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>fx</term>
-
                 <listitem>
-
                     <para>ベクトルフィールドのx要素を記述する行列.
-
                         <literal>fx(i,j)</literal> は点<literal>(x(i),y(j))</literal>における
-
                         ベクトルフィールドのx要素です.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>fy</term>
-
                 <listitem>
-
                     <para>ベクトルフィールドのy要素を記述する行列.
-
                         <literal>fy(i,j)</literal> は点<literal>(x(i),y(j))</literal>における
-
                         ベクトルフィールドのy要素です.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>&lt;opt_args&gt;</term>
-
                 <listitem>
-
                     <para>一連の命令
-
                         <literal>key1=value1,key2=value2</literal>,... を表します.
-
                         ただし, <literal>key1</literal>,
-
                         <literal>key2,...</literal> には以下のどれかを指定可能です: arfact, rect,
-
                         strf (以下参照).
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>arfact</term>
-
                 <listitem>
-
                     <para>
-
                         実数型のオプションの引数で,
-
                         プロット時の矢じりの表示用のスケールファクタを指定します.
-
                         (デフォルト値は 1.0).
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>rect</term>
-
                 <listitem>
-
                     <para>使用するグラフィックフレームの境界を指定する
-
                         ベクトル<literal>rect=[xmin,ymin,xmax,ymax]</literal>.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
             <varlistentry>
-
                 <term>strf</term>
-
                 <listitem>
-
                     <para>
-
                         長さ3の文字列 "xyz" で,<literal>plot2d</literal>の
-
                         <literal>strf</literal>パラメータと意味は同じです.
-
                         最初の文字xは<literal>champ</literal>では意味がありません.
-
                     </para>
-
                 </listitem>
-
             </varlistentry>
-
         </variablelist>
-
     </refsection>
-
     <refsection>
-
         <title>説明</title>
-
         <para>
-
-            <literal>champ</literal> は2次元ベクトルフィールドを描画します.
-
-            矢印の長さはフィールドのインテンシティに比例します.
-
+            <literal>champ(…)</literal> plots a field of 2D vectors with arrows.
         </para>
-
-        <para>フィールドのインテンシティに依存した色を有する色付の矢印を
-
-            使用したい場合,<literal>gce().colored = "on"</literal>を使用してください.
-
+        <para>
+            By default, all arrows have the same color, and their length is
+            proportional to the local intensity of the field (norm of vectors).
+            In addition, all lengths are normalized according to the longest arrow.
         </para>
-
         <para>
-
-            コマンド <literal>champ()</literal> を入力するとデモが表示されます.
-
+            When setting <literal>gce().colored = "on"</literal>,
+            each arrow becomes as long as possible in its cell, and is colored
+            according to the local intensity of the field.
         </para>
-
         <para>
-
-            <code>champ</code>の使用前に <link linkend="meshgrid">meshgrid</link>関数を
-
-            使用する場合は調整が必要なことに注意してください.
-
-            詳細については最後の例を参照ください.
-
+            After calling <literal>champ(…)</literal>, <literal>gce()</literal>
+            returns the handle of the field of arrows, of type <literal>Champ</literal>,
+            whose <link linkend="champ_properties">properties</link> can be post-processed.
+        </para>
+        <para>
+            コマンド <literal>champ()</literal> を入力するとデモが表示されます.
         </para>
-
     </refsection>
-
     <refsection>
-
         <title>例</title>
-
         <programlisting role="example"><![CDATA[
-// rect をプロット境界として使用
-champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2)
- ]]></programlisting>
+x = -4:6;
+X = ndgrid(x);
+[fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+clf
+gcf().color_map = jetcolormap(50);
+
+// Field's intensity = arrows length
+subplot(2,2,1)
+champ(x, x, fx, fy)
+
+// With bigger arrow heads
+subplot(2,2,2)
+champ(x, x, fx, fy, arfact=1.7)
+title("arfact=1.7", "fontsize",3)
+
+// Field's intensity = arrows color
+xsetech([0 0.5 0.55 0.5])
+champ(x, x, fx, fy, arfact=1.7)
+gce().colored = "on";
+title("arfact=1.7, .colored=""on""", "fontsize",3)
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+
+// Field's intensity = color, + imposed boundaries
+subplot(2,2,4)
+champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+gce().colored = "on";
+title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+gcf().axes_size = [740 680];
+    ]]></programlisting>
         <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2);
+            x = -4:6;
+            X = ndgrid(x);
+            [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+            clf
+            gcf().color_map = jetcolormap(50);
+
+            // Field's intensity = arrows length
+            subplot(2,2,1)
+            champ(x, x, fx, fy)
+
+            // With bigger arrow heads
+            subplot(2,2,2)
+            champ(x, x, fx, fy, arfact=1.7)
+            title("arfact=1.7", "fontsize",3)
+
+            // Field's intensity = arrows color
+            xsetech([0 0.5 0.55 0.5])
+            champ(x, x, fx, fy, arfact=1.7)
+            gce().colored = "on";
+            title("arfact=1.7, .colored=""on""", "fontsize",3)
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            // Field's intensity = color, + imposed boundaries
+            subplot(2,2,4)
+            champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+            gce().colored = "on";
+            title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+            gcf().axes_size = [740 680];
         </scilab:image>
         <programlisting role="example"><![CDATA[
-// 境界を取得するために (x,y) を使用
-clf()
-champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
- ]]></programlisting>
-        <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
-        </scilab:image>
-        <programlisting role="example"><![CDATA[
-// fx および fy を得るために meshgrid を使用
-clf()
-x = linspace(-1,1,30);
-y = linspace(-1,1,30);
-[X,Y] = meshgrid(x,y);
-fy = 2.*Y;
-fx = 2.*X;
-champ(x,y,fx',fy'); //転置した fx および fyを使用
+x = -1.2:0.11:0.7;
+y = -1:0.11:0.5;
+[X, Y] = ndgrid(x, y);
+[fx, fy] = (2*X, 2*Y);
+
+clf
+xsetech([0 0 0.45 1])
+champ(x, y, fx, fy)
+title(".colored = ""off"" (default)", "fontsize",3)
+xsetech([0.45 0 0.55 1])
+champ(x, y, fx, fy)
+title(".colored = ""on""", "fontsize",3)
+gce().colored = "on";
+
+gcf().color_map = jetcolormap(100);
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
 ]]></programlisting>
         <scilab:image>
-            x = linspace(-1,1,30);
-            y = linspace(-1,1,30);
-            [X,Y] = meshgrid(x,y);
-            fy = 2.*Y;
-            fx = 2.*X;
-            champ(x,y,fx',fy');
+            x = -1.2:0.11:0.7;
+            y = -1:0.11:0.5;
+            [X, Y] = ndgrid(x, y);
+            [fx, fy] = (2*X, 2*Y);
+
+            clf
+            xsetech([0 0 0.45 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""off"" (default)", "fontsize",3)
+            xsetech([0.45 0 0.55 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""on""", "fontsize",3)
+            gce().colored = "on";
+
+            gcf().color_map = jetcolormap(100);
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            gcf().axes_size = [720 340];
         </scilab:image>
     </refsection>
-
     <refsection role="see also">
-
         <title>参照</title>
-
         <simplelist type="inline">
-
             <member>
-
-                <link linkend="champ1">champ1</link>
-
+                <link linkend="champ_properties">champ_properties</link>
             </member>
-
             <member>
-
                 <link linkend="fchamp">fchamp</link>
-
             </member>
-
             <member>
                 <link linkend="xarrows">xarrows</link>
             </member>
             <member>
                 <link linkend="polyline_properties">Arrowed polyline</link>
             </member>
-
         </simplelist>
-
     </refsection>
-
-</refentry>
-
+</refentry>
\ No newline at end of file
index b4333e5..4a6034b 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ENPC - Jean-Philippe Chancelier
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="champ" xml:lang="pt">
+<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
+          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
+          xmlns:scilab="http://www.scilab.org" xml:id="champ" xml:lang="pt">
     <refnamediv>
         <refname>champ</refname>
         <refpurpose>esboço de campo vetorial 2d</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Seqüência de Chamamento</title>
-        <synopsis>champ(x,y,fx,fy,[arfact,rect,strf])
-            champ(x,y,fx,fy,&lt;opt_args&gt;)
+        <synopsis>
+            champ()  // example
+            champ(x, y, fx, fy)
+            champ(x, y, fx, fy, arfact)
+            champ(x, y, fx, fy, arfact, rect)
+            champ(x, y, fx, fy, arfact, rect, strf)
+            champ(x, y, fx, fy, &lt;opt_args&gt;)
         </synopsis>
     </refsynopsisdiv>
     <refsection>
             <varlistentry>
                 <term>x,y</term>
                 <listitem>
-                    <para>dois vetores que definem o grid</para>
+                    <para>
+                        vectors of decimal numbers, which define the grid of nodes
+                        = coordinates of arrows starting points.
+                    </para>
                 </listitem>
             </varlistentry>
             <varlistentry>
     <refsection>
         <title>Descrição</title>
         <para>
-            <literal>champ</literal> desenha um campo vetorial 2d. O comprimento
-            das setas é proporcional é proporcional à intensidade do campo.
+            <literal>champ(…)</literal> plota um campo de vetores 2D com setas.
         </para>
-        <para>Se você quiser setas coloridas com a cor das setas dependendo da
-            intensidade do campo, use <literal>gce().colored = "on"</literal>.
+        <para>
+            By default, all arrows have the same color, and their length is
+            proportional to the local intensity of the field (norm of vectors).
+            In addition, all lengths are normalized according to the longest arrow.
+        </para>
+        <para>
+            When setting <literal>gce().colored = "on"</literal>,
+            each arrow becomes as long as possible in its cell, and is colored
+            according to the local intensity of the field.
         </para>
         <para>
-            Entre com o comando <literal>champ()</literal> para visualizar uma
-            demonstração.
+            After calling <literal>champ(…)</literal>, <literal>gce()</literal>
+            returns the handle of the field of arrows, of type <literal>Champ</literal>,
+            whose <link linkend="champ_properties">properties</link> can be post-processed.
+        </para>
+        <para>
+            Entre com o comando <literal>champ()</literal> para visualizar um exemplo.
         </para>
     </refsection>
     <refsection>
         <title>Exemplos</title>
         <programlisting role="example"><![CDATA[
-// usando rect como fronteiras do esboço
-champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2)
-// usando (x,y) para conseguir obter
-clf()
-champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
- ]]></programlisting>
+x = -4:6;
+X = ndgrid(x);
+[fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+clf
+gcf().color_map = jetcolormap(50);
+
+// Field's intensity = arrows length
+subplot(2,2,1)
+champ(x, x, fx, fy)
+
+// With bigger arrow heads
+subplot(2,2,2)
+champ(x, x, fx, fy, arfact=1.7)
+title("arfact=1.7", "fontsize",3)
+
+// Field's intensity = arrows color
+xsetech([0 0.5 0.55 0.5])
+champ(x, x, fx, fy, arfact=1.7)
+gce().colored = "on";
+title("arfact=1.7, .colored=""on""", "fontsize",3)
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+
+// Field's intensity = color, + imposed boundaries
+subplot(2,2,4)
+champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+gce().colored = "on";
+title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+gcf().axes_size = [740 680];
+    ]]></programlisting>
+        <scilab:image>
+            x = -4:6;
+            X = ndgrid(x);
+            [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+            clf
+            gcf().color_map = jetcolormap(50);
+
+            // Field's intensity = arrows length
+            subplot(2,2,1)
+            champ(x, x, fx, fy)
+
+            // With bigger arrow heads
+            subplot(2,2,2)
+            champ(x, x, fx, fy, arfact=1.7)
+            title("arfact=1.7", "fontsize",3)
+
+            // Field's intensity = arrows color
+            xsetech([0 0.5 0.55 0.5])
+            champ(x, x, fx, fy, arfact=1.7)
+            gce().colored = "on";
+            title("arfact=1.7, .colored=""on""", "fontsize",3)
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            // Field's intensity = color, + imposed boundaries
+            subplot(2,2,4)
+            champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+            gce().colored = "on";
+            title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+            gcf().axes_size = [740 680];
+        </scilab:image>
+        <programlisting role="example"><![CDATA[
+x = -1.2:0.11:0.7;
+y = -1:0.11:0.5;
+[X, Y] = ndgrid(x, y);
+[fx, fy] = (2*X, 2*Y);
+
+clf
+xsetech([0 0 0.45 1])
+champ(x, y, fx, fy)
+title(".colored = ""off"" (default)", "fontsize",3)
+xsetech([0.45 0 0.55 1])
+champ(x, y, fx, fy)
+title(".colored = ""on""", "fontsize",3)
+gce().colored = "on";
+
+gcf().color_map = jetcolormap(100);
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+]]></programlisting>
+        <scilab:image>
+            x = -1.2:0.11:0.7;
+            y = -1:0.11:0.5;
+            [X, Y] = ndgrid(x, y);
+            [fx, fy] = (2*X, 2*Y);
+
+            clf
+            xsetech([0 0 0.45 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""off"" (default)", "fontsize",3)
+            xsetech([0.45 0 0.55 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""on""", "fontsize",3)
+            gce().colored = "on";
+
+            gcf().color_map = jetcolormap(100);
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            gcf().axes_size = [720 340];
+        </scilab:image>
     </refsection>
     <refsection role="see also">
         <title>Ver Também</title>
         <simplelist type="inline">
             <member>
+                <link linkend="champ_properties">champ_properties</link>
+            </member>
+            <member>
                 <link linkend="fchamp">fchamp</link>
             </member>
             <member>
index 3fbf095..cde456b 100644 (file)
@@ -2,8 +2,8 @@
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) ENPC - Jean-Philippe Chancelier
- *
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
+ * Copyright (C) 2020 - Samuel GOUGEON
  *
  * 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.
  * 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="ru" xml:id="champ">
+<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="ru" xml:id="champ">
     <refnamediv>
         <refname>champ</refname>
-        <refpurpose>двумерный график векторного поля</refpurpose>
+        <refpurpose>строит стрелками поле двумерных векторов</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Синтаксис</title>
         <synopsis>
-            champ(x, y, fx, fy, [arfact, rect, strf])
+            champ()  // example
+            champ(x, y, fx, fy)
+            champ(x, y, fx, fy, arfact)
+            champ(x, y, fx, fy, arfact, rect)
+            champ(x, y, fx, fy, arfact, rect, strf)
             champ(x, y, fx, fy, &lt;opt_args&gt;)
         </synopsis>
     </refsynopsisdiv>
@@ -32,7 +39,8 @@
                 <term>x, y</term>
                 <listitem>
                     <para>
-                        два вектора, которые определяют сетку графика.
+                        векторы десятичных чисел, которые определяют сетку узлов = координат начальных
+                        точек стрелок.
                     </para>
                 </listitem>
             </varlistentry>
     <refsection>
         <title>Описание</title>
         <para>
-            <function>champ</function> рисует двумерное векторное поле. Длина
-            стрелок пропорциональна интенсивности поля.
+            <literal>champ(…)</literal> строит поле двумерных веторов с помощью стрелок.
+        </para>
+        <para>
+            По умолчанию все стрелки одного цвета, а их длина пропорционально локальной интенсивности
+            поля (норма векторов). Кроме того, все длины нормированы в соответствии с самой длинной стрелкой.
+        </para>
+        <para>
+            Когда установлено <literal>gce().colored = "on"</literal>,
+            каждая стрелка становится настолько длинной, насколько это возможно в её ячейке, и её
+            цвет соответствует локальной интенсивности поля.
         </para>
         <para>
-            Если вы желаете раскрасить стрелки в зависимости от интенсивности
-            поля, то используйте <literal>gce().colored = "on"</literal>.
+            После вызова <literal>champ(…)</literal>, <literal>gce()</literal>
+            возвращает дескриптор поля стрелок типа <literal>Champ</literal>,
+            чьи <link linkend="champ_properties">свойства</link> могут быть далее обработаны.
         </para>
         <para>
-            Введите команду <code>champ()</code> для просмотра демонстрации.
+            Введите команду <literal>champ()</literal>, чтобу увидеть пример.
         </para>
     </refsection>
     <refsection>
         <title>Примеры</title>
         <programlisting role="example"><![CDATA[
-// использование rect в качестве границ графика
-champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2)
- ]]></programlisting>
+x = -4:6;
+X = ndgrid(x);
+[fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+clf
+gcf().color_map = jetcolormap(50);
+
+// Интенсивность поля = длине стрелок
+subplot(2,2,1)
+champ(x, x, fx, fy)
+
+// С более крупной стрелкой
+subplot(2,2,2)
+champ(x, x, fx, fy, arfact=1.7)
+title("arfact=1.7", "fontsize",3)
+
+// Интенсивность поля = цвету стрелок
+xsetech([0 0.5 0.55 0.5])
+champ(x, x, fx, fy, arfact=1.7)
+gce().colored = "on";
+title("arfact=1.7, .colored=""on""", "fontsize",3)
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+
+// Интенсивность поля = цвету, + расширенные пределы
+subplot(2,2,4)
+champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+gce().colored = "on";
+title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+gcf().axes_size = [740 680];
+    ]]></programlisting>
         <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),rect=[-10,-10,10,10],arfact=2);
+            x = -4:6;
+            X = ndgrid(x);
+            [fx, fy] =  (rand(X)-0.5, rand(X)-0.5);
+
+            clf
+            gcf().color_map = jetcolormap(50);
+
+            // Field's intensity = arrows length
+            subplot(2,2,1)
+            champ(x, x, fx, fy)
+
+            // With bigger arrow heads
+            subplot(2,2,2)
+            champ(x, x, fx, fy, arfact=1.7)
+            title("arfact=1.7", "fontsize",3)
+
+            // Field's intensity = arrows color
+            xsetech([0 0.5 0.55 0.5])
+            champ(x, x, fx, fy, arfact=1.7)
+            gce().colored = "on";
+            title("arfact=1.7, .colored=""on""", "fontsize",3)
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            // Field's intensity = color, + imposed boundaries
+            subplot(2,2,4)
+            champ(x, x, fx, fy, rect=[-5,-6,9,7],strf="011")
+            gce().colored = "on";
+            title("rect=[-5,-6,9,6], strf=""011"", .colored=""on""", "fontsize",3)
+
+            gcf().axes_size = [740 680];
         </scilab:image>
         <programlisting role="example"><![CDATA[
-// использование (x,y) для получения границ
-clf()
-champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
- ]]></programlisting>
+x = -1.2:0.11:0.7;
+y = -1:0.11:0.5;
+[X, Y] = ndgrid(x, y);
+[fx, fy] = (2*X, 2*Y);
+
+clf
+xsetech([0 0 0.45 1])
+champ(x, y, fx, fy)
+title(".colored = ""off"" (по умолчанию)", "fontsize",3)
+xsetech([0.45 0 0.55 1])
+champ(x, y, fx, fy)
+title(".colored = ""on""", "fontsize",3)
+gce().colored = "on";
+
+gcf().color_map = jetcolormap(100);
+L = sqrt(fx.^2 + fy.^2);
+colorbar(min(L), max(L));
+]]></programlisting>
         <scilab:image>
-            champ(-5:5,-5:5,rand(11,11),rand(11,11),2,[-10,-10,10,10],"021")
+            x = -1.2:0.11:0.7;
+            y = -1:0.11:0.5;
+            [X, Y] = ndgrid(x, y);
+            [fx, fy] = (2*X, 2*Y);
+
+            clf
+            xsetech([0 0 0.45 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""off"" (default)", "fontsize",3)
+            xsetech([0.45 0 0.55 1])
+            champ(x, y, fx, fy)
+            title(".colored = ""on""", "fontsize",3)
+            gce().colored = "on";
+
+            gcf().color_map = jetcolormap(100);
+            L = sqrt(fx.^2 + fy.^2);
+            colorbar(min(L), max(L));
+
+            gcf().axes_size = [720 340];
         </scilab:image>
     </refsection>
     <refsection role="see also">
index b99aa68..53915bf 100644 (file)
@@ -585,9 +585,8 @@ cdfnor_ru_RU_2.png=f6deb7f340aad408031249884d3849e0
 cepstrum_1.png=455b8e394db80f8bb6fb8c656a069af3
 champ1_1.png=d2aacf45d80c8edf7c95a54af1533ce4
 champ1_2.png=bc00271f4944a350125eb5b3c40d48c1
-champ_1.png=c0e293f757cc87203308abb3d0bd5823
-champ_2.png=83eb5af09a3e46812639bf482ce290e4
-champ_3.png=e46cb90fcd5bcc2552ee046eb1a1f216
+champ_1.png=93ae8a9901fda82c64ef93bf191628a8
+champ_2.png=1481a818a469230ed0972650870351a4
 champ_properties_1.png=6409c708318038fda6b54aacc96937eb
 cheb1mag_1.png=3b26f5856ff8a2bcfbcf78e2d77cb5c1
 cheb2mag_1.png=d53206e41bccd28401ab6309ce2f941a
index 26638c8..db95f4d 100644 (file)
Binary files a/scilab/modules/helptools/images/champ_1.png and b/scilab/modules/helptools/images/champ_1.png differ
index c556789..a4f4682 100644 (file)
Binary files a/scilab/modules/helptools/images/champ_2.png and b/scilab/modules/helptools/images/champ_2.png differ
diff --git a/scilab/modules/helptools/images/champ_3.png b/scilab/modules/helptools/images/champ_3.png
deleted file mode 100644 (file)
index 986726f..0000000
Binary files a/scilab/modules/helptools/images/champ_3.png and /dev/null differ