A VTK pipeline primer (part 1)

In my last two blogs (1, 2), I introduced the vtkPythonAlgorithm and started demonstrating how it can be used to develop sources and algorithms in Python. In those articles, I touched on a few VTK pipeline concepts. For those are not familiar with VTK’s pipeline, this may have been somewhat hard to follow. So in this article and the next, I will take a step back and explain how VTK’s pipeline works in more detail.

Preliminaries

vtkInformation and vtkInformationVector

These two classes are used all over the VTK: in algorithms, in executives, in data objects. They were developed by Brad King when we overhauled the VTK pipeline in VTK 4. Conceptually, they are simply maps. The key is a pointer to an instance of a vtkInformationKey (or of a subclass) and the value is an instance of vtkObjectBase (or of a subclass). Let’s start with an example.

This will print the following.

On line 4, we created a new key type. Most often you will use existing keys but it is useful to know how to create them. This key has a name a new key and location some class. The latter is usually the name of the class this key is accessed from. More on that later. One line 7, we create an empty information object. On line 10, we add a new vtkObject to the information object. Not that line 10 looks backwards and it feels more natural to do the following instead.

Both of these work. We’ll see below why. As I mentioned above, the values stored in an information object are all vtkObjectBase and subclass instances. However, it is relatively easy to store simple types by wrapping them with simple vtkObjectBase subclasses. For example, we can store integers easily as below.

This prints

This example may have made it a bit more clear why the methods to set values on information objects are in the key classes. Using the keys’ API to set values enables us to store multiple types without having to make vtkInformation aware of all types. As long as it can wrap a value or a set of values in a subclass of vtkObjectBase, a key can store data of any type. On the other hand, vtkInformation can only provide the API for the key types it is aware of. You can verify this by checking out vtkInformation.h. It has individual set/get methods for each key type it recognizes. Since most of the code that interact with information objects use already defined key types, you will see the information.Set(key, value) signature much more often. If you define your own key type, you will have to use the key.Set(information, value) signature.

Most often, you will access existing keys rather than create new ones. Keys created in C++ usually exist with the scope of a class and are accessed by calling a static member function. Like so:

This will print the following.

When writing code in C++, you can use various macros to create keys. For example, vtkStreamingDemandDrivenPipeline.UPDATE_PIECE_NUMBER() is created using the following.

  • vtkStreamingDemandDrivenPipeline.h:

  • vtkStreamingDemandDrivenPipeline.cxx:

vtkInformationVector is a simple vector of vtkInformation objects. Here is a demonstration.

This will print the following.

Connecting algorithms to create pipelines

Next, let’s check out how algorithms are connected together to form pipelines. Below is a simple pipeline consisting of 2 sources (s0 and s1) and 3 filters (f0, f1 and f2).

example pipeline

  • During execution, data flows in the direction of the arrows,
  • s0, s1 and s2 are simple sources with 1 output each,
  • f0 is a filter with 2 inputs and 1 output. The first input (input 0) is repeatable,
  • f1 and f2 are simple filters with 1 input and 1 output.

The code to create this pipeline would look something like this:

This is enough detail about the pipeline for now. We’ll cover the pipeline execution order and passes in the next blog. Let’s see what each of these algorithm classes looks like.

Source:

When the pipeline is updated with f1.Update() or f2.Update(), the Source instances will print the following 3 times.

This class is pretty self-explanatory. Note how in RequestData(), there is a direct relationship between the contents of inInfo and the input connections and outInfo and output connections. In the cae of a source, outInfo, which is a vtkInformationVector contains only one vtkInformation object corresponding to the only output. InInfo on the other hand will be empty since this is a source and has no input ports.

Filter1:

This is also fairly straightforward. A filter with one input and one output. InInfo will contain one vtkInformationVector (first input port) which will contain one vtkInformation (first and the only connection).

Finally, let’s look at Filter0, which is the most complicated algorithm in the example:

Overall, this algorithm still looks fairly simple. Its one unusual attribute is how it sets the first port to be repeatable in FillInputPortInformation. This means that this port can accept an arbitrary number of connections, which are established using AddInputConnection(). The most common example of such an algorithm is >vtkAppendFilter. This filter accepts multiple inputs, which it appends together to produce 1 output.

When the pipeline is updated, this will print the following.

If you look at the output carefully, you will notice that inInfo contains 2 vtkInformationVector objects, each corresponding to 2 input ports. The first port is repeatable and contains 2 connections. Therefore, the first vtkInformationVector contains 2 vtkInformation objects. The second port accepts only 1 connection and hence the second vtkInformationVector contains only vtkInformation object.

Hopefully, this gives you enough information to get started with writing basic algorithms. In my next blog, I will cover how the pipelines performs multiple passes during execution and how these passes are implement by algorithms.

On to VTK Pipeline Primer: Part 2.

Questions or comments are always welcome!