[delaunay.git] / doc / luamesh-doc.tex

% luamesh: compute and draw meshes with lua, luamplib and tikz
%
% Originally written by Maxime Chupin <mc@melusine.eu.org>,
% 2010.
%
% Distributed under the terms of the GNU free documentation licence:
%   http://www.gnu.org/licenses/fdl.html
% without any invariant section or cover text.

\documentclass{lltxdoc}
\usepackage{tcolorbox}
\usepackage{enumitem}
\usepackage[tikz]{bclogo}
\usepackage{wrapfig}
\usepackage{animate}

\title{\Verb+luamesh+: compute and draw meshes with \lualatex}
\author{Maxime Chupin \email{mc@melusine.eu.org}}
\date{\today}


\definecolor{darkred}{rgb}{0.8,0.1,0.1}


\newcommand*\commande{\noindent\hspace{-30pt}%
  \SaveVerb[aftersave={%
   \UseVerb{Vitem}
  }%
  ]{Vitem}}

\newcommand*\textme[1]{\textcolor{black}{\rmfamily\textit{#1}}}
\newcommand*\meta[1]{% % meta
  \textme{\ensuremath{\langle}#1\ensuremath{\rangle}}}
\newcommand*\optstar{% % optional star
  \meta{\ensuremath{*}}\xspace}
\DefineShortVerb{\|}

\setlength{\fboxsep}{2pt}
\fvset{%
  codes={\catcode`\«\active \catcode`\×\active },
  defineactive={\makefancyog\makefancytimes},
  formatcom=\color{darkred},
  frame=single
}
% rendre «...» équivalent à \meta{...}
{\catcode`\«\active
  \newcommandx\makefancyog[0][addprefix=\global]{%
    \def«##1»{\meta{##1}}}}
% rendre × équivalent à \optstar
{\catcode`\×\active
  \newcommandx\makefancytimes[0][addprefix=\global]{%
    \def×{\optstar{}}}}


\tcbuselibrary{listings,breakable}

\definecolor{vert}{rgb}{0.1,0.4,0.1}
\definecolor{bleu}{rgb}{0.1,0.1,0.4}
\lstset{
  numberstyle=\footnotesize\color{vert},
  keywordstyle=\ttfamily\bfseries\color{blue},
  basicstyle=\ttfamily\footnotesize,
  commentstyle=\itshape\color{vert},
  stringstyle=\ttfamily,
  showstringspaces=false,
  language=[LaTeX]TeX,
  breaklines=true,
  breakindent=30pt,
  defaultdialect=[LaTeX]TeX,
  morekeywords={buildMeshBW,buildMeshBWinc,drawPointsMesh,buildVoronoiBW,buildVoronoiBWinc,
    drawPointsMeshinc, meshAddPointBW,
    meshAddPointBWinc,drawGmsh,drawGmshinc,gmshVoronoi,gmshVoronoiinc}% frame=tb
}

\lstdefinelanguage{lua}
{morekeywords={for,end,function,do,if,else,elseif,then,
    tex.print,tex.sprint,io.read,io.open,string.find,string.explode,require},
  morecomment=[l]{--},
  morecomment=[s]{--[[}{]]},
  morestring=[b]''
}

\newtcblisting{Exemple}{%
  arc=0pt,outer arc=0pt,
  colback=red!2!white,
  colframe=red!75!black,
  breakable,
  boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
  3pt, toptitle=3pt,
  boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
  0pt, bottomrule at break = 0pt,
  listing options={breaklines},
}

\newtcblisting{commandshell}{colback=black,colupper=white,colframe=black,
  arc=0pt,
  listing only,boxsep=0pt,listing
  options={style=tcblatex,language=sh},
  every listing line={\textcolor{red}{\small\ttfamily\bfseries user \$> }}}

\newtcblisting{latexcode}{
  arc=0pt,outer arc=0pt,
  colback=red!2!white,
  colframe=red!75!black,
  breakable,
  boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle =
  3pt, toptitle=3pt,
  boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt, toprule at break =
  0pt, bottomrule at break = 0pt,
  listing only,boxsep=0pt,listing
  options={breaklines}
}


\newcommand\luamesh{\Verb+luamesh+\xspace}

\newenvironment{optionsenum}[1][]
{\begin{description}[font=\color{darkred}\ttfamily]}
  {\end{description}}

\newenvironment{warning}{%
  \setlength{\logowidth}{24pt}
  \tcbset{%
    arc=0pt,outer arc=0pt,colback=gray!10!white,colframe=gray!60!white,
    boxsep=0pt,left=5pt,right=5pt,top=5pt,bottom=5pt, bottomtitle = 3pt, toptitle=3pt,
    boxrule=0pt,bottomrule=0.5pt,toprule=0.5pt}
  \medskip
  \begin{tcolorbox}%
    \begin{wrapfigure}[2]{L}{17pt}%
      % \raisebox{-5pt}{
      \vspace*{-0.55cm}
      \bcinfo
      % }%
    \end{wrapfigure}
  }%
  {\end{tcolorbox}\medskip}

\lstset{moredelim=*[s][\color{red}\rmfamily\itshape]{<}{>}}
\lstset{moredelim=*[s][\color{blue}\rmfamily\itshape]{<<}{>>}}
\usepackage[colorlinks=true]{hyperref}
\begin{document}
%% === Page de garde ===================================================
\thispagestyle{empty}
\begin{tikzpicture}[remember picture, overlay]
  \node[below right, shift={(-4pt,4pt)}] at (current page.north west) {%
    \includegraphics{fond.pdf}%
  };
\end{tikzpicture}%

\noindent
\includegraphics{luamesh-title}\\
{\large compute and draw meshes with \lualatex}\\[1cm]
\parbox{0.6\textwidth}{
  \meshAddPointBW[
  mode=ext,step=badtriangles,
  colorNew =green!20!red,
  colorBack=red!10,
  colorCircle = blue,
  bbox = show,
  colorBbox = black!30
  ]
  {meshgarde.txt}{7}
}\hfill
\parbox{0.4\textwidth}{\Large\raggedleft
  \textbf{Contributor}\\
  Maxime \textsc{Chupin}
}
\vfill
\begin{center}
  Version 0.2, 29 novembre 2016\\
  \url{http://melusine.eu.org/syracuse/G/delaunay/}
\end{center}
%% == Page de garde ====================================================
\newpage

\maketitle

\begin{abstract}
  The package \Verb|luamesh| allows to compute and draw 2D Delaunay
  triangulation. The algorithm is written with lua, and depending on the
  choice of the ``engine'', the drawing is done by MetaPost (with
  \Verb|luamplib|) or by \Verb|tikz|.

  The Delaunay triangulation algorithm is the Bowyer and Watson
  algorithm. Several macros are provided to draw the global mesh, the
  set of points, or a particular step of the algorithm.
\end{abstract}

I would like to thank Jean-Michel Sarlat, who hosts the development
with a git project on the \Verb+melusine+ machine:
\begin{center}
  \url{https://melusine.eu.org/syracuse/G/delaunay/}
\end{center}
I would also like to thank the first user, an intensive
\emph{test} user, and a very kind English corrector: Nicole Spillane.

\tableofcontents

\section{Installation}


Of course, you can just put the two files \Verb+luamesh.lua+ and
\Verb+luamesh.sty+ in the working directory, but this is not
recommended.


\subsection{With \TeX live and Linux or Mac OSX}

To install \luamesh with \TeX live, you have to create the local
\Verb+texmf+ directory in your \Verb+home+.

\begin{commandshell}
mkdir ~/texmf
\end{commandshell}

Then place the files in the correct directories. First, the
\Verb+luamesh.sty+ file must be in the directory:
\begin{center}
  \Verb+~/texmf/tex/latex/luamesh/+
\end{center}
and secondly, the \Verb+luamesh.lua+ must be in the directory:
\begin{center}
  \Verb+~/texmf/scripts/luamesh/+
\end{center}

Once you have done this, \luamesh can be included in your document
with
\begin{latexcode}
\usepackage{luamesh}
\end{latexcode}

\subsection{With Mik\TeX{} and Windows}

We do not know these two systems, so we refer to the
documentation for integrating local additions to Mik\TeX:
\begin{center}
  \url{http://docs.miktex.org/manual/localadditions.html}
\end{center}


\subsection{A \lualatex package}

If you want to use this package, you must compile your document with
\Verb+lualatex+:

\begin{commandshell}
  lualatex mylatexfile.tex
\end{commandshell}


\subsection{Dependencies}

This package is built upon two main existing packages to draw the
triangulations :
\begin{enumerate}
\item \Verb+luamplib+ to use MetaPost via the \luatex library
  \Verb+mplib+;
\item and \Verb+tikz+.
\end{enumerate}
We will see how to choose between these two \emph{drawing engines}.

Moreover, the following packages are necessary:
\begin{enumerate}
\item \Verb+xkeyval+ to manage the optional arguments;
\item \Verb+xcolor+ to use colors (needed by \Verb+luamplib+);
\item \Verb+ifthen+ to help the programming with \TeX.
\end{enumerate}


\section{The Basic Macros}

Let us recall that this package provides macros to draw two
dimensional triangulations (or meshes).

\subsection{Draw a Complete Mesh}\label{sec:buildMesh}

\commande|\buildMeshBW[«options»]{«list of points» or «file name»}|\medskip

This macro produces the Delaunay triangulation (using the Bowyer and
Watson algorithm) of the given \meta{list of points}. The list of
points must be given in the following way :
\begin{center}
  \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
\end{center}

\begin{Exemple}
  \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)}
\end{Exemple}

\subsubsection{The Options}

There are several options to customize the drawing.
\begin{optionsenum}
\item[mode = int (default) \textme{or} ext:] this option allows to
  use either the previously described set of points in the argument, or
  a file, containing, line by line (2 columns), the points. Such a
  file looks like :
\begin{verbatim}
x1  y1
x2  y2
x3  y3
...
xn yn
\end{verbatim}
\item[bbox = none (default) \textme{or} show:] this option allows to draw the
  added points to form a \emph{bounding box}\footnote{The bounding
    box is defined by four points place at 15\% around the box
    defined by $(x_{\min},y_{\min})$, $(x_{\min},y_{\max})$,
    $(x_{\max},y_{\max})$, and $(x_{\min},y_{\max})$. It is used by
    the algorithm and will be computed in any case.} and the corresponding
  triangulation. By default, these triangles are removed at the end of
  the algorithm.
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[colorBbox = \meta{value} (default: black):] The color of the
  drawing for the elements (points and triangles) belonging to the
  bounding box.
\item[print = none (default) \textme{or} points:] To label the vertices of the
  triangulation. This also adds a \emph{dot} at each vertex.
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is drawn (the same for both
  axes). It must contain the unit of length (cm,
  pt, etc.).
\end{optionsenum}

To illustrate the options, let us show you an example. We consider a
file \Verb+mesh.txt+:
\begin{verbatim}
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
\end{verbatim}
\begin{Exemple}
  \buildMeshBW[%
  tikz,
  mode = ext,
  bbox = show,
  color = red,
  colorBbox = blue!30,
  print = points,
  meshpoint = x,
  scale = 1.3cm,
  ]{mesh.txt}
\end{Exemple}

\begin{warning}
The drawing engine is not very relevant here, but it is useful to
understand how the drawing is made. However, the engine will be
relevant to
the so called \emph{inc} macros (section~\ref{sec:inc}), for adding
code before and after the one generated by
\luamesh.
\end{warning}

\subsection{Draw the Set of Points}

\commande|\drawPointsMesh[«options»]{«list of points» or «file name»}|\medskip

With the \Verb+\drawPointsMesh+, we plot the set of (user chosen) points from
which the Bowyer and Watson algorithm computes the triangulation.

The use of this macro is quite similar to
\Verb+\buildMeshBW+. Here is an example of the basic uses.
\begin{Exemple}
  \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)}
\end{Exemple}


\subsubsection{The Options}

There are several options (exactly the same as for the
\Verb+\buildMeshBW+) to customize the drawing.
\begin{optionsenum}
\item[mode = int (default) \textme{or} ext:] this option allows to
  use either the previously described set of points as the argument, or
  a file, containing, line by line (2 columns), the points. Such a
  file looks like :
\begin{verbatim}
x1  y1
x2  y2
x3  y3
...
xn yn
\end{verbatim}
\item[bbox = none (default) \textme{or} show:] this option allows to draw the
  added points to form a \emph{bounding box} and the corresponding
  triangulation. By default, these triangles are removed at the end of
  the algorithm. \emph{Here, because we plot only the vertices of the
    mesh, there are no triangles, only dots.}
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[colorBbox = \meta{value} (default: black):] The color of the
  drawing for the elements (points and triangles) belonging to the
  bounding box.
\item[print = none (default) \textme{or} points:] To label the vertices of the
  triangulation. This also adds a \emph{dot} at each vertex. Without
  label, there is still the dot.
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is drawn (the same for both
  axes). It must contain the unit of length (cm,
  pt, etc.).
\end{optionsenum}
With the same external mesh point file presented in
section~\ref{sec:buildMesh}, we illustrate the different options.

\begin{Exemple}
  \drawPointsMesh[%
  tikz,
  mode = ext,
  bbox = show,
  color = blue,
  colorBbox = red,
  print = points,
  meshpoint = y,
  scale = 1.3cm,
  ]{mesh.txt}
\end{Exemple}


\subsection{Draw a Step of the Bowyer and Watson Algorithm}

\commande|\meshAddPointBW[«options»]{«list of points» or «file name»}{«point» or «number of line»}|\medskip

This command allows to plot the steps within the addition of a
point in a Delaunay triangulation, by the Bowyer and Watson
algorithm.

This macro produces the Delaunay triangulation (using the Bowyer and
Watson algorithm) of the given \meta{list of points} and shows a step
of the algorithm when the \meta{point} is added. The list of
points must be given in the following way:
\begin{center}
  \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
\end{center}
and the point is of the form \verb+(x,y)+. The \meta{file name}
and \meta{number of line}  will be explained in the option
description.

One can use the macro as fallows:
\begin{Exemple}
  \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)}
  \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)}
  \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)}
\end{Exemple}
The default value for \Verb+step+ is
\Verb+badtriangles+. Consequently, the first
line is equivalent to
\begin{latexcode}
\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)}
\end{latexcode}

\subsubsection{The Options}

There are several options (some of them are the same as for
\Verb+\buildMeshBW+) to customize the drawing.
\begin{optionsenum}
\item[mode = int (default) \textme{or} ext:] this option allows to
  use either the previously described set of point in the first
  argument, or
  a file containing, line by line (2 columns), the points. Such a
  file looks like :
\begin{verbatim}
x1  y1
x2  y2
x3  y3
...
xn yn
\end{verbatim}
For the second argument of the macro, if we are in the
\Verb+mode = ext+, the argument must be the \emph{line number} of the file
corresponding to the point we want to add. The algorithm will stop the
line before to build the initial triangulation for which it will add
the point corresponding to the line. The subsequent lines in the file are
ignored.
\item[bbox = none (default) \textme{or} show:] this option allows to draw the
  added points to form a \emph{bounding box} and the corresponding
  triangulation. By default, these triangles are removed at the end of
  the algorithm.
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[colorBbox = \meta{value} (default: black):] The color of the
  drawing for the elements (points and triangles) belonging to the
  bounding box.
\item[colorNew = \meta{value} (default: red):] The color of the
  drawing of the ``new'' elements which are the point to add, the
  polygon of the cavity, and the new triangles.
\item[colorBack = \meta{value} (default: black!20):] The color for the
  filling of the region concerned by the addition of the new point.
\item[colorCircle = \meta{value} (default: green):] The color for
  the circumcircle of the triangles containing the point to add.
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[step = badtriangles (default) \textme{or} cavity \textme{or}
  newtriangles:] To choose the step we want to draw, corresponding to
  the steps of the Bowyer and Watson algorithm.
\item[newpoint = \meta{value} (default: P):] The letter(s) used to
  label the new point of the triangulation. It is include in the math
  mode delimiters \Verb+$...$+.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+  is the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is draw (the same for the two
  axis). It must contain the unit of length (cm,
  pt, etc.).
\end{optionsenum}

Here is an example of customizing the drawing. First, recall that
the external file \Verb+mesh.txt+ is:
\begin{verbatim}
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
\end{verbatim}
We draw the addition of the 6th point. The 7th line will be ignored.
\begin{Exemple}
  \meshAddPointBW[
  tikz,
  mode = ext,
  color = blue!70,
  meshpoint = \alpha,
  newpoint = y,
  colorBack=red!10,
  colorNew = green!50!red,
  colorCircle = blue,
  colorBbox = black!20,
  bbox = show,
  scale=1.4cm,
  step=badtriangles]
  {mesh.txt}{6}
