; docformat = 'rst'
;
; NAME:
;   SDEVSCL
;
; PURPOSE:
;    This is a utility routine to perform standard deviation scaling
;    on image arrays. The user defines a multiple of the standard
;    deviation and this is used with the standard deviation of the
;    pixels in the image to create a threshold for linear scaling.
;    Use the EXCLUDE keyword to exclude a particular value from
;    the standard deviation calculation.
;******************************************************************************************;
;                                                                                          ;
;  Copyright (c) 2012, by Fanning Software Consulting, Inc. All rights reserved.           ;
;                                                                                          ;
;  Redistribution and use in source and binary forms, with or without                      ;
;  modification, are permitted provided that the following conditions are met:             ;
;                                                                                          ;
;      * Redistributions of source code must retain the above copyright                    ;
;        notice, this list of conditions and the following disclaimer.                     ;
;      * Redistributions in binary form must reproduce the above copyright                 ;
;        notice, this list of conditions and the following disclaimer in the               ;
;        documentation and/or other materials provided with the distribution.              ;
;      * Neither the name of Fanning Software Consulting, Inc. nor the names of its        ;
;        contributors may be used to endorse or promote products derived from this         ;
;        software without specific prior written permission.                               ;
;                                                                                          ;
;  THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY        ;
;  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES    ;
;  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT     ;
;  SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,             ;
;  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    ;
;  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;         ;
;  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND             ;
;  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              ;
;  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS           ;
;  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                            ;
;******************************************************************************************;
;
;+
; This is a utility routine to perform standard deviation scaling
; on image arrays. The user defines a multiple of the standard
; deviation and this is used with the standard deviation of the
; pixels in the image to create a threshold for linear scaling.
; Use the EXCLUDE keyword to exclude a particular value from
; the standard deviation calculation.
; 
; :Categories:
;    Utilities, Graphics
;    
; :Params:
;     image: in, required, type=numeric
;        The image array that is to be scaled.
;      
; :Keywords:
;     exclude: in, optional, type=numeric
;         Set this keyword to a value in the image array that is to be excluded from the
;         standard deviation calculation. Normally, this would be the backgroud value of
;         the image, if there is a background.
;     multiplier: in, optional, type=float, default=2.0
;        The standard deviation of the image pixels is computed and then
;        multiplied by the multiplier factor to produce upper and lower
;        thresholds for the linear scaling of the image by subtracting
;        or adding this value to the mean value of the image. The image
;        is linearly scaled between these two threshold values. 
;     negative: in, optional, type=boolean
;          Set this keyword to return the "negative" or reverse of the image scaling.
;     omax: in, optional, type=byte, default=255
;          Normally, the image is scaled into the range of 0 to 255. Setting the
;          OMIN and OMAX keywords can change this scaling.
;     omin: in, optional, type=byte, default=0
;          Normally, the image is scaled into the range of 0 to 255. Setting the
;          OMIN and OMAX keywords can change this scaling.
;     threshold: out, optional, type=float
;          A two-element array that contains the minimum and maximum thresholds, respectively,
;          that were calculated for the scaling.
;              
; :Examples:
;     To display an image with standard deviation scaling::
;        image = cgDemoData(5)
;        cgDisplay, 256*3, 256
;        !P.Multi = [0,3,1]
;        cgImage, image
;        cgImage, SDevScl(image)
;        cgImage, SDevScl(image, Exclude=0)
;        !P.Multi = 0
;       
; :Author:
;     FANNING SOFTWARE CONSULTING::
;        David W. Fanning 
;        1645 Sheely Drive
;        Fort Collins, CO 80526 USA
;        Phone: 970-221-0438
;        E-mail: david@idlcoyote.com
;        Coyote's Guide to IDL Programming: http://www.idlcoyote.com
;
; :History:
;     Change History::
;        Written by: David W. Fanning, 5 June 2012.
;
; :Copyright:
;     Copyright (c) 2012, Fanning Software Consulting, Inc.
;-
FUNCTION SDevScl, image, $
   EXCLUDE=exclude, $
   MULTIPLIER=multiplier, $
   NEGATIVE=negative, $
   OMAX=maxOut, $
   OMIN=minOut, $
   THRESHOLD=threshold

   ; Return to caller on error.
   ;On_Error, 2
   Catch, theError
   IF theError NE 0 THEN BEGIN
      Catch, /Cancel
      void = cgErrorMsg()
      RETURN, image
   ENDIF

   ; Check arguments.
   IF N_Elements(image) EQ 0 THEN Message, 'Must pass IMAGE argument.'
   IF N_Elements(multiplier) EQ 0 THEN multiplier = 2.0

   ; Check for underflow of values near 0. Yuck!
   curExcept = !Except
   !Except = 0
   i = Where(image GT -1e-35 AND image LT 1e-35, count)
   IF count GT 0 THEN image[i] = 0.0
   void = Check_Math()
   !Except = curExcept

   IF Size(image, /TNAME) NE 'DOUBLE' THEN output = Float(image)

   ; Check keywords.
   IF N_Elements(maxOut) EQ 0 THEN maxOut = 255B ELSE maxout = 0 > Byte(maxOut) < 255
   IF N_Elements(minOut) EQ 0 THEN minOut = 0B ELSE minOut = 0 > Byte(minOut) < 255
   IF minOut GE maxout THEN Message, 'OMIN must be less than OMAX.'
   
   ; Did you want to exclude a value?
   IF N_Elements(exclude) NE 0 THEN BEGIN
     indices = Where(image EQ exclude[0], count)
     IF count GT 0 THEN output[indices] = !Values.F_NAN
   ENDIF

   ; Calculate the standard deviation of the image.
   stddev = StdDev(output, /DOUBLE, /NAN)
   
   ; Calculate the thresholds.
   minThresh = Mean(output, /DOUBLE, /NAN) - (multiplier * stddev)
   maxThresh = Mean(output, /DOUBLE, /NAN) + (multiplier * stddev)

   ; Save the thresholds.
   threshold = [minThresh, maxThresh]

   ; Scale the data.
   output = cgScaleVector(Temporary(output), MIN=threshold[0], MAX=threshold [1], minOut, maxOut)

   IF Keyword_Set(negative) THEN RETURN, 0B > (maxout - Byte(output) + minOut) < 255B $
      ELSE RETURN, Byte(output)

END