\section{Parametric Curves, Surfaces, and Solids}
\label{sec:parametric}

The parametric commands are where lua-tikz3dtools becomes more than a triangle
dispatcher. Each command samples a user-provided function over one, two, or three
parameter directions and converts the result into simplices that the renderer can
sort.

\subsection{Parameter triples}

The keys \verb|uparams|, \verb|vparams|, and \verb|wparams| each expect a vector
of the form

\begin{Verbatim}
return Vector:new{start, stop, samples}
\end{Verbatim}

The sample count must be at least $2$. Legacy keys such as \verb|ustart|,
\verb|ustop|, and \verb|usamples| are still recognized, but the triple form is
better because it keeps each parameter direction self-contained.

\subsection{Curves}

The command \verb|\appendcurve| interprets its \verb|v| key as the body of a Lua
function in one variable \verb|u|. Consecutive samples are connected by line
segments. The visual style is controlled by \verb|draw options|. Optional
\verb|arrow tip| and \verb|arrow tail| values generate small surface geometry at
the end points.

\begin{Verbatim}
\appendcurve[
  uparams = {return Vector:new{0, 4*math.pi, 120}},
  v = {return Vector:new{math.cos(u), math.sin(u), 0.15*u, 1}},
  draw options = {draw=blue, very thick},
  arrow tip = {fill=blue, draw=none}
]
\end{Verbatim}

The arrowheads are not decorative TikZ path tips. They are small sampled surfaces
inserted into the scene so that they participate in the same visibility logic as
other geometric objects.

\input{figures/07-curve-sampling.tex}

\subsection{Surfaces}

The command \verb|\appendsurface| samples a function of two parameters and splits
each parameter-space cell into two triangles. The function body should return a
three-dimensional point as a homogeneous vector.

\begin{Verbatim}
\appendsurface[
  uparams = {return Vector:new{-1.5, 1.5, 40}},
  vparams = {return Vector:new{-1.5, 1.5, 40}},
  v = {return Vector:new{u, v, 0.35*(u*u - v*v), 1}},
  fill options = {fill=ltdtbrightness, draw=black!20}
]
\end{Verbatim}

The package omits degenerate triangles automatically. This is useful when a
parametric description pinches or when multiple parameter values map to the same
three-dimensional point.

\subsection{Embedded parameter-space curves on surfaces}

The key \verb|curve| on \verb|\appendsurface| is an advanced feature. It takes a
Lua chunk that returns a table of parameter-space segments. Each segment is then
clipped into the surface triangles and stored barycentrically so that it survives
subsequent triangle partitioning.

Each segment table may use either numeric entries \verb|{start, stop}| or named
fields \verb|start = ...| and \verb|stop = ...|. The end points should be
two-dimensional parameter points such as \verb|Vector:new{u, v, 1}|. An optional
Lua field \verb|drawoptions| may be added per segment.

\begin{Verbatim}
\appendsurface[
  uparams = {return Vector:new{0, 1, 32}},
  vparams = {return Vector:new{0, 1, 32}},
  v = {return Vector:new{2*u - 1, 2*v - 1, math.sin(math.pi*u)*math.sin(math.pi*v), 1}},
  fill options = {fill=ltdtbrightness, draw=none},
  curve = {
    return {
      {
        start = Vector:new{0.10, 0.10, 1},
        stop = Vector:new{0.90, 0.90, 1},
        drawoptions = "draw=black, thick"
      },
      {
        start = Vector:new{0.10, 0.90, 1},
        stop = Vector:new{0.90, 0.10, 1},
        drawoptions = "draw=black, dashed"
      }
    }
  }
]
\end{Verbatim}

This feature is especially useful for displaying coordinate curves, domain cuts,
or trajectories that are naturally defined in the surface's own parameter domain.

\input{figures/07-embedded-curves.tex}

\subsection{Solids}

The command \verb|\appendsolid| samples a function of three parameters but does
not try to fill the volume. Instead it tessellates the six boundary faces of the
parameter box. This is exactly what most illustrative applications need: the
visible boundary of a sampled solid.

\begin{Verbatim}
\appendsolid[
  uparams = {return Vector:new{-1, 1, 16}},
  vparams = {return Vector:new{-1, 1, 16}},
  wparams = {return Vector:new{-1, 1, 16}},
  v = {return Vector:new{1.2*u, 0.9*v, 0.7*w, 1}},
  fill options = {fill=ltdtbrightness, draw=black!15}
]
\end{Verbatim}

The same caveat as for surfaces applies: the quality of the result depends on the
sampling resolution. A boundary that bends sharply should be sampled more densely
than a nearly planar one.