Guider Image Controller Commands

For version 4.1; last updated 2003-11-06

• Overview
• Configuration File
• History
• Commands
  • centroid xCtr yCtr xPredFWHM yPredFWHM
  • clearimage
  • docentroid expTime xBin yBin xCtr yCtr xPredFWHM yPredFWHM
  • dodark expTime xBin yBin region
  • doread expTime xBin yBin region
  • dumpbadbin file name
  • dumpbadfits file name
  • dumpbin fileName
  • dumpfits fileName
  • exit
  • findstars maxNumStars region xPredFWHM yPredFWHM
  • help
  • init
  • loadbadbin xSize ySize fileName
  • loadbin xSize ySize fileName
  • loadfits fileName
  • makebadpixmap minGood maxGood
  • median region
  • quit
  • readconfig [filename]
  • setboxsize size
  • setcam ID#
  • setfilenum filenum
  • setmaxfilenum maxfilenum
  • showbadcaminfo
  • showbadiminfo
  • showcaminfo
  • showcamlist
  • showconfig
  • showiminfo
  • showparams
  • showstatus
  • showversion
  • stats region

Overview

This controller obtains and processes images from various guide cameras. Its commands, and associated replies, are described in this document. For more information about the controller, please see the Guide Image Controller Overview Manual. A few additional commands may be available that are not supported and hence not documented in this manual. These are generally written to aid in debugging. The complete set of commands available, including unsupported commands, may be determined by issuing the help command.

Units are as follows, unless otherwise noted:

• all linear units are in binned (x,y) pixels
• all times are in seconds
• all brightnesses are in ADUs (counts)

The position coordinate system is as follows:

• The x axis is column number, i.e. x is parallel to the serial register of the CCD and zero is the end read first during readout
• The y axis is row number, i.e. y is perpendicular to the serial register of the CCD and zero is the end read first during readout
• The point 0,0 is at the corner of first pixel read out. Hence the center of that pixel is (0.5, 0.5) and the center of a 1024x1024 CCD is (512.0, 512.0)

Configuration File

Beginning with version 4.0 a camera configuration file has been implemented. This file is read at startup and in response to the readconfig command. The format of the file changed in 4.1 and is now as follows:

• Comment lines begin with !
• Values are expressed as "keyword value" pairs, one pair per line. Keyword and value are separated by an arbitrary number of spaces and/or tabs.
• String values should not be quoted; if you supply quotes they will be read as part of the string!
• Keywords are not case sensitive.

Keywords and their associated values are:

• ImageDir directory to contain images; all data on the rest of the line is taken to be the directory, so the directory name may contain spaces. The default is guider_images.
• BadPixMapDir directory containing bad pixel maps. The default is badpixelmaps.
• MaxFileNum the maximum number of images that will be automatically saved before overwriting existing images. The default is 100.
• LastFileNum the number of the last autosaved image. Changing this number has no effect on images that have already been saved. Example: if you set it to 17, then the next image saved will be number 18 (unless macFileNum < 18, in which case the next image saved will be number 1). I suspect few, if any, users will wish to change this parameter.
• Debug 1 for debug mode, 0 (the default) for regular mode. In debug mode commands are received from standard input (the log window on a Mac) rather than from the serial port, so you can conduct tests directly from the guide image controller. This keyword is only read when the program starts up. If you want to change it you must quit, modify the config file and restart.
• Camera data for a camera, a series of whitespace-separated values in the following order:
  • ID: the integer used by setcam to select this particular camera. You cannot specify 0 because that is reserved to mean "no camera". If an ID number is specified that is already in use, the existing camera data is deleted and the new data is used. This can be used to update camera data in a running program: generate a configuration file that contains just the new data and read it in with the "readconfig" command.
  • type: a string used to select the correct camera class; the allowed types are presently PXL and SenSys on a Macintosh and Apogee on a PC. Not case sensitive.
  • name: name of camera, may not contain spaces. This string may be used by the camera support library, in which case the allowed values will depend on the camera and the string may be case sensitive.
  • x size, y size: x and y size of the image, in unbinned pixels
  • bits/pixel: the number of bits of data per pixel
  • bad pixel map?: 1 if this camera has a bad pixel map, 0 otherwise
  • temperature: desired CCD temperature (C); ignored if temperature cannot be set
  • gain (e-/ADU); used for information and internal data processing rather than to set the camera
  • read noise (e-); used for information and internal data processing rather than to set the camera
  • Append the following optional parameters for PXL and SenSys (e.g. Photometrics PPK) cameras.
    • gain setting: selects an entry in the speed table (see next item) associated with a particular gain. 1 if omitted (if you omit gain setting then you must also omit speed table).
    • speed table: selects a particular speed table. 0 if omitted
    • Notes
      • SenSys cameras require a speed table of 0; the associated gain settings are shown in the SenSys manual under "CCD Characteristics"
      • I assume similar information came with the PXL camera(s), but I don't have it.

