;------------------------------------------------------------------------------
; NAME: QUBEPDS
;
; PURPOSE: To read a 3-dimensional image into an array variable
;
; CALLING SEQUENCE: Result = QUBEPDS (filename, label, [/SILENT])
;
; INPUTS:
;    Filename: Scalar string containing the name of the PDS file to read
;    Label: String array containing the qube header information
; OUTPUTS:
;    Result: 3-D image array constructed from designated record
;
; OPTIONAL INPUT:
;    SILENT: suppresses any message from the procedure
;
; EXAMPLES:
;    To read qube file QUBE.LBL into an array, qube:
;       IDL> label = HEADPDS ('QUBE.LBL',/SILENT)
;       IDL> qube = QUBEPDS ('QUBE.LBL', label, /SILENT)
;
; PROCEDURES USED:
;    Functions: GET_VIABLE, PDSPAR, STR2NUM, POINTPDS, CLEAN, REMOVE
;
; MODIFICATION HISTORY:
;    Adapted by Puneet Khetarpal from IMAGEPDS, August, 2002
;    24 Feb 2003, P. Khetarpal: rewrote program to be compatible with
;                               other functions, i.e., GET_VIABLE, POINTPDS,
;                               CLEAN, and REMOVE. Also, removed the use
;                               of PROC_ITEMS subroutine.
;
;------------------------------------------------------------------------------

