Explanation of code resumption

This file is to help any developer who would continue the project. It's necessary to also read the README.md file (and maybe also other documentations) to understand clearly how works the application (especially for the algorithms).

ARGOS needs three dependencies : - CLI11 : To create a command line interface easily and have better communication between user and application - CGAL : Used to get algorithms for 3D mesh reconstruction (all the reconstruction algorithms in ARGOS are from CGAL) - GoogleBenchmark : To generate a benchmark easily (for console view and XLSX file)

Structure of the project

The archive of the code looks like this :

argos-core
│
├── benchmark/                      # Folder for algorithm analysis code
│   ├── metrics/                    # All metrics that can used for the analysis
│   ├── exporter/                   # Exports results in XLSX format
│   ├── reporter/                   # Retrieves benchmark results data from Google Benchmark
│   ├── BenchamrksContainer.h/.cpp  # Contains all the logic for creating and running benchmarks
│   ├── ConfigParser.cpp            # Allows reading a JSON configuration file (instead of the CLI)
│   ├── CMakeLists.txt              # CMake configuration of Benchamrk executable
│   └── main.cpp                    # Entry point for Benchmark executable
│
├── docs/                           # Documentation of the whole project
│
├── include/                        # Headers of ARGOS main executable
├── src/                            # Source code of ARGOS main executable
│   ├── algos/                      # Folder that contains all algorithms
│   │    ├── mesh_to_pointcloud/    # Sampling algorithms (To create a point cloud)
│   │    └── pointcloud_to_mesh/    # Reconstruction algorithms (To generate a 3D mesh)
│   ├── mesh/                       # All classes that represents a mesh (face, vertex...)
│   ├── serializer/                 # Mesh import/export tool (convert OBJ to Mesh and vice versa)
│   ├── structure/                  # Utilities, accelerating structures...
│   └── main.cpp                    # Entry point for ARGOS main executable
│
├── tests/                          # Unit and functional testing
├── CMakeLists.txt                  # CMake configuration of ARGOS main executable
├── Explanation_CodeResumption.md   # Document about how works the code of the project
└── README.md                       # General documentation of the ARGOS application

Globally, the structure is separated into two : on the one hand we have ìnclude and src folders which correspond to the main executable, and on the other hand, the benchmark folder contains all files used to compare algorithms with metrics. More details of the two sections below :

ARGOS - Main executable

The main ARGOS executable is the core of this application. With a command that starts by ./argos we can execute a pipeline to create a point cloud and/or generate a 3D mesh.

In the ìnclude folder we can find all the. header files of the class files present in the src folder

Algorithms

In algos we have all the algorithms separated by mesh_to_pointcloud for the algorithms that take a 3D mesh and create a point cloud, and pointcloud_to_mesh for the algorithms that take a point cloud and generate a 3D mesh.

The files in others are here mainly for the heatmap option.

The application uses abstract interfaces for sampling (ISurfaceSampler.h) and for reconstruction (ISurfaceReconstructor.h) to simply add a new algorithm by implementing these interfaces.

The files CLI_MTP_config.cpp (for sampling) and CLI_PTM_config.cpp (for reconstruction) are here to group all available algorithms in one function which is called by the CLI (Command Line Interface) in the main class.

To get more details about each algorithm, see the code documentation or README.md.

Mesh Structure

The mesh folder contains all the needed classes that represent the basic structure of a mesh, with faces, vertices, and the class for the object Mesh.

Another file TopologicMesh is present, it is used for the benchmark part but in the future, the classic mesh can be replaced by the topological version.

File Serializer

The classes to import and export files are in the serializer folder, today there are two serializers : one for OBJ files (ObjSerializer) and one for PLY files (PlySerializer).

In the future, other types of file importers/exporters can be added.

Other Structures

In structure folder we retrieve the rest of the other structures, like accelerating structure (KDTree, AABBTree...) or many other classes like Edge (to represent the edge of a mesh), VertexToFace (to get distances for heatmap)...