Here is a sample configuration file:

ImageDir    :images:
MaxFileNum  10
Debug        1
! Camera data
!       ID      type    name    x size  y size  bits    map?    temp    gain    read    gainset    spdtable
!                               (pix)   (pix)   /pix            (C)     e-/ADU  (e-)    (Photometrics)
Camera  1       PXL     PXL1024 1024    1024    16      0       -25.0    9.7    21
Camera  2       SenSys  SenSys   768     512    12      0        10.0   40.0    26      1
Camera  3       SenSys  SenSys2 1536    1024    12      0        10.0   40.0    26      1

Commands

• Commands are not case sensitive.
• Commands are be terminated with a <CR> (carriage return).
• You may supply an integer if a floating-point number is wanted, but not visa-versa.
• File names may contain spaces, but must not be enclosed in double-quotes (file names are always the last parameter requested, and simply consist of all remaining text on the line). This form of string input is due to idiosyncrasies in C++'s text handling.

Only the format for normal replies is shown below. It is hoped that error messages will be self-evident.

centroid xCtr yCtr xPredFWHM yPredFWHM

Find the position and shape of a star. The predicted FWHM is in binned pixels; an error of a factor of two either way should be acceptable. Excessive error can cause centroiding to fail. The centroid box (set by the boxsize parameter and the predicted FWHM) must contain only one star, else the centroid will be inaccurate (and will usually be rejected with an error).

If the centroid is computed successfully, returns data as follows:

bin       position        FWHM    maj ang  peak  bright  sky    pos uncert  error code
x y      x        y     maj  min                                  x     y
2 2   133.609  33.681   4.25 4.32   1.8   1105.5 24483.1 77.0   0.001 0.001     0
 

where:

• maj ang (deg) is the angle of the major axis of the ellipse with respect to the image (0 if along x, 45 if halfway between x and y).
• position, FWHM and position uncertainty are in binned pixels
• peak, brightness and sky are in counts
• error code is zero for success. Any other value suggests a reduction in accuracy of the data.

Error Codes. These may change, but are presently as follows (those returned by atDACentroid). Values -1 through -4 indicate a failed centroid, and an error message is returned instead of star data.

0	OK
-1	center isn't locally highest pixel in atObjectCenterFind_Ptr
-2	object is too close to the edge in atObjectCenterFind_Ptr
-3	object has vanishing second derivative in atObjectCenterFind_Ptr
-4	sky is too high in atObjectCenterFind_Ptr -10 Zero sigma - peak and counts not calculated after atObjectCenterFind_Ptr
-11	Infinite sigma after atObjectCenterFind_Ptr
-21	Error in setfsigma (sigma too large) in atSigmaFind
-22	Sigma out of range (inf sharp or inf flat) in atSigmaFind
-23	Too many iterations in atSigmaFind
-24	Too close to edge in atSigmaFind
-25	Error in lgausmom - check sky value in atSigmaFind
-26	Too flat in atFindFocMom, from atSigmaFind
-30	Zero sigma - peak and counts not calculated after atSigmaFind
-31	Infinite sigma after atSigmaFind

clearimage

Erase the image in memory (by resetting the image pointers).

docentroid expTime xBin yBin xCtr yCtr xPredFWHM yPredFWHM

Exposes the CCD, reads a subregion into memory, and centroids the subregion. The size of the subregion is predFWHM * boxSize, truncated as necessary to fit on the CCD. If expTime is zero then the shutter is not opened. See also doread and centroid. Note: docentroid will return an error if no camera selected.

Returns the output of showiminfo followed by the output of centroid (including the relevant error message if centroiding fails).

dodark expTime xBin yBin region

Like doread but does not open the shutter. Used to take dark frames.

Returns the output of showiminfo.

doread expTime xBin yBin region

Exposes the CCD, reads it into memory, writes a FITS image to the directory "guider images", and updates the text file last.image to point to it. The FITS file is given one of a circularly sequential set of names; if a file by that name exists, it is silently replaced. If expTime is zero then the shutter is not opened. Note: doread will return an error if no camera selected

Returns the output of showiminfo.

dumpbadbin file name

Dump the bad pixel map to a binary file.

dumpbadfits file name

Dump the bad pixel map to a FITS file.

dumpbin fileName

Dump the image to a binary file.

dumpfits fileName

Dump the image to a FITS file.

exit

Identical to the quit command. Makes the image controller program quit. Please don't issue this command unless you are prepared to get the program running again.

findstars maxNumStars region xPredFWHM yPredFWHM

Computes statistics, determines a cutoff level (see prefs), scans for stars, sorts the list in decreasing brightness and prints a list of stars. The predicted FWHM is in pixels; an error of a factor of two either way should be acceptable, but excessive error can cause star finding or centroiding to fail. The stars are listed approximately in decreasing order of brightness.

The order is approximate due to details of the algorithm. When the stars are first found only crude positions and brightnesses are determined, and these crude brightnesses are used to sort the data. The stars are accurately centroided only as they are being printed, so the brightnesses may not be in perfectly descending order. (Note that any stars for which the centroid calculation fails are omitted, with a warning printed to the log window). The ordering should probably be perfected, but the simplest solution would require accurately centroiding many more objects, which would slow down the code.

Returns one line of data per star; each line is in the format returned by centroid. Sample output:

findstars 100 0 0 0 0 5 5
created null bad pixel map for camera: 2
star finder constructed; super pixel array is 31 by 19
star finder destructed
Found 11 raw star(s)
2 2   133.609 33.681   4.32 4.25 -1.8   1105.5 24483.1 77.0   0.001 0.001   0
2 2   205.562 67.510   4.16 4.04 -70.4   985.2 20909.2 82.0   0.001 0.001   0
2 2   74.291 177.195   5.22 4.29 80.3   556.1 14238.4 77.0   0.001 0.001   0
2 2   132.761 110.889   4.82 4.56 -7.5   505.9 12899.7 77.0   0.001 0.001   0
2 2   79.187 33.018   6.58 5.27 -55.1   358.5 13771.4 77.0   0.001 0.001   0
2 2   17.606 100.423   6.19 4.42 -11.6   427.3 12682.9 77.0   0.001 0.001   0
2 2   78.383 106.623   5.30 4.35 -22.1   392.7 10272.0 76.0   0.001 0.001   0
2 2   133.305 180.496   7.00 5.10 16.8   263.5 10670.0 78.0   0.001 0.001   -24
2 2   17.149 173.413   4.59 4.05 -47.9   256.0 5690.9 77.0   0.002 0.002   0
2 2   23.220 32.065   6.80 5.18 -25.3   163.6 5897.1 76.0   0.002 0.002   0
2 2   281.312 171.713   5.19 4.32 32.6   160.8 4129.9 78.0   0.002 0.002   0

If no stars are found, the following is returned:

no stars found

help

Displays help for the program, including a list of commands, their arguments, and a brief description of each command.

init

Initialize the current camera, erases the image (and bad pixel map), and restores default parameters.

loadbadbin xSize ySize fileName

Load the bad pixel map from a binary file.

loadbin xSize ySize fileName

Load the image from a binary file.

loadfits fileName

Load the image from a FITS file. Attempts to parse CAMID (camera ID number) in the header, but defaults to the zero camera if not found. If the FITS file was written when a different set of cameras was available then CAMID may actually be wrong, in which case you may wish to edit it out of the header.

makebadpixmap minGood maxGood

Use the current image to make a bad pixel map. Pixels with values outside the range minGood to maxGood (inclusive) are considered bad. Specifying 0 for maxGood causes it to use the maximum possible counts minus one -- in other words, only completely saturated pixels are considered too bright.

median region

Computes the approximate median pixel value of the specified region. For large regions some groups of pixels are averaged together before taking the median of the averages.

quit

Identical to the exit command. Makes the image controller program quit. Please don't issue this command unless you are prepared to get the program running again.

readconfig [filename]

Reads the specified configuration file, or config.txt if none specified. Any omitted keywords are left unchanged, so this command is useful for modifying the configuration data read in at startup (from the file config.txt).

setboxsize size

Sets the centroid box size, in FWHM units. The centroid box is used for two things:

• The image size for the docentroid command.
• The size of the region to scan for computing the sky background level

The centroid box size in pixels is computed, as follows:

Centroid box size in x/y pixels = max (box size in fwhm units * predicted FWHM in x/y pixels, 15)

Unlike predicted FWHM, the appropriate value of box size (in FWHM units) should be independent of camera and observing conditions. In fact, the default box size should be adequate under all circumstances.

Making the box size too large is unlikely to cause significant problems, it mainly slows down reading of the CCD. Making the box size too small will cause centroiding to fail, and since the required size depends partly on how centered the star is in the image, this failure can be intermittent for borderline cases.

setcam camIDNum

Select a given camera and initialize it. All subsequent camera access commands, such as "doread" are directed to this camera until a new setcamera command is received. Returns the same information as showcaminfo.

0 always means "no camera". Other camera ID numbers are specified in the configuration file. A list of available cameras may be obtained via the showcamlist command.

setfilenum filenum

Sets the file number for the FITS file to be automatically written next time the camera is read. Must be in the range [1, maxfilenum].

setmaxfilenum maxfilenum

Sets the maximum file number for the FITS file automatically written each time the camera is read. Must be positive.

showbadcaminfo

Return camera data associated with the bad pixel map, using the same format as showcaminfo.

showbadiminfo

Return information about the bad pixel map, using the same format as showiminfo.

showcaminfo

Return data about the current camera, including image size, min and max possible pixel values, the CCD temperature (in C; NaN if not available for the current camera) and the file number for the next file to be written. Sample output:

showcaminfo
0 "none" 1200 1200 16 NaN 53 "camera: ID# name sizeXY bits/pixel temp fileNum"

showcamlist

Return information about all known cameras. Only hard-wired information is displayed; information about what the camera is looking at should be kept in the TCC or MC. Sample output:

showcamlist
0 "none" 1600 1600 16 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
1 "PXL1024" 1024 1024 16 -20.89 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
2 "SenSys" 768 512 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
3 "SenSys2" 1536 1024 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
4 "SenSys" 768 512 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
5 "SenSys2" 1536 1024 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
6 "SenSys" 768 512 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
7 "SenSys2" 1536 1024 12 nan 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
 

showconfig

Return data about the current configuration. Sample output:

! Current configuration
! directory for autosaved images (may contain spaces)
ImageDir     :images:

! directory for bad pixel maps (may contain spaces)
BadPixMapDir badpixelmaps

! number of autosaved images to store (may contain spaces)
MaxFileNum   10

! number of last autosaved image
! (typically best left alone, so commented out)
! LastFileNum  0

! 0 for normal operation (read commands from the serial port)
! 1 to debug (read commands from the console window)
Debug        1

! camera data is as follows:
ID number, type, name, x size, y size, bits/pix, has bad pixel map (0 if false, 1 if true), desired temperature (C), gain (e-/ADU), read noise (e-)
Camera 0 none none 1600 1600 16 0 1 0
Camera 1 PXL PXL1024 1024 1024 16 -25 9.7 21
Camera 2 SenSys SenSys 768 512 12 10 40 26
Camera 3 SenSys SenSys2 1536 1024 12 10 40 26
Camera 4 SenSys SenSys 768 512 12 10 20 19
Camera 5 SenSys SenSys2 1536 1024 12 10 20 19
Camera 6 SenSys SenSys 768 512 12 10 5 13
Camera 7 SenSys SenSys2 1536 1024 12 10 5 13

showiminfo

Return data about the current image in memory. Sample output:

showiminfo
1 1 0 0 0 0 nan 0 nan "image: binXY begXY sizeXY expTime camID temp"

showiminfo
1 1 0 0 1024 1024 nan 0 nan "image: binXY begXY sizeXY expTime camID temp"

showparams

Return the value of all user-settable parameters. Sample output:

showparams
6.00 53 "params: boxSize (FWHM units) maxFileNum"

showstatus

Concatenate output of showparams, showcaminfo and showiminfo. Sample output:

