Home

Awesome

Flow and Stress Line Visualization

LineVis is a visualization tool for rendering dense sets of 3D lines using the graphics API Vulkan. It supports loading both traditional flow lines as well as stress lines from multiple principal stress directions.

Teaser image of different data sets displayed using LineVis.

From left to right:

[Crawfis 2003]: Roger Crawfis. 2003. Tornado Data set generator. http://web.cse.ohio-state.edu/~crawfis.3/Data/Tornado/

[Pandey et al. 2018]: Ambrish Pandey, Janet D. Scheel, and Jörg Schumacher. 2018. Turbulent superstructures in Rayleigh-Bénard convection. Nature Communications 9, 1 (May 2018). https://doi.org/10.1038/s41467-018-04478-0

[Wu et al. 2018]: J. Wu, N. Aage, R. Westermann and O. Sigmund, "Infill Optimization for Additive Manufacturing - Approaching Bone-Like Porous Structures," in IEEE Transactions on Visualization and Computer Graphics, vol. 24, no. 2, pp. 1127-1140, 1 Feb. 2018, doi: 10.1109/TVCG.2017.2655523.

Building and running the program

Linux

There are four ways to build the program on Linux systems.

The script build.sh in the project root directory can be used to build the project. If no arguments are passed, the dependencies are installed using the system package manager. When calling the script as ./build.sh --vcpkg, vcpkg is used instead. The build scripts will also launch the program after successfully building it. If you wish to build the program manually, instructions can be found in the directory docs/compilation.

Below, more information concerning different Linux distributions tested can be found.

Arch Linux

Arch Linux and its derivative Manjaro are fully supported using both build modes (package manager and vcpkg).

The Vulkan SDK, which is a dependency of this program that cannot be installed using vcpkg, will be automatically installed using the package manager pacman when using the scripts.

Ubuntu

Ubuntu >= 20.04 is fully supported.

The Vulkan SDK, which is a dependency of this program that cannot be installed using the default package sources or vcpkg, will be automatically installed using the official Vulkan SDK PPA.

Please note that Ubuntu 18.04 is only partially supported. It ships an old version of CMake, which causes the build process using vcpkg to fail if not updating CMake manually beforehand.

Other Linux Distributions

If you are using a different Linux distribution and face difficulties when building the program, please feel free to open a bug report. In theory, the build scripts should also work on other Linux distributions as long as the Vulkan SDK is installed manually beforehand.

Windows

There are two ways to build the program on Windows.

In the project folder, a script called build-msvc.bat can be found automating this build process using vcpkg and Visual Studio. It is recommended to run the script using the Developer PowerShell for VS 2022 (or VS 2019 depending on your Visual Studio version). The build script will also launch the program after successfully building it. Building the program is regularly tested on Windows 10 and 11 with Microsoft Visual Studio 2019 and 2022.

Please note that the Vulkan SDK needs to be installed beforehand if using Microsoft Visual Studio for compilation.

The script build.sh in the project root directory can also be used to alternatively build the program using MSYS2/MinGW on Windows. For this, it should be run from a MSYS2 shell.

If you wish to build the program manually using Visual Studio and vcpkg, or using MSYS2, instructions can be found in the directory docs/compilation.

macOS

There are two ways to build the program on macOS.

The script build.sh in the project root directory can be used to build the program either using Homebrew when supplying no additional arguments, or using vcpkg when calling the script as ./build.sh --vcpkg. As macOS does not natively support Vulkan, MoltenVK, a Vulkan wrapper based on Apple's Metal API, is utilized. Installing it via the scripts requires admin rights. MoltenVK can also be installed manually from the website.

The program can only run with reduced feature set, as the Metal API does currently neither support geometry shaders nor hardware-accelerated ray tracing.

Notes:

How to add new data sets

Under Data/LineDataSets/datasets.json, loadable data sets can be specified. Additionally, the user can also open arbitrary data sets using a file explorer via "File > Open Dataset..." (or using Ctrl+O).

Below, an example for a Data/LineDataSets/datasets.json file can be found.

{
    "datasets": [
        { "type" : "flow", "name" : "Rings", "filenames": "flow/rings.obj", "linewidth": 0.003, "attributes": "Vorticity" },
        { "type" : "flow", "name" : "Tornado", "filenames": "flow/tornado.obj", "linewidth": 0.003, "attributes": "Vorticity" },
        { "type" : "flow", "name" : "Aneurysm", "filenames": "flow/aneurysm.obj", "attributes": "Vorticity" },
        { "type" : "flow", "name" : "Convection Rolls", "filenames": "flow/convection_rolls.obj", "attributes": "Line Curvature" },
        { "type" : "flow", "name" : "Turbulence", "filenames": "flow/turbulence.obj", "attributes": "Lambda_2 Vortex Measure" },
        { "type": "stress", "name": "Bearing",
          "filenames": "stress/bearing_psl.dat", "transform": "rotate(270°, 1, 0, 0)", "version": 3 },
        { "type": "stress", "name": "Cantilever",
          "filenames": "stress/cantilever3D_psl.dat", "transform": "rotate(270°, 1, 0, 0)", "version": 3 }
    ]
}

These files then appear with their specified name in the menu "File > Datasets". All paths must be specified relative to the folder Data/LineDataSets/ (unless they are global, like C:/path/file.dat or /path/file.dat).

Supported formats currently are:

The format of the .obj files is expected to be as follows.

v <x> <y> <z> # vertex at index 1
vt <attribute>
...
g line0
l <v_idx_1> <v_idx_2> ... <v_idx_n>
...

Principal Stress Line (PSL) tracing

This program can be used as the frontend for 3D-TSV, the 3D Trajectory-based Stress Visualizer. For this, select "Stress Line Tracer" in the menu "File > Datasets" to open the line tracing menu. When the 3D-TSV script TSV3D_server.m is running in the background, this application will then communicate with 3D-TSV over TCP/IP using ZeroMQ.

The repository of the backend can be found here: https://github.com/Junpeng-Wang-TUM/3D-TSV

3D-TSV is a visual analysis tool for the exploration of the principal stress directions in 3D solids under load. It was created for the paper "3D-TSV: The 3D Trajectory-based Stress Visualizer" by Junpeng Wang, Christoph Neuhauser, Jun Wu, Xifeng Gao and Rüdiger Westermann (https://www.sciencedirect.com/science/article/pii/S0965997822000552).

Under Data/LineDataSets/mesh.json, available simulation meshes can be specified. For example, when using the sample meshes of 3D-TSV, the following file content can be specified:

{
  "meshes": [
    { "name": "Cantilever", "filename": "../../../data/stress/ADES-2022/cantilever3D.carti" },
    { "name": "Kitten", "filename": "../../../data/stress/ADES-2022/kitten.stress" }
  ]
}

Additionally, the user can also open arbitrary simulation meshes (in .carti or .stress format) and principal stress line (PSL) data sets using a file explorer via "File > Open Dataset..." (or using Ctrl+O). .carti and .stress files will then be opened in the stress line tracing dialog.

Video 1: How to Use LineVis as a Frontend for 3D-TSV

3D-TSV System Overview

Video 2: How to Load External Stress Line Files

3D-TSV External PSL File Loading

Supported Rendering Modes

Below, a list of rendering modes supported in LineVis can be found.

In the branch https://github.com/chrismile/LineVis/tree/opengl-interop, a legacy version of this program using OpenGL is available. It can be used on old systems that do not support Vulkan 1.1. However, we recommend to first try to update the graphics drivers on systems that have issues with Vulkan, as this might already solve all problems that might eventually occur on older systems.

How to report bugs

When reporting a bug, please also attach the logfile generated by LineVis. Below, the location of the logfile on different operating systems can be found.