cusfpredict 0.2.1__tar.gz → 0.3.0__tar.gz

cusfpredict-0.3.0/MANIFEST.in

@@ -0,0 +1,3 @@
+# Include the license file
+include LICENSE.txt
+

cusfpredict-0.3.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: cusfpredict
+Version: 0.3.0
+Summary: Python Wrapper for the CUSF High-Altitude Balloon Predictor
+Keywords: horus balloon prediction gfs
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastkml
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: pytz
+Requires-Dist: shapely
+Requires-Dist: python-dateutil
+Requires-Dist: xarray
+Requires-Dist: cfgrib>=0.9.8
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# CUSF Standalone Predictor - Python Wrapper
+This is a semi-fork of the [CUSF Standalone Predictor](https://github.com/jonsowman/cusf-standalone-predictor/), which provides a Python wrapper around the predictor binary, and provides a means of gathering the requisite wind data.
+
+2018-02 Update: Wind downloader updated to use the [NOMADS GRIB Filter](http://nomads.ncep.noaa.gov/txt_descriptions/grib_filter_doc.shtml), as the OpenDAP interface stopped working. As such, we no longer require PyDAP, but we do now require GDAL to read in the GRIB2 files.
+
+2021-03 Update: We have dropped GDAL in favour of cfgrib. 
+
+2026-06 Update: A range of updates for support of newer libraries (e.g. numpy, fastkml), and better packaging. The minimum supported Python version is now 3.9.
+
+## 1. System Dependencies
+The Python package installs its Python dependencies automatically. You still need the system libraries used by the wind-data reader and the standalone C predictor.
+
+On a Raspbian/Ubuntu/Debian system, you can get most of the required dependencies using:
+```
+$ sudo apt-get install git cmake build-essential libglib2.0-dev python3-numpy python3-requests python3-dateutil python3-pip libeccodes-data libeccodes0 libgeos-dev libatlas-base-dev
+```
+
+On macOS with Homebrew:
+```
+$ brew install cmake glib eccodes geos
+```
+
+## 2. Install the Python Wrapper
+
+### From PyPI
+Install into a virtual environment:
+```
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install cusfpredict
+```
+
+Python 2 is not supported.
+
+### From Source, Editable Mode (Only required if you are experimenting with changes in this library)
+For development, clone this repository and install it in editable mode:
+```
+$ git clone https://github.com/darksidelemm/cusf_predictor_wrapper.git
+$ cd cusf_predictor_wrapper
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install -e .
+```
+
+If you only want to install the source checkout without editable mode, use:
+```
+$ python -m pip install .
+```
+
+If Python dependency installation fails, the same dependencies are listed in `requirements.txt` and can be installed explicitly:
+```
+$ python -m pip install -r requirements.txt
+```
+
+The package depends on Shapely and ecCodes-backed GRIB readers. If installation fails with missing headers or missing shared libraries, install the system dependencies above and retry.
+
+
+## 3. Building the Predictor Binary
+The predictor itself is a binary (`pred`), which is built separately using CMake. The Python package does not currently build or install this binary for you.
+
+From within the cusf_predictor_wrapper directory, run the following to build the predictor binary:
+
+```
+$ cmake -S src -B src/build
+$ cmake --build src/build
+```
+
+The `pred` binary then needs to be copied somewhere useful. For the example scripts in `apps`, copy it into that directory:
+```
+$ cp src/build/pred apps/
+```
+
+If you are building this utility for use with chasemapper, then you should copy `pred` into the chasemapper directory:
+```
+$ cp src/build/pred ~/chasemapper/
+```
+
+A pre-compiled Windows binary of the predictor is available here: http://rfhead.net/horus/cusf_standalone_predictor.zip
+Use at your own risk!
+
+
+## 4. Getting Wind Data
+The predictor binary uses a custom wind data format, extracted from NOAA's Global Forecast System wind models. The `cusfpredict.gfs` Python module pulls down and formats the relevant data from NOAA's [NOMADS](http://nomads.ncep.noaa.gov) server.
+
+If you are using this library with ChaseMapper, you will need to adjust the download command in the [chasemapper configuration file](https://github.com/projecthorus/chasemapper/blob/master/horusmapper.cfg.example#L135).
+
+An example of running it is as follows:
+```
+$ python3 -m cusfpredict.gfs --lat=-33 --lon=139 --latdelta=10 --londelta=10 -f 24 -m 0p50 -o gfs
+```
+
+The command line arguments are as follows:
+```
+Area of interest:
+     --lat       Latitude (Decimal Degrees) of the centre of the area to gather.
+     --lon         Longitude (Decimal Degrees) of the centre of the area to gather.
+     --latdelta    Gather data from lat+/-latdelta
+     --londelta    Gather data from lon+/-londelta
+
+   Time of interest:
+     -f X   Gather data up to X hours into the future, from the start of the most recent model. (Note that this can be up to 8 hours in the past.) Make sure you get enough for the flight!   
+   
+   GFS Model Choice:
+     -m <model>    Choose between either:
+           0p50  - 0.5 Degree Spatial, 3-hour Time Resolution
+           0p25_1hr - 0.25 Degree Spatial, 1-hour Time Resolution (default)
+
+   Other settings:
+     -v  Verbose output
+     -o output_dir     (Where to save the gfs data to, defaults to ./gfs/)
+```
+
+The higher resolution wind model you choose, the larger the amount of data to download, and the longer it will take. It also increases the prediction calculation time (though not significantly).
+
+`wind_grabber.sh` is an example script to automatically grab wind data first to a temporary directory, and then to the final gfs directory. This could be run from a cronjob to keep the wind data up-to-date.
+
+New wind models become available approximately every 6 hours, approximately 4 hours after the model's nominal time (i.e. the 00Z model becomes available around 04Z). Information on the status of the GFS model generation is available here: http://www.nco.ncep.noaa.gov/pmb/nwprod/prodstat_new/
+
+## 5. Using the Predictor
+(Note: This section is intended for users within to run predictions from within their own software. If you are just installing this library for use with chasemapper, you can skip all of this!)
+
+The basic usage of the predictor from within Python is as follows:
+```
+import datetime
+from cusfpredict.predict import Predictor
+
+pred = Predictor(bin_path='./pred', gfs_path='./gfs')
+
+flight_path = pred.predict(
+    launch_lat=-34.9499,
+    launch_lon=138.5194,
+    launch_alt=0.0,
+    ascent_rate=5.0,
+    descent_rate=5.0,
+    burst_alt=30000,
+    launch_time=datetime.datetime.now(datetime.timezone.utc)
+    )
+
+```
+
+Note that the launch time is a datetime object interpreted as UTC, so make sure you convert your launch time as appropriate.
+
+The output is a list-of-lists, containing entries of [utctimestamp, lat, lon, alt], i.e.:
+
+```
+>>> flight_path
+[[1516702953, -34.9471, 138.517, 250.0], [1516703003, -34.9436, 138.514, 500.0], <etc>, [1516703053, -34.9415, 138.513, 750.0]]
+```
+
+There is also a command-line utility, `predict.py`, which allows performing predictions with launch parameter variations:
+```
+usage: predict.py [-h] [-a ASCENTRATE] [-d DESCENTRATE] [-b BURSTALT]
+                  [--launchalt LAUNCHALT] [--latitude LATITUDE]
+                  [--longitude LONGITUDE] [--time TIME] [-o OUTPUT]
+                  [--altitude_deltas ALTITUDE_DELTAS]
+                  [--time_deltas TIME_DELTAS] [--absolute]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -a ASCENTRATE, --ascentrate ASCENTRATE
+                        Ascent Rate (m/s). Default 5m/s
+  -d DESCENTRATE, --descentrate DESCENTRATE
+                        Descent Rate (m/s). Default 5m/s
+  -b BURSTALT, --burstalt BURSTALT
+                        Burst Altitude (m). Default 30000m
+  --launchalt LAUNCHALT
+                        Launch Altitude (m). Default 0m
+  --latitude LATITUDE   Launch Latitude (dd.dddd)
+  --longitude LONGITUDE
+                        Launch Longitude (dd.dddd)
+  --time TIME           Launch Time (string, UTC). Default = Now
+  -o OUTPUT, --output OUTPUT
+                        Output KML File. Default = prediction.kml
+  --altitude_deltas ALTITUDE_DELTAS
+                        Comma-delimited list of altitude deltas. (metres).
+  --time_deltas TIME_DELTAS
+                        Comma-delimited list of time deltas. (hours)
+  --absolute            Show absolute altitudes for tracks and placemarks.
+```
+
+For example, to predict a radiosonde launch from Adelaide Airport (5m/s ascent, 26km burst, 7.5m/s descent), but to look at what happens if the burst altitude is higher or lower than usual:
+```
+$ python3 predict.py --latitude=-34.9499 --longitude=138.5194 -a 5 -d 7.5 -b 26000 --time "2018-01-27 11:15Z" --altitude_deltas="-2000,0,2000"
+Running using GFS Model: gfs20180127-00z
+2018-01-27T11:15:00+00:00 5.0/24000.0/7.5 - Landing: -34.8585, 138.9600 at 2018-01-27T13:03:33
+2018-01-27T11:15:00+00:00 5.0/26000.0/7.5 - Landing: -34.8587, 138.8870 at 2018-01-27T13:11:01
+2018-01-27T11:15:00+00:00 5.0/28000.0/7.5 - Landing: -34.8598, 138.7990 at 2018-01-27T13:18:22
+KML written to prediction.kml
+```
+
+A few other example scripts are located in the 'apps' directory:
+ * basic_usage.py - Example showing how to write a predicted flight path out to a KML file
+ * sonde_predict.py - A more complex example, where predictions for the next week's of radiosonde flights are run and written to a KML file.
+
+

cusfpredict-0.3.0/README.md

@@ -0,0 +1,197 @@
+# CUSF Standalone Predictor - Python Wrapper
+This is a semi-fork of the [CUSF Standalone Predictor](https://github.com/jonsowman/cusf-standalone-predictor/), which provides a Python wrapper around the predictor binary, and provides a means of gathering the requisite wind data.
+
+2018-02 Update: Wind downloader updated to use the [NOMADS GRIB Filter](http://nomads.ncep.noaa.gov/txt_descriptions/grib_filter_doc.shtml), as the OpenDAP interface stopped working. As such, we no longer require PyDAP, but we do now require GDAL to read in the GRIB2 files.
+
+2021-03 Update: We have dropped GDAL in favour of cfgrib. 
+
+2026-06 Update: A range of updates for support of newer libraries (e.g. numpy, fastkml), and better packaging. The minimum supported Python version is now 3.9.
+
+## 1. System Dependencies
+The Python package installs its Python dependencies automatically. You still need the system libraries used by the wind-data reader and the standalone C predictor.
+
+On a Raspbian/Ubuntu/Debian system, you can get most of the required dependencies using:
+```
+$ sudo apt-get install git cmake build-essential libglib2.0-dev python3-numpy python3-requests python3-dateutil python3-pip libeccodes-data libeccodes0 libgeos-dev libatlas-base-dev
+```
+
+On macOS with Homebrew:
+```
+$ brew install cmake glib eccodes geos
+```
+
+## 2. Install the Python Wrapper
+
+### From PyPI
+Install into a virtual environment:
+```
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install cusfpredict
+```
+
+Python 2 is not supported.
+
+### From Source, Editable Mode (Only required if you are experimenting with changes in this library)
+For development, clone this repository and install it in editable mode:
+```
+$ git clone https://github.com/darksidelemm/cusf_predictor_wrapper.git
+$ cd cusf_predictor_wrapper
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install -e .
+```
+
+If you only want to install the source checkout without editable mode, use:
+```
+$ python -m pip install .
+```
+
+If Python dependency installation fails, the same dependencies are listed in `requirements.txt` and can be installed explicitly:
+```
+$ python -m pip install -r requirements.txt
+```
+
+The package depends on Shapely and ecCodes-backed GRIB readers. If installation fails with missing headers or missing shared libraries, install the system dependencies above and retry.
+
+
+## 3. Building the Predictor Binary
+The predictor itself is a binary (`pred`), which is built separately using CMake. The Python package does not currently build or install this binary for you.
+
+From within the cusf_predictor_wrapper directory, run the following to build the predictor binary:
+
+```
+$ cmake -S src -B src/build
+$ cmake --build src/build
+```
+
+The `pred` binary then needs to be copied somewhere useful. For the example scripts in `apps`, copy it into that directory:
+```
+$ cp src/build/pred apps/
+```
+
+If you are building this utility for use with chasemapper, then you should copy `pred` into the chasemapper directory:
+```
+$ cp src/build/pred ~/chasemapper/
+```
+
+A pre-compiled Windows binary of the predictor is available here: http://rfhead.net/horus/cusf_standalone_predictor.zip
+Use at your own risk!
+
+
+## 4. Getting Wind Data
+The predictor binary uses a custom wind data format, extracted from NOAA's Global Forecast System wind models. The `cusfpredict.gfs` Python module pulls down and formats the relevant data from NOAA's [NOMADS](http://nomads.ncep.noaa.gov) server.
+
+If you are using this library with ChaseMapper, you will need to adjust the download command in the [chasemapper configuration file](https://github.com/projecthorus/chasemapper/blob/master/horusmapper.cfg.example#L135).
+
+An example of running it is as follows:
+```
+$ python3 -m cusfpredict.gfs --lat=-33 --lon=139 --latdelta=10 --londelta=10 -f 24 -m 0p50 -o gfs
+```
+
+The command line arguments are as follows:
+```
+Area of interest:
+     --lat       Latitude (Decimal Degrees) of the centre of the area to gather.
+     --lon         Longitude (Decimal Degrees) of the centre of the area to gather.
+     --latdelta    Gather data from lat+/-latdelta
+     --londelta    Gather data from lon+/-londelta
+
+   Time of interest:
+     -f X   Gather data up to X hours into the future, from the start of the most recent model. (Note that this can be up to 8 hours in the past.) Make sure you get enough for the flight!   
+   
+   GFS Model Choice:
+     -m <model>    Choose between either:
+           0p50  - 0.5 Degree Spatial, 3-hour Time Resolution
+           0p25_1hr - 0.25 Degree Spatial, 1-hour Time Resolution (default)
+
+   Other settings:
+     -v  Verbose output
+     -o output_dir     (Where to save the gfs data to, defaults to ./gfs/)
+```
+
+The higher resolution wind model you choose, the larger the amount of data to download, and the longer it will take. It also increases the prediction calculation time (though not significantly).
+
+`wind_grabber.sh` is an example script to automatically grab wind data first to a temporary directory, and then to the final gfs directory. This could be run from a cronjob to keep the wind data up-to-date.
+
+New wind models become available approximately every 6 hours, approximately 4 hours after the model's nominal time (i.e. the 00Z model becomes available around 04Z). Information on the status of the GFS model generation is available here: http://www.nco.ncep.noaa.gov/pmb/nwprod/prodstat_new/
+
+## 5. Using the Predictor
+(Note: This section is intended for users within to run predictions from within their own software. If you are just installing this library for use with chasemapper, you can skip all of this!)
+
+The basic usage of the predictor from within Python is as follows:
+```
+import datetime
+from cusfpredict.predict import Predictor
+
+pred = Predictor(bin_path='./pred', gfs_path='./gfs')
+
+flight_path = pred.predict(
+    launch_lat=-34.9499,
+    launch_lon=138.5194,
+    launch_alt=0.0,
+    ascent_rate=5.0,
+    descent_rate=5.0,
+    burst_alt=30000,
+    launch_time=datetime.datetime.now(datetime.timezone.utc)
+    )
+
+```
+
+Note that the launch time is a datetime object interpreted as UTC, so make sure you convert your launch time as appropriate.
+
+The output is a list-of-lists, containing entries of [utctimestamp, lat, lon, alt], i.e.:
+
+```
+>>> flight_path
+[[1516702953, -34.9471, 138.517, 250.0], [1516703003, -34.9436, 138.514, 500.0], <etc>, [1516703053, -34.9415, 138.513, 750.0]]
+```
+
+There is also a command-line utility, `predict.py`, which allows performing predictions with launch parameter variations:
+```
+usage: predict.py [-h] [-a ASCENTRATE] [-d DESCENTRATE] [-b BURSTALT]
+                  [--launchalt LAUNCHALT] [--latitude LATITUDE]
+                  [--longitude LONGITUDE] [--time TIME] [-o OUTPUT]
+                  [--altitude_deltas ALTITUDE_DELTAS]
+                  [--time_deltas TIME_DELTAS] [--absolute]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -a ASCENTRATE, --ascentrate ASCENTRATE
+                        Ascent Rate (m/s). Default 5m/s
+  -d DESCENTRATE, --descentrate DESCENTRATE
+                        Descent Rate (m/s). Default 5m/s
+  -b BURSTALT, --burstalt BURSTALT
+                        Burst Altitude (m). Default 30000m
+  --launchalt LAUNCHALT
+                        Launch Altitude (m). Default 0m
+  --latitude LATITUDE   Launch Latitude (dd.dddd)
+  --longitude LONGITUDE
+                        Launch Longitude (dd.dddd)
+  --time TIME           Launch Time (string, UTC). Default = Now
+  -o OUTPUT, --output OUTPUT
+                        Output KML File. Default = prediction.kml
+  --altitude_deltas ALTITUDE_DELTAS
+                        Comma-delimited list of altitude deltas. (metres).
+  --time_deltas TIME_DELTAS
+                        Comma-delimited list of time deltas. (hours)
+  --absolute            Show absolute altitudes for tracks and placemarks.
+```
+
+For example, to predict a radiosonde launch from Adelaide Airport (5m/s ascent, 26km burst, 7.5m/s descent), but to look at what happens if the burst altitude is higher or lower than usual:
+```
+$ python3 predict.py --latitude=-34.9499 --longitude=138.5194 -a 5 -d 7.5 -b 26000 --time "2018-01-27 11:15Z" --altitude_deltas="-2000,0,2000"
+Running using GFS Model: gfs20180127-00z
+2018-01-27T11:15:00+00:00 5.0/24000.0/7.5 - Landing: -34.8585, 138.9600 at 2018-01-27T13:03:33
+2018-01-27T11:15:00+00:00 5.0/26000.0/7.5 - Landing: -34.8587, 138.8870 at 2018-01-27T13:11:01
+2018-01-27T11:15:00+00:00 5.0/28000.0/7.5 - Landing: -34.8598, 138.7990 at 2018-01-27T13:18:22
+KML written to prediction.kml
+```
+
+A few other example scripts are located in the 'apps' directory:
+ * basic_usage.py - Example showing how to write a predicted flight path out to a KML file
+ * sonde_predict.py - A more complex example, where predictions for the next week's of radiosonde flights are run and written to a KML file.
+
+

{cusfpredict-0.2.1 → cusfpredict-0.3.0}/cusfpredict/__init__.py

@@ -5,4 +5,4 @@
 #   Copyright 2020 Mark Jessop <vk5qi@rfhead.net>
 #
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{cusfpredict-0.2.1 → cusfpredict-0.3.0}/cusfpredict/utils.py

@@ -10,6 +10,11 @@ import datetime
 import os.path
 from shapely.geometry import Point, LineString
 
+try:
+    from fastkml.enums import AltitudeMode
+except ImportError:
+    AltitudeMode = None
+
 def available_gfs(gfs_path='./gfs'):
     """ Determine the time extent of the GFS dataset """
 
@@ -30,8 +35,8 @@ def available_gfs(gfs_path='./gfs'):
 
     _timestamps.sort()
 
-    start_time = datetime.datetime.utcfromtimestamp(_timestamps[0])
-    end_time = datetime.datetime.utcfromtimestamp(_timestamps[-1])
+    start_time = datetime.datetime.fromtimestamp(_timestamps[0], datetime.timezone.utc)
+    end_time = datetime.datetime.fromtimestamp(_timestamps[-1], datetime.timezone.utc)
 
     return (start_time, end_time)
 
@@ -56,6 +61,38 @@ def gfs_model_age(gfs_path="./gfs"):
 # Geometry and KML related stuff
 ns = '{http://www.opengis.net/kml/2.2}'
 
+def _kml_altitude_mode(altitude_mode):
+    """Return an altitude mode value compatible with the installed fastkml."""
+
+    if AltitudeMode is None or not isinstance(altitude_mode, str):
+        return altitude_mode
+
+    for mode in AltitudeMode:
+        if altitude_mode in (mode.name, mode.value):
+            return mode
+
+    return altitude_mode
+
+
+def _kml_geometry(geometry, **kwargs):
+    """Create a fastkml geometry across old and new fastkml APIs."""
+
+    if hasattr(fastkml.geometry, "create_kml_geometry"):
+        if "altitude_mode" in kwargs:
+            kwargs["altitude_mode"] = _kml_altitude_mode(kwargs["altitude_mode"])
+        return fastkml.geometry.create_kml_geometry(geometry, ns=ns, **kwargs)
+
+    return fastkml.geometry.Geometry(ns=ns, geometry=geometry, **kwargs)
+
+
+def _set_placemark_geometry(placemark, geometry, **kwargs):
+    kml_geometry = _kml_geometry(geometry, **kwargs)
+
+    if hasattr(fastkml.geometry, "create_kml_geometry"):
+        placemark.kml_geometry = kml_geometry
+    else:
+        placemark.geometry = kml_geometry
+
 def flight_path_to_linestring(flight_path):
     ''' Convert a predicted flight path to a LineString geometry object '''
 
@@ -105,9 +142,9 @@ def flight_path_to_geometry(flight_path,
         name=comment,
         styles=[flight_track_style])
 
-    flight_line.geometry = fastkml.geometry.Geometry(
-        ns=ns,
-        geometry=flight_path_to_linestring(flight_path),
+    _set_placemark_geometry(
+        flight_line,
+        flight_path_to_linestring(flight_path),
         altitude_mode=altitude_mode,
         extrude=True,
         tessellate=True)
@@ -136,9 +173,9 @@ def flight_path_landing_placemark(flight_path,
         description="",
         styles=[flight_style])
 
-    flight_placemark.geometry = fastkml.geometry.Geometry(
-        ns=ns,
-        geometry=Point(flight_path[-1][2], flight_path[-1][1], flight_path[-1][3]),
+    _set_placemark_geometry(
+        flight_placemark,
+        Point(flight_path[-1][2], flight_path[-1][1], flight_path[-1][3]),
         altitude_mode='clampToGround')
 
     return flight_placemark
@@ -175,9 +212,9 @@ def flight_path_burst_placemark(flight_path,
             current_index = i
 
 
-    flight_placemark.geometry = fastkml.geometry.Geometry(
-        ns=ns,
-        geometry=Point(flight_path[current_index][2], flight_path[current_index][1], flight_path[current_index][3]),
+    _set_placemark_geometry(
+        flight_placemark,
+        Point(flight_path[current_index][2], flight_path[current_index][1], flight_path[current_index][3]),
         altitude_mode=altitude_mode)
 
     return flight_placemark
@@ -200,8 +237,10 @@ def write_flight_path_kml(flight_data,
     for _flight in flight_data:
         kml_doc.append(_flight)
 
+    kml_root.append(kml_doc)
+
     with open(filename,'w') as kml_file:
-        kml_str = kml_doc.to_string()
+        kml_str = kml_root.to_string()
         if kml_hack:
             kml_str = kml_str.replace('kml:','').replace(':kml','')
         kml_file.write(kml_str)

cusfpredict-0.3.0/cusfpredict.egg-info/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: cusfpredict
+Version: 0.3.0
+Summary: Python Wrapper for the CUSF High-Altitude Balloon Predictor
+Keywords: horus balloon prediction gfs
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastkml
+Requires-Dist: requests
+Requires-Dist: numpy
+Requires-Dist: pytz
+Requires-Dist: shapely
+Requires-Dist: python-dateutil
+Requires-Dist: xarray
+Requires-Dist: cfgrib>=0.9.8
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary
+
+# CUSF Standalone Predictor - Python Wrapper
+This is a semi-fork of the [CUSF Standalone Predictor](https://github.com/jonsowman/cusf-standalone-predictor/), which provides a Python wrapper around the predictor binary, and provides a means of gathering the requisite wind data.
+
+2018-02 Update: Wind downloader updated to use the [NOMADS GRIB Filter](http://nomads.ncep.noaa.gov/txt_descriptions/grib_filter_doc.shtml), as the OpenDAP interface stopped working. As such, we no longer require PyDAP, but we do now require GDAL to read in the GRIB2 files.
+
+2021-03 Update: We have dropped GDAL in favour of cfgrib. 
+
+2026-06 Update: A range of updates for support of newer libraries (e.g. numpy, fastkml), and better packaging. The minimum supported Python version is now 3.9.
+
+## 1. System Dependencies
+The Python package installs its Python dependencies automatically. You still need the system libraries used by the wind-data reader and the standalone C predictor.
+
+On a Raspbian/Ubuntu/Debian system, you can get most of the required dependencies using:
+```
+$ sudo apt-get install git cmake build-essential libglib2.0-dev python3-numpy python3-requests python3-dateutil python3-pip libeccodes-data libeccodes0 libgeos-dev libatlas-base-dev
+```
+
+On macOS with Homebrew:
+```
+$ brew install cmake glib eccodes geos
+```
+
+## 2. Install the Python Wrapper
+
+### From PyPI
+Install into a virtual environment:
+```
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install cusfpredict
+```
+
+Python 2 is not supported.
+
+### From Source, Editable Mode (Only required if you are experimenting with changes in this library)
+For development, clone this repository and install it in editable mode:
+```
+$ git clone https://github.com/darksidelemm/cusf_predictor_wrapper.git
+$ cd cusf_predictor_wrapper
+$ python3 -m venv venv
+$ source venv/bin/activate
+$ python -m pip install --upgrade pip
+$ python -m pip install -e .
+```
+
+If you only want to install the source checkout without editable mode, use:
+```
+$ python -m pip install .
+```
+
+If Python dependency installation fails, the same dependencies are listed in `requirements.txt` and can be installed explicitly:
+```
+$ python -m pip install -r requirements.txt
+```
+
+The package depends on Shapely and ecCodes-backed GRIB readers. If installation fails with missing headers or missing shared libraries, install the system dependencies above and retry.
+
+
+## 3. Building the Predictor Binary
+The predictor itself is a binary (`pred`), which is built separately using CMake. The Python package does not currently build or install this binary for you.
+
+From within the cusf_predictor_wrapper directory, run the following to build the predictor binary:
+
+```
+$ cmake -S src -B src/build
+$ cmake --build src/build
+```
+
+The `pred` binary then needs to be copied somewhere useful. For the example scripts in `apps`, copy it into that directory:
+```
+$ cp src/build/pred apps/
+```
+
+If you are building this utility for use with chasemapper, then you should copy `pred` into the chasemapper directory:
+```
+$ cp src/build/pred ~/chasemapper/
+```
+
+A pre-compiled Windows binary of the predictor is available here: http://rfhead.net/horus/cusf_standalone_predictor.zip
+Use at your own risk!
+
+
+## 4. Getting Wind Data
+The predictor binary uses a custom wind data format, extracted from NOAA's Global Forecast System wind models. The `cusfpredict.gfs` Python module pulls down and formats the relevant data from NOAA's [NOMADS](http://nomads.ncep.noaa.gov) server.
+
+If you are using this library with ChaseMapper, you will need to adjust the download command in the [chasemapper configuration file](https://github.com/projecthorus/chasemapper/blob/master/horusmapper.cfg.example#L135).
+
+An example of running it is as follows:
+```
+$ python3 -m cusfpredict.gfs --lat=-33 --lon=139 --latdelta=10 --londelta=10 -f 24 -m 0p50 -o gfs
+```
+
+The command line arguments are as follows:
+```
+Area of interest:
+     --lat       Latitude (Decimal Degrees) of the centre of the area to gather.
+     --lon         Longitude (Decimal Degrees) of the centre of the area to gather.
+     --latdelta    Gather data from lat+/-latdelta
+     --londelta    Gather data from lon+/-londelta
+
+   Time of interest:
+     -f X   Gather data up to X hours into the future, from the start of the most recent model. (Note that this can be up to 8 hours in the past.) Make sure you get enough for the flight!   
+   
+   GFS Model Choice:
+     -m <model>    Choose between either:
+           0p50  - 0.5 Degree Spatial, 3-hour Time Resolution
+           0p25_1hr - 0.25 Degree Spatial, 1-hour Time Resolution (default)
+
+   Other settings:
+     -v  Verbose output
+     -o output_dir     (Where to save the gfs data to, defaults to ./gfs/)
+```
+
+The higher resolution wind model you choose, the larger the amount of data to download, and the longer it will take. It also increases the prediction calculation time (though not significantly).
+
+`wind_grabber.sh` is an example script to automatically grab wind data first to a temporary directory, and then to the final gfs directory. This could be run from a cronjob to keep the wind data up-to-date.
+
+New wind models become available approximately every 6 hours, approximately 4 hours after the model's nominal time (i.e. the 00Z model becomes available around 04Z). Information on the status of the GFS model generation is available here: http://www.nco.ncep.noaa.gov/pmb/nwprod/prodstat_new/
+
+## 5. Using the Predictor
+(Note: This section is intended for users within to run predictions from within their own software. If you are just installing this library for use with chasemapper, you can skip all of this!)
+
+The basic usage of the predictor from within Python is as follows:
+```
+import datetime
+from cusfpredict.predict import Predictor
+
+pred = Predictor(bin_path='./pred', gfs_path='./gfs')
+
+flight_path = pred.predict(
+    launch_lat=-34.9499,
+    launch_lon=138.5194,
+    launch_alt=0.0,
+    ascent_rate=5.0,
+    descent_rate=5.0,
+    burst_alt=30000,
+    launch_time=datetime.datetime.now(datetime.timezone.utc)
+    )
+
+```
+
+Note that the launch time is a datetime object interpreted as UTC, so make sure you convert your launch time as appropriate.
+
+The output is a list-of-lists, containing entries of [utctimestamp, lat, lon, alt], i.e.:
+
+```
+>>> flight_path
+[[1516702953, -34.9471, 138.517, 250.0], [1516703003, -34.9436, 138.514, 500.0], <etc>, [1516703053, -34.9415, 138.513, 750.0]]
+```
+
+There is also a command-line utility, `predict.py`, which allows performing predictions with launch parameter variations:
+```
+usage: predict.py [-h] [-a ASCENTRATE] [-d DESCENTRATE] [-b BURSTALT]
+                  [--launchalt LAUNCHALT] [--latitude LATITUDE]
+                  [--longitude LONGITUDE] [--time TIME] [-o OUTPUT]
+                  [--altitude_deltas ALTITUDE_DELTAS]
+                  [--time_deltas TIME_DELTAS] [--absolute]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -a ASCENTRATE, --ascentrate ASCENTRATE
+                        Ascent Rate (m/s). Default 5m/s
+  -d DESCENTRATE, --descentrate DESCENTRATE
+                        Descent Rate (m/s). Default 5m/s
+  -b BURSTALT, --burstalt BURSTALT
+                        Burst Altitude (m). Default 30000m
+  --launchalt LAUNCHALT
+                        Launch Altitude (m). Default 0m
+  --latitude LATITUDE   Launch Latitude (dd.dddd)
+  --longitude LONGITUDE
+                        Launch Longitude (dd.dddd)
+  --time TIME           Launch Time (string, UTC). Default = Now
+  -o OUTPUT, --output OUTPUT
+                        Output KML File. Default = prediction.kml
+  --altitude_deltas ALTITUDE_DELTAS
+                        Comma-delimited list of altitude deltas. (metres).
+  --time_deltas TIME_DELTAS
+                        Comma-delimited list of time deltas. (hours)
+  --absolute            Show absolute altitudes for tracks and placemarks.
+```
+
+For example, to predict a radiosonde launch from Adelaide Airport (5m/s ascent, 26km burst, 7.5m/s descent), but to look at what happens if the burst altitude is higher or lower than usual:
+```
+$ python3 predict.py --latitude=-34.9499 --longitude=138.5194 -a 5 -d 7.5 -b 26000 --time "2018-01-27 11:15Z" --altitude_deltas="-2000,0,2000"
+Running using GFS Model: gfs20180127-00z
+2018-01-27T11:15:00+00:00 5.0/24000.0/7.5 - Landing: -34.8585, 138.9600 at 2018-01-27T13:03:33
+2018-01-27T11:15:00+00:00 5.0/26000.0/7.5 - Landing: -34.8587, 138.8870 at 2018-01-27T13:11:01
+2018-01-27T11:15:00+00:00 5.0/28000.0/7.5 - Landing: -34.8598, 138.7990 at 2018-01-27T13:18:22
+KML written to prediction.kml
+```
+
+A few other example scripts are located in the 'apps' directory:
+ * basic_usage.py - Example showing how to write a predicted flight path out to a KML file
+ * sonde_predict.py - A more complex example, where predictions for the next week's of radiosonde flights are run and written to a KML file.
+
+

cusfpredict-0.3.0/cusfpredict.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+./cusfpredict/__init__.py
+./cusfpredict/gfs.py
+./cusfpredict/predict.py
+./cusfpredict/reader.py
+./cusfpredict/utils.py
+cusfpredict/__init__.py
+cusfpredict/gfs.py
+cusfpredict/predict.py
+cusfpredict/reader.py
+cusfpredict/utils.py
+cusfpredict.egg-info/PKG-INFO
+cusfpredict.egg-info/SOURCES.txt
+cusfpredict.egg-info/dependency_links.txt
+cusfpredict.egg-info/requires.txt
+cusfpredict.egg-info/top_level.txt

cusfpredict-0.3.0/cusfpredict.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

cusfpredict-0.3.0/cusfpredict.egg-info/requires.txt

@@ -0,0 +1,8 @@
+fastkml
+requests
+numpy
+pytz
+shapely
+python-dateutil
+xarray
+cfgrib>=0.9.8

cusfpredict-0.3.0/cusfpredict.egg-info/top_level.txt

@@ -0,0 +1 @@
+cusfpredict

cusfpredict-0.3.0/pyproject.toml

@@ -0,0 +1,20 @@
+[tool.poetry]
+name = "cusfpredict"
+version = "0.3.0"
+description = "CUSF Predictor Wrapper & GFS Downloader"
+authors = ["Mark Jessop"]
+
+[tool.poetry.dependencies]
+python = "^3.9"            # last actively maintained version of Python
+fastkml = "^1"
+requests = "^2.25.1"
+numpy = "^2.0.0"
+pytz = "^2025.1"
+shapely = "^2.0.0"
+python-dateutil = "^2.8.1"
+xarray = "*"
+cfgrib = "^0.9.8"
+
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"

cusfpredict-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cusfpredict-0.3.0/setup.py

@@ -0,0 +1,44 @@
+import os
+import re
+from setuptools import setup, find_packages
+
+regexp = re.compile(r".*__version__ = [\'\"](.*?)[\'\"]", re.S)
+
+init_file = os.path.join(os.path.dirname(__file__), "cusfpredict", "__init__.py")
+with open(init_file, "r") as f:
+    module_content = f.read()
+    match = regexp.match(module_content)
+    if match:
+        version = match.group(1)
+    else:
+        raise RuntimeError(f"Cannot find __version__ in {init_file}")
+
+
+with open("README.md", "r") as f:
+    readme = f.read()
+
+
+with open("requirements.txt", "r") as f:
+    requirements = []
+    for line in f.read().split("\n"):
+        line = line.strip()
+        if line and not line.startswith("#"):
+            requirements.append(line)
+
+
+if __name__ == "__main__":
+    setup(
+        name="cusfpredict",
+        description="Python Wrapper for the CUSF High-Altitude Balloon Predictor",
+        long_description=readme,
+        long_description_content_type="text/markdown",
+        version=version,
+        install_requires=requirements,
+        keywords=["horus balloon prediction gfs"],
+        package_dir={"": "."},
+        packages=find_packages("."),
+        classifiers=[
+            "Intended Audience :: Developers",
+            "Programming Language :: Python :: 3.9"
+        ]
+    )

cusfpredict-0.2.1/PKG-INFO

@@ -1,18 +0,0 @@
-Metadata-Version: 2.1
-Name: cusfpredict
-Version: 0.2.1
-Summary: CUSF Predictor Wrapper & GFS Downloader
-Author: Mark Jessop
-Requires-Python: >=3.6,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
-Requires-Dist: cfgrib (>=0.9.8,<0.10.0)
-Requires-Dist: fastkml (>=0.11,<0.12)
-Requires-Dist: numpy (>=1.17,<2.0)
-Requires-Dist: python-dateutil (>=2.8.1,<3.0.0)
-Requires-Dist: pytz (>=2020.5,<2021.0)
-Requires-Dist: requests (>=2.25.1,<3.0.0)
-Requires-Dist: shapely (>=1.7.1,<2.0.0)
-Requires-Dist: xarray (>=0.16.2,<0.17.0)

cusfpredict-0.2.1/pyproject.toml

@@ -1,22 +0,0 @@
-[tool.poetry]
-name = "cusfpredict"
-version = "0.2.1"
-description = "CUSF Predictor Wrapper & GFS Downloader"
-authors = ["Mark Jessop"]
-
-[tool.poetry.dependencies]
-python = "^3.6"
-fastkml = "^0.11"
-requests = "^2.25.1"
-numpy = "^1.17"
-pytz = "^2020.5"
-shapely = "^1.7.1"
-python-dateutil = "^2.8.1"
-xarray = "^0.16.2"
-cfgrib = "^0.9.8"
-
-[tool.poetry.dev-dependencies]
-
-[build-system]
-requires = ["setuptools","poetry>=0.12"]
-build-backend = "poetry.masonry.api"

cusfpredict-0.2.1/setup.py

@@ -1,37 +0,0 @@
-# -*- coding: utf-8 -*-
-from setuptools import setup
-
-packages = \
-['cusfpredict']
-
-package_data = \
-{'': ['*']}
-
-install_requires = \
-['cfgrib>=0.9.8,<0.10.0',
- 'fastkml>=0.11,<0.12',
- 'numpy>=1.17,<2.0',
- 'python-dateutil>=2.8.1,<3.0.0',
- 'pytz>=2020.5,<2021.0',
- 'requests>=2.25.1,<3.0.0',
- 'shapely>=1.7.1,<2.0.0',
- 'xarray>=0.16.2,<0.17.0']
-
-setup_kwargs = {
-    'name': 'cusfpredict',
-    'version': '0.2.1',
-    'description': 'CUSF Predictor Wrapper & GFS Downloader',
-    'long_description': None,
-    'author': 'Mark Jessop',
-    'author_email': None,
-    'maintainer': None,
-    'maintainer_email': None,
-    'url': None,
-    'packages': packages,
-    'package_data': package_data,
-    'install_requires': install_requires,
-    'python_requires': '>=3.6,<4.0',
-}
-
-
-setup(**setup_kwargs)