[vtkusers] New corner marker classes

[Dean Inglis]

Hi all,

I have added three new classes to VTK for viewing/placing
orientation markers in a scene.  The two markers are
vtkAxesActor, based on Paraview's vtkPVAxesActor,
and vtkAnnotatedCubeActor which looks pretty much like
the corner annotation marker seen in VolView 2 but
uses vtkVectorText ivars for the face text.

Either of these markers can be added to a widget that
affords interactive manipulation of the placement and size
of the marker in addition to causing the camera view of the
marker to match that of the camera view of a main renderer's
scene: vtkOrientationMarkerWidget, which is again based on
a Paraview class (vtkPVAxesWidget).  The implementation of
this widget is such that combinations of markers can be added
to the widget or, in general, any vtkProp with symmetric
bounds.

Although the marker classes and widget were added sometime
last week, I have submitted a test for them today.
To view the test, change to the root directory of your
VTK build and do:
path_to_cmake/bin/ctest -R TestOrientationMarkerWidget

Any and all feedback are, as always, welcome.
enjoy!
Dean

// .NAME vtkAxesActor - a 3D axes representation
// .SECTION Description
// vtkAxesActor is a hybrid 2D/3D actor used to represent 3D axes in a
scene.
// The user can define the geometry to use for the shaft or the tip, and the
// user can set the text for the three axes. The text will appear to follow
the
// camera since it is implemented by means of vtkCaptionActor2D.  All of the
// functionality of the underlying vtkCaptionActor2D objects are accessible
so
// that, for instance, the font attributes of the axes text can be
manipulated
// through vtkTextProperty. Since this class inherits from vtkProp3D, one
can
// apply a user transform to the underlying geometry and the positioning of
the
// labels. For example, a rotation transform could be used to generate a
// left-handed axes representation.

// .SECTION Thanks
// Thanks to Goodwin Lawlor for posting a tcl script which featured the
// use of vtkCaptionActor2D to implement the text labels.  This class is
// based on Paraview's vtkPVAxesActor.

// .SECTION Caveats
// vtkAxesActor is primarily intended for use with
vtkOrientationMarkerWidget.
// The bounds of this actor are calculated as though the geometry of the
axes
// were symmetric: that is, although only positive axes are visible, bounds
// are calculated as though negative axes are present too.  This is done
// intentionally to implement functionality of the camera update mechanism
// in vtkOrientationMarkerWidget.
----------------------------------------------------------------------------
-----
// .NAME vtkAnnotatedCubeActor - a 3D cube with face labels
// .SECTION Description
// vtkAnnotatedCubeActor is a hybrid 3D actor used to represent an
anatomical
// orientation marker in a scene.  The class consists of a 3D unit cube
centered
// on the origin with each face labeled in correspondence to a particular
// coordinate direction.  For example, with Cartesian directions, the user
// defined text labels could be: +X, -X, +Y, -Y, +Z, -Z, while for
anatomical
// directions: A, P, L, R, S, I.  Text is automatically centered on each
cube
// face and is not restricted to single characters. In addition to or in
// replace of a solid text label representation, the outline edges of the
labels
// can be displayed.  The individual properties of the cube, face labels
// and text outlines can be manipulated as can their visibility.

// .SECTION Caveats
// vtkAnnotatedCubeActor is primarily intended for use with
// vtkOrientationMarkerWidget. The cube face text is generated by
vtkVectorText
// and therefore the font attributes are restricted.
----------------------------------------------------------------------------
-----
// .NAME vtkOrientationMarkerWidget - 2D widget for manipulating a marker
prop
// .SECTION Description
// This class provides support for interactively manipulating the position,
// size, and apparent orientation of a prop that represents an orientation
// marker.  This class works by adding its internal renderer to an external
// "parent" renderer on a different layer.  The input orientation marker is
// rendered as an overlay on the parent renderer and, thus, appears
superposed
// over all props in the parent's scene.  The camera view of the orientation
// the marker is made to match that of the parent's by means of an observer
// mechanism, giving the illusion that the orientation of the marker
reflects
// that of the prop(s) in the parent's scene.
//
// The widget listens to left mouse button and mouse movement events. It
will
// change the cursor shape based on its location. If the cursor is over the
// overlay renderer, it will change the cursor shape to a SIZEALL shape
// or to a resize corner shape (e.g., SIZENW) if the cursor is near a
corner.
// If the left mouse button is pressed and held down while moving, the
overlay
// renderer, and hence, the orientation marker, is resized or moved.  I the
case
// of a resize operation, releasing the left mouse button causes the widget
// to enforce its renderer to be square.  The diagonally opposite corner to
the
// one moved is repositioned such that all edges of the renderer have the
same
// length: the minimum.
//
// To use this object, there are two key steps: 1) invoke SetInteractor()
with
// the argument of the method a vtkRenderWindowInteractor, and 2) invoke
// SetOrientationMarker with an instance of vtkProp (see caveats below).
// Specifically, vtkAxesActor and vtkAnnoatedCubeActor are two classes
// designed to work with this class.  A composite orientation marker can be
// generated by adding instances of vtkAxesActor and vtkAnnoatedCubeActor to
a
// vtkPropAssembly, which can then be set as the input orientation marker.
// The widget can be also be set up in a non-interactive fashion by setting
// Interactive to Off and sizing/placing the overlay renderer in its parent
// renderer by calling the widget's SetViewport method.