Getting started

Data Flow Concept

The design of the Voreen framework revolves around the concept of data-flow networks.

These networks consist of modular units, called processors, which encapsulate rendering and data processing algorithms. A processor operates on input data it receives from its inports and outputs the processed results via its outports.

The data flow is established by unidirectional connections from outports to inports. Processor ports are typed, meaning each port transmits a specific type of data, such as a 2D image, a 3D volume, geometric data, or a collection of objects of these basic types. Processors also have properties that allow parameterization of the encapsulated algorithms. Voreen offers various types of properties, ranging from primitive numeric types to complex rendering parameters such as camera position and transfer functions. Properties can be linked within and across processors to synchronize their values.

The strength of the data-flow concept lies in the flexible combinability of components. Since a processor's behavior is solely determined by its input data and property configuration, processors can be arbitrarily joined into networks, with the only restriction that connected ports must be of equal type. Moreover, there is no distinction between standard processors provided by the framework and custom processors created by external developers. This allows developers to focus on implementing new techniques while utilizing standard framework processors for common data processing, rendering, and user interaction tasks.

---

User Interface

Main Window

The following screenshot shows a typical state of a VoreenVE session:

The green numbers indicate the main components:

1. The network editor shows the current processor network and allows the user to modify it interactively.
2. The canvas window shows the result produced by the current network. When there are multiple canvas processors in your network, also multiple canvas windows will appear.
3. The processors list shows all available processors. These can be used to construct networks.
4. The properties allow configuration of the selected processor.
5. The volume container shows the currently loaded volumes.
6. The debug console shows information about the graphic card and informs the user about errors in the render path.

Modes

Voreen can be used in network mode and application mode. Rendering networks are constructed in the network mode. Switching to application mode hides the network editor and displays a larger visualization window. While the layout of the rendering network cannot be changed in application mode, it is still possible to modify properties of the processors in the network. However, property editing in the application mode is restricted to those properties, which have been set visible in the application mode configuration.

The same network as in Main Window looks like this in application mode:

Toolbar

The picture below shows the toolbar entries and their function.

1. New Workspace - Create a new empty workspace.
2. Open Workspace... - Load an existing workspace.
3. Save Workspace - Save the current workspace.
4. Network Mode - Switch to network mode.
5. Application Mode - Switch to application mode.
6. Processors - Hide/show the processor list (only available in network mode).
7. Properties - Hide/show the property view.
8. Volumes - Hide/show information about the currently loaded volume data sets.
9. Debug Console - Hide/show a debug console containing log messages.
10. Input Mapping - Hide/show the currently set input mapping for handling keyboard and mouse events.
11. Render Targets - Hide/show the render target view, which shows intermediate rendering results, useful for debugging.
12. Rebuild Shaders - Rebuild all currently load shader programs, which allows runtime shader editing with external programs.
13. Snapshot - Save the content of one of the canvases or the network to an image file.
14. Animation - Create animations using camera paths and save these animations as videos.

Canvas Interaction

Within each canvas you can rotate the camera by moving the mouse in the window while pressing the left mouse button. Using the mouse wheel or moving the mouse up and down while pressing the right mouse button zooms the visualization. Pressing SHIFT and the left button moves the scene.

Properties

Properties are used to configure the selected processor. Changes become visible immediately in the rendering output. The visibility of each property in the application mode can be configured via the application mode configuration under Tools -> Application Mode Config while in network mode. By default, properties are not visible in application mode. In the application mode configuration, property groups can be created and properties can be added to these groups. The numbers in the application mode configuration for the individual properties are used to determine the order in which the properties appear in the application mode within the property group.

Processor List

The processor list displays all available processors that can be used to build networks. You can search for processors by typing in the text box at the top. Furthermore, you can sort the list using the tool drop-down button, and the current code state of each processor is indicated by the colored dot. The text box in the bottom shows a brief description of the processor functionality.

Loading Data Sets

To load a data set, select the VolumeSource processor in the network and click on the load volume button. After choosing a data file, the volume will be automatically loaded and integrated into the render path.

Render Target View

The render target view can be used to inspect intermediate rendering results. A left-click enlarges a texture; a second click shrinks it again. With the context menu, alpha-channels and depth buffers can be accessed.

---

Network Editor

The network editor is a graphical interface for the creation and modification of Voreen networks in a simple and intuitive way.

Main Components

The editor has about 20 different items the user can interact with. The most important ones will be explained here.

Processors

The image shows, from left to right, an unselected processor, a processor over which the mouse cursor is hovering, and aprocessor which was selected by mouse click in the editor.

A processor can have several kinds of ports: inports are located on the upper side of each processor item, outports are found on the lower side. Coprocessor inports are placed on the left and coprocessor outports on the right. The color of a port indicates its type. In general, only ports of the same color (i.e., the same type) can be connected.

