/Epsilon-Intersection

Math utility library for games and simulations including lots of intersection tests for different geometry

Primary LanguageC++OtherNOASSERTION

Epsilon Intersection Library - ε

ε is a super flexible and simple to use C++ library designed for games. It is computing intersections of various three dimensional bodies and containes different utilities you could need for culling, ray casting or similar functions.

It provides powerful template based matrix/vector and quaternion classes which come with a ton of useful functions. Due to its lean design you can easily integrate the parts you need into your project, just by adding the source!

How to use the library?

There are 2 different ways to include ε into your project:

  1. Add all files to your current project and compile as usual.
  2. Compile a library and use that

All interfaces are declared in include/ei/<xyz>.hpp files. You never need to include or look into files from the include/ei/details or src directory.

The hierarchy of header-files is as follows.

config -- elementarytypes -- vector -|- 2dtypes -- 2dintersection
                                     |- 3dtypes -- 3dintersection

Each header includes all its depenencies. So, dependent on what functionality you need you need to include only one of them:

  • config.hpp: contains some defines to change basis properies (e.g. utf8 support for things like ε::π).
  • elementarytypes.hpp: uint, int8, ... (coming soon: fixed point), lerp, min/max with variable argument count
  • vector.hpp: Vec3, IVec2, Mat3x3, ... inclusive all expected functions (dot, sum, min/max, ..., many more)
  • 2dtypes.hpp: shapes for 2D inclusive area, center, ... functions. Currently 2D support is relative minimalistic (feature request are welcome, but I did not use these functions until now)
  • 2dintersection.hpp: adds the distance() and intersection() methods to 2dtypes
  • 3dtypes.hpp: shapes for 3D inclusive surface, volume, center, ... functions. Also adds numerous "conversion" methods e.g. bounding box for a set of points.
  • 3dintersection.hpp: adds the distance() and intersection() methods to 3dtypes

The configuration system of epsilon works as follows:

All files expect to include the config.hpp (or depend on it). The repository only contains a defaultconfig.hpp. This should be copied and renamed accordingly. Thus, you can use epsilon as submodule in other repositories. Since the new (renamed) config file is not part of this repository you can change it as you want. You only need to make sure the file is found from your compiler if parsing the epsilon files.

Range of Functions

  • Elementary types: sized ints uint64... (well meanwhile you can get them from C++ std library, but the int16_t still has this ugly _t)
  • Template row and column vectors of different sizes and elementary types (don't be confused: the library defines vectors as matrices with one dimension set to 1)
  • Matrices
    • transformations: rotation, translation, projection
    • determinant and other matrix utilities
    • LU decomposition, 2D/3D spectral decomposition
  • Lots of 2D and 3D shapes
    • area(), volume(), surface() and center()
    • conversion/construction of bounding shapes for other shapes
    • distance() functions
    • intersection functions
    • transform methods

Available Intersection Methods

The following table gives an overview over the implemented intersection methods. Also, it shows the median performance in milliseconds per 1 million elements. Even though, 5000 iterations, with 2500 test each, are performed the median (and every other measure I tried) has a noticeable variance from more than 15% between application runs due to CPU boosts. Cells with a * are implemented but not measured.

Benchmarkconfigs: VS2015, /O2, Win32 on an i7-4950S

Box Cap. Cone Disc DOP Ell. Fru. Line OBox OEl. Pla. Poi. Ray Sph. The. Tri.
Box 10.1 ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Capsule 35.0 ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Cone ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Disc ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
DOP ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Ellipsoid ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Frustum * ---- ---- ---- ---- ---- ---- ---- ---- ----
Line ---- ---- ---- ---- ---- ---- ---- ---- ----
OBox ---- ---- ---- ---- ---- ---- ----
OEllipsoid ---- ---- ---- ---- ---- ----
Plane 6.27 9.73 ---- ---- ---- ---- ----
Point 8.19 15.2 10.0 ---- 8.06 6.35 * ---- 19.1 12.9 ---- ---- ---- ---- ---- ----
Ray 16.4 17.3 * ---- 36.0 ---- ---- ---- ---- ----
Sphere 10.7 15.8 5.71 3.33 5.71 6.14 ---- ----
Thetrahedron 24.9 ----
Triangle 17.3 53.5 33.4 ---- 22.4 38.2

Benchmarkconfigs: VS2015, /O2, x64 on an i7-4950S

Box Cap. Cone Disc DOP Ell. Fru. Line OBox OEl. Pla. Poi. Ray Sph. The. Tri.
Box 9.60 ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Capsule 44.0 ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Cone ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Disc ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
DOP ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Ellipsoid ---- ---- ---- ---- ---- ---- ---- ---- ---- ----
Frustum * ---- ---- ---- ---- ---- ---- ---- ---- ----
Line ---- ---- ---- ---- ---- ---- ---- ---- ----
OBox ---- ---- ---- ---- ---- ---- ----
OEllipsoid ---- ---- ---- ---- ---- ----
Plane 4.99 12.4 ---- ---- ---- ---- ----
Point 6.91 13.3 7.81 ---- 6.27 5.89 * ---- 26.6 13.1 ---- ---- ---- ---- ---- ----
Ray 14.5 16.3 * ---- 45.3 ---- ---- ---- ---- ----
Sphere 8.32 13.8 1.79 1.92 4.22 3.71 ---- ----
Thetrahedron 18.9 ----
Triangle 15.9 42.8 41.7 ---- 18.6 35.1