\newpage
\section{Class \tkzClass{angle}}
\label{sec:class_angle}

The \tkzClass{angle} class is an experimental helper object used to represent
an angle defined by three points.
It is currently self-contained and does not interact with other classes.
Its main purpose is to provide a simple and direct interface for obtaining:

\begin{itemize}
  \item the oriented angle in radians,
  \item the normalised oriented angle in $[0, 2\pi]$
  \item the interior (non-oriented) angle,
  \item the measure of the interior angle in degrees.
\end{itemize}

An \tkzClass{angle} object is \emph{static}: all values are computed at creation
time and never updated.

\subsection{Creating an object}
\label{ssub:method_angle_new}

\begin{verbatim}
  local alpha  = angle(z.A, z.B, z.C)   -- equivalent to angle:new(A,B,C)
  local beta   = angle(z.B, z.C, z.A)
  local gamma  = angle(z.C, z.A, z.B)
\end{verbatim}

The three arguments are:
\begin{itemize}
  \item \tkzVar{ps}: the vertex of the angle,
  \item \tkzVar{pa}: the first point defining the first ray,
  \item \tkzVar{pb}: the second point defining the second ray.
\end{itemize}

\subsection{Attributes}

The following attributes are stored inside every \tkzClass{angle} object:

\vspace{1em}
\bgroup
\small
\captionof{table}{Angle attributes.}\label{angle:attributes}
\begin{tabular}{lll}
\toprule
\textbf{Attribute} & \textbf{Meaning} & \texttt{Reference} \\
\midrule
\tkzAttr{angle}{ps}   & Vertex of the angle & [\ref{par:attr_angle_ps}] \\
\tkzAttr{angle}{pa}   & First defining point (ray $[ps\,pa]$) & [\ref{par:attr_angle_pa}] \\
\tkzAttr{angle}{pb}   & Second defining point (ray $[ps\,pb]$) & [\ref{par:attr_angle_pb}] \\
\tkzAttr{angle}{raw}  & Oriented angle (radians), may be negative & [\ref{par:attr_angle_raw}] \\
\tkzAttr{angle}{value} & Non-oriented angle in the range $[0,\pi]$ & [\ref{par:attr_angle_value}] \\
\tkzAttr{angle}{deg} & Interior angle in degrees & [\ref{par:attr_angle_deg}] \\

\bottomrule
\end{tabular}
\egroup

\paragraph{\tkzAttr{angle}{ps}}\label{par:attr_angle_ps}
The vertex (summit) of the angle.

\paragraph{\tkzAttr{angle}{pa}}\label{par:attr_angle_pa}
A point defining the first ray $[ps\,pa]$.

\paragraph{\tkzAttr{angle}{pb}}\label{par:attr_angle_pb}
A point defining the second ray $[ps\,pb]$.

\paragraph{\tkzAttr{angle}{raw}}\label{par:attr_angle_raw}
The oriented angle in radians as returned by \texttt{get\_angle\_(ps,pa,pb)}; it may be negative.

\paragraph{\tkzAttr{angle}{norm}}\label{par:attr_angle_norm}
The oriented angle normalised to the interval $[0,2\pi)$.

\paragraph{\tkzAttr{angle}{value}}
\label{par:attr_angle_value}
Returns the interior (non-oriented) angle in the range $[0,\pi]$:

\texttt{Example: }
\begin{tkzexample}[latex=.45\textwidth]
  \directlua{%
  init_elements()
  z.O = point(0, 1)
  z.T = point(2, 2)
  C.OT = circle(z.O, z.T)
  z.M = C.OT:point(.13)
  A.OTM = angle(z.O, z.T, z.M)
  tkzA = A.OTM.value}
\begin{center}
\begin{tikzpicture}
  \tkzGetNodes
  \tkzDrawLines(O,T O,M)
  \tkzDrawCircle(O,T)
  \tkzDrawPoints(O,T,M)
  \tkzLabelPoints(O,T,M)
  \tkzMarkAngle(T,O,M)
  \tkzLabelAngle[pos=1.5](T,O,M){%
  \tkzPN[3]{\tkzUseLua{tkzA}}}
\end{tikzpicture}
\end{center}
\end{tkzexample}


\paragraph{\tkzMeth{angle}{deg}}
\label{par:attr_angle_deg}
Returns an interior angle in degrees.

\texttt{Example: }

\begin{tkzexample}[latex=.35\textwidth]
\directlua{
  init_elements()
  z.A = point(0,0)
  z.B = point(3,0)
  z.C = point(1,2)
  A.alpha = angle(z.B, z.A, z.C)
  tex.print("Angle at A = "..A.alpha.deg.." degrees")
}
\begin{center}
\begin{tikzpicture}
  \tkzGetNodes
  \tkzDrawPolygon(A,B,C)
  \tkzDrawPoints(A,B,C)
  \tkzLabelPoints(A,B)
  \tkzLabelPoints[above](C)
\end{tikzpicture}
\end{center}
\end{tkzexample}

Also possible:

\begin{verbatim}
   T.ABC = triangle(z.A, z.B, z.C)
   local val = T.ABC.alpha_.deg
\end{verbatim}

All values are numerical scalars and remain fixed once the object is created.

\texttt{Example: }

\begin{tkzexample}[latex=.5\textwidth]
\directlua{
  init_elements()
  z.A = point(0, 0)
  z.C = point(3, 0)
  z.B = point(3, 2)
  T.ABC = triangle(z.A, z.B, z.C)
  A.A = T.ABC.alpha_
  A.B = T.ABC.beta_
  T.C = T.ABC.gamma_
  tex.print("A(value) = \\", A.A.value)
  tex.print('\\\\')
  tex.print("A(raw) = \\", A.A.raw)
  tex.print('\\\\')
  tex.print("A(deg) = \\", A.A.deg)}

\begin{center}
\begin{tikzpicture}
  \tkzGetNodes
  \tkzDrawPolygon(A,B,C)
  \tkzDrawPoints(A,B,C)
  \tkzLabelPoints(A,C)
  \tkzLabelPoints[above](B)
\end{tikzpicture}
\end{center}
\end{tkzexample}


\subsection{Methods}

\vspace{1em}
\bgroup
\small
\captionof{table}{angle methods.}\label{angle:methods}
\begin{tabular}{ll}
\toprule
\textbf{Methods} & \texttt{Reference} \\
\midrule
\textbf{Creation} & \\
\midrule
\tkzMeth{angle}{angle(ps, pa, pb)} & [\ref{ssub:method_angle_new}] \\
\midrule
\textbf{Accessors} & \\
\midrule
\tkzMeth{angle}{get()} & [\ref{ssub:method_angle_get}] \\
\midrule
\textbf{Tests} & \\
\midrule
\tkzMeth{angle}{is\_direct()} & [\ref{ssub:method_angle_is_direct}] \\

\bottomrule
\end{tabular}
\egroup


\subsubsection{\tkzMeth{angle}{get()}}
\label{ssub:method_angle_get}
Returns the three defining points:
\begin{verbatim}
local ps, pa, pb = alpha:get()
\end{verbatim}

\subsubsection{\tkzMeth{angle}{is\_direct()}}
\label{ssub:method_angle_is_direct}
Returns \verb|true| when the angle is positive (counterclockwise orientation).




\medskip
This class is \emph{experimental} and may evolve in future versions.