git.gag.com Git - debian/splat/blob - utils/README

   1                         ================
   2                         SPLAT! Utilities
   3                         ================
   4
   5 Utilities for use with SPLAT! software are found under the
   6 splat-1.2.1/utils directory.  They include the following:
   7
   8
   9 srtm2sdf
  10 ========
  11 The srtm2sdf utility generates SPLAT Data Files (SDFs) from 3-arc second
  12 STS-99 Space Shuttle Topography Mission (SRTM-3) elevation data files.
  13 This data is of a much higher quality than that contained in older USGS
  14 Digital Elevation Models of the same resolution.  However, many SRTM-3
  15 Version 2 elevation models contain data "voids" and "wells" that are the
  16 consequence of the radar mapping process.
  17
  18 The srtm2sdf utility has the ability to detect and replace SRTM data
  19 outliers with equivalent SDF data created through the usgs2sdf utility
  20 (below).  If equivalent USGS-derived SPLAT Data Files are not available,
  21 SRTM outliers are handled either through adjacent pixel averaging, or by
  22 threshold limiting using user-specified limits.  Of all three methods,
  23 the USGS-derived SDF replacement method yields the best results.
  24
  25 SRTM-3 Version 2 Elevation Data may be downloaded from:
  26
  27     ftp://e0srp01u.ecs.nasa.gov:21/srtm/version2/
  28
  29 Files available at this site are ZIP compressed, and must be
  30 uncompressed (using "unzip", or "gunzip -S .zip") prior to being
  31 processed by srtm2sdf.
  32
  33 The srtm2sdf utility accepts command-line options as follows:
  34
  35 -d: used to specify the directory path to the location of existing
  36     SDF files (presumably created at an earlier date through the
  37     usgs2sdf or postdownload utility) that are to be used to replace
  38     outliers found in the SRTM data file.  The -d option overrides
  39     the default path specified in your $HOME/.splat_path file.
  40
  41 -n: used to specify the elevation (in meters) below which SRTM data
  42     is replaced.  Below this limit, SRTM elevation data is either
  43     replaced using existing SDF equivalent files, or averaged among
  44     adjacent elevation data points.  The default threshold for the
  45     replacement limit is sea-level (0 meters).  Unless elevations
  46     below sea-level are known to exist for the region being
  47     processed by the srtm2sdf utility, the -n option need not be
  48     specified.
  49
  50 Some examples of srtm2sdf use:
  51
  52     srtm2sdf N40W074.hgt
  53
  54     srtm2sdf -d /cdrom/sdf N40W074.hgt
  55
  56     srtm2sdf -d /dev/null N40W074.hgt (/dev/null prevents USGS data
  57                 replacement from taking place)
  58
  59     srtm2sdf -n -5 N40W074.hgt
  60
  61 In all cases, SDF files are written into the current working directory.
  62
  63 The srtm2sdf utility may also be used to convert 3-arc second SRTM data
  64 in Band Interleaved by Line (.BIL) format for use with SPLAT!  This data
  65 is available via the web at: http://seamless.usgs.gov/website/seamless/
  66
  67 Once the region of the world has been selected at this site, select the
  68 "Define Download Area By Coordinates" button under "Downloads".  Proceed
  69 to request the download of the region(s) desired in 1 degree by 1 degree
  70 regions only, and make sure bounding coordinates entered fall exactly on
  71 whole numbers of latitude and longitude (no decimal fractions of a degree).
  72
  73 Select the "Add Area" button at the bottom.
  74
  75 On the next screen, select "Modify Data Request".  On the subsequent screen,
  76 de-select the National Elevation Dataset (NED) format and select "SRTM 3 arc
  77 sec - Shuttle Radar Topography Mission [Finished]".  Change the format from
  78 ArcGrid to BIL, and from HTML to TXT.
  79
  80 Select the "Save Changes and Return To Summary" button.
  81
  82 Select the "Download" button, and save the file once it has been sent to
  83 your web browser.
  84
  85 Uncompressing the file will generate a directory containing all files
  86 contained within the downloaded archive.  Move into the directory and
  87 invoke srtm2sdf as described above with the filename having the .bil
  88 extension given as its argument.  Finally, move or copy the generated
  89 .sdf file to your SPLAT! working directory.
  90
  91
  92 usgs2sdf
  93 ========
  94 The usgs2sdf utility takes as an argument the name of an uncompressed
  95 and record delimited Digital Elevation Model Data (DEM) downloaded from
  96 the US Geological Survey, and generates a SPLAT Data File (SDF) compatible
  97 with SPLAT! Software.  usgs2sdf may be invoked manually, or via the
  98 postdownload script.
  99
 100
 101 postdownload
 102 ============
 103 postdownload is a front-end to the usgs2sdf utility.  postdownload
 104 takes as an argument the name of the gzipped Digital Elevation Model
 105 (DEM) downloaded from the US Geological Survey (ie: wilmington-w.gz).
 106 postdownload uncompresses the DEM file, adds necessary record delimiters,
 107 and invokes usgs2sdf to produce a SPLAT Data File (SDF).
 108
 109 USGS Digital Elevation Models may be downloaded from:
 110
 111     http://edcftp.cr.usgs.gov/pub/data/DEM/250/
 112
 113 Invoke postdownload with the name of each DEM file downloaded to
 114 produce a database of SPLAT Data Files.
 115
 116
 117 citydecoder
 118 ===========
 119 This utility reads U.S. Census Bureau files of Incorporated Places/Census
 120 Designated Places, and generates city/site data files for use with SPLAT!
 121 software.  Files for use with this utility are available for download
 122 free of charge from:
 123
 124         http://www.census.gov/geo/www/cob/bdy_files.html.
 125
 126 Please select the ARC/INFO Ungenerate (ASCII) Metadata Cartographic Boundary
 127 Files from this site and unzip them prior to importing them to citydecoder.
 128 U.S. Census files are cataloged by the two digit FIPS code for the region
 129 (state) they represent.  citydecoder takes as an argument the two-letter
 130 file prefix plus the FIPS code of the region or state being processed.
 131 For example:
 132
 133         citydecoder pl34
 134
 135 reads files "pl34_d00.dat" and "pl34_d00a.dat" that are extracted after
 136 the downloaded file has been unzipped, and generates a list of city names
 137 and geographical coordinates for the state of New Jersey (FIPS code 34).
 138 This data may be sorted and written to a file (cities.nj.dat) in the
 139 following manner:
 140
 141         citydecoder pl34 | sort > cities.nj.dat
 142
 143 A list of FIPS codes (fips.txt) is included under splat/utils for your
 144 convenience.
 145
 146
 147 fontdata
 148 ========
 149 The fontdata utility reads Slackware gzipped console font data
 150 to create the fontdata.h file required for compilation of SPLAT!.
 151 Font data of the type needed by this utility may be found under
 152 /usr/lib/kbd/consolefonts (Slackware < 8), or under
 153 /usr/share/kbd/consolefonts (Slackware >= 8.0).
 154
 155 A default fontdata.h file is already included in with SPLAT!, and is
 156 a derivative of the s.fnt console font type available under Slackware.
 157 fontdata takes as an argument the name of the file containing the
 158 gzipped compressed console fonts:
 159
 160         fontdata s.fnt.gz
 161
 162
 163 Building The Utilities
 164 ======================
 165 Normally, these utilities are built and installed along with SPLAT!
 166 when SPLAT!'s ./configure script is invoked.  However, if you modify
 167 them and/or wish to build and install them separately, here is how it's
 168 done.  First, invoke the "build" script to compile each or all utilities
 169 in this directory by name.  For example:
 170
 171         ./build citydecoder
 172
 173 compiles citydecoder only, while
 174
 175         ./build all
 176
 177 compiles all utilities.
 178
 179
 180 Installing The Utilities
 181 ========================
 182 Invoke the "install" script to install each or all utilities in this
 183 directory by name.  For example:
 184
 185         ./install citydecoder
 186
 187 installs citydecoder only, while
 188
 189         ./install all
 190
 191 installs all utilities.
 192
 193 You need to be 'root' to install any or all of these utilities.
 194
 195 ---
 196 John A. Magliacane, KD2BD
 197 August 2007
 198