Space Weather — Omarchy bar plugin

A Kp-index pill for the Omarchy (Quattro) bar that answers the only question most of us have about geomagnetic activity: is it worth stepping outside tonight? Click it for a popup with these tabs:

• Now — the Kp index as a bar per 3-hour block, a day of readings running into NOAA's forecast, with the storm threshold and the Kp your location needs drawn across it. Below that, whether the aurora reaches you right now, how long the sky stays dark, and the solar wind numbers that decide the next few hours.
• Aurora — NOAA's OVATION aurora model drawn as a polar map: the real oval over a real coastline, with a marker where you are. Plus the model's own probability for your cell, where the oval's edge sits on your meridian, and the Kp you need for a horizon view and for an overhead one.
• Forecast — the full three-day Kp forecast, and a per-day verdict that says "reaches you" on the days that clear your threshold.
• Sun — radio blackout and radiation storm scales, 10.7 cm solar flux, the latest X-ray flare and the last week of them. Optionally, HF propagation conditions by band.

The pill turns the theme's attention colour during a geomagnetic storm, or whenever the aurora is genuinely reachable from where you are and the sky is already dark. An optional desktop notification does the same thing louder.

Everything comes from NOAA SWPC over plain curl. No API key, no account, no telemetry.

Requirements

• Omarchy Quattro (v4) with omarchy-shell (Quickshell-based bar)
• curl, grep, awk and bash on PATH
• A Nerd Font in the bar (Omarchy ships one) for the aurora glyph

Install

omarchy plugin add https://github.com/Snackwrap/omarchy-spacewx.git --enable
omarchy bar move com.leafbox.spacewx right

Location

The aurora half of this plugin needs to know where you are. It takes the first of these it finds:

1. latitude / longitude in the widget's own settings, or
2. the location you already set for the built-in weather widget, via omarchy-weather-location.

So if your bar already knows where you live, this plugin does too. Note that bare omarchy-weather-location only prints the current location — to set one:

omarchy-weather-location --set "Seattle" 47.61,-122.33   # name and coordinates
omarchy-weather-location --set "Seattle"                 # name only; geocoded

Either works. The weather widget is happy with a name alone because wttr.in resolves names itself, so --set <name> stores no coordinates; this plugin needs numbers, and looks a bare name up through the same geocoding service the weather panel uses for its own location search. Picking a location inside the weather popup stores coordinates directly and needs no lookup.

To give this widget its own coordinates instead:

omarchy bar set com.leafbox.spacewx latitude 47.61
omarchy bar set com.leafbox.spacewx longitude -122.33
omarchy restart shell

Any setting in the table below is set the same way, and an empty value falls back to the default — so omarchy bar set com.leafbox.spacewx latitude "" returns you to inheriting the weather location. (Omarchy has no settings UI for bar widgets yet; the manifest declares a schema for the one that is coming.)

With no location at all the plugin still shows Kp, the forecast and solar activity — it just can't tell you what any of it means for your own sky.

Local development

Fork the repo and check out your copy, then from inside it:

./deploy-local.sh                     # symlink into ~/.config/omarchy/plugins + validate
omarchy plugin enable com.leafbox.spacewx right
omarchy restart shell                 # reload after each edit (rescanPlugins alone
                                      # won't reload changed QML — the shell caches it)

Uninstall

omarchy plugin disable com.leafbox.spacewx
omarchy plugin remove com.leafbox.spacewx
omarchy restart shell

Settings

Interaction

How it works

• BarWidget.qml — the bar-slot button and popout-identity shim.
• Panel.qml — fetches from NOAA via Quickshell Process, derives what it means for your location, and renders the popup.
• spacewx.js — the maths: geomagnetic coordinates, the auroral oval, solar position. Pure functions with no Qt types, so the test harness can run them under node.
• AuroraMap.qml — the polar map, drawn on one Canvas.
• KpChart.qml — the Kp bars and their reference lines.
• coast.js — a decimated coastline per hemisphere, built from Natural Earth by tools/build-coast.py.
• tools/capture-preview.sh drives the popup over IPC to refresh assets/screenshot.png; tools/promo.html insets that into preview.png, the card at the top of this README.

Bandwidth

Everything except the aurora map is tiny — the solar wind summaries are about 60 bytes each, and the whole Kp history plus three-day forecast is one 7 KB file. The OVATION grid is different: 65,000 cells, roughly 1 MB, republished every 5 minutes.

So the map is fetched deliberately rather than continuously. On the default auto setting it updates when you open the panel, and otherwise only while it is dark where you are and something is actually happening (Kp 2 or above, or a storm in progress). Panel only drops the background updates entirely; Never hides the map.

The megabyte also never reaches the QML interpreter. grep splits the grid one cell per line and awk reduces it to the three things the panel draws — the probability at your cell, the equatorward edge of the oval on your meridian, and a downsampled grid for the map — so what gets parsed is a few kilobytes. The grid thins out toward the pole, because meridians converge there and a fixed longitude step would pile every sample into an ink-black disc in the middle of the plot.

Accuracy, and where it ends

The aurora numbers are a model, and it is worth knowing which parts are NOAA's and which are this plugin's arithmetic.

NOAA's, and as good as the source: the Kp index and its forecast, the G/R/S scales, solar wind, flares, and the OVATION probability — including the "chance overhead" figure and the oval you see on the map. When the map and the verdict text disagree, believe the map.

This plugin's, and approximate:

• Your geomagnetic latitude comes from a centred dipole. That is not the same as corrected geomagnetic latitude, and the two diverge most over the North Atlantic and Siberia, where the real field is least dipole-like. Reykjavík is the worst case tested: the dipole puts it 3.5° too far poleward. Elsewhere it is good to a degree or two.
• The auroral oval is the standard linear fit — 66.5° at Kp 0, about 2.06° equatorward per Kp step. Real ovals are offset toward midnight and change shape during a storm; the OVATION map shows that and this number does not.
• "Low on the horizon" extends the oval 3° equatorward. That constant is not a guess: it is what NOAA's own published viewline cities imply once you convert them to geomagnetic latitude, and tools/test-spacewx.mjs checks it against that list on every run.
• Dark means the sun is more than 12° below the horizon (nautical twilight). Times are from the sunrise equation, within a minute at that angle.
• HF conditions are a reading of the usual solar-flux and K-index rules of thumb. A starting point, not a substitute for listening.

None of this knows about clouds, moonlight or the streetlight outside your window.

Tests

node tools/test-spacewx.mjs            # checks the maths against published references
node tools/test-spacewx.mjs --offline  # skips the sunrise-sunset.org comparison

The harness runs spacewx.js unmodified and checks it against published corrected-geomagnetic latitudes, the classic Kp visibility table, NOAA's viewline cities, and sunrise-sunset.org — including the polar day and polar night edge cases.

Credits

Data from NOAA Space Weather Prediction Center, public domain. Coastlines from Natural Earth, also public domain. Neither endorses this plugin.

MIT licensed.