Display Geometry Interaction Project

From mitk.org
Jump to navigation Jump to search

Summary: Changes on Camera and Interaction Handling in MITK

Motivation for DisplayGeometry / Interaction Legacy removal

The DisplayGeometry [1] is deleted. Its original purposes were:

  • Controller for the vtkCamera in a RenderWindow. The position and the zoom factor was set as a member variable, and the next rendering would transform the camera accordingly. Also it contained a method to calculate the camera parameters so that an object was fitted to the 2D RenderWindow.
  • It provided methods to convert between display coordinates and world coordinates on the image plane.

The goal is to provide the former DisplayGeometry functionalities within existing classes, using vtk code wherever it is possible.

Along the way also the legacy Code of the Interaction has been removed. Since the old code strongly depended on the Display Geometry, these changes were carried out in a single project.

CameraController

CameraController [2] is extended to control the camera in the 2D renderwindows as a convenient interface. It provides the following new functions:

Move camera so that the given point on the plane is in the center of the screen preserving the scale: 

void MoveCameraToPoint(const Point2D &planePoint)

Zooming the camera by the factor, around the given point: 

void Zoom(ScalarType factor, const Point2D &zoomPointInMM)

Zoom and move the camera, so that the whole world geometry is visible: 

void Fit()

Get the current scaling factor: 

ScalarType GetMmPerDisplayUnits()

Adjusts the camera to be orthogonal to the plane. This is called for example, when the plane has been rotated: 

void AdjustCameraToPlane()

There is now only one implementation of the CameraController. All other implementations are deleted. Interactors [3] need to be used instead to apply the movement of any input device to the camera via the CameraController. An example for this concept is the DisplayInteractor [4] which applies certain mouse events as camera transformations (zooming, panning).

BaseRenderer

Methods for converting between display coordinates and world coordinates can now be accessed in the BaseRenderer: 

void DisplayToWorld(const Point2D& displayPoint, Point3D& worldIndex)
void DisplayToPlane(const Point2D& displayPoint, Point2D& planePointInMM)
void WorldToDisplay(const Point3D& worldIndex, Point2D& displayPoint)
void PlaneToDisplay(const Point2D& planePointInMM, Point2D& displayPoint)

Map2DRendererPositionTo3DWorldPosition does the same as DisplayToWorld but is deprecated and should not be used anymore.

Example

The new usage will be 

 renderer->WorldToDisplay(p, pt2d);

to replace the old code 

 displayGeometry->Project(p, projected_p);
 displayGeometry->Map(projected_p, pt2d);
 displayGeometry->WorldToDisplay(pt2d, pt2d);

See the Migration Guide for more code examples.

Legacy Classes

Many legacy classes are removed, e.g. all legacy event handling and some legacy GLMappers (e.g. PlaneGeometryDataGLMapper2D,mitkPointSetGLMapper2D, mitkSurfaceGLMapper2D). Also, the event handling is restructured. The 3D positions are not automatically calculated but only if they are needed.

Migration Guide

Display Geometry

The mitk::DisplayGeometry class is deleted. It was used to store information about the camera orientation and display scaling. All functionality of the DisplayGeometry was moved to either mitk::BaseRenderer or mitk::CameraController.

mitk::BaseRenderer

The following methods were added to mitk::BaseRenderer which allow for a coordinate conversion between the display, world and world plane coordinate system.

This method converts a display point to the 3D world index using the geometry of the renderWindow. 

void DisplayToWorld(const Point2D& displayPoint, Point3D& worldIndex) const;

This method converts a display point to the 2D world index, mapped onto the display plane using the geometry of the renderWindow. 

void DisplayToPlane(const Point2D& displayPoint, Point2D& planePointInMM) const;

This method converts a 3D world index to the display point using the geometry of the renderWindow. 

void WorldToDisplay(const Point3D& worldIndex, Point2D& displayPoint) const;

This method converts a 2D plane coordinate to the display point using the geometry of the renderWindow. 

void PlaneToDisplay(const Point2D& planePointInMM, Point2D& displayPoint) const;

This is a replacement for an old method from mitk::DisplayGeometry which returns the current factor to convert lengths on the display in pixels to the world coordinate system. 

double GetScaleFactorMMPerDisplayUnit() const;

