Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-macros-transfert.tex

raw
1 %====================================================================
2 \section{TeX Interface Macros (\texttt{tkz-elements.sty})}
3 \label{sec:sty_interface}
4
5 \subsection{Purpose}
6
7 The file \texttt{tkz-elements.sty} provides a small set of macros that
8 act as a bridge between \TeX{} and the Lua engine used by
9 \tkzNamePack{tkz-elements}. Their main goals are:
10
11 \begin{itemize}
12 \item printing Lua values safely in \TeX{};
13 \item transferring geometric objects (points, paths, circles) from Lua to TikZ;
14 \item simplifying the drawing stage when computations are done in Lua.
15 \end{itemize}
16
17 \medskip
18 Unless stated otherwise, these macros assume that \tkzNamePack{tkz-elements}
19 has been initialized in Lua (typically via
20
21 |\directlua{init_elements()}|.
22
23 %--------------------------------------------------------------------
24 \subsection{Summary of provided macros}
25
26
27 \begin{tabular}{ll}
28 \toprule
29 \texttt{Macro} & \texttt{Reference} \\
30 \midrule
31 \tkzMacro{tkz-elements}{tkzUseLua\{...\}} & \\
32 \tkzMacro{tkz-elements}{tkzPrintNumber\{...\}} & \\
33 \tkzMacro{tkz-elements}{tkzEraseLuaObj\{name\}} & \\
34 \tkzMacro{tkz-elements}{tkzDrawCoordinates(\dots)} & \\
35 \tkzMacro{tkz-elements}{tkzGetPointsFromPath\{P\}\{A\}} & \\
36 \tkzMacro{tkz-elements}{tkzDrawPointsFromPath(\dots)} & \\
37 \tkzMacro{tkz-elements}{tkzDrawSegmentsFromPaths(\dots)}& \\
38 \tkzMacro{tkz-elements}{tkzDrawCirclesFromPaths(\dots)} & \\
39 \bottomrule
40 \end{tabular}
41
42 \medskip
43 \texttt{Note:} The exact internal Lua object layout may evolve; these macros
44 are designed to remain stable at the user level.
45
46 %====================================================================
47 \subsection{Macro \tkzMacro{tkz-elements}{tkzUseLua}}
48 \label{subsec:tkzUseLua}
49
50 \medskip
51 \texttt{Syntax: }
52
53 \verb|tkzUseLua{<lua-expression>\}|
54
55
56 \medskip
57 \texttt{Description: }
58 Evaluates the Lua expression and prints its result in the \TeX{} stream.
59
60 \medskip
61 \texttt{Argument: }
62 \begin{itemize}
63 \item \tkzname{<lua-expression>}: a Lua expression returning a value.
64 \end{itemize}
65
66 \medskip
67 \texttt{Notes: }
68 \begin{itemize}
69 \item This macro is meant for \emph{values} (numbers, booleans, strings).
70 \item For Lua objects (point, line, circle, path, \dots), prefer dedicated
71 transfer/draw macros or call an explicit Lua method that returns a value.
72 \end{itemize}
73
74 \texttt{Example: }
75 \begin{minipage}{.52\textwidth}
76 \begin{verbatim}
77 \directlua{init_elements()
78 z.A = point(0,0)
79 z.B = point(4,2)
80 }
81 The slope is \tkzUseLua{(z.B.im-z.A.im)/(z.B.re-z.A.re)}.
82 \end{verbatim}
83 \end{minipage}
84
85 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
86
87 This macro evaluates a Lua expression and inserts its result in the document.
88
89
90 \texttt{Syntax: }\verb|\tkzUseLua{<lua-code>}|
91
92 \texttt{Example usage: }
93
94 \begin{mybox}
95 \begin{verbatim}
96 \tkzUseLua{utils_checknumber(math.pi)}
97 \end{verbatim}
98 \end{mybox}
99
100
101 %====================================================================
102 \subsection{Macro \tkzMacro{tkz-elements}{tkzPrintNumber}}
103 This macro formats and prints a number using PGF’s fixed-point output, with a default precision of 2 decimal places.
104
105 \medskip
106
107 %\texttt{Syntax: }\verb|\tkzPrintNumber[<precision>]{<number>}|
108 \texttt{Syntax: }
109 \begin{quote}
110 \tkzMacro{tkz-elements}{tkzPrintNumber\{<lua-expression>\}} \qquad
111 \tkzMacro{tkz-elements}{tkzPN\{<lua-expression>\}}
112 \end{quote}
113
114 \texttt{Example: }
115
116 \begin{mybox}
117 \begin{verbatim}
118 \tkzPrintNumber{pi} % outputs 3.14
119 \tkzPrintNumber[4]{sqrt(2)} % outputs 1.4142
120 \end{verbatim}
121 \end{mybox}
122
123 \texttt{Alias: } The macro \tkzMacro{tkz-elements}{tkzPN} is a shorthand for \tkzMacro{tkz-elements}{tkzPrintNumber}.
124
125
126 \texttt{Example: }
127 \begin{minipage}{.52\textwidth}
128 \begin{verbatim}
129 \directlua{init_elements()
130 x = math.pi/7
131 }
132 $\alpha = \tkzPN{x}$.
133 \end{verbatim}
134 \end{minipage}
135
136
137 %====================================================================
138 \subsection{Macro \tkzMacro{tkz-elements}{tkzEraseLuaObj}}
139
140 \label{sub:macro_tkzEraseLuaObj}
141
142 \texttt{Syntax: }
143 \begin{quote}
144 \tkzMacro{tkz-elements}{tkzEraseLuaObj\{<name>\}}
145 \end{quote}
146
147
148
149 \texttt{Description: }
150 Removes a stored Lua object from the global storage table (typically \code{z},
151 \code{L}, \code{C}, \code{CO}, etc., depending on your conventions).
152
153
154 \texttt{Syntax: } \verb|\tkzEraseLuaObj{<object>}|
155
156 \texttt{Example usage: }
157
158 \begin{mybox}
159 \begin{verbatim}
160 \tkzEraseLuaObj{z.A}
161 \tkzEraseLuaObj{T.ABC}
162 \end{verbatim}
163 \end{mybox}
164
165
166 \texttt{Notes: }
167 Use this macro to avoid name collisions when compiling large documents
168 or when reusing the same object names across figures.
169
170
171
172 %====================================================================
173 \subsection{Macro \tkzMacro{tkz-elements}{tkzPathCount}}
174 This macro retrieves the number of vertices in a Lua path and stores the result in a TeX macro.
175
176 \texttt{Syntax: }\verb|\tkzPathCount(<lua-path>){<MacroName>}|
177
178 \texttt{Arguments: }
179
180 \verb|<lua-path>|: identifier of a Lua \verb|path| object.
181 \verb|<MacroName>|: name of a TeX macro (without the backslash) that will store the count.
182
183
184 \texttt{Example usage: }
185
186 \begin{tkzexample}[latex=.5\textwidth]
187 \directlua{
188 z.A = point(0, 0)
189 z.B = point(5, 4)
190 L.AB = line(z.A, z.B)
191 PA.AB = L.AB:path(3)
192 z.O = point(2, 0)
193 }
194 \tkzPathCount(PA.AB){N}
195 \begin{center}
196 \begin{tikzpicture}
197 \tkzGetNodes
198 \tkzDrawCoordinates[blue](PA.AB)
199 \tkzDrawPointsFromPath[red,size=2](PA.AB)
200 \foreach \i in {1,...,\N}{
201 \tkzGetPointFromPath(PA.AB,\i){P\i}
202 \tkzDrawSegment[orange](O,P\i)
203 }
204 \end{tikzpicture}
205 \end{center}
206 \end{tkzexample}
207
208
209
210 %====================================================================
211 \subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCoordinates}}
212 This macro draws a curve using the TikZ \code{plot coordinates} syntax, with coordinates generated by Lua.
213
214 \medskip
215 \texttt{Conceptual perspective:}
216
217 A Lua \code{path} is a computational object: it stores geometric data
218 produced during the Lua phase (coordinates, sampling, transformations,
219 concatenations, etc.).
220
221 The TikZ command \code{plot coordinates} is a graphical instruction:
222 it simply draws what it receives as explicit coordinates.
223
224 \medskip
225 \emph{Lua computes — TikZ draws.}
226
227 \medskip
228 The macro \tkzMacro{tkz-elements}{tkzDrawCoordinates} establishes the
229 bridge between these two worlds:
230
231 \begin{itemize}
232 \item Lua constructs and manipulates the geometric object;
233 \item TikZ renders the explicit list of coordinates;
234 \item No additional geometric interpretation is performed during drawing.
235 \end{itemize}
236
237 This strict separation guarantees consistency between the computed
238 geometry and the final graphical output.
239
240
241 \texttt{Syntax: } |\tkzDrawCoordinates[<options>](lua-path)|
242
243 \texttt{Example usage: }
244
245
246 \begin{tkzexample}[latex=.5\textwidth]
247 \directlua{
248 z.A = point(0, 0)
249 z.B = point(6, 0)
250 z.C = point(1, 4)
251 T.ABC = triangle(z.A, z.B, z.C)
252 z.M = T.ABC.bc.mid
253 z.N = T.ABC.ca.mid
254 PA.path = T.ABC:path(z.M,z.N,4)
255 }
256 \begin{tikzpicture}[gridded]
257 \tkzGetNodes
258 \tkzDrawPolygon(A,B,C)
259 \tkzDrawCoordinates[orange,thick](PA.path)
260 \tkzDrawPoints(A,B,C,M,N)
261 \tkzLabelPoints(A,B)
262 \tkzLabelPoints[above](C)
263 \end{tikzpicture}
264 \end{tkzexample}
265
266
267 \medskip
268 \texttt{Description: }
269 Draws a Lua \code{path} object as a TikZ path. This macro is typically used
270 after the computational phase in Lua. Draws the polyline defined by the sequence of points in a Lua path, using explicit \code{(x,y)} coordinates.
271
272
273 \medskip
274 \texttt{Alias: } % \let\tkzDrawPath\tkzDrawCoordinates
275 \label{subsec:tkzDrawPath}
276
277 \begin{quote}
278 \tkzMacro{tkz-elements}{tkzDrawPath[<tikz-options>](lua-path)}
279 \end{quote}
280
281 %====================================================================
282
283 \subsection{Macro \tkzMacro{tkz-elements}{tkzDrawPointsFromPath}}
284 \label{sub:macro_tkzDrawPointsFromPath}
285
286 This macro draws all points of a path using \tkzname{tkzDrawPoint}, without exporting point names.
287
288 \medskip
289 \texttt{Syntax: }
290 \verb|\tkzDrawPointsFromPath[<options>](lua-path)|
291
292 \medskip
293 \texttt{Example usage: }
294
295 \begin{tkzexample}[latex=.5\textwidth]
296 \directlua{
297 init_elements()
298 LP.test = list_point()
299 LP.test:add(point(0, 0))
300 LP.test:add(point(1, 0))
301 LP.test:add(point(1, 1))
302 PA.curve = LP.test:as_path()
303 }
304 \begin{tikzpicture}
305 \tkzDrawCoordinates[blue](PA.curve)
306 \tkzDrawPointsFromPath[red,size=2](PA.curve)
307 \end{tikzpicture}
308 \end{tkzexample}
309
310 %====================================================================
311
312
313 %====================================================================
314 \subsection{Macro \tkzMacro{tkz-elements}{tkzGetPointsFromPath}}
315 This macro defines TikZ points from a Lua path. Each point is named with a base name followed by an index.
316
317 \texttt{Syntax: }\verb|\tkzGetPointsFromPath[<options>](<path>,<basename>)|
318
319 \medskip
320 \texttt{Description: }
321 Exports the points of a Lua path as named \TeX/TikZ points.
322 The naming scheme is \code{<prefix>1}, \code{<prefix>2}, \dots
323
324 \medskip
325 \texttt{Example: }
326
327 \begin{tkzexample}[latex=.5\textwidth]
328 \directlua{
329 init_elements()
330 PA.g = path({ "(0, 0)", "(1, 0)","(1, 1)" })
331 }
332 \begin{tikzpicture}
333 \tkzGetPointsFromPath(PA.g,A)
334 \tkzDrawPolygon(A_1,A_2,A_3)
335 \tkzDrawPoints(A_1,A_2,A_3)
336 \end{tikzpicture}
337 \end{tkzexample}
338
339 %====================================================================
340
341
342
343
344 \subsection{Macro \tkzMacro{tkz-elements}{tkzGetPointFromPath}}
345 This macro extracts the i-th vertex of a Lua path and defines it as a TikZ point with a given name.
346
347 \texttt{Syntax: }\verb|\tkzGetPointFromPath(<PathLua>,<index>){<PointName>}|
348
349 \texttt{Arguments: }
350
351 \verb|<PathLua>|: identifier of a Lua \verb|path| object.
352 \verb|<index>|: index of the vertex to retrieve (TeX number or numeric macro).
353 \verb|<PointName>|: name of the TikZ point to create.
354 \medskip
355
356
357 \texttt{Example usage:}
358
359 \begin{mybox}
360 \begin{verbatim}
361 % Get the 3rd vertex of PA.A and name it P3
362 \tkzGetPointFromPath(PA.A,3){P3}
363 % With counting and a loop
364 \tkzPathCount(PA.A){N}
365 \foreach \i in {1,...,\N}{
366 \expandafter\tkzGetPointFromPath\expandafter(PA.A,\i){P\i}
367 }
368 \end{verbatim}
369 \end{mybox}
370 %====================================================================
371
372
373
374
375 \subsection{Macro \tkzMacro{tkz-elements}{tkzDrawSegmentsFromPaths}}
376 \label{sub:macro_tkzDrawSegmentsFromPaths}
377
378 \texttt{Description: }
379 Draws segments encoded in one or more Lua paths (pairs of points or consecutive
380 points, depending on the chosen convention).
381
382 \texttt{Syntax: }\verb|\tkzDrawSegmentsFromPaths[<options>](<lua-path-start>,<lua-path-end>)|
383
384 \texttt{Example: }
385
386 \begin{tkzexample}[vbox]
387 \directlua{
388 init_elements()
389 z.A = point(0, 0)
390 z.B = point(3, 0)
391 C.AB = circle(z.A, z.B)
392 PA.c = path()
393 PA.u = path()
394 PA.v = path()
395 for i = 0, 18, 2 do
396 local angle = i * 2 * math.pi / 18
397 local p = point(polar(8, angle))
398 local Lu, Lv = C.AB:tangent_from(p)
399 local u , v = Lu.pb, Lv.pb
400 PA.c:add_point(p)
401 PA.u:add_point(u)
402 PA.v:add_point(v)
403 end}
404
405 \begin{center}
406 \begin{tikzpicture}[scale =.6]
407 \tkzGetNodes
408 \tkzDrawSegmentsFromPaths[draw,red](PA.c,PA.u)
409 \tkzDrawSegmentsFromPaths[draw,red](PA.c,PA.v)
410 \tkzDrawCircle[blue](A,B)
411 \end{tikzpicture}
412 \end{center}
413 \end{tkzexample}
414 %====================================================================
415 \subsection{Macro \tkzMacro{tkz-elements}{tkzDrawCirclesFromPaths}}
416 \label{sub:macro_tkzDrawCirclesFromPaths}
417 This macro draws circles defined by two paths: one for the centers and one for the points through which each circle passes.
418
419 \medskip
420 \texttt{Syntax: }\verb|\tkzDrawCirclesFromPaths[<options>](<PA.center>,<PA.through>)|
421
422 \medskip
423 \texttt{Example usage: }
424
425 \begin{mybox}
426 \begin{verbatim}
427 \tkzDrawCirclesFromPaths[blue](PA.O, PA.A)
428 \end{verbatim}
429 \end{mybox}
430
431 See the document \tkzname{Euclidean Geometry} presented in \href{http://altermundus.fr}{altermundus.fr}for other examples.
432
433 \medskip
434 \begin{tkzexample}[vbox]
435 \directlua{
436 init_elements()
437 z.A = point(-4, -4)
438 z.B = point(4, -4)
439 L.AB = line(z.A, z.B)
440 C.AB = circle(z.A, z.B)
441 S.AB = L.AB:square()
442 _, _, z.C, z.D = S.AB:get()
443 z.O = S.AB.ac.mid
444 z.a = S.AB.ab.mid
445 z.c = S.AB.cd.mid
446 z.o1 = tkz.midpoint(z.a, z.O)
447 z.o = tkz.midpoint(z.c, z.O)
448 z.b = S.AB.bc.mid
449 z.g = (z.o1 - z.O) + (z.b - z.O)
450 z.o2 = intersection(line(z.c, z.g), line(z.O,z.b))
451 z.o3 = (z.o - z.O) + (z.o2 - z.O)
452 z.j = intersection(line(z.c, z.b), line(z.o2,z.o3))
453 local C2 = circle(z.O, z.a)
454 local C1 = circle(z.o, z.c)
455 local C3 = circle(z.o3, z.j)
456 PA.pc, PA.pt, n = C1:CCC(C2, C3)
457 }
458
459 \begin{center}
460 \begin{tikzpicture}[scale=1]
461 \tkzGetNodes
462 \tkzDrawPolygon[cyan](A,B,C,D)
463 \tkzDrawCircles(O,a o,c o1,a o2,b o3,j)
464 \tkzDrawCirclesFromPaths[draw,red](PA.pc,PA.pt)
465 \end{tikzpicture}
466 \end{center}
467 \end{tkzexample}
468
469
470 %===============================================================
471
472 \subsection{Macro \tkzMacro{tkz-elements}{tkzDrawFromPointToPath}}
473 This macro draws a set of line segments from a given TikZ point to every point of a Lua \emph{path} object.
474
475 \medskip
476 \texttt{Syntax: }\verb|\tkzDrawFromPointToPath[<options>](<point-tikz>,<lua-path>)|
477
478 \medskip
479 \texttt{Arguments: }
480
481 \verb|<options>| (optional): pgf/tikz drawing options (color, thickness, etc.).
482
483 \verb|<point-tikz>|: the name of a TikZ point (already defined).
484
485 \verb|<lua-path>|: identifier of a Lua \verb|path| object.
486
487 \medskip
488 \texttt{Example usage: }
489
490 \medskip
491 \begin{tkzexample}[vbox]
492 \directlua{
493 init_elements()
494 z.O = point(0, 0)
495 z.A = point(5, 1)
496 z.Ta = point(8, 2)
497 C.A = circle(z.A, z.Ta)
498 L.OA = line(z.O,z.A)
499 z.x, z.y = intersection(C.A, L.OA,{near=z.O})
500 C.A.through = z.y
501 z.m = tkz.midpoint(z.O, z.x)
502 z.n = tkz.midpoint(z.O, z.y)
503 z.w = tkz.midpoint(z.m, z.n)
504 PA.A = path()
505 PA.c = path()
506 for t = 0, 1 - 1e-12, 0.1 do
507 PA.A:add_point(C.A:point(t))
508 local m = tkz.midpoint(z.O, C.A:point(t))
509 PA.c:add_point(m)
510 end
511 }
512 \begin{center}
513 \begin{tikzpicture}[scale=.8]
514 \tkzGetNodes
515 \tkzDrawCircle(A,Ta)
516 \tkzDrawLine(O,A)
517 \tkzDrawPoints(O,A,m,n,w,x,y)
518 \tkzLabelPoints(O,A,m,n,w)
519 \tkzDrawCircle[red](w,n)
520 \tkzDrawPointsFromPath[red](PA.c)
521 \tkzDrawPointsFromPath[blue](PA.A)
522 \tkzDrawSegmentsFromPaths[draw,teal](PA.c,PA.A)
523 \tkzDrawFromPointToPath[orange](O,PA.A)
524 \end{tikzpicture}
525 \end{center}
526 \end{tkzexample}
527
528
529
530 \subsection{Archimedes spiral, a complete example}
531
532 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.
533
534 \vspace{1em}
535 \begin{tkzexample}[vbox]
536 \directlua{
537 z.O = point(0, 0)
538 z.A = point(5, 0)
539 L.OA = line(z.O, z.A)
540 PA.spiral = path()
541 PA.center = path()
542 PA.through = path()
543 PA.ray = path()
544 for i = 1, 48 do
545 local k = i / 48
546 z["P"..i] = L.OA:point(k)
547 local angle = i * tkz.tau / 48
548 z["r"..i] = point(polar(5, angle))
549 ray = line(z.O, z["r"..i])
550 circ = circle(z.O, z["P"..i])
551 z["X"..i], _ = intersection(ray, circ, { near = z["r"..i] })
552 PA.spiral:add_point(z["X"..i])
553 PA.center:add_point(z.O)
554 PA.through:add_point(z["P"..i])
555 PA.ray:add_point(z["r"..i])
556 end}
557 \begin{center}
558 \begin{tikzpicture}[scale = .8]
559 \tkzGetNodes
560 \tkzDrawCircle(O,A)
561 \tkzDrawCirclesFromPaths[draw,
562 orange!50](PA.center,PA.through)
563 \tkzDrawSegmentsFromPaths[draw,teal](PA.center,PA.ray)
564 \tkzDrawPath[red,thick,smooth](PA.spiral)
565 \tkzDrawPointsFromPath[blue, size=2](PA.spiral)
566 \end{tikzpicture}
567 \end{center}
568
569 \end{tkzexample}
570
571
572
573 \endinput
574