; HLPZAMAN
;---------------------------------------------------------------
;! Fits 1-dimensional Zeeman model to absorption data - run-time help
;# TASK MODELING INTERACTIVE TV-APPL POLARIZATION SPECTRAL
;-----------------------------------------------------------------------
;;  Copyright (C) 2017, 2020
;;  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-----------------------------------------------------------------------
EXIT
This option causes the interactive portion of ZAMAN to finish.  The
task then resumes, AIPS, releases the TV device, and, if DOOUTPUT is
greater than zero, writes the output cataloged images.  The residual is
written if DOOUTPUT = 4, 5, 6, or 7; the parameter images are written if
DOOUTPUT = 2, 3, 6, or, 7; and the corrected V image is written if
DOOUTPUT = 1, 3, 5, or 7.
C-----------------------------------------------------------------------
SET MAX RES
This option allows you to specify the maximum residual for acceptable
solutions.  You will be prompted in the terminal window to enter one
value in the units of the input image.  The REDO ALL and FLAG ALL
operations use this value to test whether a solution should be redone
or flagged, resp.  A value of 0 or less will cause the test for peak
residual to be ignored.  The current value of this parameter is
displayed above the menu.
C-----------------------------------------------------------------------
SET GAIN RANGE
This option allows you to specify the minimum and maximum gain parameter
in acceptable solutions.  One range is all that is needed.  The REDO ALL
and FLAG ALL operations use these values to test whether a solution
should be redone or flagged, resp.  When the maximum is less than or
equal the minimum, the test on gain is ignored.  The current values of
these parameters are displayed above the menu.
C-----------------------------------------------------------------------
SET FIELD RANGE
This option allows you to specify the minimum and maximum field value
for the components in acceptable solutions.  One range for each of the
components will be USED.  With OPTYPE = 'GAUS', the number of components
is the maximum number of Gaussians fit to the I image.  For other
OPTYPEs, there is only 1 component.  Units are pixels.  The REDO ALL
and FLAG ALL operations use these values to test whether a solution
should be redone or flagged, resp.  When the maximum is less than or
equal the minimum the test on field for the specific Gaussian component
is ignored.  The current values of these parameters are displayed above
the menu.  You may enter fewer than 2 * NGAUSS values.  In this case,
the values entered for the first Gaussian are used for the values that
you did not enter.  This may or may not be a good idea.
C-----------------------------------------------------------------------
SET MAX ERR FLD
This option allows you to specify the maximum uncertainty in component
field for acceptable solutions.  One maximum for each of the components
will be used - one for all OPTYPEs except 'GAUS' which requires the
maximum number of Gaussians fit to the I image.  The REDO ALL and
FLAG ALL operations use these values to test whether a solution should
be redone or flagged, resp.   A value of 0 or less will cause the test
for the specific Gaussian component to be ignored.  The current values
of these parameters are displayed above the menu.  You may enter fewer
than NGAUS values, in which case, the value entered for the first
Gaussian will be used for those values you did not enter.  This may be
okay.
C-----------------------------------------------------------------------
REDO ALL
This option allows you to try to improve selected solutions.  The
operation examines all pixels for which there is a solution.  If (1)
the gain is outside the range of gains, (2) the field of any component
is outside the range of fields for that component, (3) the uncertainty
in the field of any component is greater than the maximum for that
component, or (4) the peak residual after the fit components are
subtracted is greater than the maximum residual, the solution for that
row of the input image is done over.
C-----------------------------------------------------------------------
FLAG ALL
This option allows you to flag selected solutions.  The operation
examines all pixels for which there is a solution.  If (1) the gain is
outside the range of gains, (2) the field of any component is outside
the range of fields for that component, (3) the uncertainty in the
field of any component is greater than the maximum for that component,
or (4) the peak residual after the fit components are subtracted is
greater than the maximum residual, the solution for that row of the
input image is marked as failed.
C-----------------------------------------------------------------------
OFF ZOOM
This option in the main menu allows you to turn off the zoom function
selected with TVZOOM in the image display menu.
C-----------------------------------------------------------------------
OFF TRANSFER
This option in the main menu turns of any black-and-white enhancements
done by TVTRANSF and any coloring done by TVPSEUDO or TVPHLAME in the
image display menu.
C-----------------------------------------------------------------------
SET DOOUTPUT
The option cycles the value of the DOOUTPUT adverb from 0 through 3
and back to 0.  The value of DOOUTPUT, displayed at the top of the TV
screen, when the EXIT option is selected determines whether the residual
image is written to disk (DOOUTPUT = 4, 5, 6, or 7), whether the
parameter images are written to disk (DOOUTPUT = 2, 3, 6, or 7), and
whether the corrected V image is written to disk (DOOUTPUT = 1, 3, 5,
or 7).
C-----------------------------------------------------------------------
ADD TO LIST
This option prompts you in the terminal window to enter 2 integers which
specify the X, Y pixel coordinates in the output image of a pixel for
which you would like to revisit the fit.  You can prepare a list of
pixels for revisiting using this option or CURVALUE in the image display
menu.  You can list these pixels (SHOW LIST) and you can the repeat the
fitting of them with REDO LIST or simply flag them out with FLAG LIST.
If you want to remove a pixel from the list, enter its pixel coordinates
with negative signs.  Note that the list may include pixels for which
there is not currently a solution.
C-----------------------------------------------------------------------
SHOW LIST
This option displays in the message window the current list of output
image pixels which will be revisited with the REDO LIST and FLAG LIST
options.  ADD TO LIST may be used to add a pixel to or remove a pixel
from this list.
C-----------------------------------------------------------------------
REDO LIST
The output image pixels in the current list are revisited to see if it
is possible to improve upon the current solutions (if any).  The usual
options to mark BAD, to REDO, to QUIT, and to turn off the TV
interaction are all offered.  The list is processed in inverse order
and its length reduced as one goes.  Thus a QUIT in the middle will
leave the first part of the list untouched.
C-----------------------------------------------------------------------
FLAG LIST
The output pixels in the current list are revisited in the solutions
table and those solutions are marked as failed.  The list is reset
after this operation.
C-----------------------------------------------------------------------
SHOW IMAGE G
This option allows you to enter an image display mode while displaying
an image of the gain.  The value range in the image is displayed on the
message terminal and at the top of the YV in input image units. The
image display mode offers a menu including OFF TRANSF, OFF COLOR,
TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN.  All are
the familiar operations except that CURVALUE allows you to add to a
pixel list for later re-examination of the solutions.  You can also
choose to re-load the image to the TV with a selection of transfer
functions.
C-----------------------------------------------------------------------
SHOW IMAGE EG
This option allows you to enter an image display mode while displaying
an image of the uncertainty in the gain.  The value range in the image
is displayed on the message terminal and at the top of the TV in input
image units.  The image display mode offers a menu including OFF TRANSF,
 OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN.
