Q-MAT

This is an open-source code repository for SIGGRAPH paper Q-MAT: Computing Medial Axis Transform by Quadratic Error Minimization. It contains the core simplify function of Q-MAT. For more supports, please see the Todo List.

If our open-source Q-MAT contributes to an academic publication, please cite it as:

@misc{qmatcode,
  title = {Q-MAT Open-source Code},
  author = {Yin, Yibo and Wang, Ningna and Song, Shibo},
  howpublished = "\url{https://github.com/ningnawang/QMAT}",
  year = {2024}
}

And please cite the original paper:

@article{li2015q,
  title={Q-mat: Computing medial axis transform by quadratic error minimization},
  author={Li, Pan and Wang, Bin and Sun, Feng and Guo, Xiaohu and Zhang, Caiming and Wang, Wenping},
  journal={ACM Transactions on Graphics (TOG)},
  volume={35},
  number={1},
  pages={1--16},
  year={2015},
  publisher={ACM New York, NY, USA}
}

Tested on:

• MacOS M3
• Windows
• Ubuntu22.04

Requirements

• C++ (>=14)

• CGAL (5.6.1)

  NOTE: Since CGAL version 5.0, CGAL is header-only be default, which means that there is no need to build CGAL before it can be used. Thus, CGAL header files are included in include/CGAL. Also, you can see /Eigen and /boost in the same directory. These are dependencies for CGAL and are also header-only. Details can be seen at: CGAL 5.6.1 Manual

• CMake (3.16)

• OpenMP (MacOS)

• gcc-9(Ubuntu) sudo apt install gcc-9

• libgmp(Ubuntu) sudo apt install libgmp-dev

• NOTE: For Ubuntu users, if you have installed boost which is not 1.82.0, there might have some issues, conda install boost==1.82.0 could solve this issue.

Installation & Run

• Clone the repository into your local machine:

git clone https://github.com/ningnawang/QMAT

• Compile the code using cmake (first compilation may takes a while):

cd QMAT
mkdir build && cd build
cmake ..
make -j4

• Run the program:

./QMAT <mode> <surface_mesh.off> <medial_mesh.ma> <num_target_spheres> [output_path] [selected_points.txt]

The program supports two running modes:

1. Mode 1: Regular Simplification

   ./QMAT 1 <surface_mesh.off> <medial_mesh.ma> <num_target_spheres> [output_path]
   

   This mode performs the standard Q-MAT simplification.

2. Mode 2: Simplification with Selected Poles

   ./QMAT 2 <surface_mesh.off> <medial_mesh.ma> <num_target_spheres> [output_path] <selected_points.txt>
   

   This mode performs simplification while preserving selected poles. The selected poles should be provided in the selected_points.txt file using the following format:

   v x y z r
   v x y z r
   ...
   

   You can generate the points with others MAT methods and establish connections by using this mode. For example, we use CoverageAxis to generate selected_points.

Parameters:

• mode: 1 for regular simplification, 2 for simplification with selected poles
• surface_mesh.off: Input surface mesh file in OFF format
• medial_mesh.ma: Input medial axis file in MA format
• num_target_spheres: Target number of spheres after simplification
• output_path: (Optional) Directory to save output files. Default is ./data/. The path should end with /
• selected_points.txt: (Required for mode 2) File containing selected poles to preserve

Output Files:

All output files will be saved to the specified output_path directory:

• sim_MA___v_X___e_Y___f_Z.obj: Simplified medial axis in OBJ format
• export_half___v_X___e_Y___f_Z.ma: Simplified medial axis in MA format
• test_all_poles.obj: (Mode 2 only) All poles visualization file

Examples:

Regular simplification with default output path:

./QMAT 1 ../data/bug.off ../data/bug.ma 200

Regular simplification with custom output path:

./QMAT 1 ../data/bug.off ../data/bug.ma 200 /home/user/output/

Simplification with selected poles:

./QMAT 2 ../data/bug.off ../data/bug.ma 200 ./results/ ../data/selected_points.txt

Simplification with selected poles using default output path:

./QMAT 2 ../data/bug.off ../data/bug.ma 200 ./data/ ../data/selected_points.txt

The .ma Format

The .ma file is the commonly used MAT format:

numVertices numEdges numFaces
v x y z r
e v1 v2
f v1 v2 v3

One can load the *.ma file using Blender with an open-sourced blender-mat-addon.

Once you finished the cmake process, you can use mesh_to_ma to generate .ma file by using .off file.

To transfer a .obj file to .off file, just use meshlabserver -i XX.obj -o XX.off Then

cd build
./mesh_to_ma XX.off

Q&A

1. For MacOS, resolving clang: error: unsupported option '-fopenmp':

The problem is that AppleClang does not support -fopenmp, one should use brew's 'llvm'.

• step 1:

$brew install llvm libomp

• step 2: Update Compiler Variables (or update in ~/.zshrc if you want to use brew's Clang than AppleClang permanently)

export CC=/usr/local/opt/llvm/bin/clang

Todo List:

1. add polyscope for GUI
2. ...