Welcome to Euclid

• GitHub repo
• Latest documentation

Introduction

Euclid is a header only library for geometry processing and shape analysis.

It contains some utilities and algorithms which extend and cooperate with other popular libraries around there, like Eigen(libigl), CGAL, to name a few.

The purpose of Euclid is not to replace any of the above packages, but to glue things together as well as to provide more algorithms which do not appear in those libraries.

Dependencies

Some simple third-party libraries has already been shipped with Euclid. However, you'll need the following libraries when you use headers in Euclid that work with them, including

• Boost.
• CGAL for tons of data structures and algorithms.
• Eigen for matrix manipulation as well as solving linear systems.
• Spectra for solving large scale eigen value problems.
• Libigl yet another simple but powerful geometry processing library in C++.
• Embree for fast cpu ray tracing.
• cereal for serialization.
• Doxygen for generating documentations.
• BLAS, LAPACK, and OpenMP for better performance.

Different packages in Euclid may require a different set of dependencies, and some packages may not require any of the above libraries. Also, Euclid uses features in the C++17 standard, so you'll need a C++17 enabled compiler.

Installation

Since it's a header only library, the simpliest way to use Euclid is to include the needed headers. Although be sure to configure other dependencies properly, as some of them are not header only.

If you are using CMake, there are two ways to go:

First you could use the find script shipped with Euclid and configure other dependencies manually like below. This is preferable if you only need parts of the headers and do not wish to configure all the dependencies.

find_package(Euclid)
target_include_directories(your-target Euclid_INCLUDE_DIR)
// other dependencies, e.g. Eigen

Otherwise, you could configure Euclid using CMake first. It will output an EuclidConfig.cmake file in the build tree for you to use. You can set the variable Euclid_DIR to the path containing this file and then in your own CMakeLists.txt you could do

find_package(Euclid)
target_link_libraries(your-target Euclid::Euclid)

and all the dependencies and compile options will be handled transitively by CMake.

Getting Started

Here's an example which reads a mesh file, converts it to a CGAL::Surface_mesh data structure, computes its discrete gaussian curvatures and ouput the values into mesh colors.

#include <vector>
#include <CGAL/Simple_cartesian.h>
#include <CGAL/Surface_mesh.h>
#include <Euclid/IO/OffIO.h>
#include <Euclid/IO/PlyIO.h>
#include <Euclid/MeshUtil/CGALMesh.h>
#include <Euclid/Geometry/TriMeshGeometry.h>
#include <Euclid/Util/Color.h>

using Kernel = CGAL::Simple_cartesian<float>;
using Point_3 = Kernel::Point_3;
using Mesh = CGAL::Surface_mesh<Point_3>;

int main()
{
    // Read triangle mesh into buffers
    std::vector<float> positions;
    std::vector<unsigned> indices;
    Euclid::read_off<3>("Euclid_root/data/bumpy.off", positions, nullptr, &indices, nullptr);

    // Generate a CGAL::Surface_mesh
    Mesh mesh;
    Euclid::make_mesh<3>(mesh, positions, indices);

    // Compute gaussian curvatures
    auto curvatures = Euclid::gaussian_curvatures(mesh);

    // Turn curvatures into colors and output to a file
    std::vector<unsigned char> colors;
    Euclid::colormap(igl::COLOR_MAP_TYPE_JET, curvatures, colors, true);
    Euclid::write_ply<3>(
        "outdir/bumpy.ply", positions, nullptr, nullptr, &indices, &colors);
}

Examples

See the examples folder for more tutorials. However, many modules are not covered yet. For a more complete example, you could check the test cases to see the usage of most functions and classes. More information on how to run the tests could be found here.

License

MIT for code not related to any third-party libraries.

Otherwise it should follow whatever license the third-party libraries require.