\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 angle = require("tkz_elements_angle")

local alpha  = angle(A, B, C)   -- equivalent to angle:new(A,B,C)
local beta   = angle(B, C, A)
local gamma  = angle(C, A, 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} & \textbf{Reference} \\
\midrule
\tkzAttr{angle}{ps}   & Vertex of the angle & [\ref{ssub:attr_angle_ps}] \\
\tkzAttr{angle}{pa}   & First defining point (ray $[ps\,pa]$) & [\ref{ssub:attr_angle_pa}] \\
\tkzAttr{angle}{pb}   & Second defining point (ray $[ps\,pb]$) & [\ref{ssub:attr_angle_pb}] \\
\tkzAttr{angle}{raw}  & Oriented angle (radians), may be negative & [\ref{ssub:attr_angle_raw}] \\
\tkzAttr{angle}{norm} & Oriented angle normalised to $[0,2\pi)$ & [\ref{ssub:attr_angle_norm}] \\
\bottomrule
\end{tabular}
\egroup

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

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

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

\paragraph{\tkzAttr{angle}{raw}}\label{ssub: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{ssub:attr_angle_norm}
The oriented angle normalised to the interval $[0,2\pi)$.

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

\subsection{Methods}

\vspace{1em}
\bgroup
\small
\captionof{table}{angle methods.}\label{angle:methods}
\begin{tabular}{ll}
\toprule
\textbf{Methods} & \textbf{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}] \\
\tkzMeth{angle}{value()} & [\ref{ssub:method_angle_value}] \\
\tkzMeth{angle}{deg()} & [\ref{ssub:method_angle_deg}] \\
\midrule
\textbf{Tests} & \\
\midrule
\tkzMeth{angle}{is\_direct()} & [\ref{ssub:method_angle_is_direct}] \\
\midrule
\textbf{Aliases} & \\
\midrule
\tkzMeth{angle}{to\_degrees()} & [\ref{ssub:method_angle_to_degrees}] \\
\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).

\subsubsection{\tkzMeth{angle}{value()}}
\label{ssub:method_angle_value}
Returns the interior (non-oriented) angle in the range $[0,\pi]$:

\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}


\subsubsection{\tkzMeth{angle}{deg()}}
\label{ssub:method_angle_deg}
Returns the interior angle in degrees.

\subsubsection{\tkzMeth{angle}{to\_degrees()}}
\label{ssub:method_angle_to_degrees}
Alias of \texttt{deg()}.

\subsection{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")
}
\end{tkzexample}

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