<?xml version="1.0" encoding="UTF-8"?>
<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="fr" xml:id="xarrows">
    <refnamediv>
        <refname>xarrows</refname>
        <refpurpose>dessine un ensemble de flèches en 2D ou 3D.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Séquence d'appel</title>
        <synopsis>xarrows(nx, ny [,nz] [,arsize, color])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Paramètres</title>
        <variablelist>
            <varlistentry>
                <term>nx, ny, nz</term>
                <listitem>
                    <para>valeurs réelles ou matrices de même taille.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arsize</term>
                <listitem>
                    <para>
                        réel, taille des têtes des flèches. La valeur par défaut peut être obtenue  en prenant <varname>arsize</varname> = -1.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>color</term>
                <listitem>
                    <para>
                        matrice ou scalaire. Si <varname>color</varname> est positif il donne la couleur de ligne pour toutes les flèches. S'il est négatif  la couleur courante est utilisé. S'il est un vecteur, <literal>color(i)</literal> donne la couleur pour la flèche <literal>i</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <function>xarrows</function> dessine un ensemble de flèches données par <varname>nx</varname>, <varname>ny</varname> et <varname>nz</varname>.
            Si <varname>nz</varname> n'est pas spécifié, alors les flèches sont dessinées en 2D.
            Si <varname>nx</varname>, <varname>ny</varname> et <varname>nz</varname> sont des vecteurs,
            la flèche numéro i est définie par
            <literal>(nx(i),ny(i),nz(i))--&gt;(nx(i+1),ny(i+1),nz(i+1))</literal>.
            Si <varname>nx</varname>, <varname>ny</varname> et <varname>nz</varname> sont des matrices :
        </para>
        <programlisting role=""><![CDATA[
nx = [xi_1 xi_2 ...; xf_1 xf_2 ...]
ny = [yi_1 yi_2 ...; yf_1 yf_2 ...]
nz = [zi_1 zi_2 ...; zf_1 zf_2 ...]
 ]]></programlisting>
        <para>
            la flèche numéro <literal>k</literal> est définie par <literal>(xi_k,yi_k,zi_k)--&gt;(xf_k,yf_k,zf_k)</literal>.
        </para>
        <para>
            <function>xarrows</function> utilise l'échelle graphique courante, qui peut être définie par appel préalable d'une fonction graphique de haut niveau comme <function>plot2d</function>.
        </para>
    </refsection>
    <refsection>
        <title>Exemples</title>
        <programlisting role="example"><![CDATA[
x = 2*%pi*(0:7)/8
x1 = [sin(x); 9*sin(x)];
y1 = [cos(x); 9*cos(x)];
plot2d([-10,10], [-10,10], [-1,-1], "022")
gca().clip_state = "clipgrf";
xarrows(x1, y1, -1, [1:7,9]) //8-th color is white
gca().clip_state = "off";
 ]]></programlisting>

        <scilab:image>
            x = 2*%pi*(0:7)/8
            x1 = [sin(x); 9*sin(x)];
            y1 = [cos(x); 9*cos(x)];
            plot2d([-10,10], [-10,10], [-1,-1], "022")
            gca().clip_state = "clipgrf";
            xarrows(x1, y1, -1, [1:7,9])
            gca().clip_state = "off";
        </scilab:image>
        <programlisting role="example"><![CDATA[
N = 100;
zi = linspace(-1,2,N);
zf = zi;
theta = (zi - min(zi))/(max(zi)-min(zi))*720;
xi = zeros(1,N);  xf = cosd(theta);
yi = zeros(1,N);  yf = sind(theta);
clf, plot3d([-1 1 1 1],[-1 -1 -1 1],[-1 -1 2 2])
xarrows([xi;xf],[yi;yf],[zi;zf],0.7, 32*rand(1,N))
 ]]></programlisting>
        <scilab:image>
            N = 100;
            zi = linspace(-1,2,N);
            zf = zi;
            theta = (zi - min(zi))/(max(zi)-min(zi))*720;
            xi = zeros(1,N);  xf = cosd(theta);
            yi = zeros(1,N);  yf = sind(theta);
            clf, plot3d([-1 1 1 1],[-1 -1 -1 1],[-1 -1 2 2])
            xarrows([xi;xf],[yi;yf],[zi;zf],0.7, 32*rand(1,N))
        </scilab:image>
    </refsection>
    <refsection>
        <title>Historique</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>Les flèches peuvent être dessinées en 3D.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
