% lua-tikz3dtools-doc.tex
\DocumentMetadata{
	lang         = en
	,pdfversion  = 2.0
	,pdfstandard = {UA-2}
}
\documentclass[letterpaper]{article}

\usepackage{microtype}
\usepackage{lua-tikz3dtools}

\title{The lua-tikz3dtools package v2.3.0\\\vspace{.5cm}\tiny{}https://github.com/Pseudonym321/TikZ-Animations/tree/master1/TikZ/lua-tikz3dtools}
\author{Jasper Nice}
\date{January 22, 2026}

\begin{document}

\maketitle

This work is licensed under the \LaTeX{} Project Public License,
version 1.3c or later.\par This work was typeset using \TeX{}, 
the typesetting system created by Donald~E.~Knuth, along with various 
extensions and packages developed by the \TeX{} community. I am 
grateful to the \TeX{} Stack Exchange community for their ongoing 
support and resources.\par\vspace{2em}\hfill\textit{Jasper~Nice}

\section{Introduction}

The lua-tikz3dtools package is a project of mine that aims to provide 
tools for creating 3D illustrations in TikZ using LuaLaTeX. 
In particular, it focuses on parametric 3D objects, allowing users to 
define points, curves, surfaces, solids, and triangles in 3D space using
various parameters. The package leverages Lua scripting to handle the
complex calculations required for 3D rendering, making it less slow to 
render graphics. Moreover, the graphics produced by this package are 
properly occluded in edge cases which break most other programs.

\section{Commands and keys}

The package provides several commands and keys for defining and manipulating
3D objects. The main commands, with their corresponding keys, are:
\begin{itemize}
    \item \verb|\setobject[<options>]|  
    Defines an arbitrary Lua object. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{name} — Name of the object.
        \item \texttt{object} — Arbitrary Lua object
    \end{itemize}
    \item \verb|\appendlight[<options>]|  
    Appends a light vector to the 3D scene. Options are passed as TikZ
    keys:
    \begin{itemize}
        \item \texttt{x} — x-coordinate of the light source.
        \item \texttt{y} — y-coordinate of the light source.
        \item \texttt{z} — z-coordinate of the light source.
    \end{itemize}
    Each light vector added contributes to a colour called brightness,
    which is defined before every triangle is drawm, and which is dependent 
    on the dot product of the triangle's normal vector and the light vectors.
    \item \verb|\appendpoint[<options>]|  
    Appends a 3D point to the current illustration. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{x} — x-coordinate of the point.
        \item \texttt{y} — y-coordinate of the point.
        \item \texttt{z} — z-coordinate of the point.
        \item \texttt{fill options} — TikZ options for filling the point.
        \item \texttt{transformation} — Transformation matrix to apply to the point.
        \item \texttt{filter} — Boolean to determine if the point should be filtered.
    \end{itemize}
    \item \verb|\appendlabel[<options>]|  
    Appends a label to a 3D object. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{x} — x-coordinate of the label.
        \item \texttt{y} — y-coordinate of the label.
        \item \texttt{z} — z-coordinate of the label.
        \item \texttt{text} — Text of the label.
        \item \texttt{transformation} — Transformation matrix to apply to the label.
        \item \texttt{filter} — Boolean to determine if the label should be filtered.
    \end{itemize}
    \item \verb|\appendcurve[<options>]|  
    Appends a 3D curve to the current illustration. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{ustart} — Start parameter of the curve.
        \item \texttt{ustop} — Stop parameter of the curve.
        \item \texttt{usamples} — Number of samples along the curve.
        \item \texttt{x} — x-coordinate function of the curve.
        \item \texttt{y} — y-coordinate function of the curve.
        \item \texttt{z} — z-coordinate function of the curve.
        \item \texttt{transformation} — Transformation matrix to apply to the curve.
        \item \texttt{filter} — Boolean to determine if the curve should be filtered.
        \item \texttt{draw options} — TikZ options for drawing the curve.
        \item \texttt{arrow tip} — Arrow tip style for the curve.   
        \item \texttt{arrow tail} — Arrow tail style for the curve.
    \end{itemize}
    \item \verb|\appendsurface[<options>]|  
    Appends a 3D surface to the current illustration. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{ustart} — Start parameter in the u-direction.
        \item \texttt{ustop} — Stop parameter in the u-direction.
        \item \texttt{usamples} — Number of samples in the u-direction.
        \item \texttt{vstart} — Start parameter in the v-direction.
        \item \texttt{vstop} — Stop parameter in the v-direction.
        \item \texttt{vsamples} — Number of samples in the v-direction.
        \item \texttt{x} — x-coordinate function of the surface.
        \item \texttt{y} — y-coordinate function of the surface.
        \item \texttt{z} — z-coordinate function of the surface.
        \item \texttt{transformation} — Transformation matrix to apply to the surface.
        \item \texttt{fill options} — TikZ options for filling the surface.
        \item \texttt{filter} — Boolean to determine if the surface should be filtered
    \end{itemize}
    \item \verb|\appendtriangle[<options>]|  
    Appends a 3D triangle to the current illustration. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{A} — Coordinates of vertex A.
        \item \texttt{B} — Coordinates of vertex B.
        \item \texttt{C} — Coordinates of vertex C.
        \item \texttt{transformation} — Transformation matrix to apply to the triangle.
        \item \texttt{fill options} — TikZ options for filling the triangle.
        \item \texttt{filter} — Boolean to determine if the triangle should be filtered.
    \end{itemize}
    \item \verb|\appendsolid[<options>]|  
    Appends a 3D solid to the current illustration. Options are passed as TikZ keys:
    \begin{itemize}
        \item \texttt{ustart} — Start parameter in the u-direction.
        \item \texttt{ustop} — Stop parameter in the u-direction.
        \item \texttt{usamples} — Number of samples in the u-direction.
        \item \texttt{vstart} — Start parameter in the v-direction.
        \item \texttt{vstop} — Stop parameter in the v-direction.
        \item \texttt{vsamples} — Number of samples in the v-direction.
        \item \texttt{wstart} — Start parameter in the w-direction.
        \item \texttt{wstop} — Stop parameter in the w-direction.
        \item \texttt{wsamples} — Number of samples in the w-direction.
        \item \texttt{x} — x-coordinate function of the solid.
        \item \texttt{y} — y-coordinate function of the solid.
        \item \texttt{z} — z-coordinate function of the solid.
        \item \texttt{transformation} — Transformation matrix to apply to the solid.
        \item \texttt{fill options} — TikZ options for filling the solid.
        \item \texttt{filter} — Boolean to determine if the solid should be filtered.
    \end{itemize}
    \item \verb|\displaysimplices|  
    Displays all simplices in the current illustration.
\end{itemize}

\section{Useful information}

I strongly advise that practicioners of this package read the source 
code because the methods are important to know when using this package.

If you have any questions, suggestions, or issues regarding this package,
please feel free to reach out to me via my GitHub repository or by 
asking a question on TeX Stack Exchange.

\end{document}