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


OVERVIEW
--------
MH Grid Mapper is an offline EMCOMM mapping tool for visualizing station
locations and situational awareness data distributed over a JS8Call radio
net. It displays pin markers on a USGS topo tile map, with no internet
connection required at runtime.

Key capabilities:
  - Displays F!505 Area Assessment pins color-coded by infrastructure score
  - Displays F!104 Situation Report pins showing operational status
  - Displays F!309 Situation Map pins color-coded by severity
  - Live sync with JS8Reporter: map updates automatically as new reports
    arrive, with no manual export or import required
  - New pin highlight: optional magenta ring drawn around recently-received
    pins to make new arrivals visible at a glance (configurable time window)
  - Flag Pins: manually-placed SitRep markers, import/export in a format
    interoperable with JS8Reporter for net distribution
  - Offline topo tile maps (USGS); tiles downloaded once and stored locally
  - Grid Converter: translates between Maidenhead, MGRS/USNG, and lat/lon

More Information:  SitRepNet.com


LAUNCHING THE PROGRAM
---------------------
From the desktop:
  Double-click the MH Grid Mapper icon.

From the terminal:
  python3 /home/stephen/mhgridmapper/main.py

With a starting grid locator:
  python3 /home/stephen/mhgridmapper/main.py EL99hc


TILE DATA — FIRST-TIME SETUP
-----------------------------
The map requires local tile data to display. Without tiles, the canvas shows
a gray grid pattern. Tiles only need to be downloaded once.

Recommended starting point — Continental US overview (zoom 4-9):
  This single download (~81 MB, ~20 minutes) covers the entire contiguous
  United States at zoom levels 4 through 9 — enough to navigate by grid
  square, see state and county boundaries, and track stations across a net.
  For most users, this is all that is needed.

Optional — Local/regional detail (zoom 9-12):
  Adds roads and neighborhood-level detail for a specific area. Download
  only the region you need; covering the full continental US at this zoom
  range requires ~5 GB and roughly 19 hours of download time.

Option 1 — Download using the built-in downloader:
  1. Open File > Download Tiles...
  2. Select a region preset (Continental US, Alaska, Hawaii) or enter a
     custom bounding box.
  3. Set zoom range: 4-9 for the overview, 9-12 for regional detail.
  4. Choose a save location and click Start Download.

Option 2 — Download from the command line:
  python3 /home/stephen/mhgridmapper/tile_downloader.py \
    --bbox 24.0 -125.0 50.0 -66.0 \
    --zoom 4-9 \
    --out /path/to/na_overview.mbtiles

  python3 /home/stephen/mhgridmapper/tile_downloader.py \
    --grid EL99hc \
    --zoom 9-12 \
    --out /path/to/local_detail.mbtiles

Once downloaded, the app will find .mbtiles files automatically on startup if
they are stored on a drive labelled MHMAP_NA, or anywhere under /mnt or /media.
Multiple .mbtiles files are all loaded simultaneously.

You can also load a file manually via File > Open MBTiles...


LOOKING UP A GRID LOCATOR
--------------------------
1. Type the Maidenhead grid locator in the Grid Locator field in the toolbar.
   Accepts 4, 6, or 8-character locators (e.g., EL99, EL99hc, EL99hc33).
2. Press Enter or click Go.
3. The map centers on the grid, draws a dashed red border around the grid
   square, and places a red crosshair at the center.
4. The status bar shows the grid, latitude/longitude, and current zoom level.


NAVIGATING THE MAP
------------------
Pan:      Click and drag the map in any direction.
Zoom in:  Scroll wheel up, click +, or use View > Zoom In.
Zoom out: Scroll wheel down, click -, or use View > Zoom Out.
Fit:      Click Fit to Grid to auto-zoom so the current grid square fills the window.
          Also available via View > Fit to Grid Square, or press F.
Overview: Click NA Overview to zoom out to the full continental US view.
          Also available via View > Reset to North America.

The status bar at the bottom always shows the current zoom level, the
lat/lon at the map center, and the 6-character Maidenhead grid for that point.


