Merge pull request #11 from scottstanie/bilinear-python

Bilinear python

.github/workflows/deploy-to-pypi.yml

@@ -1,70 +1,42 @@
-name: Build and upload to PyPI
+# https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+name: Publish to PyPI and TestPyPI
 
-# Build on every branch push, tag push, and pull request change:
-on: [push, pull_request]
-# Alternatively, to publish when a (published) GitHub Release is created, use the following:
-# on:
-#   push:
-#   pull_request:
-#   release:
-#     types:
-#       - published
+on: push
 
 jobs:
-  build_wheels:
-    name: Build wheels on ${{ matrix.os }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        # os: [ubuntu-20.04, windows-2019, macOS-10.15]
-        os: [ubuntu-20.04, macos-10.15]
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-python@v2
-        name: Install Python
-
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v2.1.1
-
-      - uses: actions/upload-artifact@v2
-        with:
-          path: ./wheelhouse/*.whl
-
-  build_sdist:
-    name: Build source distribution
+  build-n-publish:
+    name: Build and publish Python 🐍 distributions 📦 to PyPI and TestPyPI
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-python@v2
-        name: Install Python
-        with:
-          python-version: '3.8'
-
-      - name: Build sdist
-        run: python setup.py sdist
-
-      - uses: actions/upload-artifact@v2
-        with:
-          path: dist/*.tar.gz
-
-  upload_pypi:
-    needs: [build_wheels, build_sdist]
-    runs-on: ubuntu-latest
-    # upload to PyPI on every tag starting with 'v'
-    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags/v')
-    # alternatively, to publish when a GitHub Release is created, use the following rule:
-    # if: github.event_name == 'release' && github.event.action == 'published'
-    steps:
-      - uses: actions/download-artifact@v2
-        with:
-          name: artifact
-          path: dist
-
-      - uses: pypa/gh-action-pypi-publish@v1.4.2
-        with:
-          user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
-          # To test: repository_url: https://test.pypi.org/legacy/
+    - uses: actions/checkout@master
+    - name: Set up Python 3
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.x"
+    - name: Install pypa/build
+      run: >-
+        python -m
+        pip install
+        build
+        --user
+    - name: Build a binary wheel and a source tarball
+      run: >-
+        python -m
+        build
+        --sdist
+        --wheel
+        --outdir dist/
+        .
+    - name: Publish distribution 📦 to Test PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      if: github.ref == 'refs/heads/master'
+      with:
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        repository_url: https://test.pypi.org/legacy/
+        verbose: true
+    - name: Publish distribution 📦 to PyPI
+      if: startsWith(github.ref, 'refs/tags')
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        password: ${{ secrets.PYPI_API_TOKEN }}
+        verbose: true

.github/workflows/pytest.yml

@@ -0,0 +1,34 @@
+# https://github.com/marketplace/actions/setup-miniconda#example-6-mamba
+# https://github.com/bopen/xarray-sentinel/blob/main/.github/workflows/on-push.yml
+name: Test installation with pytest
+
+# Build on every branch push, tag push, and pull request change:
+on: [push, pull_request]
+
+jobs:
+  test:
+    name: Run tests with pytest
+    defaults:
+      run:
+        shell: bash -l {0}
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install Conda environment with Micromamba
+      uses: mamba-org/provision-with-micromamba@v12
+      with:
+        environment-file: environment.yml
+        environment-name: DEVELOP
+        channels: conda-forge
+        cache-env: true
+        cache-env-key: ubuntu-latest-3.10
+        extra-specs: |
+          python=3.10
+    - name: Install package
+      run: |
+        python -m pip install --no-deps -e .
+        python -m pip install -r requirements-dev.txt
+    - name: Run tests
+      run: |
+        pytest --doctest-modules -v

.gitignore

@@ -3,8 +3,9 @@
 
 # Don't add huge DEM data files
 *.hgt
-*.dem
+*.dem.*
 *.dem.rsc
+*.hdr
 
 # Directories for setup.py
 build
@@ -24,3 +25,4 @@ data/
 
 
 .ipynb_checkpoints
+.vscode

MANIFEST.in

@@ -1,4 +1 @@
 include README.md
-include sardem/cython/*.c
-include sardem/cython/*.pyx
-include sardem/cython/*.pxd

Makefile

@@ -13,8 +13,8 @@ install-edit:
 	pip install -e .
 
 test:
-	@echo "Running doctests and unittests: nose must be installed"
-	nosetests -v --with-doctest
+	@echo "Running doctests and pytest"
+	pytest -v --doctest-modules
 
 clean:
 	rm -f *.so
@@ -24,5 +24,5 @@ REPO?=pypi  # Set if not speficied (as pypitest, e.g.)
 
 upload:
 	rm -rf dist
-	python setup.py sdist
-	twine upload dist/*.tar.gz -r $(REPO)
+	python setup.py sdist bdist_wheel
+	twine upload dist/* -r $(REPO)

README.md

@@ -1,26 +1,24 @@
 
-# DEM creator
+# sardem
 
-Tool for making Digital Elevation Maps (DEMs) in binary data format (16-bit integers, little endian) for use in Interferometric SAR (InSAR) processing
+A tool for making Digital Elevation Maps (DEMs) in binary data format (16-bit integers, little endian) for use in interferometric synthetic aperture radar (InSAR) processing (e.g. using [isce2](https://github.com/isce-framework/isce2).
 
-`sardem` creates a cropped (and possibly upsampled) digital elevation map:
+The `sardem` command creates a cropped (and possibly upsampled) digital elevation map:
 
 ```bash
 usage: sardem [-h] [--bbox left bottom right top] [--geojson GEOJSON] [--wkt-file WKT_FILE] [--xrate XRATE] [--yrate YRATE] [--output OUTPUT] [--data-source {NASA,NASA_WATER,COP}] [-isce] [--keep-egm] [--shift-rsc]
               [left_lon] [top_lat] [dlon] [dlat]
 ```
 
-The default data source, `--data-source NASA`, uses the SRTM 1 arcsecond data. You can also use the newer [Copernicus Digital Surface Model (DSM)](https://registry.opendata.aws/copernicus-dem/). 
-To see a comparison of the two, see the [srtm_copernicus_comparison](notebooks/srtm_copernicus_comparison.ipynb) notebook.
-
-**Note** To convert the elevation values to heights about the WGS84 ellipsoid (which is the default), or to use the Copernicus data, **GDAL is required**. 
-For the Copernicus data, the minimum required GDAL version is 3.4.2; versions earlier than 3.4.0 seem to hang upon using `gdalwarp` on the global VRT, and <3.4.2 have an internal bug https://github.com/isce-framework/isce2/issues/556 .
-
-
-See below for installation:
-
 ## Setup and installation
 
+Using conda:
+```bash
+conda install -c conda-forge sardem
+# Or, if mamba is installed, mamba install -c conda-forge sardem
+```
+
+Using pip:
 ```bash
 pip install sardem
 ```
@@ -31,22 +29,34 @@ Alternatively, you can clone to build/install:
 ```bash
 git clone https://github.com/scottstanie/sardem
 cd sardem
-make
+# Install requirements using either pip or conda
+# conda install -c conda-forge --file environment.yml
+# pip install -r requirements.txt
+# the conda environment.yml is more complete, as GDAL is required for some of the functionality
+pip install -e .
 ```
 which will run `pip install --upgrade .` and create the command line script.
 
 
-If you use `virtualenv`
-```bash
-# Optional for using virtualenv
-virtualenv ~/envs/sardem && source ~/envs/sardem/bin/activate  # Or wherever you store your virtual envs
-# Or if you have virtualenv wrapper: mkvirtualenv sardem
-pip install sardem
-```
+## Data sources
+The default data source, `--data-source NASA`, uses the SRTM 1 arcsecond data. You can also use the newer [Copernicus Digital Surface Model (DSM)](https://registry.opendata.aws/copernicus-dem/). 
+To see a comparison of the two, see the [srtm_copernicus_comparison](notebooks/srtm_copernicus_comparison.ipynb) notebook.
+
+**Note:** To convert the elevation values to heights about the WGS84 ellipsoid (which is the default), or to use the Copernicus data, **GDAL is required**. 
+For the Copernicus data, the minimum required GDAL version is 3.4.2; versions earlier than 3.4.0 seem to hang upon using `gdalwarp` on the global VRT, and <3.4.2 have an internal bug https://github.com/isce-framework/isce2/issues/556 .
+
+
+## Bounding box convention
+
+`sardem` uses the gdal convention ("pixel is area") where `--bbox` points to the *edges* of the [left, bottom, right, top] pixels.
+I.e. (left, bottom) refers to the lower left corner of the lower left pixel.
+
+
 
 ### Converting to WGS84 ellipsoidal heights from EGM96/EGM2008 geoid heights
 
-GDAL is required for the conversion, which is most easily installed using `conda` (or `mamba`):
+GDAL is required for the conversion, which is installed when using `conda install -c conda-forge sardem`.
+If you already are using an existing environment, make sure that the GDAL version is >=3.4.2.
 
 ```bash 
 conda install -c conda-forge "gdal>=3.4.2"
@@ -62,18 +72,22 @@ conda install -c conda-forge "gdal>=3.4.2"
 The full options for the command line tool in `sardem/cli.py` can be found using
 
 ```
-$ sardem --help
-sardem -h
+$ sardem -h
 usage: sardem [-h] [--bbox left bottom right top] [--geojson GEOJSON] [--wkt-file WKT_FILE] [--xrate XRATE] [--yrate YRATE] [--output OUTPUT] [--data-source {NASA,NASA_WATER,COP}] [-isce] [--keep-egm] [--shift-rsc]
+              [--cache-dir CACHE_DIR]
               [left_lon] [top_lat] [dlon] [dlat]
 
 Stiches SRTM .hgt files to make (upsampled) DEM
 
     Pick a lat/lon bounding box for a DEM, and it will download
     the necessary SRTM1 tiles, stitch together, then upsample.
 
+    The `--bbox` convention points to the *edges* of the [left, bottom, right, top]
+    pixels, following the "pixel is area" convention as used in gdal.
+    I.e. (left, bottom) refers to the lower left corner of the lower left pixel.
+
     Usage Examples:
-        sardem --bbox -156 18.8 -154.7 20.3  # bounding box: left  bottom  right top
+        sardem --bbox -156 18.8 -154.7 20.3  # bounding box: [left  bottom  right top]
         sardem -156.0 20.2 1 2 --xrate 2 --yrate 2  # Makes a box 1 degree wide, 2 deg high
         sardem --bbox -156 18.8 -154.7 20.3 --data-source COP  # Copernicus DEM
         sardem --geojson dem_area.geojson -x 11 -y 3 # Use geojson file to define area
@@ -93,6 +107,8 @@ options:
   -h, --help            show this help message and exit
   --bbox left bottom right top
                         Bounding box of area of interest  (e.g. --bbox -106.1 30.1 -103.1 33.1 ).
+                        --bbox points to the *edges* of the pixels,
+                         following the 'pixel is area' convention as used in gdal.
   --geojson GEOJSON, -g GEOJSON
                         Alternate to corner/dlon/dlat box specification:
                         File containing the geojson object for DEM bounds
@@ -110,15 +126,12 @@ options:
                         Make an isce2 XML file for the DEM.
   --keep-egm            Keep the DEM heights as geoid heights above EGM96 or EGM2008. Default is to convert to WGS84 for InSAR processing.
   --shift-rsc           Shift the .rsc file by half a pixel so that X_FIRST and Y_FIRST are at the pixel center (instead of GDAL's convention of the top left edge). Default is GDAL's top-left edge convention.
+  --cache-dir CACHE_DIR
+                        Location to save downloaded files (Default = /Users/staniewi/.cache/sardem)
 ```
 
-The code used for bilinear interpolation in the upsampling routine is in `cython/upsample.c`, and is wrapped in [cython](http://docs.cython.org/en/latest/) to allow easier installation and ability to call the function from Python.
-The installation is handled through `pip install`, or by running `make build`.
-
-Functions for working with digital elevation maps (DEMs) are mostly contained in the `Downloader` and `Stitcher` classes within `sardem/dem.py` and `sardem/download.py`.
-
 
-### NASA SRTM Data access
+## NASA SRTM Data access
 
 The default data source is NASA's Shuttle Radar Topography Mission (SRTM) version 3 global 1 degree data.
 See https://lpdaac.usgs.gov/dataset_discovery/measures/measures_products_table/srtmgl3s_v003 .

environment.yml

@@ -0,0 +1,8 @@
+channels:
+- conda-forge
+dependencies:
+- python >= 3.6
+- gdal >= 3.4.2
+- numpy >= 1.14.2
+- requests >= 2.20.0
+- pip