Skip to content


Repository files navigation

Terathon Math Library

This is a C++ math library containing classes for vectors, matrices, quaternions, and elements of projective geometric algebra. The specific classes are the following:

  • Vector2D – A 2D vector (x, y) that extends to four dimensions as (x, y, 0, 0).
  • Vector3D – A 3D vector (x, y, z) that extends to four dimensions as (x, y, z, 0).
  • Vector4D – A 4D vector (x, y, z, w).
  • Point2D – A 2D point (x, y) that extends to four dimensions as (x, y, 0, 1).
  • Point3D – A 3D point (x, y, z) that extends to four dimensions as (x, y, z, 1).
  • Bivector3D – A 3D bivector x e23 + y e31 + z e12.
  • Matrix2D – A 2×2 matrix.
  • Matrix3D – A 3×3 matrix.
  • Matrix4D – A 4×4 matrix.
  • Transform2D – A 3×3 matrix with fourth row always (0, 0, 1).
  • Transform3D – A 4×4 matrix with fourth row always (0, 0, 0, 1).
  • Quaternion – A conventional quaternion xi + yj + zk + w.
  • DualNum – A dual number s + .

2D rigid geometric algebra

  • FlatPoint2D – A 2D flat point x e1 + y e2 + z e3.
  • Line2D – A 2D line x e23 + y e31 + z e12.
  • Motor2D – A 2D motion operator Qx e1 + Qy e2 + Qz e3 + Qw 𝟙.
  • Flector2D - A 2D reflection operator Fx e23 + Fy e31 + Fz e12 + Fw 1.

3D rigid geometric algebra

  • FlatPoint3D – A 3D flat point x e1 + y e2 + z e3 + w e4.
  • Line3D – A 3D line lvx e41 + lvy e42 + lvz e43 + lmx e23 + lmy e31 + lmz e12.
  • Plane3D – A 3D plane x e234 + y e314 + z e124 + w e321.
  • Motor3D – A 3D motion operator Qvx e41 + Qvy e42 + Qvz e43 + Qvw 𝟙 + Qmx e23 + Qmy e31 + Qmz e12 + Qmw 1.
  • Flector3D - A 3D reflection operator Fpx e1 + Fpy e2 + Fpz e3 + Fpw e4 + Fgx e423 + Fgy e431 + Fgz e412 + Fgw e321.

2D conformal geometric algebra

  • RoundPoint2D – A 2D round point x e1 + y e2 + z e3 + w e4.
  • Dipole2D – A 2D dipole dgx e23 + dgy e31 + dgz e12 + dpx e41 + dpy e42 + dpz e43.
  • Circle2D – A 2D circle w e321 + x e423 + y e431 + z e412.

3D conformal geometric algebra

  • RoundPoint3D – A 3D round point x e1 + y e2 + z e3 + w e4 + u e5.
  • Dipole3D – A 3D dipole dvx e41 + dvy e42 + dvz e43 + dmx e23 + dmy e31 + dmz e12 + dpx e15 + dpy e25 + dpz e35 + dpw e45.
  • Circle3D – A 3D circle cgx e423 + cgy e431 + cgz e412 + cgw e321 + cvx e415 + cvy e425 + cvz e435 + cmx e235 + cmy e315 + cmz e125.
  • Sphere3D – A 3D sphere u e1234 + x e4235 + y e4315 + z e4125 + w e3215.

Component Swizzling

Vector components can be swizzled using shading-language syntax. As an example, the following expressions are all valid for a Vector3D object v:

  • v.x – The x component of v.
  • v.xy – A 2D vector having the x and y components of v.
  • v.yzx – A 3D vector having the components of v in the order (y, z, x).

Support for repeated components in a swizzle can be enabled by defining TERATHON_SWIZZLE_REPEAT. This is disabled by default because the large number of additional swizzling possibilities increases compile times substantially. Swizzles with repeated components are always const so that it's not possible to assign to them.

Rows, columns, and submatrices can be extracted from matrix objects using a similar syntax. As an example, the following expressions are all valid for a Matrix3D object m:

  • m.m12 – The (1,2) entry of m.
  • m.row0 – The first row of m.
  • m.col1 – The second column of m.
  • m.matrix2D – The upper-left 2×2 submatrix of m.
  • m.transpose – The transpose of m.

All of the above are generally free operations, with no copying, when their results are consumed by an expression. For more information, see Eric Lengyel's 2018 GDC talk Linear Algebra Upgraded.

Geometric Algebra

The ^ operator is overloaded for cases in which the wedge or antiwedge product can be applied between vectors, bivectors, flat points, lines, planes, round points, dipoles, circles, and spheres. (Note that ^ has lower precedence than just about everything else, so parentheses will be necessary.)

The library does not provide operators that directly calculate the geometric product and antiproduct because they would tend to generate inefficient code and produce intermediate results having unnecessary types when something like the sandwich product Qp ⟇ ~Q appears in an expression. Instead, there are Transform() functions that take some object p for the first parameter and the motor Q with which to transform it for the second parameter.

See Eric Lengyel's Projective Geometric Algebra website for more information about operations among these types.

API Documentation

There is API documentation embedded in the header files. The formatted equivalent can be found in the C4 Engine documentation.


Separate proprietary licenses are available from Terathon Software. Please send an email with details about your particular use case if you are interested.