JS8REPORTER LIVE SYNC
---------------------
When JS8Reporter (v1.7.2 or later) is installed on the same machine, MH Grid
Mapper detects it automatically on startup and begins live sync. No manual
export or import is needed.

How it works:
  JS8Reporter writes three export files to its data/exports/ folder each time
  it polls its database. MH Grid Mapper watches those files and redraws the map
  within 30 seconds of any change (the sync interval is configurable).

  F!505 Area Assessments  — teardrop pins, color by infrastructure score:
    Green  — Fully Operational (@3)
    Yellow — Degraded (@2)
    Orange — Severely Impaired (@1)
    Red    — Destroyed (@0)
    Click a pin to see: Callsign, Grid, State, City/County, Time, SNR,
    Frequency, and Condition score.

  F!104 Situation Reports  — teardrop pins, color by operational status:
    Green  — Normal (status 1)
    Yellow — Degraded (status 2)
    Red    — Significant Problems (status 3)
    Click a pin to see: Callsign, Grid, State, Status (Normal/Degraded/
    Problems), Time, Age, and — when flagged in the report — Sitrep
    (F!304 Active) or Alert (F!305 Active). Sitrep and Alert rows are
    omitted when nothing is reported. Callsign display requires
    JS8Reporter v1.7.5 or later.

  F!309 Situation Map Pins  — upward triangle (▲), color by severity:
    Green  — Minor / Limited Impact
    Yellow — Moderate
    Orange — Severe
    Red    — Major / Catastrophic
    Gray   — Unknown
    Click a pin to see: Grid, Description (DS[] tag if present), Affected
    Area, Category, Severity, Time Frame, Current Status, Expiration,
    Time, and Age. Pins with expiration @0 never expire.

  Flag Pins  — the shared flags.flags.json file is also watched; flag pin
    changes in either program propagate to the other automatically.

The export reflects JS8Reporter's active date filter, deduplication, and circle
filter — both programs show the same picture at all times.

Status indicators:
  - While sync is active a green "↻ JS8R HH:MM" label appears in the status bar,
    updated after each sync cycle.
  - If JS8Reporter is installed but not running, an amber notice bar appears with
    a "Start JS8Reporter" button. Click it to launch JS8Reporter; MH Grid Mapper
    waits for it to become ready before activating sync.

File > Reconnect to JS8Reporter — manually re-evaluates sync state; useful
  after restarting JS8Reporter or changing the data folder path in Settings.

Settings > JS8Reporter tab — configure live sync:
  Enable/disable sync, set the JS8Reporter data folder path, the JS8Reporter
  executable path (for the "Start JS8Reporter" button), and the sync interval
  (10–300 seconds, default 30).


LOADING STATION DATA (MANUAL IMPORT)
--------------------------------------
When not using live sync, stations can be imported manually from a file.

From JS8Reporter — F505 station data:
  1. Apply any filters you want in JS8Reporter (e.g., circle filter by range).
  2. Export the filtered data: File > Export F505 Data (CSV format).
  3. In MH Grid Mapper: File > Open Stations... and select the CSV file.

From JS8Reporter — F104 situation reports:
  1. In JS8Reporter: File > Export as F104... and save the .txt file.
  2. In MH Grid Mapper: File > Open Stations... and select the .txt file.
  Click a pin to see callsign, status, state, and any active F!304/F!305 references.

From a custom JSON file:
  The file must be a JSON array of objects. Required field: "grid" (Maidenhead).
  Optional fields: "callsign", "snr" (integer dB), "timestamp", "frequency"
  (integer Hz), "message".

Once loaded:
  - Markers appear at each record's grid center, color-coded by status.
  - The map auto-zooms to fit all markers.
  - The status bar shows the record count.
  - Click any marker to see the details popup.
  - File > Clear Stations removes all markers.


GRID CONVERTER (MAIDENHEAD ↔ MGRS/USNG ↔ LAT/LON)
---------------------------------------------------
The Grid Converter translates between Maidenhead grid locators, MGRS/USNG
(Military Grid Reference System / US National Grid) coordinates, and decimal
latitude/longitude.

To open: Tools > Grid Converter...

Usage:
  1. Type a Maidenhead locator (e.g., EL99hc), an MGRS coordinate
     (e.g., 17RMN63511958), or a decimal Lat, Lon pair
     (e.g., 34.5678, -86.1234) in the Input field. The format is
     auto-detected.
  2. Click Convert (or press Enter).
  3. The tool displays the detected format, both grid representations,
     and the latitude/longitude.
  4. Use Copy Maidenhead or Copy MGRS to copy the result to the clipboard.
  5. Click Go to Grid on Map to center the main map on the converted location.

Precision options:
  MGRS precision: 10m (default), 100m, 1km, or 10km.
  Maidenhead length: 6-char (default), 4-char, or 8-char.

Command-line usage:
  python3 /home/stephen/mhgridmapper/grid_converter.py EL99hc
  python3 /home/stephen/mhgridmapper/grid_converter.py 17RMN63511958
  python3 /home/stephen/mhgridmapper/grid_converter.py "34.5678, -86.1234"


FLAG PINS
---------
Flag pins are manually-placed markers for situational awareness information
not derived from radio station data. Each flag pin stores a Description,
Maidenhead Grid, Date/Time (UTC), Source, Color, Severity, and Status.

Creating a flag pin:
  Right-click anywhere on the map and choose "Add Flag Pin Here...".
  The dialog pre-fills the grid and lat/lon from the click location.
  You can also type a grid or lat/lon directly; the fields sync automatically.

  Dialog fields:
    Description  — short label shown on the map and in the pin list
    Grid         — Maidenhead locator (auto-fills from click location)
    Latitude     — decimal degrees (syncs with Grid)
    Longitude    — decimal degrees (syncs with Grid)
    Date/Time    — UTC timestamp (defaults to current time)
    Source       — operator or origin of the report (defaults to callsign)
    Severity     — Low / Medium / High / Critical (optional)
    Status       — Active / Ongoing / Resolved (optional)
    Color        — named color dropdown (Black, White, Red, Green, Blue,
                   Yellow, Cyan, Magenta)

  Click OK to save the pin.

Editing a flag pin:
  Right-click the flag pin on the map and choose "Edit Flag Pin...".
  Or open View > Flag Pins..., select the pin, and click Edit...

Moving a flag pin:
  Click and drag the flag to its new location. The pin snaps to the cursor
  as you drag; releasing the mouse saves the new position automatically.

Viewing a flag pin:
  Click the flag to open a popup showing all stored fields.

Managing all flag pins:
  View > Flag Pins... opens the Flag Pins dialog with a list of all pins.
  From here you can Add, Edit, Delete, Jump to Map, Import, and Export.

Importing and exporting flag pins:
  Flag pins are stored in the sitrep_flags JSON format (.flags.json files),
  shared with JS8Reporter. To import a .flags.json file, use either
  File > Import Flag Pins… or the Import… button inside View > Flag Pins…
  To export, use File > Export Flag Pins… or the Export… button inside
  View > Flag Pins…
  Pins are saved automatically — no manual save is required.

Flag pin appearance:
  MH Grid Mapper draws flag pins as a traditional flag icon (⚑) — a vertical
  pole with a colored rectangular flag body. JS8Reporter displays the same
  pin data as a teardrop map-pin shape (▼) in the chosen color. The visual
  symbols differ between programs, but the underlying data and file format
  are identical.


SETTINGS
--------
Settings > Settings... opens the Settings dialog.

General tab:
  Station callsign — your amateur radio callsign, written to the "created by"
    field of every flag pin export file.

  New pin highlight — enter a number of hours (1–99) to draw a bright magenta
    ring around F!505, F!104, and F!309 pins received within that window. Set
    to 0 (default) to disable.

JS8Reporter tab:
  Enable/disable live sync, configure the JS8Reporter data folder and
  executable paths, and set the sync interval (10–300 seconds).

