path: root/noao/digiphot/apphot/doc/center.hlp

.help center May00 noao.digiphot.apphot
.ih
NAME
center -- compute accurate centers for a list of objects
.ih
USAGE
center image
.ih
PARAMETERS
.ls image
The list of images containing the objects to be centered.
.le
.ls coords = ""
The list of text files containing initial coordinates for the objects to
be centered. Objects are listed in coords one object per line with the
initial coordinate values in columns one and two. The number of coordinate
files must be zero, one, or equal to the number of images.
If coords is "default", "dir$default", or a directory specification then an
coords file name of the form dir$root.extension.version is constructed and
searched for, where dir is the directory, root is the root image name,
extension is "coo" and version is the next available version number for the
file.
.le
.ls output = "default"
The name of the results file or results directory. If output is
"default", "dir$default", or a directory specification then an output file name
of the form dir$root.extension.version is constructed, where dir is the
directory, root is the root image name, extension is "ctr" and version is
the next available version number for the file. The number of output files
must be zero, one, or equal to the number of image files.  In both interactive
and batch mode full output is written to output. In interactive mode
an output summary is also written to the standard output.
.le
.ls plotfile = ""
The name of the file containing radial profile plots of the stars written
to the output file. If plotfile is defined then a radial profile plot
is written to plotfile every time a record is written to \fIoutput\fR.
The user should be aware that this can be a time consuming operation.
.le
.ls datapars = ""
The name of the file containing the data dependent parameters.
The critical parameters \fIfwhmpsf\fR and \fIsigma\fR are located in
datapars.  If datapars is undefined then the default parameter set in 
uparm directory is used.
.le
.ls centerpars = ""
The name of the file containing the centering algorithm parameters.
The critical parameters \fIcalgorithm\fR and \fIcbox\fR are located in
centerpars. If centerpars is undefined then the default parameter
set in uparm is used.
.le
.ls interactive = yes
Interactive or non-interactive mode?
.le
.ls radplots = no
If \fIradplots\fR is "yes" and CENTER is run in interactive mode, a radial
profile of each star is plotted on the screen after the center is fit.
.le
.ls icommands = ""
The image display cursor or image cursor command file. 
.le
.ls gcommands = ""
The graphics cursor or graphics cursor command file.
.le
.ls wcsin = ")_.wcsin", wcsout = ")_.wcsout"
The coordinate system of the input coordinates read from \fIcoords\fR and
of the output coordinates written to \fIoutput\fR respectively. The image
header coordinate system is used to transform from the input coordinate
system to the "logical" pixel coordinate system used internally,
and from the internal "logical" pixel coordinate system to the output
coordinate system. The input coordinate system options are "logical", tv",
"physical", and "world". The output coordinate system options are "logical",
"tv", and "physical". The image cursor coordinate system is assumed to
be the "tv" system.
.ls logical
Logical coordinates are pixel coordinates relative to the current image.
The  logical coordinate system is the coordinate system used by the image
input/output routines to access the image data on disk. In the logical
coordinate system the coordinates of the first pixel of a  2D image, e.g.
dev$ypix  and a 2D image section, e.g. dev$ypix[200:300,200:300] are
always (1,1).
.le
.ls tv  
Tv coordinates are the pixel coordinates used by the display servers. Tv
coordinates  include  the effects of any input image section, but do not
include the effects of previous linear transformations. If the input
image name does not include an image section, then tv coordinates are
identical to logical coordinates.  If the input image name does include a
section, and the input image has not been linearly transformed or copied from
a parent image, tv coordinates are identical to physical coordinates.
In the tv coordinate system the coordinates of the first pixel of a 
2D image, e.g. dev$ypix and a 2D image section, e.g. dev$ypix[200:300,200:300]
are (1,1) and (200,200) respectively.
.le
.ls physical
Physical coordinates are pixel coordinates invariant  with respect to linear
transformations of the physical image data.  For example, if the current image
was created by extracting a section of another image,  the  physical
coordinates of an object in the current image will be equal to the physical
coordinates of the same object in the parent image,  although the logical
coordinates will be different.  In the physical coordinate system the
coordinates of the first pixel of a 2D image, e.g. dev$ypix and a 2D
image section, e.g. dev$ypix[200:300,200:300] are (1,1) and (200,200)
respectively.
.le
.ls world
World coordinates are image coordinates in any units which are invariant
with respect to linear transformations of the physical image data. For
example, the ra and dec of an object will always be the same no matter
how the image is linearly transformed. The units of input world coordinates
must be the same as those expected by the image header wcs, e. g. 
degrees and degrees for celestial coordinate systems.
.le
The wcsin and wcsout parameters default to the values of the package
parameters of the same name. The default values of the package parameters
wcsin and wcsout are "logical" and "logical" respectively. 
.le
.ls cache = ")_.cache"
Cache the image pixels in memory. Cache may be set to the value of the apphot
package parameter (the default), "yes", or "no". By default cacheing is 
disabled.
.le
.ls verify = ")_.verify"
Verify the critical parameters in non-interactive mode ? Verify may be set to
the apphot package parameter value (the default), "yes", or "no.
.le
.ls update = ")_.update"
Update the critical parameters in non-interactive mode if \fIverify\fR is
set to yes? Update may be set to the apphot package parameter value (the
default), "yes", or "no.
.le
.ls verbose = ")_.verbose"
Print messages on the terminal in non-interactive mode ? Verbose may be set
to the apphot package parameter value (the default), "yes", or "no.
.le
.ls graphics = ")_.graphics"
The default graphics device.
Graphics may be set to the apphot package parameter value (the default), "yes",
or "no.
.le
.ls display = ")_.display"
The default display device.  Display may be set to the apphot package
parameter value (the default), "yes", or "no. By default graphics overlay
is disabled.  Setting display to one of "imdr", "imdg", "imdb", or "imdy"
enables graphics overlay with the IMD graphics kernel.  Setting display to
"stdgraph" enables CENTER to work interactively from a contour plot.
.le

.ih
DESCRIPTION
CENTER computes accurate centers for a set of objects in the IRAF image
\fIimage\fR, whose initial coordinates are read from the image display cursor, 
from the text file \fIcoords\fR, or from a cursor command file.
The computed x and y coordinates, the errors,  and the fitting parameters
are written to the text file \fIoutput\fR.

The coordinates read from \fIcoords\fR are assumed to be in coordinate
system defined by \fIwcsin\fR. The options are "logical", "tv", "physical",
and "world" and the transformation from the input coordinate system to
the internal "logical" system is defined by the image coordinate system.
The simplest default is the "logical" pixel system. Users working on with
image sections but importing pixel coordinate lists generated from the parent
image must use the "tv" or "physical" input coordinate systems.
Users importing coordinate lists in world coordinates, e.g. ra and dec,
must use the "world" coordinate system and may need to convert their
equatorial coordinate units from hours and degrees to degrees and degrees first.

The coordinates written to \fIoutput\fR are in the coordinate
system defined by \fIwcsout\fR. The options are "logical", "tv",
and "physical". The simplest default is the "logical" system. Users
wishing to correlate the output coordinates of objects measured in
image sections or mosaic pieces with coordinates in the parent
image must use the "tv" or "physical" coordinate systems.

If \fIcache\fR is yes and the host machine physical memory and working set size
are large enough, the input image pixels are cached in memory. If cacheing
is enabled and CENTER is run interactively the first measurement will appear
to take a long time as the entire image must be read in before the measurement
is actually made. All subsequent measurements will be very fast because CENTER
is accessing memory not disk. The point of cacheing is to speed up random
image access by making the internal image i/o buffers the same size as the
image itself. However if the input object lists are sorted in row order and
sparse cacheing may actually worsen not improve the execution time. Also at
present there is no point in enabling cacheing for images that are less than
or equal to 524288 bytes, i.e. the size of the test image dev$ypix, as the
default image i/o buffer is exactly that size. However if the size of dev$ypix
is doubled by converting it to a real image with the chpixtype task then the
effect of cacheing in interactive is can be quite noticeable if measurements
of objects in the top and bottom halves of the image are alternated.

