SEE_ALSO

## 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)Coordinates of the edge points can be written to a table (parameter

`contourtable`). A least squares method is then used to determine the circular aperture's center coordinate and its radius. This scheme works even if only part of the circular aperture is exposed.

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