NAME:
  skysclim
 PURPOSE:
  Compute stretch range for a hard stretch on the background in an image.
 DESCRIPTION:
 CATEGORY:
  Image display
 CALLING SEQUENCE:
  skysclim,image,lowval,hival,meanval,sigma
 INPUTS:
  image - 2-d image to compute stretch range for.
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  NPTS - Maximum number of points to grab at random from image for scaling
           information.  Default=601.
  LOWCLIP - fraction of random sample to clip at the low end of the signal.
              If lowclip=.1 and npts=100, then the 10 lowest values in the
              random sample are excluded BEFORE the robust mean is computed
              for the stretch range.  This option will probably be just a bit
              slower if invoked.  This option will likely be more robust against
              extreme values in the image.  Default=0.0 (no clipping)
  HICLIP  - fraction of random sample to clip at the high end of the signal.
              If hiclip=.9 and npts=100, then the 10 highest values in the
              random sample are excluded BEFORE the robust mean is computed
              for the stretch range.  This option will probably be just a bit
              slower if invoked.  This option will likely be more robust against
              extreme values in the image.  Default=1.0 (no clipping)
  THRESH  - sigma threshold for excluding points (default=3.0)
  SEED    - value for the seed used by the random call. Default is undefined
              causing random to use the system time as the seed
 OUTPUTS:
  lowval - Low DN value for sky stretch  (meanval-3.0*sigma)
  hival  - High DN value for sky stretch (meanval+5.0*sigma)
  meanval - Mean of random sample
  sigma   - standard deviation of random sample
 KEYWORD OUTPUT PARAMETERS:
  SAMPLE  - Optional return of the sample of points from the sky that was
              considered to be representative of the sky.  The length of
              this array will be less than or equal to NPTS.
            WARNING!  To preserve a faster execution option if you don't
              want this sample returned a non-existant variable for this
              keyword is treated the same as no keyword at all.  If you do
              pass an undefined variable you will get the sample back but
              it will contain the entire sky sample, not the sample cleaned
              of non-sky values.  The input variable can be just about
              anything to ensure getting back a cleaned sample.
  STDMEAN - Return for the standard deviation of the mean of the returned
              sky value.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
  96/01/07 - Marc W. Buie
  2000/02/29, MWB, added NPTS keyword
  2002/11/17, MWB, added LOWCLIP, HICLIP keywords
  2002/12/18, MWB, fixed bug causing crash when image is smaller than npts.
  2005/11/22, MWB, added SAMPLE and THRESH keywords
  2010/03/12, Florian Scheulen, added SEED keyword
  2013/03/29, MWB, added STDMEAN output keyword
  2014/02/11, MWB, added more data type options for SEED