Convenience method to get the current display size in mm. 

Point2D GetDisplaySizeInMM() const;

Convenience method to get the current viewport size in mm. 

Point2D GetViewportSizeInMM() const;

Convenience method to get the current plane coordinates in mm of the display origin. 

Point2D GetOriginInMM() const;

This Method is deprecated. Please use DisplayToWorld instead. 

Point3D Map2DRendererPositionTo3DWorldPosition(const Point2D& mousePosition)


mitk::CameraController

The CameraController has functions for the adjustment and placement of the camera.

Adjust the camera, so that the world bounding box is fully visible. 

void Fit();

Move camera so that the point on the plane is in the view center. 

void MoveCameraToPoint(const Point2D &planePoint);

Move camera by a 2D vector in mm parallel to the display plane 

void MoveBy(const Vector2D &moveVectorInMM);

Zooms the camera by a factor and keeps the passed 2D point zoomPointInMM in the current display position. 

void Zoom(ScalarType factor, const Point2D &zoomPointInMM);

Returns the current camera center, projected onto the PlaneGeometry. 

Point2D GetCameraPositionOnPlane();

Moves the camera of a 2D Renderwindow without panning or zooming, eg. only rotate the camera. 

 void AdjustCameraToPlane();

Code Examples

-    mitk::BaseRenderer::GetInstance(renderwindow)->GetDisplayGeometry()->Fit();
+    mitk::BaseRenderer::GetInstance(renderwindow)->GetCameraController()->Fit();



-  displayGeometry->Project(p, projected_p);
-  displayGeometry->Map(projected_p, pt2d);
-  displayGeometry->WorldToDisplay(pt2d, pt2d);
+  renderer->WorldToDisplay(p, pt2d);


deprecated Map2DRendererPositionTo3DWorldPosition is deprecated. Please use DisplayToWorld instead. 


-  ScalarType gapinmm = gapsize * displayGeometry->GetScaleFactorMMPerDisplayUnit();
+  ScalarType gapinmm = gapsize * renderer->GetScaleFactorMMPerDisplayUnit();



-  ScalarType distance =    displayGeometry->GetWorldGeometry()->SignedDistance(point);
-  ScalarType lastDistance =    displayGeometry->GetWorldGeometry()->SignedDistance(lastP);
+  ScalarType distance = renderer->GetCurrentWorldPlaneGeometry()->SignedDistance(point);
+  ScalarType lastDistance = renderer->GetCurrentWorldPlaneGeometry()->SignedDistance(lastP);



-  dispGeometry->Map(point1, L3D);
+  renderer->GetCurrentWorldPlaneGeometry()->Map(point1, L3D);



-  dispGeometry->Map(point1, L3D);
+  renderer->GetCurrentWorldPlaneGeometry()->Map(point1, L3D);



-  displayGeometry->Project(p, projected_p);
+  renderer->GetCurrentWorldPlaneGeometry()->Project(p, projected_p);

Interaction Legacy

Old Interaction code including the GlobalInteraction has been removed completely, subsequently some functionality only used in this context has been removed. The code deprecated since a while that was deleted includes all StateMachine (not EventStateMachine!) related code such as State/StateEvent/Event/DisplayPositionEvent/etc ...

If you still have code depending on these classes please refer to the migration guide to update your code [1]

\warn The signature of actions has been adapted to return value void, as this value was discarded anyway. This is a breaking change! 


bool FunctioName(StateMachineAction*, InteractionEvent* event);

to 

void FunctioName(StateMachineAction*, InteractionEvent* event);


All remaining Interactors have been migrated to the new interaction scheme.

Base Controller

Base Controller no longer inherits from StateMachine, and the functionality of SliceRotator and SwivelMode were integrated into the DisplayInteractor.

Questions and Answers

Links

[1] http://docs.mitk.org/2014.10/classmitk_1_1DisplayGeometry.html [2] http://docs.mitk.org/2014.10/classmitk_1_1CameraController.html [3] http://docs.mitk.org/2014.10/DataInteractionPage.html [4] http://docs.mitk.org/2014.10/classmitk_1_1DisplayInteractor.html

Retrieved from "http://mitk.org/w/index.php?title=Display_Geometry_Interaction_Project&oldid=2761"