Terathon Math Library: vectors, quaternions and geometric algebra in one C++ library

One dimension of representation underneath everything

The Terathon Math Library is a C++ library of classes for vectors, matrices, quaternions and elements of projective geometric algebra, and the organising idea is that 2D and 3D are the same object in a four-dimensional homogeneous space. Vector2D extends to four dimensions as x, y, 0, 0, and Vector3D extends as x, y, z, 0, while Point2D extends as x, y, 0, 1 and Point3D as x, y, z, 1. That pairing is the whole point: the difference between a vector and a point is where the w component sits, so a transformation written once applies to both. The consequence is that a 2D rigid body and a 3D rigid body live in the same framework, and a point in space is a point in a plane without a separate code path. The homepage points at projectivegeometricalgebra.org for the theory behind the types.

The class list spans linear algebra, rigid geometry and conformal geometry

The README enumerates the classes, and the grouping tells you where the library's centre of gravity is. The base layer is Vector2D, Vector3D, Vector4D, Point2D, Point3D, Matrix2D, Matrix3D, Matrix4D, Bivector3D, Quaternion and DualNum, where a dual number is s plus t times epsilon and the quaternion is the conventional x*i plus y*j plus z*k plus w. Above that sits 2D rigid geometric algebra with FlatPoint2D, Line2D, Motor2D and Flector2D, and 3D rigid geometric algebra with FlatPoint3D, Line3D, Plane3D, Motor3D and Flector3D. The top layer is conformal, with RoundPoint2D, Dipole2D and Circle2D in two dimensions and RoundPoint3D, Dipole3D, Circle3D and Sphere3D in three. A motor is a motion operator, a reflector is a reflection operator, and a dipole is the geometric-algebra object that carries both a direction and a position.

Transform2D and Transform3D hide their affine row

The two transform classes are worth reading separately because they encode a structural constraint rather than a general matrix. Transform2D is described as a 3x3 matrix whose fourth row is always 0, 0, 1, and Transform3D as a 4x4 matrix whose fourth row is always 0, 0, 0, 1. In other words these are not general matrices that happen to be used for affine work, they are matrices with the affine row fixed. That removes a class of bug at compile time, because a translation cannot be accidentally written into a slot that is meant to be homogeneous. It also means the general Matrix3D and Matrix4D types remain available for the cases where the constraint does not hold, so nothing is lost by having both.

Swizzling uses shading-language syntax and compiles to free operations

Component access follows the convention graphics programmers already know from GLSL and HLSL. For a Vector3D named v, v.x is the x component, v.xy is a 2D vector with the x and y components, and v.yzx is a 3D vector with the components reordered. Matrices get the same treatment: for a Matrix3D named m, m.m12 is the entry at row 1, column 2, m.row0 is the first row, m.col1 is the second column, m.matrix2D is the upper-left 2x2 submatrix, and m.transpose is the transpose. The README states that all of these are generally free operations with no copying when their results are consumed by an expression, and points to Eric Lengyel's 2018 GDC talk, Linear Algebra Upgraded, for the detail.

Repeated swizzles cost compile time, so they are behind a define

There is one deliberate limitation in the swizzling system, and it is worth knowing before you write code against it. Support for repeated components, so v.xx or v.yy, is disabled by default, and enabling it requires defining TERATHON_SWIZZLE_REPEAT. The reason given is compile time, since the large number of additional swizzling possibilities increases compile times substantially. There is a second rule attached to it: swizzles with repeated components are always const, so it is not possible to assign to them. The default configuration is the one most projects will want, since the common cases are permutations and selections rather than duplicates.

The wedge product is exposed, the geometric product deliberately is not

The geometric algebra side works through the ^ operator, which is overloaded wherever the wedge or antiwedge product can be applied between vectors, bivectors, flat points, lines, planes, round points, dipoles, circles and spheres. The README includes a practical warning: ^ has lower precedence than just about everything else, so parentheses are necessary. What the library does not provide is an operator that directly calculates the geometric product and the antiproduct. The stated reason is that such operators would tend to generate inefficient code. That is a design decision with real consequences, since the geometric product is the composition operation in geometric algebra, and the library expects you to build it from the primitives it does expose rather than calling it directly.

Header and source files sit flat in the repository root

The repository layout is unusual and worth understanding before you integrate it. There is no src/ directory, no build system file and no package manifest. Instead the type definitions and their implementations are flat at the root as paired TS-prefixed files, for example TSVector3D.h next to TSVector3D.cpp, TSQuaternion.h next to TSQuaternion.cpp, and the same pattern for the rigid, conformal and algebra modules such as TSRigid3D and TSConformal3D. A shared TSPlatform.h and a TSSimd.h sit alongside them, and TSAlgebra.h with TSAlgebra.cpp holds the algebra layer. The practical consequence is that integrating the library means adding these files to your build, which is a different step from consuming a package, and it means you can read the implementation of any operation directly in the tree.

MIT licensed, header-readable, and quietly maintained

The licence is MIT, so the code can be used in commercial and closed-source products with only an attribution notice, and the fact that the implementation files are shipped rather than hidden behind a binary makes it straightforward to adapt a type to your own conventions. Maintenance is the more ambiguous part. The repository publishes no GitHub releases, so there is no tagged version to pin against and no changelog to read for breaking changes. The last push was on 2026-07-27, and the library sits under an active author who publishes the related talk material, but the absence of versioned releases means a consumer has to track the default branch rather than a release. The project is a single author effort with an academic home page rather than a company backing it, and both facts belong in the risk assessment.

Editorial conclusion

Terathon Math Library is a good fit for graphics and geometry work in C++ where transforms, planes, lines and spheres need to compose through one algebraic type rather than through several special-case representations, and where source you can read and add to your build matters. It is a poor fit for a project that only needs vectors and 4x4 matrices, since the geometric algebra types add a learning cost that pays off only when you use them. Verify first that the operations you need exist in the class list the README enumerates, because the geometric product and antiproduct are deliberately not provided, and confirm your build can take the flat TS-prefixed files before you commit to it.

Frequently asked questions

Official sources

1. EricLengyel/Terathon-Math-Library on GitHub
2. Issues
3. License: MIT
4. Project website
5. README