docs: add comments everywhere

Author: oktomus

CMakeLists.txt

@@ -18,6 +18,8 @@ set (CMAKE_CXX_EXTENSIONS OFF)
 # Automatically managed dependencies
 #
 # glm and imgui are git submodules of this project.
+#
+# nanoflann and GLAD are directly sored in the repository (src/thirdparties)
 
 set(WEB_ROOT "${CMAKE_SOURCE_DIR}/distant/web")
 set(GLM_ROOT "${CMAKE_SOURCE_DIR}/distant/glm")

src/core/closest_point_query.cpp

@@ -38,16 +38,17 @@ bool ClosestPointQuery::get_closest_point(
 {
     assert(max_distance > 0.0f);
 
+    // nanoflann (the KDTree library) use squared distance. We do the same.
     const float max_distance2 = max_distance * max_distance;
 
-    // Define how many points we take from the tree to find the closest point in the mesh.
+    // Define how many points we take from the tree to find the closest point on the mesh.
     // A number that is too low will generate incorrect results when the mesh density is high.
-    // The points we process are the closest points to the query point.
+    // The points we process are the nearest points in the cloud to the query point.
     const std::size_t point_to_process_max_count = 2000;
     std::vector<std::size_t> ret_index(point_to_process_max_count);
     std::vector<float> out_dist_sqr(point_to_process_max_count);
 
-    // Use the KDTree to find the closest points.
+    // Use the KDTree to find the nearest points to the `query_point`.
     const std::size_t num_results =
         m_tree_index.knnSearch(
             glm::value_ptr(query_point),
@@ -59,24 +60,24 @@ bool ClosestPointQuery::get_closest_point(
     float closest_distance2 = 0.0f;
 
     // Find the closest point on the mesh using all points near to `query_point`.
-    // To do so, we use the triangle on which each point is laying and compute the closest
-    // point to the quer_point that is on the triangle.
-    // For all these "triangles points", we keep the L2 closest one to the query point.
+    // To do so, we use the triangle on which each point is and compute the closest
+    // point to query_point that is on the triangle.
+    // For all these "triangles points", we keep the closest one to the query point.
     // FIXME: We analyse the same triangles multiple times.
     for (std::size_t i = 0; i < num_results; ++i)
     {
-        // Ask the triangle to the point cloud.
+        // Ask to the point cloud which triangle is this point on.
         glm::vec3 v1, v2, v3;
         m_mesh_point_cloud.get_triangle(ret_index[i], v1, v2, v3);
 
-        // Compute the point on the triangle.
+        // Compute the closest point to `query_point` that is on the triangle.
         glm::vec3 p = closest_point_in_triangle(
             query_point,
             v1,
             v2,
             v3);
 
-        // Keep the best.
+        // From all triangles, keep the closest one.
         const float distance2_to_triangle = distance2(p, query_point);
 
         if (distance2_to_triangle < max_distance2

src/core/closest_point_query.h

@@ -11,13 +11,12 @@ namespace core
 {
 
 /**
- * @brief Fast closest point to mesh.
+ * @brief Fast closest point to mesh algortihm implementation.
  *
  * After creating the query object, just call
  * `get_closest_point`.
- *
- * When creating the query object, a tree will
- * be generated to speed up look up time.
+ * 
+ * This implementation require a point cloud and not a mesh.
  */
 class ClosestPointQuery
 {

src/core/mesh_point_cloud.h

@@ -13,8 +13,9 @@ namespace core
 
 /**
  * @brief Create a point cloud using a mesh.
- * TODO: Allow to generate points on the mesh to
- * increase precision.
+ * FIXME: To get a better representation of the mesh surface,
+ * we should generate points on the mesh. At the moment, we
+ * only use the mesh vertices.
  */
 class MeshPointCloud
 {

src/core/rasterized_mesh.h

@@ -10,7 +10,8 @@ namespace core
 {
 
 /**
- * @brief Mesh wrapper that can be rendered with OpenGL.
+ * @brief Mesh wrapper that do everything necessary to
+ * render the mesh with OpenGL.
  */
 class RasterizedMesh
 {

src/core/scene.cpp

@@ -27,10 +27,10 @@ std::size_t Scene::get_mesh_count() const
     return m_meshes.size();
 }
 
-const Mesh& Scene::get_mesh() const
+const Mesh& Scene::get_mesh(const std::size_t index) const
 {
-    assert(m_meshes.size() > 0);
-    return m_meshes[0];
+    assert(index < m_meshes.size());
+    return m_meshes[index];
 }
 
 void Scene::render() const

src/core/scene.h

@@ -18,8 +18,7 @@ class Scene
 
     std::size_t get_mesh_count() const;
 
-    // FIXME: Multiple mesh usage is not supported.
-    const Mesh& get_mesh() const;
+    const Mesh& get_mesh(const std::size_t index) const;
 
     void render() const;
 

src/gui/file_system.h

@@ -15,6 +15,9 @@ namespace gui
 // File system utilities.
 //
 
+/**
+ * @brief Open a window using zenity to let the user choose a file.
+ */
 inline std::string linux_open_file(
     const std::string               title,
     const std::vector<std::string>  file_filters = {});

src/gui/main.cpp

@@ -8,8 +8,13 @@ int main()
     gui::MainWindow& window = gui::MainWindow::get_instance();
 
     window.init(800, 600);
+
+    // Load an asset by default.
     window.load_scene("resources/models/teapot.obj");
+
     window.run();
+
+    // Close the window.
     window.release();
 
     return 0;

src/gui/mainwindow.cpp

@@ -25,6 +25,11 @@
 #include <iostream>
 #include <string>
 
+// FIXME: This is not the cleanest code from this project.
+// Here are some refactoring ideas:
+// - Split IMGUI and OpenGL drawing in 2 separate classes.
+// - Store algorithm related data in a separate class.
+
 namespace gui
 {
 
@@ -173,7 +178,7 @@ void MainWindow::load_scene(const std::string& path)
     }
 
     // Build a point cloud of the mesh.
-    m_mesh_point_cloud.reset(new core::MeshPointCloud(m_scene->get_mesh()));
+    m_mesh_point_cloud.reset(new core::MeshPointCloud(m_scene->get_mesh(0)));
 
     // Prepare closest point queries.
     m_closest_point_query.reset(new core::ClosestPointQuery(*m_mesh_point_cloud));