\end{Exemple}

\section{The \emph{inc} Macros}\label{sec:inc}

The three macros presented in the above sections have complementary
macros, with the suffix \Verb+inc+ that allow the user to add code
(MetaPost or \Verb+tikz+, depending of the drawing engine) before and
after the code generated by \luamesh.

The three macros are:\medskip


\commande|\buildMeshBWinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip

\commande|\drawPointsMeshinc[«options»]{«list of points» or «file name»}{«code before»}{«code after»}|\medskip

\commande|\meshAddPointBWinc[«options»]{«list of points» or «file  name»}%|

\commande|                           {«point» or «number of line»}{«code before»}{«code after»}|\medskip

\subsection{With MetaPost}

We consider the case where the drawing engine is MetaPost (through the
\Verb+luamplib+ package).

We describe the feature taking one macro in example but the mechanism
and the possibilities are exactly the same for all the macros.

When we use the MetaPost drawing engine, the macros previously
described produced a code of the form
\begin{latexcode}
\begin{luamplib}
  u:=<scale>;
  beginfig(0);
  <code for the drawing>
  endfig;
\end{luamplib}
\end{latexcode}

Then, the arguments \meta{code before} and \meta{code after} are
inserted as follows:
\begin{latexcode}
\begin{luamplib}
  u:=<scale>;
  <<code before>>
  <code for the drawing>
  <<code after>>
\end{luamplib}
\end{latexcode}
\begin{warning}
With the \emph{inc} macros, the user has to add the \Verb+beginfig();+
and \Verb+endfig;+ commands to produce a picture. Indeed, this allows
to use the \Verb+\everymplib+ command from the \Verb+\luamplib+ package.
\end{warning}

\subsubsection{The \LaTeX{} Colors Inside the MetaPost Code}\label{sec:mpcolor}

The configurable colors
of the \LaTeX{} macro are accessible inside the MetaPost code. For
\Verb+\buildMeshBWinc+ and \Verb+\drawPointsMeshinc+, we have
\Verb+\luameshmpcolor+,
and \Verb+\luameshmpcolorBbox+.
For the macro \Verb+\meshAddPointBWinc+ we have three additional
colors : \Verb+\luameshmpcolorBack+, \Verb+\luameshmpcolorNew+, and
\Verb+\luameshmpcolorCircle+. Of course, we can define MetoPost
colors as well. Finally, the \Verb+luamplib+ mechanism of
\Verb+\mpcolor+ is also available.

\subsubsection{The Mesh Points}

At the beginning of the automatically generated code, a list of
MetaPost \Verb+pair+s are defined corresponding to all the vertices of
the mesh (when the option \Verb+bbox=show+, the last 4 points are the
\emph{bounding box points}). The points are available with the
\Verb+MeshPoints[]+ table of variables. The \Verb+MeshPoints[i]+ are
defined using the unit length \Verb+u+.

\subsubsection{Examples}

Here is three examples for the different macros.
\begin{Exemple}
\drawPointsMeshinc[
color = blue!50,
print = points,
meshpoint = x,
scale=0.8cm,
]{(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)}%
{% code before
  beginfig(0);
}%
{% code after
  label(btex Mesh $\mathbb{T}$ etex, (0,2u)) withcolor \luameshmpcolor;
  endfig;
}
\buildMeshBWinc[%
bbox = show,
color = red,
colorBbox = blue!30,
print = points,
meshpoint = x,
scale=0.8cm
]{(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)}%
{% code before
  beginfig(0);
}
{% code after
  drawdblarrow MeshPoints[3] -- MeshPoints[9] withpen pencircle scaled 1pt
  withcolor (0.3,0.7,0.2);
  endfig;
}
\meshAddPointBWinc[
meshpoint = \alpha,
newpoint = y,
colorBack=red!10,
colorNew = green!50!red,
colorCircle = blue,
colorBbox = black!20,
bbox = show,
scale=0.8cm,
step=badtriangles]
{(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)}%
{%code before
  picture drawing;
  drawing := image(
}{%code after
  );
  beginfig(0);
  fill MeshPoints[7]--MeshPoints[8]--MeshPoints[9]--MeshPoints[10]--cycle
  withcolor \mpcolor{blue!10};
  draw drawing;
  endfig;
}
\end{Exemple}
\begin{warning}
  The variables \Verb+MeshPoints[]+ are not defined for the argument
  corresponding to the code to place before the code generated by
  \luamesh. Hence, to use such variables, we have to define a
  \Verb+picture+ as shown in the third example above.
