Commit 2d043935 authored by Charles Gueunet's avatar Charles Gueunet 🎸
Browse files

Merge branch 'ReadmeImprove' into 'master'

Add How to use & contribute secion and fix some phrasing

See merge request !31
parents 1de2c4d5 7e11aad4
Pipeline #307387 passed with stages
in 17 minutes and 18 seconds
......@@ -2,6 +2,22 @@
(V)TK (E)nhanced with (S)urface (P)rocessing (A)lgorithms
## Summary
<!--toc:start-->
- [Brief](#brief)
- [How to install](#how-to-install)
- [VTK](#vtk)
- [ParaView](#paraview)
- [CGAL](#cgal)
- [VESPA](#vespa)
- [How to use](#how-to-use)
- [VTK Module](#vtk-module)
- [Cope examples](#cope-examples)
- [ParaView plugin](#paraview-plugin)
- [How to contribute](#how-to-contribute)
<!--toc:end-->
# Brief
This project contains VTK filters that use CGAL for mesh processing.
......@@ -12,7 +28,7 @@ CGAL, any binary generated with it retains the GPLv3 license.
# How to install
The VESPA project requires on your system:
The VESPA project requires the following software:
* the [CMake](https://cmake.org/) build system,
* the [VTK library](https://vtk.org/) for the module or [ParaView software](https://www.paraview.org/) for the plugin,
......@@ -20,36 +36,75 @@ The VESPA project requires on your system:
### VTK
We need VTK >= 9.0. It can be installed:
VESPA needs VTK >= 9.0. It can be installed:
* using the package manager of your system (including brew on OSX, or vcpkg on Windows),
* manually using [CMake instructions](https://vtk.org/Wiki/VTK/Configure_and_Build).
### ParaView
We need ParaView >= 5.10.0. It can be installed:
* using the package manager of your system (including brew on OSX, or vcpkg on Windows),
* by downloading the software [on the official website](https://www.paraview.org/download/),
* manually using [CMake instructions](https://gitlab.kitware.com/paraview/paraview/-/blob/master/Documentation/dev/build.md).
VESPA needs ParaView >= 5.10.0. In order to build plugins, ParaView needs to
be compiled from sources manually using these
[CMake instructions](https://gitlab.kitware.com/paraview/paraview/-/blob/master/Documentation/dev/build.md).
### CGAL
We need CGAL >= 5.3. It can be installed:
VESPA need CGAL >= 5.3. It can be installed:
* using the package manager of your system (including brew on OSX, or vcpkg on Windows),
* manually using [CMake instructions](https://doc.cgal.org/latest/Manual/installation.html#installation_configwithcmake).
If you want to get the [Alpha Wrapping](https://doc.cgal.org/latest/Alpha_wrap_3/index.html#Chapter_3D_Alpha_wrapping)
module, CGAL >= 5.5 is required.
### VESPA
Then, we can install this project using the standard CMake procedure:
VESPA can be installed using the standard CMake procedure:
1. Create a build folder
1. Launch CMake with this repository as source folder
1. Configure the project. It will need CGAL, as well as VTK or ParaView depending on whether only the VTK module or the full ParaView plugin should be built.
1. Configure the project. It will need CGAL, as well as VTK or ParaView
depending on whether only the VTK module or the full ParaView plugin should
be built.
If you want to build the ParaView plugin, set the CMake variable `VESPA_BUILD_PV_PLUGIN` to `ON`.
- If you have installed a library in a custom folder, you can find it in CMake
by giving the folder: **install_dir**/lib/cmake/**project-version**. For example,
for VTK: **install_dir**/lib/cmake/vtk-9.1.
- You can provide a custom `CMAKE_INSTALL_PREFIX` if you do not want to install
this project system wide.
1. Build and install this project (please refer to the
VESPA system wide.
1. Build and install VESPA (please refer to the
[VTK tutorial](https://vtk.org/Wiki/VTK/Configure_and_Build#Build_VTK)
if you do not know how to proceed).
# How to use
Except when stated otherwise, filters provided by VESPA require triangulated
surfaces (`vtkPolyData` meshes). These should be watertight and 2-manifold.
### VTK Module
With VTK, you may use the
[vtkTriangleFilter](https://vtk.org/doc/nightly/html/classvtkTriangleFilter.html)
and the
[vtkGeometryFilter](https://vtk.org/doc/nightly/html/classvtkGeometryFilter.html)
to get a valid triangulation. The `vtkCGALAlphaWrapping ` filter can be used
to ensure watertight, 2-manifold mesh then.
#### Cope examples
The testing of the project may be used to get simple examples on how to use each
provided filters. For instance,
for the [Isotropic remeshing](https://doc.cgal.org/latest/Polygon_mesh_processing/group__PMP__meshing__grp.html#gaa5cc92275df27f0baab2472ecbc4ea3f)
you get a [C++ example](./vespa/PolygonMeshProcessing/Testing/TestPMPIsotropicExecution.cxx)
and a [Python example](./vespa/PolygonMeshProcessing/Testing/execute_IsotropicRemesher.py)
### ParaView plugin
On ParaView, you may apply a `Tetrahedralize` and a `Extract Surface` filters
to get a valid triangulation. The `VESPA Alpha Wrapping` filter can be used
to ensure watertight, 2-manifold mesh then.
# How to contribute
If you want to contribute to this repository, simply open a Merge request
on the [gitlab instance](https://gitlab.kitware.com/vtk-cgal/vespa), we will
gladly review and help you merge your code.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment