README.md
# Computational Design of Custom-Fit PAP Masks
![teaser](./resources/teaser.png "teaser")
This repository is the official implementation of the paper [Computational Design of Custom-Fit PAP Masks](https://sutd-cgl.github.io/supp/Publication/projects/2024-SMI-MaskDesign/index.html).
The code customizes a generic mask cushion based on an input human face model that is aligned with the generic mask. The output is the customized cushion surface and mask interface.
## Repository structure
The repository contains the following items:
- **Files**
- **CMakeLists.txt**: This is the main configuration file for CMake. It defines this project's build process, specifying which files to compile, the required dependencies, and other build instructions.
- **README.md**: This file contains an introduction to this project, instructions on how to build and run it.
- **parameters.txt**: This file contains the main parameters involved in this project.
- **LICENSE**: This file contains the license under which the project's code is distributed.
- **Folders**
- **bin/Release**: This directory contains the compiled binaries of the project built in release mode. Release mode is optimized for performance and is usually stripped of debugging information.
- **cmake**: This directory contains additional CMake modules or configuration files used by the `CMakeLists.txt` to manage the build process.
- **lib**: This directory holds compiled libraries that the project depends on.
- **script** This directory contains scripts for configure and running the program.
- **src**: This directory contains the source code of the project. It includes the `.cpp`, `.h`, `.c`, `.hpp`, and other source files written in the project in C++.
- **Data**
- **data**: This directory is used to store the input data files required by this project.
- **output**: This directory contains the output data of the code.
- **resources** This directory contains images used in the README file.
## Build (Windows only):
### Dependencies
- [OpenMesh](https://www.graphics.rwth-aachen.de/software/openmesh/), [Eigen](https://eigen.tuxfamily.org/index.php?title=Main_Page), [ALGLIB](https://www.alglib.net/), [CGAL](https://www.cgal.org/), [TriangleMeshDistance](https://github.com/InteractiveComputerGraphics/TriangleMeshDistance), [CppNumericalSolvers](https://github.com/PatWie/CppNumericalSolvers), [Nelder-Mead](https://people.math.sc.edu/Burkardt/cpp_src/asa047/asa047.html) are already included in the project, and can be built through CMake.
- [libigl](https://libigl.github.io/), [finite-diff](https://github.com/zfergus/finite-diff), [Discregrid](https://github.com/InteractiveComputerGraphics/Discregrid?tab=readme-ov-file) are automatically downloaded and built through CMake.
### Configuration & Compilation
- First, ensure that Microsoft Visual Studio 2022 and CMake-GUI are installed. They can be downloaded here ([Microsoft Visual Studio 2022](https://visualstudio.microsoft.com/vs/), [CMake-GUI](https://github.com/Kitware/CMake/releases/download/v3.30.0-rc3/cmake-3.30.0-rc3.zip)).
- Then, make sure you are located in your home directory(`MaskDesign/`) and create a new `build` folder in your home directory, which you can also do with code: `mkdir build`
- Next, complete the configuration of `Where is the source code` and `Where to build the binaries` in CMake-GUI:
![image-20240624115140712](./resources/set1.png "set1")
- Click `Configure`, and just use the default options for all of the Configure settings; see inset below. On first use, the whole process takes about 5-10 minutes. Then click `Generate`.
<div align=center><img src="./resources/set2.png" alt="set2" style="zoom:67%;" /></div>
- Run the script `configure.bat` in the `./script/` folder to add dll files for the executable files.
```bat
configure.bat
```
- Click `Open Project` on CMake-GUI. Set MaskDesign as a Sartup project, then build the project in Visual Studio.
## Usage:
### Running the Program:
- To quickly generate a result from Fig.8 in the paper, run the script `./script/run_example.bat`.
- Runing the progarm though command: from home diretory, navigate to the release directory and execute the program with the path to the human face model file as an argument:
```bash
cd ./bin/Release
./MaskDesign.exe [path_to_human_face_file]
```
For instance, to reproduce a result from Fig.8 in the paper:
```bash
./MaskDesign.exe path_to_data_folder/human_face/face1.obj
```
See the input human face and it's alignment with the generic mask here:
<div align=center><img src="./resources/input.png" alt="input" style="zoom:60%;" /></div>
- To use a different human face model, align it with the [generice mask](./data/generic_cushion/generic_mask_interface.obj) first. We assume that the alignment simulates the scenario of a human wearing the mask, and some interpenetration is expected.
### Program Output:
A **customized cushion surface** and a **customized mask interface** will be saved as triangle meshes to `./output` folder. Here is the output visualized in MeshLab:
<div align=center><img src="./resources/output.png" alt="output" style="zoom:40%;" /></div>
### Modifying Design Parameters:
You can modify design parameters in the [parameters.txt](parameters.txt) file. Comments starting with "#" describe the parameters. Key parameters are those related to cushion comfort, air leakage measurement, and trajectory curve initialization:
```bash
# cushion optimization parameters
1e3 # evaluation comfort metric: average pressure
0.2 # evaluation air leakage metric: force distribution
2e-4 # evaluation air leakage metric: area distribution
# (cushion initialization) trajectory curve adjustment weight:
1e3 # objective function: measuring curve to human face distance
2e-4 # cushion width
5e-6 # curvature; control curve smoothness
0.01 # symmetry
1e8 # alignment
120.0 # angle
```
## How to cite
If you want to use any part of this work, please use the following reference:
```
@article{Lu-2024-MaskDesign,
author={Yukun Lu and Yuhang Wang and Peng Song and Hang Siang Wong and Yingjuan Mok and Ligang Liu},
title={Computational Design of Custom-Fit PAP Masks },
journal={Computers & Graphics (Proc. of Shape Modeling International)},
year={2024}
}
```