1 .TH SPLAT! 1 "20 December 2006" "KD2BD Software" "KD2BD Software"
3 splat \- An RF \fBS\fPignal \fBP\fPropagation, \fBL\fPoss, \fBA\fPnd \fBT\fPerrain analysis tool
5 splat [-t \fItransmitter_site.qth\fP]
6 [-r \fIreceiver_site.qth\fP]
7 [-c \fIrx antenna height for LOS coverage analysis (feet/meters) (float)\fP]
8 [-L \fIrx antenna height for Longley-Rice coverage analysis (feet/meters) (float)\fP]
9 [-p \fIterrain_profile.ext\fP]
10 [-e \fIelevation_profile.ext\fP]
11 [-h \fIheight_profile.ext\fP]
12 [-H \fInormalized_height_profile.ext\fP]
13 [-l \fILongley-Rice_profile.ext\fP]
14 [-o \fItopographic_map_filename.ppm\fP]
15 [-b \fIcartographic_boundary_filename.dat\fP]
16 [-s \fIsite/city_database.dat\fP]
17 [-d \fIsdf_directory_path\fP]
18 [-m \fIearth radius multiplier (float)\fP]
19 [-f \fIfrequency (MHz) for Fresnel zone calculations (float)\fP]
20 [-R \fImaximum coverage radius (miles/kilometers) (float)\fP]
21 [-dB \fImaximum attenuation contour to display on path loss maps (80-230 dB)\fP]
22 [-nf \fIdo not plot Fresnel zones in height plots\fP]
23 [-plo \fIpath_loss_output_file.txt\fP]
24 [-pli \fIpath_loss_input_file.txt\fP]
25 [-udt \fIuser_defined_terrain_file.dat\fP]
32 \fBSPLAT!\fP is a powerful terrestrial RF propagation and terrain
33 analysis tool covering the spectrum between 20 MHz and 20 GHz.
34 \fBSPLAT!\fP is free software, and is designed for operation on Unix
35 and Linux-based workstations. Redistribution and/or modification
36 is permitted under the terms of the GNU General Public License as
37 published by the Free Software Foundation, either version 2 of the
38 License or any later version. Adoption of \fBSPLAT!\fP source code
39 in proprietary or closed-source applications is a violation of this
40 license, and is \fBstrictly\fP forbidden.
42 \fBSPLAT!\fP is distributed in the hope that it will be useful, but
43 WITHOUT ANY WARRANTY, without even the implied warranty of MERCHANTABILITY
44 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
47 Applications of \fBSPLAT!\fP include the visualization, design, and
48 link budget analysis of wireless Wide Area Networks (WANs), commercial
49 and amateur radio communication systems above 20 MHz, microwave links,
50 frequency coordination and interference studies, and the determination
51 of analog and digital terrestrial radio and television contour regions.
53 \fBSPLAT!\fP provides RF site engineering data such as great circle
54 distances and bearings between sites, antenna elevation angles (uptilt),
55 depression angles (downtilt), antenna height above mean sea level,
56 antenna height above average terrain, bearings and distances to known
57 obstructions, and Longley-Rice path attenuation. In addition, the minimum
58 antenna height requirements needed to clear terrain, the first Fresnel
59 zone, and 60% of the first Fresnel zone are also provided.
61 \fBSPLAT!\fP produces reports, graphs, and high resolution topographic
62 maps that depict line-of-sight paths, and regional path loss contours
63 through which expected coverage areas of transmitters and repeater
64 systems can be obtained. When performing line-of-sight analysis in
65 situations where multiple transmitter or repeater sites are employed,
66 \fBSPLAT!\fP determines individual and mutual areas of coverage within
67 the network specified.
69 Simply typing \fCsplat\fR on the command line will return a summary
70 of \fBSPLAT!\fP's command line options:
72 --==[ SPLAT! v1.2.0 Available Options... ]==--
74 -t txsite(s).qth (max of 4)
76 -c plot coverage of TX(s) with an RX antenna at X feet/meters AGL
77 -L plot path loss map of TX based on an RX at X feet/meters AGL
78 -s filename(s) of city/site file(s) to import (max of 5)
79 -b filename(s) of cartographic boundary file(s) to import (5 max)
80 -p filename of terrain profile graph to plot
81 -e filename of terrain elevation graph to plot
82 -h filename of terrain height graph to plot
83 -H filename of normalized terrain height graph to plot
84 -l filename of Longley-Rice graph to plot
85 -o filename of topographic map to generate (.ppm)
86 -u filename of user-defined terrain file to import
87 -d sdf file directory path (overrides path in ~/.splat_path file)
88 -n no analysis, brief report
89 -N no analysis, no report
90 -m earth radius multiplier
91 -f frequency for Fresnel zone calculation (MHz)
92 -R modify default range for -c or -L (miles/kilometers)
93 -db maximum loss contour to display on path loss maps (80-230 dB)
94 -nf do not plot Fresnel zones in height plots
95 -plo filename of path-loss output file
96 -pli filename of path-loss input file
97 -udt filename of user defined terrain input file
98 -geo generate a .geo georeference file (with .ppm output)
99 -kml generate a Google Earth .kml file (for point-to-point links)
100 -metric employ metric rather than imperial units for all user I/O
103 \fBSPLAT!\fP is a command-line driven application, and reads input
104 data through a number of data files. Some files are mandatory for
105 successful execution of the program, while others are optional.
106 Mandatory files include 3-arc second topography models in the
107 form of SPLAT Data Files (SDF files), site location files (QTH
108 files), and Longley-Rice model parameter files (LRP files).
109 Optional files include city location files, cartographic boundary
110 files, user-defined terrain files, path-loss input files, and
111 antenna radiation pattern files.
113 \fBSPLAT!\fP imports topographic data in the form of SPLAT Data Files
114 (SDFs). These files may be generated from a number of information sources.
115 In the United States, SPLAT Data Files can be generated through U.S.
116 Geological Survey Digital Elevation Models (DEMs) using the \fBusgs2sdf\fP
117 utility included with \fBSPLAT!\fP. USGS Digital Elevation Models
118 compatible with this utility may be downloaded from:
119 \fIhttp://edcftp.cr.usgs.gov/pub/data/DEM/250/\fP.
121 Significantly better resolution and accuracy can be obtained through
122 the use of SRTM-3 Version 2 digital elevation models. These models are
123 the product of the STS-99 Space Shuttle Radar Topography Mission, and are
124 available for most populated regions of the Earth. SPLAT Data Files
125 may be generated from SRTM data using the included \fBsrtm2sdf\fP utility.
126 SRTM-3 Version 2 data may be obtained through anonymous FTP from:
127 \fIftp://e0srp01u.ecs.nasa.gov:21/srtm/version2/\fP
129 Despite the higher accuracy that SRTM data has to offer, some voids
130 in the data sets exist. When voids are detected, the \fBsrtm2sdf\fP
131 utility replaces them with corresponding data found in existing SDF
132 files (that were presumably created from earlier USGS data through the
133 \fBusgs2sdf\fP utility). If USGS-derived SDF data is not available, voids
134 are handled through adjacent pixel averaging, or direct replacement.
136 SPLAT Data Files contain integer value topographic elevations (in meters)
137 referenced to mean sea level for 1-degree by 1-degree regions of the
138 earth with a resolution of 3-arc seconds. SDF files can be read in
139 either standard format (\fI.sdf\fP) as generated by the \fBusgs2sdf\fP
140 and \fBsrtm2sdf\fP utilities, or in bzip2 compressed format
141 (\fI.sdf.bz2\fP). Since uncompressed files can be processed slightly
142 faster than files that have been compressed, \fBSPLAT!\fP searches for
143 needed SDF data in uncompressed format first. If uncompressed data
144 cannot be located, \fBSPLAT!\fP then searches for data in bzip2 compressed
145 format. If no compressed SDF files can be found for the region requested,
146 \fBSPLAT!\fP assumes the region is over water, and will assign an
147 elevation of sea-level to these areas.
149 This feature of \fBSPLAT!\fP makes it possible to perform path analysis
150 not only over land, but also between coastal areas not represented by
151 Digital Elevation Model data. However, this behavior of \fBSPLAT!\fP
152 underscores the importance of having all the SDF files required for
153 the region being analyzed if meaningful results are to be expected.
154 .SH SITE LOCATION (QTH) FILES
155 \fBSPLAT!\fP imports site location information of transmitter and receiver
156 sites analyzed by the program from ASCII files having a \fI.qth\fP extension.
157 QTH files contain the site's name, the site's latitude (positive if North
158 of the equator, negative if South), the site's longitude (in degrees West,
159 0 to 360 degrees), and the site's antenna height above ground level (AGL),
160 each separated by a single line-feed character. The antenna height is
161 assumed to be specified in feet unless followed by the letter \fIm\fP or
162 the word \fImeters\fP in either upper or lower case. Latitude and
163 longitude information may be expressed in either decimal format (74.6889)
164 or degree, minute, second (DMS) format (74 41 20.0).
166 For example, a site location file describing television station WNJT,
167 Trenton, NJ (\fIwnjt.qth\fP) might read as follows:
174 Each transmitter and receiver site analyzed by \fBSPLAT!\fP must be
175 represented by its own site location (QTH) file.
176 .SH LONGLEY-RICE PARAMETER (LRP) FILES
177 Longley-Rice parameter data files are required for \fBSPLAT!\fP to
178 determine RF path loss in either point-to-point or area prediction
179 mode. Longley-Rice model parameter data is read from files having
180 the same base name as the transmitter site QTH file, but with a
181 \fI.lrp\fP extension. \fBSPLAT!\fP LRP files share the following
182 format (\fIwnjt.lrp\fP):
184 15.000 ; Earth Dielectric Constant (Relative permittivity)
185 0.005 ; Earth Conductivity (Siemens per meter)
186 301.000 ; Atmospheric Bending Constant (N-units)
187 700.000 ; Frequency in MHz (20 MHz to 20 GHz)
188 5 ; Radio Climate (5 = Continental Temperate)
189 0 ; Polarization (0 = Horizontal, 1 = Vertical)
190 0.5 ; Fraction of situations (50% of locations)
191 0.5 ; Fraction of time (50% of the time)
193 If an LRP file corresponding to the tx_site QTH file cannot
194 be found, \fBSPLAT!\fP scans the current working directory for
195 the file "splat.lrp". If this file cannot be found, then the default
196 parameters listed above will be assigned by \fBSPLAT!\fP and a
197 corresponding "splat.lrp" file containing this data will be written
198 to the current working directory. "splat.lrp" can then be edited
199 by the user as needed.
201 Typical Earth dielectric constants and conductivity values are as
204 Dielectric Constant Conductivity
205 Salt water : 80 5.000
206 Good ground : 25 0.020
207 Fresh water : 80 0.010
208 Marshy land : 12 0.007
209 Farmland, forest : 15 0.005
210 Average ground : 15 0.005
211 Mountain, sand : 13 0.002
213 Poor ground : 4 0.001
215 Radio climate codes used by \fBSPLAT!\fP are as follows:
217 1: Equatorial (Congo)
218 2: Continental Subtropical (Sudan)
219 3: Maritime Subtropical (West coast of Africa)
221 5: Continental Temperate
222 6: Maritime Temperate, over land (UK and west coasts of US & EU)
223 7: Maritime Temperate, over sea
225 The Continental Temperate climate is common to large land masses in
226 the temperate zone, such as the United States. For paths shorter than
227 100 km, there is little difference between Continental and Maritime
230 The final two parameters in the \fI.lrp\fP file correspond to the statistical
231 analysis provided by the Longley-Rice model. In this example, \fBSPLAT!\fP
232 will return the maximum path loss occurring 50% of the time (fraction
233 of time) in 50% of situations (fraction of situations). In the United
234 States, use a fraction of time parameter of 0.97 for digital television
235 (8VSB modulation), or 0.50 for analog (VSB-AM+NTSC) transmissions.
237 For further information on these parameters, see:
238 \fIhttp://flattop.its.bldrdoc.gov/itm.html\fP and
239 \fIhttp://www.softwright.com/faq/engineering/prop_longley_rice.html\fP
240 .SH CITY LOCATION FILES
241 The names and locations of cities, tower sites, or other points of interest
242 may be imported and plotted on topographic maps generated by \fBSPLAT!\fP.
243 \fBSPLAT!\fP imports the names of cities and locations from ASCII files
244 containing the location of interest's name, latitude, and longitude.
245 Each field is separated by a comma. Each record is separated by a
246 single line feed character. As was the case with the \fI.qth\fP
247 files, latitude and longitude information may be entered in either
248 decimal or degree, minute, second (DMS) format.
250 For example (\fIcities.dat\fP):
252 Teaneck, 40.891973, 74.014506
253 Tenafly, 40.919212, 73.955892
254 Teterboro, 40.859511, 74.058908
255 Tinton Falls, 40.279966, 74.093924
256 Toms River, 39.977777, 74.183580
257 Totowa, 40.906160, 74.223310
258 Trenton, 40.219922, 74.754665
260 A total of five separate city data files may be imported at a time,
261 and there is no limit to the size of these files. \fBSPLAT!\fP reads
262 city data on a "first come/first served" basis, and plots only those
263 locations whose annotations do not conflict with annotations of
264 locations read earlier in the current city data file, or in previous
265 files. This behavior minimizes clutter in \fBSPLAT!\fP generated
266 topographic maps, but also mandates that important locations be placed
267 toward the beginning of the first city data file, and locations less
268 important be positioned further down the list or in subsequent data
271 City data files may be generated manually using any text editor,
272 imported from other sources, or derived from data available from the
273 U.S. Census Bureau using the \fBcitydecoder\fP utility included with
274 \fBSPLAT!\fP. Such data is available free of charge via the Internet
275 at: \fIhttp://www.census.gov/geo/www/cob/bdy_files.html\fP, and must
277 .SH CARTOGRAPHIC BOUNDARY DATA FILES
278 Cartographic boundary data may also be imported to plot the boundaries of
279 cities, counties, or states on topographic maps generated by \fBSPLAT!\fP.
280 Such data must be of the form of ARC/INFO Ungenerate (ASCII Format)
281 Metadata Cartographic Boundary Files, and are available from the U.S.
282 Census Bureau via the Internet at:
283 \fIhttp://www.census.gov/geo/www/cob/co2000.html#ascii\fP and
284 \fIhttp://www.census.gov/geo/www/cob/pl2000.html#ascii\fP. A total of
285 five separate cartographic boundary files may be imported at a time.
286 It is not necessary to import state boundaries if county boundaries
287 have already been imported.
288 .SH PROGRAM OPERATION
289 \fBSPLAT!\fP is invoked via the command-line using a series of switches
290 and arguments. Since \fBSPLAT!\fP is a CPU and memory intensive application,
291 this type of interface minimizes overhead and lends itself well to
292 scripted (batch) operations. \fBSPLAT!\fP's CPU and memory scheduling
293 priority may be modified through the use of the Unix \fBnice\fP command.
295 The number and type of switches passed to \fBSPLAT!\fP determine its
296 mode of operation and method of output data generation. Nearly all
297 of \fBSPLAT!\fP's switches may be cascaded in any order on the command
298 line when invoking the program.
300 \fBSPLAT!\fP operates in two distinct modes: \fIpoint-to-point mode\fP,
301 and \fIarea prediction mode\fP. Either a line-of-sight (LOS) or Longley-Rice
302 Irregular Terrain (ITM) propagation model may be invoked by the user. True
303 Earth, four-thirds Earth, or any other user-defined Earth radius may be
304 specified when performing line-of-sight analysis.
305 .SH POINT-TO-POINT ANALYSIS
306 \fBSPLAT!\fP may be used to perform line-of-sight terrain analysis
307 between two specified site locations. For example:
309 \fCsplat -t tx_site.qth -r rx_site.qth\fR
311 invokes a line-of-sight terrain analysis between the transmitter
312 specified in \fItx_site.qth\fP and receiver specified in \fIrx_site.qth\fP
313 using a True Earth radius model, and writes a \fBSPLAT!\fP Obstruction
314 Report to the current working directory. The report contains details of
315 the transmitter and receiver sites, and identifies the location of any
316 obstructions detected along the line-of-sight path. If an obstruction
317 can be cleared by raising the receive antenna to a greater altitude,
318 \fBSPLAT!\fP will indicate the minimum antenna height required for a
319 line-of-sight path to exist between the transmitter and receiver locations
320 specified. Note that imperial units (miles, feet) are specified unless
321 the \fI-metric\fP switch is added to \fBSPLAT!\fP's command line options:
323 \fCsplat -t tx_site.qth -r rx_site.qth -metric\fR
325 If the antenna must be raised a significant amount, this determination
326 may take a few moments. Note that the results provided are the \fIminimum\fP
327 necessary for a line-of-sight path to exist, and in the case of this
328 simple example, do not take Fresnel zone clearance requirements into
331 \fIqth\fP extensions are assumed by \fBSPLAT!\fP for QTH files, and
332 are optional when specifying -t and -r arguments on the command-line.
333 \fBSPLAT!\fP automatically reads all SPLAT Data Files necessary to
334 conduct the terrain analysis between the sites specified. \fBSPLAT!\fP
335 searches for the required SDF files in the current working directory
336 first. If the needed files are not found, \fBSPLAT!\fP then searches
337 in the path specified by the \fI-d\fP command-line switch:
339 \fCsplat -t tx_site -r rx_site -d /cdrom/sdf/\fR
341 An external directory path may be specified by placing a ".splat_path"
342 file under the user's home directory. This file must contain the full
343 directory path of last resort to all the SDF files. The path in the
344 \fI$HOME/.splat_path\fP file must be of the form of a single line of
347 \fC/opt/splat/sdf/\fR
349 and can be generated using any text editor.
351 A graph of the terrain profile between the receiver and transmitter
352 locations as a function of distance from the receiver can be generated
353 by adding the \fI-p\fP switch:
355 \fCsplat -t tx_site -r rx_site -p terrain_profile.png\fR
357 \fBSPLAT!\fP invokes \fBgnuplot\fP when generating graphs. The filename
358 extension specified to \fBSPLAT!\fP determines the format of the graph
359 produced. \fI.png\fP will produce a 640x480 color PNG graphic file,
360 while \fI.ps\fP or \fI.postscript\fP will produce postscript output.
361 Output in formats such as GIF, Adobe Illustrator, AutoCAD dxf,
362 LaTeX, and many others are available. Please consult \fBgnuplot\fP,
363 and \fBgnuplot\fP's documentation for details on all the supported
366 A graph of elevations subtended by the terrain between the receiver and
367 transmitter as a function of distance from the receiver can be generated
368 by using the \fI-e\fP switch:
370 \fCsplat -t tx_site -r rx_site -e elevation_profile.png\fR
372 The graph produced using this switch illustrates the elevation and
373 depression angles resulting from the terrain between the receiver's
374 location and the transmitter site from the perspective of the receiver's
375 location. A second trace is plotted between the left side of the graph
376 (receiver's location) and the location of the transmitting antenna on
377 the right. This trace illustrates the elevation angle required for a
378 line-of-sight path to exist between the receiver and transmitter
379 locations. If the trace intersects the elevation profile at any point
380 on the graph, then this is an indication that a line-of-sight path
381 does not exist under the conditions given, and the obstructions can
382 be clearly identified on the graph at the point(s) of intersection.
384 A graph illustrating terrain height referenced to a line-of-sight
385 path between the transmitter and receiver may be generated using
388 \fCsplat -t tx_site -r rx_site -h height_profile.png\fR
390 A terrain height plot normalized to the transmitter and receiver
391 antenna heights can be obtained using the \fI-H\fP switch:
393 \fCsplat -t tx_site -r rx_site -H normalized_height_profile.png\fR
395 A contour of the Earth's curvature is also plotted in this mode.
397 The first Fresnel Zone, and 60% of the first Fresnel Zone can be
398 added to height profile graphs by adding the \fI-f\fP switch, and
399 specifying a frequency (in MHz) at which the Fresnel Zone should be
402 \fCsplat -t tx_site -r rx_site -f 439.250 -H normalized_height_profile.png\fR
404 A graph showing Longley-Rice path loss may be plotted using the
407 \fCsplat -t tx_site -r rx_site -l path_loss_profile.png\fR
409 As before, adding the \fI-metric\fP switch forces the graphs to
410 be plotted using metric units of measure.
412 When performing path loss profiles, a Longley-Rice Model Path Loss
413 Report is generated by \fBSPLAT!\fP in the form of a text file with
414 a \fI.lro\fP filename extension. The report contains bearings and
415 distances between the transmitter and receiver, as well as the
416 Longley-Rice path loss for various distances between the transmitter
417 and receiver locations. The mode of propagation for points along the
418 path are given as \fILine-of-Sight\fP, \fISingle Horizon\fP, \fIDouble
419 Horizon\fP, \fIDiffraction Dominant\fP, and \fITroposcatter Dominant\fP.
421 To determine the signal-to-noise (SNR) ratio at remote location
422 where random Johnson (thermal) noise is the primary limiting
426 SNR = T - NJ - L + G - NF
429 where \fBT\fP is the ERP of the transmitter in dBW in the direction
430 of the receiver, \fBNJ\fP is Johnson Noise in dBW (-136 dBW for a 6 MHz
431 television channel), \fBL\fP is the path loss provided by \fBSPLAT!\fP
432 in dB (as a \fIpositive\fP number), \fBG\fP is the receive antenna gain
433 in dB over isotropic, and \fBNF\fP is the receiver noise figure in dB.
435 \fBT\fP may be computed as follows:
441 where \fBTI\fP is actual amount of RF power delivered to the transmitting
442 antenna in dBW, \fBGT\fP is the transmitting antenna gain (over isotropic)
443 in the direction of the receiver (or the horizon if the receiver is over
446 To compute how much more signal is available over the minimum to
447 necessary to achieve a specific signal-to-noise ratio:
450 Signal_Margin = SNR - S
453 where \fBS\fP is the minimum required SNR ratio (15.5 dB for
454 ATSC (8-VSB) DTV, 42 dB for analog NTSC television).
456 A topographic map may be generated by \fBSPLAT!\fP to visualize the
457 path between the transmitter and receiver sites from yet another
458 perspective. Topographic maps generated by \fBSPLAT!\fP display
459 elevations using a logarithmic grayscale, with higher elevations
460 represented through brighter shades of gray. The dynamic range of
461 the image is scaled between the highest and lowest elevations present
462 in the map. The only exception to this is sea-level, which is
463 represented using the color blue.
465 Topographic output is invoked using the \fI-o\fP switch:
467 \fCsplat -t tx_site -r rx_site -o topo_map.ppm\fR
469 The \fI.ppm\fP extension on the output filename is assumed by
470 \fBSPLAT!\fP, and is optional.
472 In this example, \fItopo_map.ppm\fP will illustrate the locations of the
473 transmitter and receiver sites specified. In addition, the great circle
474 path between the two sites will be drawn over locations for which an
475 unobstructed path exists to the transmitter at a receiving antenna
476 height equal to that of the receiver site (specified in \fIrx_site.qth\fP).
478 It may desirable to populate the topographic map with names and locations
479 of cities, tower sites, or other important locations. A city file may be
480 passed to \fBSPLAT!\fP using the \fI-s\fP switch:
482 \fCsplat -t tx_site -r rx_site -s cities.dat -o topo_map\fR
484 Up to five separate city files may be passed to \fBSPLAT!\fP at a time
485 following the \fI-s\fP switch.
487 County and state boundaries may be added to the map by specifying up
488 to five U.S. Census Bureau cartographic boundary files using the \fI-b\fP
491 \fCsplat -t tx_site -r rx_site -b co34_d00.dat -o topo_map\fR
493 In situations where multiple transmitter sites are in use, as many as
494 four site locations may be passed to \fBSPLAT!\fP at a time for analysis:
496 \fCsplat -t tx_site1 tx_site2 tx_site3 tx_site4 -r rx_site -p profile.png\fR
498 In this example, four separate terrain profiles and obstruction reports
499 will be generated by \fBSPLAT!\fP. A single topographic map can be
500 specified using the \fI-o\fP switch, and line-of-sight paths between
501 each transmitter and the receiver site indicated will be produced on
502 the map, each in its own color. The path between the first transmitter
503 specified to the receiver will be in green, the path between the
504 second transmitter and the receiver will be in cyan, the path between
505 the third transmitter and the receiver will be in violet, and the
506 path between the fourth transmitter and the receiver will be in sienna.
508 \fBSPLAT!\fP generated topographic maps are 24-bit TrueColor Portable
509 PixMap (PPM) images. They may be viewed, edited, or converted to other
510 graphic formats by popular image viewing applications such as \fBxv\fP,
511 \fBThe GIMP\fP, \fBImageMagick\fP, and \fBXPaint\fP. PNG format is
512 highly recommended for lossless compressed storage of \fBSPLAT!\fP
513 generated topographic output files. \fBImageMagick\fP's command-line
514 utility easily converts \fBSPLAT!\fP's PPM files to PNG format:
516 \fCconvert splat_map.ppm splat_map.png\fR
518 Another excellent PPM to PNG command-line utility is available
519 at: \fIhttp://www.libpng.org/pub/png/book/sources.html\fP. As a last
520 resort, PPM files may be compressed using the bzip2 utility, and read
521 directly by \fBThe GIMP\fP in this format.
522 .SH REGIONAL COVERAGE ANALYSIS
523 \fBSPLAT!\fP can analyze a transmitter or repeater site, or network
524 of sites, and predict the regional coverage for each site specified.
525 In this mode, \fBSPLAT!\fP can generate a topographic map displaying
526 the geometric line-of-sight coverage area of the sites based on the
527 location of each site and the height of receive antenna wishing to
528 communicate with the site in question. \fBSPLAT!\fP switches from
529 point-to-point analysis mode to area prediction mode when the \fI-c\fP
530 switch is invoked as follows:
532 \fCsplat -t tx_site -c 30.0 -s cities.dat -b co34_d00.dat -o tx_coverage\fR
534 In this example, \fBSPLAT!\fP generates a topographic map called
535 \fItx_coverage.ppm\fP that illustrates the predicted line-of-sight
536 regional coverage of \fItx_site\fP to receiving locations having
537 antennas 30.0 feet above ground level (AGL). If the \fI-metric\fP
538 switch is used, the argument following the \fI-c\fP switch is
539 interpreted as being in meters, rather than in feet. The contents
540 of \fIcities.dat\fP are plotted on the map, as are the cartographic
541 boundaries contained in the file \fIco34_d00.dat\fP.
543 When plotting line-of-sight paths and areas of regional coverage,
544 \fBSPLAT!\fP by default does not account for the effects of
545 atmospheric bending. However, this behavior may be modified
546 by using the Earth radius multiplier (\fI-m\fP) switch:
548 \fCsplat -t wnjt -c 30.0 -m 1.333 -s cities.dat -b counties.dat -o map.ppm\fR
550 An earth radius multiplier of 1.333 instructs \fBSPLAT!\fP to use
551 the "four-thirds earth" model for line-of-sight propagation analysis.
552 Any appropriate earth radius multiplier may be selected by the user.
554 When invoked in area prediction mode, \fBSPLAT!\fP generates a
555 site report for each station analyzed. \fBSPLAT!\fP site reports
556 contain details of the site's geographic location, its height above
557 mean sea level, the antenna's height above mean sea level, the
558 antenna's height above average terrain, and the height of the
559 average terrain calculated in the directions of 0, 45, 90, 135,
560 180, 225, 270, and 315 degrees azimuth.
561 .SH DETERMINING MULTIPLE REGIONS OF LOS COVERAGE
562 \fBSPLAT!\fP can also display line-of-sight coverage areas for as
563 many as four separate transmitter sites on a common topographic map.
566 \fCsplat -t site1 site2 site3 site4 -c 10.0 -metric -o network.ppm\fR
568 plots the regional line-of-sight coverage of site1, site2, site3,
569 and site4 based on a receive antenna located 10.0 meters above ground
570 level. A topographic map is then written to the file \fInetwork.ppm\fP.
571 The line-of-sight coverage area of the transmitters are plotted as
572 follows in the colors indicated (along with their corresponding RGB
575 site1: Green (0,255,0)
576 site2: Cyan (0,255,255)
577 site3: Medium Violet (147,112,219)
578 site4: Sienna 1 (255,130,71)
580 site1 + site2: Yellow (255,255,0)
581 site1 + site3: Pink (255,192,203)
582 site1 + site4: Green Yellow (173,255,47)
583 site2 + site3: Orange (255,165,0)
584 site2 + site4: Dark Sea Green 1 (193,255,193)
585 site3 + site4: Dark Turquoise (0,206,209)
587 site1 + site2 + site3: Dark Green (0,100,0)
588 site1 + site2 + site4: Blanched Almond (255,235,205)
589 site1 + site3 + site4: Medium Spring Green (0,250,154)
590 site2 + site3 + site4: Tan (210,180,140)
592 site1 + site2 + site3 + site4: Gold2 (238,201,0)
594 If separate \fI.qth\fP files are generated, each representing a common
595 site location but a different antenna height, a single topographic map
596 illustrating the regional coverage from as many as four separate locations
597 on a single tower may be generated by \fBSPLAT!\fP.
598 .SH LONGLEY-RICE PATH LOSS ANALYSIS
599 If the \fI-c\fP switch is replaced by a \fI-L\fP switch, a
600 Longley-Rice path loss map for a transmitter site may be generated:
602 \fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -o path_loss_map\fR
604 In this mode, \fBSPLAT!\fP generates a multi-color map illustrating
605 expected signal levels (path loss) in areas surrounding the transmitter
606 site. A legend at the bottom of the map correlates each color with a
607 specific path loss range in decibels.
609 The Longley-Rice analysis range may be modified to a user-specific
610 value using the \fI-R\fP switch. The argument must be given in miles
611 (or kilometers if the \fI-metric\fP switch is used). If a range wider
612 than the generated topographic map is specified, \fBSPLAT!\fP will
613 perform Longley-Rice path loss calculations between all four corners
614 of the area prediction map.
616 The \fI-db\fP switch allows a constraint to be placed on the maximum
617 path loss region plotted on the map. A maximum path loss between 80
618 and 230 dB may be specified using this switch. For example, if a path
619 loss beyond -140 dB is irrelevant to the survey being conducted,
620 \fBSPLAT!\fP's path loss plot can be constrained to the region
621 bounded by the 140 dB attenuation contour as follows:
623 \fCsplat -t wnjt -L 30.0 -s cities.dat -b co34_d00.dat -db 140 -o plot.ppm\fR
625 .SH ANTENNA RADIATION PATTERN PARAMETERS
626 Normalized field voltage patterns for a transmitting antenna's horizontal
627 and vertical planes are imported automatically into \fBSPLAT!\fP when a
628 Longley-Rice coverage analysis is performed. Antenna pattern data is
629 read from a pair of files having the same base name as the transmitter
630 and LRP files, but with \fI.az\fP and \fI.el\fP extensions for azimuth
631 and elevation pattern files, respectively. Specifications regarding
632 pattern rotation (if any) and mechanical beam tilt and tilt direction
633 (if any) are also contained within \fBSPLAT!\fP antenna pattern files.
635 For example, the first few lines of a \fBSPLAT!\fP azimuth pattern file
636 might appear as follows (\fIkvea.az\fP):
649 The first line of the \fI.az\fP file specifies the amount of azimuthal
650 pattern rotation (measured clockwise in degrees from True North) to be
651 applied by \fBSPLAT!\fP to the data contained in the \fI.az\fP file.
652 This is followed by azimuth headings (0 to 360 degrees) and their associated
653 normalized field patterns (0.000 to 1.000) separated by whitespace.
655 The structure of \fBSPLAT!\fP elevation pattern files is slightly different.
656 The first line of the \fI.el\fP file specifies the amount of mechanical
657 beam tilt applied to the antenna. Note that a \fIdownward tilt\fP
658 (below the horizon) is expressed as a \fIpositive angle\fP, while an
659 \fIupward tilt\fP (above the horizon) is expressed as a \fInegative angle\fP.
660 This data is followed by the azimuthal direction of the tilt, separated by
663 The remainder of the file consists of elevation angles and their
664 corresponding normalized voltage radiation pattern (0.000 to 1.000)
665 values separated by whitespace. Elevation angles must be specified
666 over a -10.0 to +90.0 degree range. As was the convention with mechanical
667 beamtilt, \fInegative elevation angles\fP are used to represent elevations
668 \fIabove the horizon\fP, while \fIpositive angles\fP represents elevations
669 \fIbelow the horizon\fP.
671 For example, the first few lines a \fBSPLAT!\fP elevation pattern file
672 might appear as follows (\fIkvea.el\fP):
685 In this example, the antenna is mechanically tilted downward 1.1 degrees
686 towards an azimuth of 130.0 degrees.
688 For best results, the resolution of azimuth pattern data should be
689 specified to the nearest degree azimuth, and elevation pattern data
690 resolution should be specified to the nearest 0.01 degrees. If the
691 pattern data specified does not reach this level of resolution,
692 \fBSPLAT!\fP will interpolate the values provided to determine the
693 data at the required resolution, although this may result in a loss
696 .SH IMPORTING AND EXPORTING REGIONAL PATH LOSS CONTOUR DATA
697 Performing a Longley-Rice coverage analysis can be a very time
698 consuming process, especially if the analysis is repeated repeatedly
699 to discover what effects changes to the antenna radiation patterns
700 make to the predicted coverage area.
702 This process can be expedited by exporting the Longley-Rice
703 regional path loss contour data to an output file, modifying the
704 path loss data externally to incorporate antenna pattern effects,
705 and then importing the modified path loss data back into \fBSPLAT!\fP
706 to rapidly produce a revised path loss map.
708 For example, a path loss output file can be generated by \fBSPLAT!\fP
709 for a receive site 30 feet above ground level over a 50 mile radius
710 surrounding a transmitter site to a maximum path loss of 140 dB using
711 the following syntax:
713 \fCsplat -t kvea -L 30.0 -R 50.0 -db 140 -plo pathloss.dat\fR
715 \fBSPLAT!\fP path loss output files often exceed 100 megabytes in size.
716 They contain information relating to the boundaries of region they describe
717 followed by latitudes (degrees North), longitudes (degrees West), azimuths,
718 elevations (to the first obstruction), and path loss figures (dB) for a
719 series of specific points that comprise the region surrounding the
720 transmitter site. The first few lines of a \fBSPLAT!\fP path loss
721 output file take on the following appearance (\fIpathloss.dat\fP):
723 119, 117 ; max_west, min_west
724 35, 33 ; max_north, min_north
725 34.2265434, 118.0631104, 48.171, -37.461, 67.70
726 34.2270355, 118.0624390, 48.262, -26.212, 73.72
727 34.2280197, 118.0611038, 48.269, -14.951, 79.74
728 34.2285156, 118.0604401, 48.207, -11.351, 81.68
729 34.2290077, 118.0597687, 48.240, -10.518, 83.26
730 34.2294998, 118.0591049, 48.225, 23.201, 84.60
731 34.2304878, 118.0577698, 48.213, 15.769, 137.84
732 34.2309799, 118.0570984, 48.234, 15.965, 151.54
733 34.2314720, 118.0564346, 48.224, 16.520, 149.45
734 34.2319679, 118.0557632, 48.223, 15.588, 151.61
735 34.2329521, 118.0544281, 48.230, 13.889, 135.45
736 34.2334442, 118.0537643, 48.223, 11.693, 137.37
737 34.2339401, 118.0530930, 48.222, 14.050, 126.32
738 34.2344322, 118.0524292, 48.216, 16.274, 156.28
739 34.2354164, 118.0510941, 48.222, 15.058, 152.65
740 34.2359123, 118.0504227, 48.221, 16.215, 158.57
741 34.2364044, 118.0497589, 48.216, 15.024, 157.30
742 34.2368965, 118.0490875, 48.225, 17.184, 156.36
744 It is not uncommon for \fBSPLAT!\fP path loss files to contain as
745 many as 3 million or more lines of data. Comments can be placed in
746 the file if they are proceeded by a semicolon character. The \fBvim\fP
747 text editor has proven capable of editing files of this size.
749 Note as was the case in the antenna pattern files, negative elevation
750 angles refer to upward tilt (above the horizon), while positive angles
751 refer to downward tilt (below the horizon). These angles refer to the
752 elevation to the receiving antenna at the height above ground level
753 specified using the \fI-L\fP switch \fIif\fP the path between transmitter
754 and receiver is unobstructed. If the path between the transmitter
755 and receiver is obstructed, then the elevation angle to the first
756 obstruction is returned by \fBSPLAT!\fP. This is because
757 the Longley-Rice model considers the energy reaching a distant point
758 over an obstructed path as a derivative of the energy scattered from
759 the top of the first obstruction, only. Since energy cannot reach
760 the obstructed location directly, the actual elevation angle to that
763 When modifying \fBSPLAT!\fP path loss files to reflect antenna
764 pattern data, \fIonly the last column (path loss)\fP should be amended
765 to reflect the antenna's normalized gain at the azimuth and elevation
766 angles specified in the file. (At this time, programs and scripts
767 capable of performing this operation are left as an exercise for
770 Modified path loss maps can be imported back into \fBSPLAT!\fP for
771 generating revised coverage maps:
773 \fCsplat -t kvea -pli pathloss.dat -s city.dat -b county.dat -o map.ppm\fR
775 \fBSPLAT!\fP path loss files can also be used for conducting coverage or
776 interference studies outside of \fBSPLAT!\fP.
777 .SH USER-DEFINED TERRAIN INPUT FILES
778 A user-defined terrain file is a user-generated text file containing latitudes,
779 longitudes, and heights above ground level of specific terrain features believed
780 to be of importance to the \fBSPLAT!\fP analysis being conducted, but noticeably
781 absent from the SDF files being used. A user-defined terrain file is imported
782 into a \fBSPLAT!\fP analysis using the \fI-udt\fP switch:
784 \fC splat -t tx_site -r rx_site -udt udt_file.txt -o map.ppm\fR
786 A user-defined terrain file has the following appearance and structure:
788 40.32180556, 74.1325, 100.0 meters
789 40.321805, 74.1315, 300.0
790 40.3218055, 74.1305, 100.0 meters
792 Terrain height is interpreted as being described in feet above ground
793 level unless followed by the word \fImeters\fP, and is added \fIon top of\fP
794 the terrain specified in the SDF data for the locations specified. Be
795 aware that each user-defined terrain feature specified will be interpreted
796 as being 3-arc seconds in both latitude and longitude. Features described
797 in the user-defined terrain file that overlap previously defined features
798 in the file are ignored by \fBSPLAT!\fP.
799 .SH SIMPLE TOPOGRAPHIC MAP GENERATION
800 In certain situations it may be desirable to generate a topographic map
801 of a region without plotting coverage areas, line-of-sight paths, or
802 generating obstruction reports. There are several ways of doing this.
803 If one wishes to generate a topographic map illustrating the location
804 of a transmitter and receiver site along with a brief text report
805 describing the locations and distances between the sites, the \fI-n\fP
806 switch should be invoked as follows:
808 \fCsplat -t tx_site -r rx_site -n -o topo_map.ppm\fR
810 If no text report is desired, then the \fI-N\fP switch is used:
812 \fCsplat -t tx_site -r rx_site -N -o topo_map.ppm\fR
814 If a topographic map centered about a single site out to a minimum
815 specified radius is desired instead, a command similar to the following
818 \fCsplat -t tx_site -R 50.0 -s NJ_Cities -b NJ_Counties -o topo_map.ppm\fR
820 where -R specifies the minimum radius of the map in miles (or kilometers
821 if the \fI-metric\fP switch is used).
823 If the \fI-o\fP switch and output filename are omitted in these
824 operations, topographic output is written to a file named \fImap.ppm\fP
825 in the current working directory by default.
826 .SH GEOREFERENCE FILE GENERATION
827 Topographic, coverage (\fI-c\fP), and path loss contour (\fI-L\fP) maps
828 generated by \fBSPLAT!\fP may be imported into \fBXastir\fP (X Amateur
829 Station Tracking and Information Reporting) software by generating a
830 georeference file using \fBSPLAT!\fP's \fI-geo\fP switch:
832 \fCsplat -t kd2bd -R 50.0 -s NJ_Cities -b NJ_Counties -geo -o map.ppm\fR
834 The georeference file generated will have the same base name as the
835 \fI-o\fP file specified, but have a \fI .geo\fP extension, and permit
836 proper interpretation and display of \fBSPLAT!\fP's .ppm graphics in
837 \fBXastir\fP software.
838 .SH GOOGLE MAP KML FILE GENERATION
839 Keyhole Markup Language files compatible with \fBGoogle Earth\fP may
840 be generated by \fBSPLAT!\fP when performing point-to-point analyses
841 by invoking the \fI-kml\fP switch:
843 \fCsplat -t wnjt -r kd2bd -kml\fR
845 The KML file generated will have the same filename structure as an
846 Obstruction Report for the transmitter and receiver site names given,
847 except it will carry a \fI .kml\fP extension.
849 Once loaded into \fBGoogle Earth\fP (File --> Open), the KML file
850 will annotate the map display with the names of the transmitter and
851 receiver site locations. The viewpoint of the image will be from the
852 position of the transmitter site looking towards the location of the
853 receiver. The point-to-point path between the sites will be displayed
854 as a white line while the RF line-of-sight path will be displayed in
855 green. \fBGoogle Earth\fP's navigation tools allow the user to
856 "fly" around the path, identify landmarks, roads, and other
858 .SH DETERMINATION OF ANTENNA HEIGHT ABOVE AVERAGE TERRAIN
859 \fBSPLAT!\fP determines antenna height above average terrain (HAAT)
860 according to the procedure defined by Federal Communications Commission
861 Part 73.313(d). According to this definition, terrain elevations along
862 eight radials between 2 and 10 miles (3 and 16 kilometers) from the site
863 being analyzed are sampled and averaged for each 45 degrees of azimuth
864 starting with True North. If one or more radials lie entirely over water
865 or over land outside the United States (areas for which no USGS topography
866 data is available), then those radials are omitted from the calculation
869 Note that SRTM elevation data, unlike older 3-arc second USGS data,
870 extends beyond the borders of the United States. Therefore, HAAT
871 results may not be in full compliance with FCC Part 73.313(d)
872 in areas along the borders of the United States if the SDF files
873 used by \fBSPLAT!\fP are SRTM-derived.
875 When performing point-to-point terrain analysis, \fBSPLAT!\fP determines
876 the antenna height above average terrain only if enough topographic
877 data has already been loaded by the program to perform the point-to-point
878 analysis. In most cases, this will be true, unless the site in question
879 does not lie within 10 miles of the boundary of the topography data in
882 When performing area prediction analysis, enough topography data is
883 normally loaded by \fBSPLAT!\fP to perform average terrain calculations.
884 Under such conditions, \fBSPLAT!\fP will provide the antenna height
885 above average terrain as well as the average terrain above mean sea
886 level for azimuths of 0, 45, 90, 135, 180, 225, 270, and 315 degrees,
887 and include such information in the generated site report. If one or
888 more of the eight radials surveyed fall over water, or over regions
889 for which no SDF data is available, \fBSPLAT!\fP reports \fINo Terrain\fP
890 for the radial paths affected.
891 .SH RESTRICTING THE MAXIMUM SIZE OF AN ANALYSIS REGION
892 \fBSPLAT!\fP reads SDF files as needed into a series of memory pages
893 or "slots" within the structure of the program. Each "slot" holds one
894 SDF file representing a one degree by one degree region of terrain.
895 A \fI#define MAXSLOTS\fP statement in the first several lines of
896 \fIsplat.cpp\fP sets the maximum number of "slots" available for holding
897 topography data. It also sets the maximum size of the topographic maps
898 generated by \fBSPLAT!\fP. MAXSLOTS is set to 9 by default. If \fBSPLAT!\fP
899 produces a segmentation fault on start-up with this default, it is an indication
900 that not enough RAM and/or virtual memory (swap space) is available to
901 run \fBSPLAT!\fP with the number of MAXSLOTS specified. In situations where
902 available memory is low, MAXSLOTS may be reduced to 4 with the understanding
903 that this will greatly limit the maximum region \fBSPLAT!\fP will be able
904 to analyze. If 118 megabytes or more of total memory (swap space plus
905 RAM) is available, then MAXSLOTS may be increased to 16. This will
906 permit operation over a 4-degree by 4-degree region, which is sufficient
907 for single antenna heights in excess of 10,000 feet above mean sea
908 level, or point-to-point distances of over 1000 miles.
909 .SH ADDITIONAL INFORMATION
910 The latest news and information regarding \fBSPLAT!\fP software is
911 available through the official \fBSPLAT!\fP software web page located
912 at: \fIhttp://www.qsl.net/kd2bd/splat.html\fP.
915 John A. Magliacane, KD2BD <\fIkd2bd@amsat.org\fP>
916 Creator, Lead Developer
918 Doug McDonald <\fImcdonald@scs.uiuc.edu\fP>
919 Longley-Rice Model integration
921 Ron Bentley <\fIronbentley@earthlink.net\fP>
922 Fresnel Zone plotting and clearance determination
projects / debian / splat / blob