| 1 |
%-------------------------------------------------------------------- |
| 2 |
\newpage |
| 3 |
\section{Transfers} |
| 4 |
\label{sec:transfers} |
| 5 |
|
| 6 |
The \tkzNamePack{tkz-elements} package strictly separates |
| 7 |
\emph{mathematical computation} from \emph{graphical rendering}. |
| 8 |
All geometric objects are created and manipulated internally in Lua, |
| 9 |
while drawing is performed by \tkzNamePack{TikZ} or |
| 10 |
\tkzNamePack{tkz-euclide}. |
| 11 |
|
| 12 |
A \emph{transfer} is the explicit operation that communicates data |
| 13 |
between the Lua computational layer and the \TeX\ rendering layer. |
| 14 |
|
| 15 |
\medskip |
| 16 |
Conceptually, the architecture may be summarized as: |
| 17 |
|
| 18 |
\begin{center} |
| 19 |
Computation (Lua) $\longrightarrow$ Transfer $\longrightarrow$ Rendering (TikZ/\TeX) |
| 20 |
\end{center} |
| 21 |
|
| 22 |
Objects remain invisible to \TeX\ until they are explicitly transferred. |
| 23 |
This design guarantees numerical robustness and a clear separation |
| 24 |
between computation and presentation. |
| 25 |
|
| 26 |
%-------------------------------------------------------------------- |
| 27 |
\subsection{Conceptual Overview} |
| 28 |
|
| 29 |
Three types of transfer mechanisms are available in |
| 30 |
\tkzNamePack{tkz-elements}: |
| 31 |
|
| 32 |
\begin{enumerate} |
| 33 |
\item Immediate transfer via the \TeX\ input stream; |
| 34 |
\item Object-based transfer through dedicated macros; |
| 35 |
\item File-based transfer via external data files. |
| 36 |
\end{enumerate} |
| 37 |
|
| 38 |
Each mechanism serves a different purpose depending on the size |
| 39 |
and nature of the data being communicated. |
| 40 |
|
| 41 |
\subsection{Object Serialization via \texttt{tostring}} |
| 42 |
\label{subsec:transfers_tostring} |
| 43 |
|
| 44 |
The macro \tkzNameMacro{tkzUseLua} is the basic bridge from Lua to \TeX. |
| 45 |
It evaluates a Lua expression and prints its result into the \TeX\ input stream. |
| 46 |
Internally, it uses Lua's \texttt{tostring()} mechanism: |
| 47 |
|
| 48 |
\begin{verbatim} |
| 49 |
\def\tkzUseLua#1{\directlua{tex.sprint(#1)}} |
| 50 |
\end{verbatim} |
| 51 |
|
| 52 |
As a consequence, any \tkzNamePack{tkz-elements} object may define a Lua |
| 53 |
\texttt{\_\_tostring} metamethod to control its textual \TeX\ representation. |
| 54 |
This is used in particular for complex numbers (\tkzClass{point}). |
| 55 |
|
| 56 |
\medskip |
| 57 |
\texttt{Example with a point:} |
| 58 |
\begin{tkzexample}[latex=.5\textwidth] |
| 59 |
\directlua{ |
| 60 |
init_elements() |
| 61 |
z.A = point(1, -2) |
| 62 |
} |
| 63 |
\tkzUseLua{tostring(z.A)} |
| 64 |
\end{tkzexample} |
| 65 |
|
| 66 |
Thus, the \emph{complex affix} associated with point $A$ is printed using |
| 67 |
Lua’s \texttt{\_\_tostring} metamethod (via \texttt{tostring}). |
| 68 |
|
| 69 |
\medskip |
| 70 |
\texttt{Example with a matrix: } |
| 71 |
|
| 72 |
The macro \tkzNameMacro{tkzUseLua} prints the \emph{value} of a Lua expression |
| 73 |
as text (internally via \texttt{tostring(<expr>)}).% |
| 74 |
\footnote{Hence objects may customize their inline representation by defining a Lua \texttt{\_\_tostring} metamethod.} |
| 75 |
|
| 76 |
|
| 77 |
\medskip |
| 78 |
\begin{tkzexample}[latex=.5\textwidth] |
| 79 |
\directlua{ |
| 80 |
init_elements() |
| 81 |
local a, b, c, d = 1, 2, 3, 4 |
| 82 |
M.new = matrix({ { a, b }, { c, d } })} |
| 83 |
\tkzUseLua{M.new:print()} |
| 84 |
\end{tkzexample} |
| 85 |
|
| 86 |
\texttt{Other cases} |
| 87 |
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. |
| 88 |
|
| 89 |
\begin{verbatim} |
| 90 |
\tkzUseLua{tostring(nil)} |
| 91 |
\tkzUseLua{tostring(true)} |
| 92 |
\tkzUseLua{"TANGENT"} |
| 93 |
\tkzUseLua{math.pi} |
| 94 |
\end{verbatim} |
| 95 |
%-------------------------------------------------------------------- |
| 96 |
\subsection{Immediate Transfer} |
| 97 |
\label{subsec:transfer_immediate} |
| 98 |
|
| 99 |
Immediate transfer occurs when Lua prints data directly into the |
| 100 |
\TeX\ input stream using \texttt{tex.print}. |
| 101 |
|
| 102 |
\subsubsection*{Numerical example} |
| 103 |
|
| 104 |
\begin{tkzexample}[latex=.5\textwidth] |
| 105 |
\directlua{ |
| 106 |
init_elements() |
| 107 |
z.A = point(3,4) |
| 108 |
tex.print(point.abs(z.A)) |
| 109 |
} |
| 110 |
\end{tkzexample} |
| 111 |
|
| 112 |
The computed value is inserted directly into the document. |
| 113 |
|
| 114 |
\subsubsection*{Boolean example} |
| 115 |
|
| 116 |
\begin{tkzexample}[latex=.5\textwidth] |
| 117 |
|
| 118 |
\directlua{ |
| 119 |
init_elements() |
| 120 |
z.A = point(0, 0) |
| 121 |
z.B = point(3, 0) |
| 122 |
z.C = point(0, 2) |
| 123 |
T.ABC = triangle(z.A, z.B, z.C) |
| 124 |
tex.print(tostring(T.ABC:check_equilateral())) |
| 125 |
} |
| 126 |
\end{tkzexample} |
| 127 |
|
| 128 |
This mechanism allows Lua computations to influence |
| 129 |
\TeX\ logic through conditional statements. |
| 130 |
|
| 131 |
\medskip |
| 132 |
\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: |
| 133 |
|
| 134 |
\begin{mybox} |
| 135 |
\begin{verbatim} |
| 136 |
\def\tkzUseLua#1{\directlua{tex.print(#1)}} |
| 137 |
\end{verbatim} |
| 138 |
\end{mybox} |
| 139 |
|
| 140 |
This macro prints the value of a Lua variable or expression directly into the TeX stream. |
| 141 |
|
| 142 |
\medskip |
| 143 |
\texttt{Example.} |
| 144 |
|
| 145 |
The following Lua code computes whether two lines intersect: |
| 146 |
|
| 147 |
\directlua{ |
| 148 |
z.a = point(4, 2) |
| 149 |
z.b = point(1, 1) |
| 150 |
z.c = point(2, 2) |
| 151 |
z.d = point(5, 1) |
| 152 |
L.ab = line(z.a, z.b) |
| 153 |
L.cd = line(z.c, z.d) |
| 154 |
det = (z.b - z.a) ^ (z.d - z.c) |
| 155 |
if det == 0 then bool = true |
| 156 |
else bool = false |
| 157 |
end |
| 158 |
x = intersection (L.ab, L.cd)} |
| 159 |
|
| 160 |
The intersection of the two lines lies at |
| 161 |
a point whose affix is: \tkzUseLua{x} |
| 162 |
|
| 163 |
\vspace{1em} |
| 164 |
\begin{minipage}{0.5\textwidth} |
| 165 |
\begin{verbatim} |
| 166 |
\directlua{ |
| 167 |
z.a = point(4, 2) |
| 168 |
z.b = point(1, 1) |
| 169 |
z.c = point(2, 2) |
| 170 |
z.d = point(5, 1) |
| 171 |
L.ab = line(z.a, z.b) |
| 172 |
L.cd = line(z.c, z.d) |
| 173 |
det = (z.b - z.a) ^ (z.d - z.c) |
| 174 |
if det == 0 then bool = true |
| 175 |
else bool = false |
| 176 |
end |
| 177 |
x = intersection (L.ab, L.cd)} |
| 178 |
|
| 179 |
The intersection of the two lines lies at |
| 180 |
a point whose affix is:\tkzUseLua{tostring(x)} |
| 181 |
|
| 182 |
|
| 183 |
\begin{tikzpicture} |
| 184 |
\tkzGetNodes |
| 185 |
\tkzInit[xmin =0,ymin=0,xmax=5,ymax=3] |
| 186 |
\tkzGrid\tkzAxeX\tkzAxeY |
| 187 |
\tkzDrawPoints(a,...,d) |
| 188 |
\ifthenelse{\equal{\tkzUseLua{bool}}{% |
| 189 |
true}}{\tkzDrawSegments[red](a,b c,d)}{% |
| 190 |
\tkzDrawSegments[blue](a,b c,d)} |
| 191 |
\tkzLabelPoints(a,...,d) |
| 192 |
\end{tikzpicture} |
| 193 |
\end{verbatim} |
| 194 |
\end{minipage} |
| 195 |
\begin{minipage}{0.5\textwidth} |
| 196 |
\begin{center} |
| 197 |
\begin{tikzpicture} |
| 198 |
\tkzGetNodes |
| 199 |
\tkzInit[xmin =0,ymin=0,xmax=5,ymax=3] |
| 200 |
\tkzGrid\tkzAxeX\tkzAxeY |
| 201 |
\tkzDrawPoints(a,...,d) |
| 202 |
\ifthenelse{\equal{\tkzUseLua{bool}}{true}}{ |
| 203 |
\tkzDrawSegments[red](a,b c,d)}{% |
| 204 |
\tkzDrawSegments[blue](a,b c,d)} |
| 205 |
\tkzLabelPoints(a,...,d) |
| 206 |
\end{tikzpicture} |
| 207 |
\end{center} |
| 208 |
\end{minipage} |
| 209 |
|
| 210 |
%---------------------------------------------- |
| 211 |
% ---> INSERT additional custom examples here |
| 212 |
%---------------------------------------------- |
| 213 |
|
| 214 |
%-------------------------------------------------------------------- |
| 215 |
\subsection{Object-Based Transfer} |
| 216 |
\label{subsec:transfer_objects} |
| 217 |
|
| 218 |
Geometric objects stored in Lua tables must be converted |
| 219 |
into TikZ-compatible structures before drawing. |
| 220 |
|
| 221 |
\subsubsection{Transferring points} |
| 222 |
\label{transferring_points} |
| 223 |
|
| 224 |
Points are internally stored as complex affixes. |
| 225 |
The macro \tkzNameMacro{tkzGetNodes} converts them |
| 226 |
into TikZ coordinates. |
| 227 |
|
| 228 |
\begin{tkzexample}[latex=7cm] |
| 229 |
\directlua{ |
| 230 |
init_elements() |
| 231 |
z.o = point(0, 0) |
| 232 |
z.a_1 = point(2, 1) |
| 233 |
z.a_2 = point(1, 2) |
| 234 |
z.ap = z.a_1 + z.a_2 |
| 235 |
z.app = z.a_1 - z.a_2 |
| 236 |
} |
| 237 |
|
| 238 |
\begin{center} |
| 239 |
\begin{tikzpicture}[ scale = 1.5] |
| 240 |
\tkzGetNodes |
| 241 |
\tkzDrawSegments(o,a_1 o,a_2 o,a' o,a'') |
| 242 |
\tkzDrawSegments[red](a_1,a' a_2,a') |
| 243 |
\tkzDrawSegments[blue](a_1,a'' a_2,a'') |
| 244 |
\tkzDrawPoints(a_1,a_2,a',o,a'') |
| 245 |
\tkzLabelPoints(o,a_1,a_2,a',a'') |
| 246 |
\end{tikzpicture} |
| 247 |
\end{center} |
| 248 |
\end{tkzexample} |
| 249 |
|
| 250 |
\subsubsection{Transferring paths and curves} |
| 251 |
|
| 252 |
|
| 253 |
\begin{tkzexample}[latex=.4\textwidth] |
| 254 |
\directlua{ |
| 255 |
init_elements() |
| 256 |
PF.ex = pfct("(cos(t))^3", "(sin(t))^3") |
| 257 |
PA.curve = PF.ex:path(0, 2*math.pi, 100) |
| 258 |
} |
| 259 |
|
| 260 |
\begin{center} |
| 261 |
\begin{tikzpicture}[scale=2] |
| 262 |
\tkzDrawCoordinates[smooth,red,fill=orange](PA.curve) |
| 263 |
\end{tikzpicture} |
| 264 |
\end{center} |
| 265 |
\end{tkzexample} |
| 266 |
|
| 267 |
The Lua object is serialized into a coordinate list |
| 268 |
interpreted by TikZ. |
| 269 |
|
| 270 |
%---------------------------------------------- |
| 271 |
% ---> INSERT advanced fct / pfct examples here |
| 272 |
%---------------------------------------------- |
| 273 |
|
| 274 |
%-------------------------------------------------------------------- |
| 275 |
\subsubsection{File-Based Transfer} |
| 276 |
|
| 277 |
|
| 278 |
For large datasets or high-resolution curves, |
| 279 |
it may be preferable to generate an external file. |
| 280 |
|
| 281 |
This time, the transfer will be carried out using an external file. The following example is based on this one, but using a table. |
| 282 |
|
| 283 |
\texttt{Generating a data file: } The file \texttt{tmp.table} is created using the $f$ function. |
| 284 |
|
| 285 |
The file \texttt{tmp.table} now contains numerical data. |
| 286 |
\texttt{Using the generated file: } Here, the curve is plotted using \tkzNamePack{TikZ}. |
| 287 |
|
| 288 |
|
| 289 |
|
| 290 |
\begin{tkzexample}[latex=.5\textwidth] |
| 291 |
\directlua{ |
| 292 |
init_elements() |
| 293 |
z.a = point(1, 0) |
| 294 |
z.b = point(3, 2) |
| 295 |
z.c = point(0, 2) |
| 296 |
A,B,C = tkz.parabola (z.a, z.b, z.c) |
| 297 |
|
| 298 |
function f(t0, t1, n) |
| 299 |
local out=assert(io.open("tmp.table","w")) |
| 300 |
local y |
| 301 |
for t = t0,t1,(t1-t0)/n do |
| 302 |
y = A*t^2+B*t +C |
| 303 |
out:write(utils.checknumber(t), " ", |
| 304 |
utils.checknumber(y), " i\string\n") |
| 305 |
end |
| 306 |
out:close() |
| 307 |
end} |
| 308 |
|
| 309 |
\begin{tikzpicture} |
| 310 |
\tkzGetNodes |
| 311 |
\tkzInit[xmin=-1,xmax=5,ymin=0,ymax=5] |
| 312 |
\tkzDrawX\tkzDrawY |
| 313 |
\tkzDrawPoints[red,size=2](a,b,c) |
| 314 |
\directlua{f(-1,3,100)}% |
| 315 |
\draw[domain=-1:3] plot[smooth] |
| 316 |
file {tmp.table}; |
| 317 |
\end{tikzpicture} |
| 318 |
\end{tkzexample} |
| 319 |
|
| 320 |
|
| 321 |
|
| 322 |
|
| 323 |
|
| 324 |
File-based transfer provides scalability and allows |
| 325 |
interoperability with external plotting tools such as |
| 326 |
\texttt{pgfplots}. |
| 327 |
|
| 328 |
%---------------------------------------------- |
| 329 |
% ---> INSERT high-resolution example here |
| 330 |
%---------------------------------------------- |
| 331 |
|
| 332 |
%-------------------------------------------------------------------- |
| 333 |
\subsection{Dynamic \TeX--Lua Interaction} |
| 334 |
\label{subsec:dynamic_transfer} |
| 335 |
|
| 336 |
Transfers are bidirectional. |
| 337 |
\TeX\ may pass parameters to Lua for computation. |
| 338 |
|
| 339 |
\medskip |
| 340 |
\begin{verbatim} |
| 341 |
\newcommand{\ComputeSquare}[1]{% |
| 342 |
\directlua{tex.print(#1 * #1)}% |
| 343 |
} |
| 344 |
\end{verbatim} |
| 345 |
|
| 346 |
\medskip |
| 347 |
Usage: |
| 348 |
\newcommand{\ComputeSquare}[1]{% |
| 349 |
\directlua{tex.print(#1 * #1)}% |
| 350 |
} |
| 351 |
\begin{verbatim} |
| 352 |
The square of 5 is \ComputeSquare{5}. |
| 353 |
\end{verbatim} |
| 354 |
|
| 355 |
\medskip |
| 356 |
The square of 5 is \ComputeSquare{5}. |
| 357 |
|
| 358 |
\medskip |
| 359 |
|
| 360 |
This interaction enables dynamic parameterized geometry, |
| 361 |
where document input directly controls Lua computations. |
| 362 |
|
| 363 |
%---------------------------------------------- |
| 364 |
% ---> INSERT dynamic geometry example here |
| 365 |
%---------------------------------------------- |
| 366 |
|
| 367 |
\medskip |
| 368 |
Transfers in \tkzNamePack{tkz-elements} may therefore be |
| 369 |
immediate, object-based, or file-based, |
| 370 |
depending on the size and structure of the data. |
| 371 |
This layered architecture ensures a clean separation |
| 372 |
between computation and graphical representation. |