%% $Id: domaincoloring-doc.tex 952 2024-08-22 15:40:35Z herbert $
% 
\listfiles

\DocumentMetadata{}
\documentclass[fontsize=11pt,english,BCOR=10mm,DIV=12,bibliography=totoc,parskip=false,headings=small,
    headinclude=false,footinclude=false,oneside]{pst-doc}
\listfiles

\usepackage{biblatex}
\addbibresource{\jobname.bib}

\usepackage{booktabs} % for examples
\usepackage{xltabular} % for examples
\usepackage{enumitem}
\setlist{noitemsep,nosep}

\usepackage{domaincoloring}
\let\DColFV\fileversion

\usepackage{hvlogos} 

\usepackage{listings}
\lstset{columns=fixed,basicstyle=\ttfamily\small}

\def\bgImage{\includegraphics[width=7cm]{titleImg}}

\title{Domain Coloring of complex functions\\version \DColFV}
\author{Herbert Voß}
\begin{document}
\settitle
\tableofcontents


\section{Introduction}

This package works only with \texttt{lualatex}!

\subsection{Loading the package}
The package \texttt{domaincoloring} creates acolored interpretation of the
domain of a complex function. The package itself has no options and should be loaded as
usual:

\begin{verbatim}
\usepackage{domaincoloring}
\end{verbatim}

The needs the following Lua modules:

\begin{itemize}
\item \texttt{domaincoloring.lua}   the main module
\item \texttt{domaincoloring-complex-numbers.lua} for complex math operations
\item \texttt{domaincoloring-functions.lua}   for predefined complex functions
\end{itemize}

The function  module has to be managed  by the user himself, if needed.



\subsection{Using the macro}

There is only one macro which does the external call of the Lua program \verb|domaincoloring.lua|.
This program creates the image which is then included into the document. The \LaTeX-run needs
the \verb|--shell-escape| option to allow the external run of the program to convert the created
ppm-file into a png file..


\begin{verbatim}
\DomainColoring[options]{complex function in Lua notation}
\end{verbatim}

Every math function has to be preceeded by \texttt{cmath} if it has a complex argument.

\subsection{Options}

\noindent
\begin{xltabular}{\linewidth}{@{} >{\ttfamily}l l X @{}}\\\toprule
\emph{name} & \emph{value} &\emph{meaning}\\\midrule
domain & {-2,2,-2,2} & the (re,im)-coordinates for the complex system\\
resolution & 500 & the number of steps for the re,im interval. At the moment only
for both coordinates the same. Will be in future
versions different for the both axes. \\
filename & \Lcs{jobname-tmp} & name of the created external file, must be unique\\ 
grfOptions &scale=0.5 & optional arguments for \Lcs{includegraphics}\\
hsvrgb & {phi,1,r} & for the conversion into rgb\\
funcName & & corresponding to external file\\
bgcolor & 0 & change color to white as background for all values $r+g+b\le\text{bgcolor}$\\
invers & false & inverted colors with $color=|color-255|$\\
\bottomrule
\end{xltabular}




\section{Examples}

\subsection{The default with function $f(z)=z$}
\begin{lstlisting}
\DomainColoring{z}\qquad  % default filename \jobname-tmp.png
\end{lstlisting}

\noindent
\DomainColoring{z}%\qquad
%\DomainColoring[filename=demo2.png,bgcolor=true]{z}



\subsection{Defining domain, color mode, resolution and filename}

\begin{align}
 f(z) &= \cos(z)/\sin(z^4-1)
\end{align}

in Lua-notation: \verb|cmath.cos(z)/cmath.sin(z^4-1)|.

\begin{lstlisting}
\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,
    grfOptions={width=0.32\linewidth},
    filename=\jobname-tmp1a]{cmath.cos(z)/cmath.sin(z^4-1)}
\hfill
\frame{\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,
    bgcolor=true,grfOptions={width=0.32\linewidth},bgcolor=3,
    filename=\jobname-tmp1b]{cmath.cos(z)/cmath.sin(z^4-1)}}
\hfill
\frame{\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,
    invers=true,,grfOptions={width=0.32\linewidth},
    filename=\jobname-tmp1c]{cmath.cos(z)/cmath.sin(z^4-1)}}
\end{lstlisting}

\noindent
\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,grfOptions={width=0.32\linewidth},
    filename=\jobname-tmp1a]{cmath.cos(z)/cmath.sin(z^4-1)}
\hfill
\frame{\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,bgcolor=3,grfOptions={width=0.32\linewidth},
    filename=\jobname-tmp1b]{cmath.cos(z)/cmath.sin(z^4-1)}}
\hfill
\frame{\DomainColoring[domain={-2.5,2.5,-2.5,2.5},resolution=500,invers=true,grfOptions={width=0.32\linewidth},
    filename=\jobname-tmp1c]{cmath.cos(z)/cmath.sin(z^4-1)}}


With \Lcs{bgcolor}\texttt{=<int>} all RGB-combinations with a sum $R+G+B <= \text{int}$ are set to
the color white. 

\subsection{Option for \Lcs{includegraphics}}
With \Lkeyword{grfOptions} one can define optional arguments for \Lcs{includegraphics}:

\begin{lstlisting}
\DomainColoring[grfOptions={width=0.49\linewidth},filename=\jobname-tmp2a]{cmath.sin(z)}\hfill
\hfill
\DomainColoring[grfOptions={width=0.49\linewidth},filename=\jobname-tmp2b]{1/cmath.sin(z)}
\end{lstlisting}

\noindent
\DomainColoring[grfOptions={width=0.49\linewidth},filename=\jobname-tmp2a]{cmath.sin(z)}
\hfill
\DomainColoring[grfOptions={width=0.49\linewidth},filename=\jobname-tmp2b]{1/cmath.sin(z)}


\subsection{Higher resolution}

The resolution is more or less the number of pixels for the given domain.
In later versions of this package it may be possible to have different values
for the two coordinates. By now the one value for \Lkeyword{resolution} is for
both axes.


\begin{lstlisting}
\DomainColoring[filename=\jobname-tmp3,resolution=1000,
  grfOptions={width=0.49\linewidth}]{z^3-1}
\hfill
\DomainColoring[filename=\jobname-tmp4,resolution=1000,
  grfOptions={width=0.49\linewidth}]{(z+1)^2*(z-1)/((z+i)*(z-i)^2)}
\end{lstlisting}

\noindent
\DomainColoring[filename=\jobname-tmp3,resolution=1000,
  grfOptions={width=0.49\linewidth}]{z^3-1}
\hfill
\DomainColoring[filename=\jobname-tmp4,resolution=1000,
  grfOptions={width=0.49\linewidth}]{cmath.sin(z)*cmath.cos(z)}


\subsection{hsv to rgb conversion}

The color model (Wikipedia)

\begin{center}
\includegraphics[width=0.5\linewidth]{hsv}

\url{http://en.wikipedia.org/wiki/File:HSV_color_solid_cylinder_alpha_lowgamma.png}
\end{center}


The complex number $z=x+iy$ is converted into its trogonometrical representation $x=r\cdot \cos\phi$ 
and $y=r\cdot \sin\phi$ with $r=\sqrt{x^2+y^2}$. The values $r$ and $\phi$ are now taken as values
for the hsv color model with a constant second value for saturation. $\phi$ is used
for hue. For example: \verb|hsvrgb=phi,1,r|, which gives

\begin{lstlisting}
\DomainColoring[filename=\jobname-tmp5a,resolution=1000,
   grfOptions={width=0.49\linewidth},hsvrgb={phi,1,r}]{cmath.sin(z)*cmath.sin(0.99*z)}
\hfill
\DomainColoring[filename=\jobname-tmp5b,resolution=1000,
   grfOptions={width=0.49\linewidth}]{cmath.sin(z)*cmath.sin(0.99*z)} % the default
\end{lstlisting}

\noindent
\DomainColoring[filename=\jobname-tmp5a,resolution=1000,
   grfOptions={width=0.49\linewidth},funcName=f10,hsvrgb={phi,1,r}]{cmath.sin(z)*cmath.sin(0.99*z)} % the default
\hfill
\DomainColoring[filename=\jobname-tmp5b,resolution=1000,
   grfOptions={width=0.49\linewidth}]{cmath.sin(z)*cmath.sin(0.99*z)} 

%For $r$ and $\phi$ we have to use $r$ and $phi$.
The optional argument \Lkeyword{hsvrgb} must define three values which can use the arguments
phi and r in any mathematical combination. It must only be compatible to the Lua math conventions,
e.g. \texttt{hsvrgb=\{phi+2,0.5,2/r\}}




\subsection{External function definition}
The already existing file \LFile{domaincoloring-functions.lua} collects sone
definitions of complex functions $f(z)$, which can be used from inside \LaTeX\ 
with the optional argument \Lkeyword{funcName}. In this case the mandatory argument
of \Lcs{DomainColoring} has no meaning and can be empty.

\begin{lstlisting}
\DomainColoring[filename=\jobname-tmp6a,resolution=1000,
   domain={-1.5,1.5,-1.5,1.5}, grfOptions={width=0.49\linewidth},
   hsvrgb={phi+2*pi,1,1/r}, funcName=f12]{}%  using predefined function
\hfill
\DomainColoring[filename=\jobname-tmp6b,resolution=2000,
   domain={-2.3,0.7,-1.5,1.5}, grfOptions={width=0.49\linewidth},
   hsvrgb={phi+2*pi,1,1/r},funcName=f13]{}
\end{lstlisting}

\noindent
\DomainColoring[filename=\jobname-tmp6a,resolution=1000,
   domain={-1.5,1.5,-1.5,1.5}, grfOptions={width=0.49\linewidth},
   hsvrgb={phi+2*pi,1,1/r}, funcName=f12]{}%  using predefined function
\hfill
\DomainColoring[filename=\jobname-tmp6b,resolution=2000,
   domain={-2.3,0.7,-1.5,1.5}, grfOptions={width=0.49\linewidth},
   hsvrgb={phi+2*pi,1,1/r},funcName=f13]{}


The contents of the function file of the current version of \LPack{domaincoloring} is::

\lstinputlisting[language={[5.3]Lua},basicstyle=\small\ttfamily]{domaincoloring-functions.lua}



\nocite{*}
\printbibliography

\end{document}
