Merge pull request #21 from araichev/master

Merge request for version 4.0.0

.gitignore

@@ -1,10 +1,94 @@
 *.DS_Store
-*.pyc
-*__pycache__
-*.egg-info
-ipynb/.ipynb_checkpoints
-tmp
+tmp/
 tests/data/tmp*
 other_docs
 secrets.json
-dist
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+
+# virtualenv
+.venv/
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+
+# Rope project settings
+.ropeproject

README.rst

@@ -19,11 +19,11 @@ Wavetrace can also compute line-of-site maps for geostationary satellites:
     :align: center
 
 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 imagemagick``
+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``
 
@@ -63,7 +63,18 @@ Authors
 Changelog
 ==========
 
-v3.0.0, 2016-09-28
+v4.0.0, 2017-01-17
+-------------------
+- Removed Gitlab API key option, because it is unnecessary for accessing the required public repository
+- Added the option to create ESRI Shapefiles in the functions ``main.compute_coverage`` and ``main.compute_satellite_los``.
+
+
+v3.0.1, 2016-12-15
+-------------------
+- Repackaged with setuptools and ensured that the README is included in tar archive this time
+
+
+v3.0.0, 2016-08-22
 -------------------
 - Added functions to compute line-of-sight for geostationary satellites
 - Renamed some functions, hence the version bump

docs/_build/singlehtml/index.html

@@ -40,7 +40,7 @@
           <div class="body" role="main">
 
   <div class="section" id="wavetrace-version-documentation">
-<h1>Wavetrace 3.0 documentation<a class="headerlink" href="#wavetrace-version-documentation" title="Permalink to this headline">¶</a></h1>
+<h1>Wavetrace 4.0 documentation<a class="headerlink" href="#wavetrace-version-documentation" title="Permalink to this headline">¶</a></h1>
 <div class="toctree-wrapper compound">
 <span id="document-introduction"></span><div class="section" id="introduction">
 <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
@@ -55,7 +55,7 @@ <h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to t
 <div class="section" id="installation">
 <h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>
 <ol class="arabic simple">
-<li>Install SPLAT! &gt;= 1.4.0, GDAL &gt;= 1.11, and ImageMagick. For example, to install these on a Linux system do <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">update;</span> <span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">splat</span> <span class="pre">gdal-bin</span> <span class="pre">imagemagick</span></code></li>
+<li>Install SPLAT! &gt;= 1.4.0, GDAL &gt;= 1.11, and ImageMagick. For example, to install these on a Linux system do <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">update;</span> <span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">splat</span> <span class="pre">gdal-bin</span> <span class="pre">python-gdal</span> <span class="pre">imagemagick</span></code></li>
 <li>Create a Python 3.5 virtual environment</li>
 <li>In your virtual environment, install Wavetrace via Pip via <code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">wavetrace</span></code></li>
 </ol>
@@ -212,8 +212,8 @@ <h2>wavetrace Package<a class="headerlink" href="#wavetrace-package" title="Perm
 
 <dl class="function">
 <dt id="wavetrace.main.compute_coverage">
-<code class="descclassname">wavetrace.main.</code><code class="descname">compute_coverage</code><span class="sig-paren">(</span><em>in_path</em>, <em>out_path</em>, <em>transmitters=None</em>, <em>receiver_sensitivity=-110</em>, <em>keep_ppm=False</em>, <em>high_definition=False</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.compute_coverage" title="Permalink to this definition">¶</a></dt>
-<dd><p>Run <a class="reference internal" href="#wavetrace.main.compute_coverage_0" title="wavetrace.main.compute_coverage_0"><code class="xref py py-func docutils literal"><span class="pre">compute_coverage_0()</span></code></a> and then run <code class="xref py py-func docutils literal"><span class="pre">post_process_coverage_0()</span></code>.</p>
+<code class="descclassname">wavetrace.main.</code><code class="descname">compute_coverage</code><span class="sig-paren">(</span><em>in_path</em>, <em>out_path</em>, <em>transmitters=None</em>, <em>receiver_sensitivity=-110</em>, <em>keep_ppm=False</em>, <em>high_definition=False</em>, <em>make_shp=False</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.compute_coverage" title="Permalink to this definition">¶</a></dt>
+<dd><p>Produce coverage reports by running <a class="reference internal" href="#wavetrace.main.compute_coverage_0" title="wavetrace.main.compute_coverage_0"><code class="xref py py-func docutils literal"><span class="pre">compute_coverage_0()</span></code></a> and then run <code class="xref py py-func docutils literal"><span class="pre">post_process_coverage_0()</span></code>.</p>
 </dd></dl>
 
 <dl class="function">
@@ -280,8 +280,9 @@ <h2>wavetrace Package<a class="headerlink" href="#wavetrace-package" title="Perm
 
 <dl class="function">
 <dt id="wavetrace.main.compute_satellite_los">
-<code class="descclassname">wavetrace.main.</code><code class="descname">compute_satellite_los</code><span class="sig-paren">(</span><em>in_path</em>, <em>satellite_lon</em>, <em>out_path</em>, <em>n=3</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.compute_satellite_los" title="Permalink to this definition">¶</a></dt>
-<dd><p>Given the path <code class="docutils literal"><span class="pre">in_path</span></code> to an SRTM1 or SRTM3 file and the longitude of a geostationary satellite, color with 8-bits of grayscale the raster cells according to whether they are in (whitish) or out (blackish) of the line-of-site of the satellite, and save the result as a GeoTIFF file located at <code class="docutils literal"><span class="pre">out_path</span></code>.</p>
+<code class="descclassname">wavetrace.main.</code><code class="descname">compute_satellite_los</code><span class="sig-paren">(</span><em>in_path</em>, <em>satellite_lon</em>, <em>out_path</em>, <em>n=3</em>, <em>make_shp=False</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.compute_satellite_los" title="Permalink to this definition">¶</a></dt>
+<dd><p>Given the path <code class="docutils literal"><span class="pre">in_path</span></code> to an SRTM1 or SRTM3 file and the longitude of a geostationary satellite, color with 8-bits of grayscale (pixel values from 0 to 255) the raster cells according to whether they are out (blackish, close to 0) or in (whitish, close to 255) of the line-of-site of the satellite, and save the result as a GeoTIFF file located at <code class="docutils literal"><span class="pre">out_path</span></code>.
+If <code class="docutils literal"><span class="pre">make_shp</span></code>, then also create an ESRI Shapefile bundle (.dbf, .prj, .shp, and .shx files) out of the GeoTIFF and save it to a similar path (same path stem but with Shapefile path suffixes).</p>
 <dl class="docutils">
 <dt>ALGORITHM: </dt>
 <dd><ol class="first last arabic simple">
@@ -295,22 +296,22 @@ <h2>wavetrace Package<a class="headerlink" href="#wavetrace-package" title="Perm
 <dt>NOTES:</dt>
 <dd><ul class="first last simple">
 <li>Calls <a class="reference internal" href="#wavetrace.main.get_geoid_height" title="wavetrace.main.get_geoid_height"><code class="xref py py-func docutils literal"><span class="pre">get_geoid_height()</span></code></a> <code class="docutils literal"><span class="pre">n**2</span></code> times. Because that function is currently implemented as an HTTP GET request, that slows things down and also introduces <code class="docutils literal"><span class="pre">n**2</span></code> opportunities for failure (raising a <code class="docutils literal"><span class="pre">ValueError</span></code>).</li>
+<li>To roughly interpret the output raster values as actual satellite signal strengths, one would need to obtain some actual on-the-ground satellite readings.</li>
 </ul>
 </dd>
 </dl>
 </dd></dl>
 
 <dl class="function">
 <dt id="wavetrace.main.download_topography">
-<code class="descclassname">wavetrace.main.</code><code class="descname">download_topography</code><span class="sig-paren">(</span><em>tile_ids</em>, <em>path</em>, <em>api_key</em>, <em>high_definition=False</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.download_topography" title="Permalink to this definition">¶</a></dt>
-<dd><p>Download from the Gitlab repository <a class="reference external" href="https://gitlab.com/araichev/srtm_nz">https://gitlab.com/araichev/srtm_nz</a> the SRTM1 or SRTM3 topography data corresponding to the given SRTM tile IDs and save the files to the directory <code class="docutils literal"><span class="pre">path</span></code>, creating the directory if it does not exist.</p>
+<code class="descclassname">wavetrace.main.</code><code class="descname">download_topography</code><span class="sig-paren">(</span><em>tile_ids</em>, <em>path</em>, <em>high_definition=False</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.download_topography" title="Permalink to this definition">¶</a></dt>
+<dd><p>Download from the public Gitlab repository <a class="reference external" href="https://gitlab.com/araichev/srtm_nz">https://gitlab.com/araichev/srtm_nz</a> the SRTM1 or SRTM3 topography data corresponding to the given SRTM tile IDs and save the files to the directory <code class="docutils literal"><span class="pre">path</span></code>, creating the directory if it does not exist.</p>
 <dl class="docutils">
 <dt>INPUT:</dt>
 <dd><ul class="first last simple">
 <li><code class="docutils literal"><span class="pre">tile_ids</span></code>: list of strings; SRTM tile IDs</li>
 <li><code class="docutils literal"><span class="pre">path</span></code>: string or Path object specifying a directory</li>
 <li><code class="docutils literal"><span class="pre">high_definition</span></code>: boolean; if <code class="docutils literal"><span class="pre">True</span></code> then download SRTM1 tiles; otherwise download SRTM3 tiles</li>
-<li><code class="docutils literal"><span class="pre">api_key</span></code>: string; a valid Gitlab API key (access token)</li>
 </ul>
 </dd>
 <dt>OUTPUT:</dt>
@@ -393,18 +394,20 @@ <h2>wavetrace Package<a class="headerlink" href="#wavetrace-package" title="Perm
 
 <dl class="function">
 <dt id="wavetrace.main.postprocess_coverage_0">
-<code class="descclassname">wavetrace.main.</code><code class="descname">postprocess_coverage_0</code><span class="sig-paren">(</span><em>path</em>, <em>keep_ppm</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.postprocess_coverage_0" title="Permalink to this definition">¶</a></dt>
+<code class="descclassname">wavetrace.main.</code><code class="descname">postprocess_coverage_0</code><span class="sig-paren">(</span><em>path</em>, <em>keep_ppm</em>, <em>make_shp</em><span class="sig-paren">)</span><a class="headerlink" href="#wavetrace.main.postprocess_coverage_0" title="Permalink to this definition">¶</a></dt>
 <dd><p>Using the PPM files in the directory <code class="docutils literal"><span class="pre">path</span></code> do the following:</p>
 <ul class="simple">
-<li>Convert each PPM files into a PNG file, replacing white with transparency using ImageMagick</li>
+<li>Convert each PPM file into a PNG file, replacing white with transparency using ImageMagick</li>
 <li>Change the PPM reference in each KML file to the corresponding PNG file</li>
 <li>Convert the PNG coverage file (not the legend file) into GeoTIFF using GDAL</li>
+<li>Optionally create ESRI Shapefile bundles (.dbf, .prj, .shp, and .shx files) from the GeoTIFF files</li>
 </ul>
 <dl class="docutils">
 <dt>INPUT:</dt>
 <dd><ul class="first last simple">
 <li><code class="docutils literal"><span class="pre">path</span></code>: string or Path object; directory where coverage reports (outputs of <a class="reference internal" href="#wavetrace.main.compute_coverage" title="wavetrace.main.compute_coverage"><code class="xref py py-func docutils literal"><span class="pre">compute_coverage()</span></code></a>) lie</li>
 <li><code class="docutils literal"><span class="pre">keep_ppm</span></code>: boolean; keep the original, large PPM files in the coverage reports if and only if this flag is <code class="docutils literal"><span class="pre">True</span></code></li>
+<li><code class="docutils literal"><span class="pre">make_shp</span></code>: boolean; create ESRI Shapefiles from the GeoTIFF files if and only if this flag is <code class="docutils literal"><span class="pre">True</span></code></li>
 </ul>
 </dd>
 <dt>OUTPUT:</dt>

docs/conf.py

@@ -61,7 +61,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = '3.0'
+version = '4.0'
 # The full version, including alpha/beta/rc tags.
 #release = '3.0'
 

docs/introduction.rst

@@ -23,7 +23,7 @@ Wavetrace is intended for use in New Zealand but can be configured to work elsew
 
 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 imagemagick``
+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``
 

requirements.txt

@@ -1,35 +1,38 @@
 alabaster==0.7.9
 Babel==2.3.4
 beautifulsoup4==4.5.1
+bleach==1.5.0
 click==6.6
 decorator==4.0.10
 docutils==0.12
 entrypoints==0.2.2
 geographiclib==1.46.3
+html5lib==0.9999999
 imagesize==0.7.1
-ipykernel==4.3.1
-ipython==5.0.0
+ipykernel==4.5.2
+ipython==5.1.0
 ipython-genutils==0.1.0
 ipywidgets==5.2.2
-Jinja2==2.8
+Jinja2==2.9.4
 jsonschema==2.5.1
 jupyter==1.0.0
-jupyter-client==4.3.0
+jupyter-client==4.4.0
 jupyter-console==5.0.0
-jupyter-core==4.1.0
+jupyter-core==4.2.1
 MarkupSafe==0.23
 mistune==0.7.3
-nbconvert==4.2.0
-nbformat==4.0.1
+nbconvert==5.0.0
+nbformat==4.2.0
 nose==1.3.7
-notebook==4.2.1
-pexpect==4.2.0
-pickleshare==0.7.3
-prompt-toolkit==1.0.3
+notebook==4.3.1
+pandocfilters==1.4.1
+pexpect==4.2.1
+pickleshare==0.7.4
+prompt-toolkit==1.0.9
 ptyprocess==0.5.1
 Pygments==2.1.3
 pytz==2016.6.1
-pyzmq==15.3.0
+pyzmq==16.0.2
 qtconsole==4.2.1
 requests==2.10.0
 Shapely==1.5.16
@@ -38,7 +41,8 @@ six==1.10.0
 snowballstemmer==1.2.1
 Sphinx==1.4.5
 terminado==0.6
-tornado==4.4.1
-traitlets==4.2.2
+testpath==0.3
+tornado==4.4.2
+traitlets==4.3.1
 wcwidth==0.1.7
 widgetsnbextension==1.2.6

setup.py

@@ -1,14 +1,22 @@
-from distutils.core import setup
+from setuptools import setup, find_packages
+
+
+with open('README.rst') as f:
+    readme = f.read()
+
+with open('LICENSE.txt') as f:
+    license = f.read()
 
 setup(
     name='wavetrace',
-    version='3.0.0',
+    version='4.0.0',
     author='Alex Raichev',
-    packages=['wavetrace', 'tests'],
+    packages=find_packages(exclude=('tests', 'docs')),
     url='https://github.com/nzrs/wavetrace',
-    license='LICENSE',
+    license=license,
+    data_files = [('', ['LICENSE.txt'])],
     description='Python 3.5 tools to produce radio signal coverage reports, mostly for New Zealand',
-    long_description=open('README.rst').read(),
+    long_description=readme,
     install_requires=[
         'requests>=2.10.0',
         'Shapely>=1.5.16',

tests/context.py

@@ -0,0 +1,5 @@
+import sys
+import os
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
+
+import wavetrace