3D-TSV

Description

This page is created to showcase and exchange the use of 3D-TSV and its accessories. Reporting bugs, leaving comments, and sharing cool application cases are warmly welcomed!

3D-TSV is a suite of trajectory-based stress tensor visualizers, which takes Principal Stress Line (PSL) as the basic visual abstract, and with a special focus on the domain-filling and evenly spaced placement of PSLs.

3D-TSV was originally developed to work with the node-wise stress tensor field of a 1st-order hexahedral mesh, which can either be a Cartesian mesh or an unstructured mesh. With subsequent efforts, three new features are introduced to 3D-TSV. (i) Support to the 1st-order tetrahedral mesh; (ii) Support to element-wise stress tensor fields; (iii) Support to 1st-order quadrilateral and triangular meshes in 2D.

3D-TSV is primarily implemented using MATLAB and can be used in varies ways. For advanced visual quality control of the result, one can take 3D-TSV as a backend and call it from a OpenGL-based frontend line visualizer, as demonstrated in the paper. For common use cases, one can simply run it in a pure MATLAB environment, which can either be accessed through a GUI or a script. Besides, we also provide the "easy-to-use" versions for application scenarios where one simply wants to see the PSLs quickly, to achieve this, the kernal functions of 3D-TSV are integrated into a single MATLAB script and several control parameters are omitted.

For an overview of this tool, please have a look at the README of the code repository and watch the guide videos.

Updates

2025-07-04: Especially to the old users: the format of the dataset files are slightly adjusted to fit the newly introduced functionalities, and a more intuitive extension (.TSV) of the input file is used, please refer to the updated datasets in the code repository.
2025-07-03: Support to element-wise data is added.
2025-07-01: Support to 1st-order Tet-mesh data is added.
2025-06-30: Page is created.

What can 3D-TSV do?

Domain-filling and evenly spaced PSLs generation of a stress field defined at the vertices of a 1st-order tetrahedral or hexahedral volume mesh in 3D. ✔️
Domain-filling and evenly spaced PSLs generation of a stress field defined at the vertices of a 1st-order triangular or quadrilateral planar mesh in 2D. ✔️
Stress topology analysis of a stress field defined at the vertices of a 1st-order triangular or quadrilateral planar mesh in 2D. I.e., capturing degenerate point(s) and create topological skeleton. ✔️
Domain-filling and evenly spaced PSLs generation of a stress field defined per-element of a 1st-order tetrahedral or hexahedral volume mesh in 3D or Triangular or quadrilateral planar mesh in 2D. ✔️
Stress fields simulated at the hybrid meshes are not supported for now. ❌

Data Format

3D-TSV defines a general ASCII file (.TSV) to input stress field from various unstructured meshes, including stress data type (node-wise or element-wise), mesh type (hexahedral, tetrahedral, quadrilateral, or triangular), mesh info (vertices, elements), loads and fixations (optional), Cartesian stress info (by order Sigma_xx, Sigma_yy, Sigma_zz, Sigma_yz, Sigma_zx, Sigma_xy in order) solid voxels/Elements, node-wise boundary conditions, per-voxel density values (optional), and passive elements if necessary. Both element and node information are stored as the indices of the target entities in the corresponding binary volume data (V) in Row-Column-Page order, refer to indices=find(V) in MATLAB.
For stress field simulated on a Cartesian mesh in 3D (commonly seen in structural topology optimization), 3D-TSV utilizes a tailored ASCII file (.TSVcarti) for stress field input, which can save data size, and more importantly, benefiting PSL tracing because of the clean topology of a Cartesian mesh. This file includes: stress data type (node-wise or element-wise), mesh info (volume resolutions, bounding box, indices of the "solid" elements in the volume), loads and fixations (optional), Cartesian stress info, as above. The element information is stored as the indices of the target entities in the corresponding volume data (V) in Row-Column-Page order, refer to indices=find(V) in MATLAB.
3D-TSV also provides guidelines on how to extract the required stress information from commericial CAE packages like ANSYS, ABAQUS, and PERMAS
The generated PSLs and the corresponding silhouette of the domain can be exported to a ".dat" file.

Demonstration Cases

Case 3: Visualizations in 2D

Context: The PSL placement algorithm of 3D-TSV seamlessly works for 2D cases. Especially, it can be combined with stress topology analysis for improved placement regularity and better represen.

Case 2: Work with datasets from unstructured hex- and tet-meshes

Context: 3D-TSV can be used to generate PSLs of stress fields that are simulated at a hex- or tet-mesh, and enables the importance-based PSLs selection. Besides, the user can also specify the PSLs to be shown in ribbons that convey the other principal stress directions and potential singularities (i.e., switch of different principal stress directions).

Case 1: Trajectory-based stress tensor visualization of stress fields simulated at Cartesian hexahedral meshes

Contexts: Cartesian hexahedral mesh is frequently used in structural topology optimization in 3D, assuming one wants to investigate the stress tensor field in the optimized structure and compare it to the corresponding one from the solid domain.

Major (warm color) and minor (cold) PSLs