How To Use VREM

VREM is a local browser app for viewing WSR-88D/NEXRAD Level II radar data in 3D.

One Start File

Windows: double-click Start_VREM.bat

Linux: open a terminal in this folder and run bash Start_VREM.sh.

The top level startup scripts are the normal way to run VREM. You do not need to open .VREM, or install packages by hand.

What Startup Does

The startup script creates a local Python environment, and installs and verifies all dependencies. Once all dependencies are installed, the script finds an open port from 5000 through 5010, and opens VREM in your browser if possible.

If Browser Does Not Open

If the browser does not open by itself, go to http://localhost:5000.

If port 5000 is busy, the launcher tries 5001 through 5010. Use the URL printed in the terminal window.

If You Encounter Bugs or Errors

If you encounter any errors or bugs within the app, please contact me in any way and I will resolve the issue as soon as I can.

What VREM Does

Loads the newest NEXRAD Level II radar scan for the selected WSR-88D site.
Renders all available elevation tilts together as a 3D point radar volume.
Updates automatically when a newer live scan becomes available..
Places a custom satellite map under the radar volume at radar local scale.
Draws state borders, county outlines, range rings, and warning/watch polygons inside the radar range circle.

Folder Organization

Use this folder as the front door. The actual app lives inside .VREM.

Volumetric Radar Echo Map/ Start_VREM.bat start here on Windows Start_VREM.sh start here on Linux with: bash Start_VREM.sh How_To_Use.html this user guide .VREM/ the actual VREM app VREM.bat Windows launcher used by Start_VREM.bat vrem.sh Linux launcher used by Start_VREM.sh app.py local web server and radar data API requirements.txt Python dependencies templates/ browser UI static/ logo and static assets .cache/ auto-created radar file cache .venv/ auto-created local Python environment Prev/ old backups or previous copies

For normal use, you only need the correct start script for your OS. Only edit files inside .VREM when you are changing the app itself.

Basic Workflow

Start VREM and wait for the radar site selector.
Search for a radar site, city, or state, or click a radar dot on the map.
Wait for the latest live Level II scan to download and parse.
Use the product buttons, tilt range controls, and vertical exaggeration slider to inspect the storm structure.
Open SETTINGS from the top bar for saved preferences, map opacity, warning opacity, performance, and advanced renderer controls.
Use CHANGE RADAR to return to the site selector.

Radar Products

REF: reflectivity. Shows where rain is.
BV: base velocity. Shows how strong winds are.
SRV: storm-relative velocity. Custom made. Shows how strong winds are without the storm motion.
CC: correlation coefficient. Shows how correlated the points in a radar are.

Volume Controls

Tilt Range:Isolates a range of tilts.
Vert Exag: Vertically exaggerates the scene for easier storm layer reading without changing radar data.
Tilt Heights: shows the current displayed height of the selected tilts at 100 km.

Settings Menu

The SETTINGS button opens a centered rounded menu with a blurred background.
Settings auto-save in the current browser. Use SAVE SETTINGS any time you want explicit confirmation.
General: UI scale, default tilt range, warning/watch opacity, county and state border opacity, map brightness, and radar brightness.
Advanced: point distance scaling, gate cap, reflectivity alpha curve, velocity alpha curve, dBZ floor/ceiling, SRV storm-motion method, parser verbosity, and harmless terminal warning suppression.
Presets: Chasing, Office, Performance, Balanced, High Quality, and Developer's Choice. High Quality sets Gate Cap to 0, which asks VREM for the largest supported scan display.
Reset All Settings: clears saved browser settings and restores defaults.
Clear Cache: clears downloaded radar files and parsed scan cache, then reloads the current radar if one is open.

Map And Overlays

Satellite Map: drawn under the radar volume as the ground reference. Brightness is controlled in Settings.
Terrain Reference: always present as a lightweight ground surface.
Range Rings: always on by default.
Warnings/Watches: lightly filled polygons for Tornado Warning, TOR E, Severe Thunderstorm Warning, Flash Flood Warning, Tornado Watch, and Severe Thunderstorm Watch.
Range Clipping: map imagery, borders, counties, warnings, and watches are clipped to the selected radar's range circle.

Live Timing

Last Scan: the newest scan time currently loaded in the viewer.
Refresh: countdown until VREM checks the live source again.
If no newer scan exists, VREM keeps the current volume and displays that the scan is current.
The first uncached scan can take longer because VREM may need to download and parse a full Level II file. Once cached, live refresh checks are kept tight.
If a live check fails, VREM keeps the current scan instead of blanking the display.

Data Source

Live Level II radar files come from the public unidata-nexrad-level2 archive.
Live warnings and watches come from api.weather.gov.
The satellite-style base layer uses public imagery tiles proxied through the local VREM server.
The old noaa-nexrad-level2 source is not used.
Latest live scan data: /api/live/<site>
Filtered live warning/watch overlays: /api/alerts
Health check: /api/health

Requirements

Operating system: Windows 10/11 or a modern Linux desktop.
Python: Python 3.11 or newer recommended. Windows should have python on PATH; Linux should have python3 on PATH.
Linux package: some distros need the virtual environment package first, such as python3-venv on Ubuntu/Debian.
Browser: a modern WebGL browser.
Internet: internet access for live radar downloads, alerts, borders, counties, and imagery.
GPU: a dedicated GPU is recommended for smoother 3D viewing, especially with High Quality or Developer's Choice presets.
Memory: 8 GB RAM is a practical minimum; 16 GB or more is better for large live scans and heavier browser sessions.
Network mode: by default VREM runs locally and is meant to be opened on the same computer.

Troubleshooting

Selector looks wrong or empty

Hard refresh the browser with Ctrl+F5. If that does not fix it, close the VREM terminal window and start it again with the launcher for your operating system.

Radar loads forever

Check the terminal window. If the internet or Unidata archive is slow, try again after a minute or choose a nearby radar site.

Port 5000 is already busy

The launcher automatically tries ports 5000 through 5010. Use the exact URL printed in the terminal.

Important Note

VREM is a beta visualization and research tool. It is not for making life threatening decisions, and could produce errors or false radar data.

VREM Archive

This tab records the big changes made during the 0.5.0 Beta rescue and production pass. The normal user guide stays clean on the Guide tab; this archive is the longer history of what was added, removed, repaired, simplified, and tuned.

Build

0.5.0 Beta

Mode

Live Level II

View

3D Only

Guide

HTML Only

Radar Data And Live Mode Added

Live Source

Added live Level II scan discovery for the radar sites.
Added latest-scan lookup by site.
Added scan download caching so repeat loads are faster.
Added parsed gate caching for the newest volume.
Added cache limiting so the cache does not grow forever.
Added a clear-cache endpoint and Settings button.
Added health and runtime settings endpoints.

Live Behavior

Added automatic refresh checks for newer scans.
Added Last Scan time display.
Added Refresh countdown display.
Changed failed refresh behavior so the current scan stays visible.
Added separate timeout behavior for initial full loads and later refresh checks.
Added gate cap requests so low-end machines can load fewer gates.

Renderer And Readability Added

Particles

Added soft gaussian particle sprites.
Added dBZ return based particle sizing.
Added camera distance particle scaling.
Added reflectivity alpha curve control.
Added velocity alpha curve control.
Added weak return transparency
Added display only color compression for readability.
Added selective glowing for stronger reflectivity cores.
Changed render order and depth behavior to reduce angle based opacity dropouts.

Velocity

Added BV and SRV as first class products.
Softened velocity brightness.
Reduced velocity point size so dense flow has structure.
Added velocity magnitude point scaling.
Added near zero grey velocity opacity.
Added median storm motion SRV method.

Tilts And Vertical Structure Added

Changed the volume to display all tilts at once by default.
Added tilt range isolation with separate start and end controls.
Added default tilt range saved in Settings.
Added displayed tilt height readout at 100 km.

Map, Borders, And Hazards Added

Map

Added a satellite base layer.
Added local proxying for map imagery.
Scaled the map to radar local kilometers.
Clipped the map to the radars range.
Added map brightness setting.

Boundaries And Alerts

Added county outlines.
Added state borders.
Added county border opacity setting.
Added state border opacity setting.
Clipped counties, borders, warnings, and watches to radar range.
Added live NWS warning polygons.
Added lightly filled warning polygons.
Added Tornado Warning display.
Added TOR E display in pink.
Added Severe Thunderstorm Warning display.
Added Flash Flood Warning display.
Added warning opacity setting.

Presets Added

Added Chasing preset.
Added Office preset.
Added Performance preset for lower-end hardware.
Added Balanced preset.
Added High Quality preset with gate cap set to 0.
Added Developer's Choice preset.
Updated Developer's Choice to use high-quality gates, strong map/radar brightness, low REF alpha curve, low velocity alpha curve, and full dBZ display range.
Made presets save like other settings.
Made presets refresh/rebuild the current radar when needed.

Packaging And Launching Added

Windows

Kept Start_VREM.bat as the one-click Windows entry point.
Kept the Windows entry point at the top of the folder.
Kept generated runtime folders separate from normal user files.
Kept extra technical notes out of the normal user flow.

Linux

Added Start_VREM.sh as the top-level Linux entry point.
Updated .VREM/vrem.sh for Linux startup.
Added Linux virtual environment creation.
Added Linux dependency installation.
Added Linux port selection from 5000 through 5010.
Added xdg-open support where available.
Added a helpful python3-venv message for Ubuntu/Debian-style setups.

Important Note

VREM is a beta visualization and research tool. It is not for making life threatening decisions, and could produce errors or false radar data.