; TVHLD
;---------------------------------------------------------------
;! Task to load an image to the TV with histogram equalization
;# TASK TV ANALYSIS
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2009, 2014-2015
;;  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
;-----------------------------------------------------------------------
TVHLD     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVHLD:      Load an image to the TV with histogram equalization
INNAME                             Image name(name). blank=>any
INCLASS                            Image name(class). blank=>any
INSEQ           0.0      9999.0    Image name(seq. #). 0=>any
INDISK          0.0         9.0    Disk drive #. 0=>any
OUTNAME                            Output name (name).
OUTCLASS                           Output name (class).
OUTSEQ         -1.0      9999.0    Output name (seq. #).
                                     0 => highest unique
OUTDISK                            Output image disk drive #
                                     0 => highest with room
BLC                                Bottom left corner out and
                                      for computing histogram
TRC                                Top right corner out and
                                      for computing histogram
TBLC            0.0      4096.0    Bottom Left Corner of image
                                      to display
TTRC            0.0      4096.0    Top Right Corner of image
                                      to display
TXINC           0.0       256.0    Load every TXINC'th column
TYINC           0.0       256.0    Load every TYINC'th row
NPOINTS         0.0      9000.0    Number of intensity bins
NX                                 Histogram actual size
----------------------------------------------------------------
TVHLD
Type: Task
Use:  TVHLD loads a map image into the TV with histogram equalization.
      Interactive control of the pixel value range and other transfer
      parameters is offered.  The pixelization implied by the use of a
      finite number of bins in the histogram and an even more finite
      number of bins the conversion from histogram to list of
      intensity ranges is obviated significantly by the use of linear
      interpolation in the conversion to the list of ranges and in the
      conversion of intensity values to equalized values.

      TVHLD was initially written by Arnold Rots in 1983-1984.
      Unfortunately, his version depended on several hardware
      functions of the IIS Models 70 and 75 which are not available in
      the X-Windows based TV programs.  Therefore, it has been
      completely re-written, in modern AIPS style, to offer a similar
      functionality.  Two related, non-interactive tasks are HISEQ
      which does the full image in one histogram with the linear
      method and an input PIXRANGE and AHIST which does histograms
      within a box surrounding each pixel.  They write out a new
      equalized image.  TVHLD does its histogram over the full window
      specified by the adverbs and then loads it (or a sub-image of
      it) to the TV.  You may then interactively change the the low
      and high values of the intensity range and select functions of
      the histogram to use in the equalization. Various TV transfer
      functions and enhancements are also offered to help study the
      image.  When you are happy you may EXIT, writing out a
      histogram-equalized image or, if unhappy, you may ABORT and
      avoid writing out an image.
Adverbs:
  INNAME......Image name (name).      Standard defaults.
  INCLASS.....Image name (class).     Standard defaults.
  INSEQ.......Image name (seq. #).    0 => highest.
  INDISK......Disk drive # for the image.  0 => any.
  OUTNAME.....Output image name (name)  ' ' -> INNAME
  OUTCLASS....Output image name (class)  ' ' -> 'TVHLD'
  OUTSEQ......Output image name (seq #)  0 -> highest+1
  OUTDISK.....Output image disk drive #
  BLC.........Bottom left corner of image to compute the equalizing
              histogram and to go to output image.
  TRC.........Top right corner of image to compute the equalizing
              histogram and to go to output image.  Note that only one
              plane is done, so TRC(3) through TRC(7) are forced to
              BLC(3) through BLC(7).
  TBLC........Bottom left corner of TV image displayed.  0 -> centered
              in BLC-TRC region.
  TTRC........Top right corner of TV image displayed.
  TXINC.......> 1 -> display only every TXINC column on TV
  TYINC.......> 1 -> display only every TYINC row on TV
  NPOINTS.....The histogram is computed in a large number (NX) of
              boxes, but the ultimate division of the intensities is
              done in NPOINTS boxes.  < 100 -> 8192 but so many levels
              will slow the task down.  1024 is a good number and the
              task may limit NPOINTS still further.
  NX..........The number of boxes used in the actual hisogram.
              0 -> 100000.  If a large number is used, then the effect
              of using functions like LOG on the histogram will be
              diluted.
----------------------------------------------------------------
TVHLD: Interactive image histogram equalization
REKATED PROGRAMS: HISEQ, AHIST

Histogram equalization is a traditional technique in image processing
to bring out fine detail where the histogram of intensities has many
pixels while obscuring detail where the histogram has few pixels.  In
typical astronomy images, this emphasizes fine details in the image
values near zero and loses much of the intensity range at the highest
values.  Nonetheless, it may be an interesting technique to apply to
images.  The LOG histogram equalizes the histogram where one takes the
logarithm of the actual histogram counts before doing the
equalization.  That leaves in much more detail of the higher levels in
the image.  TVHLD begins in that mode but can be switched between LOG
and LINear modes.

The TV menu has two columns.  On the left is

---------------
| OFF ZOOM    |  Turn off pixel-replication zoom from TVZOOM
| OFF TRANS   |  Turn off black & white enhancement from TVTRANSF
| OFF COLOR   |  Turn off color enhancement from TVPSEUDO and TVPHLAME
| TVZOOM      |  Adjust pixel-replication zoom
| TVTRANSF    |  Adjust the black & white transfer function
| TVPSEUDO    |  Adjust colors with numerous variations, types
| TVPHLAME    |  Adjust colors with flame-like scheme
| LOAD xxxx   |  Re-load TV with LIN (linear), LOG (log), SQRT (square
                 root), or LOG2 (more extreme log) transfer function
                 in sequence
---------------

The right-hand menu contains

---------------
| ADJUST LOW  |  Adjust the lower intensity level included
| ADJUST HIGH |  Adjust the higher intensity level included
| HISTO yyy   |  Equalize the histogram LINearly or the LOG of the
                 histogram or the 1/4, 1/2 (SQR), and 3/4 power of the
                 histogram in sequence
| EXIT        |  Exit task, writing out the output image
| ABORT       |  Exit task, not writing any image
---------------

You will probably find the ADJUST LOW is your most interesting option
and should examine all of the histogram modes.  The HISTO options
allow you to reduce the influence of levels around zero, which is many
images completely dominate the histogram.  The eenhancement options
are just there to help you examine the image being prepared.  They do
not affect the image that is written out.
