Overlays and Annotations

The overlays in MITK are a simple way to display additional information on the render windows. A class, deriving from mitk::Overlay represents an arbitrary 2D or 3D object that can be rendered as an overlay. This can for example be used for the annotation of 3D points or to overlay despriptions in the window corners. The mitk::OverlayManager is used to add the overlays to the renderwindows, updating them and manage the respective layout managers. The following features are implemented in this framework.

Definition of graphical elements that can be displayed in the render windows.
It is possible to manage multiple elements in each window.
A single Overlay can be rendered on any number of available render windows.
2D and 3D textelements are already defined in the Overlay module and are using VTK to create custom annotations.
The mitk::BaseLayouter interface enables the implementation of layout managers, to handle the placement of the overlays.

General Architecture

The mitk::Overlay can be implemented using a custom rendering framework like VTK. In this diagram, the vtkOverlay is shown as the superclass for all Overlays which use the vtk framework for rendering. The OverlayManager can be registered to several BaseRenderer instances in order to call the update method of each Overlay during the rendering phase of the renderer. It also manages the respective Layouters which are used to manage the placement of a group of Overlays.

Overlay

The mitk::Overlay is an abstract class that can manage property lists like the mitk::DataNode and provides the interfaces to thr three methods mitk::Overlay::AddOverlay, mitk::Overlay::UpdateOverlay and mitk::Overlay::RemoveOverlay. The subclasses of the mitk::Overlay have to implement these methods in order to provide the functionallity of an overlay. There are already a few implementations of mitk::Overlay which are using VTK as a rendering framework to display the Overlays. However the mitk::Overlay can also be implemented using OpenGL to draw the Overlay on the renderwindows.

OverlayManager

The mitk::OverlayManager is the manager for a set of Overlays and the respective Layouters. Before the manager can be used, all mitk::BaseRenderer have to be registered to the mitk::OverlayManager instance like this:

  mitk::OverlayManager::Pointer OverlayManagerInstance = mitk::OverlayManager::New();
  mitk::BaseRenderer *renderer = mitk::BaseRenderer::GetInstance(renderWindow.GetVtkRenderWindow());
  renderer->SetOverlayManager(OverlayManagerInstance);

The mitk::OverlayManager can then be used anywhere in the program by fetching it as follows:

  // The id that is passed identifies the correct mitk::OverlayManager and is '0' by default.
  mitk::BaseRenderer *renderer2D = mitk::BaseRenderer::GetInstance(renderWindow.GetVtkRenderWindow());
  mitk::OverlayManager::Pointer overlayManager = renderer2D->GetOverlayManager();

All mitk::Overlay instances can now be added to the OverlayManager by calling mitk::OverlayManager::AddOverlay.

Layouter

In order to use Layouters for the positioning of the Overlays, each Layouter object that has been created has to be added to an internal list in the OverlayManager:

  // This creates a 2DLayouter that is only active for the recently fetched axialRenderer and positione
  mitk::Overlay2DLayouter::Pointer topleftLayouter =
    mitk::Overlay2DLayouter::CreateLayouter(mitk::Overlay2DLayouter::STANDARD_2D_TOPLEFT(), renderer2D);
  // Now, the created Layouter is added to the OverlayManager and can be referred to by its identification string.
  overlayManager->AddLayouter(topleftLayouter.GetPointer());
  // Several other Layouters can be added to the overlayManager
  mitk::Overlay2DLayouter::Pointer bottomLayouter =
    mitk::Overlay2DLayouter::CreateLayouter(mitk::Overlay2DLayouter::STANDARD_2D_BOTTOM(), renderer2D);
  overlayManager->AddLayouter(bottomLayouter.GetPointer());

The mitk::OverlayManager::SetLayouter method can then be used to configure an Overlay to be positioned by a certain Layouter:

// Because a Layouter is specified by the identification string AND the Renderer, both have to be passed to the call.

overlayManager->SetLayouter(textOverlay.GetPointer(), mitk::Overlay2DLayouter::STANDARD_2D_TOPLEFT(), renderer2D);

Manually Managed Overlays

In order to integrate an Overlay into an mitk::Mapper, it is advised not to use the OverlayManager but to manually manage the Overlay. To do so, the update methods of the overlays have to be called manually before the start of each rendering procedure. It must only be called if the Properties have changed or if your custom overlay implements its own rendering mechanism.

Implement a Custom Overlay

A new custom Overlay should derive from mitkOverlay or one of the later mentioned subclasses VtkOverlay2D oder VtkOverlay3D. There should always be an implementation for the methods AddOverlay, RemoveOverlay and Update Overlay. UpdateOverlay is the procedure that is called in each rendering step. If the Overlay is rendered by VTK, this method only applies the properties to the representation. If the custom Overlay requires additional properties, they should be made accessible by getters and setters for a better usability:

void mitk::VtkOverlay3D::SetPosition3D(Point3D position3D, mitk::BaseRenderer *renderer)
{
  mitk::Point3dProperty::Pointer position3dProperty = mitk::Point3dProperty::New(position3D);
  SetProperty("Position3D", position3dProperty,renderer);
}
mitk::Point3D mitk::VtkOverlay3D::GetPosition3D(mitk::BaseRenderer *renderer)
{
  mitk::Point3D position3D;
  GetPropertyValue<mitk::Point3D>("Position3D", position3D, renderer);
  return position3D;
}

VTK 2D Overlay

VTK based overlays which are meant to be displayed in 2D over the render window should derive from the mitk::VtkOverlay2D. The mitk::VtkOverlay2D is a subclass of Vtk::Overlay, that uses VTK to render the overlay. This class creates the Overlay representation as a vtkActor2D, and is very easy to implement because only UpdateVtkOverlay2D and GetVtkActor2D have to be implemented. The add, update and remove methods are implemented in the superclasses. UpdateVtkOverlay2D only needs to apply the specific properties and GetVtkActor2D simply returns the created vtkActor.

VTK 3D Overlay

The mitkVtkOverlay3D works just like mitkVtkOverlay2D, but it is designed for arbitrary 3D objects which derive from vtkProp,

Implement a Custom Layouter

A Layouter is used for an automatic positioning of a group of Overlays and is derived from mitkBaseLayouter. Every Layouter that manages a group of Layouts should have a unique identifier which is used to register the Layouter in the OverlayManager. A Layouter is always uniquely defined by the identifier and one BaseRenderer. Before a Layouter can be used by the OverlayManager it has to be added, using the AddLayouter Method. An Overlay can then be added to a Layout as follows:

overlayManager->SetLayouter(textOverlay.GetPointer(),mitk::Overlay2DLayouter::STANDARD_2D_TOPLEFT,axialRenderer);

A new Layouter has to implement PrepareLayout which should parse the internal Overlay list and set their position as required.

Table of Contents