Docstoc

tutorial

Document Sample
tutorial Powered By Docstoc
					      Visualization Software for the
Tropical Rainfall Measuring Mission
                           ( TRMM )



                    The
                  O rbit
                 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
                 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].




                                6
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


                                7
(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 Control Specification
(ICS), volumes 3 and 4 [http://pps.gsfc.nasa.gov]. The TRMM
PR Algorithm Instruction 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

                                 8
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 Geoscience 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.
      Geophysical 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.
      of Atmos. and Oceanic Tech., 17, 385-94.



                                9
   (Combined PR/TMI rain algorithm: 2B31) Haddad, Z.S., et
      al., 1997: The TRMM ‘Day-1’ Radar/Radiometer
      Combined Rain-Profiling Algorithm.        J. of the
      Meteorological Society of 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/].



                                10
     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?



                               11
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?




                           12
                     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.


                               13
     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
filename.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.


                                14
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


                               15
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]




                                 16
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


                                17
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]



                                18
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


                                19
"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


                                 20
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.


                               21
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]


                                22
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,


                                23
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


                               24
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     ‘p a t h /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=‘p a t h /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 p a t h /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”




                                   25
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.




                              26
               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



                                27
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 filename” or “~/orbit.sh filename”
at the UNIX prompt, where filename 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.



                               28
    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.




                              29
                 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


                                30
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.




                               31
                     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.


                               32
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


                              33
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

                                34
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



                                35
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).




                                36
Figure 3.7. The 3D Control Window (top)
    and 3D Image Window (bottom).




                  37
             Observer                         Light
                                             Source



                                  Tropical              Light
           Observation
                                  Cyclone             Elevation
            Elevation


                                      Light
              Observation            Azimuth
               Azimuth


                        South

                                Vertical
                                 Shift                Zoom



                                  Tropical            Horizontal
                                  Cyclone               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


                                     38
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).




                                39
       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.




                                 40
        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).




                              41
               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




                                       42
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             (1)
colors, i.e., the color map. Generally, the                  (2 )
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.                         (5)        (4)
     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      (6 )
map information is not stored in the
standard products themselves. The Orbit                  (7)
Viewer’s color maps were created by                           (3)
examining the typical range of each array
and the important features that scientists        Figure 3.14.
might be interested in.                              Color Bar
     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


                                43
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


                                44
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        Figure 3.15.
change the color table. To change the colors       Gray Scale
for continuous data, select the                    Color Bar
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


                                45
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



                                 46
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).




                                                          (5)

                                    (1)


       (2)


                      (3)
                                                  (1)


                                                        (2)



                              (4)

                              (5)                             (4)

              (6)
             (7)


                Figure 3.17. Change the Color Map




                               47
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.


                               48
    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


                               49
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.




                                 50
      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.




                                51
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.




                               52
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.




                                53
            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).


                              54
               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, filename”, where
filename 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.




                              55
      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( filename )”.

      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).




                                56
              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


                                57
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


                                58
[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


                                59
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


                                 60
       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


                                61
       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


                                62
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 filename, use the following IDL
commands.
   IDL>   .run read_sds_name.pro
   IDL>   .run read_sds.pro
   IDL>   filename=’f i l en a m e ’
   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
   ;------------------------------



                               63
   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:


                               64
[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(:) )


                                65
       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.



                                66
    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


                               67
       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 filename, use the following Matlab commands:

   matlab> filename = ‘f i l en am e ’;
   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:

                                    68
   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 --




                               69
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(
filename ) ; ”, where filename is name of the ASCII file that you
wish to read.




                               70
                      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


                                71
    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 =



                                  72
    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



                                73
   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

                              74
     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].


                               75
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.



                                 76
   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.




                               77

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:2
posted:1/28/2013
language:simple
pages:77