Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-transfers.tex

raw
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.