Doc: correction anglais Nicole
[delaunay.git] / doc / luamesh-doc.tex
1 % luamesh: compute and draw meshes with lua, luamplib and tikz
2 %
3 % Originally written by Maxime Chupin <mc@melusine.eu.org>,
4 % 2010.
5 %
6 % Distributed under the terms of the GNU free documentation licence:
7 % http://www.gnu.org/licenses/fdl.html
8 % without any invariant section or cover text.
9
10 \documentclass{lltxdoc}
11 \usepackage{tcolorbox}
12 \usepackage{xargs}
13 \usepackage{enumitem}
14 \usepackage[tikz]{bclogo}
15 \usepackage{wrapfig}
16 \title{\Verb+luamesh+: compute and draw meshes with \lualatex}
17 \author{Maxime Chupin \email{mc@melusine.eu.org}}
18 \date{\today}
19
20
21 \definecolor{darkred}{rgb}{0.8,0.1,0.1}
22
23
24 \newcommand*\commande{\noindent\hspace{-30pt}%
25 \SaveVerb[aftersave={%
26 \UseVerb{Vitem}
27 }%
28 ]{Vitem}}
29
30 \newcommand*\textme[1]{\textcolor{black}{\rmfamily\textit{#1}}}
31 \newcommand*\meta[1]{% % meta
32 \textme{\ensuremath{\langle}#1\ensuremath{\rangle}}}
33 \newcommand*\optstar{% % optional star
34 \meta{\ensuremath{*}}\xspace}
35 \DefineShortVerb{\|}
36
37 \setlength{\fboxsep}{2pt}
38 \fvset{%
39 codes={\catcode`\«\active \catcode`\×\active },
40 defineactive={\makefancyog\makefancytimes},
41 formatcom=\color{darkred},
42 frame=single
43 }
44 % rendre «...» équivalent à \meta{...}
45 {\catcode`\«\active
46 \newcommandx\makefancyog[0][addprefix=\global]{%
47 \def«##1»{\meta{##1}}}}
48 % rendre × équivalent à \optstar
49 {\catcode`\×\active
50 \newcommandx\makefancytimes[0][addprefix=\global]{%
51 \def×{\optstar{}}}}
52
53
54 \tcbuselibrary{listings,breakable}
55
56 \definecolor{vert}{rgb}{0.1,0.4,0.1}
57 \definecolor{bleu}{rgb}{0.1,0.1,0.4}
58 \lstset{
59 numberstyle=\footnotesize\color{vert},
60 keywordstyle=\ttfamily\bfseries\color{blue},
61 basicstyle=\ttfamily\footnotesize,
62 commentstyle=\itshape\color{vert},
63 stringstyle=\ttfamily,
64 showstringspaces=false,
65 language=[LaTeX]TeX,
66 breaklines=true,
67 breakindent=30pt,
68 defaultdialect=[LaTeX]TeX,
69 morekeywords={buildMeshBW,buildMeshBWinc,drawPointsMesh,
70 drawPointsMeshinc, meshAddPointBW, meshAddPointBWinc}% frame=tb
71 }
72
73 \lstdefinelanguage{lua}
74 {morekeywords={for,end,function,do,if,else,elseif,then,
75 tex.print,tex.sprint,io.read,io.open,string.find,string.explode,require},
76 morecomment=[l]{--},
77 morecomment=[s]{--[[}{]]},
78 morestring=[b]''
79 }
80
81 \newtcblisting{Exemple}{%
82 arc=0pt,outer arc=0pt,
83 colback=red!2!white,
84 colframe=red!75!black,
85 breakable,
86 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
87 3pt, toptitle=3pt,
88 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
89 0pt, bottomrule at break = 0pt,
90 listing options={breaklines},
91 }
92
93 \newtcblisting{commandshell}{colback=black,colupper=white,colframe=black,
94 arc=0pt,
95 listing only,boxsep=0pt,listing
96 options={style=tcblatex,language=sh},
97 every listing line={\textcolor{red}{\small\ttfamily\bfseries user \$> }}}
98
99 \newtcblisting{latexcode}{
100 arc=0pt,outer arc=0pt,
101 colback=red!2!white,
102 colframe=red!75!black,
103 breakable,
104 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
105 3pt, toptitle=3pt,
106 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
107 0pt, bottomrule at break = 0pt,
108 listing only,boxsep=0pt,listing
109 options={breaklines}
110 }
111
112
113 \newcommand\luamesh{\Verb+luamesh+\xspace}
114
115 \newenvironment{optionsenum}[1][]
116 {\begin{description}[font=\color{darkred}\ttfamily]}
117 {\end{description}}
118
119 \newenvironment{warning}{%
120 \setlength{\logowidth}{24pt}
121 \tcbset{%
122 arc=0pt,outer arc=0pt,colback=gray!10!white,colframe=gray!60!white,
123 boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle = 3pt, toptitle=3pt,
124 boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt}
125 \medskip
126 \begin{tcolorbox}%
127 \begin{wrapfigure}[2]{L}{17pt}%
128 % \raisebox{-5pt}{
129 \vspace*{-0.55cm}
130 \bcinfo
131 % }%
132 \end{wrapfigure}
133 }%
134 {\end{tcolorbox}\medskip}
135
136
137 \begin{document}
138 %% === Page de garde ===================================================
139 \thispagestyle{empty}
140 \begin{tikzpicture}[remember picture, overlay]
141 \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
142 \includegraphics{fond.pdf}%
143 };
144 \end{tikzpicture}%
145
146 \noindent
147 \includegraphics{luamesh-title}\\
148 {\large compute and draw meshes with \lualatex}\\[1cm]
149 \parbox{0.6\textwidth}{
150 \meshAddPointBW[
151 mode=ext,step=badtriangles,
152 colorNew =green!20!red,
153 colorBack=red!10,
154 colorCircle = blue,
155 bbox = show,
156 colorBbox = black!30
157 ]
158 {meshgarde.txt}{7}
159 }\hfill
160 \parbox{0.4\textwidth}{\Large\raggedleft
161 \textbf{Contributor}\\
162 Maxime \textsc{Chupin}
163 }
164 \vfill
165 \begin{center}
166 Version 0.1, 25 novembre 2016\\
167 \url{http://melusine.eu.org/syracuse/G/delaunay/}
168 \end{center}
169 %% == Page de garde ====================================================
170 \newpage
171
172 \maketitle
173
174 \begin{abstract}
175 The package \Verb|luamesh| allows to compute and draw 2D Delaunay
176 triangulation. The algorithm is written with lua, and depending on the
177 choice of the ``engine'', the drawing is done by MetaPost (with
178 \Verb|luamplib|) or by \Verb|tikz|.
179
180 The Delaunay triangulation algorithm is the Bowyer and Watson
181 algorithm. Several macros are provided to draw the global mesh, the
182 set of points, or a particular step of the algorithm.
183 \end{abstract}
184
185 I would like to thank Jean-Michel Sarlat, who hosts the development
186 with a git project on the \Verb+melusine+ machine:
187 \begin{center}
188 \url{https://melusine.eu.org/syracuse/G/delaunay/}
189 \end{center}
190 I would also like to thank the first user, an intensive
191 \emph{test} user, and a very kind English corrector: Nicole Spillane.
192
193 \section{Installation}
194
195
196 Of course, you can just put the two files \Verb+luamesh.lua+ and
197 \Verb+luamesh.sty+ in the working directory, but this is not
198 recommended.
199
200
201 \subsection{With \TeX live and Linux or Mac OSX}
202
203 To install \luamesh with \TeX live, you have to create the local
204 \Verb+texmf+ directory in your \Verb+home+.
205
206 \begin{commandshell}
207 mkdir ~/texmf
208 \end{commandshell}
209
210 Then place the files in the correct directories. First, the
211 \Verb+luamesh.sty+ file must be in the directory:
212 \begin{center}
213 \Verb+~/texmf/tex/latex/luamesh/+
214 \end{center}
215 and secondly, the \Verb+luamesh.lua+ must be in the directory:
216 \begin{center}
217 \Verb+~/texmf/scripts/luamesh/+
218 \end{center}
219
220 Once you have done this, \luamesh can be included in your document
221 with
222 \begin{latexcode}
223 \usepackage{luamesh}
224 \end{latexcode}
225
226 \subsection{With Mik\TeX{} and Windows}
227
228 We do not know these two systems, so we refer to the
229 documentation for integrating local additions to Mik\TeX:
230 \begin{center}
231 \url{http://docs.miktex.org/manual/localadditions.html}
232 \end{center}
233
234
235 \subsection{A \lualatex package}
236
237 If you want to use this package, you must compile your document with
238 \Verb+lualatex+:
239
240 \begin{commandshell}
241 lualatex mylatexfile.tex
242 \end{commandshell}
243
244
245 \subsection{Dependencies}
246
247 This package is built upon two main existing packages to draw the
248 triangulations :
249 \begin{enumerate}
250 \item \Verb+luamplib+ to use MetaPost via the \luatex library
251 \Verb+mplib+;
252 \item and \Verb+tikz+.
253 \end{enumerate}
254 We will see how to choose between these two \emph{drawing engines}.
255
256 Moreover, the following packages are necessary:
257 \begin{enumerate}
258 \item \Verb+xkeyval+ to manage the optional arguments;
259 \item \Verb+xcolor+ to use colors (needed by \Verb+luamplib+);
260 \item \Verb+ifthen+ to help the programming with \TeX.
261 \end{enumerate}
262
263
264 \section{The Basic Macros}
265
266 Let us recall that this package provides macros to draw two
267 dimensional triangulations (or meshes).
268
269 \subsection{Draw a Complete Mesh}\label{sec:buildMesh}
270
271 \commande|\buildMeshBW[«options»]{«list of points» or «file name»}|\medskip
272
273 This macro produces the Delaunay triangulation (using the Bowyer and
274 Watson algorithm) of the given \meta{list of points}. The list of
275 points must be given in the following way :
276 \begin{center}
277 \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
278 \end{center}
279
280 \begin{Exemple}
281 \buildMeshBW{(0.3,0.3);(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}
282 \end{Exemple}
283
284 \subsubsection{The Options}
285
286 There are several options to customize the drawing.
287 \begin{optionsenum}
288 \item[mode = int (default) \textme{or} ext:] this option allows to
289 use either the previously described set of points in the argument, or
290 a file, containing, line by line (2 columns), the points. Such a
291 file looks like :
292 \begin{verbatim}
293 x1 y1
294 x2 y2
295 x3 y3
296 ...
297 xn yn
298 \end{verbatim}
299 \item[bbox = none (default) \textme{or} show:] this option allows to draw the
300 added points to form a \emph{bounding box}\footnote{The bounding
301 box is defined by four points place at 15\% around the box
302 defined by $(x_{\min},y_{\min})$, $(x_{\min},y_{\max})$,
303 $(x_{\max},y_{\max})$, and $(x_{\min},y_{\max})$. It is used by
304 the algorithm and will be computed in any case.} and the corresponding
305 triangulation. By default, these triangles are removed at the end of
306 the algorithm.
307 \item[color = \meta{value} (default: black):] The color of the
308 drawing.
309 \item[colorBbox = \meta{value} (default: black):] The color of the
310 drawing for the elements (points and triangles) belonging to the
311 bounding box.
312 \item[print = none (default) \textme{or} points:] To label the vertices of the
313 triangulation. This also adds a \emph{dot} at each vertex.
314 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
315 label the vertices of the triangulation. It is included in the math
316 mode delimiters \Verb+$...$+. The bounding box points are labeled
317 with numbers 1 to 4 and with a star exponent.
318 \item[tikz (boolean, default:false):] By default, this boolean is set
319 to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
320 the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
321 engine}.
322 \item[scale = \meta{value} (default: 1cm):] The scale option defines
323 the scale at which the picture is drawn (the same for both
324 axes). It must contain the unit of length (cm,
325 pt, etc.).
326 \end{optionsenum}
327
328 To illustrate the options, let us show you an example. We consider a
329 file \Verb+mesh.txt+:
330 \begin{verbatim}
331 0.3 0.3
332 1.5 1
333 4 0
334 4.5 2.5
335 1.81 2.14
336 2.5 0.5
337 2.8 1.5
338 \end{verbatim}
339 \begin{Exemple}
340 \buildMeshBW[%
341 tikz,
342 mode = ext,
343 bbox = show,
344 color = red,
345 colorBbox = blue!30,
346 print = points,
347 meshpoint = x,
348 scale = 1.3cm,
349 ]{mesh.txt}
350 \end{Exemple}
351
352 \begin{warning}
353 The drawing engine is not very relevant here, but it is useful to
354 understand how the drawing is made. However, the engine will be
355 relevant to
356 the so called \emph{inc} macros (section~\ref{sec:inc}), for adding
357 code before and after the one generated by
358 \luamesh.
359 \end{warning}
360
361 \subsection{Draw the Set of Points}
362
363 \commande|\drawPointsMesh[«options»]{«list of points» or «file name»}|\medskip
364
365 With the \Verb+\drawPointsMesh+, we plot the set of (user chosen) points from
366 which the Bowyer and Watson algorithm computes the triangulation.
367
368 The use of this macro is quite similar to
369 \Verb+\buildMeshBW+. Here is an example of the basic uses.
370 \begin{Exemple}
371 \drawPointsMesh{(0.3,0.3);(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}
372 \end{Exemple}
373
374
375 \subsubsection{The Options}
376
377 There are several options (exactly the same as for the
378 \Verb+\buildMeshBW+) to customize the drawing.
379 \begin{optionsenum}
380 \item[mode = int (default) \textme{or} ext:] this option allows to
381 use either the previously described set of points as the argument, or
382 a file, containing, line by line (2 columns), the points. Such a
383 file looks like :
384 \begin{verbatim}
385 x1 y1
386 x2 y2
387 x3 y3
388 ...
389 xn yn
390 \end{verbatim}
391 \item[bbox = none (default) \textme{or} show:] this option allows to draw the
392 added points to form a \emph{bounding box} and the corresponding
393 triangulation. By default, these triangles are removed at the end of
394 the algorithm. \emph{Here, because we plot only the vertices of the
395 mesh, there are no triangles, only dots.}
396 \item[color = \meta{value} (default: black):] The color of the
397 drawing.
398 \item[colorBbox = \meta{value} (default: black):] The color of the
399 drawing for the elements (points and triangles) belonging to the
400 bounding box.
401 \item[print = none (default) \textme{or} points:] To label the vertices of the
402 triangulation. This also adds a \emph{dot} at each vertex. Without
403 label, there is still the dot.
404 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
405 label the vertices of the triangulation. It is included in the math
406 mode delimiters \Verb+$...$+. The bounding box points are labeled
407 with numbers 1 to 4 and with a star exponent.
408 \item[tikz (boolean, default:false):] By default, this boolean is set
409 to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
410 the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
411 engine}.
412 \item[scale = \meta{value} (default: 1cm):] The scale option defines
413 the scale at which the picture is drawn (the same for both
414 axes). It must contain the unit of length (cm,
415 pt, etc.).
416 \end{optionsenum}
417 With the same external mesh point file presented in
418 section~\ref{sec:buildMesh}, we illustrate the different options.
419
420 \begin{Exemple}
421 \drawPointsMesh[%
422 tikz,
423 mode = ext,
424 bbox = show,
425 color = blue,
426 colorBbox = red,
427 print = points,
428 meshpoint = y,
429 scale = 1.3cm,
430 ]{mesh.txt}
431 \end{Exemple}
432
433
434 \subsection{Draw a Step of the Bowyer and Watson Algorithm}
435
436 \commande|\meshAddPointBW[«options»]{«list of points» or «file name»}{«point» or «number of line»}|\medskip
437
438 This command allows to plot the steps within the addition of a
439 point in a Delaunay triangulation, by the Bowyer and Watson
440 algorithm.
441
442 This macro produces the Delaunay triangulation (using the Bowyer and
443 Watson algorithm) of the given \meta{list of points} and shows a step
444 of the algorithm when the \meta{point} is added. The list of
445 points must be given in the following way:
446 \begin{center}
447 \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
448 \end{center}
449 and the point is of the form \verb+(x,y)+. The \meta{file name}
450 and \meta{number of line} will be explained in the option
451 description.
452
453 One can use the macro as fallows:
454 \begin{Exemple}
455 \meshAddPointBW[step=badtriangles]{(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}{(2.2,1.8)}
456 \meshAddPointBW[step=cavity]{(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}{(2.2,1.8)}
457 \meshAddPointBW[step=newtriangles]{(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}{(2.2,1.8)}
458 \end{Exemple}
459 The default value for \Verb+step+ is
460 \Verb+badtriangles+. Consequently, the first
461 line is equivalent to
462 \begin{latexcode}
463 \meshAddPointBW{(1.5,1);(4,0);(4.5,2.5);(1.81,2.14);(2.5,0.5);(2.8,1.5)}{(2.2,1.8)}
464 \end{latexcode}
465
466 \subsubsection{The Options}
467
468 There are several options (some of them are the same as for
469 \Verb+\buildMeshBW+) to customize the drawing.
470 \begin{optionsenum}
471 \item[mode = int (default) \textme{or} ext:] this option allows to
472 use either the previously described set of point in the first
473 argument, or
474 a file containing, line by line (2 columns), the points. Such a
475 file looks like :
476 \begin{verbatim}
477 x1 y1
478 x2 y2
479 x3 y3
480 ...
481 xn yn
482 \end{verbatim}
483 For the second argument of the macro, if we are in the
484 \Verb+mode = ext+, the argument must be the \emph{line number} of the file
485 corresponding to the point we want to add. The algorithm will stop the
486 line before to build the initial triangulation for which it will add
487 the point corresponding to the line. The subsequent lines in the file are
488 ignored.
489 \item[bbox = none (default) \textme{or} show:] this option allows to draw the
490 added points to form a \emph{bounding box} and the corresponding
491 triangulation. By default, these triangles are removed at the end of
492 the algorithm.
493 \item[color = \meta{value} (default: black):] The color of the
494 drawing.
495 \item[colorBbox = \meta{value} (default: black):] The color of the
496 drawing for the elements (points and triangles) belonging to the
497 bounding box.
498 \item[colorNew = \meta{value} (default: red):] The color of the
499 drawing of the ``new'' elements which are the point to add, the
500 polygon of the cavity, and the new triangles.
501 \item[colorBack = \meta{value} (default: black!20):] The color for the
502 filling of the region concerned by the addition of the new point.
503 \item[colorCircle = \meta{value} (default: green):] The color for
504 the circumcircle of the triangles containing the point to add.
505 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
506 label the vertices of the triangulation. It is included in the math
507 mode delimiters \Verb+$...$+. The bounding box points are labeled
508 with numbers 1 to 4 and with a star exponent.
509 \item[step = badtriangles (default) \textme{or} cavity \textme{or}
510 newtriangles:] To choose the step we want to draw, corresponding to
511 the steps of the Bowyer and Watson algorithm.
512 \item[newpoint = \meta{value} (default: P):] The letter(s) used to
513 label the new point of the triangulation. It is include in the math
514 mode delimiters \Verb+$...$+.
515 \item[tikz (boolean, default:false):] By default, this boolean is set
516 to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
517 the picture. With this option, \Verb+tikz+ is the \textit{drawing
518 engine}.
519 \item[scale = \meta{value} (default: 1cm):] The scale option defines
520 the scale at which the picture is draw (the same for the two
521 axis). It must contain the unit of length (cm,
522 pt, etc.).
523 \end{optionsenum}
524
525 Here is an example of customizing the drawing. First, recall that
526 the external file \Verb+mesh.txt+ is:
527 \begin{verbatim}
528 0.3 0.3
529 1.5 1
530 4 0
531 4.5 2.5
532 1.81 2.14
533 2.5 0.5
534 2.8 1.5
535 \end{verbatim}
536 We draw the addition of the 6th point. The 7th line will be ignored.
537 \begin{Exemple}
538 \meshAddPointBW[
539 tikz,
540 mode = ext,
541 color = blue!70,
542 meshpoint = \alpha,
543 newpoint = y,
544 colorBack=red!10,
545 colorNew = green!50!red,
546 colorCircle = blue,
547 colorBbox = black!20,
548 bbox = show,
549 scale=1.4cm,
550 step=badtriangles]
551 {mesh.txt}{6}
552 \end{Exemple}
553
554 \section{The \emph{inc} Macros}\label{sec:inc}
555
556 The three macros presented in the above sections have complementary
557 macros, with the suffix \Verb+inc+ that allow the user to add code
558 (MetaPost or \Verb+tikz+, depending of the drawing engine) before and
559 after the code generated by \luamesh.
560
561 The three macros are:
562
563 \commande|\buildMeshBWinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip
564
565 \commande|\drawPointsMeshinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip
566
567 \commande|\meshAddPointBWinc[«options»]{«list of points» or «file name»}%|
568
569 \commande| {«point» or «number of line»}{«code before»}{«code after»}|\medskip
570
571 \subsection{With MetaPost}
572
573 We consider the case where the drawing engine is MetaPost (through the
574 \Verb+luamplib+ package).
575
576 We describe the feature taking one macro in example but the mechanism
577 and the possibilities are exactly the same for all the macros.
578
579 When we use the MetaPost drawing engine, the macros previously
580 described produced a code of the form
581 \begin{latexcode}
582 \begin{luamplib}
583
584 \end{luamplib}
585 \end{latexcode}
586
587
588
589 \subsection{With TikZ}
590
591 \section{Gallery of Examples}
592
593 \end{document}
594
595
596
597 %%% Local Variables:
598 %%% flyspell-mode: 1
599 %%% ispell-local-dictionary: "american"
600 %%% End:

Licence Creative Commons Les fichiers de Syracuse sont mis à disposition (sauf mention contraire) selon les termes de la
Licence Creative Commons Attribution - Pas d’Utilisation Commerciale - Partage dans les Mêmes Conditions 4.0 International.