AIPS HELP file for TVSTAT in 31DEC24
As of Thu Apr 25 5:13:06 2024
TVSTAT: Verb to find the mean, rms and extrema in a TV subimage
INPUTS
DOINVERS -1.0 1.0 >0 find stats outside blotch
<=0 find stats inside blotch
DOALL -1.0 1.0 >0 include pure zero pixels
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)
HELP SECTION
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.
DOALL.......> 0 => all non-blank pixels are included in the
statistics.
<= 0 => pure 0.0 pixels are excluded from the
statistics.
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.
EXPLAIN SECTION
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.