FUNCTION binf,image,factor,time=time
;+
; NAME:
;        BINF
;
; PURPOSE:
;        Test software binning of Polar Camera images (but more flexible 
;        than required.)
;
; CATEGORY:
;
; CALLING SEQUENCE:
;        result = BINF( IMAGE, FACTOR, TIME=TIME)
;
; INPUTS:
;        IMAGE:        A two-dimensional array containing the image to be binned.
;        FACTOR:        A (small) integer giving the number of rows and columns
;                to be added to give one pixel in the output (binned) image.
;
; KEYWORDS:
;       TIME:   If set, the function prints the length of time
;                taken to perform the binning.
; OUTPUTS:
;        The binned image, of the same type as the input image, if possible.
;                
; OPTIONAL OUTPUT PARAMETERS:
;        None.
;
; COMMON BLOCKS:
;        None.
;
; SIDE EFFECTS:
;        None.
;
; RESTRICTIONS:
;        The input image must be two-dimensional.  The number of rows 
;        and columns must each be a multiple of the binning factor.
;
; PROCEDURE:
;       The REFORM function is used to redimension the input image
;       so that pixels to be summed are isolated in one dimension
;       and can be added using the TOTAL function, acting on a
;       single dimension of the input array.  The binning down
;       columns is performed first, and then the binning along
;       rows.  The final invocation of REFORM removes the degenerate
;       leading dimension of 1 from the result.  If the input image
;       was of a data type 'lower' than floating point, the saved
;       data type is used to cast the binned image back to the same
;        data type.
;
; MODIFICATION HISTORY:
;        Written 94/06/08 by D P Steele.
;-

; Check correctness of inputs.

IF N_PARAMS() LT 2 THEN BEGIN
    MESSAGE,'You must specify a binning factor!',/INFORMATIONAL
    doc_library,'binf'
    RETURN,-1
    ENDIF

s=SIZE(image)
IF s(0) NE 2 THEN BEGIN
    MESSAGE,'Input image must be a 2-d array!',/INFORMATIONAL
    doc_library,'binf'
    RETURN,-1
    ENDIF

factor=BYTE(ROUND(factor))
IF factor EQ 1 THEN RETURN,image $        ; trivial
               ELSE BEGIN
    c=s(1)
    r=s(2)
    type=s(3)
    IF (factor*(c/factor) NE c) OR (factor*(r/factor) NE r) THEN BEGIN
        MESSAGE,'Image dimensions must be multiples of binning factor!' $
               ,/INFORMATIONAL
        doc_library,'binf'
        RETURN,-1
        ENDIF

; Use REFORM to restructure the array so TOTAL can be used to do the
; sums.

    bt=SYSTIME(1)
    b=REFORM(TOTAL(REFORM(TOTAL(REFORM(image,c,factor,r/factor),2),factor,c/factor,r/factor),1))
    et=SYSTIME(1)
    IF KEYWORD_SET(time) THEN  $
        PRINT,et-bt,FORMAT='("Binning took ",F6.3," seconds.")'
    CASE type OF
     1: RETURN,BYTE(b<255)
     2: RETURN,FIX((b<32767)>(-32768))
     3: RETURN,LONG(b)
  ELSE: RETURN,b
        ENDCASE
    ENDELSE
END