doc: page de garde

[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{xargs}
\usepackage{enumitem}
\usepackage[tikz]{bclogo}
\usepackage{wrapfig}
\title{\Verb+luamesh+: compute and draw meshes with \lualatex}
\author{Maxime Chupin \email{mc@melusine.eu.org}}
\date{\today}

\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{red},
  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,
  % 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,
  listing only,boxsep=0pt,listing
  options={style=tcblatex}}


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

\newenvironment{optionsenum}[1][]
{\begin{description}[font=\color{red}\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}



\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}\\
{\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.1, 25 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 triangulation
  of Delaunay. The algorithm is written with lua, and depending of the
  choice of the ``engine'', the draw 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, a particular step of the algorithm.
\end{abstract}

\section{Installation}

\subsection{With Linux}

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 we have to files to place 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{Dependencies}

This package is built upon two main packages to draw the
triangulations :
\begin{enumerate}
\item \Verb+luamplib+ to use MetaPost via the \luatex library
  \Verb+mplib+;
\item or \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}

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

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

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

\subsection{Draw a Complete Mesh}

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

This macro produce 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) or ext:] this option allows to
  use either the previously described set of point 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) 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})$.} 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) or points:] To label the vertices of the
  triangulations with an adding dot.
\item[meshpoint = \meta{value} (default: P):] The letter(s) used to
  label the vertices of the triangulation. It is include in the math
  mode delimiters \Verb+$...$+. The bounding box points are labeled
  with a star exponent, and numbered from 1 to 4.
\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, it is \Verb+tikz+ 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}

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 here very relevant. But it is useful to
understand how the drawing is made. However, the engine will make sens
for the so called \emph{inc} macros (section~\ref{sec:inc}), where we
will be allowed to add code before and after the generated one by
\luamesh.
\end{warning}

\subsection{Draw the Set of Points}

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


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

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


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

\section{Gallery of Examples}

\end{document}



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