Skip to content

Argos

This project is called ARGOS, it's an application developed in C++ 17 with CMake (minimum version 3.25.1) that can create a point cloud from a 3D mesh (OBJ or PLY file) but also generate a 3D mesh from a point cloud.

Moreover, this application embedded a benchmark analysis that created an XLSX file with many data to compare the algorithms.

Table of Contents

  1. Archive
  2. Build
  3. Execution
  4. Benchmark
  5. Documentation

Archive

ARGOS/
│
├── benchmark/                          # Folder for algorithm analysis code
│   ├── metrics/                        # All metrics that can be used for the analysis
│   │   └── implementations/            # Concrete metric implementations
│   ├── exporter/                       # Exports results in XLSX format
│   ├── reporter/                       # Retrieves benchmark results data from Google Benchmark
│   ├── BenchmarksContainer.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 Benchmark 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 represent a mesh (face, vertex, ...)
│   ├── serializer/                     # Mesh import/export tool (convert OBJ/PLY 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
└── README.md                           # General documentation of the ARGOS application

Build

All the following commands must be run from the project root.

Standard build

Tests disabled, benchmarks enabled (default configuration).

cmake -S . -B out
cmake --build out

Build with tests

cmake -S . -B out -DBUILD_TESTS=ON
cmake --build out

Build with benchmarks

cmake -S . -B out -DBUILD_BENCHMARKS=ON
cmake --build out

Combine options

cmake -S . -B out -DBUILD_TESTS=ON -DBUILD_BENCHMARKS=ON
cmake --build out

Execution

The generated executables are located in the build folder out/, depending on the generator and configuration (Debug / Release).

Usage: 

./argos run [{-i|--input} <file_path>] <algorithm> [{-p|--points} <number_of_points>] [{-o|--output} <file_path>] [heatmap]

Example: 

./argos run -i "C:\...\obj.obj" uniform_area -p 5000 -o "C:\...\output_obj.obj"

Note: It is possible to specify a sampling algorithm and then a reconstruction algorithm, and also to pass the heatmap subcommand to obtain a heat map included in the output .obj file.

Options :

Option Condition Description
-i, --input Optional Source file path.
If not chosen, listen for stdin input in OBJ text format until interrupt signal
-o, --output Optional Destination file path.
If not chosen, write the result in OBJ text format to standard stdout output

Available "Sampling" algorithms

Name Type Description Parameters
naive Mesh -> PointCloud Runs the naive algorithm that converts an object into a point cloud None
centroid Mesh -> PointCloud Places a point at the center of each face None
uniform_area Mesh -> PointCloud Distributes a total number of points proportionally to the areas
  • -p or --points : Total number of points - Required
uniform_face_1 Mesh -> PointCloud Generates an identical (distributed) number of points across each face of the mesh
  • -p or --points : Total number of points - Required
uniform_face_2 Mesh -> PointCloud Generates the same number of points on each face of the mesh
  • -p or --points : Number of points per face - Required
density Mesh -> PointCloud Places x points per unit (very small unit)
  • -d or --density : Number of points per unit (It is recommended to choose a number between 0.1 and 5.0) - Required

Available "Reconstruct" algorithms

Name Type Description Parameters
scale_space PointCloud -> Mesh Launches the CGAL algorithm - Scale Space Surface Reconstruction
  • -i or --iterations : Number of smoothing iterations. The larger the number is, the smoother the constructed mesh will be (fewer faces). - Not required - Default = 4
advancing PointCloud -> Mesh Launches the CGAL algorithm - Advancing Front Reconstruction None
poisson PointCloud -> Mesh Launches the CGAL algorithm - Poisson Surface Reconstruction
  • -d or --detail : Controls the level of detail. If the number is high, small structures will be erased. Conversely, if the number is low, the algorithm will pay attention to small details; however, the algorithm will be more sensitive to noise. - Not required - Default = 6
  • -s or --smoothing : Controls the mesh smoothing factor. The higher this value is, the smoother the mesh will be; the lower the value is and the more detailed the mesh will be. - Not required - Default = 24

It is also possible to obtain all the information about the different algorithms in JSON format by using the info_algos subcommand : 

./argos info_algos [-s|-r]

Tests execution (CTest)

Tests are managed via CTest, provided with CMake.

The following commands must be executed from the build directory out/.

Simple tests execution: ctest.

Execution with detailed output: ctest -V.

Run a specific test

ctest -R test_example

Benchmark

To run a benchmark, simply specify the path to a folder containing all the .obj (or .ply) files to be processed, as well as the sampler algorithm (point cloud transformation), one or more reconstruction algorithms (mesh generation), and metrics.

Here is the command to execute :

./argos_benchmark [{-i|--input} <obj_folder_path>] <sampler_algorithm> [sampler_algorithm_parameters] <reconstruct_algorithm> [reconstruct_algorithm_parameters] [metrics]

Example: 

./argos_benchmark -i "/path/to/obj/dir/" density -d 5 advancing scale_space -i 2 10 2 bbox

Command Arguments

Argument Condition Description
-i, --input Required Path to the folder containing the .obj files to process
Sampler Algorithms Required Choose a sampling algorithm from those listed in the Sampler section. It must be written with its parameters in the same way as in the main application.
Reconstruction Algorithms Required and Optional Choose at least one reconstruction algorithm from those listed in the Reconstruct section.

For the algorithm parameters, it is possible to specify an interval [min] [max] [step]. For example: poisson --detail 2 10 2 --smoothing 1 5 will execute the Poisson algorithm with these values:
  • Detail: 2, 4, 6, 8, 10
  • Smoothing: 1, 2, 3, 4, 5
Metrics Optional Choose which metrics to add to the benchmark (See Metrics). Time and memory peak metrics are automatically called by default.

Available Metrics

All metrics are measured during the reconstruction algorithm (reconstruction phase), not the entire execution.

Name Command Description
CPU - Gives the total CPU usage execution time. This metric is called by default.
MemoryPeak - Indicates the maximum amount of RAM (in MB) used during the reconstruction phase. This metric is called by default.
GlobalMemoryPeak global_peak Indicates the maximum amount of RAM (in MB) used by the application. This metric therefore keeps the highest value: if the current algorithm consumed less than the previous one, the displayed peak will be that of the previous one.
Bounding Box bbox Compares the bounding boxes of two meshes (size, volume, diagonal, position) to evaluate their global differences and spatial offset.
Centroid to face ctf Measures the average, minimum, and maximum distances between the centroids of triangles of a mesh and the nearest faces of the other mesh (in both directions), to estimate the geometric similarity between two meshes.
Edge-Face Intersections intersections Counts the number of times that edges of the reconstructed mesh intersect the faces of the original mesh.
Heatmap heatmap Adds texture coordinates to the different reconstructed objects, allows to determine the distances between the reconstructed mesh and the original mesh (green = close to the original mesh - red = very far from the original mesh).
Holes holes Provides the number of holes detected in both of the original and reconstructed meshes, as well as the average circumference of the holes in both meshes.
Vertices vertices Provides the number of vertices of the original and reconstructed meshes.
Faces faces Provides the number of faces of the original and reconstructed meshes.

Benchmark Output

The .obj files (point cloud and reconstructed versions) are written to a timestamped subfolder, by default output/<YYYY-MM-DD_HH-MM-SS>/ next to the input folder. This folder is created automatically during execution.

A rapport.xlsx file is also produced in the same folder, listing the results of all metrics for each iteration. The full details of the metric columns and the output layout are described in docs/Benchmarks.md.

Documentation

Additional documentation is available under the docs/ directory: