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:
- Opening the connection to a usable display tool (such as DS9).
- 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.
- 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.
- 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,
- open(imtdev=None):
- Open the default display device or the device specified in
'imtdev', such as 'inet:5137' or 'fifo:/dev/imt1o'.
- close():
- Close the display device defined by 'imtdev'. This must be
done before resetting the display buffer to a new size.
- display(pix, name=None,
bufname=None, z1=None, z2=None,
transform=None, scale=None, offset=None, frame=None):
- Display the scaled array in display tool (ds9/ximtool/...).
- Parameter definitions:
- name -- optional name
to pass along for identifying array
- bufname -- name of
buffer to use for displaying array to best match size of array (such as
'imt1024')
[default: 512x512 buffer
named 'imt512']
- z1,z2 --
minimum/maximum pixel value to display (float).
Not specifying values will default to the full range values of the
input array.
- transform -- Python
function to apply to array (function)
- scale --
multiplicative scale factor to apply to array (float/int)
- offset -- additive
factor to apply to array before scaling (float/int)
- frame -- image
buffer frame number in which to display array (integer)
- The display parameters set here will ONLY apply to the display
of the current array.
- readcursor(sample=0):
- Return a single cursor position from the image display. By
default, this operation will wait for a keystroke before returning the
cursor position. If 'sample' is set to 1, then it will NOT wait to read
the cursor. This will return a string containing: x,y,frame and key.
- help():
- print Version ID and this message.
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)