\newpage
\section{Macros}

This section describes a set of LaTeX macros provided by the \tkzname{tkz-elements} package. These macros serve as interfaces between Lua-generated geometric data and TikZ/LaTeX rendering. They allow users to access, visualize, or manipulate geometric constructions stored in Lua tables, without writing any Lua code directly.

Most macros operate on objects created and named within the Lua environment, such as points, paths, lines, and circles. They simplify tasks such as printing values, drawing objects defined by Lua, or extracting points from Lua paths.

Macros in this section cover a wide range of functionalities:
\begin{itemize}
\item Numerical formatting and printing;
\item Memory management (removing Lua objects);
\item Drawing curves, paths, segments, and circles from Lua data;
\item Converting Lua paths into TikZ nodes or point sets;
\item Bridging between Lua computations and LaTeX commands.
\end{itemize}

Each macro is described with its syntax and one or more usage examples. These tools make it easy to integrate Lua-based geometric constructions into a TikZ workflow in a declarative and readable manner.


\subsection{Macro \tkzMacro{tkz-elements}{tkzPrintNumber}}
This macro formats and prints a number using PGF’s fixed-point output, with a default precision of 2 decimal places.

\medskip

\texttt{Syntax: }\verb|\tkzPrintNumber[<precision>]{<number>}|


\texttt{Example usage:}

\begin{mybox}
\begin{verbatim}
\tkzPrintNumber{pi} % outputs 3.14
\tkzPrintNumber[4]{sqrt(2)} % outputs 1.4142
\end{verbatim}
\end{mybox}

\texttt{Alias: } The macro \tkzMacro{tkz-elements}{tkzPN} is a shorthand for \tkzMacro{tkz-elements}{tkzPrintNumber}.

\subsection{Macro \tkzMacro{tkz-elements}{tkzEraseLuaObj}}
\label{sub:macro_tkzEraseLuaObj}

This macro removes a Lua object from memory.


\texttt{Syntax: } \verb|\tkzEraseLuaObj{<object>}|



\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzEraseLuaObj{z.A}
\tkzEraseLuaObj{T.ABC}
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCirclesFromPaths}}
\label{sub:macro_tkzDrawCirclesFromPaths}
This macro draws circles defined by two paths: one for the centers and one for the points through which each circle passes.

\texttt{Syntax: }\verb|\tkzDrawCirclesFromPaths[<options>](<PA.center>,<PA.through>)|

\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzDrawCirclesFromPaths[blue](PA.O, PA.A)
\end{verbatim}
\end{mybox}

See Apollonius section [\ref{sec:apollonius}] for other examples

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawSegmentsFromPaths}}
\label{sub:macro_tkzDrawSegmentsFromPaths}

This macro draws segments between corresponding points in two Lua paths.


\texttt{Syntax: }\verb|\tkzDrawSegmentsFromPaths[<options>](<start>,<end>)|

\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzDrawSegmentsFromPaths[red](PA.A, PA.B)
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawPointsFromPath}}
\label{sub:macro_tkzDrawPointsFromPath}

This macro draws all points of a path using \tkzname{tkzDrawPoint}.

\texttt{Syntax: }\verb|\tkzDrawPointsFromPath<options>|


\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzDrawPointsFromPath[color=blue]
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzGetPointsFromPath}}
This macro defines TikZ points from a Lua path. Each point is named with a base name followed by an index.

\texttt{Syntax: }\verb|\tkzGetPointsFromPath[<options>](<path>,<basename>)|

\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzGetPointsFromPath(PA.triangle,A)
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCoordinates}}
This macro draws a curve using the TikZ \code{plot coordinates} syntax, with coordinates generated by Lua.


\texttt{Syntax: } |\tkzDrawCoordinates<options>|

\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzDrawCoordinatesred,thick
\end{verbatim}
\end{mybox}

\texttt{Alias: } \tkzMacro{tkz-elements}{tkzDrawPath} is equivalent.

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawPointOnCurve}}

Draws a single point on a curve, typically computed via Lua.

\texttt{Syntax: } |\tkzDrawPointOnCurve<options>|

\medskip
\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzDrawPointOnCurvered
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawFromPointToPath}}
This macro draws a set of line segments from a given TikZ point to every point of a Lua \emph{path} object.

\texttt{Syntax: }\verb|\tkzDrawFromPointToPath[<options>](<PointTikZ>,<PathLua>)|


\texttt{Arguments: }

\verb|<options>| (optional): pgf/tikz drawing options (color, thickness, etc.).
\verb|<PointTikZ>|: the name of a TikZ point (already defined).
\verb|<PathLua>|: identifier of a Lua \verb|path| object (with \verb|:iter()| available).


\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
% Draw segments from O to all points of path PA.A
\tkzDrawFromPointToPath[blue,very thick](O, PA.A)
\end{verbatim}
\end{mybox}
\subsection{Macro \tkzMacro{tkz-elements}{tkzPathCount}}
This macro retrieves the number of vertices in a Lua path and stores the result in a TeX macro.

\texttt{Syntax: }\verb|\tkzPathCount(<PathLua>){<MacroName>}|

\texttt{Arguments: }

\verb|<PathLua>|: identifier of a Lua \verb|path| object.
\verb|<MacroName>|: name of a TeX macro (without the backslash) that will store the count.


\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
% Count the number of vertices of PA.A
\tkzPathCount(PA.A){N} % -> \N holds the count
% Iterate using TikZ
\foreach \i in {1,...,\N}{
% ...
}
\end{verbatim}
\end{mybox}
\subsection{Macro \tkzMacro{tkz-elements}{tkzGetPointFromPath}}
This macro extracts the i-th vertex of a Lua path and defines it as a TikZ point with a given name.

\texttt{Syntax: }\verb|\tkzGetPointFromPath(<PathLua>,<index>){<PointName>}|

\texttt{Arguments: }

\verb|<PathLua>|: identifier of a Lua \verb|path| object.
\verb|<index>|: index of the vertex to retrieve (TeX number or numeric macro).
\verb|<PointName>|: name of the TikZ point to create.
\medskip


\texttt{Example usage:}

\begin{mybox}
\begin{verbatim}
% Get the 3rd vertex of PA.A and name it P3
\tkzGetPointFromPath(PA.A,3){P3}
% With counting and a loop
\tkzPathCount(PA.A){N}
\foreach \i in {1,...,\N}{
\expandafter\tkzGetPointFromPath\expandafter(PA.A,\i){P\i}
}
\end{verbatim}
\end{mybox}

\subsection{Macro \tkzMacro{tkz-elements}{tkzUseLua}}

This macro evaluates a Lua expression and inserts its result in the document.


\texttt{Syntax: }\verb|\tkzUseLua{<lua-code>}|

\texttt{Example usage: }

\begin{mybox}
\begin{verbatim}
\tkzUseLua{checknumber(math.pi)}
\end{verbatim}
\end{mybox}

\subsection{Example: Archimedes spiral}

This example is built with the help of some of the macros presented in this section. It is inspired by an example created with tkz-euclide by Jean-Marc Desbonnez.

\vspace{1em}
\begin{tkzexample}[vbox]
\directlua{
  z.O = point(0, 0)
  z.A = point(5, 0)
  L.OA = line(z.O, z.A)
  PA.spiral = path()
  PA.center = path()
  PA.through = path()
  PA.ray = path()
  for i = 1, 48 do
      local k = i / 48
      z["P"..i] = L.OA:point(k)
      local angle = i * 2 * math.pi / 48
      z["r"..i] = point(polar(5, angle))
      ray = line(z.O, z["r"..i])
      circ = circle(z.O, z["P"..i])
      z["X"..i], _ = intersection(ray, circ)
      PA.spiral:add_point(z["X"..i])
      PA.center:add_point(z.O)
      PA.through:add_point(z["P"..i])
      PA.ray:add_point(z["r"..i])
  end}
\begin{center}
  \begin{tikzpicture}[scale = .8]
  \tkzGetNodes
  \tkzDrawCircle(O,A)
  \tkzDrawCirclesFromPaths[draw,
      orange!50](PA.center,PA.through)
  \tkzDrawSegmentsFromPaths[draw,teal](PA.center,PA.ray)
  \tkzDrawPath[red,thick,smooth](PA.spiral)
  \tkzDrawPointsFromPath[blue, size=2](PA.spiral)
  \end{tikzpicture}
\end{center}

\end{tkzexample}
\endinput