CENTER can be run either interactively or in batch mode by setting the
parameter \fIinteractive\fR. In interactive mode starting x and y positions
can either be read directly from the image cursor or read from the text
file \fIcoords\fR. In interactive mode the user can examine, adjust, and
save the algorithm parameters, change ojects interactively, query for
the next or nth object in the list, or fit the entire coordinate list with
the chosen parameter set.  In batch mode the positions can be read from the
text file \fIcoords\fR or the image cursor can be redirected to a text file
containing a list of cursor commands as specified by the parameter
\fIicommands\fR. 

.ih
CURSOR COMMANDS

The following cursor commands are currently available.

.nf
	Interactive Keystroke Commands

?	Print help
:	Colon commands
v	Verify the critical parameters
w	Save the current parameters
d	Plot radial profile of current star
i	Interactively set parameters using current star
f	Fit center of current star
spbar	Fit center of current star, output results
m	Move to next star in coordinate list
n	Center next star in coordinate list, output results
l	Center remaining stars in coordinate list, output results
e	Print error messages
r	Rewind the coordinate list
q	Exit task


	Colon Commands

:show	[data/center]	List the parameters
:m      [n]	        Move to next [nth] star in coordinate list
:n      [n]	        Center next [nth] star in coordinate list,
			output results


	Colon Parameter Editing Commands

# Image and file name parameters

:image		[string]	Image name
:coords		[string]	Coordinate file name
:output 	[string]	Output file name

# Data dependent parameters

:scale		[value]		Image scale (units per pixel)
:fwhmpsf	[value]		Full-width half-maximum of PSF (scale units)
:emission	[y/n]		Emission feature (y), absorption (n)
:sigma		[value]		Standard deviation of sky (counts)
:datamin	[value]		Minimum good data value (counts)
:datamax	[value]		Maximum good data value (counts)

# Noise parameters

:noise 		[string]	Noise model (constant|poisson)
:gain		[string]	Gain image header keyword
:ccdread	[string]	Readout noise image header keyword
:epadu		[value]		Gain (electrons per adu)
:readnoise	[value]		Readout noise (electrons)

# Observations parameters

:exposure	[string]	Exposure time image header keyword
:airmass	[string]	Airmass image header keyword
:filter		[string]	Filter image header keyword
:obstime	[string]	Time of observation image header keyword
:itime		[value]		Exposure time (time units)
:xairmass	[value]		Airmass value (number)
:ifilter	[string]	Filter id string
:otime		[string]	Time of observation (time units)

# Centering parameters 

:calgorithm	[string]	Centering algorithm
:cbox		[value]		Width of centering box (scale units)
:cthreshold	[value]		Centering intensity threshold (sigma)
:cmaxiter	[value]		Maximum number of iterations
:maxshift	[value]		Maximum center shift (scale units)
:minsnratio	[value]		Minimum signal to noise for centering
:clean		[y/n]		Clean subraster before centering
:rclean		[value]		Cleaning radius (scale units)
:rclip		[value]		Clipping radius (scale units)
:kclean		[value]		Clean K-sigma rejection limit (sigma)

# Plotting and marking parameters

:mkcenter	[y/n]		Mark computed centers on the display
:radplot	[y/n]		Plot radial profile of object


The following keystroke commands are available from the interactive setup
menu.

                    Interactive Center Setup Menu

	v	Mark and verify the critical center parameters (f,s,c)

	f	Mark and verify the full-width half-maximum of the psf
	s	Mark and verify the standard deviation of the background
	l	Mark and verify the minimum good data value
	u	Mark and verify the maximum good data value

	c	Mark and verify the centering box half-width
	n	Mark and verify the cleaning radius
	p	Mark and verify the clipping radius
.fi

.ih
ALGORITHMS

Descriptions of the data dependent parameters and the centering
algorithm parameters can be found in the online manual pages for
\fIdatapars\fR and \fIcenterpars\fR.

.ih
OUTPUT

In interactive mode the following quantities are written to the terminal
as each object is measured. Error is a simple string which indicates
whether an error condition has been flagged.  The centers and their errors are
in pixel units.

.nf
	image  xinit  yinit  xcenter  ycenter  xerr  yerr  error
.fi

