; HLPPLAYR
;---------------------------------------------------------------
;! OOP TV class demonstration task - run-time help
;# Task TV-APPL OOP INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2016, 2019
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
C-----------------------------------------------------------------------
TVFIDDLE
This option allows you to set the zoom factor and center to blow up the
data plot for more accurate cursor positioning.  It also allows you to
alter the look-up-tables.  Button A selects image enhancement, altering
between black-and-white and the AIPS-standard color contours.  Button B
increments the zoom or resumes zoom-center mode, while button C
decrements the zoom or resumes zoom-center mode.  Button D ends the
enhancing and returns to the menu.  Instructions appear on the message
screen.
C-----------------------------------------------------------------------
TVPSEUDO
This option allows you to set the color transfer function using the TV
cursor.  Button A loops through all possible RGB triangles, button B
selects a circle in hue (which is very useful for phase displays),
button C selects several color contours, and button D ends the
enhancement and returns to the menu.  As in AIPS, the TV cursor is used
to adjust the colors within the selected function.  Instructions appear
on the message screen.
C-----------------------------------------------------------------------
TVFLAME
This option allows you to set the color transfer function using the TV
cursor and a flame-like color scheme.  Buttons A and B cycle through the
sequence of all possible color combinations, while buttons C and D end
the enhancement and return to the menu.  The TV cursor X position
adjusts the image intensity at which the color turns more white, while
the Y position adjusts the way colors add (the gamma).  Instructions
appear on the message screen.
C-----------------------------------------------------------------------
TVZOOM
This option lets you set the TV zoom magnification factor and to set the
point about which the zoom takes place.  The cursor points at the zoom
center which will be  shifted to the center of the screen.  A hit on
buttons A or B increments the magnification factor and on button C
decrements the magnification factor in a circular fashion.  Hit button D
to exit.  Instructions appear on the message screen.  Note that the zoom
is turned off when the menu is displayed, but turned back on during
other interactive functions.
C-----------------------------------------------------------------------
TVTRAN
This option allows you to set the black-and-white transfer function
using the TV cursor to control intercept and slope.  Buttons A and B
turn a plot of the LUT on and off, button C reverses the sign of the
slope, and button D ends the enhancement and returns to the menu.
Instructions appear on the message screen.
C-----------------------------------------------------------------------
OFFCOLOR
This options turns of any color enhancements done in TVFIDDLE, TVPSEUDO,
or TVFLAME.  Has no effect if the image is in black and white.
C-----------------------------------------------------------------------
OFFTRAN
This option turns of any black-and-white enhancements done in TVFIDDLE
or TVTRANSF.
C-----------------------------------------------------------------------
OFFZOOM
This option resets any zoom factors and zoom center.  The image is
actually shown in zoom only when the menu selection is not going on.
Thus, the image is zoomed during cursor-value, Black-and-white and color
enhancement and window and box setting among other things.
C-----------------------------------------------------------------------
CURVALUE
To perform an interactive display of the pixel locations and values of
the image visible on the TV.  The X and Y pixel coordinates, the pixel
value, and the units of the pixel value are displayed in TV graphics
channels 3 and 4 at the upper left of the display.  The cursor position
determine which pixel is shown.  Button D ends the display and returns
to the menu.  Instructions appear on the message screen.  The pixel
values are read from disk and hence preserve accuracy.
C-----------------------------------------------------------------------
GAMMASET
This option allows you to display the effect of the "gamma" correction
on the TV display.  The value of the coefficient is displayed in the
upper left and modified with the cursor Y position.  Buttons A and B
reset the gamma to its original value and resume the interactive
display, Button C sets the current gamma correction into TV
"permanently" - if you know the AIPS Master password - and returns to
the menu.  Button D returns the TV gamma to normal and returns to the
menu.
C-----------------------------------------------------------------------
OFMCONTOUR
This option implements an interactive algorithm to modify the color
look-up tables (OFM) by inserting contours of constant color and
intensity.  The number of such contours is set by the SCALR1 adverb on
input and reset by the SET # CONT option.  The algorithm begins by
drawing a color wheel in a graphics channel, a list of the contours by
number down the left side of the screen, and a plot of color intensities
at the top.  Move the cursor to one of the contour numbers and select it
by hitting Button A (to set color), B (to set intensity), or C (to
revert to Black & white).  Move the cursor around the color wheel to
select color and saturation or move it up and down when setting
intensity.  Switch between those modes with buttons A and B.  Hit Button
C to set that contour so as to go on to another and hit Button D to
return to the menu, having altered only the selected contours.
C-----------------------------------------------------------------------
OFMWEDGE
This option implements an interactive algorithm to modify the color
look-up tables (OFM) by inserting wedges of constant color.  The number
of such contours is set by the SCALR1 adverb on input and reset by the
SET # CONT option.  The algorithm begins by drawing a color wheel in a
graphics channel, a list of the contours by number down the left side of
the screen, and a plot of color intensities at the top.  Move the cursor
to one of the contour numbers and select it by hitting Button A (to set
color), B (to set peak intensity) or C (to revert to Black & white).
Move the cursor around the color wheel to select color and saturation or
move it up and down when setting peak intensity.  Switch between those
modes with buttons A and B.  Hit Button C to set that contour or wedge
so as to go on to another and hit Button D to return to the menu, having
altered only the selected contour wedges.
C-----------------------------------------------------------------------
OFMADJUST
This option implements an interactive algorithm for changing the current
color lookup tables (OFM).  Here the OFM is considered to be a set of
piecewise linear functions.  The user specifies a range of input
intensities for the current piece and then a range of blue, green, and
red output intensities for that piece.  Note that all 3 colors do not
have to be specified for a given piece, and only those colors specified
will be changed.  The algorithm is menu and cursor driven.  Type HELP
OFMADJ in AIPS for details.
C-----------------------------------------------------------------------
OFM TWEAK
The option allows you to alter the current color table (OFM) by a linear
rescaling.  The cursor X position controls the intercept and the Y
position controls the slope of the rescaling.  Hit Button A to start
back at the original OFM and button D to return to the menu with the OFM
changed.
C-----------------------------------------------------------------------
OFM DIR
This option lists the OFM files owned by you and those provided with
AIPS in the standard AIPSOFM area.  This option is intended to remind
you of names to set with SET OFM NAME and then read with OFM GET.
C-----------------------------------------------------------------------
OFM GET
This option allows you to set the current color table (OFM) from a text
file specified by OFMFILE on input or by the SET OFM NAME option later.
C-----------------------------------------------------------------------
OFM PUT
This option allows you to record the current color table (OFM) in a text
file specified by OFMFILE on input or by the SET OFM NAME option later.
This option does not let you re-write the file; it defends you from
destroying a previous file of any sort.  Note that an OFM name such as
RAINBOW will initially get you the system provided rainbow colors.  You
may then modify them and do an OFM PUT with the same name.  It will
store a new file under your user number.  The next OFM GET will get
yours rather than the system's.
C-----------------------------------------------------------------------
OFM ZAP
This option allows you to delete the text file specified by OFMFILE on
input or by the SET OFM NAME option later.
C-----------------------------------------------------------------------
SET OFM NAME
This option lets you reset the name of an OFM text file, set initially
by the adverb OFMFILE.  This file name is used to read, write, and
destroy text files containing the color "OFM" look-up table.  Type in
the name with NO leading blanks and with some pre-set environment
variable name as (e.g.) MYOFMS:REDWHITE.BLUE, where MYOFMS was set prior
to running AIPS.  If you leave out the environment variable, the default
system area AIPSOFM is used.  It contains a variety of OFMs provided
originally by the Australia Telescope AIPS Group.  You may read these
OFMs and read/write/zap your own OFMs in this area.
C-----------------------------------------------------------------------
SET # CONT
This option lets you enter the number of steps (wedges or contours) used
by OFM CONTOUR and OFM WEDGE, initially set by the DOWEDGE adverb.  <= 0
and > 16 => 8.  You will be prompted on your main AIPS window with the
message "Enter number of contours/wedges <= 16'.  Type in the desired
number
C-----------------------------------------------------------------------
WEDGE WIDTH
This option lets you type in the desired width of step wedges in pixels
which was set initially by the SCALR1 adverb.  A value < 0 means to use
that width in absolute value after having you point out the desired
wedge location.  You will be in your main AIPS window with the message
"Enter width of step wedges, < 0 -> cursor sets wedge position" and
should enter a modest integer value.  If 0 is entered, -16 is used.
C-----------------------------------------------------------------------
EXIT
This option allows you to exit the task and return to AIPS.
C-----------------------------------------------------------------------
SET WINDOW
This option allows you to set the visible window into the current field.
It must encompass all Clean boxes and the TV loading procedure will
choose pixel increments large enough to load the full image window.  You
may wish to use a smaller window - if it includes all Clean boxes - in
order to use smaller pixel increments and hence to see more detail.
This option is similar to TVWINDOW in AIPS.  Any button marks the BLC on
the image, switching you to setting TRC.  Thereafter, buttons A and B
switch between setting BLC and TRC and buttons C and D set the window,
reload the image and return to the menu.  Instructions appear on the
message screen.  Note that the cursor position cannot be moved off the
currently visible image window.
C-----------------------------------------------------------------------
RESET WINDOW
This option lets you set the visible window into the current field to
include the whole field.  The image will be redisplayed using pixel
increments large enough to fit the full image into the TV memory (you
may have to increase the XAS window size to see it all - use F2).  You
may wish to do this to see the full image and/or to set a larger window
or larger Clean boxes than were available to you with the previous
window.
C-----------------------------------------------------------------------
TVBOX
This option lets you create up to 500 Clean boxes to restrict the search
for components in the current field.  The boxes may be circular or
rectangular.  While setting the lower left corner (or circle center) of
each box for the first time, button A or B will mark the point and
switch to setting the upper right corner (or radius) of the box.  Button
C will switch between setting a rectangle and setting a circle and
button D will delete the current partial box and return to the menu.
While setting the upper right corner (or radius) re-setting the lower
left or center, button A marks the current point (corner, center, or
radius) and switches to the opposite point (e.g. BLC <-> TRC, center <->
radius).  Button B marks the current point and switches to the next
(new) box, button C marks the current point and switches to a search
mode leading to the resetting of a previous box, and button D exits.  In
search mode, move the cursor to any lower left or upper right corner of
any already set rectangular box (or any center or any place on the
circumference of an already set circular box) and press button A or B to
reset that point or push button C to go on to the next box or button D
to go back to the menu.  The number of boxes is set by this function.
Instructions appear on the message screen and the TV cursor cannot be
moved to make a box extend beyond the (full) TV window.  NOTE: function
REBOX may be used to reset the results if needed.
C-----------------------------------------------------------------------
REBOX
This option lets you create up to 500 Clean boxes to restrict the search
for components in the current field.  The boxes may be circular or
rectangular.  Unlike TVBOX, REBOX begins by displaying any current Clean
boxes and then goes into the search mode to revise the current Clean
boxes.  While setting the lower left corner (or circle center) of each
box for the first time, button A or B will mark the point and switch to
setting the upper right corner (or radius) of the box.  Button C will
switch between setting a rectangle and setting a circle and button D
will delete the current partial box and return to the menu.  While
setting the upper right corner (or radius) re-setting the lower left or
center, button A marks the current point (corner, center, or radius) and
switches to the opposite point (BLC <-> TRC, center <-> radius).  Button
B marks the current point and switches to the next (new) box, button C
marks the current point and switches to a search mode leading to the
resetting of a previous box, and button D exits.  In search mode, move
the cursor to any lower left or upper right corner of any already set
rectangular box (or any center or any place on the circumference of an
already set circular box) and press button A or B to reset that point or
push button C to go on to the next box or button D to go back to the
menu.  The number of boxes is set by this function.  Instructions appear
on the message screen and the TV cursor cannot be moved to make a box
extend beyond the (full) TV window.  NOTE: function REBOX may be used to
reset the results if needed.
C-----------------------------------------------------------------------
TV WEDGE
This option allows you to draw an intensity wedge along the top side of
the currently selected image.  Only those image intensities loaded for
the image (selected by PIXRANGE and AXVAL) are displayed.  If the wedge
width is currently set < 0, you will be asked to select where to put the
bottom edge of the wedge by moving the cursor to the desired location
and pressing any button.  The wedge width is set by the SCALR1 adverb
and may be changed using the WEDGE WIDTH option.
C-----------------------------------------------------------------------
IMAGE WEDGE
This option allows you to draw an intensity wedge along the top side of
the currently selected image.  The full range of image intensities is
displayed.  If the wedge width is currently set < 0, you will be asked
to select where to put the bottom edge of the wedge by moving the cursor
to the desired location and pressing any button.  The wedge width is set
by the SCALR1 adverb and may be changed using the WEDGE WIDTH option.
C-----------------------------------------------------------------------
TV VERT WEDGE
This option allows you to draw an intensity wedge up the right-hand side
of the currently selected image.  Only those image intensities loaded
for the image (selected by PIXRANGE and AXVAL)are displayed.  If the
wedge width is currently set < 0, you will be asked to select where to
put the left-hand edge of the wedge by moving the cursor to the desired
location and pressing any button.  The wedge width is set by the SCALR1
adverb and may be changed using the WEDGE WIDTH option.
C-----------------------------------------------------------------------
IM VERT WEDGE
This option allows you to draw an intensity wedge up the right-hand side
of the currently selected image.  The full range of image intensities is
displayed.  If the wedge width is currently set < 0, you will be asked
to select where to put the left-hand edge of the wedge by moving the
cursor to the desired location and pressing any button.  The wedge width
is set by the SCALR1 adverb and may be changed using the WEDGE WIDTH
option.
C-----------------------------------------------------------------------
ERASE WEDGE
This option allows you to erase an intensity wedge.  If more than one is
visible, you will be asked to move the TV cursor to the desired wedge
and then hit any button to select it.
C-----------------------------------------------------------------------
LABEL IMAGE
This option allows you to label the currently selected image. The labels
are automatically displayed, but the display may be turned on and off
and cleared with the SHOW LABEL, HIDE LABEL, and CLEAR LABEL options,
respectively.  The labels are in celestial coordinates and the Clean
beam is displayed in the corner of the image selected by CBPLOT.
C-----------------------------------------------------------------------
LABEL WEDGE
This option allows you to label an intensity wedge.  If more than one is
visible, you will be asked to move the TV cursor to the desired wedge
and then hit any button to select it.  The labels are automatically
displayed, but the display may be turned on and off and cleared with the
next three options.
C-----------------------------------------------------------------------
SHOW LABEL
This option allows you to turn the display of image and wedge labels and
Clean boxes back on.  The TVBOX, REBOX, LABEL IMAGE and LABEL WEDGE
options turn the display on automatically.
C-----------------------------------------------------------------------
HIDE LABEL
This option allows you to turn off the graphics display of image and
wedge labels and Clean boxes without destroying the displays.  This is
good to do before BLINKs because the graphics planes slow the TV display
significantly.
C-----------------------------------------------------------------------
CLEAR LABEL
This option allows you to erase all image and wedge labels and the
display of Clean boxes (they are remembered however).
C-----------------------------------------------------------------------
SELECT IMAGE 1
This option allows you to change from the currently displayed field to
the first image.  The task will not display this option nor the
following options if only one image was given.
C-----------------------------------------------------------------------
SELECT IMAGE 2
This option allows you to change from the currently displayed field to
the second image.
C-----------------------------------------------------------------------
TVTRAN BOTH
This option allows you to change the transfer function of both images
identically, while viewing only the currently selected image.  The
cursor X position controls the intercept and the cursor Y position
controls the slope of the linear transfer function.  Buttons A and B
turn a plot of the function on and off, button C reverses the sign of
the slope, and button D returns to the menu.
C-----------------------------------------------------------------------
BLINK
This option allows you to blink the two images.  While blinking, the
cursor X position controls the blink rate and the cursor Y position
controls the relative proportion of the 2 images (center it for equal
proportions).  Buttons A and B select a TVTRANS of image 1 and image 2
at all times.  Button C selects TVTRANS of the next image during
blinking and reverses the sign of the transfer function slope during
enhancement.  Button D returns enhancements to blinking and blinking to
the menu.  As usual, in the TRVTRANS mode, the cursor X controls the
intercept and Y the slope of the linear transfer function.
C-----------------------------------------------------------------------
MANUAL BLINK
Similar to BLINK, but with a "manual blink" mode.  While auto blinking,
the cursor X position controls the blink rate and the Y controls the
relative proportions of the two images.  Button A selects the manual
blink mode and the next channel.  Button B returns to auto blinking,
Button C selects a TVTRANS of the next image, and button D returns to
the menu.  During the enhancement, Buttons A and B select images 1 and 2
resp. for individual enhancement, Button C reverses the sign of the
transfer function slope, and Button D returns to blinking.  As usual, in
the TRVTRANS mode, the cursor X controls the intercept and Y the slope
of the linear transfer function.
C-----------------------------------------------------------------------
