IDL Supported Version(s): 6.x DESCRIPTION: =========== READPDS.PRO is an IDL function that reads data from a PDS image or data table file and stores it in an IDL structure. (It is the 'top level' program that all of the others in this set are written to serve.) The calling syntax of READPDS.PRO is as follows: result = READPDS( filename,[ /SILENT, /NOSCALE] ) where: - 'result' is the data returned from the PDS image or data table file being read by READPDS. - 'filename' is a scalar string containing the name of the PDS file to be read. - 'SILENT' is an optional argument to READPDS that will suppress the default display of the size of the array or structure. - 'NOSCALE' is an optional argument to READPDS that will suppress the default application of SCALING_FACTOR and OFFSET values to and PDS IMAGE or QUBE object array. READPDS.PRO uses all of the functions in this directory: ADDEOBJ, APPLY_BITMASK, ARRCOLPDS, ARRCOL_STRUCT, ARR_STRUCT, BTABVECT2, CLEANARR, CLEAN, COLL_STRUCT, ELEM_STRUCT, GET_INDEX, GET_IDL_TYPE, HEADPDS, IMAGEPDS, OBJPDS, PDSPAR, POINTPDS, QUBEPDS, READPDS, REMOVE, STR2NUM, TASCPDS, TBINPDS, and TIMEPDS. All of these must be present or be in the idl path for READPDS.PRO to function properly. As of this version, it is intended to be used on MSB and LSB architectures, i.e.,'big-endian' and 'little-endian,' respectively. CHANGE LOGS: =========== Version Date Programmer Description 4.3 2008-04-25 P. Choganwala Resolved all the problems reading BINARY MIRO data sets. These include following. - Enhanced pointpds to look into /label directory for format files(both upper and lower case). - Modified output data structure to properly read level-2 and level-3 MIRO data sets. - Fixed the problem of data type while reading large BINARY tables. - Added get_idl_type routine.This routine converts data type from label file to correct idl data type. 4.3 2008-02-25 P. Choganwala Resolved BYTE specification problem in tascpds.pro. The program was not reading ASCII tables correctly because of BYTE specification error.The problem was solved by restucturing if-else statements in tascpds.pro. 4.3 2007-10-14 P. Choganwala Fixed leading zero problem in pdspar.pro This program was trimming off the leading zeros while reading keywords.The function was corrected which was removing leading zeros. 4.1.1 2005-04-18 P. Khetarpal Fixed problem with headpds changing the name of the input file. Resolved row suffix bytes and padding bytes conflict, and fixed some minor errors in table object reading. 4.1 2005-01-28 P. Khetarpal Resolved compatibility for both MSB and LSB architectures of all routines. Array and collection objects routine was rewritten for updated standards. Re-instated the NOSCALE keyword for images and qubes. Included bit masking for signed and unsigned integers. 4.0 2004-08-01 P. Khetarpal Rewrote the major routines for reading images, tables, and qubes by using IDL structures to read data directly, instead of reading data element by element. Also, rewrote routines using many levels of subroutines, and thorough error-checking. Heavy comments were added to almost all routines. The previous releases of version 3.3.x are compiled into one in this release of pdsread. 3.3.x 2004-03-18 P. Khetarpal Fixed bugs for reading array objects included with other non-array objects for IDL. Wrote a new binary array routine to read arrays with axes greater than 2. 3.2 2003-12-02 P. Khetarpal Fixed bugs for reading tables with long int number of rows or columns; fixed item byte issue for reading tables. 3.1 2003-10-03 P. Khetarpal Updated for standards changes; fixed minor bugs; increased robustness of subroutines; added a subroutine to handle cleaning of string arrays. 3.0 2003-08-05 P. Khetarpal Updated for standards changes; added WINDOW support; added "examples" directory; included ARRAY and COLLECTION object support. EXAMPLES: ======== LABEL: ----- - to obtain a PDS label information as a string array variable, type > label = HEADPDS('pdsfile.lbl') which will return a string array of the entire pdsfile.lbl and put it into the variable label. - to obtain a PDS ASCII file that may not contain a header, type > label = HEADPDS('asciifile.txt', /FILE) which will return the entire text file and store it into variable label. - to obtain only the associated ^STRUCTURE file FORMAT.FMT from a label, type > fmt = HEADPDS('format.fmt', /FORMAT) which will return the entire format.fmt contents and store it into the variable fmt. * Note: headpds will extract the ^STRUCTURE files by default from a label if the keyword is present. IMAGE: ----- - to read a PDS image file for viewing, type > img = READPDS('image.lbl') which will read data from the file and put it into the variable, 'img'. If there are any OFFSET or SCALING_FACTOR keywords present in the IMAGE object, then it will apply them to the image array by default. If you would like to obtain the image without the OFFSET or SCALING_FACTOR values applied, then type > img = READPDS('image.lbl', /NOSCALE) The following message will be displayed: Now reading header: image.lbl Now reading 128 by 128 array ** Structure , 2 tags, length=32770, data length=32770, refs=1: OBJECTS INT 1 IMAGE INT Array[128, 128] - to view, type > tvscl, img.image which should bring up an idl window with an image of the data from 'image.lbl' in it. (Multiple images would be returned as an IDL structure with the first element named 'images' being the number of images contained and the other elements being the images in order found.) Note: img is no longer an image array, but a structure. TABLES: ------ - to read a PDS ascii table to read or extract information from later, type > data = READPDS('ascii.lbl') - to read a PDS binary table to read or extract information from later, type > data = READPDS('binary.lbl') in either case, READPDS will return the data as an IDL structure: Now reading header: ascii.lbl Now reading table with 2 Columns and 20 Rows ** Structure , 2 tags, length=368, data length=358, refs=1: OBJECTS INT 1 TABLE STRUCT -> Array[1] To access the table, type: > help, /STRUCTURE, data.table ** Structure , 3 tags, length=360, data length=356, refs=2: COLUMN_NAMES STRING Array[3] COLUMN1 DOUBLE Array[20] COLUMN2 DOUBLE Array[20] Here's how to access columns: To access entire table: print, result.table column names: print, result.table.column_names first column: print, result.table.column1 second column: print, result.table.column2 which should cause the contents to print to the screen. ** Note: For PDS tables, the IDL routines access the "structure" file (.fmt) automatically as long as the "structure" file is in the same directory. QUBE: ---- - to read a PDS cube to read or extract information from later, type > cube = READPDS ('qube.lbl') which should return a three dimensional array. Now reading header: qube.lbl Now reading 256 by 98 by 432 qube array ** Structure , 2 tags, length=21676034, data length=21676034, refs=1 OBJECTS INT 1 QUBE INT Array[256, 98, 432] - to view the data from any of the frames, type > frame = cube[*,*,0] > tvscl, frame which should display the first frame on the screen. 6D ARRAY: -------- - to read a PDS 6D image array with 1 ELEMENT sub-object and the last axis is set to NAXIS6 = 1, type array = READPDS ('array.lbl') which should return a five dimensional array of data. Since NAXIS6 = 1, IDL ignores this axis (for example, a 128 x 128 x 1 image cube is equivalent to a 128 x 128 image). Now reading header: array.lbl Now constructing ARRAY/COLLECTION structure to be read Now reading ARRAY/COLLECTION object ** Structure , 2 tags, length=262148, refs=1: OBJECTS INT 1 ARRAY LONG Array[128, 128, 2, 1, 2] - the above description is from an example KECK data file in FITS format. The FITS file contains 2 stacked sets (chop-nod sets), each containing 2, two-dimensional images. The PDS label was written as an array object to be read and then displayed as an image. - to view the first image, type: > tvscl, result.array[*,*,0,0,0,0] or > tvscl, result.array[*,*,0,0,0] which should display the first frame on the screen. NOTE: The new PDS IDL routines have been modified so that multiple data objects can be embedded in one file. For example, one can have an image and a table in the same data file. The "result" would be returned as a structure of three objects containing the number of objects, the image array, and the table structure. Now you can also read the primitive object types such as the ARRAY objects and the COLLECTION objects. (for more information on IDL structures, see the IDL User's Guide)