function QUBEPDS, fname, label, SILENT=silent
   ; error protection:
   ON_ERROR, 2

   if n_params() LT 2 then begin
      print, 'Synatax: result = QUBEPDS (filename, label [,/SILENT])'
      return, -1
   endif

   if keyword_set(SILENT) then silent = 1 else silent = 0

   ; obtain qube objects from label:
   objects = GET_VIABLE (label,'QUBE')
   objarray = objects.array
   objcount = objects.count
   objindex = objects.index

   ; obtain required keyword parameters from label:
   axes = PDSPAR (label, 'AXES')
   axis_name = PDSPAR (label, 'AXIS_NAME')
   core_items = PDSPAR (label, 'CORE_ITEMS')
   core_bytes = PDSPAR (label, 'CORE_ITEM_BYTES')
   core_type = PDSPAR (label, 'CORE_ITEM_TYPE')
   suf_bytes = PDSPAR (label, 'SUFFIX_BYTES')
   suf_items = PDSPAR (label, 'SUFFIX_ITEMS')

   ; process core items and suffix items dimensions:
   temp_name = str_sep (axis_name, ',')
   temp_citems = str_sep (core_items, ',')
   temp_sitems = str_sep (suf_items, ',')

   param = ['"',',','(',')']
      
   for i = 0, n_elements(temp_name)-1 do begin
      temp_name[i] = REMOVE (temp_name[i],param)
      temp_name[i] = CLEAN (temp_name[i],/SPACE)
      temp_citems[i] = REMOVE (temp_citems[i],param)
      temp_citems[i] = CLEAN (temp_citems[i],/SPACE)
      temp_sitems[i] = REMOVE (temp_sitems[i],param)
      temp_sitems[i] = CLEAN (temp_sitems[i],/SPACE)

      CASE temp_name[i] OF
         'SAMPLE': begin
                      X_core = long(temp_citems[i])
                      X_suf = long(temp_sitems[i])
                   end
           'LINE': begin
                      Y_core = long(temp_citems[i])
                      Y_suf = long(temp_sitems[i])
                   end
           'BAND': begin
                      Z_core = long(temp_citems[i])
                      Z_suf = long(temp_sitems[i])
                   end
             else: message, 'ERROR: invalid AXIS_NAME parameter.'
      ENDCASE
   endfor

   ; print dimensions of qube if not is silent mode: 
   if NOT (silent) then begin
      if X_core GT 0 AND Y_core GT 0 AND Z_core GT 0 then begin
         text = string(X_core)+' by'+string(Y_core)+' by'+string(Z_core)
         print, 'Now reading '+text+' qube array'
      endif else begin
         print, fname+' has X or Y or Z = 0, no data array to read'
      endelse
   endif

   ; process item bytes and item_type:
   bits = STR2NUM(core_bytes[0]) * 8
   bits = bits[0]
   item_type = core_type[0]
   item_type = item_type[0]

   ; check item type for MSB, LSB, IEEE, or VAX:
   items = str_sep(item_type, '_')
   n_items = n_elements(items)
   j = 0
   flag = 1
   while j LT n_items AND flag NE -1 do begin
      if (items[j] EQ 'MSB') OR (items[j] EQ 'INTEGER') OR $
         (items[j] EQ 'UNSIGNED') then begin
         item_type = 'MSB'
         flag = -1
      endif else if (items[j] EQ 'LSB') then begin
         item_type = 'LSB'
         flag = -1
      endif else if (items[j] EQ 'VAX') then begin
         item_type = 'VAX'
         flag = -1
      endif else if (items[j] EQ 'IEEE') OR (items[j] EQ 'REAL') then begin
         item_type = 'IEEE'
         flag = -1
      endif
      j = j+1
   endwhile

   ; check for integer type either SIGNED or UNSIGNED:
   integer_type = item_type
   rightpos = strpos (strupcase(integer_type),'UNSIGNED')
   if (rightpos GT -1) then begin
      integer_type = 'UNSIGNED' 
   endif else begin
      integer_type = 'SIGNED'
   endelse

   ; obtain pointer information:
   pointer = POINTPDS (label, fname, objarray[0])
   datafile = pointer.datafile
   skip = pointer.skip

   ; intialize the image array for respective ITEM BITS:
   CASE bits OF
      8: begin
            IDL_TYPE = 1
            element = bytarr(X_core, Y_core, Z_core,/NOZERO)
            tempimg = bytarr(X_core,/NOZERO)
         end
     16: begin
            IDL_TYPE = 2
            element = intarr(X_core, Y_core, Z_core,/NOZERO)
            tempimg = intarr(X_core,/NOZERO)
         end
     32: begin
            if item_type EQ 'MSB' OR item_type EQ 'LSB' then begin
               IDL_TYPE = 3
               element = lonarr(X_core, Y_core, Z_core,/NOZERO)
               tempimg = lonarr(X_core,/NOZERO)
            endif else begin
               IDL_TYPE = 4
               element = fltarr(X_core, Y_core, Z_core,/NOZERO)
               tempimg = fltarr(X_core,/NOZERO)
            endelse
         end
     64: begin
            IDL_TYPE = 5
            element = dblarr(X_core, Y_core, Z_core,/NOZERO)
            tempimg = dblarr(X_core,/NOZERO)
         end
   else: message, 'ERROR: illegal value of BITPIX <= ' + $
            strtrim(string(bitpix),2)+ ' in '+fname
   ENDCASE

   ; process suffix bytes:
   suf_bytes = STR2NUM(suf_bytes[0])
   suf_bytes = suf_bytes[0]

   if X_suf GT 0 OR Y_suf GT 0 then begin
      if X_suf GT 0 then begin
         xsflag = 1
         xsuf_bytes = suf_bytes * X_suf
         xjump = bytarr(xsuf_bytes)
      endif else xsflag = -1
      if Y_suf GT 0 then begin
         ysflag = 1
         ysuf_bytes = suf_bytes * Y_suf
         yjump = bytarr(ysuf_bytes)
      endif else ysflag = -1
   endif else begin
      xsflag = -1
      ysflag = -1
   endelse

   ; read the file:
   openr, unit, datafile, /GET_LUN
   point_lun, unit, skip

   counter = fix(0)
   counter2 = fix(0)
   while counter LT Z_core do begin
      while counter2 LT Y_core do begin
         readu, unit, tempimg
         if ysflag GT -1 then $
            readu, unit, yjump
         element[*,counter2,counter] = tempimg[*]
         counter2 = counter2 + 1
      endwhile
      if xsflag GT -1 then $
         readu, unit, xjump
      counter = counter + 1
      counter2 = 0
   endwhile

   close, unit
   free_lun, unit

   ; conversion to UNIX readable type:
   CASE item_type OF
      'MSB': ; no conversion needed
     'IEEE': ; no conversion needed
      'VAX': element = conv_vax_unix (element)
      'LSB': element = conv_vax_unix (element)
       else: begin
                message, 'WARNING: unrecognized CORE_ITEM_TYPE - ' + $
                   core_type[0]+' no conversion performed.'
             end 
   ENDCASE

   ; conversion of data if unsupported by IDL:
   if (bits EQ 8 AND integer_type EQ 'SIGNED') then begin
      element = fix(element)
      fixitlist = where (element GT 127)
      if fixitlist[0] GT -1 then begin
         element [fixitlist] = element[fixitlist] - 256
      endif
   endif else if (bits EQ 16 AND integer_type EQ 'UNSIGNED') then begin
      element = long(element)
      fixitlist = where (element LT 0)
      if fixitlist[0] GT -1 then begin
         element[fixitlist] = element[fixitlist] + 65536
      endif
   endif else if (bits EQ 32 AND integer_type EQ 'UNSIGNED') then begin
      element = double(element)
      fixitlist = where (element LT 0.D0)
      if fixitlist[0] GT -1 then begin
         element[fixitlist] = element[fixitlist] + 4.294967296D+9
      endif
   endif

   return, element
end