; HLPUFLAG
;---------------------------------------------------------------
;! Edit uv-data on a grid UFLAG - run-time help
;# Task UV Plot Editing interactive TV-APPL
;-----------------------------------------------------------------------
;;  Copyright (C) 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-----------------------------------------------------------------------
ABORT
This option tells UFLAG to stop now, ignoring any flagging which may
have been done.  No flag table is written and the FC table is deleted.
C-----------------------------------------------------------------------
FLAG + EXIT
This option tells UFLAG to terminate interactive operations.  It then
redoes the plot operation decrementing the counts in each pixel.  If a
pixel has been flagged then a line is written to the output flag table.
The output flag table starts with the input flag table, with the copy
operation being done only if there are flagged data.  The output flag
table also includes flags for any baseline flagged (over all times) and
and visibility flagged during the EXAMINE VIS, AUTO FLAG VIS, and
USER FLAG VIS operations.  The task then exits deleting the FC table.
C-----------------------------------------------------------------------
FLAG + REPEAT
This option tells UFLAG to suspend interactive operations.  It then
redoes the plot operation decrementing the counts in each pixel.  If a
pixel has been flagged then a line is written to the output flag table.
The output flag table starts with the input flag table, with the copy
operation being done only if there are flagged data.  The output flag
table also includes flags for any baseline flagged (over all times) and
any visibility flagged during the EXAMINE VIS, AUTO FLAG VIS, and
USER FLAG VIS operations. UFLAG then adjusts the input and output flag
table versions, remakes the images, and restarts the interactive
operation.  The FC table (if any) is deletd,
C-----------------------------------------------------------------------
FLAG + SWITCH
This option tells UFLAG to suspend interactive operations.  It then
redoes the plot operation decrementing the counts in each pixel.  If a
pixel has been flagged then a line is written to the output flag table.
The output flag table starts with the input flag table, with the copy
operation being done only if there are flagged data.  The output flag
table also includes flags for any baseline flagged (over all times) and
any visibility flagged during the EXAMINE VIS, AUTO FLAG VIS, and
USER FLAG VIS operations. UFLAG then adjusts the input and output flag
table versions, remakes the images, and restarts the interactive
operation.  The FC table (if any) is deleted.  Polarization switches
between RR and LL, between RL and LR, between XX and YY, between XY
and YX, between I and V, and between Q and U.
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, zooming and window and
box setting.  It is not zoomed during VIEW ONLY among other operations.
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-----------------------------------------------------------------------
OFF TRANS
This option turns off any black-and-white enhancements done in TVTRANSF.
C-----------------------------------------------------------------------
OFF COLOR
This option turns off any pseudo-coloring done in TVPSEUDO and TVPHLAME.
C-----------------------------------------------------------------------
TVTRANSF
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 terminal.
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 terminal.
C-----------------------------------------------------------------------
TVPHLAME
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-----------------------------------------------------------------------
SET PIXRANGE
This option lets you enter two values in the terminal window to control
the minimum and maximum image values displayed.  Values below the
minimum are shown as if at the minimum while values greater than the
maximum are shown as if at the maximum.  Note that this range limit
applies only to the image type (SCALAR, VECTOR, PHASE, SCAL-VEC)
currently being viewed and may be reset by entering a minimum >=
maximum (i.e. 0 0).
C-----------------------------------------------------------------------
LOAD LIN
This option re-loads the current image using a linear transfer function
from the image minimum to its maximum.  The image you are now viewing
was loaded with the LOG2 (extreme log) transfer function.
C-----------------------------------------------------------------------
LOAD LOG
This option re-loads the current image using a logarithmic transfer
function from the image minimum to its maximum.  The image you are now
viewing was loaded with the LIN (linear) transfer function.
C-----------------------------------------------------------------------
LOAD SQRT
This option re-loads the current image using a square root transfer
function from the image minimum to its maximum.  The image you are now
viewing was loaded with the LOG (logarithmic) transfer function.
C-----------------------------------------------------------------------
LOAD LOG2
This option re-loads the current image using a more extreme logarithmic
transfer function from the image minimum to its maximum.  The image you
are now viewing was loaded with the SQRT (square root) transfer
function.
C-----------------------------------------------------------------------
VIEW VECTOR
This option selects the vector averaged amplitude as the image to view
and edit.  It is reloaded to the TV immediately.  The image you are now
viewing is the SCALAR averaged image.
C-----------------------------------------------------------------------
VIEW PHASE
This option selects the vector averaged phase as the image to view and
edit.  It is reloaded to the TV immediately.  The image you are now
viewing is the VECTOR averaged image.
C-----------------------------------------------------------------------
VIEW SCALAR
This option selects the scalar averaged image as the image to view and
edit.  It is reloaded to the TV immediately.  The image you are now
viewing is the SCALAR-VECTOR averaged image.
C-----------------------------------------------------------------------
VIEW SCAL-VEC
This option selects the difference between the scalar averaged and
vector averaged images as the image to view and edit.  It is reloaded
to the TV immediately.  Note that this difference image is always zero
at pixels having only one sample contributing, but can reflect
significant discrepancies between samples averaged in a pixel.  The
image you are now viewing is the PHASE averaged image.
C-----------------------------------------------------------------------
VIEW ONLY
This function allows you to select an intensity range as the only
intensities displayed.  The TV cursor begins at the right-hand edge of
the plotted step wedge and is setting the upper limit of this view-only
range.  Move the cursor to change that upper limit.  Hit buttons A or
B to switch to setting the lower limit and back again.  The current
range is shown in the upper left corner of the TV screen and
illustrated with black-and-white look-up tables used by UFLAG.  Hit
button C to set the view-only range or button D to exit without setting
the view-only range.  Once set, this range may be used to flag all
pixels having values in this range.  Note that this function displays
all pixels outside the value range as black, a different behavior than
SET PIXRANGE will give you.  The view only range is reset when you
select a different image to view or option VIEW ALL.
C-----------------------------------------------------------------------
VIEW ALL
This option tells UFLAG to display all grey-scale intensities scaled
according to the transfer function and any SET PIXRANGE.
C-----------------------------------------------------------------------
FLAG PTS OFF
This option is visible when the flagged pixels are shown marked with
cyan (graphics plane 4).  That display may be distracting, so this
option allows you to turn off the marking of flagged pixels.
C-----------------------------------------------------------------------
FLAG PTS ON
This option is visible when the flagged pixels are not shown except as
black points similar to unsampled pixels.  This option allows you to
re-display the flagged pixels marked with cyan (graphics plane 4).
C-----------------------------------------------------------------------
SET WINDOW
This option allows you to limit the editing and display to a rectangular
portion of the full plot.  First move the cursor to set the bottom left
corner of the plot, then hit button A or B to begin setting the upper
right corner.  Hit buttons A or B to switch corners.  Hit buttons C or
D to return to the menu mode (after the selected window is displayed).
The image will try to fill the TV screen, using a pixel replication
factor (integer), the same one on both the X and Y axes.
C-----------------------------------------------------------------------
RESET WINDOW
This option resets the window to include the full plot in the display
and editing.  The full plot is re-displayed.  If it does not all fit
on the TV (at full size), then the plot is shown with averaged pixels
and you are told to select a sub-image to display and edit.
C-----------------------------------------------------------------------
FLAG POINT
This option allows you to flag pixels not already flagged.  Move the
cursor to the pixel to be flagged - the coordinates of the pixel in both
pixel and physical units, the value of the pixel in the selected image,
and up to two baselines contributing to the pixel are shown in the upper
left.  To flag a point hit button A, B, or C.  The pixel will change
color after which you may flag more pixels (buttons A or B) or select
a new menu option (button C).  Button D allows you to return to the
menu without flagging the current point.
C-----------------------------------------------------------------------
FLAG AREA
This option allows you to flag pixels within rectangular areas.  Move
the cursor to select the bottom left pixel of the area, then hit button
A to set the top right corner of the area.  Hit button A as needed to
reset the opposite corners.  Hit button B or C to flag all unflagged
pixels in the rectangle.  The pixels will change color after which you
may set a new rectangle (button B) or select a new menu option (button
C).  Button D allows you to return to the menu without flagging the
current rectangle.
C-----------------------------------------------------------------------
FLAG FAST
This option allows you to flag individual pixels rapidly.  Move the
cursor to the first point to be flagged and hit one of buttons A, B, or
C.  Any further button hit will return to the main menu.  Any unflagged
pixel selected by the cursor (remember - left mouse button depressed
or click it on the point) will be flagged, changing color as it is
flagged.
C-----------------------------------------------------------------------
FLAG BASELINE
This option allows you to type in 2 numbers giving the two antennas of
the baseline you wish to flag.  If one of the numbers is 0, all
baselines to the second number will be flagged.  This operation enters
the desired baseline(s) into a list first and then examines all plotted
points to find any that are affected by the baseline(s).  The attached
baseline info is modified to record the flagging and, if there remain
no unflagged baselines attached to the point, its color is changed to
that used for flagged data.  WARNING: the displayed pixel value is not
changed (i.e. the flagged baseline is not removed from the average) by
this operation unless no valid baselines remain.
C-----------------------------------------------------------------------
UNFLAG POINT
This option allows you to unflag pixels that are already flagged.  Move
the cursor to the pixel to be unflagged - the coordinates of the pixel
in both pixel and physical units, the value of the pixel in the
selected image, and up to two baselines contributing to the pixel are
shown in the upper left.  To unflag a point hit button A, B, or C.  The
pixel will change color after which you may unflag more pixels (buttons
A or B) or select a new menu option (button C).  Button D allows you
to return to the menu without unflagging the current point.
C-----------------------------------------------------------------------
UNFLAG AREA
This option allows you to unflag pixels within rectangular areas.  Move
the cursor to select the bottom left pixel of the area, then hit button
A to set the top right corner of the area.  Hit button A as needed to
reset the opposite corners.  Hit button B or C to unflag all flagged
pixels in the rectangle.  The pixels will change color after which you
may set a new rectangle (button B) or select a new menu option (button
C).  Button D allows you to return to the menu without unflagging the
current rectangle.
C-----------------------------------------------------------------------
UNFLAG FAST
This option allows you to unflag individual pixels rapidly.  Move the
cursor to the first point to be unflagged and hit one of buttons A, B,
or C.  Any further button hit will return to the main menu.  Any
flagged pixel selected by the cursor (remember - left mouse button
depressed or click it on the point) will be unflagged, changing color
as it is unflagged.
C-----------------------------------------------------------------------
UNFLAG BASEL
This option allows you to type in 2 numbers giving the two antennas of
the baseline you previously did a FLAG BASELINE upon and which you now
wish to undo.  If one of the numbers is 0, all baselines to the second
number will be unflagged.  This operation removes the desired
baseline(s) from the flagged list first and then examines all plotted
points to find any that are affected by the baseline(s).  The attached
baseline info is modified to record the unflagging and and if there are
now unflagged baselines attached to the point, its value is changed to
that used for good data.  WARNING: if the displayed pixel value is
restored, the still-flagged baselines, if any, are not removed from the
average value displayed.
C-----------------------------------------------------------------------
EXAMINE VIS
This function starts an interaction where you select a pixel by
positioning the TV cursor and hitting buttons A, B, or C.  The task then
rereads the visibility records involved, performs the calibration and
gridding functions, and lists all samples contributing to the pixel.
It then asks for a sample number to flag and, if you enter a valid
number, it marks that sample and asks again for another to flag (if
there are any more).  Enter 0 to stop flagging.  If there are
remaining unflagged pixels, they are averaged and the image(s)
updated.  If there are no more, the pixel is set to empty in the
images.  All flagged visibilities are written to a flag command file
(FC table) which will be applied to the output flag (FG) table on
"FLAG + EXIT" or "FLAG + REPEAT" or "FLAG + SWITCH".
C-----------------------------------------------------------------------
USER FLAG VIS
This option asks you to enter two values for the range in value of the
pixels in the current window that you wish to consider.  Then it asks
for the minimum and maximum acceptable visibility amplitudes and minimum
and maximum acceptable visibility phases.  An "incorrect" answer on
phase (e.g. 0 0) causes it to use -200 to 200 degrees and hence not to
flag on phase.  Finally it asks whether to consider flagged pixels
(answer -1), unflagged pixels (answer 1), or both (answer 0).  The task
then examines all the visibilities entering each pixel in the window
within the requested value range.  Any visibility below the minimum
acceptable amplitude or above the maximum will be recorded in the flag
command file (FC table) which will be applied to the output flag (FG)
table on "FLAG + EXIT" or "FLAG + REPEAT" or "FLAG + SWITCH".  The
remaining "good" visibilities are averaged and the scalar average,
vector average, their difference, and the phase are placed appropriately
in the images in RAM and on the TV.  This operation can be very slow,
so progress messages are given approximately every two minutes.
C-----------------------------------------------------------------------
AUTO FLAG VIS
This option is like USER FLAG VIS except that it sets the limits itself.
This option does nothing when viewing PHASE or SCALAR-VECTOR as it
chooses bad limits - you can set good ones in this mode with USER FLAG
VIS.  If ISCALIB was <= 0, it examines only unflagged pixels greater
than the mean + APARM(1) times the rms and flags visibilities greater
than the median + APARM(2) times the rms.  If ISCALIB was > 0, it
examines pixels less than the median minus APARM(1) times the rms and
pixels above the mean + APARM(1) times the rms.  Visibilities with
amplitudes less than the median minus APARM(2) times the rms and and
greater than the median plus APARM(2) times the rms are flagged as are
visibilities with phases greater than APARM(3) times the rms
divided by the median (in absolute value, in radians).  APARM has
defaults of 3, 3, and 4.  The median, mean, and rms are displayed
above the step wedge on the TV.  The task then examines all the
visibilities entering each pixel in the window within the requested
value range.  Any visibility outside the acceptable range of amplitude
or phase will be recorded in the flag command file (FC table) which
will be applied to the output flag (FG) table on "FLAG + EXIT" or
"FLAG + REPEAT" or "FLAG + SWITCH".  The remaining "good" visibilities
are averaged and the scalar average, vector average, phase, and their
difference are placed appropriately in the images in RAM and on the TV.
This operation can be very slow, so progress messages are given
approximately every two minutes.
C-----------------------------------------------------------------------
FLAG ALL
If a "VIEW ONLY" range has been set, this option will appear.  It allows
you to flag all pixels in the image having value in the displayed image
within the "VIEW ONLY" range.  That range is remembered in a separate
list after the flagging and the "VIEW ONLY" range is reset to extreme
values.  Each image type is kept separate.
C-----------------------------------------------------------------------
FLAG ALL WIN
If a "VIEW ONLY" range has been set and a sub-image is displayed, this
option will appear.  It allows you to flag all pixels in the visible
sub-image having value in the displayed image within the "VIEW ONLY"
range.  That range is remembered in a separate list after the flagging
and the "VIEW ONLY" range is reset to extreme values.  Each image type
is kept separate.
C-----------------------------------------------------------------------
UNDO FLAG ALL
If a "FLAG ALL" or "FLAG ALL WIN" operation has been performed for the
present image type, this option will appear.  It allows you to undo
that operation.  If more than one such operation has been performed,
it will list the ones which have been done and ask which one you wish
to undo.  It will then unflag all flagged pixels in the image having
values within the selected range. That range is then removed from the
list of applied ranges.  Each image type is kept separate.
C-----------------------------------------------------------------------
UNDO FLAG WIN
If a "FLAG ALL" or "FLAG ALL WIN" operation has been performed for the
present image type and a sub-image is displayed, this option will
appear.  It allows you to undo that operation.  If more than one such
operation has been performed, it will list the ones which have been
done and ask which one you wish to undo.  It will then unflag all
flagged pixels in the visible sub-image having values within the
selected range.  That range remains in the list of applied ranges.
Each image type is kept separate.
C-----------------------------------------------------------------------