The symbol in the right corner of a processor indicates an extra processor widget, e.g., the canvas of the canvas processor. These widgets can be toggled by clicking this symbol.

A processor can have three different states: "ready", "not ready", and "not initialized" as seen from left to right in the image above.

State	Visual Highlighting	Meaning
ready	no sign	The processor is ready to use. The process() function will be called during network evaluation.
not ready	yellow warning sign	The isReady() function returns false. The process() function will not be called during evaluation, and the processor will not work properly. By default, this state indicates not connected ports of the processor or missing input data and can be fixed by connecting the missing ports.
not initialized	red warning sign	The initialize() function of the processor has not been called yet or has thrown an exception. After loading a network, each processor begins in this state. If the initialization fails, it remains in this state. It indicates an error (e.g., not compiled shaders) which makes proper functioning of the processor impossible. This state can normally not be fixed in the editor.

For more information on the specific processor functions mentioned in the table see [INSERT LINK TO PROGRAMMING TUTORIALS]

A processor can be renamed by selecting the processor and pressing F2 or by using the context menu by right-clicking with the mouse on the processor item. The new name has to be unique in the network; otherwise, Voreen will add a number to the name.

Properties

Properties of a processor are displayed by simple white rectangles with the property's name and its type written on them. To learn more about properties and how to interact with them, see Linking Layers.

Connections

Connections can exist between ports and between properties. Normally, they are directed, indicated by an arrowhead on one side. An arrowhead on both sides represents a bidirectional connection.

Like processors, connections can be unselected, hovered, or selected. In most cases, a color change informs the user if a connection can be made. Green means a connection is possible, whereas red indicates a connection is not possible. A yellow arrow is used for connections that can be created, but only with some modifications.

Navigation

The navigation in the network editor has been optimized since Voreen 4.1 to have better control by using two navigation modes in the upper left of the editor.

In arrow mode, items can be selected, processors can be moved, and connections can be built. This is the normal mode to modify and interact with the network.

To move the whole network, the hand cursor (button two) can be used. Alternatively, pressing Shift in the arrow mode will have the same result. In this mode, no interaction with the network is possible. The arrow keys of the keyboard areanother option to navigate.

When the network becomes bigger, it is necessary to zoom out. This can be achieved by using the + and - keys of the keyboard or by using the mouse wheel.

Layouting

The two buttons in the lower left of the editor are used to arrange the network items. By clicking the first button the network will be centered so that every processor of the network is visible on the screen. It is useful to get an overview of the entire network.

With Voreen 4.4 a new feature has been implemented to arrange the network processors automatically. Clicking the second button will heuristically arrange the network as shown in the example below.

The user can change parameters of the heuristic in Options -> Settings -> Network Editor. Subnetworks can be arranged by selecting the processor items to sort and open the context menu by right clicking the mouse and selecting "Sort Subnetwork".

Data Flow Layer

This is the main layer to build and modify a Voreen network. This layer is the default layer after starting Voreen. It can be selected by clicking the left button of the two buttons in the upper right corner.

In order to build a network, you can simply add new processors by dragging them from the Processor List into the network editor. Processors can be connected via their different ports, however the port types have to match (different types are identifiable by their colors).

Ports are connected by pressing the left mouse button over an outport (located on the lower side of a processor) and dragging the appearing arrow to an inport (on the upper side of a processor). The arrow indicates whether a connection to the inport at the current mouse position is possible or not by changing its color to green respective red. Releasing the mouse button over a valid inport (green arrow) creates a connection.

Only in this layer processor items are movable.

Linking Layers

Beside the Data Flow Layer this layer is the second main layer. It is divided into three sub layers, which are explained beneath. All sub layers allow linking of properties.

Linking properties means to synchronize their values. If a property changes its value, the changed value will be propagated along the link in the indicated direction. For instance, a change of the left option property called Slice Alignment will set the value of the right option property but not the other way round. If a link is bidirectional the properties are completely synchronized. In general all camera properties are linked bidirectionally to guarantee the same camera settings for all renderings in the network.

Normally only properties of the same type can be linked. Properties of different types, e.g. camera and boolean, cannot be linked. An exception are properties that can be converted. For example, an integer property can be linked to a bool property by simple casting.

General Linking

This layer can be used to link properties and see which properties have already been linked. By double-clicking a processor or clicking the small button in the upper left corner of the processor item a list of all linked properties of this processor will appear with connections to their linked properties.

By pressing the left mouse button over a processor and dragging the appearing connection to another processor a new dialog will pop up.

In this dialog all properties of the two processors and their ports can be seen. By clicking a property and dragging the appearing arrow to a property of the other processor a new link can be created. The color of the arrow indicates if a link between these properties is possible (see Connection). If the dialog is not closed via the ok button all changes will be discarded.

