Easy3D:基于C++与Python的3D建模与几何处理库项目

针对三维建模、几何处理和渲染而设计，强调简易性和效率。

Easy3D使用C++实现，并附带Python绑定。它适用于研究和教育目的，同时也是开发复杂三维应用程序的一个良好起点。 与现有的几何处理库（如PMP和libigl）专注于算法方面不同，Easy3D还提供了更广泛的功能，用于用户交互和渲染。

主要特点

• 高效的数据结构，用于表示和管理三维模型，如点云、多边形表面（例如三角形网格）、多面体体积（例如四面体网格）和图。 易于添加/访问任意类型的元素属性。在从文件加载模型时自动解决非流形问题...

• 一系列广泛使用的算法，例如点云法线估计/重定向、泊松曲面重建、RANSAC、网格简化、细分、平滑、参数化、重新网格化等（其中几个表面网格处理算法的实现来源于PMP）。

• 一系列渲染技术，例如点/线替代品、环境遮挡（SSAO）、硬阴影（阴影映射）、软阴影（PCSS）、眼窝照明（用于无法线信息点云的渲染）、透明度（平均颜色混合、双深度剥除）等。

• 对OpenGL和GLSL的高级封装，以实现方便且高效的渲染（基于现代且更快速的编程着色器风格渲染，即无需固定函数调用）。客户端代码无需接触OpenGL的低级API。

• 分步骤的教程，展示了API的各种用途，以熟悉数据结构、渲染技术和三维建模与几何处理算法。

• 作为一个可调用的库，非常易于使用（通常只需几行代码）。

• 一个可以直接用于可视化各种格式三维场景的查看器，也可以轻松扩展。 对于窗口/GUI的创建，Easy3D当前支持GLFW（例如默认查看器）、 Qt（见Qt查看器）和 wxWidgets（见wxWidgets查看器）。

• 从Easy3D库中创建的一个便捷工具Mapple，用于渲染和处理三维数据。

• Easy3D的Python绑定，允许您在Python脚本中使用Easy3D。

标量场	多面体网格	关键帧动画

一窥究竟

通过编写几行Easy3D代码，可以渲染任何类型的三维绘图元素（例如点、线、三角形，以及因此的点云、网格表面、标量场和向量场）。 例如，以下代码将点云渲染为一组球体

// 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

或作为一组表面元素（即，3D圆盘）

drawable->set_impostor_type(PointsDrawable::SURFEL);

将几何元素抽象为上述可绘制对象之一，可以非常方便地进行更通用的可视化（例如，向量场、标量场）。

Easy3D 仓库布局

仓库包含一个 CMakeLists.txt 文件（位于仓库的根目录），用于配置和构建程序，以及一组子文件夹：

• 3rd_party - 第三方库的源代码
• applications - 基于Easy3D构建的应用程序
• cmake - 与 CMake 相关的配置文件
• docs - 文档配置文件（Doxygen）
• easy3d - Easy3D 的源代码，实现了 Easy3D 模块：
  • util - 工具类，例如日志记录、文件系统、进度、计时器。
  • core - 基本类型和数据结构，例如点云、表面网格、图和多边形网格。
  • fileio - 读取/写入文件数据的功能。
  • kdtree - kd树的集合。
  • algo - 几何处理的算法。
  • algo_ext - 几种基于 CGAL 的扩展表面网格处理算法。
  • video - 一个可以将图像序列编码为视频的类。
  • renderer - 渲染和可视化的功能和算法。
  • gui - 用户交互工具，例如选取点、面或模型。
  • viewer - 一个简单的查看器和复合查看器。
  • python - Easy3D 的 Python 绑定和示例。
• resources - 测试数据、图像、着色器、纹理等。
• tests - 测试用例的集合
• tutorials - 示例的集合（代码中包含详细说明）

构建 Easy3D

与大多数软件一样，Easy3D 依赖于一些第三方库。Easy3D 通过包含大多数第三方库的源代码（为核心功能和基本查看器），极大地简化了用户的使用，并为可选功能留下了很少的选择（通常大多数用户不需要的额外功能）。

可选的第三方库有：

• CGAL（可选）：Easy3D 实现了几种用于高级表面网格处理的算法，如表面重定向、检测/解决重复顶点/面和自相交，以及剪裁/分割/切片表面网格。这些功能默认是禁用的（因为大多数用户不需要它们）。要启用这些功能，您可以开启 CMake 选项 Easy3D_ENABLE_CGAL 并确保 CGAL（v5.1 或更高版本）已安装并且对 CMake 可见。如果您在平台上安装了多个版本的 CGAL，只需简单地将合适版本的路径提供给 CMake 变量 CGAL_DIR。

• Qt（可选）：Easy3D 支持 Qt >= v5.6（已测试 v5.14.2、v5.12.12 和 v6.7.3），用于创建 UI，这有助于开发用于 3D 数据处理和可视化的复杂应用程序。默认情况下禁用 Qt 支持（因为大多数用户不需要它）。您可以开启 CMake 选项 Easy3D_ENABLE_QT 来包含依赖于 Qt 的示例和应用程序（例如，Tutorial_204_Viewer_Qt 和 Mapple）。

