\chapter{Linear algebra reference}
\label{ch:linalg}

\section{Homogeneous coordinates}

The package works with homogeneous 4-vectors for 3D affine geometry. In the
examples throughout the manual, a point in ordinary 3-space therefore appears
as a vector such as \verb|Vector:new{x,y,z,1}|. This convention allows
translations, rotations, and scalings to be handled uniformly by matrix
multiplication.

For most user-facing work, the final coordinate should simply be taken as
\verb|1|. The manual does not require one to manipulate the homogeneous
coordinate directly unless a specialized construction calls for it.

\section{The \texttt{Vector} type}

User expressions have access to the validated constructor
\verb|Vector:new{...}|. The type supports the operations needed by the package
internally and by user-written filters and helper expressions. Among the most
useful are homogeneous subtraction \verb|:hsub(...)|, homogeneous inner
product \verb|:hinner(...)|, homogeneous normalization \verb|:hnormalize()|,
and ordinary matrix multiplication through \verb|:multiply(...)|.

The unchecked constructor \verb|Vector:_new{...}| also exists, but it is meant
for internal hot paths. In manual examples, the validated constructor is the
better default.

\section{The \texttt{Matrix} type}

User expressions likewise have access to \verb|Matrix:new{...}| for explicit
matrices and to a number of 3D helper constructors:

\begin{description}
	\item[\texttt{Matrix.identity3()}] The identity transformation.
	\item[\texttt{Matrix.translate3(dx,dy,dz)}] Translation in 3D.
	\item[\texttt{Matrix.scale3(sx,sy,sz)}] Axis-aligned scaling.
	\item[\texttt{Matrix.xrotation3(theta)}] Rotation about the x-axis.
	\item[\texttt{Matrix.yrotation3(theta)}] Rotation about the y-axis.
	\item[\texttt{Matrix.zrotation3(theta)}] Rotation about the z-axis.
	\item[\texttt{Matrix.zyzrotation3(alpha,beta,gamma)}] A ZYZ Euler rotation.
\end{description}

These helpers cover most document-scale figures. When a custom matrix is more
natural, \verb|Matrix:new{...}| remains available.

\section{Composition order}

The transformation pipeline uses row vectors. A point is multiplied on the
left by its transformation matrix. This means that if a user writes
\verb|A:multiply(B)| as a transformation, the effect on a point is first the
transformation \verb|A| and then the transformation \verb|B|.

This convention is simple once internalized, but it differs from the column-
vector convention used by many other texts and libraries. When a figure seems
to move in the wrong direction or to rotate about the wrong place, the first
question should usually be whether the composed matrices have been written in
the intended order.