}

3.5M Operations

As of 2006-12-01, the 3.5m has three guiders, each with fairly different cameras and underlying control software but with a unified interface:

  • dcam the DIS slitviewer
  • gcam the NA2 offset guider
  • ecam the Echelle slitviewer

Note: all object coordinates are entered and returned in terms of an image's binned subframe, where the lower-left corner of the lower-left pixel is 0,0.

Table of Contents

Camera and Exposure Commands

expose EXP-ARGS
Take a shutter open exposure using the given exposure arguments.

Returns: camFile, files

setMask FILENAME
Define the mask file for the camera, which indicates which pixels are to be ignored and/or interpolated over by the PyGuide star finder and centroider. This must be an unbinned, full-frame image. The pixel values should be 0 for pixels which are to be ignored by the PyGuide routines and non-zero for valid pixels. [This is the opposite convention from PyGuide itself, but it makes it much simpler to generate a mask file from an actual image: just set the pixels to ignore to 0.]
Note that any slits themselves must be fully masked out, or the turned-down edges will confuse the PyGuide routines.

Returns: maskFile

The following commands are obsolete and no longer work:

doread EXP-ARGS (warning: this command may not work; use expose instead!)
Take a shutter open exposure using the given exposure arguments. Note that requesting a filename does not work.

Returns: camFile

dodark EXP-ARGS (warning: this command may not work!)
Take a shutter closed exposure using the given exposure arguments. Note that requesting a filename does not work.

Returns: darkFile

Configuration Commands

A number of variables affecting the PyGuide and guiding algorithms can be configured. If they are adjusted via the guide tweak command while guiding, they only affect the active guiding run. If they should be kept across guiding runs, they need to be changed with the set command.

set ARGS
Adjust one or more of the variables controlling PyGuide and guiding. If set this way, the values are persistent until the actor is restarted (which is rarely). To wit:
cradius=R
Limit the centroider to within the given number of binned pixels from the starting position (the gstar coordinates or the boresight) or the previous guider centroid, if one exists. Note: making the radius too small can have unexpected effects, particularily with masked images.
minOffset=D
Minimum offset, in arcseconds, to allow while guiding: any offset smaller will not be applied. Basically, it is not clear that the telescope can usefully be commanded to move less than a certain distance, so this gives the option of avoiding possibly useless or deleterious jitter.
chiSqScale=factor0,thresh0[,factor1,thresh1...,factorN,threshN]
Set the scaling factor for generating offsets, depending on the chiSq fit. If the chiSq value is <= thresh0, multiply the offset by factor0; if <= thresh1, multiply it by factor1, etc. If the value is > the last threshold, zero the offset.
fitErrorScale=factor0,thresh0[,factor1,thresh1...,factorN,threshN]
Set the scaling factor for generating offsets, depending on the error estimate. If the error estimate is <= thresh0, multiply the offset by factor0; if <= thresh1, multiply it by factor1, etc. If the estimate is > the last threshold, zero the offset. Note: this is currently where any overall damping is implemented. I.e. factor0 should be less than 1.0. 0.8, say.
retry=N
Number of times to retry guiding (by taking a new exposure and find the last used object) before stopping the guiding loop or attempting to find another guide star.
restart=HOW
How to handle guiding failures. Currently stop or findstars.
thresh=SIGMA
Threshold above background to require for detecting an object. This is only used by the findstars routine, and not by the centroider.
autoTime=BOOL
Whether to automatically adjust exposure time while guiding. Unimplemented.
autoDark=BOOL
Whether to automatically create and use dark frames while guiding. Unimplemented.
time=SECONDS
Integration time.

Returns: TBD.

status
Return all available status keywords.

Image Analysis Commands

The guider simply makes calls to the PyGuide package, and it can be instructive to call into PyGuide directly. Or useful: seeing measurements can be used for focus loops, etc. This needs to be fleshed out with all the possible PyGuide tweaks. I.e. bias, gain, read noise for the centroider, etc.

centroid EXP-ARGS [on=X,Y [cradius=PIXELS]]
Run the centroid algorithm with the given arguments. If not specified, the global cradius value applies.
on=X,Y [cradius=PIXELS]
Start searching from the given location, in binned pixels relative to the current subframe (i.e. pixel coordinates for the saved image). If cradius is specified, limit the search to within the given number of binned pixels. If no starting location is specified, the findstars routine is called, and the highest ranking object is returned.

Returns: star, files, centActRadius

findstars EXP-ARGS [count=N] [thresh=SIGMA]
Run the findstars algorithm with the given arguments. Returns 0 or more detected objects, up to the count limit.
count=N
Limit the number of stars returned to N.
thresh=SIGMA
Set the detection threshold above background.

Returns: star, files, fsActThresh, fsActRadMult

Guiding Commands

The guider is based on the PyGuide centroider, which is designed to centroid symmetric objects in fields with possibly large masked out regions. This allows it to usefully centroid on stars whose wings are their only visible part, by interpolating over, say, a slit mask. Obviously, there are limits to this technique, so it is also possible to guide on field stars, regardless of any field rotation.

Guiding can be broken down into several stages, each of which can be controlled to some extent:

  • acquisition - Besides exposure time, binning, and windowing, the guider can be directed to only examine a given radius from the known guide or object star position. A loadable region might be worthwhile.
  • detection - The signal threshold above background required to recognize an object can be adjusted. For guiders with bad optical aberrations, a full frame desirability map is planned.
  • offsetting - The quality-of-fit and error estimates are used to filter how position errors are transformed to guide offsets. Both of those scales and the maximum acceptable offset are adjustable.
  • restarting - When a guide star is lost, the guider can be directed to stop, retry the same guide star, or search for a new guide star.
guide off
Turn guiding off.

Returns: guiding

guide on EXP-ARGS GUIDING-ARGS TWEAK-ARGS
Start guiding. If a filename is specified for the EXP-ARGS, start reading images from the given filename, and try to increment the filename in the expected fashion. Obviously, this is only useful for off-sky investigations.

The GUIDING-ARGS specify the basic guiding mode. If boresight and/or centerOn is specified, the "nearest" centroid to the boresight will be moved to the boresight with each iteration of the guide loop. Otherwise, whatever is at the boresight when guiding starts will be kept at the boresight. The default is for the guider to find what it believes is the best guide star and guide on that.

The GUIDING-ARGS are:
boresight
Assume there is an object very near the boresight, and guide by continuously moving that object to the boresight. Conflicts with gstar.
centerOn=X,Y [noGuide]
Move the object currently at X,Y to the boresight before starting to guide. The centroider is first run on X,Y, and the result is what is offset to the boresight using a calibration offset. Implies boresight after the initial offset. If centerOn is specified, gstar cannot be. This limitation might change.
The noGuide option stops the guiding loop after the initial offset to the boresight, but before any further guide corrections are made. After the offset, a new guider frame is taken, and the centroider and findstars routines are run on it.
gstar=X,Y
Specify a guide star position. The given location is used as a seed to the centroider, whose result is what is used as the starting position of the guide star. Conflicts with boresight.
imgFile=filename
If a centerOn or gstar coordinate is specified, this option provides an image coordinate frame. If no imgFile is passed in, the coordinates are assumed to be with respect to the guide on command's binning and frame.
For any guiding, the imgFile option can be passed in to sanity check guiding requests: if an offset has been performed since the image was taken, the guide on request will be rejected.

The TWEAK-ARGS are the same as for the guide tweak and set commands.

Returns: guiding, star, , files

guide tweak TWEAK-ARGS
Adjust a running guide loop. Note that there are some obvious features which cannot be adjusted while guiding (binning, windowing, specified guide star, to name some). Some of these limitations might change. See the set command for the list of TWEAK-ARGS

Returns: guiding

TCC gcam commands

The absolute minimum set of commands that the TCC requires to guide via a GImCtrl controller has been implemented. Sorry, no details. OK, maybe one detail: init, setcam, showstatus, doread, and findstars have been implemented. All require all their arguments, just like the TCC always sends. It is not possible to call these commands directly: they are only called when the command source is the TCC.

Exposure control command arguments

Many commands require an exposure or a subframe. These commands all accept the same set of arguments to get their image. Basically, they can request that a disk file be loaded, or that a new exposure be taken.

So either:

file=FILENAME
Use the given filename. Note that the image in the file cannot be windowed. The FILENAME can be relative or absolute. If relative, the guide camera's "current" directory will be searched.

or:

time=SECONDS
Expose for the given number of SECONDS.
bin=BINFACTOR
Bin the exposure by BINFACTOR in both X and Y.
window=X0,Y0,X1,Y1
Limit the exposure to the given subframe. X0,Y0 is the lower left corner and X1,Y1 is the upper right corner (inclusive). Coordinates should be integers and refer to binned pixels on the full detector frame. Thus 100,100,119,109 returns a region with 20 columns and 10 rows, starting at pixel 100,100.

Keywords

