PDS_VERSION_ID = PDS3 RECORD_TYPE = STREAM OBJECT = TEXT INTERCHANGE_FORMAT = ASCII PUBLICATION_DATE = 1994-05-13 NOTE = "Description of the ANSI C library and example programs provided with the GVDR CD-ROM." END_OBJECT = TEXT END GVDR Software: Library and Example Programs =========================================== The SOFTWARE directory contains both source code and compiled programs to read the GVDR data files. The source code is written in standard ANSI C and resides in the SOURCE subdirectory. Compiled programs are provided for two computer platforms: MIPS-based DecStation running Ultrix (in the DECMIPS subdirectory) and Sun Sparcstation running SunOS (in the SUN4 subdirectory). All the code should be portable to any Unix machine with an ANSI C compiler. Unfortunately, many computer vendors do not supply working ANSI C compilers with their products; one solution is to use the GNU C compiler gcc, which is freely available for many different machines. The GVDR-specific library does not require Unix and should be portable to any platform supporting ANSI C. Despite this claim of portability, the source code is provided primarily as an example of a GVDR reader program that happens to work on a few specific platforms. Users on other platforms should use these examples as starting points for developing their own programs to read the GVDR. The code in the PROJ and REGEX directories may require particular attention when porting to a different system. Unfortunately, we lack the expertise to give any further helpful advice here. We hope that our examples get you started in the right direction. This preliminary CD-ROM contains only minimal documentation for using the software; more complete documentation will be provided on the final revision. Note that the ISO 9660 standard for the format of CD-ROMs does not permit file names with mixed case, and limits the length of file names to 8 characters before a period and 3 characters after the period. The CD-ROM driver on your system will map all CD-ROM file names to either lower case or upper case. This documentation assumes that the files are mapped to upper case. Parts of the compilation process may fail if the files are not converted to lower case. It is therefore best to convert all file and directory names to lower case before compiling. The SOFTWARE directory includes two packages not written by the producers of this GVDR, PROJ and REGEX. Both packages are available for public redistribution with some restrictions. See the files named COPYING in the SOURCE/PROJ and SOURCE/REGEX subdirectories for the conditions of redistribution. In both cases, some of the file names within the packages have been modified to conform to the ISO 9660 standard mentioned above. This is the only modification either package has experienced. The complete original distributions are available in the DISTRIB subdirectory. Both packages require an ANSI C compiler like gcc. The executable directories DECMIPS and SUN4 contain the following programs: GVPTEST program to examine a single pixel of the GVDR GVP2MAT program to extract a portion of GVDR into a Matlab(*) format MAT-file and supporting files: LIBGVDR.A library routines for accessing GVDR files LIBMISC.A miscellaneous routines used by libgvdr.a LIBPROJ.A map projection routines used by libgvdr.a LIBML.A Matlab interface routines used by gvp2mat REGEX.O regular expression routines used by gvp2mat MATLS program to list the contents of a Matlab MAT-file GVPTEST ======= This program reads a set of GVDR files in the current directory (for example, /GVDR/MERC). It repeatedly queries the user for a pair of pixel coordinates, then reads the appropriate pixel from the GVDR files and prints out its contents. It is provided mainly as an example of using the GVDR software library, and should be a starting point for anyone desiring to write their own specialized GVDR reader. It is invoked from the command line by simply typing (assuming upper case has been changed to lower case): % gvptest GVP2MAT ======= This program reads a set of GVDR files in the current directory (for example, /GVDR/MERC), and extracts a rectangular region of pixels. The results are written in a fairly simple file format used by Matlab(*). This program is provided as another example of using the GVDR software library, and as a starting point for adding your own favorite file format. It is invoked from the command line by typing: % gvp2mat [options] outfile.mat where the available options are: -r regexp Variable name regular expression [.*] -L left Left side bounding box -R right Right side bounding box -T top Top side bounding box -B bottom Bottom side bounding box -l var=lo Set cohort selection lower limit for var to lo -u var=hi Set cohort selection upper limit for var to hi -g Bounding box in geographic coordinates (lon/lat) (This help list is available with the '-h' option). Warning: if none of the options is given, every variable in the entire GVDR will be extracted to the output file 'outfile.mat'. This will use quite a bit of memory and disk space. Several options allow the user to make more specific requests. The '-r regexp' option limits the variables extracted to only those that match 'regexp'. For example, '-r gd_' will extract any variables with 'gd_' in their name. The variables are named according the the field names in gvdr.h, the file that resides in the SOURCE/GVDR subdirectory and defines the format of the GVDR. In the case of 'gd_', look in gvdr.h for the gvdradf_t structure and note that all seven of its fields begin with 'gd_'. Thus, each of these fields will be extracted. The '-LRTB' options limit the region that will be extracted to those pixels that fall within the bounding box. The bounding box is expressed in the pixel coordinates defined by the IMAGE_MAP_PROJECTION. If these options are omitted, the values in GVHDR.TAB file that define the maximum bounding box are used. (These values are LEFTMOST_MAP_COORD, RIGHTMOST_MAP_COORD, TOPMOST_MAP_COORD, and BOTTOMMOST_MAP_COORD.) The '-lu' options are more sophisticated. Since a given pixel may have several observations of a single quantity made under different geometrical conditions, some constraint on the selection of many possible observations is required. If the candidate observations are not limited by these options, all observations of a given quantity will be averaged to form the final result. If they are limited by the '-lu' options, only those observations that satisfy the constraints will be used in the average. For example, to limit the results to observations that were made with SAR incidence angles of greater than 30 degrees but less than 40 degrees, use % gvp2mat -l gx_inc=30 -u gx_inc=40 [etc...] Normally, one is only interested in SAR observations when using one of the SAR quantities to limit the selection. Thus the following command would be more useful: % gvp2mat -r gx_ -l gx_inc=30 -u gx_inc=40 [etc...] Many such selection criteria can be specified, and only those observations that simultaneously satisfy all criteria qualify. We could further limit the field to left-looking orbits by saying % gvp2mat -r gx_ -l gx_inc=30 -u gx_inc=40 -l gx_azim=180 since all left-looking orbits have SAR azimuthal angles of 180-360 degrees (except near the poles or in a polar projection). Finally, the '-g' option toggles the interpretation of the '-LRTB' arguments between longitude/latitude and pixel x/y. The normal interpretation is in pixel coordinates; with '-g' the interpretation is in geographic coordinates. For convenience, here is a list of all possible GVDR variables. Each corresponds to a particular column in the GVDR data files. Pixel header variables gv_X gv_Y gv_lon gv_lat gv_reclen gv_Nxif gv_Nedf gv_Nadf gv_Nanf SAR observations gx_Nlooks gx_azim gx_inc gx_poln gx_hlo gx_hmed gx_hhi gx_hpk gx_c0 gx_c1 gx_c2 gx_cang (not included in this preliminary version) Radiometer observations ge_Nlooks ge_azim ge_inc ge_poln ge_emiss ge_emissv MIT Altimetry observations gd_Nlooks gd_radius gd_radiusv gd_slope gd_slopev gd_rho gd_rhov Stanford Altimetry observations ga_Nlooks ga_Nsig0 ga_Nfit ga_dcent ga_azim ga_sig0 ga_Vsig0 Scattering law fits gf_Hag_flags gf_Exp_flags gf_Gau_flags gf_Ray_flags gf_Muh_flags gf_Hag_p1 gf_Exp_p1 gf_Gau_p1 gf_Ray_p1 gf_Muh_p1 gf_Hag_p1v gf_Exp_p1v gf_Gau_p1v gf_Ray_p1v gf_Muh_p1v gf_Hag_p2 gf_Exp_p2 gf_Gau_p2 gf_Ray_p2 gf_Muh_p2 gf_Hag_p2v gf_Exp_p2v gf_Gau_p2v gf_Ray_p2v gf_Muh_p2v gf_Hag_rms gf_Exp_rms gf_Gau_rms gf_Ray_rms gf_Muh_rms gf_Hag_rms gf_Exp_rmsv gf_Gau_rmsv gf_Ray_rmsv gf_Muh_rmsv gf_Hag_resid gf_Exp_resid gf_Gau_resid gf_Ray_resid gf_Muh_resid MATLS ===== This program lists the contents of MAT files created by the gvp2mat program, and can be used as a first test of its results. It is invoked from the command line by typing: % matls outfile.mat where 'outfile.mat' is the file you wish to list. The SOURCE directory contains the complete source code required to compile these three programs. On a standard Unix machine, the code may be compiled by copying the entire SOURCE directory to a writable medium and then running 'make' in the SOURCE directory. Note that some CD-ROM drivers will capitalize all letters in file names, or add version numbers after a semicolon. These changes must be undone before compiling. The final file names should be all lower case without version identifiers. The SOURCE directory has the following structure: SOURCE MAKEFILE Unix-style rules for compilation GVDR/ Subdirectory containing GVDR library source code and example programs gvptest and gvp2mat MAKEFILE Unix-style rules for compilation CALLPROJ.C CALLPROJ.P GCVT.C GCVT.H GCVT.P GPACK.C GPACK.H GPACK.P GPDS.C GPDS.H GPDS.P GV_CVT.C GV_CVT.P GV_INDEX.C GV_INDEX.P GV_PACK.C GV_PACK.H GV_PACK.P GV_PROJ.C GV_PROJ.P GV_SFDU.C GV_SFDU.H GV_SFDU.P GVDR.C Basic GVDR parsing routines GVDR.H GVDR.P GVP2MAT.C GVP2MAT.P GVPDSLIB.C Basic PDS-format GVDR routines GVPDSLIB.H GVPDSLIB.P GVPDSTAB.H GVPTEST.C GVPTEST.P PDSTAB.C Basic PDS-format table routines PDSTAB.H PDSTAB.P PROJ.C PROJ.H PROJ.P SFDUG.C SFDUG.H SFDUG.P TGVDRMAT.C TGVDRMAT.H TGVDRMAT.P LIBML/ Subdirectory containing source code to the Matlab MAT-file interface library INSTALL MAKEFILE README VERSION ERROR.C IVCVT.C LIBMISC.H LIBML.H LIBML.P LIBMLVER.H MAT2MAT.C MAT2MAT.P MATLS.C MATLS.P MLCVT.C MLMISC.C MLREAD.C MLVER.C MLWRITE.C PGM2MAT.C PGM2MAT.P PROJ/ Subdirectory containing source code to the USGS map projection library. Note that some file names have been changed from the original distribution in order to conform to ISO 9660 8.3 naming conventions. CHANGELG COPYING README CONFIGUR Configuration script for installation INSTALL.IN MAN/ Unix man pages for PROJ routines and programs MAN1/ GEOD.1 NAD2NAD.1 PROJ.1 MAN3/ PJ_INIT.3 SRC/ Source code for all PROJ library routines AASINCOS.C ADJLON.C BCH2BPS.C BCHGEN.C BIVEVAL.C DMSTOR.C EMESS.C EMESS.H GENCHEBY.C GEOD.C GEODESIC.H GEOFORWD.C GEOINVRS.C GEOSETUP.C HYPOT.C MAKEFILE.IN MK_CHEBY.C NAD2BIN.C NAD2NAD.C NADINTRP.C NAD_CVT.C NAD_INIT.C NAD_LIST.H PJ_AUTH.C PJ_DERIV.C PJ_ELLPS.C PJ_ELSET.C PJ_ERRNO.C PJ_FACTR.C PJ_FWD.C PJ_INIT.C PJ_INV.C PJ_LIST.C PJ_LIST.H PJ_MALLO.C PJ_MLFN.C PJ_MSFN.C PJ_OLIB.C PJ_PARAM.C PJ_PHI2.C PJ_PLIST.C PJ_QSFN.C PJ_REL.C PJ_STRER.C PJ_TSFN.C PJ_UNITS.C PJ_ZPLY1.C PROJ.C PROJECTS.H PR_SERES.C README RTODMS.C STRTOD.C VECTOR1.C X_AEA.C X_AEQD.C X_AIRY.C X_AITOFF.C X_AUGUST.C X_BACON.C X_BIPC.C X_BOGGS.C X_BONNE.C X_CASS.C X_CC.C X_CEA.C X_CHAMB.C X_COLLG.C X_CRAST.C X_DENOY.C X_ECK1.C X_ECK2.C X_ECK3.C X_ECK4.C X_ECK5.C X_EQC.C X_EQDC.C X_FAHEY.C X_FOUC_S.C X_GALL.C X_GINS8.C X_GNOM.C X_GNSINU.C X_GOODE.C X_HAMMER.C X_HATANO.C X_LABRD.C X_LAEA.C X_LAGRNG.C X_LARR.C X_LASK.C X_LCC.C X_LOXIM.C X_LSAT.C X_MBTFPP.C X_MBTFPQ.C X_MBTFPS.C X_MDSTER.C X_MERC.C X_MILL.C X_MOLL.C X_NELL.C X_NELL_H.C X_NOCOL.C X_NSPER.C X_NZMG.C X_OBTRAN.C X_OCEA.C X_OEA.C X_OMERC.C X_ORTHO.C X_PCONIC.C X_POLY.C X_PUTP2.C X_PUTP3.C X_PUTP4P.C X_PUTP5.C X_PUTP6.C X_ROBIN.C X_RPOLY.C X_STERE.C X_STS.C X_TCC.C X_TCEA.C X_TMERC.C X_TPEQD.C X_URM5.C X_URMFPS.C X_VANDG.C X_VANDG2.C X_VANDG4.C X_WAG2.C X_WAG3.C X_WAG7.C X_WINK1.C X_WINK2.C REGEX/ Subdirectory containing source code to the GNU regular expression library. Note that some file names have been changed from the original distribution in order to conform to ISO 9660 8.3 naming conventions. AUTHORS COPYING CHANGELG INSTALL MAKEFILE.IN NEWS README CONFIGUR Configuration script for installation CONFIGUR.IN REGEX.C REGEX.H CHANGES Description of changes from the original distribution. DISTRIB/ Subdirectory containing compressed software archives. The first set of files contains the original distributions of the PROJ and REGEX packages. The second set of files contains the slightly modified versions used in the proj and gvdr directories. The modifications were limited to file renaming to comply with ISO 9660 8.3 standards. PROJ43.TGZ The complete distribution of USGS PROJ library version 4.3, in standard Unix tar format and compressed by GNU gzip. PROJ43P1.TXT Patch #1 for USGS PROJ 4.3. PROJ43P2.TXT Patch #2 for USGS PROJ 4.3. PROJ43PS.GZ Documentation for USGS PROJ 4.3, in a PostScript file compressed by GNU gzip. REGEX012.TGZ The complete distribution of GNU REGEX version 0.12, in standard Unix tar format and compressed by GNU gzip. GVDR.TGZ A copy of the files stored in the gvdr directory, in standard Unix tar format and compressed by GNU gzip. LIBML.TGZ A copy of the files stored in the libml directory, in standard Unix tar format and compressed by GNU gzip. PROJ.TGZ A copy of the files stored in the proj directory, in standard Unix tar format and compressed by GNU gzip. Note that because of the file name remapping mentioned below, some of these files have slightly different names from the originals in PROJ43.TGZ. REGEX.TGZ A copy of the files stored in the regex directory, in standard Unix tar format and compressed by GNU gzip. Note that because of the file name remapping mentioned below, some of these files have slightly different names from the originals in REGEX012.TGZ. SOFTWARE SUGGESTIONS FOR BEGINNERS ================================== This software package is not really "user friendly" for beginners. But here are a few pointers that may help if you're not a software expert. If you aren't using the CD with a Unix machine, these notes won't be much help. If you don't have Unix, you may be limited to working with the standard ANSI C subroutines in SOFTWARE/SOURCE/GVDR. Good luck. 1. Make a hard copy of SOFTINFO.TXT from the SOFTWARE directory. Read it. 2. The notes below retain the upper case directory and filenames on the CD. Your system may have converted these to lower case automatically; Sun typically does, for instance. If you need to compile any of the source code or use any of the MAKEFILEs, your life will be considerably simpler if you convert everything to lower case any time you copy files or directories. The Unix script below will do this for all the file or subdirectory names in your current working directory: % foreach filename ( `ls` ) > set filename1 = `echo $filename | tr A-Z a-z` > mv $filename $filename1 > end % 3. If you have a compatible computer (Sun SPARCStation running SunOS 4.1.2, or a DEC MIPS work station running Ultrix 4.2a), you can probably use the executables we have provided. Try running GVPTEST as follows: a. Change directories to $CDPATH/GVDR/MERC, where $CDPATH is the path to the root of the CD. b. Type $CDPATH/SOFTWARE/SUN4/GVPTEST (if you have a Sun) or Type $CDPATH/SOFTWARE/DECMIPS/GVPTEST (if you have a DEC). c. If this works, you will be asked for pixel coordinates. If not, go to step 5 (below). 4. If you have a different Sun or Ultrix machine, you might want to try step 3 (above). 5. If you're not afraid of compressed files, you can copy the files in SOFTWARE/SOURCE/DISTRIB to a magnetic disk, use Gnu gzip to uncompress them, and tar to unbundle them. Gnu gzip is not provided on the CD, but it is one of many utilities available through the Free Software Foundation, 675 Massachusetts Ave., Cambridge, MA 02139. You should set up directories PROJ, REGEX, GVDR, and LIBML on your magnetic disk to hold the output. Within each directory, type "make all". Then try running something like the GVPTEST executable in GVDR/MERC. 6. Perhaps the slowest, but also the simplest, approach is to copy the SOFTWARE/SOURCE directory to magnetic disk using a command like "cd SOFTWARE; tar cf - SOURCE | (cd your_disk_area; tar xpf -)". After converting to lower case file/directory names (see step 2 above), cd to SOURCE in your copy and type "make all". a. If this works, it will take 10-15 minutes to do all the compilations; you'll get a running commentary on your screen. Then you can go to GVDR/MERC on the CD and type "your_disk_area/source/gvdr/gvptest" to run GVPTEST. b. If this doesn't work, you might check that you have a functional version of the Gnu ANSI C compiler (or an equivalent compiler that handles standard ANSI C). Many compilers provided with Unix system are not ANSI standard C compilers. Some of the MAKEFILEs on the CD look for the compiler "gcc". If they don't find it, they may look for substitutes; the substitutes may or may not work. And we have found an old version of "gcc" that also didn't work. 7. If none of the above works, look for a computer guru. (*) MATLAB is a commercial software package for data analysis and visualization. MATLAB is a registered trademark of The Mathworks, Inc.