rustywx is a desktop weather app that streams live NEXRAD Level II Doppler data straight from NOAA's public AWS archive and renders it on a pannable, zoomable map — reflectivity, velocity, and spectrum width — layered with live NWS warning polygons, National Hurricane Center tropical guidance, and a local forecast.

✨ Features

• 📡 Live Level II data — pulls the newest volume scans from the public unidata-nexrad-level2 S3 bucket. No AWS account, no API key.
• 🗺️ Pannable radar map — radar echoes rendered over a zoomable geographic basemap with cities and state / county borders.
• 🎨 Three products — Reflectivity, Velocity, and Spectrum Width, on NWS-style color tables.
• 🎚️ Tilt selector — step through elevation angles with live VCP and Nyquist-velocity readout.
• ⚠️ NWS alerts — tornado / severe-thunderstorm warning and watch polygons overlaid in real time, with live counts.
• 🌀 Tropical guidance — National Hurricane Center tracks, forecast cones, wind probabilities, and graphics products (5-day cone, key messages, wind field, peak surge) with the full public advisory text.
• 🌤️ Local forecast — city search, current conditions, a 7-day outlook, and an hourly rain-chance chart.
• 🧹 TDBZ clutter filter — knock out wind-turbine and ground clutter, with adjustable sensitivity.
• ⏱️ Auto-refresh — configurable poll interval (default 2 min) with smooth animation between volumes.
• ⌨️ Keyboard-driven — full shortcut overlay (press ?).

🚀 Quick Start

cargo install rustywx
rustywx

That's it — no credentials, no config. rustywx opens on KJGX (Robins AFB, Macon GA) and starts pulling live scans. You need a Rust toolchain (rustup) and network access.

Prefer not to build? Grab a prebuilt binary from the Releases page.

📑 Table of Contents

• Features
• Quick Start
• Why rustywx
• Installation
• Usage
• Products & Controls
• Architecture
• Contributing
• License
• Acknowledgements

🤔 Why rustywx

Weather-radar viewers tend to be either heavyweight desktop suites or browser tabs at the mercy of a vendor's tile server. rustywx is a small, fast, native alternative: it talks directly to the same public Level II archive the pros use, decodes the raw Doppler volumes locally, and renders them on the GPU with the ply-engine graphics framework. Point it at a NEXRAD site and you have a self-contained radarscope — no subscriptions, no telemetry, no middleman.

📦 Installation

From crates.io (recommended)

Requires a stable Rust toolchain (edition 2024, Rust 1.85+).

cargo install rustywx
rustywx

Prebuilt release binaries

Prebuilt binaries for Linux (x86-64 / ARM64), macOS (Apple Silicon), and Windows (x86-64) are attached to each GitHub Release. Download, unpack, and run.

From source (for development)

git clone https://github.com/kerryhatcher/rustywx
cd rustywx
just run          # or: cd app && cargo run --release

just run launches from the app/ directory so runtime assets resolve correctly during development. See CONTRIBUTING.md.

Platform notes

Platform	Notes
macOS	Apple Silicon builds are published; Intel builds from source.
Linux	Needs a GPU/Vulkan-capable environment and standard build tooling (build-essential, pkg-config).
Windows	x86-64 build published.

The app renders on the GPU via ply-engine, so a working graphics stack is required — headless servers won't display a window.

🛠️ Usage

rustywx                                     # launch the scope

Developing on rustywx? Run the tests from the repo:

cargo test                                  # unit tests, no network
cargo test --test network -- --ignored      # live end-to-end fetch/decode

On launch, rustywx opens on your default site and begins polling. Switch products, change tilt, and toggle overlays from the toolbar or the keyboard. Open the ⚙️ settings panel to change the default site, poll interval, overlay defaults, animation level, and clutter-filter sensitivity — settings persist across restarts.

See the User Guide for a full walkthrough of the display, how to read each product, and every setting.

🎛️ Products & Controls

Product	Shows	Reading it
Reflectivity	Precipitation intensity	Red/magenta = heavy rain or hail; green/blue = light.
Velocity	Radial motion	Green = toward radar (inbound); red = away (outbound).
Spectrum Width	Velocity dispersion	High values flag turbulence, shear, and rotation.

Press ? in-app for the full keyboard-shortcut overlay (product selection, tilt control, overlay toggles, settings, quit).

🏗️ Architecture

The app is the rustywx crate under app/, on the ply-engine backend:

Module	Responsibility
main.rs	App entry, async game loop, frame drawing
state.rs	App state — selected site, overlays, animation
data.rs	Background worker: poll S3 → download → decode → channel
model.rs	Thin scan model (product → sweeps → radials → gates)
scope.rs	PPI rasterizer and overlay painting
colors.rs	NWS-style color tables
geo.rs	Range/bearing and polar → screen projection
cities.rs, borders.rs	Scope overlays — city markers, state boundaries
alerts.rs, nhc.rs	NWS alerts and NHC tropical overlays
cache.rs, rle.rs	Ply-storage scan cache + RLE compression
widgets/	Reusable glass-panel UI widgets

Design docs live in docs/. For build/test/lint commands and how to extend the app, see CONTRIBUTING.md.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for dev setup, the module map, and the build/test/lint workflow, and please read our Code of Conduct. Security issues? See SECURITY.md.

💬 Support

• Bugs & feature requests: open an issue
• Questions & ideas: GitHub Discussions
• Changelog: see CHANGELOG.md or the Releases page

📄 License

• Code: AGPL-3.0-only
• Custom graphics, artwork, and assets: CC BY-SA 4.0

🙏 Acknowledgements

• NOAA / Unidata for the public unidata-nexrad-level2 Level II archive on AWS.
• NWS for the alerts feed and NHC for tropical-cyclone products.
• Open-Meteo (open-meteo/open-meteo) for the forecast and geocoding APIs behind the Forecast view.
• The nexrad crates (nexrad-data, nexrad-model) that decode the raw Level II volumes.
• Built with ply-engine, the graphics framework powering the UI and rendering.