Debian Codegraph @

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

raw
1 %--------------------------------------------------------------------
2 \section{Geometric Relations API}
3 \label{sec:geometric_relations_api}
4
5 \subsection{General Principle}
6
7 In \tkzNamePack{tkz-elements}, geometric objects provide a unified method
8 \[
9 \code{object:position(other\_object[, EPS])}
10 \]
11 to classify a geometric relation.
12
13 The result depends on the type of the second argument (\code{other\_object}).
14
15 \medskip
16 All position tests are tolerance-aware.
17 If not specified, the optional parameter \code{EPS} defaults to the global value
18 \tkzVar{tkz}{tkz.epsilon}.
19
20 \medskip
21 \textbf{Convention:}
22 All classification results are returned as \emph{uppercase symbolic strings},
23 intended for logical comparison in Lua code.
24
25 %--------------------------------------------------------------------
26 \subsection{Point vs Object}
27
28 When the tested object is a point, the result describes membership relative to
29 a region (or a boundary).
30
31 \medskip
32 Possible return values:
33
34 \begin{center}
35 \begin{tabular}{ll}
36 \code{"IN"} & strictly inside the region, \\
37 \code{"ON"} & on the boundary (within tolerance), \\
38 \code{"OUT"} & strictly outside the region.
39 \end{tabular}
40 \end{center}
41
42 \medskip
43 Examples:
44 \begin{itemize}
45 \item \code{circle:position(point)} \quad (\code{"IN"}, \code{"ON"}, \code{"OUT"})
46 \item \code{triangle:position(point)} \quad (\code{"IN"}, \code{"ON"}, \code{"OUT"})
47 \item \code{conic:position(point)} \quad (\code{"IN"}, \code{"ON"}, \code{"OUT"})
48 \item \code{line:position(point)} \quad (\code{"ON"} or \code{"OUT"})
49 \end{itemize}
50
51 %--------------------------------------------------------------------
52 \subsection{Object vs Object}
53
54 When both arguments are geometric objects, the result describes their mutual
55 geometric relation.
56
57 \subsubsection*{Line vs Line}
58
59 \begin{center}
60 \begin{tabular}{ll}
61 \code{"INTERSECT"} & lines intersect at one point, \\
62 \code{"PARALLEL"} & distinct parallel lines, \\
63 \code{"IDENTICAL"} & identical lines.
64 \end{tabular}
65 \end{center}
66
67 \subsubsection*{Line vs Circle}
68
69 \begin{center}
70 \begin{tabular}{ll}
71 \code{"DISJOINT"} & no intersection, \\
72 \code{"TANGENT"} & exactly one common point, \\
73 \code{"SECANT"} & two intersection points.
74 \end{tabular}
75 \end{center}
76
77 \subsubsection*{Circle vs Circle}
78
79 \begin{center}
80 \begin{tabular}{ll}
81 \code{"DISJOINT\_EXT"} & exterior disjoint circles, \\
82 \code{"TANGENT\_EXT"} & exterior tangency, \\
83 \code{"SECANT"} & two intersection points, \\
84 \code{"TANGENT\_INT"} & interior tangency, \\
85 \code{"DISJOINT\_INT"} & one circle strictly inside the other, \\
86 \code{"CONCENTRIC"} & same center, different radii, \\
87 \code{"IDENTICAL"} & identical circles.
88 \end{tabular}
89 \end{center}
90
91 %--------------------------------------------------------------------
92 \subsection{Triangle and Conic}
93
94 For \tkzClass{triangle} and \tkzClass{conic}, the method \code{position()}
95 currently supports point arguments only.
96
97 \subsubsection*{Triangle vs Point}
98
99 \begin{center}
100 \begin{tabular}{ll}
101 \code{"IN"} & strictly inside the triangle, \\
102 \code{"ON"} & on an edge or a vertex, \\
103 \code{"OUT"} & outside the triangle.
104 \end{tabular}
105 \end{center}
106
107 \subsubsection*{Conic vs Point}
108
109 \begin{center}
110 \begin{tabular}{ll}
111 \code{"IN"} & inside the conic region (according to its type), \\
112 \code{"ON"} & on the conic curve, \\
113 \code{"OUT"} & outside the associated region.
114 \end{tabular}
115 \end{center}
116
117 \medskip
118 \texttt{Note:} For hyperbolas and parabolas, the meaning of \code{"IN"} and
119 \code{"OUT"} depends on the region associated with the conic type and its
120 construction data (focus/directrix or equivalent representation).
121
122 %--------------------------------------------------------------------
123 \subsection{Design Philosophy}
124
125 \begin{itemize}
126 \item A single polymorphic method centralizes geometric classification.
127 \item Uppercase symbolic results ensure clarity and stability.
128 \item Numerical tolerance improves robustness near boundary cases.
129 \item The API is extensible: additional object types may be supported over time.
130 \item Backward compatibility wrappers may be provided when older boolean methods
131 existed in previous versions.
132 \end{itemize}