\chapter{Getting started}

\section{Requirements}

The package is written for Lua\LaTeX{}.  In practical terms, this means that
the document must be compiled with \verb|lualatex| and that the package
source must be visible to both the \TeX{} and Lua search paths.  If the
package has been installed into a local or system \verb|texmf| tree, that
requirement is already satisfied.  If one is working directly from the source
tree, the usual approach is to point \verb|TEXINPUTS| and \verb|LUAINPUTS|
at the \verb|src| directory before compiling.

The package assumes that the user is comfortable with TikZ and with basic Lua
expressions.  It does not require one to write standalone Lua files, but it
does ask the user to write algebraic expressions inside TikZ keys.

\manualnote{This package will not work under pdf\LaTeX{} or Xe\LaTeX{}.  The
Lua backend is essential to the command interface.}

\section{A first document}

The smallest useful way to meet the package is to draw a surface and a curve
inside a \verb|tikzpicture|, and then render the scene with
\verb|\displaysimplices|. The example below is deliberately modest. It is not
meant to show everything; it is meant to establish the rhythm of use.

\begin{verbatim}
\documentclass{article}
\usepackage{tikz}
\usepackage{lua-tikz3dtools}

\begin{document}
\begin{tikzpicture}
	\appendlight[
		v={return Vector:new{0,0,1,1}}
	]
	\appendsurface[
		ustart=0, ustop=1, usamples=16,
		vstart=0, vstop=1, vsamples=16,
		v={return Vector:new{
			u-0.5,
			v-0.5,
			0.25*sin(u*tau)*sin(v*tau),
			1
		}},
		fill options={fill=ltdtbrightness, draw=black, very thin}
	]
	\appendcurve[
		ustart=0, ustop=1, usamples=24,
		v={return Vector:new{u-0.5,0,0.35,1}},
		draw options={thick, red}
	]
	\displaysimplices
\end{tikzpicture}
\end{document}
\end{verbatim}

The workflow is worth stating plainly. Geometry is appended first. Nothing is
drawn at that moment. Only when \verb|\displaysimplices| is called does the
package partition the scene where necessary, apply filters, sort the visible
pieces, and emit the final TikZ paths.

\begin{figure}[tbp]
    \centering
    \begin{tikzpicture}
        \setobject[
            name=view,
            object={Matrix.xrotation3(-pi/5):multiply(Matrix.zrotation3(pi/6))}
        ]
        \appendlight[v={return Vector:new{1,1,2,1}}]
        \appendsurface[
            ustart=0, ustop=1, usamples=16,
            vstart=0, vstop=1, vsamples=16,
            v={return Vector:new{
                3*(u-0.5),
                3*(v-0.5),
                0.75*sin(u*tau)*sin(v*tau),
                1
            }},
            transformation={view},
            fill options={fill=ltdtbrightness, draw=black, very thin}
        ]
        \appendcurve[
            ustart=0, ustop=1, usamples=24,
            v={return Vector:new{3*(u-0.5), 0, 1.05, 1}},
            transformation={view},
            draw options={thick, red}
        ]
        \displaysimplices
    \end{tikzpicture}
    \caption{A wavy surface with a red curve floating above it.  The scene
    is assembled by appending geometry and then rendered with a single call
    to \texttt{\string\displaysimplices}.}
\end{figure}

\section{How to read the key syntax}

Each append command takes TikZ keys in its optional argument. Some of those
keys hold plain numbers, such as \verb|ustart=0|, while others hold Lua
expressions, such as \verb|v={return Vector:new{u,0,0,1}}|. Because TikZ also uses
commas to separate keys, any Lua expression containing commas should be
wrapped in braces. In practice, it is simplest to place nearly all nontrivial
Lua expressions inside braces from the start.

There are two recurring defaults throughout the interface. The
\verb|transformation| key defaults to \verb|Matrix:identity3()|, and the
\verb|filter| key defaults to \verb|return true|. This means that most first
examples can ignore both. When the geometry becomes more elaborate, these two
keys become central.

One point of notation is mildly unfortunate but harmless once learned. The key
named \verb|v| is overloaded. For points, labels, and lights, it means a
vector-valued body. For curves, surfaces, and solids, it means the
parametric map itself. In every case, the value of \verb|v| is a Lua body
that must contain an explicit \verb|return| statement, just like \verb|filter|.
This allows multi-statement code when needed. The chapter on the command
reference makes this precise for each command.

\section{What to expect from the first compile}

The first successful figure usually answers three immediate questions.  First,
whether the package is being found at all.  Second, whether the Lua
expressions are syntactically sound.  Third, whether the tessellation density
is already high enough to communicate the shape clearly.  If the answer to
the last question is no, the right response is usually to increase sample
counts gradually rather than dramatically.

That final point matters because this package does real geometric work after
tessellation.  More samples mean more simplices to partition, filter, sort,
and draw.  The manual therefore encourages a coarse-to-fine workflow: begin
with a figure that is merely recognizable, and refine it only once the
geometry and occlusion are correct.  Chapter~\ref{ch:practical} returns to
this topic in more detail.