\end{warning}


\subsection{With TikZ}

If we have chosen \Verb+tikz+ as the engine drawing, the added code
will be written in \Verb+tikz+. In that case, the two arguments
\meta{code before} and \meta{code after} will be inserted as follows:
\begin{latexcode}
\noindent
\begin{tikzpicture}[x=<scale>,y=<scale>]
  <<code before>>
  <generated code>
  <<code after>>
\end{tikzpicture}
\end{latexcode}

Because the engine is \Verb+tikz+ their is no issue with colors, the
\LaTeX{} colors (e.g.: \Verb+xcolor+) can be directly used.

\subsubsection{The Mesh Points}

The points of the mesh are defined here as \Verb+tikz+
\Verb+\coordinate+ named as follows
\begin{latexcode}
\coordinate (MeshPoints1) at (...,...);
\coordinate (MeshPoints2) at (...,...);
\coordinate (MeshPoints3) at (...,...);
%etc.
\end{latexcode}

Once again these coordinates are not yet defined for the \meta{code
  before} argument.

\subsubsection{Examples}

\begin{Exemple}
  \drawPointsMeshinc[
  tikz,
  color = blue!50,
  print = points,
  meshpoint = x,
  scale=0.8cm,
  ]{(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)}%
  {% code before
  }%
  {% code after
    \node[color = blue!50]  at (0,2) {Mesh $\mathbb{T}$} ;
  }
  \buildMeshBWinc[%
  tikz,
  bbox = show,
  color = red,
  colorBbox = blue!30,
  print = points,
  meshpoint = x,
  scale=0.8cm
  ]{(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)}%
  {% code before
  }
  {% code after
    \draw[<->,thick, color=green] (MeshPoints3) -- (MeshPoints9);
  }
\end{Exemple}

\section{Voronio Diagrams}

