Refactoring of Mapper Architecture

Migration guide

The general description of the rendering pipeline and the integration of MITK into the VTK rendering concept can be found here http://docs.mitk.org/nightly/QVTKRendering.html . MITK supports both VTK and OpenGL rendering. VTK forms an abstract layer above the graphics language (e.g. OpenGL) and ensures cross-platform portability, thus it is desirable to port the exisiting GL-based mapper to VTK. This will be done in a later scope of this plattform project and is not concerned in the following description.

Outdated mapper architecture

By the help of mappers, the input data is transformed to tangible primitives, such as surfaces, points, lines, etc. In Mitk, mitk::Mapper is the base class of all mappers, both Vtk as well as OpenGL mappers. Subclasses of mitk::Mapper control the creation of rendering primitives.

So far, the (now obsolete) structure of the mapper architecture does not follow one clear concept. The differentiation between 2D and 3D mapper becomes obsolete since their classes have never encapsulated common functionalities. It might be desirable to merge 2D and 3D mappers in the future, i.e. not providing extra classes for 2D and 3D mappers of the same data node (such as points, surfaces etc.). However, to merge all mappers is beyond the scope of this project.

New mapper architecture

Applied Changes

The base architecture of the mapper super classes has been refactored in order to simplify the existing class structure. Furthermore, the rules for inheriting methods are not consistent and some methods should not be used in MITK at all.

The following issues have to be dealt with:

1. Introduction of new classes mitk::VtkMapper and mitk::GLMapper. The classes mitk::Mapper2D, mitk::Mapper3D are removed and the classes mitk::VtkMapper2D, mitk::VtkMapper3D and mitkGLMapper2D are marked as deprecated.

2. MitkRenderOpaqueGeometry(), MitkRenderTranslucentGeometry(), MitkRenderVolumetricGeometry(), MitkRenderOverlay() are part of the new base class mitk::VtkMapper. They are automatically inherited in the subclasses of VtkMapper and do not need to be individually reimplemented any longer in each (Vtk)mapper. In the GLMappers, those functions are not needed any longer since their only purpose was to call the Paint() function. Instead, a common function MitkRender() is used therefore.

3. GenerateData() is marked as deprecated. Usage of this method will throw a warning.

4. ApplyProperties() has been renamed to ApplyColorAndOpacityProperties ()

5. The following functions of class mitk::Mapper are only convenience functions and thus marked as deprecated:

<syntaxhighlight enclose="none" lang="cpp">BaseData* GetData() const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool GetColor(float rgb[3], BaseRenderer* renderer, const char* name = "color") const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool GetVisibility(bool &visible, BaseRenderer* renderer, const char* name = "visible") const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool GetOpacity(float &opacity, BaseRenderer* renderer, const char* name = "opacity") const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool GetLevelWindow(LevelWindow &levelWindow, BaseRenderer* renderer, const char* name = "levelwindow") const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool IsVisible(BaseRenderer* renderer, const char* name = "visible") const;</syntaxhighlight>
<syntaxhighlight enclose="none" lang="css">virtual bool IsVtkBased() const = 0;</syntaxhighlight>

Note
For temporary backward compatibility, the outdated methods are still available in the interface of mitk::Mapper, but are marked as deprecated. After one whole release cycle those methods will be deleted.

Step-by-step procedures to replace existing code

What do you need to do to take account of the recent changes in the mapper architecture? If you have written your own mapper, you should go through the following list and apply the proposed changes:

1.) Make your mapper subclass of either mitk::VtkMapper or mitk::GLMapper:

All former child mapper of mitk::VtkMapper2D and mitk::VtkMapper3D should now inherit from the new class mitk::VtkMapper
All former child mapper of mitk::GLMapper2D should now inherit from the new class mitk::GLMapper

2.) Remove the methods MitkRenderOpaqueGeometry(), MitkRenderTranslucentGeometry(), MitkRenderVolumetricGeometry(), MitkRenderOverlay() in your mapper class(es). The according functionalities are provided by the new super classes

3.) Do not reimplement the function GenerateData() any longer, use GenerateDataForRenderer() instead. What you basically need to do is to copy the code from GenerateData() to GenerateDataForRenderer(). (In some cases it might not be that simple).

4.) Replace function call of ApplyProperties(VtkActor * actor, BaseRenderer* renderer) or ApplyProperties(BaseRenderer* renderer) respectively by ApplyColorAndOpacity(BaseRenderer* renderer, VtkActor * actor = NULL). Note that the order of parameter has changed. In the case of a GLMapper you do not need to pass the second argument, since it is not used and NULL by default.

5.) Do not make use of any of the convenience methods provided by the current mitk::Mapper class :

Function call (old style)	Should be replaced it by (new style)
GetData()	GetDataNode()->GetData()
GetColor(rgb,renderer, "color")	GetDataNode()->GetColor(rgb, renderer, „color“)
GetVisibility(visible, renderer, "visible")	GetDataNode()->GetVisiblity(visible, renderer, “visible”)
GetOpacity(opacity, renderer, “opacity”)	GetDataNode()->GetOpacity(opacity, renderer, “opacity”)
GetLevelWindow(levelWindow, renderer, “levelWindow”)	GetDataNode()->GetLevelWindow(levelWindow, renderer, “levelWindow”)
IsVisible(renderer, “visible”)	bool visible = true; GetDataNode()->GetVisiblity(visible, renderer, "visible"); // further evaluate bool visible
IsVtkBased()	VtkMapper* vtkmapper = dynamic_cast<VtkMapper*>( mapper ); if (vtkmapper){...}