<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://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.
 * This file was originally licensed under the terms of the CeCILL v2.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="ru" xml:id="champ">
    <refnamediv>
        <refname>champ</refname>
        <refpurpose>строит стрелками поле двумерных векторов</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <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>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>x, y</term>
                <listitem>
                    <para>
                        векторы десятичных чисел, которые определяют сетку узлов = координат начальных
                        точек стрелок.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fx</term>
                <listitem>
                    <para>
                        матрица, которая описывает x-составляющую векторного
                        поля. <literal>fx(i,j)</literal> - это x-составляющая
                        векторного поля в точке <literal>(x(i),y(j))</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fy</term>
                <listitem>
                    <para>
                        матрица, которая описывает y-составляющую векторного
                        поля. <literal>fy(i,j)</literal> - это y-составляющая
                        векторного поля в точке <literal>(x(i),y(j))</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>&lt;opt_args&gt;</term>
                <listitem>
                    <para>
                        Этот аргумент представляет последовательность инструкций
                        <literal>key1=value1, key2=value2</literal>,..., где
                        <literal>key1</literal>, <literal>key2</literal>,...
                        могут быть одним из следующих:
                        <varname>arfact</varname>, <varname>rect</varname>,
                        <varname>strf</varname> (см. ниже).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arfact</term>
                <listitem>
                    <para>
                        необязательный аргумент типа <literal>real</literal>,
                        который даёт масштабирующий коэффициент для отображения
                        остриё стрелки на графике (значение по умолчанию равно
                        <literal>1.0</literal>).
                    </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", которое имеет то же
                        самое значение, что и параметр <varname>strf</varname>
                        функции <function>plot2d</function>. Первый символ
                        <literal>x</literal> не имеет значения для <function>champ</function>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            <literal>champ(…)</literal> строит поле двумерных веторов с помощью стрелок.
        </para>
        <para>
            По умолчанию все стрелки одного цвета, а их длина пропорционально локальной интенсивности
            поля (норма векторов). Кроме того, все длины нормированы в соответствии с самой длинной стрелкой.
        </para>
        <para>
            Когда установлено <literal>gce().colored = "on"</literal>,
            каждая стрелка становится настолько длинной, насколько это возможно в её ячейке, и её
            цвет соответствует локальной интенсивности поля.
        </para>
        <para>
            После вызова <literal>champ(…)</literal>, <literal>gce()</literal>
            возвращает дескриптор поля стрелок типа <literal>Champ</literal>,
            чьи <link linkend="champ_properties">свойства</link> могут быть далее обработаны.
        </para>
        <para>
            Введите команду <literal>champ()</literal>, чтобу увидеть пример.
        </para>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
x = -4:6;
X = ndgrid(x);
[fx, fy] =  (rand(X)-0.5, rand(X)-0.5);

clf
gcf().color_map = jet(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)
colorbar

// Интенсивность поля = цвету, + расширенные пределы
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 = jet(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"" (по умолчанию)", "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 = jet(100);
colorbar
]]></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 = jet(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="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>