camFile=FILENAME (="g0051.fits")
The filename of a new exposure read out from the camera. The file is in the imageDir directory.
centDefRadius=RADIUS (=10.0) or centActRadius (=15.0)
Default or actual PyGuide.centroid search radius (in pixels), used to limit how far the centroider will go from its seed position to find a peak.
darkFile=FILENAME (="dark0051.fits")
The filename of a new dark exposure read out from the camera. The file is in the imageDir directory.
guiderPredPos=X,Y
The predicted position of the guidestar on the image. The difference between this and the measured guidestar centroid is the unfiltered guide offset.
measOffset=X,Y
The measured offset of the guidestar from its predicted position, in axis arcseconds. Some fraction of this offset will be used.
actOffset=X,Y
The offset that willl be sent to the TCC. This is a portion of the measured offset, trimmed according to various uncertainties -- currently mostly the PyGuide centroider's error statistic; eventually the PyGuide starshape's chi-squared stat will surely also be used.
guiding=STR
What state the guiding loop is in. Currently one of "on", "off", "starting", or "stopping".
imageRoot=HOST,DIRECTORY (="tycho.apo.nmsu.edu", "/export/images/")
The hostname to find the images on, and the root of the directory that any subsequent files will be saved in. The DIR component of the guiderFiles keywords should be appended to this directory string.
maskFile=FILENAME (="/export/images/keep/masks/gcam.fits")
The absolute filename of the unbinned maskfile which is used to generate the masks used for image processing. This file is never used directly, but is used to create appropriately binned and sub-framed mask files.
files=CALLER,ISNEW,DIR,FILES (="g",1,"ecam/UT050327", "p0051.fits","mask0023.fits","g0051.fits","","flat0031.fits")
List the files used by the guider or the findstars/centroid routines. The CALLER is a string which indicates the caller ("g", "f", or 'c", currently), ISNEW is 1 if the camFile was generated by a new exposure, and DIR is the common part of the file directories, with respect to the . The files are:
  1. finalFile - the actual image file that is used by the given routine. This is currently either just camFile or a file generated by processing a camFile with the specified darkFile and/or flatFile
  2. maskFile - the mask file.
  3. camFile - the raw camera image file.
  4. darkFile - (optional) a dark frame that was subtracted from camFile to generate finalFile.
  5. flatFile - (optional) a flat file that was applied to camFile to generate finalFile.
If a filename is relative (i.e. does not start with '/'), it is in the imageDir directory. Otherwise, the filename fully specifies the path.
fsDefRadMult=MULT (=2.0) or fsActMult=MULT (=2.5)
Default or actual PyGuide.findstars radius multiplier, used to adjust the radius found by the object detection routine before the centroider is called.
fsDefThresh=DATATHRESH (=2.5) or fsActThresh=DATATHRESH (=2.0)
Default or actual PyGuide.findstars object detection threshold.
star=STARINFO
The centroid and star shape statistics for one star. STARINFO is:
  1. type A string indicating why the keyword was generated. Currently one of "c", "f", or "g". respectively for centroider, findstars, or guide star.
  2. index A 1-based index identifying the star within the list of stars returned by the command. The list is ordered in descending order of desirability
  3. xCenter The x-coordinate of the calculated centroid. Generated by PyGuide.centroid.
  4. yCenter The y-coordinate of the calculated centroid. Generated by PyGuide.centroid.
  5. xError An estimate of the standard deviation in xCenter. In pixels.
  6. yError An estimate of the standard deviation of yCenter. In pixels.
  7. centroidRadius Radius of region used to centroid the object. In pixels. Note: this is not a property of the object; it is an input to PyGuide.centroid.
  8. asymm A measure of the asymmetry of the object; the value minimized by PyGuide.centroid. Not normalized, and so of doubtful value.
  9. majorFWHM Major axis of FWHM. In pixels. Note: ellipticity is not yet measured, so for now the reported majorFWHM = minorFWHM = average FWHM and angle = 0.
  10. minorFWHM Minor axis of FWHM. In pixels.
  11. angle The angle from X toward Y of the major axis of the ellipse. 0 to 180 degrees.
  12. chiSq Goodness of fit to double gaussian model star. See PyGuide.starShape.
  13. counts Sum of all unmasked pixels within the centroid radius. In ADUs. From PyGuide.centroid
  14. background Background level of fit to model star. In ADUs. From PyGuide.starShape
  15. amplitude Amplitude of fit to model star. In ADUs. From PyGuide.starShape

    The following two items are only present for guide stars (type = "g"):

  16. xPredPos optional The x-coordinate of the predicted centroid.
  17. yPredPos optional The y-coordinate of the predicted centroid.
All coordinates and pixel scales are in binned, image frame, units.

Changes

2008-01-31 ROwen:

  • Corrected zero point of on=X,Y argument to centroid.
  • Corrected an HTML typo; the page now validates.

2007-09-12 ROwen:

  • Corrected description of star keyword (fixing PR 585).

2006-12-01 ROwen:

  • Corrected radius -> cradius in description of centroid command.
  • Added EXP-ARGS link in various places.
  • Corrected links to centActRadius and centDefRadius keywords.

2006-11-07 ROwen:

  • Corrected description of window argument (X1,Y1 are included in the subframe).
  • Added expose command
  • Marked dodark and doread commands as obsolete and nonfunctional
  • Added the Changes section (it was already in the table of contents).
  • Corrected some html errors. It now passes verification.