\section{The Scene Model}
\label{sec:scene-model}

The package internally stores a scene as a list of simplices and labels.
In this manual the word \emph{simplex} is used in the package's broad internal
sense: a point-like entry, a line segment, or a triangle. User-facing commands
create those records indirectly.

\subsection{What each append command contributes}

\begin{itemize}[leftmargin=2em]
\item \verb|\appendtriangle| contributes a single triangle;
\item \verb|\appendcurve| samples a function of one parameter and contributes line segments;
\item \verb|\appendsurface| samples a function of two parameters and contributes triangles;
\item \verb|\appendsolid| samples a function of three parameters and contributes triangles on the six boundary faces;
\item \verb|\appendlabel| contributes a label record that is rendered last;
\item \verb|\appendlight| contributes a light direction used when triangles are drawn.
\end{itemize}

All geometric data are stored in three dimensions before projection. The final
TikZ paths are emitted only after the renderer has decided how overlapping pieces
must be partitioned and in what order they should appear.

\subsection{Why \texttt{\textbackslash displaysimplices} is the real render step}

The command \verb|\displaysimplices| performs more than one task.

\begin{enumerate}[leftmargin=2em]
\item It computes two-dimensional bounding boxes for non-label geometry.
\item It partitions geometry by overlapping parent pieces when an exact split is needed.
\item It applies user filters to the resulting pieces.
\item It computes an occlusion order.
\item It emits TikZ paths for segments and triangles and TikZ nodes for labels.
\item It clears the accumulated scene so the next display starts fresh.
\end{enumerate}

Because the scene is cleared at the end of rendering, a typical document builds
one scene, displays it, and then starts a new scene if another independent figure
is needed later.

\input{figures/03-scene-model-flowchart.tex}

\subsection{Labels are intentionally different}

Labels are stored with the scene, but they are not treated like occluding
surfaces. They are rendered after all geometric simplices have been emitted.
This is a deliberate design choice: labels should remain legible, and the author
typically wants to manage label visibility manually rather than through geometric
clipping.

The consequence is simple but important. If a label should disappear when it is
behind a surface, that behavior must be achieved through a filter or through a
separate labeling strategy. It does not happen automatically.

\subsection{The scene is geometric, not painterly}

The package does not merely sort previously drawn objects by a single depth value.
If two triangles intersect in projection, the renderer can partition one or both
of them and sort the resulting pieces separately. This is why figures made with
lua-tikz3dtools remain usable even after the obvious ``sort by centroid'' or
``draw in input order'' methods fail.

At the same time, the package is still based on sampled geometry. Parametric
curves, surfaces, and solids are discretized first. The visibility logic works on
those discretized pieces, not on the continuous mathematical object that the user
had in mind before sampling.