-.TH SPLAT! 1 "02 March 2006" "KD2BD Software" "KD2BD Software"
+.TH SPLAT! 1 "20 December 2006" "KD2BD Software" "KD2BD Software"
.SH NAME
splat \- An RF \fBS\fPignal \fBP\fPropagation, \fBL\fPoss, \fBA\fPnd \fBT\fPerrain analysis tool
.SH SYNOPSIS
splat [-t \fItransmitter_site.qth\fP]
-[-r \fIreceiver_site.qth\fP]
-[-c \fIrx_antenna_height_for_los_coverage_analysis (feet) (float)\fP]
-[-L \fIrx_antenna_height_for_Longley-Rice_coverage_analysis (feet) (float)\fP]
-[-p \fIterrain_profile.ext\fP]
-[-e \fIelevation_profile.ext\fP]
-[-h \fIheight_profile.ext\fP]
-[-l \fILongley-Rice_profile.ext\fP]
-[-o \fItopographic_map_filename.ppm\fP]
-[-b \fIcartographic_boundary_filename.dat\fP]
-[-s \fIsite/city_database.dat\fP]
-[-d \fIsdf_directory_path\fP]
-[-m \fIearth_radius_multiplier (float)\fP]
-[-R \fImaximum_coverage_range (for -c or -L) (miles) (float)\fP]
+[-r \fIreceiver_site.qth\fP]
+[-c \fIrx antenna height for LOS coverage analysis (feet/meters) (float)\fP]
+[-L \fIrx antenna height for Longley-Rice coverage analysis (feet/meters) (float)\fP]
+[-p \fIterrain_profile.ext\fP]
+[-e \fIelevation_profile.ext\fP]
+[-h \fIheight_profile.ext\fP]
+[-H \fInormalized_height_profile.ext\fP]
+[-l \fILongley-Rice_profile.ext\fP]
+[-o \fItopographic_map_filename.ppm\fP]
+[-b \fIcartographic_boundary_filename.dat\fP]
+[-s \fIsite/city_database.dat\fP]
+[-d \fIsdf_directory_path\fP]
+[-m \fIearth radius multiplier (float)\fP]
+[-f \fIfrequency (MHz) for Fresnel zone calculations (float)\fP]
+[-R \fImaximum coverage radius (miles/kilometers) (float)\fP]
[-dB \fImaximum attenuation contour to display on path loss maps (80-230 dB)\fP]
+[-nf \fIdo not plot Fresnel zones in height plots\fP]
+[-plo \fIpath_loss_output_file.txt\fP]
+[-pli \fIpath_loss_input_file.txt\fP]
+[-udt \fIuser_defined_terrain_file.dat\fP]
[-n]
[-N]
+[-geo]
+[-kml]
+[-metric]
.SH DESCRIPTION
\fBSPLAT!\fP is a powerful terrestrial RF propagation and terrain
-analysis tool covering the spectrum between 20 MHz and 20 GHz. It
-is designed for operation on Unix and Linux-based workstations.
-\fBSPLAT!\fP is free software. Redistribution and/or modification
+analysis tool covering the spectrum between 20 MHz and 20 GHz.
+\fBSPLAT!\fP is free software, and is designed for operation on Unix
+and Linux-based workstations. Redistribution and/or modification
is permitted under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 2 of the
License or any later version. Adoption of \fBSPLAT!\fP source code
Applications of \fBSPLAT!\fP include the visualization, design, and
link budget analysis of wireless Wide Area Networks (WANs), commercial
and amateur radio communication systems above 20 MHz, microwave links,
-frequency coordination, and the determination of analog and digital
-terrestrial radio and television contour regions.
+frequency coordination and interference studies, and the determination
+of analog and digital terrestrial radio and television contour regions.
\fBSPLAT!\fP provides RF site engineering data such as great circle
distances and bearings between sites, antenna elevation angles (uptilt),
depression angles (downtilt), antenna height above mean sea level,
antenna height above average terrain, bearings and distances to known
-obstructions, Longley-Rice path attenuation, and minimum antenna height
-requirements needed to establish line-of-sight communication paths absent
-of obstructions due to terrain. \fBSPLAT!\fP produces reports, graphs,
-and highly detailed and carefully annotated topographic maps depicting
-line-of-sight paths, path loss, and expected coverage areas of
-transmitters and repeater systems. When performing line-of-sight
-analysis in situations where multiple transmitter or repeater sites
-are employed, \fBSPLAT!\fP determines individual and mutual areas
-of coverage within the network specified.
-
-\fBSPLAT!\fP operates in two distinct modes: \fIpoint-to-point mode\fP,
-and \fIarea prediction mode\fP, and may be invoked using either
-line-of-sight (LOS) or Irregular Terrain (ITM) propagation models.
-True Earth, four-thirds Earth, or any other Earth radius may be
-specified by the user when performing line-of-sight analysis.
+obstructions, and Longley-Rice path attenuation. In addition, the minimum
+antenna height requirements needed to clear terrain, the first Fresnel
+zone, and 60% of the first Fresnel zone are also provided.
+
+\fBSPLAT!\fP produces reports, graphs, and high resolution topographic
+maps that depict line-of-sight paths, and regional path loss contours
+through which expected coverage areas of transmitters and repeater
+systems can be obtained. When performing line-of-sight analysis in
+situations where multiple transmitter or repeater sites are employed,
+\fBSPLAT!\fP determines individual and mutual areas of coverage within
+the network specified.
+
+Simply typing \fCsplat\fR on the command line will return a summary
+of \fBSPLAT!\fP's command line options:
+\fC
+ --==[ SPLAT! v1.2.0 Available Options... ]==--
+
+ -t txsite(s).qth (max of 4)
+ -r rxsite.qth
+ -c plot coverage of TX(s) with an RX antenna at X feet/meters AGL
+ -L plot path loss map of TX based on an RX at X feet/meters AGL
+ -s filename(s) of city/site file(s) to import (max of 5)
+ -b filename(s) of cartographic boundary file(s) to import (5 max)
+ -p filename of terrain profile graph to plot
+ -e filename of terrain elevation graph to plot
+ -h filename of terrain height graph to plot
+ -H filename of normalized terrain height graph to plot
+ -l filename of Longley-Rice graph to plot
+ -o filename of topographic map to generate (.ppm)
+ -u filename of user-defined terrain file to import
+ -d sdf file directory path (overrides path in ~/.splat_path file)
+ -n no analysis, brief report
+ -N no analysis, no report
+ -m earth radius multiplier
+ -f frequency for Fresnel zone calculation (MHz)
+ -R modify default range for -c or -L (miles/kilometers)
+ -db maximum loss contour to display on path loss maps (80-230 dB)
+ -nf do not plot Fresnel zones in height plots
+ -plo filename of path-loss output file
+ -pli filename of path-loss input file
+ -udt filename of user defined terrain input file
+ -geo generate a .geo georeference file (with .ppm output)
+ -kml generate a Google Earth .kml file (for point-to-point links)
+ -metric employ metric rather than imperial units for all user I/O
+\fR
.SH INPUT FILES
\fBSPLAT!\fP is a command-line driven application, and reads input
data through a number of data files. Some files are mandatory for
successful execution of the program, while others are optional.
-Mandatory files include SPLAT Data Files (SDF files), site location
-files (QTH files), and Longley-Rice model parameter files (LRP files).
-Optional files include city/site location files, and cartographic
-boundary files.
+Mandatory files include 3-arc second topography models in the
+form of SPLAT Data Files (SDF files), site location files (QTH
+files), and Longley-Rice model parameter files (LRP files).
+Optional files include city location files, cartographic boundary
+files, user-defined terrain files, path-loss input files, and
+antenna radiation pattern files.
.SH SPLAT DATA FILES
\fBSPLAT!\fP imports topographic data in the form of SPLAT Data Files
(SDFs). These files may be generated from a number of information sources.
compatible with this utility may be downloaded from:
\fIhttp://edcftp.cr.usgs.gov/pub/data/DEM/250/\fP.
-Significantly better resolution can be obtained through the use
-of SRTM-3 Version 2 digital elevation models. These models are the
-result of the STS-99 Space Shuttle Radar Topography Mission, and are
+Significantly better resolution and accuracy can be obtained through
+the use of SRTM-3 Version 2 digital elevation models. These models are
+the product of the STS-99 Space Shuttle Radar Topography Mission, and are
available for most populated regions of the Earth. SPLAT Data Files
may be generated from SRTM data using the included \fBsrtm2sdf\fP utility.
SRTM-3 Version 2 data may be obtained through anonymous FTP from:
and \fBsrtm2sdf\fP utilities, or in bzip2 compressed format
(\fI.sdf.bz2\fP). Since uncompressed files can be processed slightly
faster than files that have been compressed, \fBSPLAT!\fP searches for
-the needed SDF data in uncompressed format first. If uncompressed data
-cannot located, \fBSPLAT!\fP then searches for data in bzip2 compressed
+needed SDF data in uncompressed format first. If uncompressed data
+cannot be located, \fBSPLAT!\fP then searches for data in bzip2 compressed
format. If no compressed SDF files can be found for the region requested,
\fBSPLAT!\fP assumes the region is over water, and will assign an
elevation of sea-level to these areas.
This feature of \fBSPLAT!\fP makes it possible to perform path analysis
not only over land, but also between coastal areas not represented by
-Digital Elevation Model data. This behavior of \fBSPLAT!\fP underscores
-the importance of having all the SDF files required for the region being
-analyzed if meaningful results are to be expected.
+Digital Elevation Model data. However, this behavior of \fBSPLAT!\fP
+underscores the importance of having all the SDF files required for
+the region being analyzed if meaningful results are to be expected.
.SH SITE LOCATION (QTH) FILES
\fBSPLAT!\fP imports site location information of transmitter and receiver
sites analyzed by the program from ASCII files having a \fI.qth\fP extension.
QTH files contain the site's name, the site's latitude (positive if North
of the equator, negative if South), the site's longitude (in degrees West,
-0 to 360 degrees), and the site's antenna height above ground level (AGL).
-A single line-feed character separates each field. The antenna height is
+0 to 360 degrees), and the site's antenna height above ground level (AGL),
+each separated by a single line-feed character. The antenna height is
assumed to be specified in feet unless followed by the letter \fIm\fP or
the word \fImeters\fP in either upper or lower case. Latitude and
longitude information may be expressed in either decimal format (74.6889)
Each transmitter and receiver site analyzed by \fBSPLAT!\fP must be
represented by its own site location (QTH) file.
.SH LONGLEY-RICE PARAMETER (LRP) FILES
-\fBSPLAT!\fP imports Longley-Rice model parameter data from files having
-the same base name as the transmitter site QTH file, but with a \fI.lrp\fP
-extension, thus providing simple and accurate correlation between these
-associated data sets. The format for the Longley-Rice model parameter
-files is as follows (\fIwnjt.lrp\fP):
+Longley-Rice parameter data files are required for \fBSPLAT!\fP to
+determine RF path loss in either point-to-point or area prediction
+mode. Longley-Rice model parameter data is read from files having
+the same base name as the transmitter site QTH file, but with a
+\fI.lrp\fP extension. \fBSPLAT!\fP LRP files share the following
+format (\fIwnjt.lrp\fP):
\fC
15.000 ; Earth Dielectric Constant (Relative permittivity)
0.005 ; Earth Conductivity (Siemens per meter)
The final two parameters in the \fI.lrp\fP file correspond to the statistical
analysis provided by the Longley-Rice model. In this example, \fBSPLAT!\fP
will return the maximum path loss occurring 50% of the time (fraction
-of time) in 50% of situations (fraction of situations). Use a fraction
-of time parameter of 0.97 for digital television, 0.50 for analog in the
-United States. Isotropic antennas are assumed.
+of time) in 50% of situations (fraction of situations). In the United
+States, use a fraction of time parameter of 0.97 for digital television
+(8VSB modulation), or 0.50 for analog (VSB-AM+NTSC) transmissions.
For further information on these parameters, see:
\fIhttp://flattop.its.bldrdoc.gov/itm.html\fP and
The names and locations of cities, tower sites, or other points of interest
may be imported and plotted on topographic maps generated by \fBSPLAT!\fP.
\fBSPLAT!\fP imports the names of cities and locations from ASCII files
-containing the location's name, the location's latitude, and the location's
-longitude. Each field is separated by a comma. Each record is separated
-by a single line feed character. As was the case with the \fI.qth\fP
+containing the location of interest's name, latitude, and longitude.
+Each field is separated by a comma. Each record is separated by a
+single line feed character. As was the case with the \fI.qth\fP
files, latitude and longitude information may be entered in either
decimal or degree, minute, second (DMS) format.
and there is no limit to the size of these files. \fBSPLAT!\fP reads
city data on a "first come/first served" basis, and plots only those
locations whose annotations do not conflict with annotations of
-locations plotted earlier during \fBSPLAT\fP's execution. This behavior
-minimizes clutter in \fBSPLAT!\fP generated topographic maps, but also
-mandates that important locations be placed toward the beginning of
-the first city data file, and disposable locations be positioned
-further down the list or in subsequent data files.
+locations read earlier in the current city data file, or in previous
+files. This behavior minimizes clutter in \fBSPLAT!\fP generated
+topographic maps, but also mandates that important locations be placed
+toward the beginning of the first city data file, and locations less
+important be positioned further down the list or in subsequent data
+files.
City data files may be generated manually using any text editor,
imported from other sources, or derived from data available from the
mode of operation and method of output data generation. Nearly all
of \fBSPLAT!\fP's switches may be cascaded in any order on the command
line when invoking the program.
+
+\fBSPLAT!\fP operates in two distinct modes: \fIpoint-to-point mode\fP,
+and \fIarea prediction mode\fP. Either a line-of-sight (LOS) or Longley-Rice
+Irregular Terrain (ITM) propagation model may be invoked by the user. True
+Earth, four-thirds Earth, or any other user-defined Earth radius may be
+specified when performing line-of-sight analysis.
.SH POINT-TO-POINT ANALYSIS
\fBSPLAT!\fP may be used to perform line-of-sight terrain analysis
between two specified site locations. For example:
\fCsplat -t tx_site.qth -r rx_site.qth\fR
-invokes a terrain analysis between the transmitter specified
-in \fItx_site.qth\fP and receiver specified in \fIrx_site.qth\fP,
-and writes a \fBSPLAT!\fP Obstruction Report to the current working
-directory. The report contains details of the transmitter and
-receiver sites, and identifies the location of any obstructions
-detected during the analysis. If an obstruction can be cleared
-by raising the receive antenna to a greater altitude, \fBSPLAT!\fP
-will indicate the minimum antenna height required for a line-of-sight
-path to exist between the transmitter and receiver locations specified.
+invokes a line-of-sight terrain analysis between the transmitter
+specified in \fItx_site.qth\fP and receiver specified in \fIrx_site.qth\fP
+using a True Earth radius model, and writes a \fBSPLAT!\fP Obstruction
+Report to the current working directory. The report contains details of
+the transmitter and receiver sites, and identifies the location of any
+obstructions detected along the line-of-sight path. If an obstruction
+can be cleared by raising the receive antenna to a greater altitude,
+\fBSPLAT!\fP will indicate the minimum antenna height required for a
+line-of-sight path to exist between the transmitter and receiver locations
+specified. Note that imperial units (miles, feet) are specified unless
+the \fI-metric\fP switch is added to \fBSPLAT!\fP's command line options:
+
+\fCsplat -t tx_site.qth -r rx_site.qth -metric\fR
+
If the antenna must be raised a significant amount, this determination
-may take some time. Note that the results provided are the \fIminimum\fP
-necessary for a line-of-sight path to exist, and do not take Fresnel
-zone clearance requirements into consideration.
+may take a few moments. Note that the results provided are the \fIminimum\fP
+necessary for a line-of-sight path to exist, and in the case of this
+simple example, do not take Fresnel zone clearance requirements into
+consideration.
\fIqth\fP extensions are assumed by \fBSPLAT!\fP for QTH files, and
-are optional when invoking the program. \fBSPLAT!\fP automatically
-reads all SPLAT Data Files necessary to conduct the terrain analysis
-between the sites specified. \fBSPLAT!\fP searches for the needed
-SDF files in the current working directory first. If the needed
-files are not found, \fBSPLAT!\fP then searches in the path specified
-by the \fI-d\fP command-line switch:
+are optional when specifying -t and -r arguments on the command-line.
+\fBSPLAT!\fP automatically reads all SPLAT Data Files necessary to
+conduct the terrain analysis between the sites specified. \fBSPLAT!\fP
+searches for the required SDF files in the current working directory
+first. If the needed files are not found, \fBSPLAT!\fP then searches
+in the path specified by the \fI-d\fP command-line switch:
\fCsplat -t tx_site -r rx_site -d /cdrom/sdf/\fR
An external directory path may be specified by placing a ".splat_path"
file under the user's home directory. This file must contain the full
-directory path to the last resort location of all the SDF files. The
-path in the \fI$HOME/.splat_path\fP file must be of the form of a
-single line of ASCII text:
+directory path of last resort to all the SDF files. The path in the
+\fI$HOME/.splat_path\fP file must be of the form of a single line of
+ASCII text:
\fC/opt/splat/sdf/\fR
locations as a function of distance from the receiver can be generated
by adding the \fI-p\fP switch:
-\fCsplat -t tx_site -r rx_site -p terrain_profile.gif\fR
+\fCsplat -t tx_site -r rx_site -p terrain_profile.png\fR
\fBSPLAT!\fP invokes \fBgnuplot\fP when generating graphs. The filename
extension specified to \fBSPLAT!\fP determines the format of the graph
-produced. \fI.gif\fP will produce a 640x480 color GIF graphic file,
+produced. \fI.png\fP will produce a 640x480 color PNG graphic file,
while \fI.ps\fP or \fI.postscript\fP will produce postscript output.
-Output in formats such as PNG, Adobe Illustrator, AutoCAD dxf, LaTeX,
-and many others are available. Please consult \fBgnuplot\fP, and
-\fBgnuplot\fP's documentation for details on all the supported
+Output in formats such as GIF, Adobe Illustrator, AutoCAD dxf,
+LaTeX, and many others are available. Please consult \fBgnuplot\fP,
+and \fBgnuplot\fP's documentation for details on all the supported
output formats.
A graph of elevations subtended by the terrain between the receiver and
transmitter as a function of distance from the receiver can be generated
by using the \fI-e\fP switch:
-\fCsplat -t tx_site -r rx_site -e elevation_profile.gif\fR
+\fCsplat -t tx_site -r rx_site -e elevation_profile.png\fR
The graph produced using this switch illustrates the elevation and
depression angles resulting from the terrain between the receiver's
path between the transmitter and receiver may be generated using
the \fI-h\fP switch:
-\fCsplat -t tx_site -r rx_site -h height_profile.gif\fR
+\fCsplat -t tx_site -r rx_site -h height_profile.png\fR
+
+A terrain height plot normalized to the transmitter and receiver
+antenna heights can be obtained using the \fI-H\fP switch:
+
+\fCsplat -t tx_site -r rx_site -H normalized_height_profile.png\fR
-The Earth's curvature is clearly evident when plotting height profiles.
+A contour of the Earth's curvature is also plotted in this mode.
+
+The first Fresnel Zone, and 60% of the first Fresnel Zone can be
+added to height profile graphs by adding the \fI-f\fP switch, and
+specifying a frequency (in MHz) at which the Fresnel Zone should be
+modeled:
+
+\fCsplat -t tx_site -r rx_site -f 439.250 -H normalized_height_profile.png\fR
A graph showing Longley-Rice path loss may be plotted using the
\fI-l\fP switch:
-\fCsplat -t tx_site -r rx_site -l path_loss_profile.gif\fR
+\fCsplat -t tx_site -r rx_site -l path_loss_profile.png\fR
+
+As before, adding the \fI-metric\fP switch forces the graphs to
+be plotted using metric units of measure.
When performing path loss profiles, a Longley-Rice Model Path Loss
Report is generated by \fBSPLAT!\fP in the form of a text file with
SNR = T - NJ - L + G - NF
.EN
-where \fBT\fP is the ERP of the transmitter in dBW, \fBNJ\fP is
-Johnson Noise in dBW (-136 dBW for a 6 MHz TV channel), \fBL\fP
-is the path loss provided by \fBSPLAT!\fP in dB (as a \fIpositive\fP
-number), \fBG\fP is the receive antenna gain in dB over isotropic,
-and \fBNF\fP is the receiver noise figure in dB.
+where \fBT\fP is the ERP of the transmitter in dBW in the direction
+of the receiver, \fBNJ\fP is Johnson Noise in dBW (-136 dBW for a 6 MHz
+television channel), \fBL\fP is the path loss provided by \fBSPLAT!\fP
+in dB (as a \fIpositive\fP number), \fBG\fP is the receive antenna gain
+in dB over isotropic, and \fBNF\fP is the receiver noise figure in dB.
\fBT\fP may be computed as follows:
Signal_Margin = SNR - S
.EN
-where \fBS\fP is the minimum desired SNR ratio (15.5 dB for
-ATSC DTV, 42 dB for analog NTSC television).
+where \fBS\fP is the minimum required SNR ratio (15.5 dB for
+ATSC (8-VSB) DTV, 42 dB for analog NTSC television).
A topographic map may be generated by \fBSPLAT!\fP to visualize the
path between the transmitter and receiver sites from yet another
in the map. The only exception to this is sea-level, which is
represented using the color blue.
-\fBSPLAT!\fP generated topographic maps are 24-bit TrueColor Portable
-PixMap (PPM) images. They may be viewed, edited, or converted to other
-graphic formats by popular image viewing applications such as \fBxv\fP,
-\fBThe GIMP\fP, \fBImageMagick\fP, and \fBXPaint\fP. PNG format is
-highly recommended for lossless compressed storage of \fBSPLAT!\fP
-generated topographic output files. An excellent command-line utility
-capable of converting \fBSPLAT!\fP PPM graphic files to PNG files is
-\fBwpng\fP, and is available
-at: \fIhttp://www.libpng.org/pub/png/book/sources.html\fP. As a last
-resort, PPM files may be compressed using the bzip2 utility, and read
-directly by \fBThe GIMP\fP in this format. Topographic output
-is specified using the \fI-o\fP switch:
+Topographic output is invoked using the \fI-o\fP switch:
\fCsplat -t tx_site -r rx_site -o topo_map.ppm\fR
In situations where multiple transmitter sites are in use, as many as
four site locations may be passed to \fBSPLAT!\fP at a time for analysis:
-\fCsplat -t tx_site1 tx_site2 tx_site3 tx_site4 -r rx_site -p profile.gif\fR
+\fCsplat -t tx_site1 tx_site2 tx_site3 tx_site4 -r rx_site -p profile.png\fR
In this example, four separate terrain profiles and obstruction reports
will be generated by \fBSPLAT!\fP. A single topographic map can be
specified to the receiver will be in green, the path between the
second transmitter and the receiver will be in cyan, the path between
the third transmitter and the receiver will be in violet, and the
-path between the fourth transmitter and the receiver will be in sienna.
-.SH DETERMINING REGIONAL COVERAGE
+path between the fourth transmitter and the receiver will be in sienna.
+
+\fBSPLAT!\fP generated topographic maps are 24-bit TrueColor Portable
+PixMap (PPM) images. They may be viewed, edited, or converted to other
+graphic formats by popular image viewing applications such as \fBxv\fP,
+\fBThe GIMP\fP, \fBImageMagick\fP, and \fBXPaint\fP. PNG format is
+highly recommended for lossless compressed storage of \fBSPLAT!\fP
+generated topographic output files. \fBImageMagick\fP's command-line
+utility easily converts \fBSPLAT!\fP's PPM files to PNG format:
+
+\fCconvert splat_map.ppm splat_map.png\fR
+
+Another excellent PPM to PNG command-line utility is available
+at: \fIhttp://www.libpng.org/pub/png/book/sources.html\fP. As a last
+resort, PPM files may be compressed using the bzip2 utility, and read
+directly by \fBThe GIMP\fP in this format.
+.SH REGIONAL COVERAGE ANALYSIS
\fBSPLAT!\fP can analyze a transmitter or repeater site, or network
of sites, and predict the regional coverage for each site specified.
In this mode, \fBSPLAT!\fP can generate a topographic map displaying
In this example, \fBSPLAT!\fP generates a topographic map called
\fItx_coverage.ppm\fP that illustrates the predicted line-of-sight
regional coverage of \fItx_site\fP to receiving locations having
-antennas 30.0 feet above ground level (AGL). The contents of
-\fIcities.dat\fP are plotted on the map, as are the cartographic
+antennas 30.0 feet above ground level (AGL). If the \fI-metric\fP
+switch is used, the argument following the \fI-c\fP switch is
+interpreted as being in meters, rather than in feet. The contents
+of \fIcities.dat\fP are plotted on the map, as are the cartographic
boundaries contained in the file \fIco34_d00.dat\fP.
When plotting line-of-sight paths and areas of regional coverage,
antenna's height above average terrain, and the height of the
average terrain calculated in the directions of 0, 45, 90, 135,
180, 225, 270, and 315 degrees azimuth.
-
-If the \fI-c\fP switch is replaced by a \fI-L\fP switch, a
-Longley-Rice path loss map for a transmitter site may be generated:
-
-\fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -o path_loss_map\fR
-
-In this mode, \fBSPLAT!\fP generates a multi-color map illustrating
-expected signal levels (path loss) in areas surrounding the transmitter
-site. A legend at the bottom of the map correlates each color with a
-specific path loss level in decibels. Since Longley-Rice area
-prediction map generation is very CPU intensive, provision for
-limiting the analysis range is provided by the \fI-R\fP switch.
-The argument must be given in miles. If a range wider than the
-generated topographic map is specified, \fBSPLAT!\fP will perform
-Longley-Rice path loss calculations between all four corners of
-the area prediction map.
-
-The \fI-db\fP switch allows a constraint to be placed on the maximum
-path loss region plotted on the map. A path loss between 80 and
-230 dB may be specified using this switch. For example, if a path
-loss beyond -140 dB is irrelevant to the survey being conducted,
-\fBSPLAT!\fP's path loss plot can be constrained to the region
-bounded by the 140 dB attenuation contour as follows:
-
-\fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -db 140 -o plot.ppm\fR
-
-.SH DETERMINING MULTIPLE REGIONS OF COVERAGE
+.SH DETERMINING MULTIPLE REGIONS OF LOS COVERAGE
\fBSPLAT!\fP can also display line-of-sight coverage areas for as
many as four separate transmitter sites on a common topographic map.
For example:
-\fCsplat -t site1 site2 site3 site4 -c 30.0 -o network.ppm\fR
+\fCsplat -t site1 site2 site3 site4 -c 10.0 -metric -o network.ppm\fR
plots the regional line-of-sight coverage of site1, site2, site3,
-and site4 based on a receive antenna located 30.0 feet above ground
+and site4 based on a receive antenna located 10.0 meters above ground
level. A topographic map is then written to the file \fInetwork.ppm\fP.
The line-of-sight coverage area of the transmitters are plotted as
follows in the colors indicated (along with their corresponding RGB
If separate \fI.qth\fP files are generated, each representing a common
site location but a different antenna height, a single topographic map
illustrating the regional coverage from as many as four separate locations
-on a single tower may be generated by \fBSPLAT!\fP.
-.SH TOPOGRAPHIC MAP GENERATION
-In certain situations, it may be desirable to generate a topographic map
+on a single tower may be generated by \fBSPLAT!\fP.
+.SH LONGLEY-RICE PATH LOSS ANALYSIS
+If the \fI-c\fP switch is replaced by a \fI-L\fP switch, a
+Longley-Rice path loss map for a transmitter site may be generated:
+
+\fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -o path_loss_map\fR
+
+In this mode, \fBSPLAT!\fP generates a multi-color map illustrating
+expected signal levels (path loss) in areas surrounding the transmitter
+site. A legend at the bottom of the map correlates each color with a
+specific path loss range in decibels.
+
+The Longley-Rice analysis range may be modified to a user-specific
+value using the \fI-R\fP switch. The argument must be given in miles
+(or kilometers if the \fI-metric\fP switch is used). If a range wider
+than the generated topographic map is specified, \fBSPLAT!\fP will
+perform Longley-Rice path loss calculations between all four corners
+of the area prediction map.
+
+The \fI-db\fP switch allows a constraint to be placed on the maximum
+path loss region plotted on the map. A maximum path loss between 80
+and 230 dB may be specified using this switch. For example, if a path
+loss beyond -140 dB is irrelevant to the survey being conducted,
+\fBSPLAT!\fP's path loss plot can be constrained to the region
+bounded by the 140 dB attenuation contour as follows:
+
+\fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -db 140 -o plot.ppm\fR
+
+.SH ANTENNA RADIATION PATTERN PARAMETERS
+Normalized field voltage patterns for a transmitting antenna's horizontal
+and vertical planes are imported automatically into \fBSPLAT!\fP when a
+Longley-Rice coverage analysis is performed. Antenna pattern data is
+read from a pair of files having the same base name as the transmitter
+and LRP files, but with \fI.az\fP and \fI.el\fP extensions for azimuth
+and elevation pattern files, respectively. Specifications regarding
+pattern rotation (if any) and mechanical beam tilt and tilt direction
+(if any) are also contained within \fBSPLAT!\fP antenna pattern files.
+
+For example, the first few lines of a \fBSPLAT!\fP azimuth pattern file
+might appear as follows (\fIkvea.az\fP):
+\fC
+ 183.0
+ 0 0.8950590
+ 1 0.8966406
+ 2 0.8981447
+ 3 0.8995795
+ 4 0.9009535
+ 5 0.9022749
+ 6 0.9035517
+ 7 0.9047923
+ 8 0.9060051
+\fR
+The first line of the \fI.az\fP file specifies the amount of azimuthal
+pattern rotation (measured clockwise in degrees from True North) to be
+applied by \fBSPLAT!\fP to the data contained in the \fI.az\fP file.
+This is followed by azimuth headings (0 to 360 degrees) and their associated
+normalized field patterns (0.000 to 1.000) separated by whitespace.
+
+The structure of \fBSPLAT!\fP elevation pattern files is slightly different.
+The first line of the \fI.el\fP file specifies the amount of mechanical
+beam tilt applied to the antenna. Note that a \fIdownward tilt\fP
+(below the horizon) is expressed as a \fIpositive angle\fP, while an
+\fIupward tilt\fP (above the horizon) is expressed as a \fInegative angle\fP.
+This data is followed by the azimuthal direction of the tilt, separated by
+whitespace.
+
+The remainder of the file consists of elevation angles and their
+corresponding normalized voltage radiation pattern (0.000 to 1.000)
+values separated by whitespace. Elevation angles must be specified
+over a -10.0 to +90.0 degree range. As was the convention with mechanical
+beamtilt, \fInegative elevation angles\fP are used to represent elevations
+\fIabove the horizon\fP, while \fIpositive angles\fP represents elevations
+\fIbelow the horizon\fP.
+
+For example, the first few lines a \fBSPLAT!\fP elevation pattern file
+might appear as follows (\fIkvea.el\fP):
+\fC
+ 1.1 130.0
+ -10.0 0.172
+ -9.5 0.109
+ -9.0 0.115
+ -8.5 0.155
+ -8.0 0.157
+ -7.5 0.104
+ -7.0 0.029
+ -6.5 0.109
+ -6.0 0.185
+\fR
+In this example, the antenna is mechanically tilted downward 1.1 degrees
+towards an azimuth of 130.0 degrees.
+
+For best results, the resolution of azimuth pattern data should be
+specified to the nearest degree azimuth, and elevation pattern data
+resolution should be specified to the nearest 0.01 degrees. If the
+pattern data specified does not reach this level of resolution,
+\fBSPLAT!\fP will interpolate the values provided to determine the
+data at the required resolution, although this may result in a loss
+in accuracy.
+
+.SH IMPORTING AND EXPORTING REGIONAL PATH LOSS CONTOUR DATA
+Performing a Longley-Rice coverage analysis can be a very time
+consuming process, especially if the analysis is repeated repeatedly
+to discover what effects changes to the antenna radiation patterns
+make to the predicted coverage area.
+
+This process can be expedited by exporting the Longley-Rice
+regional path loss contour data to an output file, modifying the
+path loss data externally to incorporate antenna pattern effects,
+and then importing the modified path loss data back into \fBSPLAT!\fP
+to rapidly produce a revised path loss map.
+
+For example, a path loss output file can be generated by \fBSPLAT!\fP
+for a receive site 30 feet above ground level over a 50 mile radius
+surrounding a transmitter site to a maximum path loss of 140 dB using
+the following syntax:
+
+\fCsplat -t kvea -L 30.0 -R 50.0 -db 140 -plo pathloss.dat\fR
+
+\fBSPLAT!\fP path loss output files often exceed 100 megabytes in size.
+They contain information relating to the boundaries of region they describe
+followed by latitudes (degrees North), longitudes (degrees West), azimuths,
+elevations (to the first obstruction), and path loss figures (dB) for a
+series of specific points that comprise the region surrounding the
+transmitter site. The first few lines of a \fBSPLAT!\fP path loss
+output file take on the following appearance (\fIpathloss.dat\fP):
+\fC
+ 119, 117 ; max_west, min_west
+ 35, 33 ; max_north, min_north
+ 34.2265434, 118.0631104, 48.171, -37.461, 67.70
+ 34.2270355, 118.0624390, 48.262, -26.212, 73.72
+ 34.2280197, 118.0611038, 48.269, -14.951, 79.74
+ 34.2285156, 118.0604401, 48.207, -11.351, 81.68
+ 34.2290077, 118.0597687, 48.240, -10.518, 83.26
+ 34.2294998, 118.0591049, 48.225, 23.201, 84.60
+ 34.2304878, 118.0577698, 48.213, 15.769, 137.84
+ 34.2309799, 118.0570984, 48.234, 15.965, 151.54
+ 34.2314720, 118.0564346, 48.224, 16.520, 149.45
+ 34.2319679, 118.0557632, 48.223, 15.588, 151.61
+ 34.2329521, 118.0544281, 48.230, 13.889, 135.45
+ 34.2334442, 118.0537643, 48.223, 11.693, 137.37
+ 34.2339401, 118.0530930, 48.222, 14.050, 126.32
+ 34.2344322, 118.0524292, 48.216, 16.274, 156.28
+ 34.2354164, 118.0510941, 48.222, 15.058, 152.65
+ 34.2359123, 118.0504227, 48.221, 16.215, 158.57
+ 34.2364044, 118.0497589, 48.216, 15.024, 157.30
+ 34.2368965, 118.0490875, 48.225, 17.184, 156.36
+\fR
+It is not uncommon for \fBSPLAT!\fP path loss files to contain as
+many as 3 million or more lines of data. Comments can be placed in
+the file if they are proceeded by a semicolon character. The \fBvim\fP
+text editor has proven capable of editing files of this size.
+
+Note as was the case in the antenna pattern files, negative elevation
+angles refer to upward tilt (above the horizon), while positive angles
+refer to downward tilt (below the horizon). These angles refer to the
+elevation to the receiving antenna at the height above ground level
+specified using the \fI-L\fP switch \fIif\fP the path between transmitter
+and receiver is unobstructed. If the path between the transmitter
+and receiver is obstructed, then the elevation angle to the first
+obstruction is returned by \fBSPLAT!\fP. This is because
+the Longley-Rice model considers the energy reaching a distant point
+over an obstructed path as a derivative of the energy scattered from
+the top of the first obstruction, only. Since energy cannot reach
+the obstructed location directly, the actual elevation angle to that
+point is irrelevant.
+
+When modifying \fBSPLAT!\fP path loss files to reflect antenna
+pattern data, \fIonly the last column (path loss)\fP should be amended
+to reflect the antenna's normalized gain at the azimuth and elevation
+angles specified in the file. (At this time, programs and scripts
+capable of performing this operation are left as an exercise for
+the user.)
+
+Modified path loss maps can be imported back into \fBSPLAT!\fP for
+generating revised coverage maps:
+
+\fCsplat -t kvea -pli pathloss.dat -s city.dat -b county.dat -o map.ppm\fR
+
+\fBSPLAT!\fP path loss files can also be used for conducting coverage or
+interference studies outside of \fBSPLAT!\fP.
+.SH USER-DEFINED TERRAIN INPUT FILES
+A user-defined terrain file is a user-generated text file containing latitudes,
+longitudes, and heights above ground level of specific terrain features believed
+to be of importance to the \fBSPLAT!\fP analysis being conducted, but noticeably
+absent from the SDF files being used. A user-defined terrain file is imported
+into a \fBSPLAT!\fP analysis using the \fI-udt\fP switch:
+
+\fC splat -t tx_site -r rx_site -udt udt_file.txt -o map.ppm\fR
+
+A user-defined terrain file has the following appearance and structure:
+\fC
+ 40.32180556, 74.1325, 100.0 meters
+ 40.321805, 74.1315, 300.0
+ 40.3218055, 74.1305, 100.0 meters
+\fR
+Terrain height is interpreted as being described in feet above ground
+level unless followed by the word \fImeters\fP, and is added \fIon top of\fP
+the terrain specified in the SDF data for the locations specified. Be
+aware that each user-defined terrain feature specified will be interpreted
+as being 3-arc seconds in both latitude and longitude. Features described
+in the user-defined terrain file that overlap previously defined features
+in the file are ignored by \fBSPLAT!\fP.
+.SH SIMPLE TOPOGRAPHIC MAP GENERATION
+In certain situations it may be desirable to generate a topographic map
of a region without plotting coverage areas, line-of-sight paths, or
generating obstruction reports. There are several ways of doing this.
If one wishes to generate a topographic map illustrating the location
\fCsplat -t tx_site -r rx_site -N -o topo_map.ppm\fR
-If the \fI-o\fP switch and output filename are omitted when using
-either the \fI-n\fP or \fI-N\fP switches, output is written to a
-file named \fImap.ppm\fP in the current working directory by default.
+If a topographic map centered about a single site out to a minimum
+specified radius is desired instead, a command similar to the following
+can be used:
+
+\fCsplat -t tx_site -R 50.0 -s NJ_Cities -b NJ_Counties -o topo_map.ppm\fR
+
+where -R specifies the minimum radius of the map in miles (or kilometers
+if the \fI-metric\fP switch is used).
+
+If the \fI-o\fP switch and output filename are omitted in these
+operations, topographic output is written to a file named \fImap.ppm\fP
+in the current working directory by default.
+.SH GEOREFERENCE FILE GENERATION
+Topographic, coverage (\fI-c\fP), and path loss contour (\fI-L\fP) maps
+generated by \fBSPLAT!\fP may be imported into \fBXastir\fP (X Amateur
+Station Tracking and Information Reporting) software by generating a
+georeference file using \fBSPLAT!\fP's \fI-geo\fP switch:
+
+\fCsplat -t kd2bd -R 50.0 -s NJ_Cities -b NJ_Counties -geo -o map.ppm\fR
+
+The georeference file generated will have the same base name as the
+\fI-o\fP file specified, but have a \fI .geo\fP extension, and permit
+proper interpretation and display of \fBSPLAT!\fP's .ppm graphics in
+\fBXastir\fP software.
+.SH GOOGLE MAP KML FILE GENERATION
+Keyhole Markup Language files compatible with \fBGoogle Earth\fP may
+be generated by \fBSPLAT!\fP when performing point-to-point analyses
+by invoking the \fI-kml\fP switch:
+
+\fCsplat -t wnjt -r kd2bd -kml\fR
+
+The KML file generated will have the same filename structure as an
+Obstruction Report for the transmitter and receiver site names given,
+except it will carry a \fI .kml\fP extension.
+
+Once loaded into \fBGoogle Earth\fP (File --> Open), the KML file
+will annotate the map display with the names of the transmitter and
+receiver site locations. The viewpoint of the image will be from the
+position of the transmitter site looking towards the location of the
+receiver. The point-to-point path between the sites will be displayed
+as a white line while the RF line-of-sight path will be displayed in
+green. \fBGoogle Earth\fP's navigation tools allow the user to
+"fly" around the path, identify landmarks, roads, and other
+featured content.
.SH DETERMINATION OF ANTENNA HEIGHT ABOVE AVERAGE TERRAIN
\fBSPLAT!\fP determines antenna height above average terrain (HAAT)
according to the procedure defined by Federal Communications Commission
starting with True North. If one or more radials lie entirely over water
or over land outside the United States (areas for which no USGS topography
data is available), then those radials are omitted from the calculation
-of average terrain. If part of a radial extends over a body of water or
-over land outside the United States, then only that part of the radial
-lying over United States land is used in the determination of average
-terrain.
+of average terrain.
Note that SRTM elevation data, unlike older 3-arc second USGS data,
extends beyond the borders of the United States. Therefore, HAAT
Under such conditions, \fBSPLAT!\fP will provide the antenna height
above average terrain as well as the average terrain above mean sea
level for azimuths of 0, 45, 90, 135, 180, 225, 270, and 315 degrees,
-and include such information in the site report generated. If one or
+and include such information in the generated site report. If one or
more of the eight radials surveyed fall over water, or over regions
for which no SDF data is available, \fBSPLAT!\fP reports \fINo Terrain\fP
for the radial paths affected.
.SH RESTRICTING THE MAXIMUM SIZE OF AN ANALYSIS REGION
-\fBSPLAT!\fP reads SDF files as needed into a series of memory "slots"
-within the structure of the program. Each "slot" holds one SDF file
-representing a one degree by one degree region of terrain.
+\fBSPLAT!\fP reads SDF files as needed into a series of memory pages
+or "slots" within the structure of the program. Each "slot" holds one
+SDF file representing a one degree by one degree region of terrain.
A \fI#define MAXSLOTS\fP statement in the first several lines of
-\fIsplat.cpp\fP sets the maximum number of "slots" available for topography
-data. It also sets the maximum size of the topographic maps generated by
-\fBSPLAT!\fP. MAXSLOTS is set to 9 by default. If \fBSPLAT!\fP produces
-a segmentation fault on start-up with this default, it is an indication
+\fIsplat.cpp\fP sets the maximum number of "slots" available for holding
+topography data. It also sets the maximum size of the topographic maps
+generated by \fBSPLAT!\fP. MAXSLOTS is set to 9 by default. If \fBSPLAT!\fP
+produces a segmentation fault on start-up with this default, it is an indication
that not enough RAM and/or virtual memory (swap space) is available to
-run \fBSPLAT!\fP with this number of MAXSLOTS. In situations where
+run \fBSPLAT!\fP with the number of MAXSLOTS specified. In situations where
available memory is low, MAXSLOTS may be reduced to 4 with the understanding
that this will greatly limit the maximum region \fBSPLAT!\fP will be able
to analyze. If 118 megabytes or more of total memory (swap space plus
for single antenna heights in excess of 10,000 feet above mean sea
level, or point-to-point distances of over 1000 miles.
.SH ADDITIONAL INFORMATION
-Invoking \fBSPLAT!\fP without any arguments will display all the
-command-line options available with the program along with a brief
-summary of each.
-
The latest news and information regarding \fBSPLAT!\fP software is
available through the official \fBSPLAT!\fP software web page located
at: \fIhttp://www.qsl.net/kd2bd/splat.html\fP.
.TP
Doug McDonald <\fImcdonald@scs.uiuc.edu\fP>
Longley-Rice Model integration
+.TP
+Ron Bentley <\fIronbentley@earthlink.net\fP>
+Fresnel Zone plotting and clearance determination
+
projects / debian / splat / blobdiff