Debian Codegraph @

texmf-dist/doc/latex/tkz-elements/TKZdoc-elements-classes-list-point.tex

raw
1 \section{Class \tkzClass{list\_point}}
2 \label{sec:class_list_point}
3
4 The variable \tkzVar{list\_point}{LP} holds a table used to store \tkzClass{list\_point} objects.
5 Its use is optional, and users are free to choose any variable name.
6
7 \medskip
8
9 However, for the sake of consistency and readability throughout the documentation,
10 it is recommended to use the predefined variable \tkzVar{list\_point}{LP}.
11 The function \tkzFct{tkz-elements}{init\_elements()} automatically reinitializes this table.
12
13 \medskip
14
15 The \tkzClass{list\_point} class represents an ordered list of points.
16 It is primarily intended as a lightweight container used to store and manipulate multiple points
17 produced by geometric constructions, intersections, or iterative algorithms.
18
19 Unlike geometric objects such as lines or circles, a \tkzClass{list\_point} object does not define intrinsic geometry.
20 Its purpose is to facilitate grouping, iteration, and data transfer between \tkzname{Lua} and \tkzname{TikZ}.
21
22 \medskip
23
24 A \tkzClass{list\_point} object behaves like a Lua table indexed by integers,
25 while providing a set of convenience methods adapted to geometric workflows.
26
27 \medskip
28
29 \subsection{Attributes}
30 \label{subsec:list_point_attributes}
31
32 \vspace{1em}
33 \bgroup
34 \small
35 \captionof{table}{\texttt{list\_point} attributes.}\label{list_point:attributes}
36 \begin{tabular}{lll}
37 \toprule
38 \textbf{Attribute} & \textbf{Meaning} & \texttt{Reference} \\
39 \midrule
40 \tkzAttr{list\_point}{n} & [\ref{ssub:attr_list_point_n}] \\
41 \tkzAttr{list\_point}{items} & [\ref{ssub:attr_list_point_items}] \\
42 \bottomrule
43 \end{tabular}
44 \egroup
45
46
47 \subsubsection{Attribute \tkzAttr{list\_point}{n}}
48 \label{ssub:attr_list_point_n}
49
50 The attribute \tkzAttr{list\_point}{n} denotes the number of points stored in the list.
51 In practice, it corresponds to the Lua length operator \texttt{\#P} (array part).
52
53 \subsubsection{Attribute \tkzAttr{list\_point}{items}}
54 \label{ssub:attr_list_point_items}
55
56 The attribute \tkzAttr{list\_point}{items} refers to the ordered sequence of points stored in the list.
57 Individual points are accessed using standard Lua indexing, e.g. \texttt{P[i]}.
58
59
60 \subsection{Creating an object}
61 \label{subsec:list_point_create}
62
63 \subsubsection{Method \tkzMeth{list\_point}{new(...)}}
64 \label{ssub:meth_list_point_new}
65
66 Creates a new \tkzClass{list\_point} object.
67
68 In user code, the recommended constructor is the callable form \code{list\_point(...)}.
69 Internally, this calls the method \tkzMeth{list\_point}{new(...)}.
70
71 \medskip
72
73 A \tkzClass{list\_point} object can be created either as a local Lua variable
74 or as an entry of the table \tkzVar{list\_point}{LP}, which is reserved for storing
75 lists of points.
76
77 \begin{tkzexample}[code only]
78 local P = list_point()
79 LP.Q = list_point(z.A, z.B, z.C)
80 \end{tkzexample}
81
82 Both forms are valid and produce independent \tkzClass{list\_point} objects.
83
84 \medskip
85
86 Using a local variable is convenient for temporary computations or intermediate results.
87 However, for objects intended to be reused, transferred to \tkzname{TikZ},
88 or accessed outside a local scope, it is recommended to store them in the
89 \tkzVar{list\_point}{LP} table.
90
91 \medskip
92
93 The function \tkzFct{tkz-elements}{init\_elements()} automatically reinitializes
94 the \tkzVar{list\_point}{LP} table.
95
96
97 % --------------------------------------------------------------------
98 \subsection{Methods or Basic accessors}
99 \label{subsec:list_point_accessors}
100
101 \vspace{1em}
102 \bgroup
103 \small
104 \captionof{table}{\texttt{list\_point} methods.}\label{list_point:methods}
105 \begin{tabular}{ll}
106 \toprule
107 \texttt{Method} & \texttt{Reference} \\
108 \midrule
109 \texttt{Constructor} & \\
110 \midrule
111 \tkzMeth{list\_point}{new(...)} & [\ref{ssub:meth_list_point_new}] \\
112 \midrule
113 \texttt{Methods Returning a Integer Number}&\\
114 \midrule
115 \tkzMeth{list\_point}{len()} & [\ref{ssub:meth_list_point_len}] \\
116 \midrule
117 \texttt{Methods Returning a Point}&\\
118 \midrule\tkzMeth{list\_point}{get(i)} & [\ref{ssub:meth_list_point_get}] \\
119 \tkzMeth{list\_point}{barycenter()}& [\ref{ssub:meth_list_point_barycenter}]\\
120 \midrule
121 \texttt{Methods Returning a List\_Point}&\\
122 \midrule
123 \tkzMeth{list\_point}{add(p)} & [\ref{ssub:meth_list_point_add}] \\
124 \tkzMeth{list\_point}{extend(pl)} & [\ref{ssub:meth_list_point_extend}] \\
125 \tkzMeth{list\_point}{map(f)} & [\ref{ssub:meth_list_point_map}] \\
126 \midrule
127 \tkzMeth{list\_point}{unpack()} & [\ref{ssub:meth_list_point_unpack}] \\
128
129
130 \tkzMeth{list\_point}{clear()} & [\ref{ssub:meth_list_point_clear}] \\
131 \tkzMeth{list\_point}{foreach(f)} & [\ref{ssub:meth_list_point_foreach}] \\
132
133 \tkzMeth{list\_point}{bbox()} & [\ref{ssub:meth_list_point_bbox}] \\
134
135 \tkzMeth{list\_point}{to\_path()}& [\ref{ssub:meth_list_point_to_path}] \\
136 \bottomrule
137 \end{tabular}
138 \egroup
139
140 \subsubsection{Method \tkzMeth{list\_point}{len()}}
141 \label{ssub:meth_list_point_len}
142
143 Returns the number of points stored in the list.
144
145 \subsubsection{Method \tkzMeth{list\_point}{get(i)}}
146 \label{ssub:meth_list_point_get}
147
148 Returns the point at index \code{i}.
149
150 \subsubsection{Method \tkzMeth{list\_point}{unpack()}}
151 \label{ssub:meth_list_point_unpack}
152
153 Returns all points as separate values using \code{table.unpack}.
154 This method is useful when interfacing with functions expecting individual point arguments.
155
156 \begin{tkzexample}[latex=.5\textwidth]
157 \directlua{
158 init_elements()
159 LP = list_point()
160 LP:add(point(0,0))
161 LP:add(point(1,0))
162 LP:add(point(1,1))
163 z.A, z.B, z.C = LP:unpack()
164 }
165 \begin{center}
166 \begin{tikzpicture}
167 \tkzGetNodes
168 \tkzDrawPolygon(A,B,C)
169 \end{tikzpicture}
170 \end{center}
171 \end{tkzexample}
172
173 % --------------------------------------------------------------------
174 \subsection{Modification methods}
175 \label{subsec:list_point_mutators}
176
177 \subsubsection{Method \tkzMeth{list\_point}{add(p)}}
178 \label{ssub:meth_list_point_add}
179
180 Appends the point \code{p} to the list and returns the object itself.
181
182 \subsubsection{Method \tkzMeth{list\_point}{extend(pl)}}
183 \label{ssub:meth_list_point_extend}
184
185 Appends all points from another \tkzClass{list\_point} object \code{pl}.
186
187 \subsubsection{Method \tkzMeth{list\_point}{clear()}}
188 \label{ssub:meth_list_point_clear}
189
190 Removes all points from the list.
191
192
193 These methods modify the object in place and allow method chaining.
194
195 % --------------------------------------------------------------------
196 \subsection{Iteration helpers}
197 \label{subsec:list_point_iteration}
198
199 \subsubsection{Method \tkzMeth{list\_point}{foreach(f)}}
200 \label{ssub:meth_list_point_foreach}
201
202 Applies the function \code{f(p, i)} to each point \code{p} with its index \code{i}.
203
204 \subsubsection{Method \tkzMeth{list\_point}{map(f)}}
205 \label{ssub:meth_list_point_map}
206
207 Applies the function \code{f(p, i)} to each point and returns a new \tkzClass{list\_point} object
208 containing the results.
209
210
211 These methods support a functional programming style for geometric transformations.
212
213 % --------------------------------------------------------------------
214 \subsection{Geometric utilities}
215 \label{subsec:list_point_geometry}
216
217 \subsubsection{Method \tkzMeth{list\_point}{barycenter()}}
218 \label{ssub:meth_list_point_barycenter}
219
220 Returns the barycenter (centroid) of all points in the list.
221 If the list is empty, the method returns \code{nil}.
222
223 \subsubsection{Method \tkzMeth{list\_point}{bbox()}}
224 \label{ssub:meth_list_point_bbox}
225
226 Returns the bounding box of the point set as four numbers:
227 \[
228 (x_{\min}, y_{\min}, x_{\max}, y_{\max})
229 \]
230
231
232 % --------------------------------------------------------------------
233 \subsection{TikZ output}
234 \label{subsec:list_point_output}
235
236 \subsubsection{Method \tkzMeth{list\_point}{to\_path()}}
237 \label{ssub:meth_list_point_to_path}
238
239 Converts the list of points into a TikZ path string of the form
240 \[
241 (x_1,y_1) -- (x_2,y_2) -- \dots
242 \]
243 suitable for drawing with TikZ commands.
244
245
246 \medskip
247
248 This class provides a minimal yet effective bridge between \tkzname{Lua} computations and \tkzname{TikZ} drawing instructions.
249
250
251 \subsection{Examples}
252 \label{subsec:list_point_examples}
253
254 % --------------------------------------------------------------------
255 \subsubsection{Temporary list of points}
256 \label{ssub:list_point_example_local}
257
258 This example illustrates the use of a local \tkzClass{list\_point} object to store
259 temporary results inside a computation.
260
261 \begin{tkzexample}[code only]
262 local P = list_point()
263 for i = 1, 10 do
264 P:add(z.A + i * (z.B - z.A) / 10)
265 end
266 local G = P:barycenter()
267 \end{tkzexample}
268
269 The list \code{P} is used only locally to compute the barycenter of a set of points.
270
271 % --------------------------------------------------------------------
272 \subsubsection{Storing construction results in \tkzVar{list\_point}{LP}}
273 \label{ssub:list_point_example_lp}
274
275 This example shows how to store a list of intersection points for later use.
276
277 \begin{tkzexample}[code only]
278 LP.I = list_point()
279 local X, Y = intersection(L.AB, C.circ)
280 LP.I:add(X)
281 LP.I:add(Y)
282 \end{tkzexample}
283
284 Storing the points in \tkzVar{list\_point}{LP} makes them accessible for drawing
285 or further constructions.
286
287 % --------------------------------------------------------------------
288 \subsubsection{Iterative construction}
289 \label{ssub:list_point_example_iterative}
290
291 A typical use case is the progressive construction of a family of points.
292
293 \begin{tkzexample}[code only]
294 LP.P = list_point()
295 for i = 0, 24 do
296 local t = i / 24
297 LP.P:add(L.AB:point(t))
298 end
299 \end{tkzexample}
300
301 The list \code{LP.P} contains a discrete sampling of a segment.
302
303 % --------------------------------------------------------------------
304 \subsubsection{Functional transformation}
305 \label{ssub:list_point_example_map}
306
307 This example uses the \tkzMeth{list\_point}{map} method to transform a set of points.
308
309 \begin{tkzexample}[code only]
310 local P = list_point(z.A, z.B, z.C)
311 LP.Q = P:map(function(p)
312 return rotation_(p, tkz.tau / 3, z.O)
313 end)
314 \end{tkzexample}
315
316 The original list \code{P} is preserved, while \code{LP.Q} stores the transformed points.
317
318 % --------------------------------------------------------------------
319 \subsubsection{Conversion to a TikZ path}
320 \label{ssub:list_point_example_path}
321
322 This example illustrates the interaction between \tkzClass{list\_point} and TikZ.
323
324 \begin{tkzexample}[code only]
325 LP.P = list_point(z.A, z.B, z.C)
326 local path = LP.P:to_path()
327 \end{tkzexample}
328
329 The string returned by \tkzMeth{list\_point}{to\_path} can be passed directly
330 to TikZ drawing commands.
331
332
333 % --------------------------------------------------------------------
334 \subsubsection{From \tkzClass{list\_point} to \tkzClass{path} and drawing with \tkzNamePack{tkz-euclide}}
335 \label{ssub:list_point_example_points_path_draw}
336
337 This example shows a typical workflow: compute a list of points in \tkzname{Lua},
338 convert it into a \tkzClass{path}, and then draw the resulting points with
339 \tkzMeth{tkz-euclide}{tkzDrawPointsFromPath}.
340
341
342 \begin{tkzexample}[latex = .5\textwidth]
343 \directlua{
344 init_elements()
345 z.A = point(0, 0)
346 z.B = point(8, 6)
347 L.AB = line(z.A, z.B)
348 % list of sampled points
349 LP.P = list_point()
350 for i = 0, 12 do
351 LP.P:add(L.AB:point(i/12))
352 end
353 % convert list_point -> path
354 PA.sample = path()
355 for i = 1, LP.P:len() do
356 PA.sample:add_point(LP.P:get(i))
357 end
358 }
359 \begin{center}
360 \begin{tikzpicture}
361 \tkzGetNodes
362 % draw the points stored in the path
363 \tkzDrawPointsFromPath(PA.sample)
364 \end{tikzpicture}
365 \end{center}
366 \end{tkzexample}
367
368 The points are stored in \code{LP.P} for later reuse, while \code{PA.sample}
369 contains the corresponding TikZ path representation used for drawing.