\newpage
\section{Macros} % (fold)
\label{sec: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}} % (fold)
\label{sub:macro_tkzPrintNumber}

This macro formats and prints a number using PGF’s fixed-point output, with a default precision of 2 decimal places.

\medskip
\noindent
The command syntax is:

\begin{verbatim}
\tkzPrintNumber[<precision>]{<number>}
\end{verbatim}

\noindent
Example usage:

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

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

% subsection macro_tkzPrintNumber (end)
\subsection{Macro \tkzMacro{tkz-elements}{tkzEraseLuaObj}} % (fold)
\label{sub:macro_tkzEraseLuaObj}

This macro removes a Lua object from memory.

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzEraseLuaObj{<object>}
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzEraseLuaObj (end)



\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCirclesFromPaths}} % (fold)
\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.

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzDrawCirclesFromPaths[<options>](<centers>,<through>)
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzDrawCirclesFromPaths (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawSegmentsFromPaths}} % (fold)
\label{sub:macro_tkzDrawSegmentsFromPaths}

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

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzDrawSegmentsFromPaths[<options>](<start>,<end>)
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzDrawSegmentsFromPaths (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawPointsFromPath}} % (fold)
\label{sub:macro_tkzDrawPointsFromPath}

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

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzDrawPointsFromPath<options>
\end{verbatim}

\noindent
Example usage:

\begin{mybox}
\begin{verbatim}
\tkzDrawPointsFromPathcolor=blue
\end{verbatim}
\end{mybox}

% subsection macro_tkzDrawPointsFromPath (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzGetPointsFromPath}} % (fold)
\label{sub:macro_tkzGetPointsFromPath}

This macro defines TikZ points from a Lua path. Each point is named with a base name followed by an index.

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzGetPointsFromPath[<options>](<path>,<basename>)
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzGetPointsFromPath (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCoordinates}} % (fold)
\label{sub:macro_tkzDrawCoordinates}

This macro draws a curve using the TikZ \code{plot coordinates} syntax, with coordinates generated by Lua.

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzDrawCoordinates<options>
\end{verbatim}

\noindent
Example usage:

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

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

% subsection macro_tkzDrawCoordinates (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzDrawPointOnCurve}} % (fold)
\label{sub:macro_tkzDrawPointOnCurve}

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

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzDrawPointOnCurve<options>
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzDrawPointOnCurve (end)

\subsection{Macro \tkzMacro{tkz-elements}{tkzUseLua}} % (fold)
\label{sub:macro_tkzUseLua}

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

\medskip
\noindent
Syntax:

\begin{verbatim}
\tkzUseLua{<lua-code>}
\end{verbatim}

\noindent
Example usage:

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

% subsection macro_tkzUseLua (end)

\subsection{Example: Archimedes spiral} % (fold)
\label{sub: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}

% subsection example_archimedes_spiral (end)

% section macros (end)