; IMEAN
;---------------------------------------------------------------
;! displays the mean & extrema and plots histogram of an image
;# Task Plot ANALYSIS
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2002-2004, 2006-2009, 2011-2012
;;  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
;-----------------------------------------------------------------------
IMEAN     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
IMEAN:  Task to print the mean, rms and extrema in an image
DOHIST          -3.0         2.01  True (1.0) do histogram plot.
                                   = 2 => flux on x axis
USERID      -32000.0      32000.0  User ID.  ignored
INNAME                             Image name (name)
INCLASS                            Image name (class)
INSEQ            0.0       9999.0  Image name (seq. #)
INDISK           0.0          9.0  Disk drive #
BLC             -1.0       4096.0  Bottom left corner of image
                                     0=>entire image
TRC              0.0       4096.0  Top right corner of image
                                     0=>entire image
DOINVERS        -1.0          1.0  > 0 => histogram outside
                                   <=0 => inside BLC/TRC
NBOXES           0.0       1024.0  No. of ranges for histogram.
PIXRANGE                           Min and max range for hist.
FUNCTYPE                           'LG' => do log10 plot of #
                                   samples, else linear
DOMODEL        -1.0         1.0    > 0 fit, plot Gaussian
DOCAT          -1.0         1.0    Put true RMS in header
LTYPE         -10.0        10.0    Type of labeling: 1 border,
                                   2 no ticks, 3 - 6 standard,
                                   7 - 10 only tick labels
                                   <0 -> no date/time
DOPRINT                            0 - no print, -3 brief
OUTTEXT                            Name of output log file,
                                   No output to file if blank
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
PIXAVG   @                         Mean noise value
PIXSTD   @                         True noise rms
TRIANGLE @                         Brightness at the top 1%, 2%,
         @                         3%, ,,,50% of full histogram
----------------------------------------------------------------
IMEAN
Type: Task
Use:  IMEAN will read a portion of an image and print the mean and rms
      brightnesses found.  It also prints the location and value of the
      max and min brightnesses in that portion.  For clean maps, the
      mean is converted into a total flux.  An option to generate a
      histogram plot and/or print file is available.  It also computes
      the peak and rms of the histogram of the image in an attempt to
      determine the mean and rms of the noise part of the signal.  It
      determines the initial values for this from the header
      (ACTNOISE, ACTMEAN) or from a robust fit from the first plane of
      the image.  Note that pixel values which are exactly zero are
      not used in the fit for the rms.  This allows blanked pixels to
      be REMAGed to zero without affecting these computations.

      Three adverbs are returned by the task.  This allows the fit
      mean and noise to be used in other computations or tasks.  It
      also returns in TRIANGLE(i) the brightness level exceeded by i%
      of the pixels.

      The aperture for the computation may be either rectangular or
      circular.

      The histogram is computed even if it will not be plotted since
      it may be printed.  Thus, BLC, TRC, DOINVERS, NBOXES, PIXRANGE
      are used even of DOHIST <= 0.

      A special one-line print option is available when DOPRINT=-3.
Adverbs:
  DOHIST......True (>0) means plot the histogram determined with
              NBOXES and PIXRANGE.  A second histogram is always
              computed, ignoring these adverbs, in an attempt to fit a
              Gaussian to the peak.  If that is succesful, the fit is
              plotted on any plotted histogram.  If 0 < DOHIST <= 1,
              then the flux is plotted on the Y axis and the counts on
              the X axis.  If DOHIST > 1, the axes are reversed -
              which is a more common form.
  USERID......User ID of owner of image.  Ignored.
  INNAME......Image name(name).         Standard defaults.
  INCLASS.....Image name(class).        Standard defaults.
  INSEQ.......Image name(seq. #).       0 => highest.
  INDISK......Disk drive # of image.    0 => any.
  BLC.........The Bottom Left-hand pixel of the subarray of the image to
              be analysed. The value (0,0) means (1,1).
              If BLC(1) = -1, then BLC(2) is taken as the radius of a
              circular aperture centered in TRC(1),TRC(2) which must
              be specified, not defaulted.
  TRC.........The Top Right-hand pixel of the subarray of the image to
              be analysed.  The value (0,0) means the top right hand
              corner of the entire image.
              See note about circular aperture under BLC above.
  DOINVERS....>  0 Do the histogram OUTSIDE the rectangular or
                   circular area defined by BLC/TRC
              <= 0 Do the histogram INSIDE (including borders) the
                   rectangular or circular area defined by BLC/TRC
  NBOXES......Number of boxes used in computing histogram for
              plotting.  The number of boxes used to compute the
              apparent noise rms is controlled by the task.
              <= 1 => 101 boxes,  > 1024 => 512
  PIXRANGE....Intensity range min/max over which plotted histogram is
              computed.  Max <= min (i.e. 0) => full range.  This is
              used to set the range between the center of box 1 and
              the center of box NBOXES.
  FUNCTYPE....Type of axis plot for number of samples in each box.  'LG'
              => log base 10, else linear.
  DOMODEL.....> 0 => fit a Gaussian to the histogram and plot it along
              with the histogram.
  DOCAT.......> 0 => write the new actual noise estimate as keyword
              ACTNOISE and the estimate zero level as ACTMEAN in the
              image header.
  LTYPE.......Labelling type: 1 = border, 2 = no ticks, 3 - 10 =
              standard, with  7-10 all labels other than tick numbers
              and axis type are omitted.  Less than 0 is the same except
              that the plot file version number and create time are
              omitted.
  DOPRINT.....Additional print control when OUTTEXT is not blank.
              = 0 => no printing, = -3 => print a single line giving
              BLC(3-7), TRC(3-7), minimum, maximum, flux, and rms all
              in one line.  For plots note that task RSPEC will
              compute rmses and plot the spectra (and print it too).
  OUTTEXT.....Output file to log measurements for later user processing.
              File created if it does not exist and appended to if it
              already exists.  Nothing is written to a file if the
              name is blank.  File name should contain directory and
              file parts, i.e, "LOCAL:IMEAN.OUT" or
              "RUNFIL:IMPORTANT.POINTS".  The histogram is printed into
              the file even if DOHIST <= 0.
  DOTV........> 0 => plot directly on the TV device, otherwise make a
              plot file for later display on one or more devices
              (including the TV if desired).
  GRCHAN......Graphics channel (1 - 7) to use for line drawing.  0 => 1
Output adverbs
  PIXAVG......Mean value of the noise part of the image.  The final
              fit to the noise portion is returned.
  PIXSTD......RMS of the noise portion of the image.  The final fit is
              returned.
  TRIANGLE....TRIANGLE(i) returns the brightness which is exceeded by
              only i% of the pixels.  Values for 1 to 50% are
              returned.  Note that the histoigram used to compute this
              is computed over the full intensity range of the image,
              not just PIXRANGE.
----------------------------------------------------------------
