API Overview

Working with Klein is designed to be as simple as it is efficient. To "grok" the API, it suffices to understand the API in terms of the primary operations supported through the primary geometric entities.

The entities provided are Euclidean objects (points, lines, planes), objects that arise in Projective space (directions, ideal lines), and geometric actions (rotors, translators, motors, and planes).

Class Description
plane A plane is the manifestation of a reflection of \(\mathbf{E}^3\) (consider the set of fixed points of a reflection).
line A line is the manifestation of a rotation of \(\mathbf{E}^3\) (consider the set of fixed points of a rotation).
branch A branch is a line through the origin
ideal_line An ideal line is a line at infinity
point A point is the manifestation of a roto-reflection of \(\mathbf{E}^3\) (which has a single fixed point)
direction A direction is modeled as a point at infinity (homogeneous weight \(0\))
rotor A rotor is the product of two intersecting planes (generating a rotation)
translator A translator is the product of two parallel planes (generating a translation)
motor A motor is a screw combining a rotation and translation along a screw axis
dual A dual is the sum of a scalar and pseudoscalar quantity. Dual numbers show up in a number of contexts, including the factorization of a motor axis, and as the result of several meet and join operations.

Note

The call operator on a plane performs a reflection of the passed entity through the plane. The call operator on a rotor performs a rotation of the entity. The translator translates, and the motor performs a combination of a rotation and a translation.

The multivector operations such as the geometric product, exterior product, regressive product, etc. are supported for all the listed entities above via the following operator table:

Operator Description
+ Addition
- Subtraction
* s Uniform scaling by a float or int s
/ s Uniform inverse scaling by a float or int s
* Geometric Product
^ Exterior Product
& Regressive Product
| Symmetric Inner Product
! Poincaré Dual

Note

Addition and subtraction is only supported between arguments of the same type. For example, two planes can be added together, but not a plane and a rotor.

Tip

For the geometric actions (implemented via the conjugation operator \(xP\widetilde{x}\)), the call operator should be used on the action itself as this will invoke a more optimized routine than invoking x * P * ~x manually. For example, given a rotor r and a point p, applying the rotor to p as r(p) will be faster with equivalent results to r * p * ~r.

Similarly, while the regressive product between two entities a and b can be computed as !(!a ^ !b), the explicit a & b should be preferred for efficiency.

There are a few additional freestanding functions to perform various tasks.

Function Description
project Projects the first argument onto the second argument and returns the result.
log Takes the logarithm of the argument and returns the result.
exp Computes the exponential of the argument and returns the result.
sqrt Computes the square root of a rotor or motor and returns the result.

Note

Throughout the API, you may see functions and methods marked with KLN_VEC_CALL. This macro expands to __vectorcall to ensure that register passing is used on MSVC.