Initial commit

1 files changed, 555 insertions, 0 deletions

diff --git a/pkg/images/tv/doc/display.hlp b/pkg/images/tv/doc/display.hlp
new file mode 100644
index 00000000..9e8670c4
--- /dev/null
+++ b/pkg/images/tv/doc/display.hlp
@@ -0,0 +1,555 @@
+.help display Mar97 images.tv
+.ih
+NAME
+display -- Load and display images in an image display
+.ih
+USAGE
+display image frame
+.ih
+PARAMETERS
+.ls image
+Image to be loaded.
+.le
+.ls frame
+Display frame to be loaded.
+.le
+
+.ls bpmask = "BPM"
+Bad pixel mask.  The bad pixel mask is used to exclude bad pixels from the
+automatic intensity mapping algorithm.  It may also be displayed as an
+overlay or to interpolate the input image as selected by the \fIbpdisplay\fR
+parameter.  The bad pixel mask is specified by a pixel list image
+(.pl extension) or an regular image.  Values greater than zero define the
+bad pixels.  The special value "BPM" may be specified to select a pixel list
+image defined in the image header under the keyword "BPM".  If the
+bad pixel mask cannot be found a warning is given and the bad pixel mask
+is not used in the display.
+.le
+.ls bpdisplay = "none" (none|overlay|interpolate)
+Type of display for the bad pixel mask.  The options are "none" to not
+display the mask, "overlay" to display as an overlay with the colors given
+by the \fIbpcolors\fR parameter, or "interpolate" to linearly interpolate
+across the bad pixels in the displayed image.  Note that the bad is still
+used in the automatic intensity scaling regardless of the type of display
+for the bad pixel mask.
+.le
+.ls bpcolors = "red"
+The mapping between bad pixel values and display colors or intensity values
+when the bad pixels are displayed as an overlay.  There are two forms,
+explicit color assignments for values or ranges of values, and expressions.
+These is described in the OVERLAY COLOR section.
+.le
+
+.ls overlay = ""
+Overlay mask to be displayed.  The overlay mask may be a pixel list image
+(.pl extension) or a regular image.  Overlay pixels are identified by
+values greater than zero.  The overlay values are displayed with a mapping
+given by the \fIocolors\fR parameter.  If the overlay cannot be found a
+warning is given and the overlay is not displayed.
+.le
+.ls ocolors = "green"
+The mapping between bad pixel values and display colors or intensity values
+when the bad pixels are displayed as an overlay.  There are two forms,
+explicit color assignments for values or ranges of values, and expressions.
+These is described in the OVERLAY COLOR section.
+.le
+
+.ls erase = yes
+Erase frame before loading image?
+.le
+.ls border_erase = no
+Erase unfilled area of window in display frame if the whole frame is not
+erased?
+.le
+.ls select_frame = yes
+Select the display frame to be the same as the frame being loaded?
+.le
+.ls repeat = no
+Repeat the previous spatial and intensity transformations?
+.le
+.ls fill = no
+Interpolate the image to fit the display window?
+.le
+.ls zscale = yes
+Apply an automatic intensity mapping algorithm when loading the image?
+.le
+.ls contrast = 0.25
+Contrast factor for the automatic intensity mapping algorithm.
+If a value of zero is given then the minimum and maximum of the
+intensity sample is used.
+.le
+.ls zrange = yes
+If not using the automatic mapping algorithm (\fIzscale = no\fR) map the
+full range of the image intensity to the full range of the display?  If the
+displayed image has current min/max values defined these will be used to
+determine the mapping, otherwise the min/max of the intensity sample will
+be used.  The \fIMINMAX\fR task can be used to update the min/max values in
+the image header.
+.le
+.ls zmask = ""
+Pixel mask selecting the sample pixels for the automatic or range intensity
+mapping algorithm.  The pixel mask may be a pixel list image (.pl
+extension), a regular image, or an image section.  The sample pixels are
+identified by values greater than zero in the masks and by the region specified
+in an image section.  If no mask specification is given then a uniform sample
+of approximately \fInsample\fR good pixels will be used.  The \fInsample\fR
+parameter also limits the number of sample pixels used from a mask.  Note that
+pixels identified by the bad pixel mask will be excluded from the sample.
+.le
+.ls nsample = 1000 (minimum of 100)
+The number of pixels from the image sampled for computing the automatic
+intensity scaling.  This number will be uniformly sampled from the image
+if the default \fIzmask\fR is used otherwise the first \fInsample\fR
+pixels from the specified mask will be used.
+.le
+.ls xcenter = 0.5, ycenter = 0.5
+Horizontal and vertical centers of the display window in normalized
+coordinates measured from the left and bottom respectively.
+.le
+.ls xsize = 1, ysize = 1
+Horizontal and vertical sizes of the display window in normalized coordinates.
+.le
+.ls xmag = 1., ymag = 1.
+Horizontal and vertical image magnifications when not filling the display
+window.  Magnifications greater than 1 map image pixels into more than 1
+display pixel and magnifications less than 1 map more than 1 image pixel
+into a display pixel.
+.le
+.ls order = 0
+Order of the interpolator to be used for spatially interpolating the image.
+The current choices are 0 for pixel replication, and 1 for bilinear
+interpolation.
+.le
+.ls z1, z2
+Minimum and maximum image intensity to be mapped to the minimum and maximum
+display levels.  These values apply when not using the automatic or range
+intensity mapping methods.
+.le
+.ls ztrans = "linear"
+Transformation of the image intensity levels to the display levels.  The
+choices are:
+.ls "linear"
+Map the minimum and maximum image intensities linearly to the minimum and
+maximum display levels.
+.le
+.ls "log"
+Map the minimum and maximum image intensities linearly to the range 1 to 1000,
+take the logarithm (base 10), and then map the logarithms to the display
+range.
+.le
+.ls "none"
+Apply no mapping of the image intensities (regardless of the values of
+\fIzcale, zrange, z1, and z2\fR).  For most image displays, values exceeding
+the maximum display value are truncated by masking the highest bits.
+This corresponds to applying a modulus operation to the intensity values
+and produces "wrap-around" in the display levels.
+.le
+.ls "user"
+User supplies a look up table of intensities and their corresponding
+greyscale values.  
+.le
+.le
+.ls lutfile = ""
+Name of text file containing the look up table when \fIztrans\fR = user.
+The table should contain two columns per line; column 1 contains the
+intensity, column 2 the desired greyscale output.
+.le
+.ih
+DESCRIPTION
+The specified image and overlay mask are 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 bad pixel mask may be specified to be displayed as an overlay or to
+interpolate the displayed image.  It is also used to exclude bad pixels
+from the automatic intensity scaling.  The bad pixel mask is specified by
+the parameter \fIbpmask\fR and the display mode by the \fIbpdisplay\fR
+parameter.  The overlay display option uses the \fIbpcolors\fR parameters
+to specify a color mapping as described in the OVERLAY COLOR section.
+Interpolation consists of linear interpolation across columns if the mask
+value is one, across lines if the mask value is two, or across the shortest
+direction for other values.  This interpolation is done on the input data
+before any spatial interpolation and filling is done.  It does not modify
+the input data.  The task \fBfixpix\fR provides the same algorithm to fix
+the data in the image.
+
+An overlay mask may be specified by the \fIoverlay\fR parameter.  Any
+value greater than zero in the overlay mask will be displayed in the color or
+intensity specified by the \fIocolor\fR parameter (see the OVERLAY COLOR
+section).
+
+Note that bad pixel masks in "pixel list" format are constrained to
+non-negative values.  When an image is used instead of a pixel list the
+image is internally converted to a pixel list.  Negative values are
+set to zero or good pixels and positive real values are truncated to
+the nearest integer.
+
+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 specified 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 \fIfill\fR is selected the image and overlay mask are
+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
+\fIztrans\fR.  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 logarithmic transformation, "log", maps the image range
+linearly between 1 and 1000 and then maps the logarithm (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, \fIz1\fR and
+\fIz2\fR, to be mapped to the full display range are arranged in a
+hierarchy 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
+\fIzscale\fR.  The automatic mapping algorithm is described in the section
+ZSCALE ALGORITHM and has three parameters, \fIzmask\fR, \fInsample\fR and
+\fIcontrast\fR.
+
+When \fIztrans\fR = user, a look up table of intensity values and their
+corresponding greyscale levels is read from the file specified by the
+\fIlutfile\fR 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 \fIshowcap\fR can be used to determine the range of acceptable
+greyscale levels.  When \fIztrans\fR = user, parameters \fIzscale\fR,
+\fIzrange\fR and \fIzmap\fR are ignored.
+
+If the zscale algorithm is not selected the \fIzrange\fR parameter is
+examined.  If \fIzrange\fR is yes then the minimum and maximum pixel values
+in the image are taken from the image header or estimated from the
+intensity sample and \fIz1\fR and \fIz1\fR 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 \fIz1\fR and \fIz2\fR directly.
+
+Often several images are to be loaded with the same intensity and spatial
+transformations.  The option \fIrepeat\fR repeats the transformations from
+the previous image loaded.
+.ih
+ZSCALE ALGORITHM
+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.
+
+The sample of pixels, specified by values greater than zero in the sample mask
+\fIzmask\fR or by an image section, is selected up to a maximum of
+\fInsample\fR pixels.  If a bad pixel mask is specified by the \fIbpmask\fR
+parameter then any pixels with mask values which are greater than zero are not
+counted in the sample.  Only the first pixels up to the limit are selected
+where the order is by line beginning from the first line.  If no mask is
+specified then a grid of pixels with even spacing along lines and columns
+that make up a number less than or equal to the maximum sample size is
+used.
+
+If a \fIcontrast\fR of zero is specified (or the \fIzrange\fR flag is
+used and the image does not have a valid minimum/maximum value) then
+the minimum and maximum of the sample is used for the intensity mapping
+range.
+
+If the contrast is not zero the sample 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 \fIz1\fR and \fIz2\fR.
+Otherwise the endpoints of the linear function are used (provided they are
+within the original range of the sample):
+
+.nf
+        z1 = I(midpoint) + (slope / contrast) * (1 - midpoint)
+        z2 = I(midpoint) + (slope / contrast) * (npoints - midpoint)
+.fi
+
+As can be seen, the parameter \fIcontrast\fR may be used to adjust the contrast
+produced by this algorithm.
+.ih
+MAGNIFY AND FILL ALGORITHM
+The spatial interpolation algorithm magnifies (or demagnifies) the image
+(and the bad pixel and overlay masks) 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.
+.ih
+OVERLAY COLORS
+The masks specified by the \fIbpmask\fR and \fIoverlay\fR parameters may be
+displayed as color overlays on the image data.  The non-zero pixels in the
+mask are assigned integer display values.  The values may fall in the same
+range, 1 to 200, as the mapped image pixel data values and will behave the
+same way as the pixel values when the display map is interactively adjusted.
+Values of 0 and 201 to 255 may be used and depend on the display server and
+display resource definitions.  The expected or standard server behavior is
+that 0 is the background color and 201 to 255 are various colors with the
+lower numbers being the more standard primary colors.  The expected colors
+are:
+
+.nf
+        Value   Color               Value   Color
+        201     white (cursor)      210     coral
+        202     black (background)  211     maroon
+        203     white               212     orange
+        204     red                 213     khaki
+        205     green               214     orchid
+        206     blue                215     turquoise
+        207     yellow              216     violet
+        208     cyan                217     wheat
+        209     magenta
+.fi
+
+The values 201 and 202 are tied to the cursor and background resource
+colors.  These are generally white and black respectively.  Values above 217
+are not defined and depend on the current state of the color table for the
+window system.
+
+The mapping between mask values and overlay colors are specified
+by the \fIbpcolors\fR and \fIocolors\fR parameters.  There are two mapping
+syntax, a list and an expression.
+
+The list syntax consists of
+a comma delimited set of values and assignments with one of the following
+forms.
+
+.nf
+    color
+    maskvalue=color
+    maskvalue-maskvalue=color
+.fi
+
+where color may be a color name, a color value, or value to be added or
+subtracted to the mask value to yield a color value.  Color names may be
+black, white, red, green, blue, yellow, cyan, magenta, or transparent with
+case ignored and abbreviations allowed.  Transparent does the obvious of
+being invisible.  These values are based on the default resource colors for
+the display servers (as shown above) and any custom definitions may result
+in incorrect colors.
+
+The color values are unsigned integers (no '+' or '-') or values to be added
+or subtracted are given as signed integers.  The first form provides the
+default intensity or color for all mask values.  Note that if no default
+color is specified the default will be white.  The other forms map a mask
+value or range of mask values to a color.  In a list the last color defined
+for the default or mask value will be used.
+
+The addition or subtraction from mask values provides a mechanism to have
+the bad pixel or overlay masks encode a variety of overlay colors.  Note
+that to display the mask values directly as colors one would use the color
+value "+0".  Subtraction may produce values less than zero which then
+are not visible; i.e. equivalent to "transparent".
+
+The following examples illustrate the features of the syntax.
+
+.nf
+    ocolors=""          Display in default white
+    ocolors="red"       Display in red
+    ocolors="+0"        Display mask values as color values
+    ocolors="+200"      Display mask values offset by 200
+
+    ocolors="205,1=red,2=yellow,10-20=cyan,30-40=+100,50-100=transparent"
+.fi
+
+The last example has a default color of 205, mask values of 1 are
+red, mask values of 2 are yellow, mask values of 10 to 20 are cyan,
+and mask values of 30 to 40 are displayed as intensities 130 to 140.
+
+Expressions are identified by being enclosed in parentheses.
+This uses the general IRAF expression syntax (see \fBexpressions\fR).
+The mask values are referenced by the character $.  The same named
+colors (black, white, red, green, blue, yellow, cyan, magenta,
+and transparent) may be used in place of color values. Expressions
+must evaluate to integer values.  To avoid needing special handling of
+input mask values of zero, all pixels with input mask values of zero
+are not shown regardless of the expression value.
+
+There are currently two function extensions, "colors" and "acenum".
+In both functions the first and only required argument, arg1, is an integer
+value.  Typically this will '$' or a function based on '$'.
+
+The "colors" function maps input values with a modulus type behavior.  The
+optional second argument, arg2, is a color value for mapping zero.  As noted
+above, if the input mask value is zero it will not be displayed.  However,
+functions applied to non-zero input mask values may return a value of zero
+which may then be displayed with the specified color.  The default is
+transparent.  The next two optional arguments (arg3 and arg4) define a color
+range with defaults of 204 to 217.  If only arg3 is specified then
+arg4 takes the value of arg3, thus having the effect of a constant
+output color.  Positive values of the first argument are mapped to a color
+value by
+
+.nf
+    if arg1 is 0:       result = arg2
+    if arg1 greater 0:  result = arg3 + mod ($-1, arg4-arg3+1)
+    otherwise:          result = arg1
+.fi
+
+This function is primarily used to make colorful displays of regions
+defined with different mask values.
+
+The "acenum" function handles \fBace\fR package object detection masks
+which include bit flags.  Each object in the mask has an object number
+with value greater than 10.  Values less than 10 are passed along during
+detection and generally identify detector or saturated bad pixels.
+Along with the object number there may be zero or more bit flags
+set.  This function removes the bit flags and returns the mask number.
+The optional second argument, arg2, is a string of letters which selects
+pixels with certain sets of bit flags.  The bit flags are:
+
+.nf
+    B -- a bad pixel treated as a good for detection
+    D -- original detection (i.e. without G or S flag)
+    E -- edge pixel used for displaying detection isophotes
+    F -- object contains a bad pixel
+    G -- grown pixel
+    S -- pixel not assigned to an object during splitting
+.fi
+
+The default of arg2 is "BDEG" which essentially returns all pixels
+in an object.
+
+The acenum function also returns 0 for the pixels with values between
+one and ten and -1 for the pixels not selected by the flags.  The value
+of zero may be made visible using the colors function.  The two functions
+are often used in concert:
+
+.nf
+    (colors(acenum($)))
+    (colors(acenum($),black))
+    (colors(acenum($,'E'),red,green)
+.fi
+
+Note that when filling and anti-aliasing the behavior of the overlay
+colors may be different than intended.
+.ih
+EXAMPLES
+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:
+
+.nf
+        cl> display image1 1
+        cl> display image2 2
+.fi
+
+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.
+
+.nf
+        cl> display.xsize=0.5
+        cl> display image1 fill+ xcen=0.25
+        cl> display image2 erase- fill+ xcen=0.75
+.fi
+.ih
+REVISIONS
+.ls DISPLAY V2.11
+The bad pixel mask, overlay mask, sample mask, and overlay colors
+parameters and functionality have been added.  The "nsample_lines"
+parameter is now an "nsample" parameter.
+
+Bugs in the coordinate system sent to the image display for cursor
+readback were fixed.
+.le
+.ih
+BUGS
+The "repeat" option is not implemented.
+.ih
+SEE ALSO
+cvl, magnify, implot, minmax, fixpix
+.endhelp