Skip to content
This repository has been archived by the owner on Aug 2, 2024. It is now read-only.
/ klein Public archive

P(R*_{3, 0, 1}) specialized SIMD Geometric Algebra Library

License

Notifications You must be signed in to change notification settings

jeremyong/klein

Repository files navigation

edit: Project has been temporarily archived as I don't have time to maintain it at the moment. Stay tuned for an updated version of the project in the future.

License: MIT DOI

Build Status Build Status Coverity Status Codacy Badge

👉👉 Project Site 👈👈

Description

Do you need to do any of the following? Quickly? Really quickly even?

  • Projecting points onto lines, lines to planes, points to planes?
  • Measuring distances and angles between points, lines, and planes?
  • Rotate or translate points, lines, and planes?
  • Perform smooth rigid body transforms? Interpolate them smoothly?
  • Construct lines from points? Planes from points? Planes from a line and a point?
  • Intersect planes to form lines? Intersect a planes and lines to form points?

If so, then Klein is the library for you!

Klein is an implementation of P(R*_{3, 0, 1}), aka 3D Projective Geometric Algebra. It is designed for applications that demand high-throughput (animation libraries, kinematic solvers, etc). In contrast to other GA libraries, Klein does not attempt to generalize the metric or dimensionality of the space. In exchange for this loss of generality, Klein implements the algebraic operations using the full weight of SSE (Streaming SIMD Extensions) for maximum throughput.

Requirements

  • Machine with a processor that supports SSE3 or later (Steam hardware survey reports 100% market penetration)
  • C++11/14/17 compliant compiler (tested with GCC 9.2.1, Clang 9.0.1, and Visual Studio 2019)
  • Optional SSE4.1 support

Usage

You have two options to use Klein in your codebase. First, you can simply copy the contents of the public folder somewhere in your include path. Alternatively, you can include this entire project in your source tree, and using cmake, add_subdirectory(Klein) and link the klein::klein interface target.

In your code, there is a single header to include via #include <klein/klein.hpp>, at which point you can create planes, points, lines, ideal lines, bivectors, motors, directions, and use their operations. Please refer to the project site for the most up-to-date documentation.

Motivation

PGA fully streamlines traditionally used quaternions, and dual-quaternions in a single algebra. Normally, the onus is on the user to perform appropriate casts and ensure signs and memory layout are accounted for. Here, all types are unified within the geometric algebra, and operations such as applying quaternion or dual-quaternions (rotor/motor) to planes, points, and lines make sense. There is a surprising amount of uniformity in the algebra, which enables efficient implementation, a simple API, and reduced code size.

Performance Considerations

It is known that a "better" way to vectorize computation in general is to arrange the data in an SoA layout to avoid unnecessary cross-lane arithmetic or unnecessary shuffling. PGA is unique in that a given PGA multivector has a natural decomposition into 4 blocks of 4 floating-point quantities. For the even sub-algebra (isomorphic to the space of dual-quaternions) also known as the motor algebra, the geometric product can be densely packed and implemented efficiently using SSE.

References

Klein is deeply indebted to several members of the GA community and their work. Beyond the works cited here, the author stands of the shoulders of giants (Felix Klein, Sophus Lie, Arthur Cayley, William Rowan Hamilton, Julius Plücker, and William Kingdon Clifford, among others).

[1] Gunn, Charles G. (2019). Course notes Geometric Algebra for Computer Graphics, SIGGRAPH 2019. arXiv link

[2] Steven De Keninck and Charles Gunn. (2019). SIGGRAPH 2019 Geometric Algebra Course. youtube link

[3] Leo Dorst, Daniel Fontijne, Stephen Mann. (2007) Geometric Algebra for Computer Science. Burlington, MA: Morgan Kaufmann Publishers Inc.