\section{Objects and Basic Primitives}
\label{sec:basic-primitives}

\subsection{Reusable objects with \texttt{\textbackslash setobject}}

The command \verb|\setobject| takes two keys: \verb|name| and \verb|object|.
The \verb|object| key is a Lua chunk evaluated in the package sandbox, and the
result is stored under the chosen name. The stored object can then be reused in
later expressions.

This mechanism is useful for:

\begin{itemize}[leftmargin=2em]
\item transformations that should be shared by several commands;
\item named points or axes;
\item scalar parameters such as radii or angles;
\item helper functions that belong to one figure.
\end{itemize}

\begin{Verbatim}
\setobject[
  name = spin,
  object = {return Matrix.axis_angle(Vector:new{0, 0, 1, 1}, 0.5)}
]

\setobject[
  name = apex,
  object = {return Vector:new{0, 0, 1.8, 1}}
]
\end{Verbatim}

\subsection{Triangles}

The command \verb|\appendtriangle| is the smallest direct route to a visible
surface. It takes a single matrix-valued key, \verb|m|. That matrix should have
three rows, one per homogeneous vertex.

\begin{Verbatim}
\appendtriangle[
  m = {
        return Matrix:new{
          {-1, -1, 0, 1},
          { 1, -1, 0, 1},
          { 0,  1, 0, 1}
        }
      },
  fill options = {fill=ltdtbrightness, draw=black}
]
\end{Verbatim}

If any two vertices coincide after evaluation, the triangle is discarded. The
package does this intentionally so that degenerate faces do not pollute the
partitioning and sorting stages.

\subsection{Labels}

Labels are appended by three-dimensional position but rendered as ordinary TikZ
nodes in the projected plane.

\begin{Verbatim}
\appendlabel[
  v = {return Vector:new{0.2, 0.6, 0.4, 1}},
  text = {$p$}
]
\end{Verbatim}

The \verb|text| key is passed directly into the node body. Since labels are
rendered after geometry, they are a good mechanism for annotations, captions, and
 callouts that should remain visible regardless of occlusion.

\subsection{About isolated points}

The Lua layer still understands point-like simplex records, but the public
\verb|\appendpoint| command is not exported by the current style file. If a figure
needs a visible point marker, the easiest replacements are:

\begin{itemize}[leftmargin=2em]
\item a tiny surface patch oriented toward the viewer;
\item a small triangle or short curve segment used as a marker;
\item a label whose text is itself the marker, such as \verb|$\bullet$|.
\end{itemize}

For example, a tiny disk-like patch can be approximated with a surface whose
parameter domain is a small polar rectangle.

\begin{Verbatim}
\appendsurface[
  uparams = {return Vector:new{0, tau, 16}},
  vparams = {return Vector:new{0, 0.08, 2}},
  v = {return Vector:new{0.6 + v*math.cos(u), 0.3 + v*math.sin(u), 0.2, 1}},
  fill options = {fill=black, draw=none}
]
\end{Verbatim}

\subsection{Using \texttt{\textbackslash luatikztdtoolsset}}

The wrapper \verb|\luatikztdtoolsset| is simply a convenience entry into the key
family \verb|/lua-tikz3dtools/.cd|. It is most useful when you want to establish
defaults before several append commands. For example, a document may prefer to
store a common surface style in the key tree and then override it only locally.

In most figures this is optional. Local keys attached to each append command are
usually clearer than globally mutated defaults.