%--------------------------------------------------------------------
\newpage
\section{Transfers}
\label{sec:transfers}

The \tkzNamePack{tkz-elements} package strictly separates
\emph{mathematical computation} from \emph{graphical rendering}.
All geometric objects are created and manipulated internally in Lua,
while drawing is performed by \tkzNamePack{TikZ} or
\tkzNamePack{tkz-euclide}.

A \emph{transfer} is the explicit operation that communicates data
between the Lua computational layer and the \TeX\ rendering layer.

\medskip
Conceptually, the architecture may be summarized as:

\begin{center}
Computation (Lua) $\longrightarrow$ Transfer $\longrightarrow$ Rendering (TikZ/\TeX)
\end{center}

Objects remain invisible to \TeX\ until they are explicitly transferred.
This design guarantees numerical robustness and a clear separation
between computation and presentation.

%--------------------------------------------------------------------
\subsection{Conceptual Overview}

Three types of transfer mechanisms are available in
\tkzNamePack{tkz-elements}:

\begin{enumerate}
\item Immediate transfer via the \TeX\ input stream;
\item Object-based transfer through dedicated macros;
\item File-based transfer via external data files.
\end{enumerate}

Each mechanism serves a different purpose depending on the size
and nature of the data being communicated.

\subsection{Object Serialization via \texttt{tostring}}
\label{subsec:transfers_tostring}

The macro \tkzNameMacro{tkzUseLua} is the basic bridge from Lua to \TeX.
It evaluates a Lua expression and prints its result into the \TeX\ input stream.
Internally, it uses Lua's \texttt{tostring()} mechanism:

\begin{verbatim}
\def\tkzUseLua#1{\directlua{tex.sprint(#1)}}
\end{verbatim}

As a consequence, any \tkzNamePack{tkz-elements} object may define a Lua
\texttt{\_\_tostring} metamethod to control its textual \TeX\ representation.
This is used in particular for complex numbers (\tkzClass{point}).

\medskip
\texttt{Example with a point:}
\begin{tkzexample}[latex=.5\textwidth]
\directlua{
  init_elements()
  z.A = point(1, -2)
}
\tkzUseLua{tostring(z.A)}
\end{tkzexample}

Thus, the \emph{complex affix} associated with point $A$ is printed using
Lua’s \texttt{\_\_tostring} metamethod (via \texttt{tostring}).

\medskip
\texttt{Example with a matrix: }

The macro \tkzNameMacro{tkzUseLua} prints the \emph{value} of a Lua expression
as text (internally via \texttt{tostring(<expr>)}).%
\footnote{Hence objects may customize their inline representation by defining a Lua \texttt{\_\_tostring} metamethod.}


\medskip
\begin{tkzexample}[latex=.5\textwidth]
\directlua{
  init_elements()
  local a, b, c, d = 1, 2, 3, 4
  M.new = matrix({ { a, b }, { c, d } })}
  \tkzUseLua{M.new:print()}
\end{tkzexample}

\texttt{Other cases}
To transfer \code{nil}, \code{true}, and \code{false}, you must use \code{tostring}, However, you can directly transfer a number or a string of characters.

\begin{verbatim}
  \tkzUseLua{tostring(nil)}
  \tkzUseLua{tostring(true)}
  \tkzUseLua{"TANGENT"}
  \tkzUseLua{math.pi}
\end{verbatim}
%--------------------------------------------------------------------
\subsection{Immediate Transfer}
\label{subsec:transfer_immediate}

Immediate transfer occurs when Lua prints data directly into the
\TeX\ input stream using \texttt{tex.print}.

\subsubsection*{Numerical example}

\begin{tkzexample}[latex=.5\textwidth]
\directlua{
  init_elements()
  z.A = point(3,4)
  tex.print(point.abs(z.A))
}
\end{tkzexample}

The computed value is inserted directly into the document.

\subsubsection*{Boolean example}

\begin{tkzexample}[latex=.5\textwidth]

\directlua{
  init_elements()
  z.A = point(0, 0)
  z.B = point(3, 0)
  z.C = point(0, 2)
  T.ABC = triangle(z.A, z.B, z.C)
  tex.print(tostring(T.ABC:check_equilateral()))
}
\end{tkzexample}

This mechanism allows Lua computations to influence
\TeX\ logic through conditional statements.

\medskip
\texttt{Note: } It is possible to choose when to perform the transfer. A macro has been created for this purpose, but you can also create your own: it is called \tkzcname{tkzUseLua}. It is defined as follows:

\begin{mybox}
  \begin{verbatim}
  \def\tkzUseLua#1{\directlua{tex.print(#1)}}
\end{verbatim}
\end{mybox}

This macro prints the value of a Lua variable or expression directly into the TeX stream.

\medskip
\texttt{Example.}

 The following Lua code computes whether two lines intersect:

\directlua{
 z.a = point(4, 2)
 z.b = point(1, 1)
 z.c = point(2, 2)
 z.d = point(5, 1)
 L.ab = line(z.a, z.b)
 L.cd = line(z.c, z.d)
 det = (z.b - z.a) ^ (z.d - z.c)
 if det == 0 then bool = true
   else bool = false
 end
 x = intersection (L.ab, L.cd)}

The intersection of the two lines lies at
a point whose affix is: \tkzUseLua{x}

\vspace{1em}
\begin{minipage}{0.5\textwidth}
\begin{verbatim}
\directlua{
  z.a = point(4, 2)
  z.b = point(1, 1)
  z.c = point(2, 2)
  z.d = point(5, 1)
  L.ab = line(z.a, z.b)
  L.cd = line(z.c, z.d)
  det = (z.b - z.a) ^ (z.d - z.c)
  if det == 0 then bool = true
    else bool = false
  end
  x = intersection (L.ab, L.cd)}

The intersection of the two lines lies at
    a point whose affix is:\tkzUseLua{tostring(x)}


\begin{tikzpicture}
  \tkzGetNodes
  \tkzInit[xmin =0,ymin=0,xmax=5,ymax=3]
  \tkzGrid\tkzAxeX\tkzAxeY
  \tkzDrawPoints(a,...,d)
  \ifthenelse{\equal{\tkzUseLua{bool}}{%
  true}}{\tkzDrawSegments[red](a,b c,d)}{%
  \tkzDrawSegments[blue](a,b c,d)}
  \tkzLabelPoints(a,...,d)
\end{tikzpicture}
\end{verbatim}
\end{minipage}
\begin{minipage}{0.5\textwidth}
\begin{center}
\begin{tikzpicture}
  \tkzGetNodes
  \tkzInit[xmin =0,ymin=0,xmax=5,ymax=3]
  \tkzGrid\tkzAxeX\tkzAxeY
  \tkzDrawPoints(a,...,d)
  \ifthenelse{\equal{\tkzUseLua{bool}}{true}}{
  \tkzDrawSegments[red](a,b c,d)}{%
  \tkzDrawSegments[blue](a,b c,d)}
  \tkzLabelPoints(a,...,d)
\end{tikzpicture}
\end{center}
  \end{minipage}

%----------------------------------------------
% ---> INSERT additional custom examples here
%----------------------------------------------

%--------------------------------------------------------------------
\subsection{Object-Based Transfer}
\label{subsec:transfer_objects}

Geometric objects stored in Lua tables must be converted
into TikZ-compatible structures before drawing.

\subsubsection{Transferring points}
\label{transferring_points}

Points are internally stored as complex affixes.
The macro \tkzNameMacro{tkzGetNodes} converts them
into TikZ coordinates.

\begin{tkzexample}[latex=7cm]
  \directlua{
     init_elements()
     z.o   = point(0, 0)
     z.a_1 = point(2, 1)
     z.a_2 = point(1, 2)
     z.ap  = z.a_1 + z.a_2
     z.app = z.a_1 - z.a_2
  }

  \begin{center}
    \begin{tikzpicture}[ scale = 1.5]
       \tkzGetNodes
       \tkzDrawSegments(o,a_1 o,a_2 o,a' o,a'')
       \tkzDrawSegments[red](a_1,a' a_2,a')
       \tkzDrawSegments[blue](a_1,a'' a_2,a'')
       \tkzDrawPoints(a_1,a_2,a',o,a'')
       \tkzLabelPoints(o,a_1,a_2,a',a'')
    \end{tikzpicture}
  \end{center}
\end{tkzexample}

\subsubsection{Transferring paths and curves}


\begin{tkzexample}[latex=.4\textwidth]
\directlua{
 init_elements()
 PF.ex = pfct("(cos(t))^3", "(sin(t))^3")
 PA.curve = PF.ex:path(0, 2*math.pi, 100)
 }

\begin{center}
 \begin{tikzpicture}[scale=2]
  \tkzDrawCoordinates[smooth,red,fill=orange](PA.curve)
\end{tikzpicture}
 \end{center}
\end{tkzexample}

The Lua object is serialized into a coordinate list
interpreted by TikZ.

%----------------------------------------------
% ---> INSERT advanced fct / pfct examples here
%----------------------------------------------

%--------------------------------------------------------------------
\subsubsection{File-Based Transfer}


For large datasets or high-resolution curves,
it may be preferable to generate an external file.

This time, the transfer will be carried out using an external file. The following example is based on this one, but using a table.

\texttt{Generating a data file: } The file \texttt{tmp.table} is created using the $f$ function.

The file \texttt{tmp.table} now contains numerical data.
 \texttt{Using the generated file: } Here, the curve is plotted using \tkzNamePack{TikZ}.



\begin{tkzexample}[latex=.5\textwidth]
 \directlua{
  init_elements()
   z.a = point(1, 0)
   z.b = point(3, 2)
   z.c = point(0, 2)
   A,B,C = tkz.parabola (z.a, z.b, z.c)

 function f(t0, t1, n)
  local out=assert(io.open("tmp.table","w"))
  local y
  for t = t0,t1,(t1-t0)/n  do
   y = A*t^2+B*t +C
   out:write(utils.checknumber(t), " ",
             utils.checknumber(y), " i\string\n")
  end
  out:close()
 end}

\begin{tikzpicture}
   \tkzGetNodes
   \tkzInit[xmin=-1,xmax=5,ymin=0,ymax=5]
   \tkzDrawX\tkzDrawY
   \tkzDrawPoints[red,size=2](a,b,c)
   \directlua{f(-1,3,100)}%
   \draw[domain=-1:3] plot[smooth]
        file {tmp.table};
\end{tikzpicture}
 \end{tkzexample}





File-based transfer provides scalability and allows
interoperability with external plotting tools such as
\texttt{pgfplots}.

%----------------------------------------------
% ---> INSERT high-resolution example here
%----------------------------------------------

%--------------------------------------------------------------------
\subsection{Dynamic \TeX--Lua Interaction}
\label{subsec:dynamic_transfer}

Transfers are bidirectional.
\TeX\ may pass parameters to Lua for computation.

\medskip
\begin{verbatim}
\newcommand{\ComputeSquare}[1]{%
  \directlua{tex.print(#1 * #1)}%
}
\end{verbatim}

\medskip
Usage:
\newcommand{\ComputeSquare}[1]{%
  \directlua{tex.print(#1 * #1)}%
}
\begin{verbatim}
The square of 5 is \ComputeSquare{5}.
\end{verbatim}

\medskip
The square of 5 is \ComputeSquare{5}.

\medskip

This interaction enables dynamic parameterized geometry,
where document input directly controls Lua computations.

%----------------------------------------------
% ---> INSERT dynamic geometry example here
%----------------------------------------------

\medskip
Transfers in \tkzNamePack{tkz-elements} may therefore be
immediate, object-based, or file-based,
depending on the size and structure of the data.
This layered architecture ensures a clean separation
between computation and graphical representation.