<?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
 *
 * 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="en" xml:id="xarrows">
    <refnamediv>
        <refname>xarrows</refname>
        <refpurpose>draw a set of arrows in 2D or in 3D.</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>xarrows(nx, ny [,nz] [,arsize, color])</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>nx, ny, nz</term>
                <listitem>
                    <para>real vectors or matrices of same size.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>arsize</term>
                <listitem>
                    <para>
                        a real scalar, size of the arrow head.
                        The default value can be obtained  by
                        setting <varname>arsize</varname> to
                        <literal>-1</literal>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>color</term>
                <listitem>
                    <para>
                        a matrix or scalar. If <varname>color</varname>
                        is a positive scalar it gives the color
                        to use for all arrows. If it is a
                        negative scalar then the current color is
                        used. If it is a vector <literal>color(i)</literal>
                        gives the color to use for arrow <literal>i</literal>.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <function>xarrows</function> draws a set of arrows
            given by <varname>nx</varname>, <varname>ny</varname> and <varname>nz</varname>.
            If <varname>nz</varname> is not given, then the arrows are drawn in 2D.
            If <varname>nx</varname>, <varname>ny</varname> and <varname>nz</varname> are vectors,
            the <literal>i</literal>-th arrow is defined by
            <literal>(nx(i),ny(i),nz(i))--&gt;(nx(i+1),ny(i+1),nz(i+1))</literal>.
            If <varname>nx</varname>, <varname>ny</varname> and <varname>nz</varname> are matrices:
        </para>
        <programlisting role="no-scilab-exec"><![CDATA[
nx=[xi_1 x1_2 ...; xf_1 xf_2 ...]
ny=[yi_1 y1_2 ...; yf_1 yf_2 ...]
nz=[zi_1 z1_2 ...; zf_1 zf_2 ...]
 ]]></programlisting>
        <para>
            the <literal>k</literal>-th arrow is defined by <literal>(xi_k,yi_k,zi_k)--&gt;(xf_k,yf_k,zf_k)</literal>.
        </para>
        <para>
            <function>xarrows</function> uses the current graphics
            scale which can be set by calling a high level
            drawing function such as <function>plot2d</function>.
        </para>
    </refsection>
    <refsection>
        <title>Examples</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>History</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>Arrows can be drawn in 3D.</revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
