add README.md

# Meshing

There are several approaches commonly used to define domains for volumetric mesh generation:

1. Domains defined implicitly by level sets of functions.

2. Domains defined by a set of bounding polygons (i.e., a polygonal surface mesh).

3. Domains defined constructively using solid modeling, i.e. [constructive solid geometry](

   https://en.wikipedia.org/wiki/Constructive_solid_geometry) (CGS).

4. Hybrid domains defined by a combination of the several aforementioned approaches.

The second approach, CGS, can be translated to the previous approaches either by discretizing the

solid model's boundary into polygons, or by constructing an appropriate level set.

The polygonal boundary can also be treated as a level set of a suitable function, but it is

separated because there are notable differences between the first two approaches:

- Meshing an implicitly defined domain ensures that all boundary points are in the level set within

  any specified error bound. On the other hand, a polygonal surface may be already an approximation

  of a smooth, curved domain, in which case meshing the polyhedron may result in more or less

  visible edges.

- Intersections of polygonal surfaces can be computed automatically, so the meshing tool can be

  instructed to preserve sharp features of the surface. On the other hand, sharp features of

  domains defined implicitly by level sets of functions must be specified manually, which may be

  tedious. (In the CGS approach, intersections of subdomains in unions or differences could also be

  determined automatically, but the evaluation of the CGS model is more expensive compared to

  polygonal surface algorithms.)

- Finally, the available polygonal surface may be "dirty". For example, the bounding may not be

  "water-tight", there may be duplicate vertices or edges, overlapping polygons, etc.

## Tools in this repository

This repository provides several tools based on the [CGAL library](

https://doc.cgal.org/latest/Mesh_3/index.html), which offers algorithms for 3D volumetric mesh

generation based on the first two concepts.

- [cgal-mesher](./cgal-mesher.cpp) is a command-line tool generating a volumetric mesh from an

  input polygonal surface mesh.

- [cgal-view-surface](./cgal-view-surface.cpp) is a graphical viewer for surface polygonal meshes

  based on the Qt5 library.

The polygonal surface mesh can be in either of the OFF, STL, OBJ, PLY, VTP, or GOCAD file formats.

See the [CGAL documentation](https://doc.cgal.org/latest/Polygon_mesh_processing/group__PMP__IO__grp.html)

for more information.

## Installation

First, make sure that the required packages are installed on your Linux system. On Arch Linux,

these are:

[base-devel](https://archlinux.org/groups/x86_64/base-devel/),

[cmake](https://archlinux.org/packages/extra/x86_64/cmake/),

[cgal-headers](https://aur.archlinux.org/packages/cgal-headers/),

[eigen](https://archlinux.org/packages/extra/any/eigen/),

and [git](https://archlinux.org/packages/extra/x86_64/git/).

Optionally, install [tbb](https://archlinux.org/packages/extra/x86_64/tbb/) to enable parallelism

in CGAL, and [qt5-svg](https://archlinux.org/packages/extra/x86_64/qt5-svg/) to build the

`cgal-view-surface` tool.

Then clone this repository and initialize its submodules:

    git clone --recurse-submodules https://mmg-gitlab.fjfi.cvut.cz/gitlab/klinkovsky/meshing.git

    cd meshing

Finally, build the tools:

    cmake -B build -S . -DCMAKE_BUILD_TYPE=Release

    make -C build

When successful, the executables will be found in the `build` directory.  You can test the tools on

the examples provided in the [meshes](./meshes) directory.

## Other software

[meshio](https://github.com/nschloe/meshio) can be used to convert meshes between various file

formats.

### Constructive solid geometry

[OpenSCAD](https://openscad.org/) is a solid 3D CAD modeller for programmers.

[SolidPython](https://github.com/SolidCode/SolidPython) is a Python front-end for solid modelling

that compiles to OpenSCAD.

OpenSCAD can export a polygonal surface of the model to the [STL, OFF or other format](

https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/STL_Import_and_Export).

[pygalmesh](https://github.com/nschloe/pygalmesh) is a Python interface to CGAL's 2D and 3D meshing

tools. It combines a primitive CGS-like approach with the implicit level set definition that is

used required by CGAL.

### Mesh generators

See these awesome comprehensive lists:

- https://github.com/nschloe/awesome-scientific-computing#meshing

- http://www.robertschneiders.de/meshgeneration/software.html