search

LiangliangNan / Easy3D

A lightweight, easy-to-use, and efficient C++ library for processing and rendering 3D data
GNU General Public License v3.0
1.35k stars 243 forks source link
3d-modeling computer-graphics data-structure geometry-processing graph mesh opengl point-cloud polyhedral-mesh reconstruction rendering shader surface-mesh viewer visualization

readme



3D model generated and rendered by Easy3D

Easy3D is an open-source library for 3D modeling, geometry processing, and rendering. It is implemented in C++ and designed with an emphasis on simplicity and efficiency. Easy3D is intended for research and educational purposes, but it is also a good starting point for developing sophisticated 3D applications.

Compared to existing geometry processing libraries (such as PMP and libigl) that focus on the algorithm aspect, Easy3D also provides a wider range of functionalities for user interactions and rendering.

Key features

Scalar field Polyhedral mesh Keyframe animation

A glance

Any type of 3D drawables (e.g., points, lines, triangles, and thus point clouds, mesh surfaces, scalar fields, and vector fields) can be rendered by writing a few lines of code with Easy3D. For example, the following code renders a point cloud as a set of spheres

// assume your point cloud has been loaded to the viewer
PointsDrawable* drawable = cloud->renderer()->get_points_drawable("vertices");
drawable->set_impostor_type(PointsDrawable::SPHERE); // draw points as spheres.
drawable->set_point_size(3.0f);    // set point size

or as a set of surfels (i.e., 3D discs)

drawable->set_impostor_type(PointsDrawable::SURFEL);

By abstracting geometric elements as one of the above drawables, more general visualization (e.g., vector fields, scalar fields) can be done very conveniently.

Easy3D repository layout

The repository contains a CMakeLists.txt file (in the root directory of the repository) that serves as an anchor for configuring and building programs, as well as a set of subfolders:

Build Easy3D

Like most software, Easy3D depends on some third-party libraries. Easy3D has made this easier for users by including the source code of most third-party libraries (for the core functionalities and the basic viewer), and it leaves very few optional (for a few additional features that are typically not needed by most users).

The optional third-party libraries are:

To build Easy3D, you need CMake (>= 3.12) and, of course, a compiler that supports >= C++11.

Easy3D has been tested on macOS (Xcode >= 8), Windows (MSVC >=2015 x64), and Linux (GCC >= 4.8, Clang >= 3.3). Machines nowadays typically provide higher support, so you should be able to build Easy3D on almost all platforms.

There are many options to build Easy3D. Choose one of the following (not an exhaustive list):

Don't have any experience with C/C++ programming? Have a look at How to build Easy3D step by step.

Test Easy3D

A test suite is provided in the tests subfolder, which contains a collection of automated test cases (for data structures, IO, algorithms, visualization, etc.) and some semi-automated test cases (for GUI-related functionalities that require interactive user input). All cases are integrated into the single target tests.

To build and run the test suite, download the entire source, use the CMakeLists.txt in the root directory of the repository, switch on the CMake option Easy3D_BUILD_TESTS (which is disabled by default), and run CMake. After CMake, you can build ALL or only the tests target. Finally, run the tests executable (i.e., YOUR_BUILD_DIRECTORY/bin/tests) for the test.

Use Easy3D in your project

This is quite easy, like many other open-source libraries :-) After you have built Easy3D, you only need to point Easy3D_DIR to your build (or the installation) directory of Easy3D when doing cmake. Then the requested Easy3D libraries, including directories and relevant compile definitions of Easy3D, are visible and accessible to your project. Below is an example of using the default Easy3D viewer. The CMakeLists.txt looks like:

cmake_minimum_required(VERSION 3.12)
project(MyProject)
set(CMAKE_CXX_STANDARD 11)                       # specify C++ standard
find_package(Easy3D COMPONENTS viewer REQUIRED)  # request Easy3D (recommended to request only needed components)
add_executable(Test main.cpp)                    # create an executable target
target_link_libraries(Test easy3d::viewer)       # link to necessary Easy3D modules (add more if needed, e.g., algo)

and the main.cpp with minimum code:

#include <easy3d/viewer/viewer.h>
#include <easy3d/util/initializer.h>

int main(int argc, char** argv) {
    easy3d::initialize();
    easy3d::Viewer viewer("Test");
    return viewer.run();
}

Documentation

The documentation for Easy3D is available here.

The Easy3D Documentation is an ongoing effort with more and more details being added. You can build the latest Easy3D documentation from the source code. Easy3D uses Doxygen (>= 1.8.3) to generate documentation from source code. To build it from the source code, install Doxygen first. Then, switch on the CMake option ` in the mainCMakeList.txt. Finally, build thedoc` target to generate the documentation.

Questions, new features, bugs, or contributing to Easy3D

See the Contribution Guide for more information.

License

Easy3D is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License or (at your option) any later version. The full text of the license can be found in the accompanying 'License' file.

Acknowledgments

The implementation of Easy3D greatly benefited from and was inspired by existing great open-source libraries, such as PMP, libQGLViewer, Surface mesh, and Graphite. In particular, the implementation of several surface mesh algorithms was taken (with modifications) from PMP, i.e., simplification, subdivision, smoothing, parameterization, remeshing, hole filling, geodesic distances, fairing, curvatures, and triangulation. We would like to thank the original authors of these projects for their permissive license terms. We also thank the users and contributors for reporting/fixing bugs, testing, and providing valuable feedback and suggestions.

Citation

If you use Easy3D in scientific work, I kindly ask you to cite it:

@article{easy3d2021,
  title = {Easy3{D}: a lightweight, easy-to-use, and efficient {C}++ library for processing and rendering 3{D} data},
  author = {Liangliang Nan},
  journal = {Journal of Open Source Software}，
  year = {2021},
  volume = {6},
  number = {64},
  pages = {3255},
  doi = {10.21105/joss.03255},
  url = {https://doi.org/10.21105/joss.03255}
}

Should you have any questions, comments, or suggestions, please contact me at i>liangliang.nan@gmail.com</i

Liangliang Nan

Dec. 8, 2018