view_hdf version 3.0 README 1.0 Overview view_hdf is a visualization and analysis tool for accessing data stored in Hierarchical Data Format (HDF) and HDF-EOS (EOS extensions to HDF) files. It is being developed by the CERES Data Management Team at NASA Langley Research Center and is distributed by the NASA Langley Atmospheric Sciences Data Center (http://eosweb.larc.nasa.gov). The view_hdf tool can select and subset variables from either Science Data Set (SDS) or vdata structures in an HDF file, render both two- and three-dimensional graphics, and plot geolocated data onto various world map projections. Other features include multiple variable plots, difference plots, and simple statistics. Plots can be saved in PostScript, encapsulated PostScript and GIF or sent directly to a printer. Filtered subsets and statistical results can be written to a file in ASCII format for use in other analysis programs. This tool was developed primarily for the CERES project but is of more general use with many other HDF files, although it does not have the ability to read all HDF or HDF-EOS structures. The view_hdf tool is written in Interactive Data Language (IDL) and uses a graphical user interface to manipulate the data. It has been tested with IDL version 5.0 and higher. view_hdf also makes use of a shared library written in C which is accessed from the IDL program. In version 2.3.0, most of the functionality is now accessed directly through IDL and minimal use is made of the C shared library. The tool was developed on a UNIX platform and has been ported to SGI, Sun Solaris, HP, and DEC Alpha (running Digital Unix) workstations. It has also been ported to Windows NT. It should be portable to most platforms which support IDL, the HDF libraries, and a C compiler. 2.0 Installation Packages containing a pre-built shared library are available for several platforms from the NASA Langley Atmospheric Sciences Data Center and can be downloaded from the following URL: http://eosweb.larc.nasa.gov/view_hdf.html Both tar and gzip compressed tar files are available for each of the supported operating systems. If the gzip version is downloaded, uncompress it with the command: >gunzip view_hdf.tar.gz where > represents the Unix command line prompt. Then extract the files from the resulting tar file with the command: >tar xvf view_hdf.tar If the tar version is downloaded, use only the above tar command. The tar extraction will create a directory under the current directory and write the files in the view_hdf package into that directory. 3.0 Running view_hdf If your system is compatible with the system the view_hdf shared library was built on, you need only run IDL and start view_hdf within IDL: >idl IDL> view_hdf This should bring up the view_hdf GUI window. A sample data file CER_ES8_TRMM-PFM_AtLaunch_00000.19980101.50rec is included in the view_hdf package; this file can be opened in view_hdf to test for correct operation of the shared library on your system. To see the operating system and version of the system where the pre-built shared library was created, check the file named "built_on" that is part of the view_hdf package. The contents of this file are the output string from a uname -a command executed on the system where the shared library was built. 4.0 Building the shared library If your Unix operating system is not supported by any of the pre-built view_hdf packages, you can download any one of the Unix packages and modify it to compile the shared library on your system. Each of the packages also contains the HDF include files and libraries (HDF version 4.1r2) in the subdirectories named include and lib. If these files will not work with your computer and operating system, you can obtain other versions of the HDF files from the National Center for Supercomputing Applications (NCSA, developers of HDF) web site, http://hdf.ncsa.uiuc.edu To build the shared library on your system, you will need to run the script file named setup which is part of the view_hdf package. This file may need to be edited to use the proper C compiler and the proper compile and load options for your operating system. In particular, the options that need to be specified to create a shared library (as opposed to an executable file) need to be determined and modified in the setup script. As an example, here are the commands (comments excluded) from the setup script for Sun Solaris: setenv HDFINC ./include setenv HDFLIB ./lib cc -c -KPIC -Dsparc -I$HDFINC ies_bds.c get_digital_data.c ld -G -B symbolic -o ies_bds_rel2.so ies_bds.o get_digital_data.o \ -L$HDFLIB -lmfhdf -ldf -lz -lm -lc The -KPIC option for the cc command causes the compiler to build position-independent code which is needed for the shared library. The -G and -B symbolic options are needed for ld to generate a shared library file. These options differ from one operating system to the next. For example, on the HP running HP-UX, the cc option for generating position-independent code is +z and the ld option for creating a shared library is -b: cc -c +z -Ae -I$HDFINC ies_bds.c get_digital_data.c ld -b -o ies_bds_rel2.so ies_bds.o get_digital_data.o \ -L$HDFLIB -lmfhdf -ldf -lz -lm -lc So in general, it will be necessary to determine the C compiler to be used, the compile option(s) that will generate position-independent code, and the load option(s) that will create a shared library. The HP is different from the other tested operating systems in that it requires that *all* code linked to build a shared library be position independent. The HDF binary libraries from NCSA are not built as position independent code, so when building on the HP it is necessary to use the library files supplied with view_hdf or to obtain the HDF source code and build the libraries with the proper position independent compile options. Note that some operating systems give their shared library files a suffix other than the .so suffix used with view_hdf. The view_hdf IDL routine expects the shared library to be named ies_bds_rel2.so; if another name is used, the name needs to be changed in the IDL code. Or the name of the shared library can be specified directly in the ld command with the -o option as shown in the examples above; this is probably the easier approach. Once the compiler and option determinations have been made and the proper HDF library files are obtained, the shared library can be generated by executing the setup script at the Unix command line: >setup Additional setup script notes and operating system specific information are contained in the setup script file. Detailed view_hdf operating instructions are contained in the view_hdf Version 3.0 User's Guide, which is included in PDF format in the view_hdf package. A PostScript version can be downloaded from the view_hdf web site. Information about to view_hdf since version 3.0 is contained in the release notes for the current version. PDF and PostScript versions of the release notes are contained in the view_hdf packages and are available from the view_hdf web site. 5.0 Additional Assistance If there are questions about installing or using the view_hdf software, contact the NASA Langley Science, User and Data Services (SUDS) office. SUDS may be reached by e-mail: larc@eos.nasa.gov Telephone: 757-864-8656 Fax: 757-864-8807 The SUDS mailing address is: NASA Langley Atmospheric Sciences Data Center Science, User and Data Services Office Mail Stop 157D, 2 S. Wright St. Hampton, VA 23681-2199 USA Last revision date: 9/14/2001