Help for MARSUVWROT

PURPOSE:

MARSUVWROT rotates the vectors in a surface normal (or xyz) file, generating
a new surface normal (or xyz) file.  It can also be used to change coordinate
systems for a surface normal (or xyz) file without rotating it.

The original intent of this program was to assist with effort to find a
winter haven for Spirit in Jan. 2010.  The rotation simulated the effect
of having some of the wheels under the nominal ground surface (as the rover
dug itself in).  Having wheels dug in creates a rotational offset between
the true solar panel orientation and the nominal orientation assuming the
rover is on the surface.  It is assumed that as the rover makes progress,
the wheels stay submerged.

However, the program is more general purpose than that.  The USE_CURRENT
and NOMINAL_UVW parameters are somewhat tailored for this scenario, but
the other parameters are general-purpose.

The input for MARSUVWROT is a UVW image such as that created by the MARSUVW
program (typically with the -slope option, for the Sprit usage), and a set
of parameters to specify the rotation (see below).  The UVW file can be a
single 3-band file or three 1-band files; see MARSUVW for details.

The output of MARSUVWROT 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 this has not been implemented.

Note, with the -XYZ option this program will work with XYZ inputs instead
of UVW.  The only difference is in how coordinate system transforms are done
(if needed), the use of ROT_ORIGIN, and in the output label.  Thus an XYZ
image can be rotated as well.  The rotation happens around the origin unless
ROT_ORIGIN is specified.

EXECUTION:

marsuvwrot inp=data.uvw out=rot.uvw axis=\(0, 0, -1\) angle=20.0
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 (or XYZ) to the frame specified by COORD et al, if necessary.
This should be the site frame for the Spirit case.

* Compute a composite quaternion combining all three rotation options (see
below).

* Rotate the UVW vectors by the rotation quaternion.  For XYZ, the origin is
subtracted off before the rotation and added again afterwards.

* Normalize the result to make sure it's still a unit vector.

SPECIFYING ROTATIONS:

There are five methods by which rotations can be specified: Current,
Axis-angle, Euler angles, Vector Difference, and Quaternion.  These are
applied in order, so the Current rotation is first, followed by Axis-angle,
then Euler, then Vector Difference, and finally Quaternion.  Any number of
these may be specified (including none); they are composited to get the final
rotation.

Be careful which coordinate system you specify things in!  The Current
method is hard-coded to use Site and Rover.  All the others are specified
using the frame named in ROT_COORD.

Current

This method is tailored to the Spirit case.  Turn this on via -USE_CURRENT.
The NOMINAL_UVW parameter must also be specified.

The nominal uvw (in Site frame) is compared to the current rover orientation
(derived from the Rover frame of the label).  The difference between the two
represents the off-nominal tilt, i.e. how far under ground the rover is.  This
difference is the rotation to be used.  The theory is, if the current sinkage
is maintained, this represents the appropriate rotation.

The nominal uvw ideally is derived from a slope UVW file taken before the
rover got to its current spot.  Where the rover now is in that image, is the
appropriate surface normal to use.  Be careful of coordinate systems:  it must
be Site frame (slope normals are generated in Site).

Axis-Angle

This allows you to specify an arbitrary rotation.  Provide an axis (a unit
vector) around which the rotation is to happen, and an amount of rotation
(the angle, in degrees).  These are all specified using the ROT_COORD frame
(typically Rover).

Euler Angles

This allows you to specify roll, pitch, and yaw values (in degrees).  The
values are expressed in the ROT_COORD frame.  This should normally be Rover.
Using Site frame to specify these will result in yaw becoming azimuth and
pitch becoming elevation (potentially useful), but roll is simply defined
as a rotation around +X, which points north (not so useful).

Vector Difference

This allows you to specify two vectors, with the rotation computed as necessary
to transform the first into the second.  This rotation is computed as an
axis-angle where the axis is defined by the cross product between the vectors
and the angle is defined by the dot product between them.

Quaternion

This allows you to directly specify a rotation quaternion.  The quaternion
should be expressed in the ROT_COORD frame.  Note that the quaternion is
specified in Ground order (scalar first).

USING MULTIPLE COORDINATE FRAMES

It is important to realize that the Rover coordinate frame, if in use, is
the Rover frame associated with the input image.  There is no way to specify
a rover frame at a different RMC (perhaps an item for future enhancement).
Similarly, the current position for -USE_CURRENT is derived using the given
input image.

It is possible though to use a different location.  Take for example the
Spirit case.  You may want to use the rover's current position as of tosol,
but apply that to images taken by the navcam before the rover got stuck.
Doing this is a two-step process.

1) Use an image from the current location, and specify the rotation as you
wish.  Make sure to specify -site so the output will be in Site frame.  It
will report the final quaternion, including the axis-angle breakdown, to the
terminal output.  Discard the output file.

2) Run the program a second time.  Use the earlier image (the one you want
to make a map from) as the input image.  For the rotation, use the axis-angle
or quaternion methods and provide the values obtained from step 1.  Make sure
to say ROT_COORD=SITE.  The output will then contain the desired result.

A future enhancement would obviously be to support multiple frames, or
multiple input images (one for current and one for the actual surface normal).
That may be considered if this program sees a lot of use.  For now, this seems
actually less confusing.

COGNIZANT PROGRAMMER: B. Deen
HISTORY:
  2010-01-08 B. Deen - Initial version.
  2013-01-10 B. Deen - Added XYZ and support for vector-diff and quaternion input.
  2020-05-26 W. Bunch - Replaced sprintf calls. Added unit test. Removed unused variables.

PARAMETERS: