VofFlow 1.0

.clang-format

@@ -0,0 +1,32 @@
+---
+# Default rules
+BasedOnStyle: LLVM
+ColumnLimit: 120
+IndentWidth: 4
+UseTab: Never
+---
+# C++ rules
+Language: Cpp
+
+AccessModifierOffset: -4
+AlignAfterOpenBracket: DontAlign
+AlignEscapedNewlines: Left
+AllowAllArgumentsOnNextLine: false
+AllowAllConstructorInitializersOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: Empty
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakTemplateDeclarations: Yes
+BreakBeforeBraces: Attach
+BreakConstructorInitializers: BeforeColon
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+DerivePointerAlignment: false
+IndentCaseLabels: true
+NamespaceIndentation: All
+PointerAlignment: Left
+SpaceAfterCStyleCast: true
+SpaceAfterTemplateKeyword: false
+Standard: c++17
+...

.editorconfig

@@ -0,0 +1,17 @@
+# EditorConfig: https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[{CMakeLists.txt,*.cmake}]
+indent_size = 2
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

.github/workflows/build.yml

@@ -0,0 +1,45 @@
+name: Build
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  linux:
+    name: Linux-Build
+    runs-on: ubuntu-22.04
+    container:
+      image: kitware/paraview_org-plugin-devel:5.12.0
+    env:
+      ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true # nodejs 16 is required for CentOS 7
+    steps:
+      - name: Install dependencies
+        run: |
+          # Fix CentOS 7 EOL (https://serverfault.com/a/1161847)
+          sed -i s/mirror.centos.org/vault.centos.org/g /etc/yum.repos.d/CentOS-*.repo
+          sed -i s/^#.*baseurl=http/baseurl=http/g /etc/yum.repos.d/CentOS-*.repo
+          sed -i s/^mirrorlist=http/#mirrorlist=http/g /etc/yum.repos.d/CentOS-*.repo
+          yum -y install devtoolset-9
+      - uses: actions/checkout@v3 # glibc in container is too old for v4
+      - name: Configure
+        run: |
+          PARAVIEW_DIR=`find /builds/gitlab-kitware-sciviz-ci/build/install/lib/cmake -type d -regex "/builds/gitlab-kitware-sciviz-ci/build/install/lib/cmake/paraview-[0-9,.]*"`
+          scl enable devtoolset-9 -- cmake -S . -B ${{github.workspace}}/build -DParaView_DIR=$PARAVIEW_DIR -DCMAKE_BUILD_TYPE=Release
+      - name: Build
+        run: |
+          scl enable devtoolset-9 -- cmake --build ${{github.workspace}}/build --parallel 4
+      - name: Install
+        run: |
+          scl enable devtoolset-9 -- cmake --install ${{github.workspace}}/build --prefix ./install
+      - name: Cleanup
+        run: |
+          mv ./install/lib64 ./install/lib
+      - uses: actions/upload-artifact@v3 # glibc in container is too old for v4
+        with:
+          name: VofFlow
+          path: |
+            ./install/lib/paraview-5.12/plugins/VofFlow/VofFlow.so
+            ./install/bin/MaxVelocity
+            ./install/bin/PolyGap
+            ./install/bin/SeedGrid
+            ./install/bin/SmoothNormals

.gitignore

@@ -0,0 +1,5 @@
+build/
+cmake-build-*/
+.idea/
+.vs/
+.vscode/

CMakeLists.txt

@@ -0,0 +1,81 @@
+cmake_minimum_required(VERSION 3.12...3.29 FATAL_ERROR)
+
+include(CMakeDependentOption)
+
+option(VOFFLOW_USE_VCPKG "Use vcpkg to load dependencies." ON)
+cmake_dependent_option(VOFFLOW_DISABLE_VCPKG_BOOST "Disable vcpkg boost for ParaView superbuild." OFF "VOFFLOW_USE_VCPKG" OFF)
+
+# vcpkg
+if (VOFFLOW_USE_VCPKG)
+  include(FetchContent)
+  mark_as_advanced(FORCE
+    FETCHCONTENT_BASE_DIR
+    FETCHCONTENT_FULLY_DISCONNECTED
+    FETCHCONTENT_QUIET
+    FETCHCONTENT_UPDATES_DISCONNECTED)
+
+  # Require git for download
+  find_package(Git REQUIRED)
+
+  FetchContent_Declare(vcpkg-download
+    GIT_REPOSITORY https://github.com/microsoft/vcpkg.git
+    GIT_TAG 2024.04.26
+    SOURCE_DIR ${CMAKE_CURRENT_BINARY_DIR}/vcpkg)
+  FetchContent_GetProperties(vcpkg-download)
+  if (NOT vcpkg-download_POPULATED)
+    message(STATUS "Fetch vcpkg ...")
+    FetchContent_Populate(vcpkg-download)
+    mark_as_advanced(FORCE
+      FETCHCONTENT_SOURCE_DIR_VCPKG-DOWNLOAD
+      FETCHCONTENT_UPDATES_DISCONNECTED_VCPKG-DOWNLOAD)
+  endif ()
+
+  set(VCPKG_BOOTSTRAP_OPTIONS "-disableMetrics")
+  set(VCPKG_INSTALL_OPTIONS "--clean-after-build" "--no-print-usage")
+  set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_BINARY_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake" CACHE STRING "Vcpkg toolchain file")
+  set(ENV{VCPKG_FORCE_DOWNLOADED_BINARIES} ON)
+
+  if (WIN32)
+    set(VCPKG_TARGET_TRIPLET "x64-windows-static")
+  endif ()
+
+  if (VOFFLOW_DISABLE_VCPKG_BOOST)
+    include(cmake/disable_vcpkg_boost.cmake)
+  endif ()
+endif ()
+
+project(VofFlow
+  LANGUAGES C CXX)
+
+# Set a default build type if none was specified
+if (NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  message(STATUS "Setting build type to 'Release' as none was specified.")
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "RelWithDebInfo" "MinSizeRel")
+endif ()
+
+find_package(ParaView REQUIRED)
+
+option(BUILD_SHARED_LIBS "Build shared libraries" ON)
+
+include(GNUInstallDirs)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}")
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR}")
+
+paraview_plugin_scan(
+  PLUGIN_FILES "${CMAKE_CURRENT_SOURCE_DIR}/src/ParaViewPlugin/paraview.plugin"
+  PROVIDES_PLUGINS plugins
+  ENABLE_BY_DEFAULT ON)
+
+paraview_plugin_build(
+  RUNTIME_DESTINATION "${CMAKE_INSTALL_BINDIR}"
+  LIBRARY_DESTINATION "${CMAKE_INSTALL_LIBDIR}"
+  LIBRARY_SUBDIRECTORY "${PARAVIEW_PLUGIN_SUBDIR}"
+  INSTALL_HEADERS OFF
+  PLUGINS ${plugins})
+
+option(VOFFLOW_TOOLS "Build tools." ON)
+if (VOFFLOW_TOOLS)
+  add_subdirectory(src/Tools)
+endif ()

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Visualization Research Center (VISUS), University of Stuttgart
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,120 @@
+# Visualization of Finite-Time Separation in Multiphase Flow
+
+*Moritz Heinemann, Johanna Potyka, Kathrin Schulte, Filip Sadlo, Thomas Ertl*
+
+![ParaView Plugin Properties](docs/img/teaser.png)
+
+This repository contains the ParaView plugin used in our [paper](https://doi.org/10.1109/TVCG.2024.3493607).
+We provide [details on the reproducibility](docs/REPRODUCIBILITY.md) and usage examples in the [`docs`](docs) folder of this repository.
+
+## Download
+
+Plugin binaries for ParaView 5.12.0 are provided on the [Release Page](https://github.com/UniStuttgart-VISUS/vof-flow/releases).
+They are compatible with the official ParaView 5.12.0 MPI release for Linux or Windows, available from the [ParaView website](https://www.paraview.org/download/):
+- [Download ParaView 5.12.0 MPI Linux](https://www.paraview.org/paraview-downloads/download.php?submit=Download&version=v5.12&type=binary&os=Linux&downloadFile=ParaView-5.12.0-MPI-Linux-Python3.10-x86_64.tar.gz)
+- [Download ParaView 5.12.0 MPI Windows](https://www.paraview.org/paraview-downloads/download.php?submit=Download&version=v5.12&type=binary&os=Windows&downloadFile=ParaView-5.12.0-MPI-Windows-Python3.10-msvc2017-AMD64.zip)
+
+## Build from source
+
+The plugin can be built from source using the common ParaView plugin interface.
+For details, we refer to the [ParaView Plugin Howto](https://www.paraview.org/paraview-docs/v5.12.0/cxx/PluginHowto.html).
+A more detailed example of the build steps can be found in our [reproducibility documentation](docs/REPRODUCIBILITY.md).
+
+## Example Data
+
+The jet-collision dataset from our paper can be used as example data:
+[https://doi.org/10.18419/darus-4225](https://doi.org/10.18419/darus-4225).
+
+## Plugin Usage
+
+The plugin adds three filters to ParaView.
+The main filter is called `VofTracking`, which implements the method described in our paper.
+There are two additional filters called `Plic` and `Plic3` to generate the PLIC surfaces of Volume-of-Fluid datasets.
+All filters require rectilinear grid data as input.
+The properties of the `VofTracking` filters are documented below.
+
+### VofTracking Properties
+
+![ParaView Plugin Properties](docs/img/plugin_properties.png)
+
+| Property                 | Description                                                                                           |
+|--------------------------|-------------------------------------------------------------------------------------------------------|
+| `Use Three Phase`        | Switch between two-phase and three-phase.                                                             |
+| `VoF`                    | VoF array.                                                                                            |
+| `VoF3`                   | VoF3 array (if three-phase).                                                                          |
+| `VoF Norm`               | VoF normals array (if three-phase).                                                                   |
+| `Velocity`               | Velocity array.                                                                                       |
+| `Use Components`         | Switch to use custom component fields.                                                                |
+| `Components VoF`         | Components field for the VoF data.                                                                    |
+| `Components VoF3`        | Components field for the VoF3 data (if three-phase).                                                  |
+| `Use Target Time Step`   | Switch to use a fixed target time step. If false, the current ParaView time is used.                  |
+| `Init Time Step`         | Initial time step.                                                                                    |
+| `Target Time Step`       | Target time step (if `Use Target Time Step` is true, otherwise current ParaView time is used).        |
+| `Refinement`             | Number of seeded particles per cell is (r+1)^3.                                                       |
+| `Neighbor Correction`    | Enable Neighbor Correction step.                                                                      |
+| `Cell Correction`        | Enable Cell Correction step.                                                                          |
+| `PLIC Correction`        | Enable PLIC Correction step.                                                                          |
+| `Integration Method`*    | Select the particle advection integration method: `RK4` or `Euler`.                                   |
+| `Integration Sub-Steps`* | Select the number of sub-steps used for the integration.                                              |
+| `Epsilon`*               | Epsilon for the PLIC surface generation.                                                              |
+| `Num Iterations`*        | Maximum number of iterations used for the PLIC surface generation.                                    |
+| `Ghost Cells`            | Number of ghost cells shared between MPI processes.                                                   |
+| `Cut Labels`*            | Use label cut function (experimental).                                                                |
+| `Label Cut Type`*        | vtkImplicitFunction for cutting label space (experimental).                                           |
+| `Boundary Method`*       | Method used to generate the separation boundaries `DiscreteMarchingCubes` or `DiscreteFlyingEdges3D`. |
+| `Output Data Type`       | Type of the grid output data: `vtkRectilinearGrid` or `vtkImageData`.                                 |
+| `Output State`*          | Store state of plugin properties as json in the output data.                                          |
+| `Output Time Measure`*   | Store benchmarking data in the output data.                                                           |
+| `Mirror X Min`           | Mirror boundary condition at X min boundary.                                                          |
+| `Mirror X Max`           | Mirror boundary condition at X max boundary.                                                          |
+| `Mirror Y Min`           | Mirror boundary condition at Y min boundary.                                                          |
+| `Mirror Y Max`           | Mirror boundary condition at Y max boundary.                                                          |
+| `Mirror Z Min`           | Mirror boundary condition at Z min boundary.                                                          |
+| `Mirror Z Max`           | Mirror boundary condition at Z max boundary.                                                          |
+
+Properties marked with `*` are advanced properties.
+Use the ParaView `Toggle advanced properties` button to show them.
+
+### VofTracking Output
+
+![ParaView Plugin Properties](docs/img/plugin_pipeline.png)
+
+The VofTracking filter has four outputs.
+
+| Output             | Description                                                                                    |
+|--------------------|------------------------------------------------------------------------------------------------|
+| Grid               | Output grid with the extracted labels and the grid-based uncertainty values.                   |
+| Seeds              | Seeded particles, including label and particle-based uncertainty values.                       |
+| Advected Particles | End position of the advected particles, including label and particle-based uncertainty values. |
+| Boundaries         | Extracted separation boundaries.                                                               |
+
+## Citing
+
+If you use our work in a scientific context, please cite our work:
+
+M. Heinemann, J. Potyka, K. Schulte, F. Sadlo, T. Ertl: "**Visualization of Finite-Time Separation in Multiphase Flow**" in IEEE Transactions on Visualization and Computer Graphics, doi: 10.1109/TVCG.2024.3493607.
+
+```bibtex
+@Article{Heinemann2024VofFlow,
+  author  = {Heinemann, Moritz and Potyka, Johanna and Schulte, Kathrin and Sadlo, Filip and Ertl, Thomas},
+  journal = {IEEE Transactions on Visualization and Computer Graphics},
+  title   = {Visualization of Finite-Time Separation in Multiphase Flow},
+  year    = {2024},
+  pages   = {1-14},
+  doi     = {10.1109/TVCG.2024.3493607},
+}
+```
+
+## License
+
+> Copyright (c) 2024, Visualization Research Center (VISUS), University of Stuttgart
+
+Our code in this repository is licensed under the [BSD 3-Clause License](LICENSE).
+
+Additionally, the following dependencies with their corresponding licenses are used and/or downloaded automatically during the build step or in some of our scripts:
+
+- [ParaView](https://gitlab.kitware.com/paraview/paraview)
+- [CGAL](https://github.com/cgal/cgal)
+- [JSON for Modern C++](https://github.com/nlohmann/json)
+- [vcpkg](https://github.com/microsoft/vcpkg)
+- [ParaViewEasyPluginBuilder](https://gitlab.kitware.com/paraview/paraview-easy-plugin-builder)

cmake/disable_vcpkg_boost.cmake

@@ -0,0 +1,21 @@
+# Disable all vcpkg boost* ports, to use the version provided by the ParaView superbuild.
+# This overwrites all boost ports with empty ports. The empty ports use the original
+# vcpkg.json to keep all features and dependencies next to an empty portfile.
+
+set(empty_ports_dir "${CMAKE_CURRENT_BINARY_DIR}/vcpkg_empty_ports")
+
+# Cleanup port dir
+file(REMOVE_RECURSE "${empty_ports_dir}")
+file(MAKE_DIRECTORY "${empty_ports_dir}")
+
+# Searching boost ports
+set(port_dirs "${CMAKE_CURRENT_BINARY_DIR}/vcpkg/ports")
+file(GLOB boost_ports RELATIVE ${port_dirs} ${port_dirs}/boost*)
+
+# Create empty port
+foreach (portname ${boost_ports})
+  file(COPY "${port_dirs}/${portname}/vcpkg.json" DESTINATION "${empty_ports_dir}/${portname}/")
+  file(WRITE "${empty_ports_dir}/${portname}/portfile.cmake" "set(VCPKG_POLICY_EMPTY_PACKAGE enabled)\n")
+endforeach ()
+
+set(VCPKG_OVERLAY_PORTS "${empty_ports_dir};${VCPKG_OVERLAY_PORTS}")