; HLPCLEAN
;---------------------------------------------------------------
;! Cleaning tasks  - run-time help
;# TASK AP IMAGING OOP CALIBRATION INTERACTIVE TV-APPL
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1997, 2000, 2004, 2006-2007, 2009, 2014-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.
C-----------------------------------------------------------------------
OFFTRANS
This option turns of any black-and-white enhancements done in TVFIDDLE
or TVTRANSF.
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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
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.
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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
UNBOX
This option lets you create up to 4 or more (up to 4096 if there are
fewer than 64 fields) Clean boxes to restrict the search for
components in the current field to exclude the areas specified.  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
(leaving zero or more boxes) 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.  There is no DELBOX or REBOX for these UNClean boxes
C-----------------------------------------------------------------------
TVBOX
This option lets you create up to 256 or more (up to 4096 if there are
fewer than 64 fields) Clean boxes to restrict the search for
components in the current field to include only the areas specified.
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 (leaving zero or more boxes) 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 and DELBOX to delete one or more of the boxes if needed.
Since TVBOX deletes any pre-existing boxes, IMAGR, SCIMG, and SCMAP now
ask for permission to do so.  If you do not answer Y or y, REBOX is
done instead.  DELBOX may be used to delete some boxes in a field,
without deleting all of them.
C-----------------------------------------------------------------------
REBOX
This option lets you create up to 256 or more (up to 2048 if there are
fewer than 64 fields) 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-----------------------------------------------------------------------
DELBOX
This option lets you delete some or all of the existing Clean boxes in
the current field.  DELBOX shows you all the current boxes in the
current field or at least those boxes that appear partially in the
selected window of the current field.  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-----------------------------------------------------------------------
CHECK BOXES
This option causes a check of all boxes to see if some boxes in one
field overlap a box in another field.  If they do, the smaller of the
two boxes is removed from the list.  This check is not critical in
OVERLAP >= 2 mode, but is made available via the TV.  It is so critical
in OVERLAP < 2 mode, that it is done automatically but it may be
helpful to run it while interacting with your images.  NOTE: there is
no difficulty with boxes overlapping within the same facet.
C-----------------------------------------------------------------------
CONTINUE CLEANING
This option allows you to resume the current Clean operation without
waiting for the time-out interval to expire.
C-----------------------------------------------------------------------
STOP CLEANING
This option allows you to request that the current Clean operation be
declared complete at this point.  Components will be restored to the
residual images (if requested) and the output images written.  If more
channels, self-cal loops or whatever are to be done, they will take
place as if the Clean had ended for normal reasons (iteration or flux
limits).
C-----------------------------------------------------------------------
ABORT TASK
This option allows you to request that the task finish as soon as
possible with an abnormal termination.
C-----------------------------------------------------------------------
TURN OFF DOTV
This option lets you turn off the display and interaction with the Clean
residual images.  It may be turned back on only with the TELL <taskname>
verb in AIPS.
C-----------------------------------------------------------------------
REMAKE IMAGES
This option allows you to have the task re-compute images of all fields
using the current residual UV data.  It will then re-display one of the
residual images (initially), but allow you to view all fields and to set
Clean windows for all fields.  This is important since the selection of
which field to do next is based on the maxima only in the Clean windows.
This option is offered only when OVERLAP=2 and DO3DIMAG is true.
C-----------------------------------------------------------------------
FORCE BGC CLEAN
This option allows you to request the Clark Clean algorithm rather than
the Steer-Dewdney-Ito method of Cleaning.  The option will be displayed
only if the SDI method was used used during the last major cycle.  SDI
will be used in the next major cycle only if appropriate given the value
of IMAGRPRM(4) and the ratio of the number of pixels with residuals over
half of the peak residual and only if this option has not been selected.
C-----------------------------------------------------------------------
FORCE SDI CLEAN
This option allows you to require the next major cycle to use the Steer-
Dewdney-Ito Clean method rather than the Clark Clean method.  The option
will be offered only if IMAGRPRM(4) was not zero so that SDI Clean will
be done when the fraction of pixels in the Clean windows with residuals
greater than half of the peak residual > IMAGRPRM(4).  To have the SDI
method used no matter what that fraction is, specify this option.
C-----------------------------------------------------------------------
FILTER COMPS
This option will be offered only if IMAGRPRM(8) was not zero.  It
allows you to request that all Clean Component files be examined at this
moment and any weak, isolated components eliminated.  After this
filtering, the new Clean components model is subtracted from the
original UV data and new residual images for all fields are computed.
The filtering will be done as well at the end of the Clean, but doing
it after the Clean is well along (so that weak and isolated are
meaningful) but before it finishes does allow Clean to adjust to the
revised model.  Clean may well put more components on the sources after
a filtering has removed the isolated components.
C-----------------------------------------------------------------------
FORCE A FIELD
This option allows you to enter the field number to be Cleaned in the
next major cycle, overriding the program's chosen field.  The task will
prompt you in the main window to enter a field number.  Because it must
use the main window, this option is only offered if AIPS has not been
restarted.  This will be the case if you run IMAGR with DOWAIT true or
if you are using more than 64 fields.  The task will recompute the
forced field, display it on the TV, and allow you to reset its Clean
boxes.  This is a way to recompute one field rather than having to
recompute all fields and you can force another field when the forced
field is displayed.
C-----------------------------------------------------------------------
STOP FLD <n>
This option allows you to mark the specified field as needing no more
cleaning for the moment.  This option only appears in OVERLAP=2 mode.
To allow IMAGR to Clean this field again, you must first REMAKE IMAGES
and then SELECT FIELD for this field.  Then the ALLOW FLD option for
the field will appear.
C-----------------------------------------------------------------------
ALLOW FLD <n>
This option allows you to mark the specified field as needing more
Cleaning now.  This option only appears in OVERLAP=2 mode and only after
the particular field was STOPed earlier.  The option will only appear
if this field is again accessible - so REMAKE IMAGES and then
SELECT FIELD for this field.  Then the ALLOW FLD option for the field
will appear.
C-----------------------------------------------------------------------
SELECT NEW FIELD
This option is displayed only if there are more than 64 fields being
imaged and available to you at the moment.  It allows you to select
which of those fields you wish to view and interact with next.
C-----------------------------------------------------------------------
SELECT FLD <n>
This option allows you to change from the currently displayed field to
the SPECIFIED image field of the Clean.  The task will display only as
many of these select options as are useful.
C-----------------------------------------------------------------------
THIS IS FLD <n>
This option is offered only when OVERLAP=2 and DO3DIMAG is true.  It is
simply to tell you which field is displayed and does nothing if selected
with Buttons A, B, or C.
C-----------------------------------------------------------------------
