\chapter{Command reference}

\section{General conventions}

All append commands take their input as TikZ keys. When a key contains a Lua
expression with commas, braces should be used to protect that expression from
TikZ's key parser. The keys \verb|transformation| and \verb|filter| recur
throughout the interface. Unless stated otherwise, \verb|transformation|
defaults to \verb|Matrix:identity3()| and \verb|filter| defaults to
\verb|return true|.

The object types exposed to expressions are \verb|Vector| and \verb|Matrix|,
together with standard mathematical functions and the constant \verb|tau|.
Expressions are evaluated in a restricted environment intended for geometry,
not for general system access.

\section{Scene management commands}

\subsection*{\texttt{\string\setobject}}

Use \verb|\setobject| to bind a name to an arbitrary Lua value.

\begin{description}
	\item[\texttt{name}] The symbol to be introduced into the expression environment.
	\item[\texttt{object}] A Lua expression whose value will be bound to that name.
\end{description}

This command is most useful for storing reusable matrices, vectors, and other
objects that would otherwise be repeated across several append commands.

\subsection*{\texttt{\string\displaysimplices}}

Use \verb|\displaysimplices| to render the current scene. This command takes
no keys. It partitions the geometry where necessary, applies filters, sorts
the resulting simplices by occlusion, emits TikZ paths, and then clears both
the scene and the current light list.

\subsection*{\texttt{\string\luatikztdtoolsset}}

The helper \verb|\luatikztdtoolsset| is a thin wrapper around \verb|\tikzset|
with the package family selected in advance. Most users will not need it in
day-to-day work, but it remains available for defining package-local styles or
experimenting with key defaults.

\section{Point, label, and light commands}

\subsection*{\texttt{\string\appendpoint}}

Append a single point to the scene.

\begin{description}
	\item[\texttt{v}] Required. A Lua body producing a \verb|Vector|.
	\item[\texttt{fill options}] Optional. TikZ options used when drawing the point.
	\item[\texttt{transformation}] Optional. A matrix applied to the point.
	\item[\texttt{filter}] Optional. A predicate evaluated on the point simplex.
\end{description}

Internally the point is rendered as a small circle of fixed radius. If a scene
demands points of visibly different sizes, a custom construction using curves
or surfaces may be the better choice.

\subsection*{\texttt{\string\appendlabel}}

Append a label anchored at a point.

\begin{description}
	\item[\texttt{v}] Required. A Lua body producing a \verb|Vector|.
	\item[\texttt{text}] Required. The label contents.
	\item[\texttt{transformation}] Optional. A matrix applied to the anchor point.
	\item[\texttt{filter}] Optional. A predicate evaluated on the label anchor.
\end{description}

Labels are emitted after the geometry rather than participating in occlusion.
This makes them suitable for annotation, but not for physically hidden text.

\subsection*{\texttt{\string\appendlight}}

Append a directional light vector.

\begin{description}
	\item[\texttt{v}] Required. A Lua body returning a \verb|Vector| giving the light direction.
\end{description}

Lights affect triangles, including triangles generated from surfaces, solids,
and curve arrowheads. The accumulated light state is cleared after each
\verb|\displaysimplices|.

\section{Curve, surface, and solid commands}

\subsection*{\texttt{\string\appendcurve}}

Append a parametric curve, sampled into line segments.

\begin{description}
	\item[\texttt{ustart}] Optional. Default \verb|0|.
	\item[\texttt{ustop}] Optional. Default \verb|1|.
	\item[\texttt{usamples}] Optional. Default \verb|10|. Must be at least 2.
	\item[\texttt{v}] Required. A Lua body in \verb|u| returning a \verb|Vector|.
	\item[\texttt{transformation}] Optional. A matrix applied after evaluation.
	\item[\texttt{draw options}] Optional. TikZ options for the line segments.
	\item[\texttt{arrow tip}] Optional. Fill options for a generated arrowhead.
	\item[\texttt{arrow tail}] Optional. Fill options for a generated tail marker.
	\item[\texttt{filter}] Optional. A predicate evaluated on each segment.
\end{description}

The \verb|arrow tip| and \verb|arrow tail| keys do not invoke TikZ's native
arrow-tip machinery. Instead, the package generates small parametric surfaces
attached to the endpoints of the sampled curve.

\subsection*{\texttt{\string\appendsurface}}

Append a parametric surface, sampled into triangles.

\begin{description}
	\item[\texttt{ustart}] Optional. Default \verb|0|.
	\item[\texttt{ustop}] Optional. Default \verb|1|.
	\item[\texttt{usamples}] Optional. Default \verb|10|. Must be at least 2.
	\item[\texttt{vstart}] Optional. Default \verb|0|.
	\item[\texttt{vstop}] Optional. Default \verb|1|.
	\item[\texttt{vsamples}] Optional. Default \verb|10|. Must be at least 2.
	\item[\texttt{v}] Required. A Lua body in \verb|u| and \verb|v| returning a \verb|Vector|.
	\item[\texttt{transformation}] Optional. A matrix applied after evaluation.
	\item[\texttt{fill options}] Optional. TikZ options for the triangles.
	\item[\texttt{filter}] Optional. A predicate evaluated on each triangle.
\end{description}

Each rectangular parameter cell is divided into two triangles. Degenerate
cases are skipped when the sampled vertices collapse together.

\subsection*{\texttt{\string\appendsolid}}

Append a parametric solid by tessellating the boundary of a three-parameter
domain.

\begin{description}
	\item[\texttt{ustart}, \texttt{ustop}, \texttt{usamples}] Optional. Defaults \verb|0|, \verb|1|, \verb|10|.
	\item[\texttt{vstart}, \texttt{vstop}, \texttt{vsamples}] Optional. Defaults \verb|0|, \verb|1|, \verb|10|.
	\item[\texttt{wstart}, \texttt{wstop}, \texttt{wsamples}] Optional. Defaults \verb|0|, \verb|1|, \verb|10|.
	\item[\texttt{v}] Required. A Lua body in \verb|u|, \verb|v|, and \verb|w| returning a \verb|Vector|.
	\item[\texttt{transformation}] Optional. A matrix applied after evaluation.
	\item[\texttt{fill options}] Optional. TikZ options for the triangles.
	\item[\texttt{filter}] Optional. A predicate evaluated on each triangle.
\end{description}

All three sample counts must be at least 2. At present the command tessellates
the six outer faces of the parameter box rather than constructing a volumetric
interior mesh.

\section{Explicit simplex command}

\subsection*{\texttt{\string\appendtriangle}}

Append an explicit triangle.

\begin{description}
	\item[\texttt{A}] Required. A Lua expression producing the first vertex.
	\item[\texttt{B}] Required. A Lua expression producing the second vertex.
	\item[\texttt{C}] Required. A Lua expression producing the third vertex.
	\item[\texttt{transformation}] Optional. A matrix applied to the triangle.
	\item[\texttt{fill options}] Optional. TikZ options for the triangle.
	\item[\texttt{filter}] Optional. A predicate evaluated on the triangle.
\end{description}

This command is useful when the desired object is already simplicial, or when
one wants exact control over a small piece of visible geometry without passing
through a parametric sampling stage.