STScI Logo

rfitx stsdas.hst_calib.foc.focgeom


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

rfitx -- Calculate the mapping difference between reference and distorted coordinates.

USAGE

rfitx input1 entry input2 refentry output xmin xmax ymin ymax

DESCRIPTION

This program will compare the differences between the coordinates of a geometrically corrected image and the coordinates of a distorted image to provide a mapping transformation. The distorted positions are presumed to have been already measured as reseau locations using the rfindx task (or as star positions using the daophot task in the images package.

The transformation has the following form.

    xin = f (xref, yref)
    yin = g (xref, yref)

The functions f and g are either a power series polynomial or a Legendre or Chebyshev polynomial surface of order xxorder and xyorder in the X axis, and yxorder and yyorder in the Y axis. Cross-terms are optional. The computation can be done in either real or double precision by setting the calctype parameter; the default is real. Automatic pixel rejection may be enabled by setting reject to a value higher than 0.0; reject is a threshold, and values below that threshold will not be accepted.

The xmin, xmax, ymin, and ymax parameters define the region, in reference coordinates, of the fit. These parameters can be used to reject out-of-range data before the actual fitting is peformed. If these parameters are not set by the user, then the INDEF values will default to the values stored in the reseau entry headers; this will normally be the size of the image on which the reseau marks were measured.

The rfitx task can be run interactively by setting interactive = yes, and then entering single-keystroke commands. In the interactive mode, the user can change fit parameters and can graphically display data until a satisfactory fit has been achieved. Keystroke commands are listed below.

?	Display this list of commands.
f	Fit the data and graph it using the current graph 
        type (g, x, r, y, s).
g	Graph the data and the current fit.
x	Graph the difference between the X fit residuals 
        and original X values.
r       Graph the difference between the X fit residuals 
        and original Y values.
y	Graph the difference between the Y fit residuals 
        and original X values.
s       Graph the difference between the Y fit residuals 
        and original Y values.
d	Delete the data point nearest the cursor.
u	Undelete a previously deleted point.
o	Overplot the next graph.
c	Toggle the constant X,Y plotting option (x,r or y,s).
t       Plot a line of constant X,Y through the nearest 
        data point.	
l	Print the current values of 'xshift', 'yshift', 
        'xscale', 'yscale', 'xrotate', and 'yrotate'.
v	Display magnified vector residuals of fit.
q	Quit; exit the interactive curve fitting.

Simple colon commands are used to change the values of parameters during an interactive session. Entering a colon command together with a new value changes the value of that parameter; entering the colon command without a new value will display the current value of the parameter. Colon commands are described below.

:show		List all parameters and their values.
:function       Fitting function (i.e., 'chebyshev', or 'legendre').
:xxorder 	X fitting function xorder.
:xyorder	X fitting function, yorder.
:yxorder	Y fitting function, xorder.
:yyorder	Y fitting function, yorder.
:xxterms	Include cross-terms in X fit?
:yxterms	Include cross-terms in Y fit?
:reject 	Rejection threshold.
:magnification	Magnification of vector residuals.

The final fit is stored in a simple text file that can be used by the geotran task in the images package, or by revalfitx in the focgeom package to produce reseau files for input to the geomcorrx task. The input to revalfitx will be a reseau file transformed by, for example the optical distortions, in order to combine distortion fields.

The transformation computed in this model is arbitrary, and does not correspond to a physically meaningful model. However, the first-order terms can be given by the following simple geometrical interpretation:

	xin = a + b * xref + c * yref
	yin = d + e * xref + f * yref

The coefficients can be interpreted as follows (xref0, yref0, xin0, and yin0 are the origins in the reference and input frames respectively).

	b = xscale * cos (xrot)
	c = yscale * sin (xrot)
	e = -xscale * sin (yrot)
	f = yscale * cos (yrot)
	a = xoin - b * xrefo - c * yref0
	d = yoin - e * xref0 - f * yref0

PARAMETERS

input[file name]
The input reseau file.
entry = "*" [string]
Template used to select the entries from input1 to be processed. The default (*) will process all entries.
input[file name]
Optional reference reseau file. If input2 is left blank, then the reference reseau data will be read from input1.
refentry [string]
Entries in the reference file corresponding to the entries in input1.
output [file name]
Name of the text data base file to be created by rfitx.
xmin = INDEF [real]
Minimum X value to be used. The default is to use the lowest value in the data.
xmax = INDEF [real]
Maximum X value to be used. The default is to use the highest value in the data.
ymin = INDEF [real]
Minimum Y value to be used. The default is to use the lowest value in the data.
ymax = INDEF [real]
Maximum Y value to be used. The default is to use the highest value in the data.
(function = "chebyshev") [string,
allowed values: chebyshev | legendre | polynomial]
The type of analytic surface to be fit. If function = chebyshev--the default value--then Chebyshev polynomials in the X and Y dimension will be used. Setting function = legendre will cause Legendre polynomials to be used, and setting function = polynomial causes a power series in the X and Y dimensions to be used. The "polynomial" option is strongly discouraged.
(xxorder = 2) [integer, min=2]
The order of the polynomials in X for the X fits. The default order and cross-term settings define a linear transformation in X and Y, where the six coefficients can be interpreted in terms of an X and Y shift, an X and Y scale change, and a rotation of the X and Y axis.
(xyorder = 2) [integer, min=2]
The order of the polynomials in the Y dimension for the X fits. The default order and cross-term settings define a linear transformation in X and Y, where the six coefficients can be interpreted in terms of an X and Y shift, an X and Y scale change, and a rotation of the X and Y axis.
(yxorder = 2) [integer, min=2]
The order of the polynomials in X for the Y fits. The default order and cross-term settings define a linear transformation in X and Y, where the six coefficients can be interpreted in terms of an X and Y shift, an X and Y scale change, and a rotation of the X and Y axis.
(yyorder = 2) [integer, min=2]
The order of the polynomials in Y for the Y fits. The default order and cross-term settings define a linear transformation in X and Y, where the six coefficients can be interpreted in terms of an axis and Y shift, an X and Y scale change, and a rotation of the X and Y axis.
(xxterms = no) [boolean]
Include cross terms in the X fits?
(yxterms = no) [boolean]
Include cross terms in the Y fits?
(reject = 0.) [real]
The rejection limit in units of sigma. The default (0.0) is to reject nothing.
(calctype = "real") [string, allowed values: real | double]
The precision of coordinate transformation calculations. Calculations are either performed as single or double precision real values.
(interactive = yes) [boolean]
Use the interactive mode? In interactive mode the user enters single-keystroke commands, controlling the fitting process, for example, the user can change the order of the fit, reject points, and display the data.
(device = "stdgraph") [string]
The graphics output device.
(cursor = "") [file name]
The graphics cursor. (Type "help cursor" for more information about the IRAF cursor facility.)

EXAMPLES

1. Create the mappings for all entries in a reseau file called input1 except the entry named approx. The entry Reference in the file input2 will be provide undistorted reference positions. Output will be stored in a text data base called fit.output.


   fo> rfitx input1 "*,~approx" input2 Reference fit.output 1 1024 1 1024

BUGS

REFERENCES

This task was written by David Giaretta.

SEE ALSO

rfindx, revalfitx, geomcorrx

Type "help reseau for a description of reseau files.

Type "help focgeom option=sys" for a higher-level description of the focgeom package.

This task is largely based on the geomap task in the images package. Modifications include the direct interface to FOC reseau files and the addition of display options.


Source Code · Package Help · Search Form · STSDAS