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