IRAF help page for package images.tv, program display

• image
• frame
• erase = yes
• border_erase = no
• select_frame = yes
• repeat = no
• fill = no
• zscale = yes
• contrast = 0.25
• zrange = yes
• nsample_lines = 5
• xcenter = 0.5, ycenter = 0.5
• xsize = 1, ysize = 1
• xmag = 1., ymag = 1.
• order = 0
• z1, z2
• ztrans = linear
• linear
• log
• none
• user
• lutfile =

display image frame

image

frame

erase = yes

border_erase = no

select_frame = yes

repeat = no

fill = no

zscale = yes

contrast = 0.25

zrange = yes

nsample_lines = 5

xcenter = 0.5, ycenter = 0.5

xsize = 1, ysize = 1

xmag = 1., ymag = 1.

order = 0

z1, z2

ztrans = linear

log

none

user

lutfile =

The specified image is loaded into the specified frame of the standard image display device ("stdimage"). For devices with more than one frame it is possible to load an image in a frame different than that displayed on the monitor. An option allows the loaded frame to become the displayed frame. The previous contents of the frame may be erased (which can be done very quickly on most display devices) before the image is loaded. Without erasing, the image replaces only those pixels in the frame defined by the display window and spatial mapping described below. This allows displaying more than one image in a frame. An alternate erase option erases only those pixels in the defined display window which are not occupied by the image being loaded. This is generally slower than erasing the entire frame and should be used only if a display window is smaller than the entire frame.

The image is mapped both in intensity and in space. The intensity is mapped from the image pixel values to the range of display values in the device. Spatial interpolation maps the image pixel coordinates into a part of the display frame called the display window. Many of the parameters of this task are related to these two transformations.

A display window is defined in terms of the full frame. The lower left corner of the frame is (0, 0) and the upper right corner is (1, 1) as viewed on the monitor. The display window is specifed by a center (defaulted to the center of the frame (0.5, 0.5)) and a size (defaulted to the full size of the frame, 1 by 1). The image is loaded only within the display window and does not affect data outside the window; though, of course, an initial frame erase erases the entire frame. By using different windows one may load several images in various parts of the display frame.

If the option fill is selected the image is spatially interpolated to fill the display window in its largest dimension (with an aspect ratio of 1:1). When the display window is not automatically filled the image is scaled by the magnification factors (which need not be the same) and centered in the display window. If the number of image pixels exceeds the number of display pixels in the window only the central portion of the image which fills the window is loaded. By default the display window is the full frame, the image is not interpolated (no filling and magnification factors of 1), and is centered in the frame. The spatial interpolation algorithm is described in the section MAGNIFY AND FILL ALGORITHM.

There are several options for mapping the pixel values to the display values. There are two steps; mapping a range of image intensities to the full display range and selecting the mapping function or transformation. The mapping transformation is set by the parameter ztrans. The most direct mapping is "none" which loads the image pixel values directly without any transformation or range mapping. Most displays only use the lowest bits resulting in a wrap-around effect for images with a range exceeding the display range. This is sometimes desirable because it produces a contoured image which is not saturated at the brightest or weakest points. This is the fastest method of loading the display. Another transformation, "linear", maps the selected image range linearly to the full display range. The logrithmic transformation, "log", maps the image range linearly between 1 and 1000 and then maps the logrithm (base 10) linearly to the full display range. In the latter transformations pixel values greater than selected maximum display intensity are set to the maximum display value and pixel values less than the minimum intensity are set to the minimum display value.

Methods for setting of the range of image pixel values, z1 and z2, to be mapped to the full display range are arranged in a heirarchy from an automatic mapping which gives generally good result for typical astronomical images to those requiring the user to specify the mapping in detail. The automatic mapping is selected with the parameter zscale. The automatic mapping algorithm is described in the section ZSCALE ALGORITHM and has two parameters, nsample_lines and contrast.

When ztrans = user, a look up table of intensity values and their corresponding greyscale levels is read from the file specified by the lutfile parameter. From this information, a piecewise linear look up table containing 4096 discrete values is composed. The text format table contains two columns per line; column 1 contains the intensity, column 2 the desired greyscale output. The greyscale values specified by the user must match those available on the output device. Task showcap can be used to determine the range of acceptable greyscale levels. When ztrans = user, parameters zscale, zrange and zmap are ignored.