All of these classes are used for a "secondary job" like the heatmap (optional) or to count the intersections in benchmark, they have no impact on the basic pipeline.

Benchmark - Algorithm analysis

The Benchmark executable is the part dedicated to analysis and algorithm comparison. This executable returns an XLSX file with all the data of the benchmark and the object files (see other documentations for more details).

Structure

Inside the benchmark folder we retrieve all the necessary files used for benchmarking, like the file BenchmarksContainer that contains all the functions for the execution, but also a ConfigParser.cpp file, used to read a JSON file and replace the CLI command.

Other folders are in this benchmark part. They are detailed just below.

Metrics

One of the folders in the benchmark part is dedicated to the metrics, it contains all the metrics that are available, and a file for CLI configuration (to add metrics in CLI options).

Reporter and Exporter

The Reporter collects all the data from the tests done by Google Benchmark and sends this to the Exporter that formats all the data in an XLSX file. (see Benchmark documentation for more details)

Procedures

The two most important procedures are explained here. For the other procedures, there are easily : For exemple, to add another file serializer. You just need to copy/paste an existing file serializer and modify the content.

How to add an algorithm ?

Adding a new algorithm

It depends on what type of algorithm :

If the new algorithm is for sampling (creation of a point cloud from a 3D mesh), you will need to extend the class ÌSurfaceSampler.h and override the function sample(const Mesh& mesh) that take a mesh and create a point cloud with the new algorithm. You must also override the function name() and return a string with the name of this new algorithm (this function is particularly used in benchmark part).
If the new algorithm is for reconstruction (generation of a 3D mesh from a point cloud), you will need to extend the class ÌSurfaceReconstructor.h and override the function reconstruct(const PointCloud& pc) that take a point cloud and create a 3d mesh with the new algorithm. You must also override the function name() and return a string with the name of this new algorithm (this function is particularly used in benchmark part).

Adding this new algorithm in CLI

So that CLI knows this new algorithm, it's necessary to add them in the CLI config file. If your algorithm is for sampling, you must add it in the file CLI_MTP_config.cpp, and if your algorithm is for reconstruction, you must add it in the file CLI_PTM_config.cpp.

To add the option in the CLI, you just need to add this algorithm in the function addAlgosMeshToPointcloud(...) or addAlgosPointcloudToMes(...) by adding a new subcommand in the group like this :

// You must precise in the function 'group.subcommand()' the name and a description of the algorithm
auto *name_algorithm = group.add_subcommand("name", "description");

// Then you implement a callback that add in the result list a pointer of the algorithm class
name_algorithm->callback([&result]() {
     result = std::make_shared<MyAlgorithm>();
});

Note : For reconstruction algorithm, the CLI can accept many values for each parameters (only used in benchmark part) like a minimum, a maximum and a step. So you can use the function nbMaxIterations() and valueAt() to easily insert correct values at the i-th iteration. (See README.md to learn more about the iterations)

How to add a metric ?

To add a metric for the benchmark part you will need to extend the class Metric.h. Then you must call the Metric constructor with the name of this new metric and override the function compute(const Mesh& m1, const Mesh& m2, benchmark::State& state) that takes a Mesh (if you just need a pointcloud do test to ensure that the mesh contains only points...) and return a mesh (idem here), the value of the metric is print like this state.counters... (see code documentation).

After this you need to add this new metric in the CLI by adding in the file CLI_Metrics_config.cpp a subcommand like this :

// You must precise in the function 'group.subcommand()' the name and a description of the metric
auto* name_of_metric = group.add_subcommand("name", "description");

// Then you implement a callback that add in the metrics list a pointer of the metric class
name_of_metric->callback([&metrics]() {
  metrics.push_back(std::make_shared<MyNewMetric>());
});

Blender addon

A Blender addon was created to simplify the process of the pipeline (for ARGOS main executable).

With this addon, the user can create a point cloud, generate a 3D mesh and even see a heatmap (only if the complete pipeline is choosed).