; TVSTAT
;---------------------------------------------------------------
;! Find the mean and RMS in a blotch region on the TV
;# VERB TV INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2003, 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
;-----------------------------------------------------------------------
TVSTAT    LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVSTAT:  Verb to find the mean, rms and extrema in a TV subimage
DOINVERS          -1.0         1.0 >0 find stats outside blotch
                                   <=0 find stats inside blotch
           Main input is the image on the TV and cursor inputs.
         @          Output adverbs:
PIXAVG   @                         Mean pixel value
PIXSTD   @                         RMS about mean pixel value
PIXVAL   @                         Peak pixel value
PIXXY    @                         Coordinates of peak (pixels)
PIX2VAL  @                         Minimum pixel value
PIX2XY   @                         Coords of minimum (pixels)
----------------------------------------------------------------
TVSTAT
Type: Verb
Use:  TVSTAT will read a portion of an image and print the mean
      and rms brightnesses found.  It also prints the locations
      and values of the max/min brightnesses in that portion.
      It returns these results in adverbs.  TVSTAT differs from
      IMSTAT in 2 ways: it uses the current TV image rather than
      an image specified by adverbs and it determines the values
      over irregular regions ("blotch" areas) marked by the user
      with the TV cursor.  (See EXPLAIN TVSTAT for details.)
Adverbs (input):
  DOINVERS....If true (>0.), find statistics over full image as
              displayed on the TV except for the blotch regions.
              If false (<= 0.), find statistics inside the
              blotch regions.
Adverbs (output):
  PIXAVG......Mean pixel value found in subimage in the same
              units as the image (e.g. Jy/beam).
  PIXSTD......RMS in the pixel values about the mean in the
              subimage in the same units as the image.
  PIXVAL......Peak pixel value in the subimage.
  PIXXY.......Pixel coordinates of the pixel having the largest
              value within the subimage.
  PIX2VAL.....Minimum pixel value in the subimage.
  PIX2XY......Pixel coordinates of the pixel having the smallest
              value within the subimage.
----------------------------------------------------------------
TVSTAT

                         PURPOSE

     TVSTAT is intended to let users determine image statistics
over irregular regions of an image.  It returns the mean, rms,
and maximum brightnesses and the pixel position of the maximum
in adverbs intended for use by RUN files and other automatic
procedures.  It does, however, require user interaction via the
TV.  For batch and other truely automatic processes the verb
IMSTAT should be used instead.

     The TV cursor is used to set the vertices of one or more
polygonal "blotch" regions and the results are determined only
for those pixels which fall within or without (see DOINVERS
below) the blotch regions.  The routine begins by asking for
the vertices of polygon 1.  Move the TV cursor to the desired
spot and press Button A.  Then move it to the next vertex and
again press Button A.  Continue this process moving strictly in
a clockwise or a counter-clockwise direction.  When the last
vertex of the polygon is reached, press one of Buttons B, C, or
D to finish the current polygon.  (The program will take care of
drawing the line from the last vertex to the initial one.)
Button B means that you wish to set another, independent
polygon; Button C means that you wish to correct one or more
previously set vertices; and Button D means that you are done
setting the blotch areas.

     If you go into "correction" mode (via Button C at the end
of a polygon), then move the cursor over the vertex that you
wish to correct and press either button A or B to indicate your
selection.  Further movement of the cursor will cause the vertex
position to shift with it.  Press any button to set the new
vertex position.  Button A or B mean that you wish to correct
another vertex.  In either step of the correction, Button C
means that you wish to go on to a new, independent polygon and
Button D means that you wish to quit setting polygons.

     After the polygons are set (Button D pressed), the routine
fills in the polygons obscuring the blotch regions.  After some
further delay, it prints the results (at message level 5) and
puts the answers in the PIXAVG, PIXSTD, PIXVAL, PIXXY, PIX2VAL,
and PIX2XY adverbs.

     The sequence in which the vertices are set is important.
One must maintain either a clockwise or a counter clockwise
direction.  However there is a trick.  In the diagram below, the
asterisks (*) represent a source and we wish to determine the
rms over the entire area not including the source.  The numbers
are the sequence of vertices:

  2                                                          3

                              6
                              *
                             **
                          7 ****  ""                        ++
                             **
                             *
                             9


  1                                                         12

where "" represents vertices 5 and 10 and ++ represents vertices
4 and 11 on top of each other.  The basic clockwise motion
includes the inner area, while the small counter-clockwise
motion excludes the innermost area.  Be very careful to set all
vertices within the image.

     An easier way to carry out this function is to set
DOINVERS to true (1.0).  Then the statistics are determined for
all map points visible on the TV (ignoring zoom) except for
those inside the blotch region(s).  The description above
assumes that DOINVERS is false (<= 0.0).  Be careful with this
adverb --- numerous tasks use it for various purposes.
----------------------------------------------------------------
