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