Debian Codegraph @

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

raw
1 \newpage
2 \section{Presentation}
3 \subsection{Geometric Construction Philosophy}
4 \tkzNamePack{tkz-elements} is built around the principles of classical Euclidean geometry, emphasizing constructions achievable with an unmarked straightedge and a compass. The library favors a declarative and geometric approach over algebraic or numeric definitions.
5
6 This philosophy means that all geometric objects — points, lines, circles, triangles, and so on — are primarily defined by other points. Explicit numerical values such as coordinates, distances, or angles are deliberately avoided unless they are essential to the construction. This is in line with a traditional ruler-and-compass mindset, where geometric reasoning emerges from visual configurations and not from numbers.
7
8 For example:
9 \begin{itemize}
10 \item A circle is defined by its center and a point on the circumference,
11 \item A perpendicular bisector is constructed using midpoint and symmetry,
12 \item An angle is inferred from three points rather than given as a numeric value.
13 \end{itemize}
14
15 This design decision also explains why constructors based on scalar values, such as OCCS (One Center and a Scalar), are not part of the default interface. Their use would introduce numerical dependency at odds with the intended geometric abstraction.
16
17 \bigskip
18 While \tkzNamePack{tkz-elements} promotes a high-level, point-based approach to geometry, it relies internally on \textbf{Lua} for performing all necessary calculations. Lua is not exposed to the user as a scripting tool, but rather serves as a powerful computational engine that enables precise and robust geometric operations behind the scenes.
19
20 This separation of concerns allows users to focus entirely on geometric constructions while benefiting from Lua’s computational precision and performance. In the next section, we will explain how Lua integrates with \LaTeX\ in the context of this package — not as a programming layer, but as an invisible partner enabling advanced constructions.
21
22
23 \subsection{With Lua}
24 The primary purpose of \tkzNamePack{tkz-elements} is to perform geometric computations and define points using \tkzname{Lua}. You can think of it as a computational kernel that can be used by either \tkzNamePack{tkz-euclide} or directly with \tkzNamePack{\TIKZ}.
25
26 \tkzname{Lua} code can be executed in two ways: directly, using the \tkzMacro{lualatex}{directlua} primitive, or within a \tkzEnv{tkz-elements}{tkzelements} environment based on the \tkzNamePack{luacode} package (which must be loaded separately).
27 When using \tkzMacro{lualatex}{directlua}, especially in complex documents, you can reset internal data structures — such as coordinate tables and scaling factors — using the \tkzFct{package}{init\_elements()} function.
28
29 \begin{minipage}[t]{.52\textwidth}\vspace{0pt}%
30 The key points are:
31 \begin{itemize}
32 \item The source file must be \tkzRHand\ {\color{red}\uline{ \color{black}UTF-8}} encoded.
33 \item Compilation must be performed with \tkzRHand\ {\color{red}\uline{ \color{black}Lua\LATEX{}}}.
34 \item You need to load \tkzNamePack{tkz-euclide} and \code{tkz-elements}.
35 \item All definitions and calculations are carried out in an \tkzClass{occs} (orthonormal cartesian coordinate system,) using Lua either via the macro \tkzMacro{lualatex}{directlua} or within the \tkzEnv{tkz-elements}{tkzelements} environment.
36 \end{itemize}
37
38 On the right, you will find a minimal template.
39
40 The code is divided into two main parts: the Lua code (executed using \tkzMacro{lualatex}{directlua} or placed inside a \tkzEnv{tkz-elements}{tkzelements} environment), and the \tkzEnv{tikz}{tikzpicture} environment, where drawing commands — typically from \tkzNamePack{tkz-euclide} — are issued.
41
42 When using \tkzNamePack{tkz-euclide}, the \code{mini} option is recommended, as it loads only the macros
43 required for drawing.
44 However, at the current stage, some drawing macros are not yet completely independent of computation macros;
45 if a compilation problem occurs, simply load \tkzNamePack{tkz-euclide} without this option.
46
47 Within the \tkzname{Lua} section, it is best practice to systematically call the
48 \tkzFct{package}{init\_elements()} function.
49 This function resets internal tables and clears internal data structures.
50 \textbf{Important:} from this point on, all scaling operations must be avoided in the \tkzname{Lua} code.
51
52
53 \vspace*{4.1 cm}%
54 \end{minipage}\hspace*{\fill}
55 \begin{minipage}[t]{.45\textwidth}\vspace{0pt}%
56 \begin{mybox}
57 \begin{verbatim}
58 % !TEX TS-program = lualatex
59 % Created by Alain Matthes
60 \documentclass{standalone}
61 \usepackage[mini]{tkz-euclide}
62 % or simply TikZ
63 \usepackage{tkz-elements}
64 begin{document}
65
66 \directlua{
67 init_elements()
68 % definition of some points
69 z.A = point( , )
70 z.B = point( , )
71 % or
72 z.A = point:new( , )
73 z.B = point:new( , )
74
75 ...code...
76 }
77
78 \begin{tikzpicture}
79 % points transfer to Nodes
80 % from Lua to tikz (tkz-euclide)
81 \tkzGetNodes
82
83 \end{tikzpicture}
84 \end{document}
85 \end{verbatim}
86 \end{mybox}
87 \end{minipage}
88
89 \subsection{The main process}
90
91 \tikzset{concept/.append style={fill={none}}}
92 \tikzset{root concept/.style= {minimum size=3cm,text width=2.8cm}}%
93 \tikzset{level 1 concept/.append style={minimum size=4cm, font=\large, text width=3cm}}%
94 \begin{tikzpicture}
95 \path[mindmap,concept color=orange,text=black]
96 node[concept] {Transfers\\\textcolor{orange}{ \textbackslash{tkzGetNodes}}}
97 child[concept color=red,grow=right] {
98 node[concept] {Drawings\\\textcolor{red}{tkz-euclide}\\\textcolor{red}{\TIKZ}} }
99 child[concept color=purple,grow=left] {
100 node[concept] {Definitions\\Calculations\\\textcolor{purple}{tkz-elements}} };
101 \end{tikzpicture}
102
103 After obtaining all the necessary points for the drawing, they must be transformed into \tkzname{nodes} so that \tkzNamePack{\TIKZ} or \tkzNamePack{tkz-euclide} can render the figure. This is accomplished using the macro \tkzMacro{tkz-elements}{tkzGetNodes}. This macro iterates through all the elements of the table \tkzname{z} using the key (which is essentially the name of the point) and retrieves the associated values, namely the coordinates of the point (node).
104
105 \subsection{Complete example: Pappus circle}
106 \label{sub:the_figure_pappus_circle}
107
108
109 \subsubsection{The figure}
110
111 \directlua{
112 z.A = point(0, 0)
113 z.B = point(10, 0)
114 L.AB = line(z.A, z.B)
115 z.C = L.AB:gold_ratio()
116 L.AC = line(z.A, z.C)
117 L.CB = line(z.C, z.B)
118 L.AB = line(z.A, z.B)
119 z.O_0 = L.AB.mid
120 z.O_1 = L.AC.mid
121 z.O_2 = L.CB.mid
122 C.AB = circle(z.O_0, z.B)
123 C.AC = circle(z.O_1, z.C)
124 C.CB = circle(z.O_2, z.B)
125 z.P = C.CB.north
126 z.Q = C.AC.north
127 z.O = C.AB.south
128 z.c = z.C:north(2)
129 C.PC = circle(z.P, z.C)
130 C.QA = circle(z.Q, z.A)
131 z.P_0 = intersection(C.PC, C.AB)
132 z.P_1 = intersection(C.PC, C.AC)
133 _, z.P_2 = intersection(C.QA, C.CB)
134 T.P = triangle(z.P_0, z.P_1, z.P_2)
135 z.O_3 = T.P.circumcenter
136 }
137
138 \begin{center}
139 \begin{tikzpicture}[scale = .75]
140 \tkzGetNodes
141 \tkzDrawCircle[black,fill=yellow!20,opacity=.4](O_0,B)
142 \tkzDrawCircles[teal,fill=teal!40,opacity=.6](O_1,C O_2,B)
143 \tkzDrawCircle[purple,fill=purple!20,opacity=.4](O_3,P_0)
144 \tkzDrawArc[cyan,delta=10](Q,A)(P_0)
145 \tkzDrawArc[cyan,delta=10](P,P_0)(B)
146 \tkzDrawArc[cyan,delta=10](O,B)(A)
147 \tkzDrawPoints(A,B,C,O_0,O_1,O_2,P,Q,P_0,P_0,P_1,P_2,O)
148 \tkzLabelPoints(A,B,C,O_0,O_1,O_2,P,Q,P_0,P_0,P_1,P_2,O)
149 \end{tikzpicture}
150 \end{center}
151
152 \subsubsection{The code}
153 \label{ssub:the_code}
154
155 \begin{mybox}{}
156 \begin{verbatim}
157 % !TEX TS-program = lualatex
158 \documentclass{article}
159 \usepackage[mini]{tkz-euclide} % mini = only tracing function
160 \usepackage{tkz-elements}
161 \begin{document}
162
163 \directlua{
164 init_elements() % Clear tables
165 z.A = point(0, 0)
166 z.B = point(10, 0) % creation of two fixed points $A$ and $B$
167 L.AB = line(z.A, z.B)
168 z.C = L.AB:gold_ratio() % use of a method linked to “line”
169 z.O_0 = line(z.A, z.B).mid % midpoint of segment with an attribute of “line”
170 z.O_1 = line(z.A, z.C).mid % objects are not stored and cannot be reused.
171 z.O_2 = line(z.C, z.B).mid
172 C.AB = circle(z.O_0, z.B) % new object “circle” stored and reused
173 C.AC = circle(z.O_1, z.C)
174 C.CB = circle(z.O_2, z.B)
175 z.P = C.CB.north % “north” atrributes of a circle
176 z.Q = C.AC.north
177 z.O = C.AB.south
178 z.c = z.C:north(2) %“north” method of a point (needs a parameter)
179 C.PC = circle(z.P, z.C)
180 C.QA = circle(z.Q, z.A)
181 z.P_0 = intersection(C.PC,C.AB) % search for intersections of two circles.
182 z.P_1 = intersection(C.PC,C.AC) % idem
183 _,z.P_2 = intersection(C.QA,C.CB) % idem
184 T.P = triangle(z.P_0, z.P_1, z.P_2)
185 z.O_3 = T.P.circumcenter % circumcenter attribute of “triangle”
186 }
187 \end{verbatim}
188 \end{mybox}
189
190 \begin{verbatim}
191 \begin{tikzpicture}
192 \tkzGetNodes
193 \tkzDrawCircle[black,fill=yellow!20,opacity=.4](O_0,B)
194 \tkzDrawCircles[teal,fill=teal!40,opacity=.6](O_1,C O_2,B)
195 \tkzDrawCircle[purple,fill=purple!20,opacity=.4](O_3,P_0)
196 \tkzDrawArc[cyan,delta=10](Q,A)(P_0)
197 \tkzDrawArc[cyan,delta=10](P,P_0)(B)
198 \tkzDrawArc[cyan,delta=10](O,B)(A)
199 \tkzDrawPoints(A,B,C,O_0,O_1,O_2,P,Q,P_0,P_0,P_1,P_2,O)
200 \tkzLabelPoints(A,B,C,O_0,O_1,O_2,P,Q,P_0,P_0,P_1,P_2,O)
201 \end{tikzpicture}
202 \end{document}
203 \end{verbatim}
204
205 \subsection{Another example with comments: South Pole}
206 Here's another example with comments
207
208 \begin{mybox}{}
209 \begin{verbatim}
210 % !TEX TS-program = lualatex
211 \documentclass{standalone}
212 \usepackage[mini]{tkz-euclide}
213 \usepackage{tkz-elements}
214 \begin{document}
215 \directlua{
216 init_elements() % Clear tables
217 z.A = point(2, 4)
218 z.B = point(0, 0) % three fixed points are used
219 z.C = point(8, 0) %
220 T.ABC = triangle(z.A, z.B, z.C) % we create a new triangle object
221 C.ins = T.ABC:in_circle() % we get the incircle of this triangle
222 z.I = C.ins.center % center is an attribute of the circle
223 z.T = C.ins.through % through is also an attribute
224 z.I, z.T = C.ins:get() % get() is a shortcut
225 C.cir = T.ABC:circum_circle() % we get the circumscribed circle
226 z.W = C.cir.center % we get the center of this circle
227 z.O = C.cir.south % now we get the south pole of this circle
228 L.AO = line(z.A, z.O) % we create an object "line"
229 L.BC = T.ABC.bc % we get the line (BC)
230 z.I_A = intersection(L.AO, L.BC) % we search the intersection of the last lines
231 }
232 \end{verbatim}
233 \end{mybox}
234
235 \directlua{
236 init_elements()
237 z.A = point(2, 4)
238 z.B = point(0, 0)
239 z.C = point(8, 0)
240 T.ABC = triangle(z.A, z.B, z.C)
241 C.ins = T.ABC:in_circle()
242 z.I = C.ins.center
243 z.T = C.ins.through
244 C.cir = T.ABC:circum_circle()
245 z.W = C.cir.center
246 z.O = C.cir.south
247 L.AO = line(z.A, z.O)
248 L.BC = T.ABC.bc
249 z.I_A = intersection(L.AO, L.BC)
250 }
251
252 \begin{center}
253 \begin{tikzpicture}[ scale= 1.2]
254 \tkzGetNodes
255 \tkzDrawCircles(W,A I,T)
256 \tkzDrawArc(O,C)(B)
257 \tkzDrawPolygon(A,B,C)
258 \tkzDrawSegments[new](A,O B,O C,O)
259 \tkzDrawLine(B,I)
260 \tkzDrawPoints(A,B,C,I,I_A,W,O)
261 \tkzFillAngles[green!20,opacity=.3](A,O,B A,C,B)
262 \tkzFillAngles[teal!20,opacity=.3](O,B,C B,C,O B,A,O O,A,C)
263 \tkzLabelPoints(I,I_A,W,B,C,O)
264 \tkzLabelPoints[above](A)
265 \end{tikzpicture}
266 \end{center}
267
268 \vspace{12pt}
269 Here's the \tkzEnv{tikz}{tikzpicture} environment to obtain the drawing:
270 \begin{verbatim}
271 \begin{tikzpicture}
272 \tkzGetNodes
273 \tkzDrawCircles(W,A I,T)
274 \tkzDrawArc(O,C)(B)
275 \tkzDrawPolygon(A,B,C)
276 \tkzDrawSegments[new](A,O B,O C,O)
277 \tkzDrawLine(B,I)
278 \tkzDrawPoints(A,B,C,I,I_A,W,O)
279 \tkzFillAngles[green!20,opacity=.3](A,O,B A,C,B)
280 \tkzFillAngles[teal!20,opacity=.3](O,B,C B,C,O B,A,O O,A,C)
281 \tkzLabelPoints(I,I_A,W,B,C,O)
282 \tkzLabelPoints[above](A)
283 \end{tikzpicture}
284 \end{verbatim}
285 \endinput