Pileus Git - ~andy/rsl/blob - README

   1 v1.41 (Released 6/22/2011)
   2
   3 This is the README file for the Radar Software Library (RSL).
   4
   5 The author of RSL is John H. Merritt.
   6
   7 RSL is maintained by Bart Kelley <Bartie.L.Kelley@nasa.gov>.
   8
   9 What is RSL?
  10    This software manipulates NexRad, Lassen, UF, sigmet, kwajalein,
  11 toga, RAPIC, RADTEC, mcgill and EDGE radar formats.
  12
  13 The radar data is used by the NASA TRMM Office to produce rain
  14 and climatological products.  This software
  15 can ingest an entire input data file, representing it in RAM as it
  16 is on disk, manipulate the data and produce simple images.  The intent
  17 of this library is to provide you with the tools to manipulate the
  18 data.  With those tools you gain easy access to the different radar
  19 fields (reflectivity, velocity, spectral width, etc.) and ancilliary
  20 information (headers: time, beam width, angles, etc).  And, with the
  21 tools you can code a scientific application that are radar format
  22 independent.
  23
  24 COPYRIGHT NOTICE:
  25     NASA/TRMM, Code 910.1.
  26     This is the TRMM Office Radar Software Library.
  27     Copyright (C) 1996-1999
  28             John H. Merritt
  29             SM&A Corp.
  30             Vienna, Virginia
  31
  32     This library is free software; you can redistribute it and/or
  33     modify it under the terms of the GNU Library General Public
  34     License as published by the Free Software Foundation; either
  35     version 2 of the License, or (at your option) any later version.
  36
  37     This library is distributed in the hope that it will be useful,
  38     but WITHOUT ANY WARRANTY; without even the implied warranty of
  39     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  40     Library General Public License for more details.
  41
  42     You should have received a copy of the GNU Library General Public
  43     License along with this library; if not, write to the Free
  44     Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  45
  46
  47 System Requirements:
  48   Linux, Mac OS X 10.5.
  49
  50   Note: MS Windows is not supported.
  51
  52 Memory Requirements:
  53   16 Mbytes of RAM just to ingest the data.  Plus any for your application.
  54   If you expect to use the TSDIS toolkit component, which requires the HDF
  55   library, then you'll need at least 64 MB RAM!
  56
  57 Software Environment.  Additional libraries may be needed for building
  58 or linking, especially if you plan to use the TSDIS Toolkit and HDF.
  59 All the source for wsr88d, lassen, tg, nsig, mcgill, kwajalein,
  60 etc, are included in librsl.a and librsl.so.  RSL works on big or
  61 little endian machines.  HP, SUN, SGI are examples of big endian machines.
  62 Intel 386/486/Pentium is an example of a little endian machine.
  63
  64 Additional software needed for executing RSL code is listed below.
  65 Note, RSL can be built without TSDIS toolkit and without HDF and
  66 without PKWARE support.
  67
  68   pbmplus (Jef Poskanzer) Available via anon ftp to ftp.uu.net.  This is
  69                           used when making GIF, PPM, PBM, PGM, PICT, etc.
  70                           images.  Output via pipes.  Required for executing
  71                           your RSL application, if you plan to output images.
  72                           This is not required when
  73                           linking your application with the RSL.
  74
  75                           You only need ppmtogif and ppmtopict.
  76
  77   gcc (GNU cc compiler)   Normal cc or acc (sun) will work.  Not required,
  78                           but, you do need an ansi compilier.
  79
  80   gzip (GNU compress)     Available via anon ftp to ftp.uu.net.  Unpacking.
  81                           Input and output filters for auto un/compressing.
  82
  83
  84   make (GNU make)         GNU make version 3.76. Standard make on SGI
  85                           IRIX 6.2 doesn't work.  It's a good idea
  86                           to have GNU make (GNU tar too).
  87
  88   PKWARE Data             Version 1.11.  Needed for the RAPIC ingest.
  89   Compression library.    Call PKWARE, Inc. at 414-354-8699 or via
  90                           http://www.pkware.com.
  91
  92   libetor                 The EDGE libraray to decode the EDGE format.
  93                           This is available from Enterprise  Electronics
  94                           Corporation, Enterprise,  Alabama,  USA  36330
  95                           334-347-3478.
  96
  97 Example mainlines are provided in the directory examples.
  98
  99 INSTALLATION INSTRUCTIONS
 100 --------------------------
 101
 102 1.  Unpack the GNU compressed tar archive, example:
 103
 104      tar -xzf rsl-v1.29.tgz
 105
 106          -or-
 107
 108      zcat rsl-v1.29.tgz | tar xf -
 109
 110 2. If you DON'T want LASSEN capability or you find that your system
 111    can not compile the lassen routines, you must edit acconfig.h and
 112    change '#define HAVE_LASSEN 1' to '#undef HAVE_LASSEN'.
 113
 114 3. configure
 115    make install    -- Installs the RSL library, and then installs
 116                       any_to_gif and any_to_uf.
 117
 118 NOTE: You can specify the --prefix=/some/other/dir as an option to
 119       the configure command.  This will install the librsl.so there
 120       and will install the examples there.  Also, when resolving
 121       whether you have hdf, tsdistk, etc. the --prefix instructs
 122       configure to look in the prefix/lib directory for those libraries.
 123           The examples installed are any_to_gif and any_to_uf.
 124
 125
 126 BUILDING APPLICATIONS
 127 ---------------------
 128 Place the following line in your C code:
 129
 130 #include "rsl.h"
 131
 132 And link your application with:
 133
 134    -lrsl -lm
 135
 136 If you're on a SUN, you might have to specify:
 137
 138    -lrsl -lnsl -lm
 139
 140 If you want HDF and TSDIS toolkit libraries (the link line looks messy):
 141
 142    setenv TSDISTK /usr/local/toolkit  (or your top-level directory name)
 143
 144    -lrsl -L/usr/local/hdf/lib  -L/usr/local/toolkit/lib \
 145    -ltsdistk -lmfhdf -ldf -ljpeg -lz -lm
 146
 147    Be sure to substitute the appropriate -L specification for the HDF
 148    and the TSDISTK library paths on your system.
 149
 150 PROBLEMS
 151 --------
 152
 153 1. If you don't have ppmtogif nor ppmtopict, you can still make images.  The
 154    images will be PPM files.  Create two commands called 'ppmtogif' and
 155    'ppmtopict' that consists of the following two lines:
 156 ---- cut ----
 157 #!/bin/csh -f
 158 cat
 159 ---- cut ----
 160    Make these new commands executable and
 161    place them in a directory that is in your $PATH.  No translation
 162    of PPM will happen and you can use 'xv', for instance, to view
 163    the files.
 164
 165 2. Linking on SUN running SunOS 5.4, you may need to add '-lnsl' to
 166    the link line to link your application.  'libnsl.{a,so}' is where
 167    the 'xdr' routines reside.
 168
 169 3. On our HP, gcc cannot build a shared library in one fell swoop.  You
 170    must use the '-v' option.  You'll get an error similiar to that shown
 171    in the following 'make' excerpt.
 172
 173
 174 ----- cut -----
 175 gcc -v -shared -W1,-soname,librsl.so.1 -o librsl.so.1.17 rapic_to_radar.o rapic.tab.o lex.rapic.o rapic_routines.o radar.o volume.o image_gen.o cappi.o fraction.o read_write.o farea.o range.o radar_to_uf.o uf_to_radar.o lassen_to_radar.o wsr88d_to_radar.o carpi.o cube.o sort_rays.o toga_to_radar.o gts.o histogram.o ray_indexes.o anyformat_to_radar.o get_win.o endian.o mcgill_to_radar.o mcgill.o interp.o toga.o lassen.o  wsr88d.o wsr88d_get_site.o gzip.o prune.o reverse.o fix_headers.o radar_to_hdf_1.o radar_to_hdf_2.o nsig_to_radar.o nsig.o nsig2_to_radar.o hdf_to_radar.o toolkit_memory_mgt.o africa_to_radar.o africa.o
 176 Reading specs from /opt/hppd/lib/gcc/gcc-lib/hppa1.1-hp-hpux9.05/2.7.2.1/specs
 177 gcc version 2.7.2.1
 178  /opt/hppd/lib/gcc/gcc-lib/hppa1.1-hp-hpux9.05/2.7.2.1/ld -b -o librsl.so.1.17 -L/opt/hppd/lib/gcc/gcc-lib/hppa1.1-hp-hpux9.05/2.7.2.1 -L/opt/hppd/lib/gcc rapic_to_radar.o rapic.tab.o lex.rapic.o rapic_routines.o radar.o volume.o image_gen.o cappi.o fraction.o read_write.o farea.o range.o radar_to_uf.o uf_to_radar.o lassen_to_radar.o wsr88d_to_radar.o carpi.o cube.o sort_rays.o toga_to_radar.o gts.o histogram.o ray_indexes.o anyformat_to_radar.o get_win.o endian.o mcgill_to_radar.o mcgill.o interp.o toga.o lassen.o wsr88d.o wsr88d_get_site.o gzip.o prune.o reverse.o fix_headers.o radar_to_hdf_1.o radar_to_hdf_2.o nsig_to_radar.o nsig.o nsig2_to_radar.o hdf_to_radar.o toolkit_memory_mgt.o africa_to_radar.o africa.o
 179 /bin/ld: DP-Relative Code in file /usr/tmp/cca11778.o - Shared Library must be Position-Independent
 180 collect2: ld returned 1 exit status
 181 make: *** [librsl.so.1.17] Error 1
 182 ----- cut -----
 183
 184    Take the 'ld' command that is shown, the second of the two commands,
 185    and execute it directly at the Unix prompt.  It will create the
 186    shared library. I don't get it, but, it works.  My guess is that
 187    the 'gcc' command is doing something that is not shown.  What is
 188    shown are the correct commands.  Go figure.
 189
 190
 191 Contributions
 192 -------------
 193 Dave Wolff - Most of the specifications for the functionality and feedback
 194              during debugging.
 195 Mike Kolander - The HDF, Mcgill and kwaj to radar routines.
 196 Alan McConnell - The toga_to_radar routine.
 197 Dennis Flanigan - New sorting code. Echo top height routines. Vertical
 198                   structure code.
 199 Thuy Nguyen - Bug fixes and testing.
 200 Paul Kucera - Testing, bug reports and SIGMET code.
 201 Michael Whimpy - BMRC, Austrailia.  Lassen modifications.
 202 Don Burrows - The edge_to_radar routine.
 203
 204 QUESTIONS
 205 ---------
 206
 207 Contact the TRMM Office help at help@radar.gsfc.nasa.gov