Another interesting concept of Delaunay triangulation is that it is
\emph{dual} to it so-called Voronio diagram. For a finite set of
points $\{p_{1},\ldots, p_{n}\}$ in the Euclidean plane, for all
$p_{k}$, it corresponds a Voronoi cell $R_{k}$ consisting of
every point in the Euclidean plane whose distance to $p_{k}$ is less
than
or equal to its distance to any other $p_{k'}$.\bigskip


\commande|\buildVoronoiBW[«options»]{«list of points» or «file  name»}|\medskip

This macro produce the Voronio diagram dual to the Delaunay
triangulation (computed by the Bowyer and Watson
algorithm) of the given \meta{list of points}. Once again, the
list of
points must be given in the following way :
\begin{center}
  \verb+(x1,y1);(x2,y2);(x3,y3);...;(xn,yn)+
\end{center}

\begin{Exemple}
  \buildVoronoiBW{(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);(0.1,2);(1.5,-0.3)}
\end{Exemple}

\subsection{The Options}\label{sec:voronoiOptions}


There are several options to customize the drawing.
\begin{optionsenum}
\item[mode = int (default) \textme{or} ext:] this option allows to
  use either the previously described set of points in the argument, or
  a file, containing, line by line (2 columns), the points. Such a
  file looks like :
\begin{verbatim}
x1  y1
x2  y2
x3  y3
...
xn yn
\end{verbatim}
\item[bbox = none (default) \textme{or} show:] this option allows to draw the
  added points to form a \emph{bounding box}\footnote{The bounding
    box is defined by four points place at 15\% around the box
    defined by $(x_{\min},y_{\min})$, $(x_{\min},y_{\max})$,
    $(x_{\max},y_{\max})$, and $(x_{\min},y_{\max})$. It is used by
    the algorithm and will be computed in any case.} and the corresponding
  triangulation. By default, these points are removed at the end of
  the algorithm.
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[colorBbox = \meta{value} (default: black):] The color of the
  drawing for the elements (points and triangles) belonging to the
  bounding box.
\item[colorVoronoi = \meta{value} (default: black):] The color of the
  drawing for the elements (points and polygons) belonging to the
  Voronoi diagram.
\item[print = none (default) \textme{or} points:] To label the vertices of the
  triangulation. Contrary to the previous macros, where
  \Verb+print=none+,  a \emph{dot} is produced at each vertex (of the
  set of points and on the circumcircle center which are the nodes of
  the Voronoi diagram).
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[circumpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the Voronoi diagram. It is included in the math
  mode delimiters \Verb+$...$+.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is drawn (the same for both
  axes). It must contain the unit of length (cm,
  pt, etc.).
\item[delaunay = none (default) \textme{or} show] This option
  allows to draw the Delaunay triangulation under the Voronoi diagram.
\item[styleDelaunay = none (default) \textme{or} dashed] This option
  allows to draw dashed lines for the Delaunay triangulation.
\item[styleVoronoi = none (default) \textme{or} dashed] This option
  allows to draw dashed lines for the Voronoi edges.
\end{optionsenum}

\begin{Exemple}
  \buildVoronoiBW[tikz,delaunay=show,styleDelaunay=dashed]
  {(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);(0.1,2);(1.5,-0.3)}
\end{Exemple}

\subsection{The \emph{inc} variant}

Once again, a variant of the macros is available allowing the user to
add code before and after the code produced by \luamesh. We refer to
the section~\ref{sec:inc} because it works the same way.

Let us note that:
\begin{itemize}
\item with MetaPost, the circumcenters are defined using
  \Verb+pair CircumPoints[];+, and so, are accessible.
\item With \Verb+tikz+, there are new coordinates defined as follows
  \begin{latexcode}
    \coordinate (CircumPoints1) at (...,...);
    \coordinate (CircumPoints2) at (...,...);
    \coordinate (CircumPoints3) at (...,...);
    % etc.
  \end{latexcode}
\end{itemize}

Finally, when the MetaPost drawing engine is used, another color is
available (see~\ref{sec:mpcolor}): \Verb+\luameshmpcolorVoronoi+.


\section{With Gmsh}

Gmsh is a open source efficient software that produces meshes. The
exporting format is the \emph{MSH ASCII file format} and can be easily
read by a Lua program. \luamesh provides the user with dedicated
macros to read and draw meshes coming from a Gmsh exportation.\bigskip

\commande|\drawGmsh[«options»]{«file  name»}|\medskip

This macro draw the triangulation produced by Gmsh and exported in the
\Verb+msh+ format. The argument is the name of the file to read
(e.g.: \Verb+maillage.msh+).

\begin{Exemple}
\drawGmsh{maillage.msh}
\end{Exemple}

There are several options to customize the drawing.
\begin{optionsenum}
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[print = none (default) \textme{or} points:] To label the vertices of the
  triangulation. Contrary to the previous macros, where
  \Verb+print=none+,  a \emph{dot} is produced at each vertex (of the
  set of points and on the circumcircle center which are the nodes of
  the Voronoi diagram).
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is drawn (the same for both
  axes). It must contain the unit of length (cm,
  pt, etc.).
\end{optionsenum}
Here is an example:
\begin{Exemple}
  \drawGmsh[scale=2cm,print=points, color=blue!30]{maillage.msh}
\end{Exemple}

\subsection{Gmsh and Voronoi Diagrams}

Because Gmsh generates Delaunay triangulations, we can plot the
Voronoi diagram associated. This is done by the following macro:\bigskip

\commande|\gmshVoronoi[«options»]{«file name»}|\medskip

\begin{Exemple}
  \gmshVoronoi{maillage.msh}
\end{Exemple}


\subsection{The Options}\label{sec:voronoiOptions}


There are several options to customize the drawing.
\begin{optionsenum}
\item[color = \meta{value} (default: black):] The color of the
  drawing.
\item[colorVoronoi = \meta{value} (default: black):] The color of the
  drawing for the elements (points and polygons) belonging to the
  Voronoi diagram.
\item[print = none (default) \textme{or} points:] To label the vertices of the
  triangulation. Contrary to the previous macros, where
  \Verb+print=none+,  a \emph{dot} is produced at each vertex (of the
  set of points and on the circumcircle center which are the nodes of
  the Voronoi diagram).
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is included in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with numbers 1 to 4 and with a star exponent.
\item[circumpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the Voronoi diagram. It is included in the math
  mode delimiters \Verb+$...$+.
\item[tikz (boolean, default:false):] By default, this boolean is set
  to \Verb+false+, and MetaPost (with \Verb+luamplib+) is used to draw
  the picture. With this option, \Verb+tikz+ becomes the \textit{drawing
    engine}.
\item[scale = \meta{value} (default: 1cm):] The scale option defines
  the scale at which the picture is drawn (the same for both
  axes). It must contain the unit of length (cm,
  pt, etc.).
\item[delaunay = none (default) \textme{or} show] This option
  allows to draw the Delaunay triangulation under the Voronoi diagram.
\item[styleDelaunay = none (default) \textme{or} dashed] This option
  allows to draw dashed lines for the Delaunay triangulation.
\item[styleVoronoi = none (default) \textme{or} dashed] This option
  allows to draw dashed lines for the Voronoi edges.
\end{optionsenum}

\begin{Exemple}
  \gmshVoronoi[tikz,scale=1.5cm, delaunay=show,styleVoronoi=dashed]{maillage.msh}
\end{Exemple}


\subsection{The \emph{inc} variants}

Once again, there exists \emph{inc} variant macros:\bigskip

\commande|\drawGmshinc[«options»]{«file name»}{«code before»}{«code after»}|\medskip

\commande|\gmshVoronoiinc[«options»]{«file name»}{«code before»}{«code after»}|\medskip

We refer to the previous sections for explanations.

\section{Gallery}
\subsection{With Animate}

If you use \emph{adobe acrobat reader}, you can easily produce an
animation of the Bowyer and Watson algorithm with the package
\Verb+animate+.

For example, the following code (in a file name \Verb+animation.tex+):
\begin{latexcode}
  \documentclass{article}
  %% lualatex compilation
  \usepackage[margin=2.5cm]{geometry}
  \usepackage{luamesh}
  \usepackage{fontspec}
  \usepackage{multido}
  \pagestyle{empty}
  \def\drawPath{draw (-2,-2)*u--(8,-2)*u--(8,6)*u--(-2,6)*u--cycle  withcolor 0.99white;}
  \def\clipPath{clip currentpicture to (-2,-2)*u--(8,-2)*u--(8,6)*u--(-2,6)*u--cycle;}
  \begin{document}
  \drawPointsMeshinc[mode=ext, bbox = show,colorBbox = blue!20,print=points]{mesh.txt}%
  {%
    beginfig(0);
    \drawPath
  }%
  {%
    \clipPath
    endfig;
  }
  \newpage\buildMeshBWinc[mode=ext,bbox = show,colorBbox = blue!20,print=points]{meshInit.txt}%
  {%
    beginfig(0);
    \drawPath
  }%
  {%
    \clipPath
    endfig;
  }
  \multido{\ii=5+1}{4}{%
    \newpage\meshAddPointBWinc[mode=ext,step=badtriangles,colorNew
    =green!20!red,colorBack=red!10,colorCircle = blue,bbox =
    show,colorBbox = blue!20]{mesh.txt}{\ii}%
    {%
      beginfig(0);
      \drawPath
    }%
    {%
      \clipPath
      endfig;
    }   \newpage
    \meshAddPointBWinc[mode=ext,step=cavity,colorNew
    =green!20!red,colorBack=red!10,colorCircle = blue,bbox =
    show,colorBbox = blue!20]{mesh.txt}{\ii}%
    {%
      beginfig(0);
      \drawPath
    }%
    {%
      \clipPath
      endfig;
    }  \newpage
    \meshAddPointBWinc[mode=ext,step=newtriangles,colorNew
    =green!20!red,colorBack=red!10,colorCircle = blue,bbox =
    show,colorBbox = blue!20]{mesh.txt}{\ii}%
    {%
      beginfig(0);
      \drawPath
    }%
    {%
      \clipPath
      endfig;
    }
  }
  \newpage
  \buildMeshBWinc[mode=ext,bbox = show,colorBbox = blue!20,print=points]{mesh.txt}%
  {%
    beginfig(0);
    \drawPath
  }%
  {%
    \clipPath
    endfig;
  }
  \newpage
  \buildMeshBWinc[mode=ext,print=points]{mesh.txt}%
  {%
    beginfig(0);
    \drawPath
  }%
  {%
    \clipPath
    endfig;
  }
\end{document}
\end{latexcode}
produces a PDF with multiple pages. Using the \Verb+pdfcrop+ program,
we crop the pages to the material, and then we can animate the PDF
using the \Verb+animate+ package.

%\begin{Exemple}
%\animategraphics[controls]{1}{animation-crop}{}{}
%\end{Exemple}

\input{dum.bbl}

\end{document}



%%% Local Variables:
%%% flyspell-mode: 1
%%% ispell-local-dictionary: "american"
%%% End: