Pileus Git - ~andy/rsl/blob - README

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