nzrs / wavetrace

Radio propagation modelling

Wavetrace

Wavetrace is a Python 3.5 package designed to produce radio signal coverage reports, such as GeoTIFF files of signal strength contours,

given radio transmitter data and topography data around the transmitters. It uses SPLAT! to predict the attenuation of radio signals, which implements a Longley-Rice model.

Wavetrace can also compute line-of-site maps for geostationary satellites:

Wavetrace is intended for use in New Zealand but can be configured to work elsewhere on Earth.

Installation

1. Install SPLAT! >= 1.4.0, GDAL >= 1.11, and ImageMagick. For example, to install these on a Linux system do sudo apt-get update; sudo apt-get install splat gdal-bin python-gdal imagemagick
2. Create a Python 3.5 virtual environment
3. In your virtual environment, install Wavetrace via Pip via pip install wavetrace

Usage

Here is a common workflow for computing radio signal coverage reports for terrestrial transmitters.

1. Create a CSV file containing transmitter data; see tests/data/transmitters.csv
2. Process the transmitter data into SPLAT! files via the function wavetrace.main.process_transmitters
3. Download topography data around the transmitters via the functions wavetrace.main.compute_tiles and wavetrace.main.download_topography. Topography data comes in two flavors: SRTM3 (standard definition; 3 arc second resolution; roughly 66 meters at 45 degrees south latitude) or SRTM1 (high definition; 1 arc second resolution; roughly 22 meters at 45 degrees south latitude). SPLAT! can only handle those two formats.
4. Process the topography data into SPLAT! files via the function wavetrace.main.process_topography
5. Compute signal coverage reports, which include GeoTIFF signal strength contour maps, from the processed transmitter and topography data via the function wavetrace.main.compute_coverage

See the IPython notebook ipynb/examples.ipynb for a detailed example.

Additionally, you can call the most useful functions in the module wavetrace.main through Wavey, a command line interface for Wavetrace implemented in the module wavetrace.cli.

Documentation

In docs and on Rawgit here

Further Reading

• SPLAT! documentation
• Open Street Map wiki page on SRTM data

Authors

• Chris Guest (2013-06)
• Alex Raichev (2016-08)

wavetrace's Issues

Error executing create_output_from_dir.py

Executing with no parameters like this;
> python create_output_from_dir.py

causes a TypeError to be thrown

Traceback (most recent call last):
  File "create_output_from_dir.py", line 24, in <module>
    receive_sensitivity = (0 - (receive_sensitivity))
TypeError: unsupported operand type(s) for -: 'int' and 'str'

Code review ideas: slugify the network name

make_files.py:55
base_filename is the network name (read from the csv file) with certain characters replaced (namely spaces).
This pattern is usually called 'slugify'
On github;
un33k has a unicode version for python called python-slugify
benlinton has a bash/cli project called slugify
In django there is a built-in called slugify

The code on line 55 needs to create a name which is acceptable for a file system, and this involves not just replacing spaces. This line could be replaced with a call to any of these projects above which can handle many more outlier cases than just replacing spaces (ie unicode, slashes, double extensions etc)

Calculation of the attenuation of free space point-to-point

Hello.
Is it possible to calculate the attenuation of free space to point-to-point radio stations using the code in this repository?

P.s.: I'm not yet very strong at programming and in Python.

Code review ideas: internationalise the parameters

make_files.py;

print >> f, '''15.000 ; Earth Dielectric Constant (Relative permittivity) 0.005 ; Earth Conductivity (Siemens per meter) 301.000 ; Atmospheric Bending Constant (N-units) '''+ inner_dict['frequency_mhz'] + ''' ; Frequency in MHz (20 MHz to 20 GHz) 6 ; Maritime Temperate, over land (UK and west coasts of US & EU) ''' + pol + ''' ; Polarization (0 = Horizontal, 1 = Vertical) 0.5 ; Fraction of situations (50% of locations) 0.5 ; Fraction of time (50% of the time) ''' + inner_dict['power_eirp'] + ''' ; ERP in watts'''

These parameters could be internationalised into a dict, enabling other users to contribute back their dicts rather than just getting the code and localising the parameters

Make the region of the world to download more user fiendly

THE HD Data is not broken into regional pages so specifying bounds using;

