FUNCTION test_bit_pattern_bpm_3darr, bpmdata, xsize, ysize, zsize
; Description: This function tests that the parameter "bpmdata" contains a three-dimensional
; bit-pattern bad pixel mask of size "xsize" by "ysize" by "zsize" pixels. A
; bit-pattern bad pixel mask stores a non-negative integer value at each pixel
; that represents the pattern of bits that are set (or the equivalent binary
; number). If no bits are set, then the integer value is "0", and this is
; generally considered to be a good pixel. If at least one bit is set, then
; the integer value will be positive, and this is generally considered to be
; a bad pixel with the "bad pixel" properties indicated by which bits are set.
; Therefore, this function tests that the parameter "bpmdata" is a
; three-dimensional array of size "xsize" by "ysize" by "zsize" pixels that is
; of BYTE, INTEGER, or LONG type, and that contains no negative pixel values.
;
; Input Parameters:
;
; bpmdata - ANY - The parameter to be tested whether or not it satisfies the properties
; that a three-dimensional bit-pattern bad pixel mask would have.
; xsize - INTEGER/LONG - The size of the input parameter "bpmdata" along the x-axis
; should be equal to the value of "xsize". If this parameter is
; not of the correct number type, or if it is zero or negative,
; then the input parameter "bpmdata" is allowed to be of any size
; along the x-axis.
; ysize - INTEGER/LONG - The size of the input parameter "bpmdata" along the y-axis
; should be equal to the value of "ysize". If this parameter is
; not of the correct number type, or if it is zero or negative,
; then the input parameter "bpmdata" is allowed to be of any size
; along the y-axis.
; zsize - INTEGER/LONG - The size of the input parameter "bpmdata" along the z-axis
; should be equal to the value of "zsize". If this parameter is
; not of the correct number type, or if it is zero or negative,
; then the input parameter "bpmdata" is allowed to be of any size
; along the z-axis.
;
; Return Value:
;
; The function returns an INTEGER value set to "1" if "bpmdata" satsifies the properties
; that a three-dimensional bit-pattern bad pixel mask would have. Otherwise, the function
; returns an INTEGER value set to "0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 08/01/2012 - Module created (dmb).
;Check that "bpmdata" is a three-dimensional array that contains numbers of the type BYTE,
;INTEGER, or LONG
;If required, check that "bpmdata" is of size "xsize" along the x-axis
;If required, check that "bpmdata" is of size "ysize" along the y-axis
;If required, check that "bpmdata" is of size "zsize" along the z-axis
;Check that "bpmdata" does not have any negative pixel values
;If "bpmdata" satisfies the properties that a three-dimensional bit-pattern bad pixel mask
;would have, then return a value of "1"