NEXRAD Radar Loop Generator

This utility will generate a base map and any number of the most recent NEXRAD radar imagery frames, with the primary purpose of presenting an animated loop in HTML (but you could use the map and frames however you like).

It uses python-awips to pull raw NEXRAD level III radar data from the EDEX server maintained by UCAR's Unidata Program Center in Boulder, Colorado.

Installation

The instructions below assume Linux or macOS. The same should work in Windows, but the commands will be slightly different.

First, grab a copy of the utility:

git clone https://github.com/MaffooClock/MrRadar.git

Docker

The easiest way to run this utility is with Docker, which guarantees that you won't have any dependency issues.

1. First, build the image:

   docker build -t mr_radar:latest .

2. Then run it (minimal command to output --help):

   docker run -t --rm mr_radar:latest

Conda

Conda make managing Python environments easy.

1. Start by creating the environment, which will also install the required dependencies:

   cd MrRadar
   conda env create -f environment.yml 

2. Activate the environment:

   conda activate mr_radar

3. Then run it:

   python3 -m run mr_radar --help

Pip

And for those who prefer using good ol' Pip... of course, doing this in a Python venv (virtual environment) is recommended:

1. Create the venv:

   cd MrRadar
   python -m venv .venv

2. Activate the venv:

   source .venv/bin/activate

3. Install the dependencies

   python3 -m pip install -r requirements.txt

4. Then run it:

   python3 -m run mr_radar --help

Usage

The instructions below show running this utility with just mr_radar, but the actual invocation will depend on whether you installed via Docker or Conda/Pip, so adjust accordingly.

Positional arguments

There are two positional arguments that are required:

mr_radar <command> <site>

Command:

1. map: generate the geographical map that will serve as the background to the NEXRAD imagery frames
2. frames: generate one or more NEXRAD image frames
3. dump-products: Dump a list of valid radar products to the console for the given site without generating any imagery

Typically, the map command is only ever needed once; the only time you'd want to run it again would be for a different site or radius. The frames command would then be executed at some interval to have the latest quantity of frames available at all times.

Site:

This is the four-letter site code (known as the ICAO) of the radar site from which you want to use NEXRAD data. Consult the NWS Radar Operations Center for various methods on finding available radar sites.

Optional Arguments

Here are the flags with explanations of each:

[!TIP] When running in Docker, don't forget to map the /data directory within the container to a local path, or you won't get any of the generated images:

docker run -t --rm --volume $(pwd)/out:/data mr_radar:latest <command> <site_id>

Example Usage

Generate a map with a 150-mile radius centered around KSJT:

mr_radar map KSJT

This will result in a new PNG file at ./out/ksjt/map.png.

Generate 12 of the latest NEXRAD frames for the same location and radius:

mr_radar frames KSJT

This will result in 12 new PNG files at ./out/ksjt/frame_0.png through ./out/ksjt/frame_11.png.

Data Caching

You will also find a new JSON file (./out/ksjt.json, in this example) in the root output path, which contains the command-line arguments you supplied, as well as additional derived information based on the site ID and radius.

Here's what it's good for:

1. This makes subsequent runs faster and more efficient by re-using information rather than having to make repeated requests for information that would never change (such as radar site coordinates, for instance).
2. You will no longer need any of the optional command-line arguments on subsequent runs; those values will be read from this file if they are not present on the command line.

Deleting this file won't hurt anything, but it's not a necessary task in the course of normal use.

Using in HTML

Check out the html directory for a basic example of how to "animate" the frames on top of the base map.

The example HTML will work out-of-the-box if you run the utility with:

1. default root file path (./out)
2. default file names (map.png and frame_<i>.png).
3. specify --images . to save generated images in the root path

Otherwise, you'll need to tweak the loop.html file to make it work.

To view the animated loop after generating the map and NEXRAD frames, simply open the loop.html file in your browser (no web server needed to test-drive locally).

[!IMPORTANT] The example HTML files aren't intended to be deployed as-is to your website, they're just an example to show how to create an animated loop effect (but you may certainly copy/paste to your heart's desire).