Numdisplay Usage

Description:

 Package for displaying numpy arrays in IRAF-compatible image display tool such as DS9 or XIMTOOL. This task can take advantage of the 'stdimage' IRAF environment variable if used under PyRAF, the Python interface to IRAF, but there is no requirement for running under PyRAF. 

Platform Support:

It has been successfully tested as a standalone Python module on Mac OS X, Linux, Solaris, and Windows.

General Instructions:

This task was designed to work strictly with numpy objects.  Images stored as FITS files can be read in using PyFITS, while the readgeis module distributed with PyFITS can be used to read in IRAF GEIS formatted images as numpy objects.  Alternatively, a numpy object could just as easily be created in memory directly and displayed using numdisplay. 

Displaying a numpy array object that has been read into or created in memory involves:
  1. Opening the connection to a usable display tool (such as DS9).
  2. Setting the display parameters for the array, such as min and max array value to be used for min and max grey scale level, along with any offset, scale factor and/or transformation function to be applied to the array.
  3. Applying any transformation to the input array. This transformation could be a simple numpy ufunc or a user-defined function that returns a modified array.
  4. Building the byte-scaled version of the transformed array and sending it to the display tool. The image sent to the display device will be trimmed to fit the image buffer defined by the 'imtdev' device from the 'imtoolrc' or the 'stdimage' variable under IRAF. If the image is smaller than the buffer, it will be centered in the display device.
NOTE:
All pixel positions reported back will be relative to the full image size.

Methods:

This package provides several methods for controlling the display of the numpy array; namely,


Example:

The user starts with a 1024x1024 array in the variable 'fdata'. This array has min pixel value of -157.04 and a max pixel value of 111292.02. The display tool DS9 has already been started from the host level and awaits the array for display. Displaying the array requires:
            >>> import numdisplay
            >>> numdisplay.display(fdata)
If there is a problem connecting to the DS9 application, then you may need to manually try to open the connection to the display device using:
            >>> numdisplay.open()
The numpy object can then be displayed in the normal manner. To bring out the fainter features, an offset value of 158 can be added to the array to allow a 'log' scaling can be applied to the array values using:
            >>> numdisplay.display(fdata,transform=numpy.log,offset=158.0)
To redisplay the image with default full-range scaling:
            >>> numdisplay.display(fdata)