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 triangulation
 176   of Delaunay. The algorithm is written with lua, and depending of the
 177   choice of the ``engine'', the draw 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, 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 Then, I would 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 it 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 we have to files to place 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 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 produce 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 point 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})$.} and the corresponding
 304   triangulation. By default, these triangles are removed at the end of
 305   the algorithm.
 306 \item[color = \meta{value} (default: black):] The color of the
 307   drawing.
 308 \item[colorBbox = \meta{value} (default: black):] The color of the
 309   drawing for the elements (points and triangles) belonging to the
 310   bounding box.
 311 \item[print = none (default) \textme{or} points:] To label the vertices of the
 312   triangulations with an adding dot.
 313 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
 314   label the vertices of the triangulation. It is include in the math
 315   mode delimiters \Verb+$...$+. The bounding box points are labeled
 316   with a star exponent, and numbered from 1 to 4.
 317 \item[tikz (boolean, default:false):] By default, this boolean is set
 318   to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
 319   the picture. With this option, it is \Verb+tikz+ the \textit{drawing
 320     engine}.
 321 \item[scale = \meta{value} (default: 1cm):] The scale option defines
 322   the scale at which the picture is draw (the same for the two
 323   axis). It must contain the unit of length (cm,
 324   pt, etc.).
 325 \end{optionsenum}
 326
 327 To illustrate the options, let us show you an example. We consider a
 328 file \Verb+mesh.txt+:
 329 \begin{verbatim}
 330 0.3    0.3
 331 1.5    1
 332 4      0
 333 4.5    2.5
 334 1.81   2.14
 335 2.5    0.5
 336 2.8    1.5
 337 \end{verbatim}
 338 \begin{Exemple}
 339   \buildMeshBW[%
 340   tikz,
 341   mode = ext,
 342   bbox = show,
 343   color = red,
 344   colorBbox = blue!30,
 345   print = points,
 346   meshpoint = x,
 347   scale = 1.3cm,
 348   ]{mesh.txt}
 349 \end{Exemple}
 350
 351 \begin{warning}
 352 The drawing engine is not here very relevant. But it is useful to
 353 understand how the drawing is made. However, the engine will make sens
 354 for the so called \emph{inc} macros (section~\ref{sec:inc}), where we
 355 will be allowed to add code before and after the generated one by
 356 \luamesh.
 357 \end{warning}
 358
 359 \subsection{Draw the Set of Points}
 360
 361 \commande|\drawPointsMesh[«options»]{«list of points» or «file name»}|\medskip
 362
 363 With the \Verb+\drawPointsMesh+, we plot the set of the points from
 364 which the Browyer and Watson algorithm compute the triangulation.
 365
 366 The use of this macro is quite similar to the
 367 \Verb+\buildMeshBW+. Here is an example of the basic uses.
 368 \begin{Exemple}
 369   \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)}
 370 \end{Exemple}
 371
 372
 373 \subsubsection{The Options}
 374
 375 There are several options (exactly the same that for the
 376 \Verb+\buildMeshBW+)to customize the drawing.
 377 \begin{optionsenum}
 378 \item[mode = int (default) \textme{or} ext:] this option allows to
 379   use either the previously described set of point in the argument, or
 380   a file, containing, line by line (2 columns), the points. Such a
 381   file looks like :
 382 \begin{verbatim}
 383 x1  y1
 384 x2  y2
 385 x3  y3
 386 ...
 387 xn yn
 388 \end{verbatim}
 389 \item[bbox = none (default) \textme{or} show:] this option allows to draw the
 390   added points to form a \emph{bounding box} and the corresponding
 391   triangulation. By default, these triangles are removed at the end of
 392   the algorithm. \emph{Here, because we plot only the vertices of the
 393     mesh, there is no triangles, but only dots.}
 394 \item[color = \meta{value} (default: black):] The color of the
 395   drawing.
 396 \item[colorBbox = \meta{value} (default: black):] The color of the
 397   drawing for the elements (points and triangles) belonging to the
 398   bounding box.
 399 \item[print = none (default) \textme{or} points:] To label the vertices of the
 400   triangulations with an adding dot. Without label, there is a dot.
 401 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
 402   label the vertices of the triangulation. It is include in the math
 403   mode delimiters \Verb+$...$+. The bounding box points are labeled
 404   with a star exponent, and numbered from 1 to 4.
 405 \item[tikz (boolean, default:false):] By default, this boolean is set
 406   to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
 407   the picture. With this option, it is \Verb+tikz+ the \textit{drawing
 408     engine}.
 409 \item[scale = \meta{value} (default: 1cm):] The scale option defines
 410   the scale at which the picture is draw (the same for the two
 411   axis). It must contain the unit of length (cm,
 412   pt, etc.).
 413 \end{optionsenum}
 414 With the same external mesh point file presented in
 415 section~\ref{sec:buildMesh}, we illustrate the different options.
 416
 417 \begin{Exemple}
 418   \drawPointsMesh[%
 419   tikz,
 420   mode = ext,
 421   bbox = show,
 422   color = blue,
 423   colorBbox = red,
 424   print = points,
 425   meshpoint = y,
 426   scale = 1.3cm,
 427   ]{mesh.txt}
 428 \end{Exemple}
 429
 430
 431 \subsection{Draw a Step of the Bowyer and Watson Algorithm}
 432
 433 \commande|\meshAddPointBW[«options»]{«list of points» or «file name»}{«point» or «number of line»}|\medskip
 434
 435 This command allows to plot the different step of the addition of a
 436 point in a Delaunay triangulation, using the Bowyer and Watson
 437 algorithm.
 438
 439 This macro produce the Delaunay triangulation (using the Bowyer and
 440 Watson algorithm) of the given \meta{list of points} and shows a step
 441 of the algorithm when the \meta{point} is added. The list of
 442 points must be given in the following way:
 443 \begin{center}
 444   \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
 445 \end{center}
 446 and the point is of the form \verb+(x,y)+. The \meta{file name}
 447 and \meta{number of line}  will be explained in the option
 448 description.
 449
 450 One can use the macro as fallow:
 451 \begin{Exemple}
 452   \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)}
 453   \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)}
 454   \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)}
 455 \end{Exemple}
 456 The default value for \Verb+step+ is \Verb+badtriangles+. The first
 457 line is then equivalent to
 458 \begin{latexcode}
 459 \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)}
 460 \end{latexcode}
 461
 462 \subsubsection{The Options}
 463
 464 There are several options (some of them are the same as for
 465 \Verb+\buildMeshBW+) to customize the drawing.
 466 \begin{optionsenum}
 467 \item[mode = int (default) \textme{or} ext:] this option allows to
 468   use either the previously described set of point in the argument
 469   number one, or
 470   a file, containing, line by line (2 columns), the points. Such a
 471   file looks like :
 472 \begin{verbatim}
 473 x1  y1
 474 x2  y2
 475 x3  y3
 476 ...
 477 xn yn
 478 \end{verbatim}
 479 For the second argument of the macro, if we are in the
 480 \Verb+mode = ext+, the argument must be the \emph{line number} of the file
 481 corresponding to the point we want to add. The algorithm will stop the
 482 line before to build the initial triangulation for which it will add
 483 the point corresponding to the line. The other lines of the file are
 484 ignored.
 485 \item[bbox = none (default) \textme{or} show:] this option allows to draw the
 486   added points to form a \emph{bounding box} and the corresponding
 487   triangulation. By default, these triangles are removed at the end of
 488   the algorithm.
 489 \item[color = \meta{value} (default: black):] The color of the
 490   drawing.
 491 \item[colorBbox = \meta{value} (default: black):] The color of the
 492   drawing for the elements (points and triangles) belonging to the
 493   bounding box.
 494 \item[colorNew = \meta{value} (default: red):] The color of the
 495   drawing of the ``new'' elements which are the point to add, the
 496   polygon of the cavity, and the new triangles.
 497 \item[colorBack = \meta{value} (default: black!20):] The color for the
 498   filling of the region concerned by the addition of the new point.
 499 \item[colorCircle = \meta{value} (default: green):] The color for
 500   circoncircle of the triangles containing the point to add.
 501 \item[meshpoint = \meta{value} (default: P):] The letter(s) used to
 502   label the vertices of the triangulation. It is include in the math
 503   mode delimiters \Verb+$...$+. The bounding box points are labeled
 504   with a star exponent, and numbered from 1 to 4.
 505 \item[step = badtriangles (default) \textme{or} cavity \textme{or}
 506   newtriangles:] To choose the step we want to draw, corresponding to
 507   the steps of the Bowyer and Watson algorithm.
 508 \item[newpoint = \meta{value} (default: P):] The letter(s) used to
 509   label the new point of the triangulation. It is include in the math
 510   mode delimiters \Verb+$...$+.
 511 \item[tikz (boolean, default:false):] By default, this boolean is set
 512   to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
 513   the picture. With this option, it is \Verb+tikz+ the \textit{drawing
 514     engine}.
 515 \item[scale = \meta{value} (default: 1cm):] The scale option defines
 516   the scale at which the picture is draw (the same for the two
 517   axis). It must contain the unit of length (cm,
 518   pt, etc.).
 519 \end{optionsenum}
 520
 521 Here is an example of customization of the drawing. First, recall that
 522 the external file \Verb+mesh.txt+ is:
 523 \begin{verbatim}
 524 0.3    0.3
 525 1.5    1
 526 4      0
 527 4.5    2.5
 528 1.81   2.14
 529 2.5    0.5
 530 2.8    1.5
 531 \end{verbatim}
 532 We draw the addition of the 6th point. The 7th line will be ignored.
 533 \begin{Exemple}
 534   \meshAddPointBW[
 535   tikz,
 536   mode = ext,
 537   color = blue!70,
 538   meshpoint = \alpha,
 539   newpoint = y,
 540   colorBack=red!10,
 541   colorNew = green!50!red,
 542   colorCircle = blue,
 543   colorBbox = black!20,
 544   bbox = show,
 545   scale=1.4cm,
 546   step=badtriangles]
 547   {mesh.txt}{6}
 548 \end{Exemple}
 549
 550 \section{The \emph{inc} Macros}\label{sec:inc}
 551
 552 The three macros presented in the above sections have complementary
 553 macros, with the suffix \Verb+inc+ that allow the user to add code
 554 (MetaPost or \Verb+tikz+, depending of the drawing engine) before and
 555 after the code generated by \luamesh.
 556
 557 The three macros are:
 558
 559 \commande|\buildMeshBWinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip
 560
 561 \commande|\drawPointsMeshinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip
 562
 563 \commande|\meshAddPointBWinc[«options»]{«list of points» or «file  name»}%|
 564
 565 \commande|                           {«point» or «number of line»}{«code before»}{«code after»}|\medskip
 566
 567 \subsection{With MetaPost}
 568
 569 We consider the case where the drawing engine is MetaPost (through the
 570 \Verb+luamplib+ package).
 571
 572
 573
 574 \subsection{With TikZ}
 575
 576 \section{Gallery of Examples}
 577
 578 \end{document}
 579
 580
 581
 582 %%% Local Variables:
 583 %%% flyspell-mode: 1
 584 %%% ispell-local-dictionary: "american"
 585 %%% End: