NAME

apercen -- Determine the deflection coordinates of an HSP aperture's center.

USAGE

apercen infile outtable

DESCRIPTION

This task calculates an HSP aperture center's deflection coordinates (aperture location calibration phase I). It uses the area scan data of a uniformly illuminated extended source (e.g., bright Earth) to determine the edge of the circular aperture; it then fits these edge contour points with a circle to find the center coordinate in HSP deflection units.

The user can choose N brightest data points (specified by the pt_ceiling parameter) to determine the mean "ceiling" count level. A mean "floor" count level can be similarly determined. The edge count level is then determined from a fraction (specified by the edge_level parameter) of the floor-to-ceiling difference, i.e.,

	edge_count  = floor_mean_count + edge_level *
			(ceiling_mean_count - floor_mean_count)

The input file must be 2-dimensional and no larger than 80 x 80.

PARAMETERS

infile [file name]

Name of the input data file.

The following keywords are needed from the science file header:

'ROOTNAME'      Rootname of the observation set (char*10).
'APERTURE'	Aperture name (char*10).

outtable [file name]

File name of the output table, which contains the following columns:

'ROOTNAME'	Observation ID of the file used in this task 
		(char*10).
'APERTURE'	Name of the aperture whose coordinate is 
		determined in this task (char*10).
'X0'		X coordinate of the circle center (real).
'Y0'		Y coordinate of the circle center (real).
'RADIUS'        Radius of the circle (real).
'SIGMA_X0'	Standard error of X0 (real).
'SIGMA_Y0'	Standard error of Y0 (real).
'SIGMA_R' 	Standard error of RADIUS (real).
'C_X0_Y0'	Correlation between X0 and Y0 (real).
'C_X0_R'	Correlation between X0 and RADIUS (real).
'C_Y0_R'	Correlation between Y0 and RADIUS (real).
'X_WEIGHT'      Weight scheme of X axis (real).
'Y_WEIGHT'      Weight scheme of Y axis (real).
'EDGE'		Count level of the edge points (real).
'CEILING'	Count level of the ceiling (real).
'FLOOR'		Count level of the floor (real).
'CHISQ'         Chi-squared (real).
'TOLERANCE'     Convergence of sigma squared (real).
'XMIN'		leftmost pixel of the selected section (int).
'XMAX'		rightmost pixel of the selected section (int).
'YMIN'		bottom pixel of the selected section (int).
'YMAX'		top pixel of the selected section (int).
'NPOINTS'       Number of edge points (int).
'ITERMAX'       Number of iterations used in the least square
                fitting (int).

(inmask) [file name]

File name of the data quality mask associated with infile. If the value of this parameter is null, it is assumed the mask file has the same root name as the input file but with an extension of "q", e.g., if the input file is called abc.d0h, the default mask file will be abc.q0h. If the mask file does not exist, all data points in the input file are assumed to be good.

(udlfile) [file name]

Name of the unique data log (UDL) file associated with infile. If the value of this parameter is null, it is assumed the UDL file has the same root name as the input file but with the extension ".ulh". This file must exist as the following keywords are needed from the UDL file header:

'VHORIZ'        Horizontal deflection of the starting point (int).
'VVERT'         Vertical deflection of the starting point (int).
'VHPOINTS'      Number of area scan columns (int).
'VVPOINTS'      Number of area scan rows (int).
'VHORSTPT'      Horizontal steps per point (int).
'VVERSTPT'      Vertical steps per point (int).
'VNOINTPT'      Number of integrations per point (int).

(np_ceiling) = [integer, min = 1]

Number of brightest points used to determine the ceiling level. For large apertures, the image has a flat top profile, and more than one point can be used as the ceiling; the profile for small apertures does not have a flat top so this parameter should be set to 1.

(np_floor) = [integer, min = 0]

Number of lowest points used to determine the floor level. If this parameter is set to 0, floor level is set to 0.

(xmin) = [integer, min = 0]

Leftmost pixel on the X axis of the selected section. If both xmin and xmax are set to zero, the X dimension of the section is the same as that of the input image.

(xmax) = [integer, min = 0]

Rightmost pixel in the X direction of the selected section. If both xmin and xmax are set to zero, the X dimension of the section is the same as that of the input image.

(ymin) = [integer, min = 0]

Lower Y pixel of the selected section. If both ymin and ymax are set to zero, the Y dimension of the section is the same as that of the input image.

(ymax) = [integer, min = 0]

Upper Y pixel of the selected section. If both ymin and ymax are set to zero, the Y dimension of the section is the same as that of the input image.

(edge_level) = 0.[real, min = 0., max = 1.]

Fraction of the floor-to-ceiling level to be used to specify the edge count level.

(contourkeep) = no [boolean]

Keep the table containing edge coordinates?

(contourtable) [file name]

If contourkeep = yes, then this parameter is used to specify the file name in which the table of edge contour point coordinates is stored. This table has the following columns:

X             X coordinate (real).
Y             Y coordinate (real).
DX            Standard error of X (real).
DY            Standard error of Y (real).

(xweight = -2.) [real]

Weighting flag of the X coordinate. The weight of each data point is proportional to the standard deviation with this flag as its exponent. For example, if hweight = 0, equal weight is applied. If 'hweight = -1000' or less, horizontal coordinates are assumed to be precise.

(yweight = -2.) [real]

Weighting flag of the Y coordinate. The weight of each data point is proportional to the standard deviation with this flag as its exponent. For example, if vweight = 0, equal weight is applied. If 'vweight = -1000' or less, vertical coordinates are assumed to be exact. You can not set BOTH hweight and vweight to -1000 or less.

(itermax = 100) [integer, min = 1]

Maximum number of iterations to be used in the least squares circle fitting.

(tolern = 1.E-12) [real, min = 0, max = 1.]

The tolerance of the "goodness" of the least squares fit. If the FRACTIONAL improvement of sigma-squared after an iteration is smaller than tolern, the fit is deemed satisfactory and the least squares iteration will terminate.

EXAMPLES

1. Determine the aperture center from the input data file input.hhh and put results in the output table output while saving the intermediate result of edge contour coordinates in contour. The input file has an associated data quality mask file input.msh. The count level of edge points is assumed to be half way between the floor level and the ceiling level.

hs> apercen infile="input.hhh" outtable="output" inmask="input.msh" 
	udlfile="input.ulh" edge_level=0.5 
	contourkeep=yes contourtable="contour"

BUGS

REFERENCES

SEE ALSO