To keep the layer from becoming cluttered, the most common property links (i.e., camera and render size links) are hidden. They can be shown by clicking on the first two buttons. The third button simply deletes all existing property links.

Camera Linking

This layer has the same functionality as the general linking layer except for the limitation to camera properties. Here, only processors with cameras can be selected and linked.

The first button toggles the auto camera linking, which is enabled by default. If a new processor is added to the networkand auto camera linking is enabled all camera properties of this processor will be linked bidirectionally to all other camera properties of the network.

The second button links all camera properties. So, if the auto linking is disabled, the user can control when the linking should take place.

The last button simply removes all camera property links.

All these actions can also be used on a selection of processors using the context menu.

Render Size Linkin

This layer was designed to get an easy management of render size links. All render ports with a size origin property or size receive property are highlighted in this layer. Origins are red and receiver are green. Like connecting ports in theData Flow Layer two properties can be linked. A render size link should always go from an origin to a receiver (red to green). It is also possible to connect origin with origin and receiver with receiver. Connections from receiver to origin are not possible.

Like in the Camera Layer the first button controls the auto linking. If it is enabled each render port of a new processor will be linked automatically. If the linking cannot be done automatically the user will be informed by a warning in the debug console.

The second button links all render size properties manually.

The third button removes all render size links from the network.

All actions can also be controled by the context menu.

Stop Evaluator

The button in the lower right corner of the editor indicates whether or not the network evaluator is enabled. By clicking pause the evaluator will be disabled and the render path will be stopped. It can be useful if connections are reconnected and expensive computations would be triggered. By clicking play the network will be evaluated again.

---

Your First Workspace in Voreen

Voreen provides a flexible framework for creating dataflows (also referred to as data pipelines) tailored to your specific application. You can start building these in one of two ways:

• From scratch: Manually add and configure all necessary components, which requires familiarity with Voreen's processors but offers maximum flexibility.
• Using sample workspaces: Begin with one of Voreen's predefined examples and adapt it to your needs. This approach is more accessible but may require finding a sample that closely aligns with your goals.

Building a Pipeline from Scratch

To create a simple pipeline, use the following processors: VolumeSource, SliceViewer, and Canvas. These components together create a straightforward dataflow:

In this setup:

• VolumeSource: Loads the dataset.
• SliceViewer: Processes the data and provides customizable properties.
• Canvas: Generates a visual output.

Example

To load a dataset:

1. Access the properties of VolumeSource.
2. Navigate to Load Volume → Select walnut.vvd.

This pipeline renders a visual output of the loaded dataset. For instance, loading walnut.vvd produces the following result:

Expanding the Pipeline

You can enhance the pipeline by incorporating additional processors. For example:

• Adding Background allows customization of the background color.
• Using Splitter enables handling multiple datasets simultaneously.

The resulting pipeline might look like this:

Building a Pipeline Using Samples

Voreen also provides predefined sample workspaces, which can be accessed via:

File → Open Workspaces → Workspaces

For example, opening the rendering-raycasting sample workspace yields the following layout:

Adapting the Workspace

Suppose you want to visualize flow data with a specific mask. You can modify the rendering-raycasting workspace as follows:

1. Change the Data Source:
   In VolumeSource, replace nucleon.vvd with aneurysm.vvd.

2. Integrate Vector Magnitude:
   Add the VectorMagnitude processor after VolumeSource and enable it in its properties to combine the dataset's three channels into one.

3. Adjust the Raycaster:
   In the SingleVolumeRaycaster properties:

   • Change Level of Detail to Advanced.
   • Set Color Maps Presets to Hot Metal.
   • Switch Compositing Output 1 from DVR to MIP.

After these adjustments, the workspace might look like this:

Adding a Mask to the Pipeline

To combine the dataflow with a mask dataflow, follow these steps:

1. Add the following processors:

   • VolumeSource (for the mask)
   • IsosurfaceExtractor
   • GeometryRenderer
   • GeometryProcessor
   • Splitter

   Combine them in the order listed, connecting the second input of the Splitter to the SingleVolumeRaycaster.

2. Load aneurysm-mask.vvd into the new VolumeSource.

3. Configure the new processors:

   • In IsosurfaceExtractor, set Isovalue to 0.04.
   • In GeometryRenderer, choose a color and enable lighting.
   • In Splitter, enable Overlay and select a grid color.

The final output will look like this:

You can drag the black line in the canvas to adjust the view, revealing either the surface or the magnitudes.

---

This guide provides a solid foundation for getting started with Voreen workspaces, whether building pipelines from scratch or leveraging sample workspaces. Experimentation is encouraged to tailor the workflows to your specific needs.