Pileus Git - ~andy/rsl/blob - README

   1 v1.43 (Released 4/30/2012)
   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, and mcgill 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: RSL is not supported on Microsoft Windows.
  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 Example mainlines are provided in the directory examples.
  93
  94 INSTALLATION INSTRUCTIONS
  95 --------------------------
  96
  97 1.  Unpack the GNU compressed tar archive, example:
  98
  99      tar -xzf rsl-v1.43.tgz
 100
 101          -or-
 102
 103      zcat rsl-v1.43.tgz | tar xf -
 104
 105 2. If you DON'T want LASSEN capability or you find that your system
 106    can not compile the lassen routines, you must edit acconfig.h and
 107    change '#define HAVE_LASSEN 1' to '#undef HAVE_LASSEN'.
 108
 109 3. configure
 110    make install    -- Installs the RSL library, and then installs
 111                       any_to_gif and any_to_uf.
 112
 113 NOTE: You can specify the --prefix=/some/other/dir as an option to
 114       the configure command.  This will install the librsl.so there
 115       and will install the examples there.  Also, when resolving
 116       whether you have hdf, tsdistk, etc. the --prefix instructs
 117       configure to look in the prefix/lib directory for those libraries.
 118           The examples installed are any_to_gif and any_to_uf.
 119
 120
 121 BUILDING APPLICATIONS
 122 ---------------------
 123 Place the following line in your C code:
 124
 125 #include "rsl.h"
 126
 127 And link your application with:
 128
 129    -lrsl -lm
 130
 131 If you're on a SUN, you might have to specify:
 132
 133    -lrsl -lnsl -lm
 134
 135 If you want HDF and TSDIS toolkit libraries (the link line looks messy):
 136
 137    setenv TSDISTK /usr/local/toolkit  (or your top-level directory name)
 138
 139    -lrsl -L/usr/local/hdf/lib  -L/usr/local/toolkit/lib \
 140    -ltsdistk -lmfhdf -ldf -ljpeg -lz -lm
 141
 142    Be sure to substitute the appropriate -L specification for the HDF
 143    and the TSDISTK library paths on your system.
 144
 145 PROBLEMS
 146 --------
 147
 148 1. If you don't have ppmtogif nor ppmtopict, you can still make images.  The
 149    images will be PPM files.  Create two commands called 'ppmtogif' and
 150    'ppmtopict' that consists of the following two lines:
 151 ---- cut ----
 152 #!/bin/csh -f
 153 cat
 154 ---- cut ----
 155    Make these new commands executable and
 156    place them in a directory that is in your $PATH.  No translation
 157    of PPM will happen and you can use 'xv', for instance, to view
 158    the files.
 159
 160 2. Linking on SUN running SunOS 5.4, you may need to add '-lnsl' to
 161    the link line to link your application.  'libnsl.{a,so}' is where
 162    the 'xdr' routines reside.
 163
 164 3. On our HP, gcc cannot build a shared library in one fell swoop.  You
 165    must use the '-v' option.  You'll get an error similiar to that shown
 166    in the following 'make' excerpt.
 167
 168
 169 ----- cut -----
 170 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
 171 Reading specs from /opt/hppd/lib/gcc/gcc-lib/hppa1.1-hp-hpux9.05/2.7.2.1/specs
 172 gcc version 2.7.2.1
 173  /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
 174 /bin/ld: DP-Relative Code in file /usr/tmp/cca11778.o - Shared Library must be Position-Independent
 175 collect2: ld returned 1 exit status
 176 make: *** [librsl.so.1.17] Error 1
 177 ----- cut -----
 178
 179    Take the 'ld' command that is shown, the second of the two commands,
 180    and execute it directly at the Unix prompt.  It will create the
 181    shared library. I don't get it, but, it works.  My guess is that
 182    the 'gcc' command is doing something that is not shown.  What is
 183    shown are the correct commands.  Go figure.
 184
 185
 186 Contributions
 187 -------------
 188 Dave Wolff - Most of the specifications for the functionality and feedback
 189              during debugging.
 190 Mike Kolander - The HDF, Mcgill and kwaj to radar routines.
 191 Alan McConnell - The toga_to_radar routine.
 192 Dennis Flanigan - New sorting code. Echo top height routines. Vertical
 193                   structure code.
 194 Thuy Nguyen - Bug fixes and testing.
 195 Paul Kucera - Testing, bug reports and SIGMET code.
 196 Michael Whimpy - BMRC, Austrailia.  Lassen modifications.
 197 Don Burrows - The edge_to_radar routine.
 198
 199 QUESTIONS
 200 ---------
 201
 202 Contact the TRMM Office help at gsfc-rsl-help@lists.nasa.gov