; HLPFILIT
;---------------------------------------------------------------
;! Interactive Clean box file editing with image display - run-time help
;# Task TV-APPL OOP INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 2009, 2016
;;  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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
OFFTRAN
This option turns of any black-and-white enhancements done in TVFIDDLE
or TVTRAN.
C-----------------------------------------------------------------------
OFFCOLOR
This options turns of any color enhancements done in TVFIDDLE, TVPSEUDO,
or TVFLAME.  It does not turn off any enhancements done by TVTRAN, just
the coloring.
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.  If you want to combine image enhancement with coloring use
TVTRAN and TVPSEUDO or TVFLAME.
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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
REBOX
This option lets you create up to 4096 Clean boxes to restrict the
search for components in the current facet.  The boxes may be circular
or rectangular.  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: functions REBOX and DELBOX
may be used to reset the results if needed.
C-----------------------------------------------------------------------
DELBOX
This option lets you delete some or all of the existing Clean boxes in
the current facet.  DELBOX shows you all the current boxes in the
current facet or at least those boxes that appear partially in the
selected window of the current facet.  It begins in the search mode.
Move the cursor to the lower left or upper right corner of rectangular
boxes or the center or anywhere on the circumference of circular boxes
and press buttons A or B.  The selected box will change color.  If it
is the desired box, hit button A and it will disappear and DELBOX will
return to the search mode.  If you want to keep the box, hit buttons
B, C or D and it will return to the initial color and be retained.  If
you hit button B or C, DELBOX returns to the search mode.  Button D
exits at any time with no more deletions.
C-----------------------------------------------------------------------
AUTOBOX
This option looks at the full image of the present facet.  It starts by
blanking out the edges and corner, keeping an inscribed ellipse whose
diameter is the image size minus 2*IM2PARM(6).  It then blanks out all
current boxes.  Having done this, it determines the rms and peak of
the "residual" image.  It finds islands of emmision greater than
IM2PARM(2)*rms, keeps those islands that have a peak pixel above both
IM2PARM(3)*rms and IM2PARM(4)*peak residual, and turns the strongest
IM2PARM(1) of these into boxes.  Each of these boxes is expanded by
IM2PARM(5) pixels (allowed range -1 to 6) in all directions beyond the
basic island size.  Islands that are only 1 pixel on one of the sides
are made into boxes only if their peaks are rather larger than the
above cutoffs.  You can repeat AUTOBOX until all islands are too weak
or too small to meet the criteria.
C-----------------------------------------------------------------------
AUTOBOX PARMS
This option prompts you on the terminal for all of the IM2PARM
auto-boxing parameters.  The current value is shown in brackets, but
you must enter a number to respond to each question.  Entering 0 for
most questions causes that parameter to remain unchanged.  The expand
boxes question has 0 as a legitimate answer so you would have to
answer -2 to get an unchanged value.  The parameters are requested in
the order of IM2PARM and the full set entered is repeated in the
message window.
C-----------------------------------------------------------------------
DEL ALL BOXES
This option allows you to set the current number of boxes in the current
facet to zero.  REBOX and AUTOBOX may then be used to make boxes, if
needed, in the current facet.
C-----------------------------------------------------------------------
RESET BOXES
This option resets the number of boxes and their description to what
they were when work on this facet was begun THIS TIME.  The resetting
would allow recovery from an erroneous deletion or excessive AUTOBOX
operation.  Note that any selection of NEXT FACET, LAST FACET, or ENTER
FACET freezes the current description of this facet's boxes and one
cannot return to a previous description.  When you start on a facet, the
boxes for that facet at that moment are remembered in a special memory
and may be used to replace any new set of boxes for that facet until
you leave or attempt to leave that facet for another.  At that time,
this special memory is overwritten by the boxes of the new facet.
C-----------------------------------------------------------------------
CHECK BOXES
This option examines all boxes one facet at a time to see if they
overlap boxes in any of the other facets.  If so, the smaller of the
two boxes is deleted.  The routine uses fiducial points: the center and
4 corners of rectangles and the center and 8 points around the
circumference of circles.  If more than 1 fiducial point in a box lies
within another box in another facet then the two are taken to be in
conflict and the smaller one is deleted from the list.  Note that
Cleaning the same source at the same time from two separate facets will
cause difficulties - OVERLAP >= 2 mode avoids this by Cleaning one facet
at a time, but OVERLAP < 2 mode does all facets at once and can have
trouble with overlapped boxes.  NOTE: there is no difficulty with boxes
overlapping within the same facet.
C-----------------------------------------------------------------------
NEXT FACET
This option changes from the current facet image to the facet numbered
one higher, wrapping back to facet 1 when it exceeds NFIELD.  The new
facet image is loaded to the TV, either in a regular TV load to channel
one if the image will fit fully on the TV, or in a "roam" mode if the
image is larger in one or both dimensions.  While roaming, the cursor
position controls the portion of the image that is visible.  You may
zoom the image with Buttons A or B and reduce the image zoom with Button
C, but this zooming may confuse the "captured" image.  Use TVZOOM
instead after the image is "captured."  Hitting Button D turns off the
roam mode and the currently visible image will be "captured" as a simple
image loaded to image plane 1 for processing by REBOX, DELBOX, etc.  Use
REROAM to change the selected subimage to allow editing of all Clean
boxes for the facet.  This operation freezes the current facet's box
description and enables the box description of the new facet to be
RESET BOXES.
C-----------------------------------------------------------------------
LAST FACET
This option changes from the current facet image to the facet numbered
one lower, wrapping back to facet NFIELD when it drops below 1.  The new
facet image is loaded to the TV, either in a regular TV load to channel
one if the image will fit fully on the TV, or in a "roam" mode if the
image is larger in one or both dimensions.  While roaming, the cursor
position controls the portion of the image that is visible.  You may
zoom the image with Buttons A or B and reduce the image zoom with Button
C, but this zooming may confuse the "captured" image.  Use TVZOOM
instead after the image is "captured."  Hitting Button D turns off the
roam mode and the currently visible image will be "captured" as a simple
image loaded to image plane 1 for processing by REBOX, DELBOX, etc.  Use
REROAM to change the selected subimage to allow editing of all Clean
boxes for the facet.    This operation freezes the current facet's box
description and enables the box description of the new facet to be
RESET BOXES.
C-----------------------------------------------------------------------
ENTER FACET
This option allows you to switch to any of the available facets.  The
program will prompt you for a number and then will switch to that new
facet number.  Note that selecting this option will reset the remembered
boxes used by RESET BOXES even if you enter the facet number of the
current facet.p
C-----------------------------------------------------------------------
REROAM
This option causes a resumption of the roam operation begun when the
facet image was first loaded and is available only when the facets are
larger than the TV display on one or both axes.  While roaming, the
cursor position controls the portion of the image that is visible.
You may zoom the image with Buttons A or B and reduce the image zoom
with Button C, but this zooming may confuse the "captured" image.  Use
TVZOOM instead after the image is "captured."  Hitting Button D turns
off the roam mode and the currently visible image will be "captured"
as a simple image loaded to image plane 1 for processing by REBOX,
DELBOX, etc.  Use REROAM again to change the selected subimage to allow
editing of all Clean boxes for the facet.
C-----------------------------------------------------------------------
EXIT
This option causes all the edited Clean boxes (and those that were not
changed) to be written to OBOXFILE.  Then the task exits.
C-----------------------------------------------------------------------
