\documentclass[letterpaper]{article}

\usepackage{microtype}
\usepackage{mathtools}
\usepackage{unicode-math}
\usepackage{tabularx}
\usepackage{booktabs}

\usepackage{lua-tikz3dtools}

\title{lua-tikz3dtools documentation v3.2.0}
\author{Jasper Nice}
\date{2026-05-21}

\begin{document}

\maketitle
\tableofcontents


\section{What this package is}

This package handles three main things; matrix based projective 
transformations, simplicial occlusion, and simplicial partitioning.

Users append optioned simplices and simplicially tessellated 
parametric objects to a big list, and lua-tikz3dtools handles 
the projective transformations, the simplical partitioning, and 
the simplicial occlusion.

\section{Command reference}

This section collects the public commands and their keys in reference form.
Examples remain brief here; the larger workflow discussion is in the earlier
sections.

\subsection{\texttt{\textbackslash luatikztdtoolsset}}

Convenience wrapper for setting keys in the family
\verb|/lua-tikz3dtools/.cd|. Use it when document-wide or figure-wide defaults are
worth centralizing.

\subsection{\texttt{\textbackslash setobject}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{name} & nonempty string & Name stored in the sandbox object table. \\
\texttt{object} & Lua chunk & Evaluated object to store under \texttt{name}. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendlabel}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{v} & point expression & Three-dimensional label position. \\
\texttt{text} & TeX material & Node body emitted after the geometry. \\
\texttt{transformation} & matrix expression & Optional transform; default is identity. \\
\texttt{filter} & Lua block & Predicate on the projected point \texttt{A}; default returns true. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendlight}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{v} & vector expression & Directional light vector. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendtriangle}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{m} & matrix expression & Whole $3 \times 4$ triangle matrix, with one homogeneous vertex per row. \\
\texttt{transformation} & matrix expression & Optional transform; default is identity. \\
\texttt{fill options} & TikZ option list & Styling for the emitted triangle path. \\
\texttt{filter} & Lua block & Predicate on the triangle vertices \texttt{A}, \texttt{B}, \texttt{C}. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendcurve}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{uparams} & parameter triple & Start, stop, and sample count for \texttt{u}. \\
\texttt{v} & function body in \texttt{u} & Returns a point for each sample. \\
\texttt{transformation} & matrix expression & Optional transform; default is identity. \\
\texttt{draw options} & TikZ option list & Styling for emitted segments. \\
\texttt{arrow tip} & TikZ option list & Style for geometric arrowhead at the end. \\
\texttt{arrow tail} & TikZ option list & Style for geometric arrowhead at the start. \\
\texttt{filter} & Lua block & Predicate on segment endpoints \texttt{A}, \texttt{B}. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendsurface}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{uparams}, \texttt{vparams} & parameter triples & Start, stop, and sample counts for the two parameters. \\
\texttt{v} & function body in \texttt{u,v} & Returns the sampled point on the surface. \\
\texttt{transformation} & matrix expression & Optional transform; default is identity. \\
\texttt{fill options} & TikZ option list & Styling for emitted triangles. \\
\texttt{filter} & Lua block & Predicate on triangle vertices \texttt{A}, \texttt{B}, \texttt{C}. \\
\texttt{curve} & Lua chunk & Returns a table of parameter-space line segments to embed on the surface. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash appendsolid}}

\begin{tabularx}{\linewidth}{>{\raggedright\arraybackslash}p{0.22\linewidth} >{\raggedright\arraybackslash}p{0.20\linewidth} X}
\toprule
Key & Expected value & Meaning \\
\midrule
\texttt{uparams}, \texttt{vparams}, \texttt{wparams} & parameter triples & Parameter ranges and sample counts for the three directions. \\
\texttt{v} & function body in \texttt{u,v,w} & Returns the sampled point in space. \\
\texttt{transformation} & matrix expression & Optional transform; default is identity. \\
\texttt{fill options} & TikZ option list & Styling for emitted boundary triangles. \\
\texttt{filter} & Lua block & Predicate on triangle vertices \texttt{A}, \texttt{B}, \texttt{C}. \\
\bottomrule
\end{tabularx}

\subsection{\texttt{\textbackslash displaysimplices}}

This command takes no keys. It partitions geometry if needed, applies filters,
sorts by occlusion, emits TikZ paths, emits labels, and clears the accumulated
scene and light list.


\section{Example}

\begin{verbatim}
\documentclass[tikz,border=1cm]{standalone}
\usepackage{lua-tikz3dtools} % https://github.com/Pseudonym321/TikZ-Animations/tree/master1/TikZ/lua-tikz3dtools
\begin{document}
\foreach \CCC in {15} {
\begin{tikzpicture}
\useasboundingbox (-80mm,-45mm) rectangle (80mm,45mm);
\ltdtappendlight[v = {return Vector:new{1, 1, 1 , 1}}]
\def\SSS{3}
\foreach \AAA in {0,30,60} { 
\pgfmathsetmacro{\AAA}{\AAA+\CCC}
\ltdtsetobject[
    name=a,object={return \AAA*pi/180}
]
\ltdtsetobject[
    name=R,
    object={return 1/cos(a)}
]
\ltdtsetobject[
    name=r,
    object={return sqrt(abs(1/cos(a)^2)-abs(cos(a)))}
]
\ltdtsetobject[
    name=view,
    object = {return Matrix.zyzrotation(Vector:new{pi/6, pi/3, pi/2})
    :multiply(Matrix.perspective(Vector:new{0,0,-1/8}))}
]
\pgfmathtruncatemacro{\BBB}{((\AAA-10)*10/7)}
\ltdtappendsurface[
    uparams={return Vector:new{pi/2,-pi,20}},
    vparams={return Vector:new{0,2*pi,50}},
    transformation = {return view},
    v = {
        return Vector.sphere(Vector:new{u, v, r})
        :hadd(Vector:new{R*cos(u), R*sin(u), 0, 1})
    },
    filter = {
        local M = A:hadd(B):hadd(C):hscale(1/3):multiply(view:inverse())
        return abs(M[1]) < \SSS.001 and abs(M[2]) < \SSS.001 and abs(M[3]) < \SSS.001
    },
    fill options = {fill={gray!\BBB!black!50!ltdtbrightness},fill opacity = 1},
    curve = {
        local segments = {}
        local domain_origin = pi/2
        local branches = 7
        local samples_per_branch = 40
        local samples = branches*samples_per_branch
        local step = tau/samples
        local function append_segment(s0, s1)
            if s1 <= s0 then
                return
            end
            local wrap = floor(branches*s0/tau + 1e-9)
            local u0 = domain_origin - s0
            local u1 = domain_origin - s1
            local v0 = branches*s0 - wrap*tau
            local v1 = branches*s1 - wrap*tau
            table.insert(segments, {
                Vector:new{u0, v0},
                Vector:new{u1, v1},
                drawoptions = "draw = green!50!black, thick"
            })
        end
        for i = 0, samples - 1 do
            local s0 = i*step
            local s1 = s0 + step
            local wrap0 = floor(branches*s0/tau + 1e-9)
            local wrap1 = floor(branches*s1/tau + 1e-9)
            if wrap0 == wrap1 then
                append_segment(s0, s1)
            else
                local seam = (wrap0 + 1)*tau/branches
                append_segment(s0, seam)
                append_segment(seam, s1)
            end
        end
        return segments
    }
]
} % ends foreach
\ltdtappendsolid[
    uparams={return Vector:new{-\SSS,\SSS,2}},
    vparams={return Vector:new{-\SSS,\SSS,2}},
    wparams={return Vector:new{-\SSS,\SSS,2}},
    transformation = {return view},
    filter = {return false},
    v = {return Vector:new{u, v, w, 1}}
]
\ltdtdisplaysimplices
\end{tikzpicture}} % ends \CCC
\end{document}
\end{verbatim}

\end{document}