showstatus
1 "PXL1024" 1024 1024 16 -20.89 318 "camera: ID# name sizeXY bits/pixel temp lastFileNum"
1 1 0 0 0 0 nan 0 nan "image: binXY begXY sizeXY expTime camID temp"
8.00 1000 params: boxSize (FWHM units) maxFileNum

showversion

Returns the software version and date. Sample output:

showversion
Guider Image Controller v3.0b2 3/26/97

stats region

Compute and prints statistics for the given region. Sample output:

stats 0 0 0 0
819.33 106.27 455.00 21678.00 1048576 0 "mean stdDev min max nGoodPix nBadPix"

Parameters

region

Four numbers specifying a region of interest, as follows:

xCtr yCtr xSize ySize

where:

• all values are in decimal pixels
• the center of a given pixel is that pixel's index plus 0.5 (the corner pixel has index 0,0)
• the size is from edge to edge
• the desired region need not fit on the CCD or current image in memory; it will be truncated as necessary, without warning
• if xSize or ySize are zero then the entire image area in that axis is used, and the corresponding ctr is ignored

For example:

7.5 1 3 4

requests a 3x4 box of pixels centered on the center of pixel 7 in x and the boundary between pixels 0 and 1 in y. This is a rectangle extending from pixel 6,-1 through pixel 8,2 (inclusive). However, a portion of this requested region is out of range (less than zero), so the actual region will be truncated to a 3x3 box extending from pixel 6,0 through 8,2 (inclusive).

History

2003-11-06 manual fixes

• The sample output for showstatus had the image info in the wrong order for (presumably it was outdated output). Also, the output for showcaminfo was changed at some point to show the comment string on every line, so that example was updated.

4.1 2002-05-22

• Released 4.1b5 as 4.1. No code changes, but I did clean up the comments in config.txt.

4.1b5 2001-06-18

• Bug fix: a command consisting of one or more spaces caused an error.
• Improved the reliability of the serial port open code; if the port is already open (as can happen if the application dies or is killed), tries to close it and then open it again before giving up.
• Improved the error handling of main: all code is now in a try block; formerly if the serial ports failed to open, for instance, the application would instantly quit.
• Increased the Mac memory partition to 18000k, in the faint hope of improving a sporadic slow read time seen in the 3.5m NA2 PXL camera.
• Added a message to stdout when the serial port is opened and closed.

4.1b4 2001-06-01

• Fixed routil_getRecord, which was not always setting isEOF, producing a failure on Windows.

4.1b3 2001-05-18

• Bug fix: floating point parameters in fits headers had no decimal point if only zeros would have been displayed to the right of the decimal (due to using "g" format).
• Documented the dodark command; it has existed for awhile and was described by the help command, but was not documented in this manual.

4.1b2 2001-04-04

• Changed Mac version serial port back to A (from B).
• Moved serial port code to namespace ser.
• Improved routil_getRecord's algorithm for detecting eof or error.

4.1b1 2001-03-07

• Made commands case insensitive.
• Overhauled the configuration file format, adding many items and changing the default filename to config.txt.
• Changed Mac version to use serial port B (instead of A).
• Moved camera info class to Camera.h and Camera namespace. and added an instance to Image and BaseCam classes, eliminating most uses of camIDNum (yay!).
• Made methods of BaseCam that must be overridden "pure virtual", to force the override.
• Eliminated uninit method in BaseCam and camera-specific classes; wind-down is so simple that a separate method seemed wasteful; all such work is now done directly in the destructor.

4.0b3, 1/18/00

Ported to Windows 95 with support for Apogee Cameras. This version has two targets and still supports the Macintosh with the Photometrics cameras. The port required the following changes:

• Conversion of small amounts of code to ANSI standard C++.
• Use the WinSOUIX libraries for the Windows implementation of the interface.
• Abstracting the camera control library to create a hardware independent base class.
• Writing two hardware dependent camera control classes, one for the Mac which interfaces with the Photometrics camera and one for the PC which interfaces with the Apogee camera.
• Adding a serial port class for Windows
• Adding compiler directives throughout the code to sense which target platform is being compiled and including the proper header files.
• Move all camera configuration parameters to a text configuration file so that adding new cameras which use the same library not longer requires recompilation.
• Made necessary big-endian - little-endian conversions for FITS images on Windows platform.

For more detailed information you may want to look at the file "4.0 Developer Notes" in the development directory

3.0b27, 6/22/99