In both interactive and batch mode the full output is written to the
text file \fIoutput\fR. At the beginning of each file is a header
listing the current values of the parameters when the first stellar
record was written. These parameters can be subsequently altered.
For each star measured the following record is written

.nf
	image  xinit  yinit  id  coords  lid
	   xcenter  ycenter  xshift  yshift  xerr  yerr  cier error
.fi

Image and coords are the name of the image and coordinate file respectively.
Id and lid are the sequence numbers of stars in the output and coordinate
files respectively. Cier and error are the centering error code and accompanying
error message respectively.  Xinit, yinit, xcenter, ycenter, xshift, yshift,
and xerr, yerr are self explanatory and output in pixel units. The sense of
the xshift and yshift definitions is the following.

.nf
	xshift = xcenter - xinit
	yshift = ycenter - yinit
.fi

In interactive mode a radial profile of each measured object is plotted
in the graphics window if \fIradplots\fR is "yes".

In interactive and batchmode a radial profile plot is written to
\fIplotfile\fR  if it is defined each time the result of an object
measurement is written to \fIoutput\fR .

.ih
ERRORS

If the object centering was error free then the field cier will be zero.
Non-zero values in the cier column flag the following error conditions.

.nf
	0        # No error
	101      # The centering box is off the image
	102      # The centering box is partially off the image
	103      # The S/N ratio is low in the centering box
	104      # There are two few points for a good fit
	105      # The x or y center fit is singular
	106      # The x or y center fit did not converge
	107      # The x or y center shift is greater than maxshift
	108      # There is bad data in the centering box
.fi

.ih
EXAMPLES

1. Compute the centers for a few  stars in dev$ypix using the image display
and the image cursor. Setup the task parameters using the interactive
setup menu defined by the i keystroke command and a radial profile plot.

.nf
	ap> display dev$ypix 1 fi+

	... display the image

	ap> center dev$ypix

	... type ? to see help screen

	... move image cursor to a star
	... type i to enter the interactive setup menu
	... enter the maximum radius in pixels for the radial profile or
	    accept the default with a CR
	... type  v to get the default menu
	... set the fwhmpsf, sigma, and centering box half-width using the
	    graphics cursor and the stellar radial profile plot
	... typing <CR> after a prompt leaves the parameter at its default
	    value
	... type q to exit setup menu

	... type the v key to verify the critical parameters

	... type the w key to save the parameters in the parameter files

	... move the image cursor to the stars of interest and tap
	    the space bar

	... type q to quit followed by q to confirm the quit

	... the output will appear in ypix.ctr.1

.fi

2. Compute the centers for a few stars in dev$ypix using the contour plot
and the graphics cursor. This option is only useful for those (now very few)
users who have access to a graphics terminal but not to an image display
server. Setup the task parameters using the interactive setup menu defined by
the i key command as in example 1.

.nf
	ap> show stdimcur

	... record the default value of stdimcur

	ap> set stdimcur = stdgraph

	... define the image cursor to be the graphics cursor

	ap> contour dev$ypix

	... make a contour plot of dev$ypix

	ap> contour dev$ypix >G ypix.plot1

	... store the contour plot of ypix in the file ypix.plot

	ap> center dev$ypix display=stdgraph

	... type ? to see the help screen

	... move graphics cursor to a star
	... type i to enter the interactive setup menu
	... enter the maximum radius in pixels for the radial profile or
	    accept the default with a CR
	... type v key to get the default setup menu
	... enter maximum radius in pixels of the radial profile
	... set the fwhmpsf, sigma, and centering box half-width
	    using the graphics cursor and the stellar radial profile plot
	... typing <CR> after the prompt leaves the parameter at its
	    default value
	... type q to quit the setup menu

	... type the v key to verify critical parameters

	... type the w key to save the parameters in the parameter files

	... retype :.read ypix.plot1 to reload the contour plot

	... move the graphics cursor to the stars of interest and tap
	    the space bar

	... a one line summary of the answers will appear on the standard
	    output for each star measured

	... type q to quit followed by q to confirm the quit

	... full output will appear in the text file ypix.ctr.2 

	ap> set stdimcur = <default>

	... reset stdimcur to its previous value
.fi


