Initial commit

1 files changed, 287 insertions, 0 deletions

diff --git a/pkg/images/tv/iis/doc/cvl.hlp b/pkg/images/tv/iis/doc/cvl.hlp
new file mode 100644
index 00000000..cda07b07
--- /dev/null
+++ b/pkg/images/tv/iis/doc/cvl.hlp
@@ -0,0 +1,287 @@
+.help cvl Jul87 images.tv.iis
+.ih
+NAME
+cvl -- load images in image display
+.ih
+USAGE
+cvl image frame
+.ih
+PARAMETERS
+.ls image
+Image to be loaded.
+.le
+.ls frame
+Display frame to be loaded.
+.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
+Display the frame to be loaded?
+.le
+.ls fill = no
+Interpolate or block average 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.
+.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?
+.le
+.ls nsample_lines = 5
+Number of sample lines to use in the automatic intensity mapping algorithm.
+.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 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
+\fIzscale, 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 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 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 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
+\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 transformation is
+also the fastest.  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 two parameters,
+\fInsample_lines\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 \fIz1\fR and \fIz2\fR are set to
+the minimum and maximum image pixels 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.
+.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.
+
+A subset of the image is examined.  Approximately 600 pixels are
+sampled evenly over the image.  The number of lines is a user parameter,
+\fInsample_lines\fR.  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 \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 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
+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> cvl image1 1
+	cl> cvl 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> cvl image2 3 fill+ zscale-
+
+The next example makes image1 square and sets the intensity range explicitly.
+
+	cl> cvl 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> cvl.xsize=0.5
+	cl> cvl image1 fill+ xcen=0.25
+	cl> cvl image2 erase- fill+ xcen=0.75
+.fi
+.ih
+SEE ALSO
+display, magnify
+.endhelp