If the zscale algorithm is not selected the zrange parameter is examined. If zrange is yes then the minimum and maximum pixel values in the image are estimated and z1 and z1 are set to those values, respectively. This insures that the full range of the image is displayed but is generally slower than the zscale algorithm (because all the image pixels must be examined) and, for images with a large dynamic range, will generally show only the brightest parts of the image.

Finally, if the zrange algorithm is not selected the user specifies the values of z1 and z2 directly.

Often several images are to be loaded with the same intensity and spatial transformations. The option repeat repeats the transformations from the previous image loaded.

The zscale algorithm is designed to display the image values near the median image value without the time consuming process of computing a full image histogram. This is particularly useful for astronomical images which generally have a very peaked histogram corresponding to the background sky in direct imaging or the continuum in a two dimensional spectrum.

A subset of the image is examined. Approximately 600 pixels are sampled evenly over the image. The number of lines is a user parameter, nsample_lines. The pixels are ranked in brightness to form the function I(i) where i is the rank of the pixel and I is its value. Generally the midpoint of this function (the median) is very near the peak of the image histogram and there is a well defined slope about the midpoint which is related to the width of the histogram. At the ends of the I(i) function there are a few very bright and dark pixels due to objects and defects in the field. To determine the slope a linear function is fit with iterative rejection;

I(i) = intercept + slope * (i - midpoint)

If more than half of the points are rejected then there is no well defined slope and the full range of the sample defines z1 and z2. Otherwise the endpoints of the linear function are used (provided they are within the original range of the sample):

	z1 = I(midpoint) + (slope / contrast) * (1 - midpoint)
	z2 = I(midpoint) + (slope / contrast) * (npoints - midpoint)

As can be seen, the parameter contrast may be used to adjust the contrast produced by this algorithm.

The spatial interpolation algorithm magnifies (or demagnifies) the image along each axis by the desired amount. The fill option is a special case of magnification in that the magnification factors are set by the requirement that the image just fit the display window in its maximum dimension with an aspect ratio (ratio of magnifications) of 1. There are two requirements on the interpolation algorithm; all the image pixels must contribute to the interpolated image and the interpolation must be time efficient. The second requirement means that simple linear interpolation is used. If more complex interpolation is desired then tasks in the IMAGES package must be used to first interpolate the image to the desired size before loading the display frame.

If the magnification factors are greater than 0.5 (sampling step size less than 2) then the image is simply interpolated. However, if the magnification factors are less than 0.5 (sampling step size greater than 2) the image is first block averaged by the smallest amount such that magnification in the reduced image is again greater than 0.5. Then the reduced image is interpolated to achieve the desired magnifications. The reason for block averaging rather than simply interpolating with a step size greater than 2 is the requirement that all of the image pixels contribute to the displayed image. If this is not desired then the user can explicitly subsample using image sections. The effective difference is that with subsampling the pixel-to-pixel noise is unchanged and small features may be lost due to the subsampling. With block averaging pixel-to-pixel noise is reduced and small scale features still contribute to the displayed image.

For the purpose of these examples we assume a display with four frames, 512 x 512 in size, and a display range of 0 to 255. Also consider two images, image1 is 100 x 200 with a range 200 to 2000 and image2 is 2000 x 1000 with a range -1000 to 1000. To load the images with the default parameters:

	cl> display image1 1
	cl> display image2 2

The image frames are first erased and image1 is loaded in the center of display frame 1 without spatial interpolation and with the automatic intensity mapping. Only the central 512x512 area of image2 is loaded in display frame 2

To load the display without any intensity transformation:

cl> cvl image1 1 ztrans=none

The next example interpolates image2 to fill the full 512 horizontal range of the frame and maps the full image range into the display range. Note that the spatial interpolation first block averages by a factor of 2 and then magnifies by 0.512.

cl> display image2 3 fill+ zscale-

The next example makes image1 square and sets the intensity range explicitly.

cl> display image1 4 zscale- zrange- z1=800 z2=1200 xmag=2

The next example loads the two images in the same frame side-by-side.

	cl> display.xsize=0.5
	cl> display image1 fill+ xcen=0.25
	cl> display image2 erase- fill+ xcen=0.75

BUGS The "repeat" option is not implemented.

cvl, magnify, implot,