Package numdisplay

source code

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

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.

    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/...).
            name -- optional name to pass along for identifying array

            bufname -- name of buffer to use for displaying array
                       (such as 'imt512')
                        '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  -- 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)

            zscale -- 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 -- same as the contrast parameter in the IRAF display
                        task.  Only applies if zscale=True.  Default value = 0.25.
                        Higher contrast values make z1 and z2 closer together,
                        while lower values give a gentler (wider) range.

            scale  -- multiplicative scale factor to apply to array (float/int)
                      Persistent, so to reset it you must specify scale=1 in the
                      display call.

            offset -- additive factor to apply to array before scaling (float/int)
                      This value is persistent, so to reset it you have to set it
                      to 0.

            frame  -- image buffer frame number in which to display array
                        (integer)
            
            quiet  -- if True (default: False), will turn off 
                        all status messages (bool)

            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 stsci.numdisplay as 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)

Imports: n, math, string, displaydev, _zscale, imconfig, zscale