{"id":15108932,"url":"https://github.com/liangliangnan/easy3d","last_synced_at":"2025-05-14T12:12:15.057Z","repository":{"id":38325398,"uuid":"159520915","full_name":"LiangliangNan/Easy3D","owner":"LiangliangNan","description":"A lightweight, easy-to-use, and efficient library for processing and rendering 3D data (C++ \u0026 Python)","archived":false,"fork":false,"pushed_at":"2025-04-04T16:14:10.000Z","size":273456,"stargazers_count":1487,"open_issues_count":3,"forks_count":263,"subscribers_count":46,"default_branch":"main","last_synced_at":"2025-04-10T08:05:04.859Z","etag":null,"topics":["3d-modeling","computer-graphics","data-structure","geometry-processing","graph","mesh","opengl","point-cloud","polyhedral-mesh","reconstruction","rendering","shader","surface-mesh","viewer","visualization"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LiangliangNan.png","metadata":{"files":{"readme":"ReadMe.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-28T15:11:38.000Z","updated_at":"2025-04-08T11:11:56.000Z","dependencies_parsed_at":"2023-09-26T16:09:23.888Z","dependency_job_id":"1ba99b21-b17c-4b40-875c-6feae79fe3b2","html_url":"https://github.com/LiangliangNan/Easy3D","commit_stats":{"total_commits":3233,"total_committers":8,"mean_commits":404.125,"dds":"0.0049489638107020895","last_synced_commit":"4f9602fbe825319c59f69d341f33c16f6bab482e"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiangliangNan%2FEasy3D","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiangliangNan%2FEasy3D/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiangliangNan%2FEasy3D/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LiangliangNan%2FEasy3D/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LiangliangNan","download_url":"https://codeload.github.com/LiangliangNan/Easy3D/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248381917,"owners_count":21094530,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-modeling","computer-graphics","data-structure","geometry-processing","graph","mesh","opengl","point-cloud","polyhedral-mesh","reconstruction","rendering","shader","surface-mesh","viewer","visualization"],"created_at":"2024-09-25T22:42:59.840Z","updated_at":"2025-04-11T19:47:50.311Z","avatar_url":"https://github.com/LiangliangNan.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"right\"\u003e\n    \u003cb\u003e \u003cimg src=\"https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-green\" title=\"Supported Platforms\"/\u003e \u003c/b\u003e \u003cbr\u003e\n    \u003cb\u003e \u003cimg src=\"https://img.shields.io/badge/license-GPL-blue\" title=\"license-GPL\"/\u003e \u003c/b\u003e \u003cbr\u003e\n\u003c/p\u003e\n\n![3D model generated and rendered by Easy3D](resources/images/logo.jpg)\n\n#### For 3D modeling, geometry processing, and rendering, designed with emphasis on simplicity and efficiency. \nEasy3D is implemented in C++ and comes with **Python bindings**. It is intended for research and educational purposes, but it is also a good starting point for developing sophisticated 3D applications. \nCompared to existing geometry processing libraries (such as [PMP](http://www.pmp-library.org/) and [libigl](https://github.com/libigl/libigl/)) that focus on the algorithm aspect, Easy3D also provides a wider range of functionalities for user interactions and rendering.\n\n\u003cp align=\"center\"\u003e \n     \u003cimg src=\"./resources/images/overview.jpg\" width=\"600\"\u003e \n\u003c/p\u003e\n\n### Key features\n* Efficient data structures for representing and managing 3D models such as point clouds, polygonal surfaces \n  (e.g., triangle meshes), polyhedral volumes (e.g., tetrahedral meshes), and graphs. \n  Easy to add/access arbitrary types of per-element properties. Non-manifoldness is automatically resolved when \n  loading models from files ...\n  \n* A set of widely used algorithms, e.g., point cloud normal estimation/re-orientation, Poisson surface reconstruction, \n  RANSAC, mesh simplification, subdivision, smoothing, parameterization, remeshing, and more (the implementation of\n  several surface mesh processing algorithms were taken from [PMP](http://www.pmp-library.org/)).\n   \n* A bunch of rendering techniques, e.g., point/line imposters, ambient occlusion (SSAO), hard shadow (shadow maps), \n  soft shadow (PCSS), eye-dome lighting (for rendering point clouds without normal information), transparency (average \n  color blending, dual depth peeling), and more.\n   \n* High-level encapsulation of OpenGL and GLSL for convenient and efficient rendering (based on modern and faster\n  programmable-shader-style rendering, i.e., no fixed function calls). Client code does not need to touch the low-level \n  APIs of OpenGL. \n  \n* Step-by-step tutorials demonstrating various uses of the API, to get acquainted with the data structures, rendering techniques, and algorithms \n  for 3D modeling and geometry processing. \n  \n* Very easy to use as a callable library (usually only a few lines of code).\n  \n* A viewer that can be used directly to visualize 3D scenes in various formats, which can also be easily extended. \n  For window/GUI creation, Easy3D currently supports [GLFW](https://www.glfw.org/) (e.g., [the default viewer](https://github.com/LiangliangNan/Easy3D/blob/main/easy3d/viewer)), \n  [Qt](https://www.qt.io/) (see [the Qt viewer](https://github.com/LiangliangNan/Easy3D/tree/main/tutorials/Tutorial_204_Viewer_Qt)), \n  and [wxWidgets](https://www.wxwidgets.org/) (see [the wxWidgets viewer](https://github.com/LiangliangNan/Easy3D/tree/main/tutorials/Tutorial_203_Viewer_wxWidgets)).\n\n* A handy tool \u003cb\u003eMapple\u003c/b\u003e created out of the Easy3D library for rendering and processing 3D data.\n\n* Python bindings for Easy3D, which allow you to use Easy3D in Python scripts. \n\n|              Scalar field                |              Polyhedral mesh              |              Keyframe animation            |\n|------------------------------------------|-------------------------------------------|--------------------------------------------|\n| ![](resources/images/mapple-scalar.jpg)  | ![](resources/images/mapple-polymesh.gif) | ![](resources/images/mapple-animation.gif) |\n\n### A glance\n\nAny type of 3D drawables (e.g., points, lines, triangles, and thus point clouds, mesh surfaces, scalar fields, \nand vector fields) can be rendered by writing a few lines of code with Easy3D. For example, the following code renders a \npoint cloud as a set of spheres\n\n```c++\n// assume your point cloud has been loaded to the viewer\nPointsDrawable* drawable = cloud-\u003erenderer()-\u003eget_points_drawable(\"vertices\");\ndrawable-\u003eset_impostor_type(PointsDrawable::SPHERE); // draw points as spheres.\ndrawable-\u003eset_point_size(3.0f);    // set point size\n```\nor as a set of surfels (i.e., 3D discs)\n\n```c++ \ndrawable-\u003eset_impostor_type(PointsDrawable::SURFEL);\n``` \n\nBy abstracting geometric elements as one of the above drawables, more general visualization (e.g., vector fields, \nscalar fields) can be done very conveniently.\n\n### Easy3D repository layout\nThe repository contains a `CMakeLists.txt` file (in the root directory of the repository) that serves as an anchor for \nconfiguring and building programs, as well as a set of subfolders:\n* [`3rd_party`](https://github.com/LiangliangNan/Easy3D/tree/main/3rd_party) - source code of third-party libraries\n* [`applications`](https://github.com/LiangliangNan/Easy3D/tree/main/applications) - applications built on top of Easy3D\n* [`cmake`](https://github.com/LiangliangNan/Easy3D/tree/main/cmake) - CMake-related configuration files\n* [`docs`](https://github.com/LiangliangNan/Easy3D/tree/main/docs) - documentation configuration file (Doxygen)\n* [`easy3d`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d) - source code of Easy3D, implementing the Easy3D modules:\n  * [`util`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/util) - utilities, e.g., logging, file system, progress, timer.\n  * [`core`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/core) - basic types and data structures, e.g., point cloud, surface mesh, graph, and polyhedron mesh.\n  * [`fileio`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/fileio) - functionalities for reading/writing data from/into files.\n  * [`kdtree`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/kdtree) - a collection of kd-trees.\n  * [`algo`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/algo) - algorithms for geometry processing.\n  * [`algo_ext`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/algo_ext) - several extended surface mesh processing algorithms (based on CGAL).\n  * [`video`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/video) - a class that can encode an image sequence into a video.\n  * [`renderer`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/renderer) - functionalities and algorithms for rendering and visualization.\n  * [`gui`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/gui) - tools for user interactions, e.g., picking points, faces, or models.\n  * [`viewer`](https://github.com/LiangliangNan/Easy3D/tree/main/easy3d/viewer) - a simple viewer and a composite viewer.\n  * [`python`](https://github.com/LiangliangNan/Easy3D/tree/main/python) - Python bindings for Easy3D, and examples.\n* [`resources`](https://github.com/LiangliangNan/Easy3D/tree/main/resources) - test data, images, shaders, textures, etc.\n* [`tests`](https://github.com/LiangliangNan/Easy3D/tree/main/tests) - a collection of test cases\n* [`tutorials`](https://github.com/LiangliangNan/Easy3D/tree/main/tutorials) - a collection of examples (with detailed explanations in code)\n\n### Build Easy3D\nLike most software, Easy3D depends on some third-party libraries. Easy3D has made this easier for users by including\nthe source code of most third-party libraries (for the core functionalities and the basic viewer), and it leaves very \nfew optional (for a few additional features that are typically not needed by most users). \n\nThe **optional** third-party libraries are:\n- **[CGAL](https://www.cgal.org/) (optional)**: Easy3D has implemented a few algorithms for advanced surface mesh \n  processing, such as surface reorientation, detecting/resolving duplicate vertices/faces and self-intersection, \n  and clipping/splitting/slicing surface meshes. These features are disabled by default (because most users don't \n  need them). To enable these features, you can switch on the CMake option `Easy3D_ENABLE_CGAL` and make sure \n  CGAL ([v5.1 or later](https://github.com/CGAL/cgal/releases)) is installed and visible to CMake. In case you have\n  multiple versions of CGAL on your platform, simply provide the path of a suitable one to the CMake variable `CGAL_DIR`.\n\n- **[Qt](https://www.qt.io/) (optional)**: Easy3D supports Qt \u003e= v5.6 ([v5.14.2](https://download.qt.io/archive/qt/5.14/5.14.2/),\n  [v5.12.12](https://download.qt.io/archive/qt/5.12/5.12.12/), and [v6.7.3](https://www.qt.io/download-qt-installer-oss)\n  have been tested) for UI creation, which can help develop sophisticated applications for 3D data processing and visualization. \n  The Qt support is disabled by default (because most users don't need it). You can switch on the CMake option `Easy3D_ENABLE_QT` \n  to include the examples and applications that depend on Qt (e.g., \n  [`Tutorial_204_Viewer_Qt`](https://github.com/LiangliangNan/Easy3D/tree/main/tutorials/Tutorial_204_Viewer_Qt) and \n  [`Mapple`](https://github.com/LiangliangNan/Easy3D/tree/main/applications/Mapple)).\n  \nTo build Easy3D, you need [CMake](https://cmake.org/download/) (`\u003e= 3.12`) and, of course, a compiler that supports `\u003e= C++11`.\n\nEasy3D has been tested on macOS (Xcode \u003e= 8), Windows (MSVC \u003e=2015 `x64`), and Linux (GCC \u003e= 4.8, Clang \u003e= 3.3). Machines \nnowadays typically provide higher [support](https://en.cppreference.com/w/cpp/compiler_support), so you should be able \nto build Easy3D on almost all platforms.\n\nThere are many options to build Easy3D. Choose one of the following (not an exhaustive list):\n\n- Option 1 (purely on the command line): Use CMake to generate Makefiles and then `make` (on Linux/macOS) or `nmake`(on Windows with Microsoft \n  Visual Studio). \n  - On Linux or macOS, you can simply\n    ```\n        $ cd path-to-root-dir-of-Easy3D\n        $ mkdir Release\n        $ cd Release\n        $ cmake -DCMAKE_BUILD_TYPE=Release ..\n        $ make\n    ```\n  - On Windows with Microsoft Visual Studio, use the `x64 Native Tools Command Prompt for VS XXXX` (**don't** use the x86 one), then\n    ```\n        $ cd path-to-root-dir-of-Easy3D\n        $ mkdir Release\n        $ cd Release\n        $ cmake -G \"NMake Makefiles\" -DCMAKE_BUILD_TYPE=Release ..\n        $ nmake\n    ```\n  \n- Option 2: Use any IDE that can directly handle CMakeLists files to open the `CMakeLists.txt` in the **root** directory of \n  Easy3D. Then you should have obtained a usable project and just build it. I recommend using \n[CLion](https://www.jetbrains.com/clion/) or [QtCreator](https://www.qt.io/product). For Windows users: your IDE must be set for `x64`.\n  \n- Option 3: Use CMake-Gui to generate project files for your IDE. Then load the project to your IDE and build it. For Windows users: your IDE must be set for `x64`.\n\nDo not have any experience with C/C++ programming? \nHave a look at \u003ca href=\"https://github.com/LiangliangNan/Easy3D/blob/main/HowToBuild.md\"\u003eHow to build Easy3D step by \nstep\u003c/a\u003e.\n\n#### Build and use Python bindings\n- Please check [here](./python/ReadMe.md).\n\n### Test Easy3D\nA test suite is provided in the [`tests`](./tests) subfolder (and [`test`](./python/test) for Python users), which \ncontains a collection of automated test cases (for data structures, IO, algorithms, visualization, etc.) and some \nsemi-automated test cases (for GUI-related functionalities that require interactive user input). All cases are \nintegrated into the single target `tests`.\n\nTo build and run the test suite, download the entire source, use the `CMakeLists.txt` in the root directory of the \nrepository, switch on the CMake option `Easy3D_BUILD_TESTS` (which is disabled by default), and run CMake. After CMake, \nyou can build ALL or only the `tests` target. Finally, run the `tests` executable (i.e., `YOUR_BUILD_DIRECTORY/bin/tests`) for the test.\n\n### Use Easy3D in your project\nThis is quite easy, like many other open-source libraries :-) \nAfter 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. \nThe `CMakeLists.txt` looks like:\n``` cmake\ncmake_minimum_required(VERSION 3.12)\nproject(MyProject)\nset(CMAKE_CXX_STANDARD 11)                       # specify C++ standard\nfind_package(Easy3D COMPONENTS viewer REQUIRED)  # request Easy3D (recommended to request only needed components)\nadd_executable(Test main.cpp)                    # create an executable target\ntarget_link_libraries(Test easy3d::viewer)       # link to necessary Easy3D modules (add more if needed, e.g., algo)\n```\nand the `main.cpp` with minimum code:\n\n``` c++\n#include \u003ceasy3d/viewer/viewer.h\u003e\n#include \u003ceasy3d/util/initializer.h\u003e\n\nint main(int argc, char** argv) {\n    easy3d::initialize();\n    easy3d::Viewer viewer(\"Test\");\n    return viewer.run();\n}\n```\n\nUsing the Python bindings is also straightforward, for example:\n``` python\nimport easy3d\n\neasy3d.initialize()\nviewer = easy3d.Viewer(\"Test\")\nviewer.add_model(easy3d.directory() + \"/data/bunny.ply\")\nviewer.run()\n```\n\n### Documentation\nThe documentation for Easy3D is available [here](https://3d.bk.tudelft.nl/liangliang/software/easy3d_doc/html/index.html).\n\nThe Easy3D Documentation is an ongoing effort with more and more details being added. You can build the latest Easy3D \ndocumentation from the source code.\nEasy3D uses [Doxygen](https://www.doxygen.nl/index.html) (`\u003e= 1.8.3`) to generate documentation from source code. \nTo build it from the source code, [install Doxygen](https://www.doxygen.nl/manual/install.html) first. \nThen, switch on the CMake option `` in the main `CMakeList.txt`. Finally, build the `doc` \ntarget to generate the documentation. \n\nFor Python users, please check these [tutorials](./python/tutorials).\n\n### Questions, new features, bugs, or contributing to Easy3D\nSee the [Contribution Guide](https://github.com/LiangliangNan/Easy3D/blob/main/CONTRIBUTING.md) for more information.\n\n### License\nEasy3D is free software; you can redistribute it and/or modify it under the terms of the \nGNU General Public License as published by the Free Software Foundation; either version 3\nof the License or (at your option) any later version. The full text of the license can be\nfound in the accompanying 'License' file.\n\n### Acknowledgments\nThe implementation of Easy3D greatly benefited from and was inspired by existing great open-source libraries, such as\n[PMP](http://www.pmp-library.org/), [libQGLViewer](http://libqglviewer.com/), [Surface mesh](https://opensource.cit-ec.de/projects/surface_mesh),\nand [Graphite](http://graphite.gforge.inria.fr/). In particular, the implementation of several surface mesh \nalgorithms was taken (with modifications) from PMP, i.e., simplification, subdivision, smoothing, \nparameterization, remeshing, hole filling, geodesic distances, fairing, curvatures, and triangulation. \nWe would like to thank the original authors of these projects for their permissive license terms. \nWe also thank the users and contributors for reporting/fixing bugs, testing, and providing valuable feedback and suggestions.\n\n### Citation\nIf you use Easy3D in scientific work, I kindly ask you to cite it:\n\n```bibtex\n@article{easy3d2021,\n  title = {Easy3{D}: a lightweight, easy-to-use, and efficient {C}++ library for processing and rendering 3{D} data},\n  author = {Liangliang Nan},\n  journal = {Journal of Open Source Software}，\n  year = {2021},\n  volume = {6},\n  number = {64},\n  pages = {3255},\n  doi = {10.21105/joss.03255},\n  url = {https://doi.org/10.21105/joss.03255}\n}\n```\n---------\n\nShould you have any questions, comments, or suggestions, please contact me at \u003ci\u003eliangliang.nan@gmail.com\u003c/i\u003e\n\n[\u003cb\u003e\u003ci\u003eLiangliang Nan\u003c/i\u003e\u003c/b\u003e](https://3d.bk.tudelft.nl/liangliang/)\n\nDec. 8, 2018\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliangliangnan%2Feasy3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliangliangnan%2Feasy3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliangliangnan%2Feasy3d/lists"}