Help for MARSSHOT

PURPOSE:
Simple program to determine where a spectral shot is on an accompanying context
image.

While designed for M2020 SuperCam, there is nothing inherently mission-specific
about this program, other than the instrument name shortcut (which can be
overridden with a specific hotspot location).  It works equally well with
MSL ChecmCam for example, and likely other instruments.

EXECUTION:

marsshot inp=context.img pointing=\(.1 .2\) -scam-libs
- or -
marsshot inp=\(context.img pre.img\) pointing=\(.1 .2\) -ccam-libs -interp

then

set line = `v2param -i 0 image_pos`
set samp = `v2param -i 0 image_pos`

METHOD:
There are two different modes - interp and no interp.  The default (and
simpler case) is no interp.

NO INTERP MODE
----
marsshot takes the given context image, and repoints it to the designated
pointing.  This pointing should be the pointing used when the spectral
observation was taken.  This creates a virtual camera model, as if the mast
(or other device) was pointed as it was for the actual spectral observation.

It then determines the "hotspot", the location where the spectral observation
would be if the context image were taken with the same pointing.  This can be
provided directly via parameter, or using the INSTRUMENT keyword.  In the
latter case, one of the various SuperCam instrument modes is used to look up
the hotspot in an internal table (see INSTRUMENT keyword help below for table).

The hotspot is then projected through the virtual camera model into space.
The ray is intersected with the surface model (default is the infinity model;
the surface model usually shouldn't matter), and then projected back into the
*real* camera model provided as input.  The resulting location is printed to
the screen, as well as provided in output variables that can be accessed via
v2param.

INTERP MODE
----
In interp mode, the program does the same basic thing.  However, you provide
it with TWO context images (generally, one before and one after the shots).
These images should be tiepointed and nav'd together to eliminate (relative)
pointing errors between them.  In other words, make a seam-corrected mosaic
that includes the two images (the nav file can contain more images, but only
the two given are relevant).

The program then looks at both images, both before and after the nav correction
is applied.  It uses that information to interpolate the given location, in
order to apply the pointing corrections to it.

The result is that the shot location is corrected via the pointing adjustments,
so it better matches the images.  The first image is what the image locations
are reported relative to.

Specifically, the interpolation works as follows.  Each pointing parameter is
handled independently.  Pointing parameters are usually azimuth and elevation
for a mast-mounted camera, but that depends on the specific pointing model
used (these pointing parameters are what must be supplied in the POINTING
parameter).

It then computes the ratio:

	ratio = (shot param - raw param 1) / (raw param 2 - raw param 1)

which is used as the interpolation control variable.  Then it computes the
delta pointing parameters given the nav file:

	delta1 = nav param 1 - raw param 1
	delta2 = nav param 2 - raw param 2

It then uses those to compute the final adjusted pointing parameter:

	final = shot param + delta1 + ratio * (delta2 - delta1)

These adjusted pointings are printed out, and then used as with the non-
interp case.

NOTES:

The surface model can be specified if desired, although in normal usage the
infinity camera model is appropriate. That's because there should not be enough
parallax between the two locations for the surface model to matter.

The pointing parameters given are those directly used by the PointingModel
associated with the image.  There is no check that the parameters are
appropriate; the given ones are simply set.  The pointing model and parameters
are printed, so one could run the program without providing any POINTING
parameters (which should return the hotspot value unchanged), see what the
params are, and then provide the proper updates.  For the SuperCam RMI, the
pointing parameters should be (azimuth, elevation) in radians.

While a nav file is not strictly needed for INTERP mode, lack of one negates
the purpose of -interp, so one should consider it required (although this is
not enforced).  In no-interp mode, a nav file should not generally be used,
because it implies corrections to the image without accompanying corrections
to the shot locations, which is likely wrong.  Again, this is not enforced.

The hotspot, as well as the reported positions, are all 1-based image
coordinates, in (line, samp) order.

Note that the hotspot image coordinates are expressed with respect to the
full image sensor, regardless of any downsampling or subframing that might
have occurred for this image.  However, the output coordinates are specifically
for the given image - they DO take into account downsampling or subframing.

HISTORY:

2020-01-29 rgd	Initial version
2020-02-13 rgd	Added interp mode

COGNIZANT PROGRAMMER:  Bob Deen