\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
\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 \tkzMacro{tkz-elements}{tkzEraseLuaObj}}
\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 \tkzMacro{tkz-elements}{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 \tkzMacro{tkz-elements}{tkzDrawSegmentsFromPaths}}
\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 \tkzMacro{tkz-elements}{tkzDrawPointsFromPath}}
\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 \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.

\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 \tkzMacro{tkz-elements}{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 \tkzMacro{tkz-elements}{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 \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.

\medskip
\noindent
Syntax:
\begin{verbatim}
\tkzDrawFromPointToPath[<options>](<PointTikZ>,<PathLua>)
\end{verbatim}

\noindent
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).
\medskip
\noindent
Remarks:
For each vertex
(
x
,
y
)
(x,y) in the path, a temporary TikZ point \verb|tmp| is created and connected to the fixed point.
The path must already exist on the Lua side.
\medskip
\noindent
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.
\medskip
\noindent
Syntax:
\begin{verbatim}
\tkzPathCount(<PathLua>){<MacroName>}
\end{verbatim}
\noindent
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.
\medskip
\noindent
Remarks:
The macro is defined with \verb|\edef|, e.g., \verb|\edef\N{10}|.
This allows direct iteration in TikZ or pgfloops.
\medskip
\noindent
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.
\medskip
\noindent
Syntax:
\begin{verbatim}
\tkzGetPointFromPath(<PathLua>,<index>){<PointName>}
\end{verbatim}
\noindent
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
\noindent
Remarks:
The index is passed as a number to the Lua method \verb|get_number_path(i)|.
Indexing is consistent with the Lua implementation (usually 1-based).
The created point is defined with \verb|\tkzDefPoint(x,y){<PointName>}|.
\medskip
\noindent
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.

\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{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