The interface routines in gsurfit.c check the NO_UNDERSCORE macro to
see whether to append an underscore when defining the names:
# define GSRESTORE dgsree_
# define GSEVAL    dgsevl_
# define GSFREE    dgsfre_

The wavelength arrays in the phottab and apertab are assumed to be
monotonically increasing.

When adding the small-scale distortion offset, the value is taken from the
nearest pixel in the sgeofile data rather than by interpolating, i.e. it is
assumed to not vary significantly on a pixel scale.  When an input pixel
(or any corner of a pixel) is off the edge of the input image, the nearest
pixel is used for the sgeo offset.

if (GetKeyD (hdr, "SHIFTA1", use_def, 0., &sts->msm_slop[0]))
The wavecal offsets are taken from the SHIFTAi keywords.  Greater than
zero mean the target is located at a larger X or Y position than the
nominal position.

The interpolation (interp7) causes the bad pixel flags to expand to
adjacent row or columns in some cases, e.g. with the identity mapping.
This should not be a significant problem in practice.

The offsets have been renamed.  The offsets are:

MSM offset:
	MSM slop = SHIFTAi  (added to both TARGPSAi and CRPIXi by cs12)
	MAMA "dither" = MOFFSETi
aperture offset = OFFSETi from aperture description table (arcsec)
pos targ = new keywords POSTARGi;  currently ignored!  (units?)

Note that the MSM offsets are in units of image pixels, not necessarily
reference pixels.

Is this significant?:

There is a complication in converting the aperture offset to pixels.
In the notation of Don's manual, p 119, when the blaze angle is large
and alpha is not equal to beta, a given change in alpha (an aperture
offset) does not result in the same magnitude of change to beta; there's
a factor of cos (alpha) / cos (beta).  This is not a problem for the
MSM slop or MAMA dither, because we already have those in pixels (though
the values are different for different gratings).  It's a problem for
the aperture offset because we have to convert that into pixels, and the
conversion depends on grating parameters as well as image scale.

The offsets of the aperture from the nominal position (columns OFFSET1
and OFFSET2 from APDESTAB) are ...

Comments on the algorithm:

from Stefi:

>>  Scale both axes depending on the binning of the input image???
> Yes, scaling seems best to me too. Does this mean we will always
> output a full frame image, even when subarrays are used? That seems
> like a fine going in position for now - subarrays will be
> relatively  rarely used...

It's not scaling that results in a full frame output image, it's the
selection criteria for rows in the 2-D spectroscopic distortion table.
The output image size is specified in that table.  It should be possible
to modify the output image size if the input is a subarray, but I haven't
thought out the details.

from Don:

I think the algorithm basically looks fine.  Some answers to questions
are:

1) All reference tables and images are in units of lo-res MAMA or unbinned
CCD pixels.  Any reference image that does not have lo-res MAMA or unbinned
CCD pixels (e.g. MAMA flats, binned CCD biases) should have the LTV and LTM
keywords properly set with respect to the reference coordinates.

2) I agree that the output image size parameters from SDC should be properly
scaled depending on the binning of the input image.

3) I also agree that lower priority should be given to subarrays.  You might
want to take the approach that I plan to use.  For subarrays, I plan to
immediately insert the subarray into a full size image, modify
the header appropriately, and flag pixels outside the sub-array in the data
quality image.  Processing then will proceed as if a full readout was done.
Upon completion of the image rectification, you may optionally want to
"trim" the output image.  This can be done by using the data quality image.
Just trim any rows or columns at the edges that have all data quality values
set to indicate unusable image values.  Then modify CRPIXi and CRVALi
accordingly.  This approach to sub-arrays may waste extra computing time but
since sub-arrays will probably be used infrequently it shouldn't matter
much.

4) I think output wavecal offsets should be stored in unbinned raw pixel
coordinates (CCD pixels or MAMA Lo-res pixels).  The sample offset will be
used to adjust the a0 coef. of the dispersion relation which has units of
unbinned raw pixels.

5) Since your rectified Y positions are mapped to slit positions in units
of arcseconds, I agree that the Yoffset should be included.  By including
the Yoffset, it should also be easier to apply a slit transmission function
which would be a function of position along the slit.  Currently, by
definition, offset2 is set to 0.0 for all slits in the reference table.
Supposedly, Hartig helped adjust the slit wheel resolver position to make
this the case for the small slits.  Even if they are not exactly at the
same y-location, I prefer a coordinate system where a rectified pixel
retains the same y-location regardless of which slit was used.

6) The IAC correction is not quiet right.  I have defined the reference tables
to include any correction to the A0 term caused by changes in the A1 term.  See
27-Nov-1996 mail message (attached below) which also includes the MSM offset
correction algorithm.

7) I am still not entirely convinced that the output image values should
be multiplied by the projected area of the pixel in the input image.
I suppose there are pros and cons to either choice.  

Don

-----------------------------------------------------------------------------

From:	WIDGET::HRSLINDLER   "Don Lindler" 27-NOV-1996 14:09:20.57
To:	SMTP%"sbaum@stsci.edu",SMTP%"hodge@stsci.edu",SMTP%"hulbert@stsci.edu"
CC:	SMTP%"shaw@stsci.edu",HRSHEAP,GULL,WOODGATE,HRSLINDLER
Subj:	Pipeline incidence angle and MSM offset correction algorithm.

Stefi, Phil, and Steve;

How does this look for the incidence angle and MSM offset correction
algorithms?  

Don


Incidence Angle and MSM Offset Correction Algorithms
----------------------------------------------------

The following algorithm and reference data can be used to compute the
dispersion coefficients for an arbitrary grating, central wavelength, 
slit, and MSM offset.

1) Select the dispersion coefficients for the observation by grating, spectral
order and central wavelength (note the coefficients vary with position in the
cross dispersion direction, A2CENTER, for the first order grating modes).
Use linear interpolation to obtain the coefficients for untabulated values of
A2CENTER for the first order grating modes. For an A2CENTER outside of the
region of tabulated A2CENTERs use the closest tabulated value.
Ignore A2CENTER for the echelle modes.
Let COEF be the vector of dispersion coefficients.

2) If the slit for the tabulated dispersion coefficients is different than
the slit used for the observation, perform an incidence angle correction.

	a) determine the offset between the two slits in the dispersion
	   direction, DELTA, using the OFFSET1 values tabulated in the 
	   Aperture Description Table.
 
	b) select the incidence angle coefficients by grating, spectral order
	   and central wavelength in the Incidence Angle Correction Table.
	   There are two sets of coefficients in the table COEF1 and COEF2.

	c) correct the dispersion coefficients by:

		COEF(i) = COEF(i) + COEF1(i)*DELTA   for each i
		COEF(1) = COEF(1) + COEF2(1)*DELTA + COEF2(2)*DELTA**2

3) Correct the dispersion coefficients for the MSM offset.  Let A1OFF
and A2OFF be the MSM offset (either predicted or measured) in pixels.

	a) Select the MSM offset coefficients by grating, spectral order,
	   and central wavelength.  Two sets of offsets are required,
	   MCOEF1(i) and MCOEF2(i).

	b) Correct each dispersion coefficient, COEF(i) by:

		COEF(i) = COEF(i) + MCOEF1(i)*A1OFF + MCOEF2(i)*A2OFF

NOTE: The MSM Correction table can have the exact same columns as the
incidence angle correction table. 


4) Apply the computed auto-wavecal offset:

		COEF(1) = COEF(1) + waveoffset
