MH Grid Mapper — Program Overview
===================================
Designed and developed by Stephen Clay McGehee, KN4AM
Coding done using Claude Code AI
See SitRepNet.com for more information


PURPOSE
-------
MH Grid Mapper is an offline topographic mapping tool for amateur radio and
emergency communications (EMCOMM) operators. It displays USGS topo tiles
centered on a Maidenhead grid locator with pan and zoom, and live-syncs
station data from JS8Reporter so both programs show the same operational
picture simultaneously.


JS8REPORTER LIVE SYNC
---------------------
When JS8Reporter v1.7.2 or later is running on the same machine, MH Grid Mapper
automatically detects it and begins syncing without any manual export or import.
JS8Reporter writes export files after each database poll; MH Grid Mapper watches
them and redraws within the configured sync interval (default 30 seconds).

Three data layers sync automatically:

  F!505 Area Assessments — teardrop pins colored by infrastructure score
    Green / Yellow / Orange / Red (Fully Operational → Destroyed)
    Click popup shows: Callsign, Grid, State, City/County, Time, SNR,
    Frequency, Condition score.

  F!104 Situation Reports — teardrop pins colored by operational status
    Green / Yellow / Red (Normal / Degraded / Significant Problems)
    Click popup shows: Callsign, Grid, State, Status, Time, Age, and active
    F!304 Sitrep or F!305 Alert references when present.

  F!309 Situation Map Pins — upward triangles (▲) colored by severity
    Green / Yellow / Orange / Red / Gray (Minor → Catastrophic / Unknown)
    Click popup shows: Grid, Description, Affected Area, Category, Severity,
    Time Frame, Current Status, Expiration, Time, and Age. Expiration @0
    means the pin does not expire.

  Flag Pins — the shared flags.flags.json is also watched; changes in either
    program propagate automatically.

The sync reflects JS8Reporter's active date filter, deduplication, and circle
filter — both programs always show the same records.


KEY FEATURES
------------
- Offline operation: works fully without an internet connection after tile data
  is downloaded
- Maidenhead grid locator entry (4, 6, or 8-character)
- Topographic map display using USGS National Map tiles (US coverage)
- Multiple mbtiles files loaded simultaneously (overview + regional detail)
- Auto-detection of mbtiles files on startup from connected drives or /mnt
- Dashed red grid-square boundary overlay and center crosshair
- Pan and zoom (mouse drag, scroll wheel, toolbar buttons)
- NA Overview button (continental view, zoom 4)
- Fit to Grid button (auto-zooms so the grid square fills the window)
- JS8Reporter live sync — F!505, F!104, and F!309 pins update automatically
  while JS8Reporter is running; no manual export/import needed
- New pin highlight: optional magenta ring drawn around recently-received
  pins to make new arrivals visible at a glance (configurable time window,
  Settings > General)
- Station import (manual fallback) from JS8Reporter CSV or custom JSON
- Flag Pins for manually-placed situational awareness markers
  - Right-click any map location to add a flag pin
  - Fields: Description, Maidenhead Grid, Date/Time (UTC), Source, Color
  - Drag any flag pin to move it; click to view details
  - Manage via View > Flag Pins…; import/export in sitrep_flags JSON format
    (interoperable with JS8Reporter)
  - Pins persist automatically between sessions
- Grid Converter tool: converts between Maidenhead, MGRS/USNG, and decimal Lat/Lon
- Tile downloader: downloads USGS topo tiles by bounding box or grid locator
- Auto-update check: notifies when a new version is available at startup
- Current version shown in the window title bar and Help > About dialog
- Settings dialog: JS8Reporter sync options, update check behavior
- Linux desktop launcher (.desktop file)
- Runs on Linux and current Raspberry Pi OS


TILE DATA
---------
Map tiles are sourced from the USGS National Map (public domain, US coverage
only). Tiles are stored locally in MBTiles format (.mbtiles files). The app
loads all .mbtiles files it finds automatically from:

  1. A USB drive labelled MHMAP_NA
  2. Any mounted drive under /mnt or /media containing .mbtiles files
  3. The local tiles/ directory in the program folder

Recommended tile set for full US coverage:
  na_overview.mbtiles   — zoom 4-9,  Continental US (~112 MB)
  southeast_detail.mbtiles  — zoom 9-12, Southeast US (~810 MB)
  northeast_detail.mbtiles  — zoom 9-12, Northeast US (~535 MB)
  midwest_detail.mbtiles    — zoom 9-12, Midwest       (~913 MB)
  southcentral_detail.mbtiles — zoom 9-12, South Central (~471 MB)
  mountainwest_detail.mbtiles — zoom 9-12, Mountain West (~971 MB)
  westcoast_detail.mbtiles  — zoom 9-12, West Coast    (~599 MB)

Total: approximately 4.4 GB for full continental US coverage.


GRID SYSTEMS
------------
The primary grid system is the Maidenhead Locator System used in amateur radio.
The built-in Grid Converter tool (Tools menu) converts between Maidenhead,
MGRS/USNG (Military Grid Reference System / US National Grid), and decimal
latitude/longitude — accepting any of the three as input and displaying all
three as output.


TECHNOLOGY
----------
- Python 3 with Tkinter (pre-installed on Linux and Raspberry Pi OS)
- Pillow (PIL) for image compositing
- mgrs library for MGRS/USNG coordinate conversion
- USGS National Map for topographic tile data (public domain)
- MBTiles (SQLite) for local tile storage