All are the familiar operations except that CURVALUE allows you to add
to a pixel list for later re-examination of the solutions.  You can also
choose to re-load the image to the TV with a selection of transfer
functions.
C-----------------------------------------------------------------------
SHOW IMAGE F<n>
These options allow you to enter an image display mode while displaying
an image of the field of the selected component in pixels.  The value
range in the image is displayed on the message terminal and at the top
of the TV.  The image display mode offers a menu including OFF TRANSF,
OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM, CURVALUE, and RETURN.
All are the familiar operations except that CURVALUE allows you to add
to a pixel list for later re-examination of the solutions.  You can also
choose to re-load the image to the TV with a selection of transfer
functions.
C-----------------------------------------------------------------------
SHOW IMAGE EF<n>
These options allow you to enter an image display mode while displaying
an image of the uncertainty in the field value of the selected component
in pixels .  The value range in the image is displayed on the message
terminal and at the top of the TV.  The image display mode offers a menu
including OFF TRANSF, OFF COLOR, TVTRANSF, TVPSEUDO, TVPHLAME, TVZOOM,
CURVALUE, and RETURN.  All are the familiar operations except that
CURVALUE allows you to add to a pixel list for later re-examination of
the solutions.  You can also choose to re-load the image to the TV
with a selection of transfer functions.
C-----------------------------------------------------------------------
RETURN
This option returns from the image display menu to the primary menu to
select a different image to display, to set data selection values, and
to revisit selected solutions in order to modify or flag them.
C-----------------------------------------------------------------------
LOAD AS LN
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 L2 (extreme log) transfer function.
C-----------------------------------------------------------------------
LOAD AS SQ
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 LN (linear) transfer function.
C-----------------------------------------------------------------------
LOAD AS LG
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 SQ (square root) transfer function.
C-----------------------------------------------------------------------
LOAD AS L2
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 LG (logarithmic) transfer function.
C-----------------------------------------------------------------------
SET WINDOW
This option turns on a standard TVWINDOW operation to set the lower left
corner and upper right corner of a sub-image that you would like to view
in more detail.  Buttons A and B switch between corners and buttons C
and D set the desired window which is immediately displayed.
C-----------------------------------------------------------------------
RESET WINDOW
This option returns the image display to the full image.  This option is
available in the edit screen and the image display screen.
C-----------------------------------------------------------------------
OFF TRANSF
This option turns of any black-and-white enhancements done in TVTRANSF.
C-----------------------------------------------------------------------
OFF COLOR
This options turns of any color enhancements done in TVPSEUDO or
TVPHLAME.  Has no effect if the image is in black and white.
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 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-----------------------------------------------------------------------
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-----------------------------------------------------------------------
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
channel 1 at the upper left of the display.  The cursor position
determines which pixel is shown.  Unlike other CURVALUEs in AIPS,
buttons A and B allow you to add the selected pixel to a list of pixels
to be flagged or re-fit at a later time.  Buttons C and D end the
display and returns to the menu.  Instructions appear on the message
screen.  The pixel values are read from the image in memory and hence
preserve accuracy.
C-----------------------------------------------------------------------
NEXT WINDOW
Very large images may not be able to fit on your TV.  When the image
exceeds the size of the TV, the top line will show the component
number followed by a subimage number in parentheses and the NEXT
WINDOW option will appear.  The first sub-images displayed is called
number 0 and shows the full image every n'th pixel in X and Y.
Sub-image 1 begins at the lower left, moves right, then back to the
left and up, and so forth until the top right is reached.  Every pixel
is displayed in these sub-images.  Use the NEXT WINDOW option to step
through the sub-images in a circular fashion.
C-----------------------------------------------------------------------
DO FIT
Selecting this option tells ZAMAN to use the current initial guess to
try to fit the model parameters.
C-----------------------------------------------------------------------
BAD
Selecting this option tells ZAMAN to mark the current pixel as "bad"
in the model file and then go on to the next pixel.
C-----------------------------------------------------------------------
QUIT
Selecting this option causes ZAMAN to exit cleanly.  It may be
re-started later with the same model file to continue model fitting and
image editing.
C-----------------------------------------------------------------------
GOOD
Selecting this option tells ZAMAN that the fit appears to be good.  The
task stores the parameters in the model file and goes on to the next
pixel.
C-----------------------------------------------------------------------
TVOFF
Selecting this option turns off the TV interaction and tells ZAMAN to
ncontinue fitting with its own self-generated initial guesses.  The
interactive mode will be turned back on when the fit parameters are
outside a reasonable range of values, the RMS exceeds RMSLIMIT, or when
ZAMAN reaches the image editing stage.
C-----------------------------------------------------------------------
HAND
Selecting this options tells the task that you wish to enter an initial
guess by typing in values in the AIPS terminal window (after prompting).
In ZAMAN, the parameters are the gain (0 to 1) and either the average
"field" (in pixels) or the "field" for each of the Gaussian components.
C-----------------------------------------------------------------------
