Treelike  v1.0
Program documentation

Background

This project is an implementation of the paper Parameterization and Feature Extraction for the Visualization of Tree-like Structures [Lichtenberg et al. 2018]. The main contribution of this paper is a method to automatically generate u- and v-parametrisations for a tree-like, tubular mesh, for example a mesh of blood vessels or bronchial structures.

Very tensely summarizing, end-points and a root point of the mesh are detected by iterative skeletonisation, and the u-coordinates are calculated from the mesh geometry (curvature, geodesic distances) and this root point. The v-coordinate is based on the current screen-projection of the mesh and is recalculated per frame. U stretches along the vessel structure, from the root point towards the end points. V stretches from the contour towards the centre of a vessel.

This parameterisation can then be used for various visualisation techniques, like iso-lines, colour-coding, drawing decals or hatching.

Implementation

The program display consists of two parts: The viewer and the control window (GUI), as shown in this image.

Viewer

In the viewer, the currently selected mesh visualisation is drawn. The camera is implemented in an arc-ball style: Holding the left mouse button while moving the mouse rotates the camera around the mesh. Holding the middle or right mouse button while moving pans. The scroll wheel is used to control the camera's distance (zoom).

Control window (GUI)

The GUI allows to select different visualisation techniques (also in combination), and to modify the parameters for each technique. It also allows to load a different mesh. Furthermore, the current parameter settings can be loaded and saved from/to a file. Pressing the F1 key hides/shows the GUI.

Visualisation techniques and parameters

The top section of the GUI, labelled "Main visualisations", is used to select the currently active combination of techniques. Some of the techniques have additional parameters; these are accessible below, in the section "Parameters", when the respective technique is active.

Lighting

Toggles between Blinn/Phong lighting and a plain-coloured mesh. While this is not a separate technique per se, turning off lighting can change the overall impression of other visualisations, most prominently hatching.

Parameters ("Light,Material,Color"):

  • Light dir: defines the 3D direction of incoming light (from a directional light source).
  • Viewer-relative light: If checked, the light direction is relative to the viewer.
  • Ambient, Diff, Spec, Shiny: Define the Blinn/Phong material properties of the mesh.
  • Backg./Cont./Mesh/Unlit color: Set the colour for background, contour, mesh (when lit), mesh (when lighting is disabled) respectively.

Endpoints, Root point

  • Endpoints visualises the detected mesh endpoints as green, semi-transparent spheres.
  • Root point shows the root point as a red sphere.

Parameters ("Light,Material,Color"):

  • Sphere size (in "Light,Material,Color"): Controls the radius of the endpoint-spheres.

Scalar field

This is a colour-code visualisation of the U-parametrisation, i.e., the distance from the root point. The checkbox on contour selects whether the colour-coding is applied to the mesh itself or its contour.

Parameters:

  • Colour map: Allows to pick between four pre-defined colour-coding textures.
  • Invert: Inverts the colour sequence.

Isolines

In this visualisation, iso-lines, i.e. lines marking equal parametrisation values, can be drawn for the U- and V-parametrisation separately or combined.

Parameters:

  • Freq: Sets the frequency of the iso-lines (the higher, the more lines are drawn)
  • Width: Selects the width of each line
  • Same parameters: The above parameters can be changed independently for U and V (when this is not checked), or set to the same values simultaneously.

Hatching

This visualisation generates hatching strokes solely based on the U- and V-parametrisation (contrary to traditional hatching methods which usually employ textures).

Note: Hatching typically looks better if lighting is disabled, as the main purpose of hatching strokes is to provide a hand-drawn appearance.

Parameters:

  • Frequency: Defines the spacing between neighbouring hatching lines (the higher the frequency, the more lines there are and the less their distance is).
  • Offset: Typically not changed by user. Controls the shifting of the hatching pattern along the U-parametrisation.
  • Width: Controls the width of the hatching lines.
  • Length: Controls the (maximum) length of the lines. The actual length is randomized per line between 20% to 100% of this value.
  • Strength: Defines the intensity-decrease as hatching lines approach their end (the higher this value, the "blockier" the lines will look).
  • Number: If this is set higher than one, multiple hatching lines are drawn for each initial location. The additional lines are skewed a bit to increase a hand-drawn appearance.

Decals

This allows to draw decals, like arrows, on either the mesh or the contour (controlled with the checkbox on contour).

Parameters:

  • Scale: The first value controls the decal scaling in its U-direction (and thereby also the total number of decals drawn). The second and third value control the scaling in the decal's V-direction; the second value is used when drawing on the mesh, the third one is used when drawing on the contour.
  • Offset: This controls an offset of the decal positions in the mesh's U- and V-direction. The first value simultaneously controls animation speed and direction. The second value can be used, e.g., to move decals closer to/farther away from the contour.
  • Clamp V: Avoids drawing more than two decals per mesh cross-section.
  • Invert V: Controls whether decals start near the contour, or near the centre of the mesh.
  • Anim: Toggles animation mode. The first offset value controls speed and direction.

Other parameters

  • Cont.width: controls the width of the contour drawn around the mesh
  • Perspective (in "Light,Material,Color"): toggles between orthographic and perspective projection. (Note that the method presented in the paper is only suitable for orthographic projection; perspective projection introduces some discontinuities in the V-parametrisation, which are most noticeable with iso-lines or decals at areas close to the camera.)

Loading different meshes

Pressing the button "Load mesh..." shows a file dialogue, where a mesh file in .obj or .off format can be selected. Subsequently the endpoints and U-parametrisation are calculated (this can take a couple of seconds) and the mesh is displayed.

WARNING: The method of the implemented paper relies on meshes being watertight and manifold.
If the loaded mesh does not fulfil these properties, the outcome will be erroneous at best, or the program can even crash (due to unstable behaviour of one of the used external libraries in that case).

A typical problem of vessel-meshes found on the Internet is that they are often combined from overlapping sub-meshes. Combining these into single connected mesh can be very tedious and error-prone.

The loaded mesh should also have not much more than 10.000 vertices; if it does, it will either take a very long time to calculate the parametrisation, or fail during skeletonisation.

For these reasons, pre-processing of meshes is almost always necessary.

Three example meshes are included and pre-processed as well as possible.

  • "vesselTree4.off" is the default mesh displayed and should be perfectly suited for the paper's method.
  • "bronchial_tree.off" is pre-processed heavily and works quite well; there still remains a small geometric problem in one of the branches resulting in an incorrect U-parametrisation in the vicinity.
  • "aneurysm.obj" fulfils the required properties and works fine. This structure does not have a unique end-point (as per definition in the paper).

Loading and saving parameters

The current parameter settings can be saved to or loaded from a file. Use the buttons "Load params..." and "Save params..." for that task.

Note: All the GUI settings are saved, except the currently loaded mesh and the camera position.

Links

The binary and source code can be downloaded here: