Visualization Software for the Tropical Rainfall Measuring Mission

(TRMM)

The Orbit

Viewer Tutorial

version 1.3.6

Developed by the Precipitation Processing System

pps.gsfc.nasa.gov

Hurricane Ivan. The TRMM Precipitation Radar observed Hurricane Ivan on September 15, 2004, one day before it struck the Florida Panhandle. The data in the image are rainfall rate estimates at an altitude of 2.5 km taken from the three dimensional estimates of the 2A25 algorithm. The Orbit Viewer created this image.

PPS, NASA Goddard, Greenbelt, Maryland. First published in HTML in 2000. First published in PDF in 2003. Revised in 2008. To obtain a copy of the Orbit Viewer or this tutorial, visit the PPS web site [http://pps.gsfc.nasa.gov]. The Orbit Viewer for TRMM data was developed by NASA and any use of it should be acknowledged. The TRMM data used in this tutorial were provided by NASA, JAXA, and NICT. The Orbit Viewer is written in the IDL language, which is manufactured by ITT [http://www.ittvis.com]. If you have questions about the Orbit Viewer, contact the PPS Helpdesk at helpdesk@pps-mail.nascom.nasa.gov or 301-614-5060. Alternatively, contact the Orbit Viewer developer and author of this tutorial at Owen.A.Kelley@nasa.gov or 301-614-5245.

Contents

1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1. Tutorial Overview 1.2. TRMM Data 1.3. Bug Reports 2. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 2.1. Freeware Installation under UNIX / Linux 2.2. Freeware Installation under Mac OS X 2.3. Freeware Installation under Microsoft Windows 2.4. Developer Installation 3. Data Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 3.1. Basic Display 3.2. Vertical View Fixed Cross Section Variable Cross Section 3.3. 3D View 3.4. Generic View 3.5. Array Summaries 3.6. Colors 3.7. Image Options 3.8. Displaying the TRMM Mission Index 3.9. Miscellaneous Topics Interactive Commands Right-Side Up

4. Data Subsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 4.1. Create an Image 4.2. Create a Data Subset 4.3. Read a Subset with IDL IDL Basics Reading HDF 4 in IDL Reading ASCII in IDL 4.4. Read a Subset with Matlab Matlab Basics Reading HDF 4 in Matlab Reading ASCII in Matlab Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

6

1 Introduction

The Tropical Rainfall Measuring Mission (TRMM) satellite measures rainfall and related variables. TRMM is a joint mission of the United States (NASA) and Japan (JAXA and NICT). Launched in 1997, the TRMM satellite carries the first satellite-borne radar capable of measuring the detailed three-dimensional structure of rain. The Precipitation Processing System (PPS) processes data from three instruments on the TRMM satellite: the radar, a passive microwave instrument, and a passive visible and infrared instrument. The Orbit Viewer is a tool for displaying TRMM standard products produced at PPS. Since 1997, PPS has developed and distributed the Orbit Viewer. The Orbit Viewer runs under SGI Unix, Linux, Windows XP, and Mac OS X. The Orbit Viewer can be downloaded at no cost from the PPS web site [http://pps.gsfc.nasa.gov].

7

1.1. Tutorial Overview Chapter 1 provides an introduction to TRMM data products. Chapter 2 discusses installing the Orbit Viewer. The Orbit Viewer requires 128 megabytes of memory to display some arrays in full-orbit files (such as 2A25.rain and 1C21.normalSample). The Orbit Viewer is designed for monitors with at least 1100 by 850 pixels, but most features will work on monitors as small as 800 by 600 pixels. Chapter 3 describes how to display data with the Orbit Viewer. The Orbit Viewer makes it easy to perform an initial examination of TRMM data files. The viewer allows you to display TRMM data at the full instrument resolution on a map of the Earth. Vertical cross sections and 3D images of rain structure can also be created. In addition to standard HDF products, the Orbit Viewer can read TRMM real-time products and the daily gridded text product (3G68). The Orbit Viewer creates images for on-screen display, i.e., with a resolution of approximately 90 dots-per-inch (dpi). This is sufficient for informal presentations, but it is not publication quality (600+ dpi). Chapter 4 describes how to create data subsets and save images to files. Once you create an image in the Orbit Viewer, you can save that image in various image formats, such as PNG and Postscript. In addition, you can save the data in various data formats, such as GrADS binary, Arc/Info text, or pure ASCII text. Chapter 5 describes how to search through the TRMM dataset to decide which orbits to order from the TRMM archive.

1.2. TRMM Data The Precipitation Processing System (PPS) at NASA Goddard produces TRMM standard products for three instruments on the TRMM satellite: the Precipitation Radar (PR), the TRMM Microwave Imager (TMI), and the Visible and Infrared Scanner

8

(VIRS). Contact the following organizations for information about two other TRMM instruments: for the Lightning Imaging Sensor (LIS), contact Marshall Space Flight Center [http://thunder.msfc.nasa.gov], and for the Clouds and the Earth's Radiant Energy System (CERES), contact Langley Space Flight Center [http://eosweb.larc.nasa .gov]. There are two main web sites for TRMM, one hosted by the United States and one by hosted by Japan: [http://trmm.gsfc. nasa.gov] and [http://www.eorc.JAXA.go.jp/TRMM]. The file specification for TRMM standard products can be downloaded from PPS in the Interface Contro l Spec i f i cat ion (ICS), volumes 3 and 4 [http://pps.gsfc.nasa.gov]. The TRMM PR Algori thm Instruct ion Manual contains a more detailed description of the algorithms for the TRMM Precipitation Radar. To download the PR manual, go to the JAXA TRMM web site and click on “Document.” The Goddard Earth Sciences Distributed Active Archive Center (DAAC) archives TRMM standard products and distributes them to the public. The data ordering page at the DAAC is [http://lake.nascom.nasa.gov/data/dataset/TRMM]. PPS generates TRMM standard products and distributes them to the public via anonymous FTP: [ftp://trmmopen.gsfc.nasa.gov/ pub/trmmdata/ByDate/]. TRMM standard products are stored in the HDF 4 format, version 4.0r2. This version of HDF 4 is no longer on the NCSA web site, but it can still be obtained from NCSA or PPS. An HDF 4 manual can be downloaded from [http://hdf.ncsa. uiuc.edu] or [ftp://ftp.ncsa.uiuc.edu/HDF/HDF/Documentation/HDF4.1r3/Users_Guide]. Be aware that the HDF 5 format and HDF-EOS format are not compatible with the HDF 4 format of TRMM data products. You must install the HDF 4 libraries before you will be able to read HDF 4 data into a C or FORTRAN program. Optionally, you may also install the PPS I/O Toolkit if you are using a UNIX computer. If you do not need to read TRMM data into a C or FORTRAN program and you only want to make images, it is easier to install just the Orbit Viewer on your computer. The Orbit Viewer works without you

9

having to install the HDF library or the PPS I/O Toolkit. The Orbit Viewer is able to read and display HDF on its own because it is written in the IDL language, which is created by the Visual Information Solutions (VIS) subsidiary of the International Telephone & Telegraph (ITT) Corporation. The ITT VIS web site is [http://www.ittvis.com]. You do not need to install the IDL language on your computer before running the Orbit Viewer because a stripped-down copy of IDL comes packaged within the Orbit Viewer. Since the launch of the TRMM satellite in 1997, hundreds of journal articles have been published about the TRMM instruments, TRMM rainfall algorithms, and applications of TRMM data. A partial list of articles is maintained on NASA’s TRMM web site [http://trmm.gsfc.nasa.gov]. Below are a few articles that may serve as starting points:

Kummerow, C., and W. Barnes, 1998: The Tropical

Rainfall Measuring Mission (TRMM) Sensor Package. J . Atmos. and Oceanic Tech. , 15, 809–17.

(PR instrument) Kawanishi, T., et al., 2000: TRMM Precipitation Radar. Adv. Space Research, 25, 969–72.

(PR rain algorithm: 2A25) Iguchi, T., et al., 2000: Rain Profiling Algorithm for TRMM Precipitation Radar Data. Adv. Space Research , 25, 973–76.

(TMI rain algorithm: 2A12) Kummerow, C., et. al., 1996: A Simplified Scheme for Obtaining Precipitation and Vertical Hydrometeor Profiles from Passive Microwave Sensors. IEEE Trans. on Geosci ence and Remote Sensing , 34, 1213–32.

(TMI rain algorithm: 2A12) Chang, A.T.C., et al, 1999: First Results of the TRMM Microwave Imager (TMI) Monthly Oceanic Rain Rate: Comparison with SSM/I. Geophysi cal Research Letters , 26, 2379–82.

(VIRS instrument) Lyu, C., et al., 2000: First Results from the On-Orbit Calibrations of the Visible and Infrared Scanner for the Tropical Rainfall Measuring Mission. J . o f Atmos. and Oceanic Tech., 17, 385-94.

10

(Combined PR/TMI rain algorithm: 2B31) Haddad, Z.S., et al., 1997: The TRMM ‘Day-1’ Radar/Radiometer Combined Rain-Profiling Algorithm. J . o f the Meteorolog i cal Soc ie ty o f Japan , 75, 799–09.

Several terms are used in this tutorial in very specific ways: algorithm, product, version, level, and swath. An algorithm is a computer program that processes data, not the set of mathematical steps that the program carries out. A product is a kind of data file that is defined by a particular set of variables and format (such as HDF or text). A product is also the final output of an algorithm. The version of a product generally identifies the processing cycle that created it. Product version 3 indicates the first processing cycle, which began shortly after the launch of the TRMM satellite in November of 1997. The Goddard DAAC distributes PR and TMI orbital data collected after December 8 of 1997 and VIRS data after December 20 of 1997. Gridded products are available starting with observations from January of 1998. In October of 1998, PPS updated the algorithms, and the resulting products were classified as product version 4. In November of 1999, PPS began yet another processing cycle, which created product version 5. In August 6 to 16 of 2001, the TRMM satellite increased its orbiting altitude from 350 to 402.5 km. This orbit boost altered the footprint of the instruments and required a slightly different version of some algorithms to compensate for the change. For this reason, the files created after the orbit boost were initially designated product version 5A. In April of 2004, PPS began producing product version 6. From July 1 to August 5, 2004, orbit boosts were forbidden, which caused degradation in some TRMM products due to orbit decay. The 402.5 km orbit was restored in early August of 2004. In 2010, PPS anticipates that it will begin producing TRMM product version 7. In 2013, PPS anticipates that the Orbit Viewer will be modified so that it will be able to display products from Global Precipitation Measurement (GPM) Mission to be launched that year [http://gpm.gsfc.nasa.gov/].

11

The level of a product indicates the degree to which the data have been processed. Some level 1 products contain instrument-independent physical variables such as radar reflectivity or brightness temperature in the original observation geometry of the instrument (i.e., the satellite’s data swath). Other level 1 products contain engineering variables, such as returned power, that are instrument dependent. Level 2 products have been further processed so that they contain geophysical variables such as rainfall rate. Generally, level 2 products have the same observation geometry as the corresponding level 1 product. Level 3 products contain time-averaged and space-averaged data, such as monthly average rainfall rate in 5 degree latitude/longitude grid boxes. The two observation geometries for arrays are grids and swaths. TRMM grids are composed of boxes of data that each cover a particular number of degrees of latitude and longitude, such as 5 degrees. A swath is collected by an instrument that is scanning across the direction of motion of the satellite. Many TRMM swath arrays have two dimensions: field-of-view (fov) and scan number. A field-of-view is an individual observation. A scan line is one row of field-of-views. Some swath arrays have a third dimension such as height or instrument channel. In addition to arrays, TRMM files contain tables and text fields. Tables sometimes contain one row for each scan in a swath, but not all tables are tied to a swath in this way.

1.3. Bug Reports If you find a bug in the Orbit Viewer, please contact the PPS Helpdesk at [helpdesk@pps-mail.nascom.nasa.gov] or 301-614-5060. When asking the helpdesk a question or reporting an error, please include the following information:

What operation were you performing when the error occurred? For example, were you opening a file, creating a zoom image, or saving a subset?

12

Please mention any error messages that appeared on the screen.

What operating system are you using? For example, is it Red Hat Linux, SGI IRIX, or Microsoft Windows XP?

Have you purchased your own IDL license from RSI, or are you using the embedded IDL license that comes with the freeware Orbit Viewer?

What version of the Orbit Viewer are you using? The version number is printed in the lower-right corner of the main window.

What is the name of the data file that you were displaying when the error occurred?

13

2 Installation

The Orbit Viewer can be installed on several operating systems and in two modes of use. The operating systems are Linux, SGI IRIX, Mac OS X, or Microsoft Windows XP. The modes of use are freeware mode and developer mode. Experienced software developers may wish to run the Orbit Viewer in developer mode. Developer mode requires the purchase of an IDL license, but it allows modification of the Orbit Viewer’s source code.

2.1. Freeware Installation under UNIX/Linux

The Orbit Viewer is primarily designed to run under one variety of UNIX, i.e., under Linux. The Orbit Viewer also runs on SGI IRIX, but that support will end in the near future because as of IDL version 7.0 release in November of 2007, IDL is no longer supported on SGI IRIX.

14

To obtain the Orbit Viewer from the web, download the zip file appropriate to your operating system from [http://pps.gsfc.nasa.gov]. If you are running 64-bit Linux, download the zip file that contains the string "linux64bit". Alternatively, if you are running 32-bit Linux, download the zip file that contains the string "linux32bit". After downloading the zip file, place it in your "~" home directory or wherever you wish to install it. Type “unzip –qq f i l ename.zip” to create the orbit directory. Go into the orbit directory ("cd orbit") and type “./setupUNIX.sh” to run the Orbit Viewer setup shell script. You can now launch the Orbit Viewer by typing “~/orbit.sh” on the UNIX command line. You can use several UNIX command line options when launching an Orbit Viewer session. The command line options are listed in table 2.1. In the table, the command to launch the Orbit Viewer has been shortened from “~/orbit.sh” to just “orbit”. You can shorten the command by creating a link or an alias as described in step 3 of section 2.4. of the tutorial.

Table 2.1. UNIX Command Line Options

orbit Launch the Orbit Viewer. orbit -help Print usage instructions. orbit file Open a file and run in the

background. orbit -debug file Launch the Orbit Viewer

and open a file. With the optional –debug keyword, debug statements are printed.

orbit -no_file Open the Orbit Viewer without being prompted for a filename.

orbit -interact See section 3.8.

The rest of this section provides tips on specific issues that may come up when you install the Orbit Viewer on a UNIX system.

15

libXp.so.6 under 64-bit Linux When starting the Orbit Viewer on a 64-bit Linux system, IDL may crash and print the following error message to UNIX standard out:

error while loading shared libraries: libXp.so.6: cannot open

shared object file: No such file or directory This error is known to have occurred on some Redhat Linux and CentOS Linux systems. ITTvis Tech Tip #3923 discusses this error. The problem is due to IDL needing a different version of the X11 library than the version that is installed by default on some 64-bit Linux systems. The following commands, executed by the system's root user, may install the required version:

yum install libXp.x86_64 yum install libXp

[Release 1.3.6]

Developer Mode under UNIX and Linux To use developer mode, you must first purchase a developer license for the IDL language. Contact ITT, the manufacturer of IDL, to purchase a developer license for IDL version 7.0 or later [http://www.ittvis.com], which was released in November of 2007. To set up for developer mode, make a one-time modification to the orbitUNIX.sh shell script in the orbit/TSDISorbitViewer directory. Locate the “main line” section near the bottom of the script. Change ‘is_CDROM=“yes” ’ to ‘is_CDROM=“no” ’. Then, follow steps 2 and 3 of section 2.4 of this tutorial. [release 1.3]

Linux: Scrambled Colors Suppose you set up the Orbit Viewer, open a TRMM file with it, and select an array from the list on the left side of the main window. The Orbit Viewer should respond by generating a global image of the array in the lower portion of the window and

16

a color bar in the right portion of the window. If the screen remains blank or if the color bar appears to have odd candy-cane-like stripes, it suggests that the color depth of your monitor may need to be changed. Also, the color depth may need to be changed if the Orbit Viewer generates the following error when you launch it: “unsupported X windows visual [StaticGray: Depth 0].” The Orbit Viewer is written in the IDL language, and IDL versions 5.3 and 5.4 do not support 16-bit monitor displays. Unfortunately, the default color depth of many Linux systems is 16-bits. The solution is to change the color depth of your monitor to 8 or 24 bits. This change can be made by editing your X windows configuration file using the root account. If you are not familiar with this file, find someone who is, because if you change the wrong setting, it might damage your monitor. First, locate the XF86Config file which is often located in the /etc/X11, /etc, or /usr/X11 directory. As the root user, make a backup copy of this file by typing “cp XF86Config XF86Config.old”. Then, edit all references to DefaultColorDepth so that they read “DefaultColorDepth 8”. You must shutdown the X windows server and restart it before the change will take affect. [release 1.3]

SGI IRIX: Install libblas.so On IRIX platforms, it is usually necessary to install the libblas.so library before the IDL language will run. Because the Orbit Viewer is written in IDL, the libblas.so library is essential. You will need to install this library if you receive the following error when you try to start the Orbit Viewer: “unable to map libblas.so”. To install the libblas.so system library, ask your system administrator to install the ftn_eoe.sw.libblas base product from the IRIX 6.5 Foundations CD #1. The administrator will then have to add overlays for this library, which can usually be found on the IRIX Overlay CD #2 for each subsequent version of the IRIX operating system. [release 1.3]

17

hersh1.chr When you launch the Orbit Viewer you may receive an error similar to “IDL cannot map /usr/lib/rsi/idl_5.3/hersh1.chr”. This error usually means that the Orbit Viewer setup script setupUNIX.sh has failed to define the IDL_DIR environment variable. When that variable is undefined, IDL looks for the hershy character file in the default location for the IDL language. The solution is to verify that the Orbit Viewer script is correctly defining the location of the IDL source code as the absolute path to the orbit/TSDISorbitViewer/idl directory. [release 1.3]

X emulators and Dotted Lines If the Orbit Viewer is running on a UNIX system, but you are displaying the results on the monitor of a Microsoft Windows system, you may experience difficulties with dotted lines. In some situations, all line styles other than solid will appear as dashed lines. This means that dotted lines and dash-dotted lines will incorrectly be displayed as dashed lines. The cause of the problem is your X window emulator. The emulator is the software that allows your UNIX session to open a display on your Microsoft Windows monitor. If you are using the MI/X X windows emulator, there is no known solution, but if you are using the Exceed X window emulator, try the following steps. With the right mouse button, click on the Exceed bar at the bottom of the screen. In the menu that pops up, select Tools and then Configuration. In the exceed.cfg-Xconfig window that appears, double-click on Performance. In the Performance window, make sure that there is a checkmark in the box next to “Exact Zero-Width Lines.” Click OK in the Performance window to dismiss it. [release 1.3]

2.2. Freeware Installation under Mac OS X

If you are using Mac OS X, you can basically follow the same steps as for installing the Orbit Viewer under Linux as described

18

in the previous section of the tutorial. Alternatively, you can follow the instructions in this section. To obtain the Orbit Viewer from the web, download the zip file appropriate to your operating system from [http://pps.gsfc.nasa.gov]. If your Mac contains the new Intel chip, download the zip file that contains the string "macIntel". Alternatively, if your Mac contains the older PowerPC chip, download the zip file that contains the string "macPowerPC". After downloading the zip file, place it in your home directory or wherever you wish to install it. Double click on the hard drive icon at the upper right corner of the screen and go to the directory that contains the zip file. Double click on the zip file to unzip it using the compression software that comes with Mac OS X (i.e., Stuffit Expander). Double click on the setupMAC.command file. The setupMAC.command file will launch the setupUNIX.sh shell script for you. Once the script finishes running, click on the Desktop (the background of your monitor), so that the new Desktop icon will appear. To run the Orbit Viewer, double click on the Desktop icon or drag and drop a TRMM HDF file onto the Desktop icon. The bottom of the Orbit Viewer window may be cut off by the Dock at the bottom of the screen if the Dock is always visible. The solution to this problem is to make the Dock appear only when you move the mouse to the bottom of the screen. To make this change, select the System Preferences menu item from the apple menu at the upper left corner of the screen. In the System Preferences window that appears, click on Dock. Select "automatically hide and show the Dock." Click the red button at the upper left of the window to apply the change. The rest of this section provides tips on specific issues that may come up when you install the Orbit Viewer on a Mac.

The one-button mouse If you are using a Mac one-button mouse and you want to do a right click, hold down the control (ctrl) key before clicking the mouse. [release 1.3.5]

19

X windows The X windows application must be installed on your Mac before the Orbit Viewer can run. If you try to run the Orbit Viewer from a Terminal's command line without X windows installed and running, you will receive the following error: "DEVICE: unable to Open X." To determine if the X windows application is installed, double click on the hard drive icon on the upper left of your screen. Click on Applications, scroll down to Utilities, click to open Utilities, and scroll down in the alphabetical list until you can see if there is an application called X11.app. If one does not exist, find the X11User.pkg package on your system CD and install it onto your hard drive. To locate the X11 application on your Mac installation disk, insert a Mac installation disk into your CD drive, start a terminal application, and go to the top directory of that CD. Then type the following UNIX command: find . –name "X11User.pkg" –print Once you have found the X11 package, type the following to install it on your Mac: open X11User.pkg If the X11 installation is successful, it will create an X11.app application folder in your /Applications/Utilities folder and a /etc/X11 directory. [release 1.3.5]

Terminal application You may wish to add the Mac terminal application to the Dock along the bottom of the screen. To find the terminal application, double click on the hard drive icon on the upper right of the screen. Select Applications, scroll down to Utilities, click to open Utilities, and scroll down to Terminal. Drag and drop the Terminal onto the Dock. To keep the Terminal in the Dock, hold down the "ctrl" key while clicking on the Terminal where it appears in the Dock. In the menu that pops up, select

20

"Keep in Dock." If you ever want to remove the Terminal from the Dock, click and drag the Terminal off the Dock and it will disappear. After you do that, the Terminal application will not reappear in the Dock when you reboot your Mac. [release 1.3.5]

2.3. Freeware Installation under Microsoft Windows

Currently, the only version of Microsoft Windows that the Orbit Viewer is tested on is Windows XP. An easy way to obtain the Orbit Viewer is by downloading the zip file from the PPS web site [http://pps.gsfc.nasa.gov]. Place the zip file in the top folder of a hard disk of your Microsoft Windows system. Do not place the zip file in the “My Documents” folder of your computer or in any other folder whose name contains a space. If the zip file ends in *.exe, it is a self-extracting Zip file. To unzip it, double-click it. If the zip file ends in *.zip, use a compression program such as WinZip to unzip it. Either way, when the zip file is uncompressed, it will create the orbit folder. Go into the orbit folder and double-click on the setupWIN.exe program to set up the Orbit Viewer. Your virus protection software may warn you about the two Visual Basic Scripts that the setup program runs. These scripts create a shortcut for the Orbit Viewer on your desktop, but even if that fails you can still use the Orbit Viewer. Lacking a shortcut, you can double click on the orbit/TSDISorbitViewer/orbitWIN.exe program when you want to run the Orbit Viewer. You can also drag and drop a TRMM file onto either the shortcut or the orbitWIN.exe program. The rest of this section provides tips on specific issues that may come up when you install the Orbit Viewer on a Microsoft Windows system.

Developer Mode under Windows Use developer mode only if you have purchased a developer license for IDL and you want to modify the Orbit Viewer source code. Contact RSI, the manufacturers of IDL, to purchase a

21

developer license for IDL version 7.0 or later [http://www.rsinc.com]. To run in developer mode, start the IDL Development Environment (IDLDE) by double-clicking on the IDL icon on your desktop or by double-clicking on the idlde.exe program usually located in the C:\RSI\IDL61\bin\bin.x86 folder. Then, type the following commands in the IDLDE’s command line. The commands given below assume that the Orbit Viewer is located in the C:\orbit folder. The "!path" command is needed because, in Windows, IDL separates paths using ";" while the code\setup.pro file uses ":" to separate paths, as is done by IDL on UNIX systems.

source_dir = ‘C:\orbit\TSDISorbitViewer’ setenv, ‘SOURCE_DIR=‘ + source_dir cd, source_dir cd, current=pwd & print, pwd !path=!path+';C:\orbit\TSDISorbitViewer\code' @code\setup.pro

[release 1.3]

Monitors with Low Resolution The Orbit Viewer was designed for monitors with a minimum of 1152 by 864 pixels. If your monitor is old or you have voluntarily set it to a low resolution, such as 800 by 600 pixels, the Orbit Viewer will attempt to adjust to the low resolution of your monitor. If the Orbit Viewer is too big to fit on your screen, it has failed to adjust to your monitor’s resolution, and you must make a one-time modification to the Orbit Viewer’s configuration. In the main window of the Orbit Viewer, select the Option Configuration menu item. At the top of the Configuration window, click the button next to the number 2, to go to the second page. At the bottom of the second page, find the pull-down menu to the right of the Window Size label. Select “small” using the pull-down menu. To save this new configuration, click the Apply button at the bottom of the window. When given a choice, choose to apply the changes to the User Configuration File. Exit the Orbit Viewer and restart it.

22

The main window of the Orbit Viewer should now be approximately half as big as it was previously. [release 1.3]

Manual Setup If you are unable to use the setupWIN.exe program to set up the Orbit Viewer, here are instructions for setting up the Orbit Viewer by hand. Determine the location of the Microsoft Windows “temp” folder. To do this, select Run from the Start menu at the lower left corner of the screen. Type “command.com” in the Run window to start a DOS command prompt. In the DOS command prompt, type “echo %TEMP%”. The output of that command is the temp folder. Using a text editor such as Notepad or Edit create a file called OV_root.txt in your Windows temp folder. To start Notepad, type “notepad” in the window that appears when you select Run from the Start menu. The most important line of the OV_root.txt file is the definition of the OV_root environment variable. The environment variable is set to the name of the folder that contains the TSDISorbitViewer folder. More specifically, if you have installed the Orbit Viewer on your hard disk, then the environment variable should be set something like C:\orbit\. If you are using the Orbit Viewer CD, the environment variable should be set to the drive letter of your CD drive, such as F:\. It is necessary that the last character of environment variable be the “\” backslash character. The contents of a sample OV_root.txt file are show below:

@echo off rem . filename: OV_root.bat set OV_root=C:\orbit\ echo OV_root.bat: OV_root... %OV_root%

Once you have placed the OV_root.txt file in the temp folder, you should be able to run the Orbit Viewer. To run the Orbit Viewer, double-click on the orbitWIN.exe program in the TSDISorbitViewer folder. For your convenience, you may wish to create a shortcut on your desktop for the orbitWIN.exe program. To create a shortcut, follow the suggestions in the paragraph below. [release 1.3]

23

Create a Desktop Shortcut A desktop shortcut is an icon that sits on your desktop that you can double-click with the left mouse button to start a program. Most Windows systems come with VBScript, which allows the Orbit Viewer’s setup program, setupWIN.exe, to automatically create a desktop shortcut for you as part of the fast setup option. If you are unable to use the setupWIN.exe program to automatically create a desktop shortcut for the Orbit Viewer, it is because setupWIN.exe is unable to run VBScript. If you have turned off the Windows Scripting Host (WSH), then VBScript will be de-activated. In these cases, the solution is to create the shortcut manually as described below. To create a desktop shortcut, first open the folder that contains the orbitWIN.exe program. If you want to run the Orbit Viewer from the CD, then open the TSDISorbitViewer folder of the CD. If you have installed the Orbit Viewer on your hard disk, then open the orbit\TSDISorbitViewer folder of your hard disk. Then, right click on the orbitWIN.exe program and select “Create Shortcut” from the menu that pops up. If the shortcut is not created on the desktop, drag it from the folder onto the desktop using the left mouse button. You should now be able to start the Orbit Viewer by double-clicking the shortcut with the left mouse button. You can also drag a TRMM file onto the shortcut with the left mouse button, and the Orbit Viewer will open that file. To make the shortcut look nicer, you can change its name and icon. Change the name of a shortcut the same way that you would change the name of any other file: click once with the left mouse button, wait a few seconds, and then click again with the left mouse button. Now type in the new name of the shortcut, such as “orbit.” When you are done, just click anywhere else on your screen. The steps to change the icon of a shortcut are slightly different on different versions of Windows, but the basic method is as follows. First, right click on the shortcut, and select Properties from the menu that pops up. In the Properties window, click on the Program tab. Click the Change Icon button. In the Change Icon window, click the Browse button,

24

and double-click the following file: TSDISorbitViewer\data\internal\OV_icon.ico. To apply this new icon, click OK in the Change Icon window, and then Apply or OK in the Properties window. [release 1.3]

Minimize the Launch Window The orbitWIN.exe program places diagnostic text in an output window that, by default, is open as the Orbit Viewer launches and lingers after the Orbit Viewer has finished being launched. The contents of the output window are only helpful if you are trying to diagnose a problem with the launch of the Orbit Viewer. Most of the time, you will not want to see the output window. In Windows 98, it is possible to change a setting to minimize the output window and to close it as soon as the Orbit Viewer has finished being launching. In Windows XP, it is not possible to prevent the output window from lingering, but it is still possible to minimize it. Click on the Orbit Viewer’s desktop shortcut with the right button and select the Properties option from the menu that pops up. In the Properties window that appears, select the Shortcut tab in Windows XP or the Program tab in Windows 98. In both Windows XP and Windows 98, change “Normal Window” to “Minimized Window.” In Windows 98, click on the box next to the text “Close on Exit.” [release 1.3]

2.4. Developer Installation The Orbit Viewer was originally created on a UNIX system, and it required that the system have a licensed copy of the IDL language. UNIX users with a licensed copy of IDL can still download the Orbit Viewer for use in this “developer” mode. The developer zip file is much smaller than the usual freeware zip file (~10 megabytes instead of ~200 megabytes) because the developer zip file contains only the Orbit Viewer source code, not the IDL language. The developer Orbit Viewer allows

25

scientists to modify the Orbit Viewer source code and run that modified version. 1. Download the developer Orbit Viewer zip file, orbit_X.X.X_dev.zip, and the installation instructions, installUNIX.txt, from the PPS web site [http://pps.gsfc.nasa .gov]. Go to your home directory and uncompress and unzip file to create the TSDISorbitViewer directory.

cd ~ unzip -qq orbit_X.X.X_dev.zip

2. Define the TSDISorbitViewer_src environment variable in your shell resource file. In these instructions, path represents the absolute path of the TSDISorbitViewer directory. For C shell and T shell users, the command is:

setenv TSDISorbitViewer_src ‘path/TSDISorbitViewer’

For C shell and T shell, place the command in ~/.cshrc for a single-user installation or in /etc/cshrc for a system-wide installation. In contrast, for Bourne shell and Korn shell users, the command is:

export set TSDISorbitViewer_src=‘path/TSDISorbitViewer’

For Bourne shell and Korn shell users, place the command in ~/.profile for a single-user installation or in /etc/profile for a system-wide installation. 3. Add a link in the /usr/local/bin directory to the orbit command:

ln -s path/TSDISorbitViewer/orbitUNIX.sh \ /usr/local/bin/orbit

If you do not have the system privileges to create this link, you can create an alias instead in your .cshrc or .profile file, but this will allow only you, and not others on your system to run the Orbit Viewer. Be sure to define the TSDISorbitViewer_src environment variable before defining this alias:

alias orbit “$TSDISorbitViewer_src/orbitUNIX.sh”

26

To test the installation, type “orbit” on the UNIX command line and the Orbit Viewer should launch. One advantage of the developer Orbit Viewer is that you can use the interactive mode by typing “orbit –interact”. Interactive mode is described in section 3.8.

27

3 Data Display

The Orbit Viewer provides many ways to display TRMM data, but first-time users can get started by reading just the first section of this chapter. Most of the rest of the chapter describes alternative ways to display arrays. Arrays are emphasized because most TRMM data is stored in arrays rather than tables or text fields. Near the end of the chapter is a description of the various ways to alter images, which may be of interest to experienced users of the Orbit Viewer.

3.1. Basic Display Array The most frequently made images in the Orbit Viewer are high-resolution horizontal images of data arrays. The following steps

28

will lead you through the process of opening a file, choosing a data array, and choosing a zoom region. Start the Orbit Viewer and open a TRMM data file. If you are using UNIX, type “orbit f i l ename” or “~/orbit.sh f i l ename” at the UNIX prompt, where f i l ename is the name of the file that you want to open. If you are using Microsoft Windows, double-click the Orbit Viewer icon or the TSDISorbitViewer\orbitWIN.exe program and then use the File Open menu item to open a data file. The main window of the Orbit Viewer will exist throughout your Orbit Viewer session (figure 3.1). For this example, we open a TRMM 2A25 file, which contains the three-dimensional rainfall rate estimated from observations of the TRMM Precipitation Radar (PR). Now that you have opened a file in the Orbit Viewer, select an array from the list on the left side of the main window. In figure 3.1, we have chosen the “rain” array. From here on, this array will be referred to as “2A25.rain” because the 3D rainfall rate estimate is named “rain” in TRMM 2A25 files. If the array has more than two dimensions, use the slider on the left side of the window to choose one element of the additional dimension. In this example, the rain array has 80 vertical levels going from the highest sampling level (height 1) down to the earth’s ellipsoid (height 80). Here we select height 70, which corresponds to a height of 2.5 km. For more information about the vertical structure of PR data, see section 1.2 of ICS volume 4 and section 6.1 of ICS volume 3. Both volumes can be downloaded from the PPS web site [http://pps.gsfc.nasa.gov]. In the interest of consistency, the Orbit Viewer’s slider always goes from 1 to the number of elements in the dimension. With arrays such as the VIRS 1B01.channels array, the one-based numbering system matches the numbers that scientists use when they talk about the data. However, scientists often talk about the PR’s range bins going from 0 to 79, i.e., they use a zero-based numbering system. When looking at PR data with the Orbit Viewer, it is important to remember that the Orbit Viewer uses a one-based number system for all arrays.

29

Now that you have chosen a variable and a vertical height, select a zoom region by clicking somewhere on the global image at the bottom of the Orbit Viewer’s main window. Using the Option Zoom_Resolution menu item, increase the magnification by switching from the default zoom image size of 20 degrees to 5 degrees. To improve the image quality, select Option Interpolate_Data. If you click on a data point in the zoom image, detailed information about that observation will be printed in the lower-left corner of the window. Once you create a zoom image in the main window of the Orbit Viewer, it becomes possible to open several additional windows to examine the array in different ways. Select the View Array menu item to see what windows are available for the currently displayed array. For example, choose View Array Histogram to open a histogram window. A few of the View Array menu items become active even before you select a zoom region. For example, you can create a statistical summary of all the arrays in the file by selecting View Array Quick_File_Summary.

30

Figure 3.1. The Main Window

Table A table is a data structure with rows and columns, and each column can have a different data type, such as integer, float, or string. In TRMM HDF files, tables are stored as Vertex Data (Vdata). Most TRMM files contain two to five tables. Most tables in swath files (level 1 or 2 files) have 10 to 20 columns and one row for each scan in the swath. To get a list of the tables in a particular file, select the View Table menu item. When you select a table, the Table Viewer window will appear (figure 3.2). Select the name of a column from the list on the left side of the Table Viewer window. A plot of that whole column will appear, along with a detail plot of a portion of it. To change the resolution of the detail plot, use the pull-down menu at the

31

bottom of the window. To change which portion of the column appears in the detail plot, use the slider at the bottom of the window. To save the plot to an image file, click the Save button.

Figure 3.2. The Table Viewer

Text Field Metadata and occasionally others sorts of information are stored as text fields in TRMM HDF files. To view the metadata of a file, select the View Metadata menu item, and the Metadata window will appear (figure 3.3). Due to a peculiarity in the way TRMM HDF files are structured, other text fields, such as the GridStructure field, are stored as Vdata Tables and can therefore be accessed by selecting the View Table menu item.

32

Figure 3.3. Metadata

3.2. Vertical View Swath arrays have two horizontal dimensions: scan number and field-of-view (fov). Some swath arrays have a third dimension that can represent height above the earth’s surface, the method of calculation, or some other dimension. One of the strengths of the TRMM dataset is the ability to resolve the three-dimensional structure of rainfall rate, so the Orbit Viewer provides two ways to make vertical cross sections of swath arrays: a fixed cross section and a variable cross section. The first method holds one dimension of the swath fixed and makes an image along the other two dimensions. In contrast, the second method cuts the swath at any azimuth angle. A more general way to make vertical cross sections of an array is to use the View Array Generic_View menu option. The Generic View menu option has the advantage that it works on both grid arrays and swath arrays, whereas the fixed cross section and variable cross section windows work only on swath arrays.

33

Fixed Cross Section Select a three-dimensional swath array, such as the 2A25.rain array, in the main window of the Orbit Viewer and choose a zoom region by clicking on the global image at the bottom of the main window. Select the View Array Fixed_Cross_Section menu item, and a new window will appear (figure 3.4). In the Fixed Cross Section window, click on the left-hand column to choose which type of cross section to make: horizontal, along track, or across track. Whichever cross section you choose, one dimension of the swath array will be fixed. To change the displayed element of the fixed dimension, move the slider at the bottom of the Fixed Cross Section window. Click on the image to open a detail window.

Figure 3.4. Fixed Cross Section

Variable Cross Section Select a three-dimensional array in the main window of the Orbit Viewer and choose a zoom region by clicking in the global image at the bottom of the Orbit Viewer’s main window. Select the View Array Variable_Cross_Section menu item in the main

34

window, and a new window will appear (figure 3.5). To choose the geographic endpoints of the cross section, either type them into the text fields or click the button labeled “select endpoints with the cursor.” If you chose to select the endpoints with the cursor, click on the zoom image where the cross section should begin, hold down the mouse button, and drag the mouse to where you would like the cross section to end. Then, let go of the mouse button. The Orbit Viewer will draw a white line where the cross section would lie. Click the button labeled “display the cross section.”

Figure 3.5. Variable Cross Section

3.3. 3D View The vertical cross sections described in the previous section are easy to interpret. However, they only show one slice of the

35

three-dimensional rain structure at a time. To visualize the full 3D structure of an array, it can be helpful to examine a 3D surface. The Orbit Viewer can construct a 3D surface that contains all data above a user-supplied threshold. By varying the threshold, the researcher can get a sense of the data’s structure. The following steps describe how to generate a 3D surface from a swath array using the Orbit Viewer. Open a 2A25 file and select the Precipitation Radar’s “rain” array (in mm/h) from the left-hand column of the Orbit Viewer’s main window. Alternatively, you could open a 2A12 file and select “precipitable water,” (in g/m3) which is estimated from TMI observations. Whatever array you have chosen, click on the global image at the bottom of the Orbit Viewer’s main window to select a zoom region. Select the View Array 3D_Viewer menu item from the main window. A small window titled “Select Volume” will appear to allow you to select the volume to be displayed three-dimensionally (figure 3.6). Also, a white box will appear on the zoom image. Move the box to so that it covers the data that you would like to visualize. To do this, click on the “+” symbol in the middle of the box, hold down the mouse button, drag the mouse to the center of the region of interest, and then let go of the mouse button. Alternatively, the center of the 3D region can be fixed by typing its latitude and longitude values into the Select Volume window. To select the size of the region in degrees of latitude, use the pull-down menu.

Figure 3.6. Select 3D Location

36

Once you have chosen the region of interest, click the Select Data button. After a brief delay, a 3D Control window and a 3D Image window will appear (figure 3.7). The sliders in the 3D Control window allow you to change the observation angle (1) and the angle of the light source (2). Figure 3.8 shows the definition of these angles. Another slider allows the threshold to be changed that defines what data are included inside the 3D surface (3). All data values greater than that threshold are inside the 3D surface. This slider is label in the units of the data being displayed. In figure 3.7, the threshold is 1.5 mm/h (15 * 0.1 mm/h). To zoom in, use the “Zoom” slider (4). Once you have zoomed in, you may find that the portion of the data that interests you has fallen outside the image. To solve this problem, move the image using the horizontal or vertical shift sliders (5).

37

Figure 3.7. The 3D Control Window (top)

and 3D Image Window (bottom).

38

Tropical Cyclone

Observer

South

Observation Azimuth

Observation Elevation

Light Azimuth

Light Elevation

Light Source

Tropical Cyclone

Zoom Vertical

Shift

Horizontal Shift

Figure 3.8. Definition of the sliders in the

3D Control window

3.4. Generic View Most of the Orbit Viewer’s windows are used to display swath or grid arrays on a map of the Earth. There may be times, however, when a researcher wishes to examine an array in a more generic way. By selecting the View Array Generic_View menu item, a researcher can do just that. Three windows will appear: a Control window that determines what portion of the array is

39

displayed and the Image and Text windows where the array is displayed (figures 3.9, 3.10, and 3.11).

Figure 3.9. The GenericView Control Window

In this example, we examine the 2A25.rain array. The HDF file contains names for the dimensions of this array, namely height, ray, and scan. The height is the vertical dimension, the ray is the field-of-view, and the scan is the number of the scan along the satellite track. The check boxes next to each dimension determines which dimensions are currently being displayed. In this case, field-of-view and scan number are being displayed, i.e., this is a horizontal slice at height bin 70. This corresponds to a height of 2.5 km above the earth’s ellipsoid (80 - 70 = 10 cells from the ellipsoid; 1 cell is 0.25 km of altitude).

40

Figure 3.10. The GenericView Image Window

By default, the text values are displayed with the full precision of a four-byte floating-point number, i.e., an IDL character format of “g13.6”. In order to see a larger portion of the array as text, you may wish to reduce the precision of the displayed value. To do this, select the File Change_Format menu item from the GenericView Text window. If you choose the three-digit integer format (“i3”) and expand the window by stretching its lower-right corner, you will get the text shown below in figure 3.11.

41

Figure 3.11. The GenericView Text Window

Showing a Hurricane’s Eye Wall. Both the Generic View Text and Image windows can be saved. Use the File Save_Image menu item in the GenericView Control window to save the image to an image file. Use the File Save menu item in the GenericView Text window to save the text to a text file.

3.5. Array Summaries There are two ways to summarize an array in the Orbit Viewer. You can create a histogram of an individual array or a summary of all the arrays in a file. To create a histogram, select the View Array Histogram menu item (figure 3.12).

42

Figure 3.12. Histogram Window

To create a file summary, select the View Array File_Summary menu item. Wait while the Orbit Viewer reads all the arrays in the file and calculates statistics. The result will be a new window that contains a list of all the arrays and their statistics. Below is shown the statistics for the Rain variable in a 2A25 subset file (figure 3.13).

Figure 3.13. A Portion of a File Summary

------------------------------------------------------- ** rain ** DFNT_INT16 ( 80 49 359 ) ------------------------------------------------------- data scalars in the HDF file: 1.e-02 at least 5% of the elements were one of these values data value 0 % frequency 81.000 % the distribution of the rest of the data is -9999 -9999 -8888 211 936 30000 min 5 % 25 % 75 % 95 % max

43

3.6. Colors One of the strengths of the Orbit Viewer is its ability to map the data in a TRMM file to a color table. This section describes how the Orbit Viewer’s color table is displayed in the color bar on the right side of the main window. This section also describes how to modify the colors and the mapping of data to colors.

Color Bar Figure 3.14 shows the color bar, which is an image on the right side of the Orbit Viewer’s main window that summarizes the colors in the color table and how the data is mapped to the colors, i.e., the color map. Generally, the same color table is used for all arrays but the color map is specific to each array. To make it easier to compare the same array in two different files, the same color map is used for a given array, regardless of what file it appears in. In other words, when you are looking at the rain array in a 2A25 file, the color blue corresponds to the same rainfall rate, independent of what 2A25 file you happen to have opened. The information necessary to define a “static” color map for most arrays in a TRMM standard product is found in a parameter file of the Orbit Viewer. The parameter file is required because the color map information is not stored in the standard products themselves. The Orbit Viewer’s color maps were created by examining the typical range of each array and the important features that scientists might be interested in. The following information is shown in the upper half of the color bar. This information comes from the Orbit Viewer’s parameter file: the upper and lower limits of

(1)

(2)

(3)

(4) (5)

(6)

(7)

Figure 3.14. Color Bar

44

the data mapped to the color table (2), whether the data is mapped linearly or logarithmically to the colors, and the units of the array (1). The middle of the color bar lists the data flags (4). Discrete flags are often mixed in with continuous data to indicate array elements for which the algorithm was not able to function optimally. For example, many arrays contain elements with a value of –9999 to indicate “missing data.” Other flag values are also negative values that usually fall outside the range of the physically meaningful data, but the meaning of these additional flags vary. The Orbit Viewer’s color bar displays the data flags that it detects in the currently displayed array. No list of flags is stored in the data file’s metadata or in any Orbit Viewer parameter file. An advantage of having the Orbit Viewer search through the array to compile a list of data flags is that it makes the Orbit Viewer an independent check on the software that generates PPS products: if an unexpected or unintended flag exists in an array, the Orbit Viewer is likely to discover it. A disadvantage of this method is that TRMM arrays are too big for the Orbit Viewer to be able to check every array element. Instead, the Orbit Viewer searches through just a random sample of the elements. In addition, the Orbit Viewer estimates the percentage of data that equals each data flag (5). Near the bottom of the color bar is found the data scalar (6). TRMM arrays are often scaled immediately before they are written to the HDF file. The Orbit Viewer reads these scalars and uses them to unscale the data. Near the bottom of the color bar is also displayed an approximate distance scale for the zoom image of the main window (7). The distance scale changes when you change the resolution of the zoom window. The scale is only approximate because the geographic map projection used by the Orbit Viewer is equally spaced in latitude and longitude. As you move away from the equator, the kilometers per degree of longitude decreases, while the kilometers per degree of latitude stays constant. This means that the color bar’s distance scale (in kilometers) is only accurate in the north-south direction. To

45

estimate east-west distance, multiple the distance scale by the cosine of the latitude. For example, east-west distances are shrunk by a factor of 0.77 at 40 degrees latitude (the limit of most TRMM grids) and by 0.50 at 60 degrees latitude. At the very bottom of the color bar is the phrase “static map” (3). This phrase indicates that one of the Orbit Viewer’s static color maps is being used. Occasionally, you may wish to allow the color map to dynamically adjust to the full range of the data in one file. In that situation, click the label “static map” to switch to a dynamic color map. Click again and the Orbit Viewer will return to the static color map.

Change the Color Table The casual user will probably be satisfied with the color table and color mapping that is automatically chosen by the Orbit Viewer. An experienced user, however, may want to change either the colors in the color table or the way that the data are mapped to the color table. These two actions are discussed below. There are several ways for the user to change the color table. To change the colors for continuous data, select the Option Color_Table Continuous_Color menu item. To change the colors for discrete data, including data flags, select the Option Color_Table Discrete_Color menu item. If you are planning to save images created by the Orbit Viewer and print them on a black and white printer, then you may wish to use the gray scale color table. To use the gray scale color table, select Option Color_Table Gray_Scale (figure 3.15). After making any change to the color table, you can

Figure 3.15. Gray Scale Color Bar

46

return to the default color table by selecting Option Colors_Table Use_Default_Colors.

Figure 3.16. Change Continuous Colors (left) and

Change Discrete Colors (right).

Change the Color Map The color map for an array can be changed permanently by editing a parameter file or temporarily by using a menu item of the Orbit Viewer’s main window. To make a permanent change or to create a static color map for an array that does not have one, edit the static_color.txt file in the TSDISorbitViewer/data/install directory. To make a temporary change to a color map, select the Option Color_Table Change_Color_Map menu item. The temporary change will last only until you open another array in the Orbit Viewer. Figure 3.17 shows the Color Map window as it would appear if the currently displayed array contained continuous data. The window would be slightly different for discrete data. At the top of the window is the definition of the lower and upper limits of the data mapped to the color bar (1). Below that are the values treated as data flags, which are assigned

47

their own colors (2). The user can also choose whether the color mapping is linear or logarithmic (3). At the bottom of the window, the user can change the data scalar (4). Also, the user can change the text string that names the units of the array (5). When you are ready to load the new color mapping, click the Load New Settings button (6). If you wish to return to the original color mapping, click the Reload Original Settings button (7).

(1)

(2)

(3)

(4)

(5)

(6) (7)

(1)

(2)

(4)

(5)

Figure 3.17. Change the Color Map

48

3.7. Image Options There are a number of way to adjust images, and many of them are located in the Option menu of the Orbit Viewer’s main window. The Option Color_Table menu item has been discussed in the previous section. The other items in the Option menu are discussed here, including the two most commonly used options: Zoom_Resolution and Interpolate_Data. The Option Zoom_Resolution menu item allows you to choose how big a portion of the Earth to include in the zoom image of the main window. The choices range from a 40 degree box to a 1 degree box. A 1 degree box is so small that it becomes difficult to adjust its location by the usual method of clicking on the global image at the bottom of the Orbit Viewer’s main window. In this situation, adjust the zoom image’s location by clicking on the zoom image and dragging the mouse a few inches in the direction that you want the zoom image to move. Alternatively, use the View Goto_Location menu item. When you choose this menu item, a small window opens that allows you to type in a latitude/longitude pair and to have that location become the center of the zoom image. The Option Interpolate_Data menu item allows you to interpolate the observations in a swath array to make a continuous image rather than display the observations individually with discrete dots. A less commonly used option, Option Array_Scalar, allows you to override the data scalar for the currently displayed array. By default, the Orbit Viewer uses the scalar stored in the TRMM data file. Experienced users of the Orbit Viewer may wish to control what kinds of geographic information are displayed in the zoom image of the Orbit Viewer’s main window. To do so, select the Option Map menu item. In the Map window, click “Turn Features On/Off” to choose which geographic information to display in the zoom image. A Map Feature window will appear. Available features include capital cities, major cities, small islands, rivers, and country boundaries. All of these optional features are turned off by default. After you turn on a feature, you must click Apply before the change will registered.

49

It is even possible to edit details of certain kinds of geographic information. The city locations and names that appear in the Orbit Viewer are derived from a United Nations’ dataset. The user can add a city or alter an existing city’s entry by editing the city_list.txt file in the TSDISorbitViewer/data/internal directory of the Orbit Viewer installation. The rivers, coastlines, and political boundaries are part of the standard IDL distribution and cannot be altered by the user. Once you have turned on some of the optional geographic features, you can adjust their appearance. To adjust the text of geographic features, select the Option Map Text_Style menu item. To adjust the lines that define geographic features, select the Option Map Line_Style menu item. To adjust the latitude and longitude grid lines, select the Option Map Grid_Style menu item. After making a change to a value in one of these pop-up windows, you must click the Apply button for the change to take affect. Additional options can be found by selecting the Option More_Options and the Option Configuration menu items. Those options, however, are rarely used unless your computer differs in some significant way from the computers on which the Orbit Viewer was developed and tested.

3.8. TRMM Mission Index The TRMM Mission Index can help you find unusually intense storms in regions with frequent rainfall where it is difficult to decide which storm is stronger. The Mission Index can also help you find storms in semi-arid regions even though rainfall is rare there. Once you determine a TRMM orbit of interest using the Mission Index, you will have enough information to order that orbit’s full-resolution file from the TRMM archive. Full-resolution files can be obtained from the Goddard DAAC at [http://daac.gsfc.nasa.gov]. The TRMM Mission Index summarizes the more than 10 terabytes of TRMM Microwave Imager (TMI) and Precipitation

50

Radar (PR) single-orbit rainfall products produced since January, 1998. Based on the 3G68 algorithm, the Mission Index consists of daily-average rainfall rate on a 1 degree grid with an overlay of the satellite track and orbit numbers. Each Mission Index file summarizes the single-orbit files for one year for one of the following two surface rainfall algorithms: the TMI 2A12 algorithm and the Precipitation Radar 2A25 algorithm. Each file is small, only 11 megabytes, for easy downloading. The first step is to download a Mission Index file from the PPS web site [http://pps.gsfc.nasa.gov]. Open the file in the Orbit Viewer and select the avg_rain_rate array. Next, click on the global image to select a zoom region. At this point, the Orbit Viewer will calculate a time series of rainfall rate for that year in that zoom region. The time series will appear in a new Time Series window (figure 3.18). By clicking on a peak in the time series, the scientist can create a low-resolution image of heavy rainfall on a particular day (the top of figure 3.19). If you wish to refine the region in the time series, use the File Select_Region menu item in the Time Series window. In the Select Region window that appears, type in the latitude and longitude boundaries of the region of interest and click the Apply button. Alternatively, click on the box to the left of the words “Select region with cursor.” Then, rubber band a region in the zoom image of the Orbit Viewer’s main window. Once you chose a region, the time series is recalculated automatically. The example shown below examines New Mexico using the 2A25.1999.day.HDF which contains PR-estimated rainfall rate from 1999. The zoom region is around 28 north latitude and 111 west longitude. The chosen day is April 30, which shows up as a blue bar in figure 5.1.

51

Figure 3.18. Time Series of TRMM Observations

Over New Mexico in 1999 In the low-resolution image in figure 3.19a, you can read the orbit number of the orbits that contain rain. In this case, the heaviest rainfall is in orbit 8175, so it would make sense to order the full-resolution data for that orbit. The full-resolution image for that file, 2A25.990430.8175.5.HDF, is shown in figure 3.19b. Another useful tool is the TRMM Overflight Finder, which can be found on the PPS homepage: [http://pps.gsfc.nasa.gov].

Figure 3.19a. A low-resolution Mission Index image that shows

several orbits from 1999/04/30.

52

Figure 3.19b. A high-resolution Mission Index image that shows several orbits from 1999/04/30.

3.9. Miscellaneous Topics Interactive Commands The only way to start an IDL interactive session is to purchase an IDL development license from RSI. If you have such a license on a UNIX system, type “orbit –interact” to start an interactive IDL session with Orbit Viewer procedures compiled to make it easier to read TRMM HDF data. These procedures include one to read an HDF SDS array, HDF Vdata table, or HDF metadata text. These procedures are called read_sds, read_vdata, and read_meta. To get the usage syntax for any of these procedures, type just their name at the command line. Alternatively, read the interact_info.txt file in the TSDISorbitViewer/doc/help_page directory.

53

Right-Side Up When some swath arrays are displayed in the zoom image of the Orbit Viewer’s main window, they have a different orientation than in other Orbit Viewer windows, such as the Fixed Cross Section window or Generic View window. In other words, they look as if they are upside down. The orientation difference is related to how the TRMM instruments collects data and how the Orbit Viewer displays it. Regardless of the orientation of satellite, the Fix Cross Section and Generic View windows generally put the origin of an array at the lower-left corner of an image. In contrast, the zoom image of the Orbit Viewer’s main window places the data where they belong on the map of the Earth. Determining what is “right-side up” can be confusing for two reasons. First, the TRMM satellite reverses direction every few weeks. Sometimes the satellite is pointing forward, i.e., in the plus X direction (+X). At other times, the satellite is pointing backward, i.e., in the minus X direction (-X). Second, the various TRMM instruments—the Precipitation Radar (PR), TRMM Microwave Imager (TMI), and the Visible and Infrared Scanner (VIRS)—scan in different directions. When the TRMM satellite is moving in the +X direction, the TMI instrument is scanning ahead of the satellite and the first field-of-view in the TMI swath is at the swath’s northern edge. Meanwhile the Precipitation Radar and VIRS instruments are scanning below the satellite and the first field-of-views in their swaths are at the swaths’ southern edge. Conversely, when the TRMM satellite is moving in the –X direction, then first TMI field-of-view is at the southern edge and the first PR and VIRS field-of-views are at the northern edge.

54

4 Data Subsets

This chapter describes how the Orbit Viewer can be used to save images and data subsets. First, how to save an image is described. Next is a description of how to create a data subset containing the grid array or swath array that you are currently displaying in the Orbit Viewer.

4.1. Create an Image The previous chapter describes how to display data in the zoom image of the Orbit Viewer’s main window. To save that zoom image, select the File Save_Image menu item in the Orbit Viewer's main window. Most of the other windows of the Orbit Viewer either have a Save Image item in their own File menu or they have a Save Image button. You can save images in the following formats: PNG, GIF, JPEG, and TIFF. Alternatively, you can copy the image to an Image window (figure 4.1).

55

Figure 4.1. The Image Window

The PNG and GIF formats are loss-less: all the pixels are preserved as they appear on the screen. The JPEG and TIFF formats use lossy compression, which means that image quality is degraded. Adobe Photoshop, Microsoft Office, IDL, and Matlab can import all these formats. After you have saved an image to your hard disk, it takes only a few commands to import and display the image using the Matlab or IDL languages. If you have an IDL license, put the following text into source file called “plot_image.pro”. Type “idl” at the UNIX command line to start an IDL session or double-click the IDL icon on your Windows computer. In the IDL session, type “.run plot_image.pro” to compile the procedure, and then type “plot_image, f i l ename”, where f i l ename is the name of the file that you wish to display. The plot_image procedure will read the file and display the image with its color table.

56

Figure 4.2. The plot_image.pro IDL Source File pro plot_image, filename, image, r, g, b ;-------------------------------- device, decompose=0 data = read_image( filename, r,g,b ) window, xsize=n_elements(data(*,0)), $ ysize=n_elements(data(0,*)) tvlct,r,g,b tv, data end

If you are using Matlab, put the following code into a source file called “plot_image.m”. start a Matlab session by typing “matlab –nodesktop –nosplash”. Then type “plot_image( f i l ename )”.

Figure 4.3. The plot_image.m Matlab Source File function [data,color_table] = plot_image( filename ) %---------------------------------------- [ data, color_table ] = imread( filename ) ; axes( 'Position' ,[0,0,1,1] ) ; colormap( color_table ) ; image( data ) ; % -- end of function --

4.2. Create a Data Subset Once you have displayed an array in the zoom image of the Orbit Viewer’s main window, you can save the data to a data subset. To create a data subset, select the File Save_Data menu item. In response, a Save Data window will appear (figure 4.4).

57

Figure 4.4. The Save Data Window

The suggested output file name is the name of the TRMM input file plus the name of the array currently being displayed in the Orbit Viewer. Edit the output file name as necessary. If the data array being display is a swath rather than a grid, then you can alter the latitude and longitude range of the data to be written to the data subset. Click the "Create File" button to create the data subset. When a data subset is written for a swath array, the following files are written: an ESRI ShapeFile, an 8-bit color-coded TIFF image, and a set of ASCII files. The ShapeFile is actually composed of three files ending in *.dbf, *.shp, and *.shx. A ShapeFile contains a vector boundary for each pixel in the array that contains non-zero observations. The floating point observation at those values are also stored in the ShapeFile. A 8-bit color-coded TIFF image is written along with a companion ESRI text WorldFile ending in *.tfw. The worldFile contains the geographic metadata necessary for a Geographic Information System (GIS) to display the TIFF image. In addition to the TIFF imaging containing the data array, another TIFF image is written containing the color table. The ASCII data file is written in a format specific to the Orbit Viewer. A simple example of the Orbit Viewer's ASCII format is shown in Figure 4.5. The first line of the file states the name of

58

the format. The second line is number of dimensions in the array. The third line contains the number of elements in each dimension, and the rest of the file is the array itself.

Figure 4.5. ASCII Text Subset orbit_ascii ; format name 2 ; number of dimensions 3 4 ; size of each dimension 0 0 4 ; d(1,1) d(1,2) d(1,3) 1 2 0 ; ... ... ... 9 8 2 ; ... ... ... 1 2 3 ; d(4,1) d(4,2) d(4,3)

When a data subset is written for a grid array, a different set of files is created by the Orbit Viewer. The files are a 16-bit integer TIFF image, an 8-bit color-coded TIFF image, and an ASCII text file. The 16-bit TIFF image contains the floating point estimate of the grid array multipled by ten and converted into an integer. For example if the grid array contained rain rates from 0.0 to 46.5 mm/h, then the data subset would contain integer values from 0 to 465. World Files are provided for these TIFF images so that they can be displayed by GIS applications.

4.3. Read a Subset with IDL This section describes how to read arrays into IDL. To keep the description concise, it does not describe how to read tables, metadata, and data array scalars into IDL. The information necessary to read those kinds of data objects can be found in the IDL documentation, HDF documentation, and the TRMM file specification. One way to obtain IDL documentation is by typing a “?” question mark at the interactive prompt of a licensed copy of IDL.

IDL Basics IDL is an abbreviation of "Interactive Data Language". IDL is a data analysis and visualization language created by ITTvis

59

[http://www.ittvis.com]. Instead of being on-line, the complete set of IDL documentation is available from ITT. If you wish to start a IDL command line on a UNIX computer, you type "idl" at the UNIX command prompt. By default on most systems, IDL will start up in a 24-bit color mode. 24-bit colors are helpful for advanced users, but for beginning users and for quick plots, it is often more convenient to use 8-bit color. If you wish to switch to 8-bit color, you must do so at the beginning of the IDL session, before you make any plots. If you are using a UNIX or Linux system, use this command to choose 8-bit color: IDL> device, pseudo_color=8 IF you are using a Windows or Mac system, use instead the following commands to choose 8-bit color: IDL> device, true_color=24 IDL> device, decompose=0 The following command show one way to create a two dimensional variable, and how to obtain information about it. IDL> ? IDL> exit IDL> data = [ [1,2,3] , [4,5,6] ] IDL> help IDL> help, data IDL> print, data IDL> print, size(data), n_elements(data) IDL> print, min(data) IDL> index = where( data le 2 ) IDL> print, data(index) To get a help on individual IDL commands type the a question mark at the IDL command line. The "help" command will give a list of all the variables defined in this IDL session. Type "help, variable" to get information about a particular variable. To obtain

60

the number of elements in each dimension of the array, use the size( ) function, as shown above. To obtain the total number of elements in the array use the n_elements( ) function. The min() function returns the minimum of an array. The max( ), mean( ), and median( ) functions work the same way. To get the total of all elements in an array, use the total( ) function. If you to put multiple commands on the same line, separate them with the ampersand character (&). The where command returns the index of all of the elements of the array that satisfy the given relational expression. When working in IDL, there are several commands that can help you keep your work organized: IDL> journal, filename=filename IDL> ; this is a comment IDL> help, /structure, !version The "journal, filename=filename" stores a copy of all the commands you type in the filename journal file, for future reference. When you are finished with a journal file type "journal" again. The ";" character is encountered, the rest of the line is treated as a comment. This is true regardless of whether the ";" character appears at the beginning or the middle of the line. The up arrow key will allow you to edit previous commands that you've issued and then reissue them. If someone asks what version of IDL you are using and what kind of platform you are running it on, you can obtain this information by printing the !version structure. This information is also printed out on the screen when you first start the matlab session. Below is a list of some of the operators in the IDL language. Mathematical Operators in IDL +, -, *, / addition, subtraction, multiplication, division a mod b modulus, i.e., signed remainder after division a^b raise a to the b power exp(b) raise e≈2.71828 to the b power log(b) take natural log of b log10(b) take the log base 10 of b

61

sqrt(b) take the square root of b abs(b) absolute value of b fix(b) truncate b to obtain an integer round(b) the closest integer to b ceil(b) the smallest integer greater than or equal to b floor(b)the largest integer less than or equal to b Relational Operators in IDL a lt b a less than b a gt b a greater than b a le b a less than or equal to b a ge b a greater than or equal to b a eq b a equal b a ne b a not equal b Logical Operators in IDL a and b a and b a or b a or b not b not b Miscellaneous Characters in Matlab ; starts a comment

$ if the line ends with this sequence of characters, the command continues onto the next line

a & b to execute two commands on the same line There are many ways in IDL to display a two dimensional array. One of those ways is using a contour plot, as shown below. Display Data in IDL IDL> ; ---- plain contour plot IDL> contour, data IDL> ; ---- filled contour plot with shade of blue IDL> loadct, 1

62

IDL> contour, data, /fill IDL> ; ---- contour plot with lines labeled IDL> contour, data, nlevels=10, c_labels=intarr(10)+1, \ c_charsize=2, c_charthick=2 IDL> ; ---- contour with axis labels IDL> contour, data, title='main title' , xtitle='x title', \ ytitle='y title' IDL> ; ----contour with axis range limits IDL> contour, data, xrange=[ min_x, max_x ], \ yrange=[ min_y, max_y ], xstyle=1, ystyle=1 When calling an IDL procedure, such as the contour procedure, arguments are separated by commas. The first argument is the array to be displayed. There are many optional arguments to the contour procedure which alter the graphic is produces. These options are described in the documentation, which can be accessed by typing "?" at the IDL command line. Some options are on/off switches. To turn one of these switches, such as the "filled contour" switch, add a slash followed by the name of the switch, such as "/fill." Other options take scalar or array arguments, such as nlevels=10. The "loadct, table_number" command loads one of IDL's predefined color tables. By default, color table zero, which is gray scales is loaded in a new IDL session. Once you have displayed your data, you may want to save a copy of the image to a file. Here is how you do so in IDL. Save an Image to a File IDL> tvlct, red, green, blue, /get IDL> image = tvrd( ) IDL> write_gif, 'image.gif', image, red, green, blue IDL> write_png, 'image.png', image, red, green, blue The tvlct procedure reads the current color table into arrays. The tvrd( ) function reads the image from the current graphics display. The write_gif function creates the specified output GIF file containing the given image array and color table. IDL can save in

63

many other image formats in addition to GIF, such as the PNG format.

Reading HDF 4 in IDL Regardless of what programming language you are using, the general method of extracting an array from an HDF file has two steps: first get a list of the names of all the arrays in the HDF file, and second, read one of those arrays. If you want to read the first array in a file called f i l ename , use the following IDL commands.

IDL> .run read_sds_name.pro IDL> .run read_sds.pro IDL> filename=’filename’ IDL> read_sds_name, filename, sds_list IDL> read_sds, filename, sds_list(0), data

The commands given above use two IDL sources files that you must create: read_sds_name.pro and read_sds.pro. The source code for the read_sds_name.pro IDL procedure is the following:

pro read_sds_name, filename, sds_list ;------------------------------- file_id = hdf_sd_start( filename, /read ) hdf_sd_fileinfo, file_id, num_sds, natt sds_list = strarr( num_sds ) for which_sds = 0, num_sds - 1 do begin sds_id = hdf_sd_select( file_id, which_sds ) hdf_sd_getinfo, sds_id, name=name, ndim = nd,type= typ sds_list(which_sds) = name hdf_sd_endaccess, sds_id endfor hdf_sd_end, file_id end

The source code for the read_sds.pro IDL procedure is the following:

pro read_sds, filename, sds_name, data ;------------------------------

64

file_id = hdf_sd_start( filename, /read ) which_sds = hdf_sd_nametoindex( file_id, name ) sds_id = hdf_sd_select( file_id, which_sds ) hdf_sd_getdata, sds_id, data hdf_sd_endaccess, sds_id hdf_sd_end, file_id end

The read_sds procedure presented here is not the same as the read_sds procedure mentioned in section 3.8.

Reading ASCII in IDL There are two steps to reading an ASCII file created by the Orbit Viewer: first read the header and then read the data. Both steps are carried out in the following IDL procedure:

pro read_ascii, filename, data, num_dim, dim_size ;-------------------------------- num_dim = 0 file_type = ' ' ; -- read the header openr,1, file readf,1, file_type readf,1, num_dim dim_size = intarr( num_dim ) readf,1, dim_size data = make_array( dimension=dim_size ) ; -- read the data readf,1, data close,1 end

4.4. Read a Subset with Matlab

Matlab Basics Matlab is a data analysis and visualization language created by Mathworks. A complete reference to matlab commands is available on the Mathworks website:

65

[http://www.mathworks.com]. These instructions are based on Matlab version 6.1 on a Linux system. The commands may be different on other version of Matlab or on Matlab running on other systems. If you wish to start a Matlab command line on a UNIX computer, you can type "matlab –nodesktop –nosplash" at the UNIX command prompt. Before using the commands listed in this section, you may wish to type the following commands to make the environment more friendly. matlab> format long matlab> more on matlab> help matlab> help command matlab> ver matlab> exit The "format long" command (vs. "format short") shows you all the decimal places of a floating point variable when you print it to the screen. The "more on" command (vs. "more off") allows you to see the help pages for a matlab command, one page at a time. To obtain a list of help topics, type "help" on the matlab command line. To obtain help on an individual matlab command, type "help command". If someone asks what version of IDL you are using and what kind of platform you are running it on, you can obtain this information by printing the !version structure. This information is also printed out on the screen when you first start the matlab session. The following command show one way to create a two dimensional variable, and how to obtain information about it. matlab> data = [ transpose([1,2,3]) , transpose([4,5,6]) ] ; matlab> whos matlab> data matlab> [ num_column, num_row ] = size(data) matlab> num_elements = numel(data) matlab> min( data(:) )

66

matlab> [ index_column, index_row ] = find( data <=2 ) matlab> index = find( data <= 2 ) matlab> data(index) The first command creates a two dimensional array. The "whos" command will give a list of all the variables defined in this Matlab session. To print all the elements of a variable to the screen, you simply type the name of the variable on the command line and hit the "return" key. To obtain the number of elements in each dimension of the array, use the size( ) function, as shown above. To obtain the total number of elements in the array use the numel( ) function. The min() function returns the minimum of a one dimensional array. To get the minimum of an array with two or more dimensions, you need to use the "(:)" syntax inside the call to min( ) in order to temporarily convert it to a one-dimensional array. The max( ), mean( ), and median( ) functions work the same way. To get the total of all elements in an array, use the sum( ) function. If you to put multiple commands on the same line, separate them with commas if you want to see the output printed to the screen or with semicolons if you don't want to see the output. The find command returns the index of all of the elements of the array that satisfy the given relational expression. When working in Matlab, there are several commands that can help you keep your work organized: matlab> diary filename matlab> % this is a comment The "diary filename" stores a copy of all the commands you type in the filename diary file, for future reference. When you are finished with a diary file type "diary off". The "%" character is encountered, the rest of the line is treated as a comment. This is true regardless of whether the "%" character appears at the beginning or the middle of the line. The up arrow key will allow you to edit previous commands that you've issued and then reissue them.

67

Below is a list of some of the operators in the Matlab language. Mathematical Operators in Matlab +, -, *, / addition, subtraction, multiplication, division a mod b modulus, i.e., signed remainder after division a^b raise a to the b power exp(b) raise e≈2.71828 to the b power log(b) take natural log of b log10(b) take the log base 10 of b sqrt(b) take the square root of b abs(b) absolute value of b fix(b) truncate b to obtain an integer round(b) the closest integer to b ceil(b) the smallest integer greater than or equal to b floor(b)the largest integer less than or equal to b Relational Operators in Matlab a < b a less than b a > b a greater than b a <= b a less than or equal to b a >= b a greater than or equal to b a == b a equal b a != b a not equal b Logical Operators in Matlab a & b a and b a | b a or b ~ b not b Miscellaneous Characters in Matlab

% starts a comment ... if the line ends with this sequence of

characters, the command continues onto the next line

a, b use a comma to execute two commands on the same line

68

a; b; use semi-colons to separate commands on the same line that you do not want output printed from to the screen

There are many ways in matlab to display a two dimensional array. One of those ways is using a contour plot, as shown below. matlab> contour( data ) %to draw contour lines matlab> [cs,h] = contourf( data ) %to draw filled contours matlab> % ----- add labels matlab> clabel( cs, h, 'FontSize', 18, 'FontWeight', 'bold' ) matlab> title( 'main title' ), xlabel( 'x title' ), ylabel( 'y title' ) matlab> colorbar matlab> % ----- limit the range of the x and y axis matlab> axis( [ min_x, max_x, min_y, max_y ] ) There are two ways to save an image that you have generated. You can use the file->export menu item of the window that contains the image. Alternatively, you can use the following menu option: print( '-dpng', 'image.png' ) Matlab can also save images in a variety of other formats. These formats can be listed by typing the "help print" command. Remember to type "more on" before using the help command, so that the text is displayed one page at a time.

Reading HDF 4 in Matlab Reading an HDF subset in Matlab is similar to reading an HDF subset in IDL. If you want to read the first array in the file called f i l ename , use the following Matlab commands:

matlab> filename = ‘filename’; matlab> sds_list = read_sds_name( filename ); matlab> data = read_sds(filename, sds_list(1) );

The source code for the read_sds_name.m Matlab function is as follows:

69

function sds_list = read_sds_name( filename ) %---------------------------------------- file_id = hdfsd( 'start', filename , 'read' ) ; num_sds = hdfsd( 'fileinfo', file_id ) ; for i = 1 : num_sds %hdf is ZERO based, while matlab is 1 based!! sds_id = hdfsd( 'select', file_id, i -1 ) ; next_name = hdfsd( 'getinfo', sds_id ) ; if i == 1 sds_list = next_name ; else sds_list = char( sds_list , next_name ) ; end hdfsd( 'endaccess', sds_id ) ; end hdfsd( 'end', file_id ) ; sds_list = cellstr( sds_list ) ; % -- end of function --

The source code for the read_sds.m Matlab function is as follows:

function data = read_sds( filename, var_name ) %---------------------------------------- file_id = hdfsd( 'start', filename , 'read' ) ; which_sds = hdfsd( 'nametoindex', file_id, char(var_name) ) ; sds_id = hdfsd( 'select', file_id, which_sds ) ; [name,rank,dim_size] = hdfsd( 'getinfo', sds_id ) ; start_index = dim_size - dim_size ; stride_index = start_index +1 ; edge_index = dim_size ; data = hdfsd( 'readdata', sds_id , ... start_index, stride_index, edge_index ) ; %since some matlab functions fail on the common hdf %datatype of int16. data = double( data ) ; hdfsd( 'endaccess', sds_id ) ; hdfsd( 'end', file_id ) ; % -- end of function --

70

Reading ASCII in Matlab Reading an ASCII file into Matlab is a little more complicated than in IDL because Matlab does not have a generic way to read an n-dimensional array from an ASCII file in a single operation. First, place the following text in a file called “read_ascii.m.”

function data = read_ascii( filename ) %---------------------------------------- id = fopen( filename ) ; if id == -1 error( ['error: file could not be opened... ' filename] ); end format_name = fgetl( id ) ; num_dim = fscanf( id, '%d', 1 ) ; dim_size = fscanf( id, '%d', num_dim ) ; [ 'info: ', int2str(num_dim), 'D variable in ' ... filename ' has a size of ( ', ... int2str(transpose(dim_size)) ' ) ' ] switch num_dim case 1 ; data = fscanf( id , '%f' ) ; case 2 ; data = fscanf( id , '%f', ... transpose(dim_size) ) ; case 3 data = zeros( transpose(dim_size) ) ; for i = 1:dim_size(3) data(:,:,i) = fscanf( id , '%f', ... transpose(dim_size(1:2)) ) ; end otherwise error( ['error: invalid dimensions... ' ... int2str(num_dim)] ) ; end fclose( id ) ; % -- end of function –

Second, start a matlab session and type “data = read_ascii( f i l ename ) ; ”, where f i l ename is name of the ASCII file that you wish to read.

71

Glossary

1C21. A standard TRMM algorithm that contains single-orbit uncorrected reflectivity data from the Precipitation Radar.

2A12. A standard TRMM algorithm that contains single-orbit rain estimates from the TRMM Microwave Imager.

2A25. A standard TRMM algorithm that contains single-orbit rain estimates for the Precipitation Radar.

3D. three-dimensional. 3G68. A TRMM algorithm that contains hourly 0.5 degree

gridded rain estimates for one full day from the 2A12, 2A25, and 2B31 algorithms.

Arc/Info. A GIS program manufactured by ESRI that is driven by a command line.

Arc/View. A GIS program manufactured by ESRI that is driven by a Graphical User Interface (GUI).

ASCII. American Standard Code for Information Interchange. In this tutorial, an ASCII file is used as a synonym for a pure text file. If an ASCII file were read as a stream of one-byte integers, character meanings could be assigned to some of

72

the 256 values of an unsigned one-byte integer: a-z (97–122), A–Z (65–90), blank space (32), C-end-of-string (0), tab (9), new-line (10). In a text file created on a UNIX system, lines end with a byte value of 10. In a text file created on a Microsoft Windows system, text lines end in a two-character sequence of [10,13].

bit. A one-digit number in base-two. A bit takes on the values of 0 or 1. File transfer rates on the internet are often stated in bits per second. Since files sizes are measured in bytes, not bits, divide the transfer rate in bits per second by approximately 8 to estimate the transfer rate in bytes per second. The estimate may be optimistic because of overhead in the transfer process.

BMP. Bitmap Pattern. An uncompressed binary file format used to store images.

byte order. The order in which bits are read to construct single byte or a multi-byte value (i.e., long integers and floats). When reading binary data, it is important to know if the byte order of your machine differs from the byte order of the machine that the file was created on. If the byte order differs, you must swap the bits after reading them. In the big-endian byte order, the most significant bit is listed first in the byte. Most high-end computers today are big-endian. In the little-endian byte order, the least significant bit is listed first. Intel-compatible PCs and Digital VAX computers are little-endian. The byte order is determined by the hardware, not the system software. For example, a Linux system running on a PC will be little-endian, but Linux running on a SUN computer will be little-endian.

byte. An eight-digit number in base-two. An unsigned byte takes on the base-ten values of 0 to 255. File sizes are often stated in bytes or multiples of bytes. When measuring physical quantities, the following prefixes are defined by powers of ten: kilo- (103), mega- (106), giga- (109), tera- (1012), and peta- (1015). When measuring file sizes, use powers of 2: 1 k = 210=1024 bytes, 1 M = 220≈1.05e6 bytes, 1 G =

73

230≈1.07e9 bytes, 1 T = 240≈1.10e12 bytes, 1 P = 250≈1.13e15 bytes.

CD. Compact Disk. A common optical storage media. CDs come in several varieties: CD-ROMs, which are mass produced by etching the data onto the disk; CD-Rs, on which data is burned after the disk is manufactured; and CD-RWs, which are like CD-Rs except that data can be erased and rewritten.

color bar. A color bar is a graphical representation of a color table.

color depth. Also referred to as the display depth. To define the color of each pixel of an image, the pixel is assigned a number with a certain number of bits. Eight-bit pixels were standard in the 1980s and most of the 1990s, but 16 and 24-bit pixels have recently become common.

color map. A color map defines how data values are mapped to the colors of a color table.

color table. The ordered set of colors used in an image with pixels generally no larger than eight-bits. Eight-bit color devices generally have a maximum of 256 colors in their color tables. Each color in a color table is usually defined by a red-green-blue (RGB) triplet.

DAAC. Distributed Active Archive Center. The Goddard Earth Sciences DAAC archives and distributes TRMM data to the public. [http://daac.gsfc.nasa.gov].

EORC. Earth Observation Research Center. An organization within JAXA. [http://www.eorc.JAXA.go.jp].

ESRI. Environmental Systems Research Institute. The company that makes the Arc/Info software and other GIS software. [http://www.esri.com].

fov. field-of-view. FTP. File Transfer Protocol. A popular way to transfer files

between computers. Anonymous FTP sites allow you to download files using “anonymous” as the username and your e-mail address as the password. If you wish a file to be

74

encripted while being downloaded, use the UNIX program “scp” instead of FTP.

GIF. Graphic Interchange Format. The GIF image format uses loss-less compression and can be displayed by web browsers.

GIS. Geographical Information System. A software package for generating and analyzing maps.

GrADS. Grid Analysis and Display System. A display program and its associated binary file format used by many researchers who model the global atmospheric. GrADS is developed and maintained by Brian Doty of the Center for Ocean, Land, and Atmosphere Studies (COLA). [http://grads.iges.org].

GSFC. Goddard Space Flight Center. GSFC is NASA’s research center located in Greenbelt, Maryland. PPS and the Goddard DAAC are located at GSFC. [http://www.gsfc.nasa.gov].

GUI. Graphical User Interface. A window that allows the user to control a program by using menus, buttons, and mouse clicks. An alternative way to control a program is through the use of a command line on which the user types in commands.

HDF. Hierarchical Data Format. A binary data format first developed by NCSA in the late 1980s and adopted by NASA for its earth observing data in the early 1990s. [http://hdf.ncsa.uiuc.edu].

HTML. Hypertext Markup Language. The most popular format for web pages since the World Wide Web first became popular in the mid-1990s.

ICS. Interface Control Specification. Volumes 2 and 3 of this series of documents describe the file formats of TRMM standard products. The ICS is available from the PPS Web site. [http://pps.gsfc.nasa.gov].

IDL. Interactive Data Language. This high-level language is developed by RSI [http://www.rsinc.com], and it is the language that the Orbit Viewer is written in. IDL combines the ease of programming of a high-level language with some of the computation speed of low-level languages. It also has

75

built-in features useful to scientists such data format procedures (include HDF access routines), commands to define graphical user interfaces, and computation procedures.

IDLDE. IDL Development Environment. The graphical user interface for the IDL language. Type “idlde” to launch it on a UNIX system, or type “idl” to start the interactive command line.

JAXA. Japanese Aerospace Exploration Agency. JAXA is the Japanese government’s counterpart to NASA. Prior to October, 2003, this organization was called the National Space Development Agency (NASDA) [http://www.jaxa.jp].

JPEG. Joint Photographic Expert Group. The JPEG image format uses lossy-compression and so is not well-suited for images that contain text or lines.

lat. latitude. LIS. Lighting Imaging Sensor. One of the TRMM instruments.

Pronounced “ l z.” lon. longitude. Mac OS X. Since 2001, the UNIX-based operating system of

Mackintosh computers. The "X" is read as the letter "X" not the roman numeral 10. The nicknames, versions, and release dates of this operating system are: Cheetah (v10.0, 2001), Puma (v10.1, 2001), Jaguar (v10.2, 2002), Panther (v10.3, 2003), and Tiger (v10.4, 2005). [www.mac.com]

Matlab. Matrix Laboratory. A software package for analyzing and displaying data. [http://www.mathworks.com].

mm/h. millimeters per hour. The unit of rainfall rate. One inch per hour is 25.4 mm/h.

NASA. National Aeronautics and Space Administration. A government agency of the United States of America. [http://www.nasa.gov].

NICT. The National Institute of Information and Communications Technology. Prior to April, 2004, this organization was called the Communications Research Laboratory (CRL). CRL built the TRMM Precipitation Radar. [http://www.nict.go.jp].

76

NCSA. National Center for Supercomputing Applications. As the name would imply, the NCSA develops applications for supercomputers and has also developed software such as telnet and the Mosaic web browser and data formats such as HDF.

PNG. Portable Network Graphic. The PNG image format was developed in the 1990s, and most web browsers can now display it. PNG uses loss-less compression. [http://www.libpng.org].

PPS. The Precipitation Processing System at NASA Goddard. The organization that processes TRMM data to produce the TRMM standard products. Prior to June of 2008, this organization was called TSDIS. [http://pps.gsfc.nasa.gov].

PR. Precipitation Radar. rain. Precipitation in the form of liquid water. rainfall rate. The rate at which liquid or solid water

precipitation is falling. Typical units are millimeters per hour (mm/h).

rainfall. The amount of accumulation of liquid or solid water precipitation. Typical units are millimeters per day or millimeters per month.

RSI. Research Systems, Inc. The manufacturers of the IDL language. [http://www.rsinc.com].

SDS. Scientific Dataset. A type of data object that can appear in an HDF file. An SDS is basically an array of data.

TIFF. Tagged Image Format. An image format with loss-less compression.

TMI. TRMM Microwave Imager. TRMM. Tropical Rainfall Measuring Mission. Pronounced

“tr m.” [http://trmm.gsfc. nasa.gov] and [http://www.eorc.JAXA.go.jp/ TRMM].

tropical cyclone. A tropical cyclone is the generic name for a storm 100-1000 km across with winds spiraling inward at sustained speeds of greater than 65 knots or 32 m/s. In the Atlantic Ocean, tropical cyclones are also called hurricanes.

77

In the northwest Pacific Ocean, tropical cyclones are also called typhoons.

TSDIS. TRMM Science Data and Information System. The former name for what is now called the Precipitation Processing System (PPS).

TSU. TSDIS Science User. This acronym does not stand for “TRMM Science User.” A TSU is a scientist that the TRMM Project Scientist as given permission to obtain data directly from TSDIS instead of using the public data access site of the Goddard DAAC.

Vdata. Vertex Data. A type of data object that can appear in an HDF file. A Vdata is a table of information: each column can be a different data type, and each row has an identical data structure to all the other rows in the table.

VIRS. Visible and Infrared Scanner.