Debian Codegraph @

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

raw
1 \newpage
2 \section{Various functions}
3
4 In addition to object-oriented constructions, the package provides a collection of auxiliary functions. These functions are not strictly required but serve to simplify many geometric operations and shorten code. Their use depends on the context, but in the spirit of the package, it's preferable to use objects.
5
6 \medskip
7 They allow:
8 \begin{itemize}
9 \item direct geometric computation without having to define intermediate objects (e.g., lines or triangles),
10 \item quick tests (alignment, orthogonality),
11 \item or access to commonly used constructs (midpoints, barycenters, bisectors).
12 \end{itemize}
13
14 These tools follow the same convention as the rest of the package and accept either point objects or complex numbers (when appropriate). They are typically used in Lua code blocks when you want to keep your scripts minimal and avoid explicit variable declarations.
15
16 \medskip
17 \texttt{Example: }
18
19 To compute the midpoint of a segment without defining the line:
20 \begin{mybox}
21 \begin{verbatim}
22 z.M = tkz.midpoint(z.A, z.B)
23 \end{verbatim}
24 \end{mybox}
25 This avoids having to define \code{L.AB = line(z.A, z.B)} and then access \code{L.AB.mid}.
26
27 \texttt{Overview: } The table below summarizes the available functions:
28
29
30 \bgroup
31 \catcode`_=12
32 \small
33 \captionof{table}{Functions.}\label{misc}
34 \begin{tabular}{ll}
35 \toprule
36 \textbf{Functions} & \texttt{Reference}\\
37 \midrule
38 \tkzFct{tkz}{tkz.length(z1, z2) } & [\ref{sub:length_of_a_segment}] \\
39 \tkzFct{tkz}{tkz.midpoint(z1, z2)} & [\ref{sub:midpoint_and_midpoints}] \\
40
41 \tkzFct{tkz}{tkz.midpoints(z1, z2, ..., zn)} & [\ref{sub:midpoint_and_midpoints}]\\
42
43 \tkzFct{tkz}{tkz.is\_linear(z1, z2, z3) } & [\ref{sub:alignment_or_orthogonality}] \\
44 \tkzFct{tkz}{tkz.is\_ortho(z1, z2, z3)} & [\ref{sub:alignment_or_orthogonality}]\\
45
46 \tkzFct{tkz}{tkz.bisector(z1, z2, z3)} & [\ref{sub:bisector}; \ref{sub:bisector_and_altitude}; \ref{sub:tkz.get_angle}] \\
47
48 \tkzFct{tkz}{tkz.bisector\_ext(z1, z2, z3)} & [\ref{sub:bisector_and_altitude}] \\
49
50 \tkzFct{tkz}{tkz.altitude(z1, z2, z3)} & [\ref{sub:bisector_and_altitude}] \\
51
52
53
54 \tkzFct{tkz}{tkz.get\_angle(z1, z2, z3)} & [\ref{sub:tkz.get_angle}] \\
55
56 \tkzFct{tkz}{tkz.inner\_angle(z1, z2, z3)} & [\ref{sub:tkz_inner_angle}] \\
57
58 \tkzFct{tkz}{tkz.angle\_normalize(an) } & [\ref{sub:tkz_angle_normalize}] \\
59
60 \tkzFct{tkz}{tkz.get\_angle\_normalize} & [\ref{sub:tkz.get_angle_normalize}] \\
61
62 \tkzFct{tkz}{tkz.angle\_between\_vectors} & [\ref{sub:angle_between_vectors}]\\
63
64
65 \tkzFct{tkz}{tkz.barycenter (\{z1,n1\},\{z2,n2\}, ...)} & [\ref{sub:misc_barycenter}] \\
66
67 \tkzFct{tkz}{tkz.dot\_product(z1, z2, z3)} & [\ref{sub:dot_or_scalar_product}] \\
68 \tkzFct{tkz}{tkz.parabola(pta, ptb, ptc)} & [\ref{tkz:parabola}] \\
69
70 \tkzFct{tkz}{tkz.nodes\_from\_paths} & \ref{sub:tkz_nodes_from_paths}\\
71
72 \tkzFct{tkz}{tkz.fsolve(f, a, b, n [, opts])} & \ref{sub:fsolve}\\
73
74 \tkzFct{tkz}{tkz.derivative(f, x0 [, accuracy])} & \ref{sub:derivative}\\
75 \bottomrule
76 \end{tabular}
77 \egroup
78
79
80
81 \subsection{Length of a segment}
82 \label{sub:length_of_a_segment}
83
84 The function \tkzFct{misc}{tkz.length(z1, z2)} returns the Euclidean distance between two points. It is equivalent to:
85
86 \begin{mybox}
87 \begin{verbatim}
88 point.abs(z1 - z2)
89 \end{verbatim}
90 \end{mybox}
91
92 This shortcut allows you to compute the length of a segment without manipulating complex numbers explicitly.
93
94 \medskip
95 \texttt{Alternative: }
96
97 If you need to define the segment as a \tkzClass{line} object for later use (e.g., to draw it or to access other attributes such as the midpoint or direction), you can use:
98
99 \begin{mybox}
100 \begin{verbatim}
101 L.AB = line(z.A, z.B)
102 l = L.AB.length
103 \end{verbatim}
104 \end{mybox}
105
106 \medskip
107 \texttt{Recommendation: }
108
109 Use \code{tkz.length(z1, z2)} for simple distance computations, especially within calculations or conditions. If you're building a full construction and need more geometric attributes, prefer defining the segment explicitly as a line object.
110
111 \subsection{Midpoint and midpoints}
112 \label{sub:midpoint_and_midpoints}
113
114 As with \tkzFct{misc}{length}, the function \tkzFct{misc}{tkz.midpoint(z1, z2)} provides a shortcut for computing the midpoint of a segment:
115
116 \begin{mybox}
117 \begin{verbatim}
118 z.M = tkz.midpoint(z.A, z.B)
119 \end{verbatim}
120 \end{mybox}
121
122 This is equivalent to creating a \tkzClass{line} object and accessing its midpoint:
123
124 \begin{mybox}
125 \begin{verbatim}
126 L.AB = line(z.A, z.B)
127 z.M = L.AB.mid
128 \end{verbatim}
129 \end{mybox}
130
131 \medskip
132 \texttt{Polygonal midpoints: }
133 To compute the midpoints of a polygonal chain, use the function |tkz.midpoints(...)|. This function returns the midpoints of each successive segment: $z_1z_2$, $z_2z_3$, ..., $z_{n-1}z_n$.
134
135 \begin{mybox}
136 \begin{verbatim}
137 z.MA, z.MB, z.MC = tkz.midpoints(z.A, z.B, z.C, z.D)
138 \end{verbatim}
139 \end{mybox}
140
141 \medskip
142 \texttt{Medial triangle: }
143 For triangles, it is often useful to compute the medial triangle — the triangle formed by the midpoints of the sides. After defining a triangle object:
144
145 \begin{mybox}
146 \begin{verbatim}
147 T.abc = triangle(z.a, z.b, z.c)
148 z.ma, z.mb, z.mc = T.abc:medial()
149 \end{verbatim}
150 \end{mybox}
151
152 This is equivalent to calling \tkzFct{tkz}{midpoints} directly:
153
154 \begin{mybox}
155 \begin{verbatim}
156 z.mc, z.ma, z.mb = tkz.midpoints(z.a, z.b, z.c)
157 \end{verbatim}
158 \end{mybox}
159
160 If you already have a triangle object, you may also write:
161
162 \begin{mybox}
163 \begin{verbatim}
164 z.mc, z.ma, z.mb = tkz.midpoints(T.ABC:get())
165 \end{verbatim}
166 \end{mybox}
167
168 This avoids the need to extract the triangle’s vertices manually, but |T.abc:medial()| is preferable.
169
170 \medskip
171 \texttt{Recommendation: }
172
173 Use \tkzFct{tkz}{midpoint} or \tkzFct{tkz}{midpoints} for quick calculations when no object is needed. Prefer object methods like \tkzMeth{triangle}{medial()} when working within a structured construction.
174
175 \subsection{Bisectors}
176 \label{sub:bisector}
177
178 The functions \tkzFct{tkz}{tkz.bisector(z1, z2, z3)} and \tkzFct{tkz}{tkz.bisector\_ext(z1, z2, z3)} define internal and external angle bisectors, respectively, for a given vertex.
179
180 These functions return a \tkzClass{line} object that represents the bisector of angle $\widehat{z_2 z_1 z_3}$, originating from point \code{z1}.
181
182 \medskip
183 \texttt{Internal bisector: }
184 This defines the internal bisector of angle $ \widehat{BAC}$, starting at \code{z.A}. The resulting line is stored as \code{L.Aa}.
185
186 \begin{mybox}
187 \begin{verbatim}
188 L.Aa = tkz.bisector(z.A, z.B, z.C)
189 \end{verbatim}
190 \end{mybox}
191
192 \medskip
193 \texttt{External bisector: }
194
195 This defines the external bisector at vertex \code{z.A}. It is orthogonal to the internal one and also originates at \code{z.A}.
196
197 \begin{mybox}
198 \begin{verbatim}
199 L.Aa = tkz.bisector_ext(z.A, z.B, z.C)
200 \end{verbatim}
201 \end{mybox}
202
203 \medskip
204 \texttt{Recommendation: }
205 Use these functions when you need the bisector explicitly as a \tkzClass{line} object (e.g., for intersection or drawing). If you are working within a triangle object, some methods may also provide access to bisectors directly.
206
207 \subsection{Barycenter}
208 \label{sub:misc_barycenter}
209
210 The function \tkzFct{tkz}{tkz.barycenter} computes the barycenter (or center of mass) of any number of weighted points. It is a general-purpose function that works independently of geometric objects.
211
212 \medskip
213 \texttt{Syntax: }
214
215 The function takes a variable number of arguments. Each argument must be a table of the form:
216
217 \begin{center}
218 \code{\{point, weight\}}
219 \end{center}
220
221
222 Example with three equally weighted points:
223 \begin{mybox}
224 \begin{verbatim}
225 z.G = tkz.barycenter({z.A, 1}, {z.B, 1}, {z.C, 1})
226 \end{verbatim}
227 \end{mybox}
228
229 This computes the centroid of triangle $ABC$. The same result can be obtained using the object attribute:
230
231 \begin{mybox}
232 \begin{verbatim}
233 T.ABC = triangle(z.A, z.B, z.C)
234 z.G = T.ABC.centroid
235 \end{verbatim}
236 \end{mybox}
237
238 \medskip
239 \texttt{General case: }
240
241 The function can be applied to any number of points with arbitrary weights:
242
243 \begin{mybox}
244 \begin{verbatim}
245 z.G = tkz.barycenter({z.A, 2}, {z.B, 3}, {z.C, 1}, {z.D, 4})
246 \end{verbatim}
247 \end{mybox}
248
249 This computes:
250 \[
251 G = \frac{2A + 3B + C + 4D}{10}
252 \]
253
254 \medskip
255 \texttt{Use cases: }
256
257 \begin{itemize}
258 \item Use \tkzFct{tkz}{tkz.barycenter} when dealing with arbitrary sets of weighted points.
259 \item In triangle geometry, prefer \code{T.ABC.centroid}, which is automatically computed and stored.
260 \end{itemize}
261
262 \medskip
263 \texttt{Note: }
264
265 The result is returned as a \tkzClass{point} object and can be used in any subsequent construction.
266
267
268
269 %%%----------------------------------------------------
270 %%%----------------- ANGLES ----------------------
271 %%%----------------------------------------------------
272
273
274 \subsection{Angles and the constant \code{tkz.tau}}
275
276 Most trigonometric and geometric computations in \tkzname{tkz-elements}
277 are expressed in radians. A full turn is therefore represented by the
278 constant
279 \[
280 \tau = 2\pi.
281 \]
282
283 For convenience, the value of~$\tau$ is available to the user as
284
285
286 \verb|tkz.tau = 2 * math.pi|
287
288
289 This constant is particularly useful when dealing with normalized or
290 periodic angles. For instance:
291
292 \begin{itemize}
293 \item \code{tkz.tau / 4} corresponds to a right angle ($90^\circ$),
294 \item \code{tkz.tau / 2} corresponds to $180^\circ$,
295 \item \code{3 * tkz.tau / 2} corresponds to $270^\circ$,
296 \item \code{a \% tkz.tau} normalizes any angle \code{a} to the interval $[0,\tau)$.
297 \end{itemize}
298
299 Using~$\tau$ avoids the explicit appearance of $2\pi$ in numerical code
300 and improves readability in geometric computations.
301
302 %%----------------------------------------------------
303 %%----------------- GET_ANGLE base ----------------------
304 %%----------------------------------------------------
305
306 \subsection{Function \tkzFct{tkz}{tkz.get\_angle(pa, pb, pc)}}
307 \label{sub:tkz.get_angle}
308
309 The function \tkzFct{tkz}{tkz.get\_angle} returns the oriented angle at a point,
310 given three points \tkzname{A}, \tkzname{B}, \tkzname{C}.
311
312 It computes the oriented angle $\widehat{BAC}$ at vertex $A$, corresponding to the
313 rotation from vector $\overrightarrow{AB}$ to vector $\overrightarrow{AC}$, in radians.
314
315 \medskip
316 \texttt{Syntax: }
317
318 \begin{mybox}
319 \verb|an = tkz.get_angle(pa, pb, pc)|
320 \end{mybox}
321
322
323 \texttt{Arguments: }
324 \begin{itemize}
325 \item \code{pa}, \code{pb}, \code{pc} — three points (Lua complex numbers).
326 \end{itemize}
327
328 \texttt{Return value:}
329 \begin{itemize}
330 \item an oriented angle (Lua number) in radians, in the interval $(-\pi, \pi]$.
331 \end{itemize}
332
333 \medskip
334
335 \texttt{Example: }
336
337 The following code computes both angles $ \widehat{CAB}$ and $ \widehat{CAB}$ using point \code{a} as the vertex, and formats them for display using \code{tkzround}:
338
339
340 \begin{tkzexample}[latex = .5\textwidth]
341 \directlua{
342 init_elements()
343 z.a = point(0, 0)
344 z.b = point(-2, -2)
345 z.c = point(0, 3)
346 ang_cb = tkz.round(
347 tkz.get_angle(z.a, z.c, z.b), 3)
348 ang_bc = tkz.round(
349 tkz.get_angle(z.a, z.b, z.c), 3)
350 }
351 \begin{center}
352 \begin{tikzpicture}[scale = 1.2]
353 \tkzGetNodes
354 \tkzDrawLines[red](a,b a,c)
355 \tkzDrawPoints(a,b,c)
356 \tkzLabelPoints(a,b,c)
357 \tkzMarkAngle[->](c,a,b)
358 \tkzLabelAngle(c,a,b){%
359 \tkzUseLua{ang_cb}}
360 \tkzMarkAngle[->](b,a,c)
361 \tkzLabelAngle(b,a,c){%
362 \tkzUseLua{ang_bc}}
363 \end{tikzpicture}
364 \end{center}
365 \end{tkzexample}
366
367 %%----------------------------------------------------
368 %%----------------- INNER_ANGLE ----------------------
369 %%----------------------------------------------------
370
371
372 \subsection{Function \tkzFct{tkz}{tkz.inner\_angle(pa, pb, pc)}}
373 \label{sub:tkz_inner_angle}
374
375 The function \verb|\tkzFct{tkz}{tkz.inner_angle}| returns the interior (non-oriented) angle
376 at a point, given three points \tkzname{pa}, \tkzname{pb}, \tkzname{pc}.
377
378 It corresponds to the absolute value of the oriented angle $\widehat{BAC}$ in radians.
379
380 \medskip
381 \texttt{Syntax: }
382
383 \begin{mybox}
384 \verb|an = tkz.inner_angle(pa, pb, pc)|
385 \end{mybox}
386
387 \texttt{Arguments:}
388 \begin{itemize}
389 \item \code{pa}, \code{pb}, \code{pc} — three points.
390 \end{itemize}
391
392 \texttt{Return value:}
393 \begin{itemize}
394 \item a non-oriented angle in radians, in the interval $[0, \pi]$.
395 \end{itemize}
396
397 \medskip
398 This function is especially useful for working with triangle angles:
399 \[
400 \alpha = \texttt{tkz.inner\_angle}(A,B,C),\quad
401 \beta = \texttt{tkz.inner\_angle}(B,C,A),\quad
402 \gamma = \texttt{tkz.inner\_angle}(C,A,B).
403 \]
404
405
406 %%----------------------------------------------------
407 %%----------------- NORMALIZE_ANGLE ----------------------
408 %%----------------------------------------------------
409
410
411 \subsection{Function \tkzFct{tkz}{tkz.angle\_normalize}}
412 \label{sub:tkz_angle_normalize}
413
414 The function \verb|\tkzFct{tkz}{tkz.angle\_normalize}| normalizes a real angle to the interval
415 $[0, 2\pi)$.
416
417 \medskip
418 \texttt{Syntax: }
419
420 \verb|an2 = tkz.angle_normalize(an1)|
421
422
423 \texttt{Arguments: }
424 \begin{itemize}
425 \item \code{an1} — a real number (angle in radians).
426 \end{itemize}
427
428 \texttt{Return value:}
429 \begin{itemize}
430 \item \code{an2} — the same angle, reduced modulo $2\pi$ into $[0, 2\pi)$.
431 \end{itemize}
432
433 \medskip
434 \texttt{Application: }
435
436 To compute the orientation of a line segment in the plane, we use the function \tkzFct{point}{arg(z)} which returns the angle (in radians) between the positive horizontal axis and the vector represented by the complex number \code{z}. This value may be negative or greater than $2\pi$ depending on the direction of the vector.
437
438 \medskip
439 To ensure consistency, especially when comparing angles or sorting them, the function
440
441 \tkzFct{tkz}{tkz.angle\_normalize(an)} maps any angle to the interval $[0, 2\pi]$.
442
443 \medskip
444 \texttt{Example: }
445
446 The following example computes and displays the slope (angle) of three vectors \code{(ab)}, \code{(ac)}, and \code{(ad)}. It shows both the raw angle and the normalized version.
447 \begin{Verbatim}
448 \directlua{%
449 init_elements()
450 z.a = point(0, 0)
451 z.b = point(-3, -3)
452 z.c = point(0, 3)
453 z.d = point(2, -2)
454 local angle = point.arg(z.b - z.a)
455 tex.print('slope of (ab): '..tostring(angle)..'\\\\')
456 tex.print('slope normalized of (ab): '..tostring(tkz.angle_normalize(angle))..'\\\\')
457 local angle = point.arg (z.c-z.a)
458 tex.print('slope of (ac): '..tostring(angle)..'\\\\')
459 tex.print('slope normalized of (ac): '..tostring(tkz.angle_normalize(angle))..'\\\\')
460 local angle = point.arg (z.d-z.a)
461 tex.print('slope of (ad): '..tostring(angle)..'\\\\')
462 tex.print('slope normalized of (ad): '..tostring(tkz.angle_normalize(angle))..'\\\\')
463 }
464 \end{Verbatim}
465 \directlua{%
466 init_elements()
467 z.a = point(0, 0)
468 z.b = point(-3, -3)
469 z.c = point(0, 3)
470 z.d = point(2, -2)
471 local angle = point.arg (z.b-z.a)
472 tex.print('slope of (ab): '..tostring(angle)..'\\\\')
473 tex.print('slope normalized of (ab): '..tostring(tkz.angle_normalize(angle))..'\\\\')
474 local angle = point.arg (z.c-z.a)
475 tex.print('slope of (ac): '..tostring(angle)..'\\\\')
476 tex.print('slope normalized of (ac): '..tostring(tkz.angle_normalize(angle))..'\\\\')
477 local angle = point.arg (z.d-z.a)
478 tex.print('slope of (ad): '..tostring(angle)..'\\\\')
479 tex.print('slope normalized of (ad): '..tostring(tkz.angle_normalize(angle))..'\\\\')
480 }
481
482 \begin{minipage}{.5\textwidth}
483 \begin{Verbatim}
484 \begin{tikzpicture}[scale = .75]
485 \tkzGetNodes
486 \tkzDrawLines[red](a,b a,c a,d)
487 \tkzDrawPoints(a,b,c,d)
488 \tkzLabelPoints(a,b,c,d)
489 \end{tikzpicture}
490 \end{Verbatim}
491
492 \end{minipage}
493 \begin{minipage}{.5\textwidth}
494 \begin{center}
495 \begin{tikzpicture}[scale = .75]
496 \tkzGetNodes
497 \tkzDrawLines[red](a,b a,c a,d)
498 \tkzDrawPoints(a,b,c,d)
499 \tkzLabelPoints(a,b,c,d)
500 \end{tikzpicture}
501 \end{center}
502 \end{minipage}
503
504 \medskip
505 \texttt{Note: }
506
507 This technique is essential when working with angular comparisons, sorting directions (e.g., in convex hull algorithms), or standardizing outputs for further geometric processing.
508
509 %%----------------------------------------------------
510 %%----------------- DIRECT_ANGLE ----------------------
511 %%----------------------------------------------------
512
513
514
515
516 \subsection{Function \tkzFct{tkz}{tkz.is\_direct}}
517 \label{sub:tkz_is_direct}
518
519 The function \tkzFct{tkz}{tkz.is\_direct} tests whether the oriented angle at a point
520 is direct (counter-clockwise).
521
522 \medskip
523 \texttt{Syntax: }
524
525 \begin{mybox}
526 \verb|ok = tkz.is_direct(pa, pb, pc)|
527 \end{mybox}
528
529 \medskip
530 \texttt{Arguments: }
531 \begin{itemize}
532 \item \code{pa}, \code{pb}, \code{pc} — three points.
533 \end{itemize}
534
535 \medskip
536 \texttt{Return value: }
537 \begin{itemize}
538 \item \code{true} if the oriented angle $\widehat{BAC}$ (from $\overrightarrow{AB}$ to $\overrightarrow{AC}$) is $> 0$ (direct, counter-clockwise),
539 \item \code{false} otherwise.
540 \end{itemize}
541
542 %%----------------------------------------------------
543 %%----------------- tkz.get_angle_normalize -------
544 %%----------------------------------------------------
545
546
547 \subsection{Function \tkzFct{tkz}{tkz.get\_angle\_normalize}}
548 \label{sub:tkz.get_angle_normalize}
549
550 The function \tkzFct{tkz}{tkz.get\_angle\_normalize} combines
551 \tkzFct{tkz}{tkz.get\_angle} and \tkzFct{tkz}{tkz.angle\_normalize}.
552
553 It returns the oriented angle at a point, normalized to $[0, 2\pi)$.
554
555 \medskip
556 \texttt{Syntax: }
557
558 \begin{mybox}
559 \verb|an = tkz.get_angle_normalize(pa, pb, pc)|
560 \end{mybox}
561
562 \medskip
563 \texttt{Arguments: }
564 \begin{itemize}
565 \item \code{pa}, \code{pb}, \code{pc} — three points.
566 \end{itemize}
567
568 \medskip
569 \texttt{Return value: }
570 \begin{itemize}
571 \item a real number in $[0, 2\pi)$: the normalized oriented angle at \code{pa}.
572 \end{itemize}
573
574 %%----------------------------------------------------
575 %%----------------- tkz.angle_between_vectors -------
576 %%----------------------------------------------------
577
578 \subsection{Function \tkzFct{tkz}{tkz.angle\_between\_vectors}}
579 \label{sub:tkz_angle_between_vectors}
580
581 The function \tkzFct{tkz}{tkz.angle\_between\_vectors} returns the oriented angle
582 between two vectors $\overrightarrow{AB}$ and $\overrightarrow{CD}$.
583
584 \medskip
585 \texttt{Syntax:}
586
587 \begin{mybox}
588 \verb|an = tkz.angle_between_vectors(a, b, c, d)|
589 \end{mybox}
590
591 \medskip
592 \texttt{Arguments: }
593 \begin{itemize}
594 \item \code{a}, \code{b} — endpoints of the first vector (from \code{a} to \code{b}),
595 \item \code{c}, \code{d} — endpoints of the second vector (from \code{c} to \code{d}).
596 \end{itemize}
597
598 \medskip
599 \texttt{Return value: }
600 \begin{itemize}
601 \item an oriented angle in radians, in the interval $(-\pi, \pi]$, corresponding to the
602 rotation from $\overrightarrow{AB}$ to $\overrightarrow{CD}$.
603 \end{itemize}
604
605 \medskip
606 Internally, the angle is computed using the standard $\operatorname{atan2}$ formula
607 based on the dot product and the determinant of the two vectors.
608
609
610 %%----------------------------------------------------
611 %%----------------- end ANGLES -------
612 %%----------------------------------------------------
613
614
615
616 \subsection{Function \tkzFct{tkz}{tkz.dot\_product(z1, z2, z3)}}
617 \label{sub:dot_or_scalar_product}
618
619 The function computes the dot (scalar) product of the vectors $\overrightarrow{z_1z_3}$ and $\overrightarrow{z_1z_2}$:
620 \[
621 (z_3 - z_1) \cdot (z_2 - z_1)
622 \]
623
624 \texttt{Note: }
625
626 This is equivalent to \code{(z2 - z1)..(z3 - z1)} See also [\ref{ssub:attributes_vector_z}]
627 \label{par:note_dot}
628
629
630 It is used to test orthogonality or to measure projection components. A result of zero indicates that the vectors are perpendicular.
631
632 \medskip
633 \texttt{Syntax: }
634
635 \begin{center}
636 \code{tkz.dot\_product(origin, point1, point2)}
637 \end{center}
638 %
639 This returns the scalar product $\overrightarrow{z_1z_3} \cdot \overrightarrow{z_1z_2}$.
640
641 \texttt{Example.}
642
643 In the example below, the triangle $ABC$ is constructed along with its triangle of antiparallels. The dot product of $\overrightarrow{AC}$ and $\overrightarrow{AB}$ is computed:
644
645 \begin{minipage}{0.5\textwidth}
646 \begin{Verbatim}
647 \directlua{%
648 init_elements()
649 z.A = point(0, 0)
650 z.B = point(5, 0)
651 z.C = point(0, 3)
652 T.ABC = triangle(z.A, z.B, z.C)
653 z.A_1,
654 z.B_1,
655 z.C_1 = T.ABC:anti():get()
656 x = tkz.dot_product(z.A, z.B, z.C)}
657 \begin{tikzpicture}
658 \tkzGetNodes
659 \tkzDrawPolygon(A,B,C)
660 \tkzDrawPoints(A,B,C,A_1,B_1,C_1)
661 \tkzLabelPoints(A,B,C,A_1,B_1,C_1)
662 \tkzDrawPolygon[blue](A_1,B_1,C_1)
663 \tkzText[right](0,-1){dot product =
664 \tkzUseLua{x}}
665 \end{tikzpicture}
666 \end{Verbatim}
667 \end{minipage}
668 \begin{minipage}{0.5\textwidth}
669 \directlua{%
670 init_elements()
671 z.A = point(0, 0)
672 z.B = point(5, 0)
673 z.C = point(0, 3)
674 T.ABC = triangle(z.A, z.B, z.C)
675 z.A_1,
676 z.B_1,
677 z.C_1 = T.ABC:anti():get()
678 x = tkz.dot_product(z.A, z.B, z.C)}
679 \begin{center}
680 \begin{tikzpicture}[ scale = .6]
681 \tkzGetNodes
682 \tkzDrawPolygon(A,B,C)
683 \tkzDrawPoints(A,B,C,A_1,B_1,C_1)
684 \tkzLabelPoints(A,B,C,A_1,B_1,C_1)
685 \tkzDrawPolygon[blue](A_1,B_1,C_1)
686 \tkzText[right](0,-1){dot product =\tkzUseLua{x}}
687 \end{tikzpicture}
688 \end{center}
689 \end{minipage}
690
691 \medskip
692 \texttt{Interpretation: }
693
694 In this example, the dot product of vectors $\overrightarrow{AC}$ and $\overrightarrow{AB}$ is \tkzUseLua{x}. Since the result is zero, the vectors are orthogonal.
695
696 %
697
698 \subsection{Alignment and orthogonality tests}
699 \label{sub:alignment_or_orthogonality}
700
701 The functions \tkzFct{tkz}{tkz.is\_linear} and \tkzFct{tkz}{tkz.is\_ortho} are used to test the geometric relationships between three points, namely alignment and orthogonality.
702
703 \medskip
704 \textbf{\tkzFct{tkz}{tkz.is\_linear(z1, z2, z3)}}
705 This function returns \code{true} if the three points are aligned — that is, if the vectors $\\overrightarrow{z_1z_2}$ and $\\overrightarrow{z_1z_3}$ are collinear. Geometrically, this means the three points lie on the same straight line:
706 \[
707 (z_2 - z_1) \parallel (z_3 - z_1)
708 \]
709
710 \begin{mybox}
711 \begin{verbatim}
712 if tkz.is_linear(z.A, z.B, z.C) then
713 -- the points are collinear
714 end
715 \end{verbatim}
716 \end{mybox}
717
718 This code replaces:
719
720 \begin{mybox}
721 \begin{verbatim}
722 L.AB = line(z.A, z.B)
723 L.BC = line(z.B, z.C)
724 if L.AB:is_parallel(L.BC) then
725 -- the points are collinear
726 end
727 \end{verbatim}
728 \end{mybox}
729
730 \medskip
731 \textbf{\tkzFct{tkz}{tkz.is\_ortho(z1, z2, z3)}}
732 This function returns \code{true} if the vectors $\overrightarrow{z_1z_2}$ and $\overrightarrow{z_1z_3}$ are orthogonal — that is, the scalar product between them is zero:
733 \[
734 (z_2 - z_1) \cdot (z_3 - z_1) = 0
735 \]
736
737 \begin{mybox}
738 \begin{verbatim}
739 if tkz.is_ortho(z.A, z.B, z.C) then
740 -- the angle between the segments is 90°
741 end
742 \end{verbatim}
743 \end{mybox}
744
745 This code replaces:
746
747 \begin{mybox}
748 \begin{verbatim}
749 L.AB = line(z.A, z.B)
750 L.BC = line(z.B, z.C)
751 if L.AB:is_orthogonal(L.BC) then
752 -- the angle between the segments is 90°
753 end
754 \end{verbatim}
755 \end{mybox}
756
757 \medskip
758 \texttt{Use case: }
759
760 These functions are particularly useful in decision structures or automated constructions (e.g., checking if a triangle is right-angled or degenerate). They return boolean values and do not create any geometric object.
761
762 \subsection{Bisector and altitude}
763 \label{sub:bisector_and_altitude}
764
765 The functions \tkzFct{misc}{bisector}, \tkzFct{misc}{bisector\_ext}, and \tkzFct{misc}{altitude} return \tkzClass{line} objects corresponding to classical triangle constructions. They are useful when you don't need to create a full \tkzClass{triangle} object and simply want the desired line or foot point directly.
766
767 \medskip
768 \texttt{Internal bisector: }
769
770 \code{tkz.bisector(z1, z2, z3)} returns the internal angle bisector at point \code{z1}, computed between vectors $\overrightarrow{z_1z_2}$ and $\overrightarrow{z_1z_3}$. The result is a \tkzClass{line} object; its foot (point \code{pb}) lies on the opposite side.
771
772 \medskip
773 \texttt{External bisector: }
774
775 \code{tkz.bisector\_ext(z1, z2, z3)} returns the external angle bisector at \code{z1}. It is orthogonal to the internal bisector.
776
777 \medskip
778 \texttt{Altitude: }
779
780 \code{tkz.altitude(vertex, foot1, foot2)} returns the perpendicular from \code{vertex} to the line passing through \code{foot1} and \code{foot2}. The result is also a \tkzClass{line} object; the foot is stored in its \code{pb} attribute.
781
782 \begin{verbatim}
783 \directlua{
784 z.a = point(0, 0)
785 z.b = point(5, -2)
786 z.c = point(2, 3)
787 z.i = tkz.bisector(z.a, z.c, z.b).pb
788 z.h = tkz.altitude(z.b, z.a, z.c).pb
789 angic = tkz.round(tkz.get_angle(z.a, z.i, z.c), 2)
790 angci = tkz.round(tkz.get_angle(z.a, z.b, z.i), 2)
791 z.e = tkz.bisector_ext(z.a, z.b, z.c).pb
792
793 \begin{tikzpicture}
794 \tkzGetNodes
795 \tkzDrawPolygon(a,b,c)
796 \tkzDrawSegments(a,i b,h a,e)
797 \tkzDrawPoints(a,b,c,i,h)
798 \tkzLabelPoints(a,b)
799 \tkzLabelPoints[above](c,i,h)
800 \tkzMarkAngle[->](i,a,c)
801 \tkzLabelAngle[font=\tiny,pos=.75](i,a,c){\tkzUseLua{angci}}
802 \tkzMarkAngle[<-](b,a,i)
803 \tkzLabelAngle[font=\tiny,pos=.75](b,a,i){\tkzUseLua{angic}}
804 \end{tikzpicture}
805 \end{verbatim}
806
807
808 \directlua{
809 init_elements()
810 z.a = point(0, 0)
811 z.b = point(5, -2)
812 z.c = point(2, 3)
813 z.i = tkz.bisector(z.a, z.c, z.b).pb
814 z.h = tkz.altitude(z.b, z.a, z.c).pb
815 angic = tkz.round(tkz.get_angle(z.a, z.i, z.c), 2)
816 angci = tkz.round(tkz.get_angle(z.a, z.b, z.i), 2)
817 z.e = tkz.bisector_ext(z.a, z.b, z.c).pb}
818
819 \begin{center}
820 \begin{tikzpicture}
821 \tkzGetNodes
822 \tkzDrawPolygon(a,b,c)
823 \tkzDrawSegments(a,i b,h a,e)
824 \tkzDrawPoints(a,b,c,i,h)
825 \tkzLabelPoints(a,b)
826 \tkzLabelPoints[above](c,i,h)
827 \tkzMarkAngle[->](i,a,c)
828 \tkzLabelAngle[font=\tiny,pos=.75](i,a,c){\tkzUseLua{angci}}
829 \tkzMarkAngle[<-](b,a,i)
830 \tkzLabelAngle[font=\tiny,pos=.75](b,a,i){\tkzUseLua{angic}}
831 \end{tikzpicture}
832 \end{center}
833
834 \medskip
835 \texttt{Note: }
836
837 These functions return full \tkzClass{line} objects, allowing access to their points and directions. This makes them ideal for flexible constructions where you do not need a structured \code{triangle} object.
838
839 \subsection{Function \tkzFct{tkz}{tkz.is\_linear}}
840 \label{sub:function_islinear}
841
842 The function \tkzFct{tkz}{tkz.is\_linear(z1, z2, z3)} checks whether three points are collinear. It returns \code{true} if the vectors $\overrightarrow{z_1z_2}$ and $\overrightarrow{z_1z_3}$ are parallel — i.e., if the points lie on the same line:
843 \[
844 (z_2 - z_1) \parallel (z_3 - z_1)
845 \]
846
847 This is equivalent to testing whether the oriented area of triangle $(z_1, z_2, z_3)$ is zero.
848
849 \medskip
850 \texttt{Syntax: }
851
852 \begin{center}
853 \code{tkz.is\_linear(z1, z2, z3)} $\rightarrow$ \code{boolean}
854 \end{center}
855
856 \texttt{Example: }
857
858 The following code tests whether the points $A$, $B$ and $C$ are aligned. If so, the new point $D$ is set to $(0, 0)$; otherwise it is set to $(-1, -1)$.
859
860 % \begin{minipage}{0.48\textwidth}
861 % \begin{tkzexample}[code only]
862 % \directlua{
863 % init_elements()
864 % z.a = point(1, 1)
865 % z.b = point(2, 2)
866 % z.c = point(4, 4)
867 % if tkz.is_linear(z.a, z.b, z.c) then
868 % z.d = point(0, 0)
869 % else
870 % z.d = point(-1, -1)
871 % end
872 % }
873 % \end{tkzexample}
874 %
875 % \begin{tkzexample}[code only]
876 % \begin{tikzpicture}
877 % \tkzGetNodes
878 % \tkzDrawPoints(a,b,c,d)
879 % \tkzLabelPoints(a,b,c,d)
880 % \end{tikzpicture}
881 % \end{tkzexample}
882 % \end{minipage}
883 % \hfill
884 % \begin{minipage}{0.48\textwidth}
885 % \begin{center}
886 % \begin{tikzpicture}
887 % \tkzGetNodes
888 % \tkzDrawPoints(a,b,c,d)
889 % \tkzLabelPoints(a,b,c,d)
890 % \end{tikzpicture}
891 % \end{center}
892 % \end{minipage}
893
894 \medskip
895 \texttt{Note: }
896
897 The function does not create any geometric object. It is intended for use in conditionals or assertions to verify configurations before constructing further elements.
898
899 \subsection{Function \tkzFct{tkz}{tkz.round(num, idp)}}
900 \label{sub:function_tkz_round}
901
902 This function performs rounding of a real number to a specified number of decimal places and returns the result as a numerical value.
903
904 \medskip
905 \texttt{Syntax: }
906
907 \begin{center}
908 \code{local r = tkz.round(3.14159, 2)} \hspace{4em} $\rightarrow$ \code{3.14}
909 \end{center}
910
911
912 \texttt{Arguments: }
913
914 \begin{itemize}
915 \item \code{num} – A real number to round.
916 \item \code{idp} – Optional number of decimal digits (default: 0).
917 \end{itemize}
918
919 \medskip
920 \texttt{Returns: }
921
922 A rounded number, of type \code{number}.
923
924 \medskip
925 \texttt{Example.}
926
927 \begin{verbatim}
928 tkz.round(3.14159, 0) --> 3
929 tkz.round(3.14159, 2) --> 3.14
930 tkz.round(-2.71828, 3) --> -2.718
931 \end{verbatim}
932
933 \medskip
934 \texttt{Related functions: }
935
936 \tkzFct{utils}{format\_number(x, decimals)} – Converts rounded number to string
937
938
939 \subsection{Function \tkzFct{tkz}{tkz.angle\_between\_vectors(a, b, c, d)}}
940 \label{sub:angle_between_vectors}
941
942 \texttt{Purpose: }
943
944 The function computes the angle between the oriented vector $\vec{AB}$ (from \code{a} to \code{b}) and the oriented vector $\vec{CD}$ (from \code{c} to \code{d}).
945
946 This function is especially useful for computing turning angles or verifying geometric configurations such as orthogonality (angle = ±π/2), alignment (angle = 0 or π), and orientation.
947
948 \medskip
949 \begin{tabular}{@{}ll@{}}
950 \texttt{Arguments: } & \code{a}, \code{b}, \code{c}, \code{d} (points as complex numbers) \\
951 \texttt{Returns: } & Angle in radians (real number) \\
952 \end{tabular}
953
954
955 \texttt{Example: }
956
957 In this example, several methods are used to determine the angles for each vertex.
958
959 \medskip
960 \begin{tkzexample}[vbox]
961 \directlua{
962 z.A = point(0, 0)
963 z.B = point(5, 0)
964 z.C = point(1, 4)
965 T.ABC = triangle(z.A, z.B, z.C)
966 }
967 \begin{center}
968 \begin{tikzpicture}
969 \tkzGetNodes
970 %\tkzDrawCircles()
971 \tkzDrawPolygon(A,B,C)
972 \tkzDrawPoints(A,B,C)
973 \tkzLabelPoints(A,B)
974 \tkzLabelPoints[above](C)
975 \tkzLabelAngle(B,A,C){$\tkzPrintNumber[2]{%
976 \tkzUseLua{math.deg(T.ABC.alpha)}}$}
977 \tkzLabelAngle(C,B,A){$\tkzPrintNumber[2]{%
978 \tkzUseLua{math.deg(tkz.get_angle(z.B,z.C,z.A))}}$}
979 \tkzLabelAngle(A,C,B){$\tkzPrintNumber[2]{%
980 \tkzUseLua{math.deg(tkz.angle_between_vectors(z.C,z.A,z.C,z.B))}}$}
981 \end{tikzpicture}
982 \end{center}
983 \end{tkzexample}
984
985 \subsection{Function \tkzFct{tkz}{tkz.parabola(pta, ptb, ptc)}}
986 \label{tkz:parabola}
987 Given three non-collinear points, there exists a unique parabola passing through them.
988 The function \tkzFct{tkz}{parabola} computes the coefficients \(A,B,C\) of the quadratic
989 function \(y = Ax^2 + Bx + C\) that interpolates these points.
990
991 \begin{tkzexample}[latex=.5\textwidth]
992 \directlua{
993 init_elements()
994 z.a = point(1, 0)
995 z.b = point(3, 2)
996 z.c = point(0, 2)
997 local A,
998 B,
999 C = tkz.parabola(z.a, z.b, z.c)
1000
1001 function def_curve(t0, t1, n)
1002 local p = path()
1003 local dt = (t1-t0)/n
1004 for t = t0, t1, dt do
1005 local y = A * t^2 + B * t + C
1006 local pt = point(t, y)
1007 p:add_point(pt)
1008 end
1009 return p
1010 end
1011
1012 PA.curve = def_curve(-1,3,100)
1013 }
1014
1015 \begin{tikzpicture}
1016 \tkzGetNodes
1017 \tkzInit[xmin = -2,xmax=4,ymin =-1,ymax=6]
1018 \tkzDrawX\tkzDrawY
1019 \tkzDrawPoints[red,size=4pt](a,b,c)
1020 \tkzDrawCoordinates[smooth,purple](PA.curve)
1021 \end{tikzpicture}
1022 \end{tkzexample}
1023
1024 \subsection{Function \tkzFct{tkz}{tkz.nodes\_from\_paths}}
1025 \label{sub:tkz_nodes_from_paths}
1026
1027 \texttt{Syntax: }
1028 \verb|tkz.nodes_from_paths(PAcenters, PAthrough [, wbase, tbase, indice])|
1029
1030 \texttt{Purpose: }
1031 This function transfers the points contained in two Lua paths — one representing the circle centers and the other the corresponding through points — into the global Lua table \tkzVar{z}.
1032 Each pair of points is assigned a name based on two prefixes (for instance ``w'' and ``t'') followed by an index number.
1033
1034 \texttt{Arguments: }
1035 \begin{itemize}
1036 \item \verb|PAcenters| – a path containing the centers of the circles.
1037 \item \verb|PAthrough| – a path containing the corresponding through points.
1038 \item \verb|wbase| (optional) – base name for the centers (default: \verb|"w"|).
1039 \item \verb|tbase| (optional) – base name for the through points (default: \verb|"t"|).
1040 \item \verb|indice| (optional) – starting index (default: \verb|1|).
1041 \end{itemize}
1042
1043 \texttt{Returned values: }
1044 None.
1045 The function creates Lua entries in the global table \tkzVar{z} such as:
1046
1047 \verb|z["w1"]=z.w1, z["t1"]=z.t1, z["w2"], z["t2"], ...|
1048
1049 \texttt{Example: } The task here is to determine the two circles passing through point $P$ and tangent to the two lines $(AB)$ and $(CD)$.
1050
1051 \begin{tkzexample}[latex=.5\textwidth]
1052 \directlua{
1053 z.A = point(0, 0)
1054 z.B = point(5, 2)
1055 z.C = point(0, 1)
1056 z.D = point(4, 5)
1057 z.P = point(2, 1.5)
1058 L.AB = line(z.A, z.B)
1059 L.CD = line(z.C, z.D)
1060 pc, pt = L.AB:LLP(L.CD, z.P)
1061 tkz.nodes_from_paths(pc, pt)}
1062 \begin{tikzpicture}
1063 \tkzGetNodes
1064 \tkzDrawLines(A,B C,D)
1065 \tkzDrawCircles[thick,red](w1,t1 w2,t2)
1066 \tkzDrawPoints(A,B,C,D,P)
1067 \tkzLabelPoints(A,B,C,D,P)
1068 \end{tikzpicture}
1069 \end{tkzexample}
1070
1071 \texttt{Remarks: }
1072 \begin{itemize}
1073 \item Both paths must have the same number of points; otherwise, the error originates from the previous computation.
1074 \item The optional \verb|indice| argument is useful when several sets of contact circles are created successively, avoiding overwriting previously defined nodes.
1075 \item This function does not perform any drawing. It only defines the Lua variables for later use in TikZ constructions.
1076 \end{itemize}
1077
1078 \subsection{Function \tkzFct{tkz}{tkz.fsolve}(f, a, b, n [, opts])}
1079 \label{sub:fsolve}
1080
1081 \texttt{Purpose: }
1082 Searches numerically for real roots of a function \( f(x) \) over the interval \([a,b]\).
1083
1084 The interval is divided into \( n \) subintervals, and on each one a few Newton-type iterations are performed (with numerical derivative).
1085
1086 \medskip
1087 \texttt{Syntax: }
1088 \verb|roots = tkz.fsolve(f, a, b [, n, opts])|
1089
1090 \medskip
1091 \texttt{Arguments:}
1092 \begin{itemize}
1093 \item \code{f} — function of one variable (\texttt{function(x) → number});
1094 \item \code{a}, \code{b} — interval bounds (\texttt{number});
1095 \item \code{n} — number of subintervals (default: \texttt{25});
1096 \item \code{opts} — optional table of parameters:
1097 \begin{itemize}
1098 \item \code{tol} — tolerance on \(|f(r)|\) (default: \texttt{1e-8});
1099 \item \code{step\_tol} — tolerance on the Newton step (default: \texttt{1e-10});
1100 \item \code{h} — step size for the numerical derivative (default: \texttt{1e-6});
1101 \item \code{max\_iter} — maximum iterations per seed (default: \texttt{8});
1102 \item \code{merge\_eps} — distance threshold to merge nearby roots (default: \texttt{1e-5}).
1103 \end{itemize}
1104 \end{itemize}
1105
1106 \medskip
1107 \texttt{Returns:}
1108 A Lua table (array) containing all distinct roots found in \([a,b]\),
1109 or \texttt{nil} if no root exists.
1110
1111
1112 \medskip
1113 \texttt{Notes:}
1114 \begin{itemize}
1115 \item Each subinterval \([x_i, x_{i+1}]\) is explored independently.
1116 \item The derivative is approximated by the finite difference
1117 \((f(x+h)-f(x))/h\).
1118 \item Nearby roots (closer than \code{merge\_eps}) are merged automatically.
1119 \item This method is simple and robust for basic searches but not intended
1120 as a high-precision or multi-dimensional solver.
1121 \end{itemize}
1122
1123
1124 \subsection{\tkzFct{tkz}{tkz.derivative}(f, x0 [, accuracy])}
1125 \label{sub:derivative}
1126
1127 \texttt{Purpose: }
1128 Computes the numerical derivative \( f'(x_0) \) using a symmetric finite difference.
1129
1130 \medskip
1131 \texttt{Syntax: }
1132 \verb|df = tkz.derivative(f, x0 [, accuracy])|
1133
1134 \medskip
1135 \texttt{Arguments:}
1136 \begin{itemize}
1137 \item \code{f} — function of one variable (\texttt{function(x) → number});
1138 \item \code{x0} — point where the derivative is evaluated;
1139 \item \code{accuracy} — optional increment controlling the precision of the finite difference (default: \texttt{1e-6}).
1140 \end{itemize}
1141
1142 \medskip
1143 \texttt{Returns:}
1144 The approximate derivative value \( f'(x_0) \), or \texttt{nil} if inputs are invalid.
1145
1146
1147 \medskip
1148 \texttt{Notes:}
1149 \begin{itemize}
1150 \item The derivative is approximated by the central formula:
1151 \[
1152 f'(x_0) \approx \frac{f(x_0 + accuracy) - f(x_0 - accuracy)}{2\,accuracy}.
1153 \]
1154 \item The parameter \code{accuracy} controls the trade-off between precision and numerical stability.
1155 \item Too small a value of \code{accuracy} may amplify floating-point rounding errors.
1156 \end{itemize}
1157
1158 \subsection{Function \tkzFct{tkz}{tkz.range}}
1159 \label{sub:tkz_range}
1160
1161 The \tkzname{tkz.range} function creates a Lua table containing a sequence of numbers
1162 between two bounds, using a specified step (similar to the Python \texttt{range} function).
1163
1164 \texttt{Syntax: }
1165 \begin{verbatim}
1166 tkz.range(a, b [, step])
1167 \end{verbatim}
1168
1169 \begin{itemize}
1170 \item \code{a}, \code{b} — the lower and upper bounds.
1171 \item \code{step} — optional increment (default: 1).
1172 Can be negative for decreasing sequences.
1173 \end{itemize}
1174
1175 \texttt{Returns: } a Lua table \code{tbl} containing the values from \code{a} to \code{b} (inclusive).
1176
1177 \medskip
1178 \texttt{Example: }
1179 \begin{tkzexample}[code only]
1180 \directlua{
1181 local T = tkz.range(5, 1, -1)
1182 for i, v in ipairs(T) do
1183 tex.print(string.format("Value i: v))
1184 end
1185 }
1186 \end{tkzexample}
1187
1188 \texttt{Output: }
1189 \begin{verbatim}
1190 Value 1: 5
1191 Value 2: 4
1192 Value 3: 3
1193 Value 4: 2
1194 Value 5: 1
1195 \end{verbatim}
1196
1197 \endinput