\section{Overview}

lua-tikz3dtools is a LuaLaTeX package for constructing three-dimensional figures
inside ordinary TikZ pictures. The package is aimed at mathematical and
technical drawings where visibility matters: curves should disappear behind
surfaces, intersecting triangles should be split when necessary, and the author
should be able to describe geometry in coordinates instead of manually ordering
every path.

The package sources and the evolving example collection are maintained at
\url{https://github.com/Pseudonym321/TikZ-Animations/tree/master1/TikZ/lua-tikz3dtools}.

The public interface is intentionally small. In practice you define reusable Lua
objects with \verb|\setobject|, append geometry with commands such as
\verb|\appendtriangle| or \verb|\appendsurface|, optionally add lights and
filters, and finish the picture with \verb|\displaysimplices|. Everything before
that final command only builds an internal scene.

\input{figures/01-overview-gallery.tex}

The checked-in gallery is intentionally larger than the minimal tutorial path.
The second spread leans harder into showpiece scenes so the manual demonstrates
both routine usage and the more decorative end of the package.

\input{figures/01-overview-showcase.tex}

\subsection{What the package does well}

The package is strongest when the final picture can be reduced to triangles and
line segments after sampling. This includes:

\begin{itemize}[leftmargin=2em]
\item individual triangles;
\item sampled parametric curves;
\item tessellated parametric surfaces;
\item sampled solid boundaries;
\item labels placed by three-dimensional coordinates;
\item layered scenes where visibility must be computed automatically.
\end{itemize}

The package also provides a small but useful mathematical layer based on
homogeneous vectors and matrices. Those objects are available directly from the
Lua snippets embedded in the TikZ keys, so the same package can serve as both a
scene description system and a lightweight geometry toolkit.

\subsection{Public commands at a glance}

The checked-in style file currently exports the following commands:

\begin{itemize}[leftmargin=2em]
\item \verb|\luatikztdtoolsset|, a convenience wrapper around the package key family;
\item \verb|\setobject| for reusable Lua values;
\item \verb|\appendlabel| for labels placed by a three-dimensional point;
\item \verb|\appendlight| for directional lights;
\item \verb|\appendtriangle| for a single triangle;
\item \verb|\appendcurve| for a sampled parametric curve;
\item \verb|\appendsurface| for a sampled parametric surface;
\item \verb|\appendsolid| for a sampled solid boundary;
\item \verb|\displaysimplices| for partitioning, sorting, and rendering the scene.
\end{itemize}

An internal point primitive exists on the Lua side, but the public
\verb|\appendpoint| macro is commented out in the present style file. For that
reason this manual treats point-like markers as a design pattern rather than as
an exported command; Section~\ref{sec:basic-primitives} discusses practical
replacements.

\subsection{How this manual is organized}

The first half of the manual is workflow-driven. It starts with a minimal
document, explains the scene model, and then introduces the Lua-expression
conventions and the transformation layer. The second half is reference-oriented:
it records command keys, rendering behavior, limitations, and the low-level Lua
API for readers who want to extend the package or reason about its internals.

If you are reading this package for the first time, the best path is
Section~\ref{sec:getting-started}, then
Section~\ref{sec:scene-model}, then
Section~\ref{sec:lua-expressions}, and only afterward the command reference in
Section~\ref{sec:command-reference}.