scatter with extended polyline properties mark_size, mark_foreground, mark_background
[scilab.git] / scilab / modules / graphics / help / en_US / xsegs.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) 2009 - DIGITEO - Pierre Lando
6  * 
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at    
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <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="xsegs">
15     <refnamediv>
16         <refname>xsegs</refname>
17         <refpurpose>
18             draw unconnected segments
19         </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>
24             xsegs(xv, yv, [style])
25             xsegs(xv, yv, zv,[style])
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>xv, yv, zv</term>
33                 <listitem>
34                     <para>
35                         matrices of the same size. If <varname>zv</varname> is
36                         not specified, a zero vector is used.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>style</term>
42                 <listitem>
43                     <para>
44                         vector or scalar. If <varname>style</varname> is a
45                         positive scalar, it gives the color to use for all
46                         segments. If <varname>style</varname> is a negative
47                         scalar, then current color is used. If <varname>style</varname>
48                         is a vector, then <literal>style(i)</literal> gives the
49                         color to use for segment <literal>i</literal>.
50                     </para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             <function>xsegs</function> draws a set of unconnected segments given
59             by <varname>xv</varname>, <varname>yv</varname> and
60             <varname>zv</varname>. If <varname>xv</varname>,
61             <varname>yv</varname> and <varname>zv</varname> are matrices they
62             are considered as vectors by concatenating their columns. The
63             coordinates of the two points defining a segment are given by two
64             consecutive values of <varname>xv</varname>, <varname>yv</varname>
65             and <varname>zv</varname>:
66         </para>
67         <para>
68             <literal>(xv(i),yv(i),zv(i))--&gt;(xv(i+1),yv(i+1),zv(i+1))</literal>.
69         </para>
70         <para>
71             For instance, using matrices of size <literal>(2,n)</literal>, the
72             segments can be defined by:
73         </para>
74         <programlisting role="no-scilab-exec"><![CDATA[ 
75 xv=[xi_1 xi_2 ...; xf_1 xf_2...]
76 yv=[yi_1 yi_2 ...; yf_1 yf_2...]
77 zv=[zi_1 zi_2 ...; zf_1 zf_2...]
78  ]]></programlisting>
79         <para>
80             and the segments are <literal>(xi_k,yi_k,zi_k)--&gt;(xf_k,yf_k,zf_k)</literal>.
81         </para>
82     </refsection>
83     <refsection>
84         <title>Examples</title>
85         <programlisting role="example"><![CDATA[
86 // 2D example
87 x=2*%pi*(0:9)/10;
88 xv=[sin(x);9*sin(x)];
89 yv=[cos(x);9*cos(x)];
90 plot2d([-10,10],[-10,10],[-1,-1],"022")
91 xsegs(xv,yv,1:10)
92  ]]></programlisting>
93         <scilab:image>
94             x=2*%pi*(0:9)/10;
95             xv=[sin(x);9*sin(x)];
96             yv=[cos(x);9*cos(x)];
97             plot2d([-10,10],[-10,10],[-1,-1],"022")
98             xsegs(xv,yv,1:10)
99         </scilab:image>
100         <programlisting role="example"><![CDATA[
101 // 2D example
102 plot2d([-10,10],[-10,10],[-1,-1],"022")
103 xsegs([9, -9],[9 , -9]) // Draw the line from X(9,9) to Y(-9, -9)
104 xsegs([5, -2],[4 , -1]) // Draw the line from X(5,4) to Y(-2, -1)
105  ]]></programlisting>
106         <scilab:image>
107             plot2d([-10,10],[-10,10],[-1,-1],"022")
108             xsegs([9, -9],[9 , -9]) // Draw the line from X(9,9) to Y(-9, -9)
109             xsegs([5, -2],[4 , -1]) // Draw the line from X(5,4) to Y(-2, -1)
110         </scilab:image>
111         <programlisting role="example"><![CDATA[
112 // 3D example
113 clf();
114 a=gca();
115 a.view="3d";
116 f=gcf();
117 f.color_map=rainbowcolormap(120);
118 alpha=2*%pi*(0:119)/40;
119 xv=[sin(alpha)/2;sin(alpha)/3];
120 yv=[cos(alpha)/2;cos(alpha)/3];
121 zv=[alpha/8;alpha/8];
122 xsegs(xv,yv,zv,1:120);
123 // Now adjust the data_bounds
124 a.data_bounds = [min(xv) min(yv) min(zv); ...
125                  max(xv) max(yv) max(zv)];
126 // We can add an arrow to each segs
127 e = gce();
128 e.arrow_size = 0.4;
129
130  ]]></programlisting>
131         <scilab:image>
132             a=gca();
133             a.view="3d";
134             f=gcf();
135             f.color_map=rainbowcolormap(120);
136             alpha=2*%pi*(0:119)/40;
137             xv=[sin(alpha)/2;sin(alpha)/3];
138             yv=[cos(alpha)/2;cos(alpha)/3];
139             zv=[alpha/8;alpha/8];
140             xsegs(xv,yv,zv,1:120);
141             a.data_bounds = [min(xv) min(yv) min(zv); ...
142             max(xv) max(yv) max(zv)];
143             e = gce();
144             e.arrow_size = 0.4;
145         </scilab:image>
146         
147     </refsection>
148 </refentry>