• Added commands setfilenum and setmaxfilenum
• Improved showparams to show maxfilenum and improved camera status to show current file number
• Fixed bug in command parser: was not catching all classes of exceptions; fixed bug in the auto-generated FITS file naming routine (file numbers > 99 were causing very strange file names) and overhauled that code
• Improved sfind.genStarList to catch errors from gim.centerOfMass and reject such stars; this fixed the error mentioned in 3.0b25 and allowed returning to use of cheap median without fear
• Returned to use of cheap median

3.0b26, 6/21/99

• Bug fixes to centroid output
  • FWHM is now listed with the major axis first
  • angle of major axis of ellipse now has the correct sign

3.0b25, 6/17/99

• Modified to use true median code in star finder init because of extremely rare errors seen when using "cheap median" (mean with highest pixel eliminated); note that this is a quick fix, in that the errors need to be properly investigated; true median is much slower than cheap median, and it's not clear that true median gives any better star finding
• Modified super pixel type to have separate counts field instead of overloading the "med" field

3.0b24, 6/17/99

• Bug fix: star finder could find the same star twice (distant bright star neighbors were being treated as stars). R. Owen.

3.0b23, 6/16/99

• Increased # of images in ring buffer to 1000 (again, the change in 3.0b19 seems to have been somehow lost). R. Owen.

3.0b22, 6/16/99

• Repaired a test for hot pixels in the star finder; known bugs: star finder may find a given star twice
• Note that the cheap "median filter" for superpixels is commented out for reasons Jeff Morgan nor Russell Owen can remember, we intend to restore it but didn't get to it for this iteration

3.0b21, 6/16/99

• Eliminated zfindrawstars command; gim.centroid now always computes position uncertainty, and as a side effect gain is now a required parameter for each camera, even "none"
• Uses gim__star structure to hold star centroid and shape data
• gim.showStarInfo displays the appropriate # of decimal digits for each item, displays centroid status, uses spaces to group items and no longer outputs a descriptive comment after each line
• Help now describes the output from gim.showStarInfo.

3.0b20, 6/14/99

• Modified to use current SDSS centroiding code and to be tolerant of nonfatal centroiding errors
• Modified to yield time to background processes and allow quitting during exposures

3.0b19, 6/1/99

• Changed # of images in ring buffer from 20 to 1000

3.0b18 4/8/99

• Fixed gcam_initCamera to handle the Echelle SenSys camera better (gain was not being properly set)

3.0b17, 12/14/98

• Added an extra setting for Echelle SenSys camera "Sensys2"

Changes in versions 3.0b12 - 3.0b16 were not recorded

3.0b11, 8/19/97

(note: 3.0b10 was never released)

• Documentation enhanced to describe the output of centroid better. R.O. 11/25/97
• Documentation enhanced to describe the x,y coordinate system better. 11/6/97.
• Fixed star position output: the comment didn't have a space before it.
• Fixed log window findstars error reporting; when a raw star cannot be centroided the failure code is now displayed.
• Fixed a problem with box size and sky determination in centroid by putting a floor on the box size.
• Changed the output of showiminfo so that binning data comes first, thus matching the order of command parameters.

3.0b9, 8/11/97 (created 8/18/97)

This version number and date were used for two releases (oops). These notes refer to the later release, which was built 8/18/97.

• Docentroid failed due to the image being too small when PredFWHM = 1. Fixed by putting a floor of 15 pixels on the image size. The automatic image size calculation should now work for all valid PredFWHM (though the centroid routine still cannot handle large PredFWHM due to speed optimizations we neither need nor want).
• When the centroid portion of docentroid failed, the doread output of docentroid would be returned with the next command, whatever it might be. This was because the reply stream was not getting flushed if the parser threw an exception. Two fixes were applied:
  • The reply stream is now flushed if an exception is thrown
  • The parser now returns the usual sort of command error messages in the reply stream itself and only throws an exception if a nasty unrecoverable error occurs. The main routine still attempts to recover from all errors, but such recovery used to be the normal mechanism for handling parsing errors and now is a last-ditch effort to stay alive. This is arguably a more reasonable use of exception handling.
• As a result of the error handling improvement, compound commands such as docentroid now return intermediate results, even if an error occurs in a later portion. At the moment this only affects docentroid

3.0b5-3.0b8

• Short lived versions with various bug fixes that were not documented (sigh).

3.0b4, 4/7/97

• Removed the setPredFWHM command.
• Added xPredFWHM yPredFWHM arguments to centroid and findstars commands.

3.0b3, 4/4/97

• Removed code that worked around bugs in CodeWarrior 10's string and stream handling. Those bugs were fixed in CodeWarrior 11!

3.0b2, 3/31/97

• Added support for Photometrics cameras. Removed support for SpectraSores cameras.
• Changed centroiding algorithm to that used by the SDSS.
• Removed "expose", "flush", "read" commands; all replaced by "doread".
• Changed format of all status replies, mostly adding new information.
• Compiled using Metrowerks CodeWarrior 11.

2.0, ?/?/96

This version was developed by Jeff Morgan, but the manuals were apparently never updated. Changes include:

• An new star finding algorithm that is much more sensitive.
• Improvements to the centroiding routine to make it more robust.
• Implemented FITS file I/O
• Replaced "setthresh" with "setboxsize" and "setpredfwhm".

1.1, 7/25/95

• Added overscan versions of both cameras (SpectraSource HPC-1 TK1024 and TK512)
• Note that to properly support the TK512 camera, this software must be rebuilt using the TK512 run-time library. This is new as of the 512 camera repair. The symptoms are: a 28-pixel wide overscan region in normal 512x512 frames, and high noise.
• Note that CameraMPP may or may not need to be called in gim_image_initCamera for the TK512 camera; this won't be clear until we have the proper RTL. Meanwhile, I have assumed that it will not need to be called.

1.0b11.x, 3/17/95

• Attempted to emulate CameraDigitizeArea, with no success. More careful testing is see whether the direct copy can be made to work like the original when no binning occurs. Use 1.0b9 instead!

1.0b10, 3/17/95

• Same as 1.0b10 but took out bin factor multipliers on xOffset, width, yOffset, height arguments to CameraDigitizeArea -- an experiment in binning. The results should tell me how to write my own version that does what I want. Use 1.0b9, instead!

1.0b9, 3/17/95

• Same as 1.0b8 but with CameraMPP called with TRUE instead of FALSE. This did the trick -- biases finally look normal.

1.0b8, 3/17/95

• Modified to use the 3/95 RTL again.
• Kurt of SpectraSource says the camera can be switched into a high gain/high bias mode, as opposed to the normal (low) gain and bias mode. He suspects that high gain is probably the default in the 3/95 RTL, which would explain the 10k count bias we were seeing. So at his recommendation I added a call to CameraMPP (which switches the gain, despite the name) calling it with FALSE. Note that I had to add the prototype for CameraMPP to the header file "camera.h".

1.0b7, 3/17/95

• Changed the expose command to use CameraExpose as the timer, since my own timer routine was crashing.
• Removed doRead, doFindstars; the TCC does these jobs better
• Changed the output of showimage to show the size of the image rather than the maximum coordinate -- size is more useful when viewing the images
• Added display of median and standard deviation to the output of findstars.
• Bug fix: flush was ignoring its argument
• setCamera now flushes once instead of 5 times (flushing takes 1 sec).

1.0b5? 6?, 3/15/95 if 5

• Added the argument nFlushes to flush.
• Added the command DoRead.
• Deleted the command DoCentroid.
• DoFindStars now flushes, in addition to the other operations.
• Changed the Expose command again, back to the 1.0b3 method (but with my own timer routine, since the one I was using had an upper limit of 65 seconds), in hopes it may eliminate the 10k bias counts we're seeing. If it doesn't, it's the new RTL and not the expose method causing the problem.

1.0b4, 3/13/95

• Switched to the 3/2/95 version of the SpectraSource HPC-1 run-time library (HPC-1 RTL).
• Started using the Expose command for the HPC-1 camera, exposing the shutter exactly as shown in the manual -- bizarre as it looks (it's not at all clear what the damn command is doing).
• Using Expose to do the timing may permit longer exposures. I was calling DelayMS from the HPC-1 RTL, which takes a 16-bit unsigned integer, limiting it to a bit over a minute. The SpectraSource HPC-1 RTL is awful.
• Removed the default exposure time.
• Stopped loadbin from clearing the camera info. Loadbin is only intended for debugging, and clearing the camera info prevents star finding.

1.0b3, 11/21/94

First release, by Russell Owen.