Overlays and Annotations Module

Table of Contents

• Overlays and Annotations
• General Architecture
• Usage of Predefined Overlays
  • mitkTextOverlay2D
  • mitkTextOverlay3D
  • Manually Managed Overlays
• Implement a Custom Overlay
  • VTK 2D Overlay
  • VTK 3D Overlay
• Implement a Custom Layouter

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.

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

General Architecture

Usage of Predefined Overlays

mitkTextOverlay2D

This exemplary overlay can render UTF-8 encoded text as a 2D Overlay. The Overlay2DLayouter can be used to automatically place a group of overlays to a specific corner.

  // Create a textOverlay2D
  mitk::TextOverlay2D::Pointer textOverlay = mitk::TextOverlay2D::New();

  textOverlay->SetText("Test!"); // set UTF-8 encoded text to render
  textOverlay->SetFontSize(40);
  textOverlay->SetColor(1, 0, 0); // Set text color to red
  textOverlay->SetOpacity(1);

  // The position of the Overlay can be set to a fixed coordinate on the display.
  mitk::Point2D pos;
  pos[0] = 10, pos[1] = 20;
  textOverlay->SetPosition2D(pos);

  // Add the overlay to the overlayManager. It is added to all registered renderers automaticly
  overlayManager->AddOverlay(textOverlay.GetPointer());

  // Alternatively, a layouter can be used to manage the position of the overlay. If a layouter is set, the absolute
  // position of the overlay is not used anymore
  // The Standard TopLeft Layouter has to be registered to the OverlayManager first
  overlayManager->AddLayouter(
    mitk::Overlay2DLayouter::CreateLayouter(mitk::Overlay2DLayouter::STANDARD_2D_TOPLEFT(), renderer2D).GetPointer());

  // 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);

mitkTextOverlay3D

This overlay displays labels in 3D coordinates. The labels always face the camera.

  mitk::PointSet::Pointer pointset = mitk::PointSet::New();

  // This vector is used to define an offset for the annotations, in order to show them with a margin to the actual
  // coordinate.
  mitk::Point3D offset;
  offset[0] = .5;
  offset[1] = .5;
  offset[2] = .5;

  // Just a loop to create some points
  for (int i = 0; i < 10; i++)
  {
    // To each point, a TextOverlay3D is created
    mitk::TextOverlay3D::Pointer textOverlay3D = mitk::TextOverlay3D::New();
    mitk::Point3D point;
    point[0] = i * 20;
    point[1] = i * 30;
    point[2] = -i * 50;
    pointset->InsertPoint(i, point);
    textOverlay3D->SetText("A Point");

    // The Position is set to the point coordinate to create an annotation to the point in the PointSet.
    textOverlay3D->SetPosition3D(point);

    // move the annotation away from the actual point
    textOverlay3D->SetOffsetVector(offset);

    overlayManager->AddOverlay(textOverlay3D.GetPointer());
  }

  // also show the created pointset
  mitk::DataNode::Pointer datanode = mitk::DataNode::New();
  datanode->SetData(pointset);
  datanode->SetName("pointSet");
  dataStorage->Add(datanode);

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.