Auto-Update tab:
  "Check for updates on startup" — when checked, MH Grid Mapper checks the
  configured URL at launch and notifies you if a newer version is available.
  No map tile data or personal data is transmitted; the check is a simple
  HTTP fetch of a version number file.

  "Version check URL" — the URL of the version.json file to compare against.
  Leave blank to disable all automatic update checks.

Settings > Check for Updates Now — runs an immediate version check regardless
  of whether the startup check is enabled, and shows a result either way.


FILE MENU REFERENCE
-------------------
Open MBTiles...         Load a .mbtiles tile file manually.
Select Tile Folder...   Load tiles from a directory tile cache.
Download Tiles...       Download USGS topo tiles for offline use.
Open Stations...        Import station data from JS8Reporter CSV or JSON.
Clear Stations          Remove all station markers from the map.
Import Flag Pins...     Import flag pins from a .flags.json file.
Export Flag Pins...     Export all flag pins to a .flags.json file.
Reconnect to JS8Reporter  Re-evaluate live sync state manually.
Quit                    Save settings and exit.


VIEW MENU REFERENCE
-------------------
Zoom In               Increase zoom level.
Zoom Out              Decrease zoom level.
Fit to Grid Square    Auto-zoom so the current grid square fills the window.
Reset to North America  Zoom out to full continental US view.
Flag Pins...          Open the Flag Pins management dialog.


SETTINGS MENU REFERENCE
------------------------
Settings...           Open the Settings dialog (update check options).
Check for Updates Now Run an immediate version check against the server.


HELP MENU REFERENCE
--------------------
About                 Shows the currently running program version, credits,
                       and a link to SitRepNet.com. The window title bar also
                       displays the current version at all times.


KEYBOARD SHORTCUTS
------------------
Enter    Execute grid lookup (when cursor is in the Grid Locator field)
F        Fit to current grid square
+        Zoom in
-        Zoom out


CONFIGURATION
-------------
Settings are saved automatically to:
  ~/.config/mhgridmapper/config.json

Saved settings include: last grid locator, last zoom level, last map center,
window size and position, and auto-update preferences.

Flag pins are saved separately to:
  ~/.config/mhgridmapper/flags.flags.json

The tile source path is NOT saved — tiles are always auto-detected on startup.


FLASH DRIVE SETUP (PORTABLE TILE STORAGE)
------------------------------------------
To use a USB flash drive for tile storage:
  1. Format the drive (exFAT recommended for large files).
  2. Label the drive MHMAP_NA.
  3. Copy your .mbtiles files to the root of the drive.
  4. Plug in the drive before launching MH Grid Mapper.

The app will find and load all .mbtiles files automatically on startup.
Other files on the drive do not interfere with map operation.

Note: On Linux, relabelling an exFAT drive requires it to be unmounted first:
  sudo umount /dev/sdXN
  sudo exfatlabel /dev/sdXN MHMAP_NA


TROUBLESHOOTING
---------------
Gray canvas on startup:
  No tile data has been loaded. Use File > Open MBTiles... or download tiles
  via File > Download Tiles...

"No tile source loaded" warning in status bar:
  Same as above.

Grid locator not recognized:
  Check that the locator is 4, 6, or 8 characters in the form AA##xx
  (two letters, two digits, optionally two more letters). Example: EL99hc.

Stations not appearing after import:
  Verify the CSV has a "Grid" column with valid Maidenhead locators, or the
  JSON has a "grid" field. Records with missing or invalid grids are skipped.

Tools > Grid Converter does nothing (no dialog appears):
  The mgrs library is not installed. Open a terminal and run:
      pip3 install mgrs              (Linux / Raspberry Pi)
      pip install mgrs               (Windows)
  Then restart the app. See Installation Guide Section 7 for details.

Map tiles appear blurry at high zoom:
  The current .mbtiles file does not have data at that zoom level. The app
  scales up the nearest available zoom level as a fallback. Download higher-
  zoom tiles for that region to get full detail.
