[interpolation] mesh2d gateway introduced
[scilab.git] / scilab / modules / interpolation / help / en_US / mesh2d.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) 2008 - INRIA
5  * Copyright (C) 2018 - St├ęphane MOTTELET
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program. *
13  *
14  -->
15 <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" xml:lang="en" 
16 xmlns:scilab="http://www.scilab.org"
17 xml:id="mesh2d">
18   <info>
19     <pubdate>$LastChangedDate$</pubdate>
20   </info>
21   <refnamediv>
22     <refname>mesh2d</refname>
23     <refpurpose>Triangulation of n points in the plane</refpurpose>
24   </refnamediv>
25   <refsynopsisdiv>
26     <title>Calling Sequence</title>
27     <synopsis>
28 triEdges = mesh2d(x, y)
29 [triEdges, bdy] = mesh2d(x, y)
30 triEdges = mesh2d(x, y, bdy)</synopsis>
31   </refsynopsisdiv>
32   <refsection>
33     <title>Parameters</title>
34     <variablelist>
35       <varlistentry>
36         <term>x</term>
37         <listitem>
38           <para>real vector</para>
39         </listitem>
40       </varlistentry>
41       <varlistentry>
42         <term>y</term>
43         <listitem>
44           <para>real vector</para>
45         </listitem>
46       </varlistentry>
47       <varlistentry>
48         <term>bdy</term>
49         <listitem>
50           <para>integer vector</para>
51         </listitem>
52       </varlistentry>
53       <varlistentry>
54         <term>triEdges</term>
55         <listitem>
56           <para>integer matrix</para>
57         </listitem>
58       </varlistentry>
59     </variablelist>
60   </refsection>
61   <refsection>
62     <title>Description</title>
63     <para>
64     <literal>mesh2d</literal> computes a triangulation of <literal>n</literal> points in the plane with coordinates given by vectors<literal>x,y</literal>. It 
65      returns a matrix <literal>triEdges</literal> of size <literal>[3,nbt]</literal> where <literal>triEdges(:,i)</literal> gives the vertices numbers of triangle <literal>#i</literal> and <literal>nbt</literal> is the number of triangles.
66   </para>
67   <para>
68     When <literal>bdy</literal> is given as an input parameter this vector defines the
69     boundary and contains the indices of edges belonging to it, grouped by successive connected components. Each component is positively oriented, i.e. successive <literal>bdy(i:i+1)</literal> segments have the interior of the domain to their left. Hence, for a simply connected domain, the boundary is given counterclockwise, and eventual holes are always given clockwise.
70     Each connected component must be closed and is represented by the vector <literal>[i1,..,i_nc]</literal> such that 
71     <literal>i1 == i_nc</literal>. 
72   </para>
73   <para>
74     When <literal>bdy</literal> is given as an output parameter the boundary is computed prior to the triangulation as the convex hull of input points <literal>x,y</literal> and is returned in <literal>bdy</literal> with the same convention as above, i.e. counterclockwise sucessive vertices numbers.
75   </para>
76
77     <para>Possible error cases are the following:
78       <varlistentry>
79     <listitem>all nodes are collinear,</listitem>
80     <listitem>some points are identical,</listitem>
81     <listitem>wrong boundary array,</listitem>
82     <listitem>crossed boundary,</listitem>
83     <listitem>wrong orientation of the boundary,</listitem>
84     <listitem>size limitation,</listitem>
85     <listitem>an interior point is too close to the boundary,</listitem>
86     <listitem>an interior point is on the boundary,</listitem>
87   </varlistentry>
88   </para>
89   </refsection>
90   <refsection>
91     <title>Warning</title>
92     <para>The triangulation computed by <literal>mesh2d</literal> is not garanteed to be a Delaunay triangulation of points <literal>(x,y)</literal>.
93     </para>
94   </refsection>
95   <refsection>
96     <title>Examples</title>
97     <programlisting role="example"><![CDATA[ 
98 function displayTri(X, Y, Tr)
99   plot(0,0,rect=[-1 -1 2 2])
100   [m, n] = size(Tr);
101   xpols = matrix(X(Tr), m, n); 
102   ypols = matrix(Y(Tr), m, n);
103   xfpolys(xpols, ypols, [n/4:n/4+n-1]);
104 endfunction 
105
106 r1 = 1;
107 n1 = 20;
108 u = linspace(2*%pi, 0, n1);
109 xc1 = r1*cos(u(1:$-1));
110 yc1 = r1*sin(u(1:$-1));
111 bdy1 = [1:n1-1, 1];
112
113 r2 = 2;
114 n2 = 40;
115 v = linspace(0, 2*%pi, n2);
116 xc2 = r2*cos(v(1:$-1));
117 yc2 = r2*sin(v(1:$-1));
118 bdy2 = n1-1+[1:n2-1, 1];
119
120 xr = (rand(1, 100)-.5)*2*r2;
121 yr = (rand(1, 100)-.5)*2*r2;
122 r = sqrt(xr.^2+yr.^2);
123
124 clf
125 gcf().color_map = rand(400, 3); 
126 gcf().position(4)=300
127
128 // [t, bdy] = mesh2d(x, y) syntax
129 subplot(1, 2, 1)
130 k = find(r < = r2);
131 [t, bdy] = mesh2d(xr(k), yr(k));
132 displayTri(xr(k), yr(k), t)
133 plot(xr(k(bdy)), yr(k(bdy)),"-ok","thickness",2)
134 xtitle("[triEdges, bdy] = mesh2d(x, y)")
135 isoview
136
137
138 // t = mesh2d(x, y, bdy) syntax
139 subplot(1, 2, 2)
140 k = find((r > =  r1) & (r < =  r2));
141 x = [xc1 xc2 xr(k)];
142 y = [yc1 yc2 yr(k)];
143 t = mesh2d(x, y, [bdy1 bdy2]);
144 displayTri(x, y, t)
145 plot(x(bdy1), y(bdy1),"-ok","thickness",2)
146 plot(x(bdy2), y(bdy2),"-ok","thickness",2)
147 xtitle("triEdges = mesh2d(x, y, bdy)")
148 isoview
149  ]]></programlisting>
150  <scilab:image>
151 function displayTri(X, Y, Tr)
152   plot(0,0,rect=[-1 -1 2 2])
153   [m, n] = size(Tr);
154   xpols = matrix(X(Tr), m, n); 
155   ypols = matrix(Y(Tr), m, n);
156   xfpolys(xpols, ypols, [n/4:n/4+n-1]);
157 endfunction 
158
159 r1 = 1;
160 n1 = 20;
161 u = linspace(2*%pi, 0, n1);
162 xc1 = r1*cos(u(1:$-1));
163 yc1 = r1*sin(u(1:$-1));
164 bdy1 = [1:n1-1, 1];
165
166 r2 = 2;
167 n2 = 40;
168 v = linspace(0, 2*%pi, n2);
169 xc2 = r2*cos(v(1:$-1));
170 yc2 = r2*sin(v(1:$-1));
171 bdy2 = n1-1+[1:n2-1, 1];
172
173 xr = (rand(1, 100)-.5)*2*r2;
174 yr = (rand(1, 100)-.5)*2*r2;
175 r = sqrt(xr.^2+yr.^2);
176
177 clf
178 gcf().color_map = rand(400, 3); 
179 gcf().position(4)=300
180
181 // [t, bdy] = mesh2d(x, y) syntax
182 subplot(1, 2, 1)
183 k = find(r &lt; = r2);
184 [t, bdy] = mesh2d(xr(k), yr(k));
185 displayTri(xr(k), yr(k), t)
186 plot(xr(k(bdy)), yr(k(bdy)),"-ok","thickness",2)
187 xtitle("[triEdges, bdy] = mesh2d(x, y)")
188 isoview
189
190
191 // t = mesh2d(x, y, bdy) syntax
192 subplot(1, 2, 2)
193 k = find((r &gt; =  r1) &amp; (r &lt; =  r2));
194 x = [xc1 xc2 xr(k)];
195 y = [yc1 yc2 yr(k)];
196 t = mesh2d(x, y, [bdy1 bdy2]);
197 displayTri(x, y, t)
198 plot(x(bdy1), y(bdy1),"-ok","thickness",2)
199 plot(x(bdy2), y(bdy2),"-ok","thickness",2)
200 xtitle("triEdges = mesh2d(x, y, bdy)")
201 isoview
202
203
204
205  </scilab:image>
206   </refsection>
207   <refsection>
208     <title>References</title>
209     <para><literal>mesh2d</literal> was previously part of the <literal>metanet</literal> ATOMS module.
210     </para>
211   </refsection>
212 </refentry>