HyperTreeGrid in VTK: Using Masks

This is the third part of a series of blog articles about vtkHyperTreeGrid usage and implementation in VTK. The first part, an introduction about HTG, can be found here, the second part, HTG data construction, can be found here.

After quickly focusing on the TB-AMR (tree-based Adaptive Mesh Refinement) technique and a HyperTreeGrid building (the TB-AMR representation in VTK), we suggest to extend this construction to include the notion of mask.

Declare and set mask

Let us resume the construction of this kind of representation by following the example written in Python from the previous article in order to complete it.

We keep the construction stages by modifying the third step from HTG data construction article, Use the cursor to build the tree with successive refinement.

As we have seen, at any time when browsing the datastructure, information is accessible from the cursor, in particular the global offset, which identifies the index in an array where the value of the current cell must be stored, or the access reading mode.

Once we have declared an array, it is then easy to position the value for the cell pointed to by the cursor by doing this:

The mask setting is done in a similar way by declaring an array of bits (the name is free):

and then applied during construction:

True means that the cell is hidden, therefore invisible.
False means that the cell is not hidden, therefore visible.

Associate mask on HTG

Once the construction of the HTG is finished, we send the mask to the latter by the following call:

Read access to the mask value using the cursor

During a read scan, do not forget to test the value of the mask by doing:

The mask is then automatically taken into account in the filters and render mappers.

Write access to the mash value using the cursor

During a write scan, the mask has not yet been positioned at the HyperTreeGrid, you must directly interrogate the mask array by doing:

This can happen because your way of building a HyperTree requires going over the same spot multiple times.

The parent mask status can override daughter mask status

If a parent cell is masked, the daughter cells will be considered as masked, even if the value of the mask is not True. The memory occupation does not change, nor does the number of vertices (coarse or fine/leaf) in the tree.

Set mask on child cells

After refining a cell, it is important that you browse each of the child cells in order to set the mask to False, the default value. A safe way to do this is to combine a refinement:

This is especially important if you are browsing the tree not only in construction but also in reading. In fact, you might then find something like this in the code :

In the next example, the tree is traversed only once and does not require this coding “protection”.

Small complete example

We provide here a small complete Python code whose result will give:

Fig 1: The result of this example building an TB-AMR (HTG) of 3×2 cells of which three cells are defined of which has been refined, included a mask which was used to hide a leaf cell. Note that if you do not initialize with a cursor under construction on a rectilinear grid cell, the cell is not defined.

Code validated in ParaView 5.9.1

A complete example in Python was made by S├ębastien Jourdain during a “Hackathon” in January 2019, but by preallocating the size of the mask in order to set it by default to false. https://gitlab.kitware.com/vtk/vtk/-/blob/master/Common/DataModel/Testing/Python/TestHyperTreeGrid2DMask.py

Other example in 3D: https://gitlab.kitware.com/vtk/vtk/-/blob/master/Common/DataModel/Testing/Python/TestHyperTreeGrid3DMandel.py

CEA, DAM, DIF, F-91297 Arpajon, France

Questions or comments are always welcome!