NumDisplay Class Interface

This class provides the primary functionality for displaying numpy arrays in DS9 using the IIS protocol.

numdisplay: Package for displaying numpy arrays in IRAF-compatible
image display tool such as DS9 or XIMTOOL.

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, quiet=False, transform=None, scale=None, offset=None, frame=None)::
Display the scaled array in display tool (ds9/ximtool/…).
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.

Notes

Displaying a numpy array object 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.

    All pixel positions reported back will be relative to the full image size.

Examples

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, the connection can be manually started using:

>>> numdisplay.open()

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)

To redisplay using the IRAF display zscale algorithm, and with a contrast value steeper than the default value of 0.25:

>>> numdisplay.display(fdata, zscale=True, contrast=0.5)
class stsci.numdisplay.NumDisplay

Class to manage the attributes and methods necessary for displaying the array in the image display tool.

This class contains the methods:

open(imtdev=None):

close():

set(z1=None,z2=None,scale=None,factor=None,frame=None): reset(names=None)

display(pix, name=None, bufname=None):

readcursor():

checkDisplay()
close()

Close the display device entry.

display(pix, name=None, bufname=None, z1=None, z2=None, transform=None, zscale=False, contrast=0.25, scale=None, offset=None, frame=None, quiet=False)

Displays byte-scaled (UInt8) n to XIMTOOL device. This method uses the IIS protocol for displaying the data to the image display device, which requires the data to be byte-scaled.

If input is not byte-scaled, it will perform scaling using set values/defaults.

Parameters:
  • name (str) – optional name to pass along for identifying array
  • bufname (str) –

    name of buffer to use for displaying array (such as ‘imt512’). Other valid values include:

    'iraf': look for 'stdimage' and use that buffer or default to 'imt1024' [1024x1024 buffer]
None  : ignore 'stdimage' and automatically select a buffer matched to the size of the image.
  • z1,z2 (float) – minimum/maximum pixel value to display. Not specifying values will default to the full range values of the input array.
  • transform (function) – Python function to apply to array (function)
  • zscale (bool) – Specify whether or not to use an algorithm like that in the IRAF display task. If zscale=True, any z1 and z2 set in the call to display are ignored. Using zscale=True invalidates any transform specified in the call.
  • contrast (float (Default=0.25)) – Same as the contrast parameter in the IRAF display task. Only applies if zscale=True. Higher contrast values make z1 and z2 closer together, while lower values give a gentler (wider) range.
  • scale (float/int) – multiplicative scale factor to apply to array. The value of this parameter remains persistent, so to reset it you must specify scale=1 in the display call.
  • offset (float/int) – additive factor to apply to array before scaling. This value is persistent, so to reset it you have to set it to 0.
  • frame (int) – image buffer frame number in which to display array
  • quiet (bool (Default: False)) – if True, this parameter will turn off all status messages

Notes

The display parameters set here will ONLY apply to the display of the current array.

getHandle()
open(imtdev=None)

Open a display device.

readcursor(sample=0)

Return the cursor position from the image display.

reset(names=None)

Reset specific attributes, or all by default.

Parameters:names (string or list of strings) – names of attributes to be reset, separated by commas or spaces; the default is to reset all attributes to None
set(frame=None, z1=None, z2=None, contrast=None, transform=None, scale=None, offset=None)

Allows user to set multiple parameters at one time.