if (int(degrees[1]) > 34) and (int(degrees[2]) > 160):

Gets all hemisphere.

Ideas

• Specify hemisphere
• Break into regions

Code review ideas: python xml libs instead of grep/echo/sed code

kml2wld.sh contains this code

imgcoord=$(grep -A 10 "$imgname" "$path/$bn.kml") north=$(echo $imgcoord | sed 's/^.*<north>\([0-9-][0-9\.]*\)<\/north>.*/\1/') south=$(echo $imgcoord | sed 's/^.*<south>\([0-9-][0-9\.]*\)<\/south>.*/\1/') east=$(echo $imgcoord | sed 's/^.*<east>\([0-9-][0-9\.]*\)<\/east>.*/\1/') west=$(echo $imgcoord | sed 's/^.*<west>\([0-9-][0-9\.]*\)<\/west>.*/\1/')

Fast, full of zen, fairly self documenting, but a nightmare for a python dev to debug.

The kml could be opened with an xml parser (ElementTree XML API has been build into python since 2.5 AFAIK) and much of the manipulation could be done in pure python.

Code review ideas: logging instead of print statements

wavetrace is great for batch processing, however it's tough to import into another project and call the methods, returning the result you need.

There are a few things that could make this easier - without making the batch processing harder, so i'll note these ideas one-per-issue;
This one is logging.

Logging instead of print statements would make it much easier for a consuming project to handle the output. Logging also makes it easy to see where and when (even what line no.) a logging call is being made from, plus you can crank up the logging level with one line change, and drop it back after you find and fix the problem.

wt.main.process_topography function is throwing an unexpected error

Hi,

Thanks for building a super helpful library for RF engineering researchers. I was trying to execute the 'example' codes on my PC (pycharm IDE), but it's throwing an error when I called the 'process_topology' function.

Details -

Error lines: FileNotFoundError: [WinError 2] The system cannot find the file specified

Please note that topology files (splat_files, srtm3) are downloaded successfully.

Appreciate your suggestions here.

Thank You

Tauhid

No such file or directory: 'srtm2sdf': 'srtm2sdf'

I have cloned this repo to my local and following the examples.ipynb notebook and still got this error

Units for power_eirp

I presumed that EIRP would be in dBm, maybe dBW, but i see in make_files.py:88 that its in watts.

Maybe this could be noted in the readme?

Code review ideas: Either check for dependencies or provide a list to install?

The following are requirements for wavetrace

shell

splat
pnmscale
pnmtopng
convert
mv
sed
basename
grep
identify
bc

python

requests
BeautifulSoup
csv

There is no way to get away from the python dependencies (unless you want to convert the project to a shell program) so to simplify using the project, dependencies could be checked at the start and hints given for where to find these.
My system was missing splat, and my virtualenv was missing requests - pretty simple to fix, but some will get tripped up on RedHat/CentOS 5 with where to find convert and identify, or some Ubuntu servers with pnmscale

Pure python solution

Another solution could be requiring libs such as
pip install Pillow
and lean on these kinds of libraries which are (especially in a virtualenv) very stable and easy to document the installation of;

This happens in wavetrace;

extimg=$(echo ${imgname#*.})
bnimg=$(basename $imgname .$extimg)
width=$(identify -format "%w" "$path/${bn}_${bnimg}.$extimg")
height=$(identify -format "%h" "$path/${bn}_${bnimg}.$extimg")

In pure python:

from PIL import Image
im = Image.open(filename) 
w = im.size[0]
h = im.size[1]

example usage includes non-existent function

In the example workflow in the "usage" section of the readme on the main page, the example includes using the function wavetrace.main.compute_tiles, but this does not exist. Can the basic usage example be reviewed and updated please?

PIP installation of wavetrace doesn't work

README file suggests to install wavetrace with pip, but doesn't work.

Collecting wavetrace
  Downloading wavetrace-3.0.0.tar.gz
    Complete output from command python setup.py egg_info:
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-build-20787n9x/wavetrace/setup.py", line 11, in <module>
        long_description=open('README.rst').read(),
    FileNotFoundError: [Errno 2] No such file or directory: 'README.rst'

    ----------------------------------------
Command "python setup.py egg_info" failed with error code 1 in /tmp/pip-build-20787n9x/wavetrace/