\section{Vector and Matrix Cookbook}

This appendix records the most useful Lua-side constructors and helpers for users
who want to build scene data more explicitly.

\subsection{General guidance}

Use the validated constructors \verb|Vector:new| and \verb|Matrix:new| in
document-level code. Internal unchecked constructors such as
\verb|Vector:\_new| and \verb|Matrix:\_new| exist for performance inside the
package implementation and are not the intended public interface.

\subsection{Useful vector constructors and helpers}

{\footnotesize
\setlength{\tabcolsep}{5pt}
\begin{longtable}{>{\raggedright\arraybackslash}p{0.40\linewidth} >{\raggedright\arraybackslash}p{0.46\linewidth}}
\toprule
Function & Purpose \\
\midrule
\endfirsthead
\toprule
Function & Purpose \\
\midrule
\endhead
\texttt{Vector:new\{x,y,z,1\}} & General homogeneous point constructor. \\
\texttt{Vector.sphere(Vector:new\{theta,phi,r\})} & Point on a sphere from spherical coordinates. \\
\texttt{Vector.stereographic\_projection(v)} & Stereographic projection of a three-dimensional point. \\
\nolinkurl{Vector.inverse_stereographic_projection(v)} & Inverse stereographic projection from a planar point. \\
\texttt{v:hadd(w)}, \texttt{v:hsub(w)} & Homogeneous addition and subtraction. \\
\texttt{v:hinner(w)} & Homogeneous inner product ignoring the last coordinate. \\
\texttt{v:hhypercross(w)} & Cross-product-like construction used for normals and orthogonal vectors. \\
\texttt{v:hnormalize()} & Normalize the spatial part of a vector. \\
\texttt{v:orthogonal\_vector()} & Return an arbitrary vector orthogonal to \texttt{v}. \\
\bottomrule
\end{longtable}
}

\subsection{Useful matrix constructors and helpers}

{\footnotesize
\setlength{\tabcolsep}{5pt}
\begin{longtable}{>{\raggedright\arraybackslash}p{0.40\linewidth} >{\raggedright\arraybackslash}p{0.46\linewidth}}
\toprule
Function & Purpose \\
\midrule
\endfirsthead
\toprule
Function & Purpose \\
\midrule
\endhead
\texttt{Matrix.identity()} & Identity transformation. \\
\texttt{Matrix.translate(delta)} & Translation by a vector \texttt{delta}. \\
\texttt{Matrix.scale\_axis(scale)} & Axis-aligned scaling. \\
\texttt{Matrix.axis\_angle(axis, theta)} & Rotation about an arbitrary axis through the origin. \\
\texttt{Matrix.zyzrotation(angles)} & ZYZ Euler rotation. \\
\texttt{Matrix.shear(...)} & Six-parameter shear matrix. \\
\texttt{Matrix.reflect\_axis(axis)} & Reflection about an axis through the origin. \\
\texttt{Matrix.perspective(axis)} & Projective perspective transform. \\
\texttt{Matrix.transform\_about(point, T)} & Conjugate a transform \texttt{T} by a fixed point. \\
\texttt{M:multiply(N)} & Matrix composition in row-vector order. \\
\texttt{M:get\_bbox2()}, \texttt{M:get\_bbox3()} & Axis-aligned bounding boxes. \\
\texttt{M:hcentroid()} & Homogeneous centroid of the rows. \\
\bottomrule
\end{longtable}
}

\subsection{Typical recipes}

\paragraph{Rotate, then translate.}

\begin{Verbatim}
return Matrix.axis_angle(Vector:new{0, 0, 1, 1}, 0.6)
  :multiply(Matrix.translate(Vector:new{2, 0, 0, 1}))
\end{Verbatim}

\paragraph{Build a tilted sphere point.}

\begin{Verbatim}
return Vector.sphere(Vector:new{u, v, 1.4})
  :multiply(Matrix.axis_angle(Vector:new{1, 0, 0, 1}, 0.8))
\end{Verbatim}

\paragraph{Apply a local motion about a non-origin point.}

\begin{Verbatim}
return Matrix.transform_about(
  Vector:new{1, 2, 0, 1},
  Matrix.axis_angle(Vector:new{0, 0, 1, 1}, 0.4)
)
\end{Verbatim}