要构建 Easy3D，您需要 CMake（>= 3.12）以及支持 >= C++11 的编译器。

Easy3D 已在 macOS（Xcode >= 8）、Windows（MSVC >=2015 x64）和 Linux（GCC >= 4.8, Clang >= 3.3）上进行了测试。现在的计算机通常提供更高的支持，因此您应该能够在几乎所有平台上构建 Easy3D。

构建 Easy3D 有许多选项。选择以下之一（非详尽列表）：

• 选项 1（纯命令行）：使用 CMake 生成 Makefile，然后使用 make（在 Linux/macOS 上）或 nmake（在带有 Microsoft Visual Studio 的 Windows 上）。

  • 在 Linux 或 macOS 上，您可以简单地

        $ cd path-to-root-dir-of-Easy3D
        $ mkdir Release
        $ cd Release
        $ cmake -DCMAKE_BUILD_TYPE=Release ..
        $ make
    

  • 在带有 Microsoft Visual Studio 的 Windows 上，使用 x64 Native Tools Command Prompt for VS XXXX（不要使用 x86），然后

        $ cd path-to-root-dir-of-Easy3D
        $ mkdir Release
        $ cd Release
        $ cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ..
        $ nmake
    

• 选项 2：使用任何可以直接处理 CMakeLists 文件的 IDE 来打开 Easy3D 根目录中的 CMakeLists.txt。然后您应该已经获得了一个可用的项目，直接构建即可。我建议使用 CLion 或 QtCreator。对于 Windows 用户：您的 IDE 必须设置为 x64。

• 选项 3：使用 CMake-Gui 为您的 IDE 生成项目文件。然后将项目加载到 IDE 中并构建。对于 Windows 用户：您的 IDE 必须设置为 x64。

没有任何 C/C++ 编程经验？ 请查看 如何逐步构建 Easy3D。

构建和使用 Python 绑定

• 请查看 此处。

测试 Easy3D

在 tests 子文件夹（对于 Python 用户为 test）提供了一个测试套件，其中包含了一系列自动化的测试用例（用于数据结构、IO、算法、可视化等）和一些半自动化的测试用例（需要用户交互的 GUI 相关功能）。所有用例都集成到了单一目标 tests 中。

要构建和运行测试套件，请下载整个源代码，使用仓库根目录中的 CMakeLists.txt，开启 CMake 选项 Easy3D_BUILD_TESTS（默认禁用），然后运行 CMake。CMake 运行后，您可以构建 ALL 目标或仅构建 tests 目标。最后，运行 tests 可执行文件（即 YOUR_BUILD_DIRECTORY/bin/tests）以进行测试。

在您的项目中使用Easy3D

这非常简单，就像许多其他开源库一样 😃 在您构建完Easy3D之后，只需在执行CMake操作时将Easy3D_DIR指向您的Easy3D构建（或安装）目录。这样，所需的Easy3D库、包括目录和相关的编译定义就会对您的项目可见并可供访问。以下是使用默认Easy3D查看器的示例。 CMakeLists.txt 文件看起来是这样的：

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)

并且带有最少代码的 main.cpp：

#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();
}

使用 Python 绑定同样直观简单，例如：

import easy3d

easy3d.initialize()
viewer = easy3d.Viewer("Test")
viewer.add_model(easy3d.resource_directory() + "/data/bunny.ply") # <-- Use your actual file path
viewer.run()

文档

• Easy3D 文档
  • Easy3D Python 文档
  • Easy3D Python 教程

文档是一个持续更新的工作，越来越多的细节正在被添加进去。您可以从源代码构建最新的 Easy3D 文档。 Easy3D 使用 Doxygen (>= 1.8.3) 从源代码生成文档。要从源代码构建，请先 安装 Doxygen。然后，开启 CMake 选项 Easy3D_BUILD_DOCUMENTATION 并运行 CMake。最后，构建 Documentation 目标以生成文档。

对于 Python 用户，您可能也会对 教程 感兴趣。

问题、新功能、错误或对 Easy3D 的贡献

请查阅 贡献指南 以获取更多信息。

许可

Easy3D 是免费软件；您可以在 Free Software Foundation 发布的 GNU 通用公共许可证的条款下重新分发和/或修改它；无论是许可证的第 3 版，还是（根据您的选择）任何后续版本。许可证的完整文本可以在随附的 'License' 文件中找到。

鸣谢

Easy3D 的实现极大地得益于并受到了现有的优秀开源库的启发，例如 PMP、libQGLViewer、Surface mesh 和 Graphite。特别是，我们采用了（并进行了修改）来自 PMP 的多个表面网格算法，包括简化、细分、平滑、参数化、重构网格、孔洞填充、测地距离、优化、曲率和三角剖分。我们感谢这些项目的原始作者提供了宽松的许可条款。同时，我们也感谢用户和贡献者报告/修复错误、测试以及提供宝贵的反馈和建议。

引用

如果您在科学工作中使用 Easy3D，我恳请您引用它：

@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}
}

若有任何疑问、意见或建议，请通过 liangliang.nan@gmail.com 与我联系。

南亮亮

2018年12月8日