;***************************************************************************
;+
;*NAME:
;
;    BIMAGE     (General IDL Library 01) 12 DECEMBER, 1986
;
;*CLASS: 
;
;    Resampling
;
;*CATEGORY:
;
;*PURPOSE:  
;
;    To bin a vector or a two dimensional array in either or both directions.
; 
;*CALLING SEQUENCE: 
;
;    BIMAGE,IMAGE,SWIDTH,LWIDTH,OUT,NNS,INDEX
;    BIMAGE,IMAGE,SWIDTH,LWIDTH,OUT
;    BIMAGE,IMAGE,SWIDTH,LWIDTH,OUT,NNS
;
;*PARAMETERS:
;
;    IMAGE   (REQ) (I) (1 2) (B I L F D)
;            Required input image vector or array which is to be binned.
;  
;    SWIDTH  (REQ) (I) (0) (I L F D)
;            Required input scalar giving the bin width in the sample (x)
;            or column direction.
;
;    LWIDTH  (REQ) (I) (0) (I L F D)
;            Required input scalar giving the bin width in the line (y)
;            or row direction.
;    
;    OUT     (REQ) (O) (1 2) (F)
;            Required output vector or array containing the binned data
;            in floating point format.
;
;    NNS     (OPT) (O) (0) (I)
;            Optional output scalar giving the number of points in the
;            sample direction.
;
;    INDEX   (OPT) (O) (1) (I F)
;            Elements from input image corresponding to bin centers in the
;            sample direction. Centers for even bin widths will be half an
;            element too high.
;
;*EXAMPLES:
;
;     To bin an LBLS file (read in to array FILE using READFILE) with a bin
;     size of 10 in the sample direction and 2 in the line direction:
;        BIMAGE,FILE,10,2,OUT   or,
;        BIMAGE,FILE,10,2,OUT,NNS,INDEX
;
;*SYSTEM VARIABLES USED:
;
;*INTERACTIVE INPUT:
;
;*SUBROUTINES CALLED:
;
;     PARCHECK
;
;*FILES USED: 
;
;*SIDE EFFECTS:
;
;*RESTRICTIONS:
;
;*NOTES:
;
;    1) OUT is truncated in line and sample direction to be a multiple
;    of LWIDTH and SWIDTH respectively.
;    2) Any width specified as less than or equal to 1 defaults to 1.
;    3) If IMAGE is a vector, the value of LWIDTH is ignored. However,
;       it must still be specified.
;    4) Bin centers described in INDEX will be half an element too high
;       when SWIDTH is an even number. For example, if SWIDTH = 8, the
;       first element of INDEX will be 5, not 4.5.
;    5) Specifying BIMAGE with no parameters will display the procedure
;       call statement
;
;	tested with IDL Version 2.1.0 (sunos sparc)	19 JUN 91
;	tested with IDL Version 2.1.0 (ultrix mispel)	N/A
;	tested with IDL Version 2.1.0 (vms vax)    	19 Jun 91
; 
;*PROCEDURE:
;
;    BIMAGE is basically a driver for the new intrinsic IDL command
;    REBIN. Because REBIN requires that the dimensions of the input array
;    be a multiple of the bin size, BIMAGE calls REBIN with an appropriately
;    truncated input array. BIMAGE also calculates the dimensions of the 
;    output array as required by REBIN, and calls REBIN with the appropriate
;    number of parameters depending on whether IMAGE is a vector or an array.
; 
;*INF_1:
;
;*MODIFICATION HISTORY:
;
;            87 SRH HRS   wrote COMPRESS
;     Apr 13 87 RWT GSFC  renamed procedure, added PARCHECK, and removed 
;                         INSERT
;     Jun  5 87 RWT GSFC  rewrite to use REBIN, make INDEX and NNS optional,
;                         and allow IMAGE to be a vector.
;     Aug 19 87 RWT GSFC  add listing of procedure call statement
;     Mar  7 88 CAG GSFC  add VAX RDAF-style prolog
;     Jun 19 91 PJL GSFC  cleaned up; tested on SUN and VAX; updated prolog
;
;-
;***********************************************************************
 pro bimage,image,swidth,lwidth,out,nns,index
;
 if n_params(0) eq 0 then begin
    print,' BIMAGE,IMAGE,SWIDTH,LWIDTH,OUT,nns,index'
    retall
 endif  ; n_params(0)
 parcheck,n_params(0),[4,5,6],'BIMAGE'
 in = float(image)
 sz = size(image)
 sw=fix(swidth > 1)
 ns = sz(1)
 if sz(0) eq 1 then begin     ; if image is a vector 
    lw = 1 
    nl = 1
 endif else begin          ; if image is an array
    lw=fix(lwidth > 1)
    nl = sz(2)
 endelse  ; sz(0)
 nns = fix(ns/sw) & nnl = fix(nl/lw)  ; dimensions of out
 index = indgen(nns) * sw + fix(sw/2)
;
; make sure bin size is less than image size
;
 if (sw gt ns) or (lw gt nl) then begin
    print,'Bin size specified is larger than input image'
    print,'ACTION: Returning'
    retall
 endif  ; sw
;
; make dimensions of in multiples of lwidth and swidth
;
 sam = ns mod sw
 lin = nl mod lw 
 if (sam+lin) ne 0 then begin
    if sz(0) eq 2 then in = in(0:ns-1-sam,0:nl-1-lin)
    if sz(0) eq 1 then in = in(0:ns-1-sam)
 endif  ; (sam+lin)
;
; call rebin to perform binning
;
 if sz(0) eq 1 then out = rebin(in,nns) else out = rebin(in,nns,nnl)
;
 return
 end  ; bimage