3. Setup and run CENTER interactively on a list of objects temporarily
overriding the fwhmpsf, sigma, and cbox parameters determined in examples
1 or 2.

.nf
	ap> daofind dev$ypix fwhmpsf=2.6 sigma=25.0 verify-

	... make a coordinate list 

	... the output will appear in the text file ypix.coo.1

	ap> center dev$ypix cbox=7.0 coords=ypix.coo.1 

	... type ? for optional help


	... move the graphics cursor to the stars and tap space bar

				or

	... select stars from the input coordinate list with m / :m #
	    and measure with spbar

	... measure stars selected from the input coordinate list
	    with n / n #

	... a one line summary of results will appear on the standard output
	    for each star measured

	... the output will appear in ypix.ctr.3 ...
.fi


4. Display and measure some stars in an image section and write the output
coordinates in the coordinate system of the parent image.

.nf
	ap> display dev$ypix[150:450,150:450] 1

	... display the image section

	ap> center dev$ypix[150:450,150:450] wcsout=tv

	... move cursor to stars and type spbar

	... type q to quit and q again to confirm quit

	... output will appear in ypix.ctr.4

	ap> pdump ypix.ctr.4 xc,yc yes | tvmark 1 STDIN col=204 
.fi


5. Run CENTER in batch mode using the coordinate file and the previously
saved parameters. Verify the critical parameters.

.nf
	ap> center dev$ypix coords=ypix.coo.1 verify+ inter-

	... output will appear in ypix.ctr.5 ...
.fi


6. Repeat example 5 but assume that the input coordinate are ra and dec
in degrees and degrees, turn off verification, and submit the task to to
the background.

.nf
	ap> display dev$ypix

	ap> rimcursor wcs=world > radec.coo

	... move to selected stars and type any key

	... type ^Z to quit

	ap> center dev$ypix coords=radec.coo wcsin=world verify- inter- &

	... output will appear in ypix.ctr.6

	ap> pdump ypix.ctr.6 xc,yc yes | tvmark 1 STDIN col=204

	... mark the stars on the display


7. Run CENTER interactively without using the image display.

.nf
	ap> show stdimcur

	... record the default value of stdimcur

	ap> set stdimcur = text

	... set the image cursor to the standard input

	ap> center dev$ypix coords=ypix.coo.1

	... type ? for optional help

	... type :m 3 to set the initial coordinates to those of the
	    third star in the list

	... type i to enter the interactive setup menu
	... enter the maximum radius in pixels for the radial profile or
	    accept the default with a CR
	... type v to enter the default menu
	... set the fwhmpsf, sigma, and centering box half-width
	    using the graphics cursor and the stellar radial profile plot
	... typing <CR> after the prompt leaves the parameter at its default
	    value

	... type r to rewind the coordinate list

	... type l to measure all the stars in the coordinate list

	... a one line summary of the answers will appear on the standard
	    output for each star measured

	... type q to quit followed by q to confirm the quit

	... full output will appear in the text file ypix.ctr.7 

	ap> set stdimcur = <default>

	... reset the value of stdimcur
.fi

8. Use a image cursor command file to drive the CENTER task. The cursor command
file shown below sets the fwhmpsf, calgorithm, and cbox parameters, computes
the centers for 3 stars, updates the parameter files, and quits the task.

.nf
	ap> type cmdfile
	: calgorithm gauss
	: fwhmpsf 2.5
	: cbox 9.0
	442 410 101 \040 
	349 188 101 \040 
	225 131 101 \040 
	w
	q

	ap> center dev$ypix icommands=cmdfile  verify-

	... full output will appear in ypix.ctr.8
.fi

.ih
BUGS

It is the responsibility of the user to make sure that the image displayed
in the image display is the same as the image specified by the image parameter.

Commands which draw to the image display are disabled by default.
To enable graphics overlay on the image display, set the display
parameter to "imdr", "imdg", "imdb", or "imdy" to get red, green,
blue or yellow overlays and set the centerpars mkcenter switch to
"yes". It may be necessary to run gflush and to redisplay the image
to get the overlays position correctly. 

.ih
SEE ALSO
datapars, centerpars
.endhelp