diff --git a/Core/Documentation/Doxygen/Concepts/Overlays.dox b/Core/Documentation/Doxygen/Concepts/Overlays.dox index 945be37fba..f76f183c32 100644 --- a/Core/Documentation/Doxygen/Concepts/Overlays.dox +++ b/Core/Documentation/Doxygen/Concepts/Overlays.dox @@ -1,112 +1,146 @@ /** \page OverlaysPage Overlays and Annotations Concepts \tableofcontents \section OverlaysPage_Introduction Overlays and Annotations The Overlays in mitk are a simple way to display additional information on the render windows.
  1. Definition of graphical elements that can be displayed in the render windows.
  2. It is possible to manage multiple elements in each window. An element is automaticly added in all available render windows.
  3. 2D and 3D textelements are already defined and are using vtk to create custom annotations. 3D elements can be placed in the coordinate system and are always visible for the camera.
\section ArchitectureSection General Architecture \dot digraph linker_deps { node [shape=record, fontname=Helvetica, fontsize=10]; BR [ label="BaseRenderer" ]; BL [ label="{BaseLayouter|+ArrangeOverlays()}" ]; O [ label="{Overlay|-PropertyList|+UpdateOverlay(BaseRenderer)}" ]; OM [ label="{OverlayManager|+AddOverlay()\n+RemoveOverlay()}" ]; TO [ label="TextOverlay" ]; VTKO [ label="{vtkOverlay|GetVtkActor()}" ]; TO -> VTKO; VTKO -> O; OM -> O [style="dashed",label="manages"]; OM -> BL [style="dashed"]; OM -> BR [style="dashed"]; BR -> OM [style="dashed"]; } \enddot The mitkOverlay can be implemented using a custom rendering framework. In this diagram, the vtkOverlay is shown as the superclass for all Overlays which use the vtk framework for rendering. The OverlayManager is a microservice that 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. \section UsageSection Usage of Predefined Overlays \subsection TextWidget2DUsageSection mitkTextOverlay2D \code //The BaseRenderer is only needed to set a layouter mitk::BaseRenderer* axialRenderer = mitk::BaseRenderer::GetInstance(this->GetRenderWindowPart()->GetRenderWindow("axial")->GetRenderWindow()); //This fetches an instance of the OverlayManager microservice mitk::OverlayManager::Pointer overlayManager = mitk::OverlayManager::GetServiceInstance(); mitk::TextOverlay2D::Pointer textOverlay; //Create a textOverlay2D textOverlay = mitk::TextOverlay2D::New(); textOverlay->SetText("Test!"); //Position is committed as a Point2D Property 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()); //Set a Layouter to the overlay. If the Layouter is custom it has to be added to the OverlayManager first. overlayManager->SetLayouter(textOverlay.GetPointer(),mitk::Overlay2DLayouter::STANDARD_2D_BOTTOM,axialRenderer); \endcode \subsection TextWidget3DUsageSection mitkTextOverlay3D \code //This fetches an instance of the OverlayManager microservice mitk::OverlayManager::Pointer om = mitk::OverlayManager::GetServiceInstance(); mitk::PointSet::Pointer ps = mitk::PointSet::New(); //Just a loop to create some points for(int i=0 ; i < 10 ; i++){ //To each point, a TextOverlay3D is created mitk::TextOverlay3D::Pointer to3d = mitk::TextOverlay3D::New(); mitk::Point3D point; point[0] = i*20; point[1] = i*30; point[2] = -i*50; ps->InsertPoint(i, point); to3d->SetText("A Point"); //The Position is set to the point coordinate to create an annotation to the point in the PointSet. to3d->SetPosition3D(point); om->AddOverlay(to3d.GetPointer()); } mitk::DataNode::Pointer dn = mitk::DataNode::New(); dn->SetData(ps); dn->SetName("pointSet"); GetDataStorage()->Add(dn); \endcode \subsection NotManagedSection Manually Managed Overlays The use of an OverlayManager is not required to render an overlay. If you decide to manage an Overlay by yourself, for example if it was integrated into a mitkMapper, you have to call the UpdateOverlay yourself. it must only be called if the Properties have changed or if your custom overlay implements its own rendering mechanism. \section CustomOverlaySection 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: +\code +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("Position3D", position3D, renderer); + return position3D; +} +\endcode + \subsection CustomVTK2DOverlay VTK 2D Overlay +The mitkVtkOverlay2D is a subclass of VtkOverlay, 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. + \subsection CustomVTK3DOverlay VTK 3D Overlay +The mitkVtkOverlay3D works just like mitkVtkOverlay2D, but it is designed for arbitrary 3D objects which derive from vtkProp, + \section CustomLayouterSection 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: + +\code +overlayManager->SetLayouter(textOverlay.GetPointer(),mitk::Overlay2DLayouter::STANDARD_2D_BOTTOM,axialRenderer); +\endcode + +A new Layouter has to implement PrepareLayout which should parse the internal Overlay list and set their position as required. */