Merge pull request #228 from ASFHyP3/osmium-dep

osmium-tool dependency missing for asf-tools PyPI distribution bug

CHANGELOG.md

@@ -6,15 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/) 
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [0.7.1]
+
+### Added
+- A description of the `asf_tools.watermasking` sub-package has been added to the [`asf_tools` README](src/asf_tools/README.md)
+- Installation instructions for `osmium-tool` have been added to the [`asf_tools.watermasking` README](src/asf_tools/watermasking/README.md)
+
+### Fixed
+- `osmium-tool` dependency handling. Because `osmium-tool` is not distributed on PyPI and thus is not installed when `pip` installing `asf_tools`, `asf_tools` will now raise an `ImportError` when `osmium-tool` is missing that provides installation instructions. Note: `osmium-tool` is distributed on conda-forge and will be included when conda installing `asf_tools`.
+
 ## [0.7.0]
 
 ## Added
 * Scripts and entrypoints for generating our global watermasking dataset added to `watermasking`.
 
-
 ## [0.6.0]
 
-## Added
+### Added
 * You can choose whether the `ts` (threat score; default) or `fmi` (Fowlkes-Mallows index) minimization metric is used for the flood mapping iterative estimator:
   * the `flood_map` console script entrypoint now accepts a `--minimization-metric` argument
   * the  `asf_tools.hydrosar.floopd_map.make_flood_map` function now accepts a `minimization_metric` keyword argument

pyproject.toml

@@ -27,6 +27,7 @@ dependencies = [
     "gdal>=3.3",
     "geopandas",
     "numpy",
+    # "osmium-tool", # C++ CLI tool available via conda-forge or 'https://osmcode.org/osmium-tool/', used by `asf_tools.watermasking.generate_osm_tiles`.
     "pyogrio",
     "pysheds>=0.3",
     "rasterio",

src/asf_tools/README.md

@@ -161,3 +161,10 @@ flood_map --help
 ```
 
 For details on the algorithm see the `asf_tools.flood_map.make_flood_map` docstring.
+
+### Water Mask Dataset Generation
+
+The `asf_tools.watermasking` sub-package allows you to create a watermasking dataset 
+over an arbitrary ROI using OpenStreetMap and ESA WorldCover data.
+Note, this program requires `osmium-tool`. See [README.md](watermasking/README.md) 
+for more information on setup and usage.

src/asf_tools/watermasking/README.MD → src/asf_tools/watermasking/README.md

@@ -2,12 +2,13 @@ These scripts are for creating a global (or regional) water mask dataset based o
 
 For the OSM water mask dataset, follow these steps to replicate our dataset:
 
-1. Download the "Latest Weekly Planet PBF File" file from here: "https://planet.openstreetmap.org/".
-2. Download the WGS84 water polygons shapefile from: "https://osmdata.openstreetmap.de/data/water-polygons.html".
-3. The files should be unzipped and you should have something like `planet.osm.pbf` or `planet.pbf` and `water_polygons.shp` (and the support files for `water_polygons.shp`). 
-4. Run ```generate_osm_dataset --planet-file-path [path-to-planet.pbf] --ocean-polygons-path [path-to-water-polygons.shp] --lat-begin -85 --lat-end 85 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
-5. Run ```fill_missing_tiles --fill-value 0 --lat-begin -90 --lat-end -85 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
-6. Run ```fill_missing_tiles --fill-value 1 --lat-begin 85 --lat-end 90 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
+1. Install osmium-tool from conda-forge or "https://osmcode.org/osmium-tool/".
+2. Download the "Latest Weekly Planet PBF File" file from here: "https://planet.openstreetmap.org/".
+3. Download the WGS84 water polygons shapefile from: "https://osmdata.openstreetmap.de/data/water-polygons.html".
+4. The files should be unzipped and you should have something like `planet.osm.pbf` or `planet.pbf` and `water_polygons.shp` (and the support files for `water_polygons.shp`). 
+5. Run ```generate_osm_dataset --planet-file-path [path-to-planet.pbf] --ocean-polygons-path [path-to-water-polygons.shp] --lat-begin -85 --lat-end 85 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
+6. Run ```fill_missing_tiles --fill-value 0 --lat-begin -90 --lat-end -85 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
+7. Run ```fill_missing_tiles --fill-value 1 --lat-begin 85 --lat-end 90 --lon-begin -180 --lon-end 180 --tile-width 5 --tile-height 5```
 
 For the WorldCover water mask dataset, follow these steps:
 

src/asf_tools/watermasking/generate_osm_tiles.py

@@ -202,6 +202,11 @@ def main():
 
     args = parser.parse_args()
 
+    try:
+        subprocess.run(['osmium', '--help'], check=True, stdout=subprocess.DEVNULL)
+    except subprocess.CalledProcessError:
+        raise ImportError('osmium-tool must be installed to run this program: https://osmcode.org/osmium-tool/.')
+
     lat_begin = int(args.lat_begin)
     lat_end = int(args.lat_end)
     lon_begin = int(args.lon_begin)