;+
; NAME:
;       APPLY_HANNING
;
; PURPOSE:
;
;       The purpose of this function is to provide a
;       wrapper for the built-in IDL function:
;       hanning(). I found that I was constantly having
;       to rewrite the following code each time I
;       needed to use the Hanning window.
;
; AUTHOR:
;
;       Nathan Johnson
;       University of Arizona
;       Department of Atmospheric Sciences
;       johnson AT atmo DOT arizona DOT edu
;
; CATEGORY:
;
;       Signal, image processing.
;
; CALLING SEQUENCE (WITH REQUIRED INPUT PARAMETERS):
;
;       output = APPLY_HANNING(array_in)
;                   : array_in is the input array to which the hanning window
;                     will be applied.
;
; OPTIONAL INPUT PARAMETERS:
;
;       None.
;
; INPUT KEYWORD PARAMETERS:
;
;   ALPHA = width parameter of generalized Hamming window.  Alpha
;       must be in the range of 0.5 to 1.0.  If Alpha = 0.5,
;       the default, the function is called the "Hanning" window.
;       If Alpha = 0.54, the result is called the "Hamming" window.
;
;   DOUBLE = Set this keyword to force the computations to be done
;            in double-precision arithmetic. This keyword is always
;            set in the call to the hanning() function. It remains
;            a keyword here for compatability.
;
; OUTPUT KEYWORD PARAMETERS:
;
;       None.
;
; COMMON BLOCKS:
;       None.
;
; SIDE EFFECTS:
;       None known.
;
; RESTRICTIONS:
;       None. 
;
; EXAMPLE:
;
;      windowed_data = apply_hanning(data, alpha=0.54)
;
;      This command will apply the hamming filter to the specified data.
;
;
; MODIFICATION HISTORY:
;
;       Written by: Nathan Johnson, 15 January 2008.
;-

Function Apply_Hanning, array_in, $
    Alpha=alpha, $
    DOUBLE=double

  on_error, 2

  IF N_PARAMS() eq 0 THEN MESSAGE, 'At least one input required for this function.'

  sze = size(array_in)

  IF sze[0] eq 1 THEN BEGIN
    n1In = sze[1]
    n2In = 1
  ENDIF

  IF sze[0] eq 2 THEN BEGIN
    n1In = sze[1]
    n2In = sze[2]
  ENDIF

  IF sze[0] ne 1 AND sze[0] ne 2 THEN MESSAGE, 'Input array must be 1D or 2D.'

  IF n1In gt 0 AND n2In gt 0 THEN BEGIN
    ; Always use double precision.
    return, (array_in-mean(array_in))*HANNING(n1In, n2In, ALPHA=ALPHA, /DOUBLE)    
  ENDIF ELSE $
    MESSAGE, 'Array dimensions must be greater than 0.

END