PyGuide: Image Analysis for Telescope Guiding

PyGuide offers image analysis routines for telescope guiding, including a star finder, centroider and star shape fitter. The algorithms are designed to work well with partial images, e.g. where much of the image of a star is lost down a spectrograph slit or off the edge of a coherent fiber optic bundle.

PyGuide was written by Russell E. Owen, based on algorithms and code by Jim Gunn, and with help from Connie Rockosi and Craig Loomis. The current version may be downloaded here, and older versions here.


Requirements and Installation

To install and use PyGuide you must have the following:

To install, use the standard python "distutils" procedure:

% python build
% sudo python install

To install information for UPS, the Fermilab/Princeton runtime loader, include --ups on the install line, e.g.:

% sudo python install --ups

User's Guide

The main routines are:

See Masks and Coordinates for some important information about using these routines. For details about a particular package or subroutine, get help in the usual way (or read the comments at the beginning of each routine):

>>> import PyGuide
>>> help(PyGuide.centroid)
>>> help(PyGuide)

Other files of interest (in the source distribution, not installed):


A mask is required for images that have missing light, e.g. due to light going down a slit on a slitviewer image, or truncated by the edge of a fiber bundle. The mask tells PyGuide what portions of the image to ignore.

A mask consists of a boolean array (of type numarray.Bool) with the same dimensions as the image. A value of True masks out the corresponding pixel in the image, making PyGuide ignore that data.

Warning: to get good results, you must mask out all bad areas of the image, including transitional areas where the image is dimmer but not completely dark. Thus, for example, you should mask out the edges of a slit (where you can still see some light but some of it is lost). If you fail to mask out transitional data, you will get garbage out of the centroider.

Hints For Centroiding

PyGuide.centroid is capable of doing a very good job of centroiding. However, it is also capable of returning garbage of you are not careful. To get good results:

Coordinate Systems

PyGuide uses x to mean the rows of a CCD (parallel to the shift register) and y the columns. Also, by default:

Another common convention is that used by iraf and ds9: the center of the lower left pixel is (1.0, 1.0) and the lower left corner of the image is (0.5, 0.5). PyGuide.ImUtil includes converters between ds9 position and xy position: ds9PosFromXYPos and xyPosFromDS9Pos. In addition, if you really dislike the zero-point convention for xy position, you can change it. The zero point is defined by PyGuide.Constants.PosMinusIndex. To modify PosMinusIndex, edit PyGuide/python/PyGuide/ and reinstall the software. PyGuide ships with PosMinusIndex = 0.5; to use the ds9 convention, change it to 1.0. (Note that ds9PosFromXYPos and xyPosFromDS9Pos work correctly regardless of how you set PosMinusIndex.)

In addition to xy position, PyGuide internally makes use of ij position: rounding ij position to the nearest integer gives the array index of the pixel containing that position. The main reason for ij position is because numarray swaps indices (like the C language): the x axis is the second axis of a numarray array. Thus conversion between ij and xy position involves swapping axes and a small offset (PosMinusIndex).

PyGuide.ImUtil offers routines to convert between ds9 position, xy position, ij position and ij index. If you are doing any array manipulation in your own code, you will probably find these very useful.



PyGuide is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

PyGuide is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with PyGuide; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA