PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM OBJECT = TEXT NOTE = " READPDS.TXT file for the new BETA version of READPDS.PRO. The IDL routines that read various PDS objects have been modified to 1) Read the PDS QUBE object, 2) Read multiple data objects embedded in one PDS file, and 3) Return all results into an IDL data structure (instead of an array) For example, if a PDS file contains an image object and a table object, the new version of READPDS (and the routines it calls) will return the results into an IDL data structure. The data structure will contain three objects: the number of objects, the image array, and the table structure. For more information about IDL data structures, refer to the IDL User's Guide. " PUBLICATION_DATE = 2002-11-11 END_OBJECT END ***** File READPDS.TXT READPDS.PRO is an IDL function that reads data from a PDS image, data table file, or cube and stores it in an IDL structure. READPDS is the main IDL function in this directory. It calls the other IDL programs in this directory: ARASCPDS, ARBINPDS, BTABVECT, CLEAN, COLASPDS, COLBIPDS, HEADPDS, IMAGEPDS, PDSEXPAR, PDSPAR, POINTPDS, QUBEPDS, STR2NUM, TASCPDS, TBINPDS, and TIMEPDS. All of these IDL routines must be present or in your idl path for READPDS to properly function. CALLING SYNTAX The calling syntax of READPDS.PRO is result = READPDS( filename,[ label,/NOSCALE,/SILENT] ) where - 'result' is the data returned from the PDS image or data table file being read by READPDS. NOTE: The 'result' is an IDL data structure. In the previous version of READPDS, 'result' was an array. - 'filename' is a scalar string containing the name of the PDS file to be read. - 'label' is an optional argument to READPDS to return the string array containing the label from the PDS file being read, as per HEADPDS. - '/NOSCALE' is an optional argument to READPDS that will suppress the default scaling of the output using the optional OFFSET and SCALING_FACTOR keywords in the PDS label. - 'SILENT' is an optional argument to READPDS that will suppress the default display of the size of the array or structure. EXAMPLES 1) To read a PDS image file for viewing, type img = READPDS('image.lbl') which will read data from the file and put it into an IDL data structure called 'img'. To view the image, type tvscl,img.object1 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. See IMAGEPDS.DOC for further information.) REMEMBER, 'img' is no longer an image array, but an IDL data structure. 2) To read a PDS ascii table or a PDS binary table, respectively, type data = READPDS('ascii.lbl') or data = READPDS('binary.lbl') In either case, READPDS will return the data as an IDL structure. To view pieces of the IDL structure, issue the following IDL commands: To view Type into IDL -------------- --------------------------------- Entire table print, data.object0 Column names print, data.object0.column_names First column print, data.object0.column1 Second column print, data.object0.column2 These commands will write the requested table contents to your screen. 3) To read a PDS cube, type cube = READPDS ('qube.lbl') The result is placed in a three dimensional array called 'cube'. To view the data from any of the frames within the cube, type frame = cube[*,*,0] tvscl, frame This will display of the first frame within the cube on your screen. COMPATIBILITY WARNINGS 1) The new versions of the programs were tested on IDL Version 5.5 for Solaris (sunos sparc). The programs may not work as well on other systems/versions. 2) READPDS is intended to be used only on MSB architectures ('big-endian') with files that were written on an MSB architecture. At this time, READPDS cannot convert from MSB to other architectures. ***** ADDITIONAL INFORMATION from the original version of READPDS PDSREAD was created at the Small Bodies Node (SBN) of the Planetary Data System (PDS) to read PDS image and data files. For complete explanations regarding the use of any of these programs, check the headers of the program source files, which end in '.pro'. HISTORY: These programs were announced for original test release at the November, 1994 meeting of the Planetary Data System, and have been included on this CD-ROM for use with any PDS image or table files on this disc or elsewhere. A complete listing of the programs follows: btabvect.pro -retrieves vectors from PDS binary tables headpds.pro -retrieves the PDS label from a file imagepds.pro -retrieves image data from PDS image files pdspar.pro -retrieves specified data from PDS labels readpds.pro -calls imagepds, tascpds, and tbinpds, returns data str2num.pro -converts character string to numerical form tascpds.pro -retrieves data from PDS ascii table files tbinpds.pro -retrieves data from PDS binary table files timepds.pro -retrieves time from PDS labels or ASCII tables arascpds.pro -reads a PDS ascii array into an IDL array or an IDL structure arbinpds.pro -reads a PDS binary array into an IDL array or structure colaspds.pro -reads a PDS ascii collection into an IDL structure colbipds.pro -reads a PDS binary collection into an IDL structure NOTE: Additional programs not written at SBN are required to properly access binary table data. They are 'conv_vax_unix.pro' and 'ieee_to_host.pro', and may be found in NASA/Goddard's IDL Astronomy Users Library (anonymous ftp at idlastro.gsfc.nasa.gov /pub/astron.tar.Z or WWW URL listed below) PDS objects supported by these programs Major Objects: ARRAY COLLECTION IMAGE TABLE INDEX_TABLE GAZETTEER_TABLE PALETTE SERIES SPECTRUM TEXT Sub-objects: COLUMN PDS objects not supported by these programs: BIT_COLUMN BIT_ELEMENT CATALOG CONTAINER ELEMENT HISTOGRAM HISTORY IMAGE_MAP_PROJECTION QUBE SPICE_Kernal PDS objects not needed by these programs: DATA_PRODUCT DATA_SUPPLIER DIRECTORY DOCUMENT FILE HEADER VOLUME ============================================================================ Quick guide for new IDL users: To use these functions to view a pds image; 1) copy these functions to a directory of your choice, 2) make sure you are in a 'windows' type environment (eg; x-windows, MS-Windows,open-windows,etc ) before proceeding, 3) at the prompt type: idl on a unix system, this should bring up a prompt like this : IDL> 4) at the 'IDL>' prompt, type IDL commands as you would DOS or UNIX commands, example: tvscl, readpds(imgfile) this should bring up a window with a display of the image inside. 5) to exit 'IDL' type : exit this will return you to the normal prompt, and close any idl image windows still open at the time. ============================================================================ FITS: I/O software in the commercial language IDL is available from the IDL Astronomy Library (Landsman 1995), which is accessible from the WWW site http://idlastro.gsfc.nasa.gov/homepage.html. Landsman, W.B. 1995, ``The IDL Astronomy User's Library'' in ``Astronomical Data Analysis Software and Systems IV", ed. R. Shaw, H.E. Payne, J.J.E. Hayes, ASP Conference Series 77, p. 437 A listing of some particularly useful 'idlastro' procedures follow: headfits.pro -retrieves the FITS header from a file readfits.pro -reads a FITS file, returns data sxaddpar.pro -add or modify a parameter in a FITS array sxpar.pro -retrieves specified data from FITS headers wherenan.pro -finds the position of the IEEE NaN special values LICENSING INFORMATION: IDL is the property of Research Systems, Inc., Copyright 1989-1994 All rights reserved. Unauthorized reproduction prohibited. The University of Maryland is licensed to use IDL.