Help for MARSUVWPROJ

PURPOSE:

MARSUVWPROJ projects a surface normal onto an arbitrary plane in space.
The result is a normalized 3-D vector which is constrained to lie in the plane.

Currently, the plane can only be a vertical plane, aligned with the X-Z
axes, and then rotated by ANGLE about the +Z axis.  So, a value for ANGLE
of 0 degrees will project to the X-Z plane, while a value of 90 degrees
will project to the Y-Z plane.  Other parameters to specify other rotations
may be added in the future.

The original intent of this program was to deal with the stuck arm joint #1
on Opportunity (Sep. 08).  By providing the joint #1 angle (converted to
degrees, and note that the stuck angle is negative, meaning the plane rotates
to the left), it reduces the available degrees of freedom for the surface
normal.  This helps determine what is reachable with the reduced capability
of the arm.

However, the program is not mission-specific; it can be used in any situation
requiring projection of a surface normal.

The input for MARSUVWPROJ is a UVW image such as that created by the MARSUVW
program, and an angle of rotation (see above).  The UVW file can be a single
3-band file or three 1-band files; see MARSUVW for details.

The output of MARSUVWPROJ is a single 3-band file of type REAL (a surface
normal, like the input).  It should support outputting 3 1-band files as
well, but his has not been implemented.

EXECUTION:

marsuvwproj inp=data.uvw out=proj.uvw angle=-6.777289
where:
data.uvw is an input 3-band image of type REAL with the U, V, and W components
of the unit vector for each pixel.

METHOD:

The algorithm to compute the projection is as follows:

* Convert UVW to the frame specified by COORD et al, if necessary.  This should
be the rover frame for the Opportunity case.

* Construct a rotation quaternion representing a rotation of the specified
angle around the +Z axis.  Other rotations may be supported in the future.

* Rotate the UVW vectors by the negative of the rotation quaternion.  This
aligns the plane with the X-Z plane.

* Zero out the Y component of the normal.  This projects it to the X-Z plane.

* Undo the rotation by using the quaternion.

* Normalize the result to get a unit vector.


HISTORY:
09-22-08  Initial version by B. Deen.
COGNIZANT PROGRAMMER: B. Deen

PARAMETERS: