================================================================================
SitRepMapper v1.12.1 — Program Overview

Designed and developed by Stephen Clay McGehee, KN4AM
Coding done using Claude Code AI
See SitRepNet.com for more information
================================================================================


PURPOSE
-------
SitRepMapper is an offline situation-report and map-pin viewer. Its
original audience was amateur radio and emergency communications (EMCOMM)
operators, and that JS8-driven reporting remains central: it reads F!505
Area Assessment, F!104 Situation Report, F!309 Situation Map Pin, and
CommStat StatRep records — either from JS8Spotter's SQLite database, or
directly from JS8Call's own DIRECTED.TXT log with no JS8Spotter
involvement at all — plots them on a local topo/street tile map, and
generates the same text summary reports as JS8Reporter — all in one
program, fully offline once tile data and one of those two sources is in
place.

Beyond radio use, SitRepMapper is equally suited to conducting an Area
Study — building up a working knowledge of what's in your AO (Area of
Operations) — and to information gathering for preparedness groups more
generally. The Areas tool (drawn polygons, rectangles, and circles) and
Flag Pins (manually-placed markers) exist specifically for this: mark out
regions and points of interest on the map, then export them so other
members of a local group can import the same data into their own copy of
SitRepMapper. No radio or JS8Spotter database is required for this use —
it works as a standalone offline mapping and area-study tool.

SitRepMapper is the successor to MHGridMapper (offline map viewer) and
JS8Reporter (JS8Spotter report parsing/reporting); both are being retired
in its favor.

SitRepMapper is also not read-only: its Send menu composes and transmits
F!104/F!309/F!505/CommStat reports over JS8Call directly, with saved
drafts, one-time or daily scheduled sending, and a sent-log — see KEY
FEATURES below and SitRepMapper_User_Manual.txt's SENDING REPORTS section.


REPORT SOURCES
-----------------
SitRepMapper reads its four report layers from exactly one source at a
time (Settings > Data Source, or use either File > Open command below —
opening a source switches to it):

  File > Open JS8Spotter DB… reads directly from JS8Spotter's SQLite
  database, opened read-only so it is safe to use while JS8Spotter is
  running. Polled every 60 seconds while active.

  File > Open JS8Call Directed Log… reads JS8Call's own DIRECTED.TXT log
  directly — plain text, no SQLite, no JS8Spotter involved. JS8Call
  writes this file continuously to its own Log directory regardless of
  what companion programs are running, so it also captures traffic
  received while SitRepMapper wasn't open, and isn't subject to
  JS8Spotter's own group-filter setting. The whole file is scanned on
  first open (and on switching to this source); after that, only newly
  appended lines are read, polled every 5 seconds while active.

Either way, View > Pause Auto-Refresh suspends the poll for whichever
source is active. All four report types can additionally be loaded
without either live source via File > Import/Export Reports — either a
raw per-type import from a plain-text log export, or SitRepMapper's own
Report Library format (.reports.json, all four types at once, see KEY
FEATURES below) — and merge with whichever live source is active.

Four report layers are parsed, regardless of source:

  F!505 Area Assessments — round pins colored by average infrastructure
    score across up to 32 fields (Water, Sewage/Waste, Power,
    Communications, Economy, Transportation, Health/Safety,
    Social/Political). Green / Yellow / Orange / Red / Gray
    (Fully Operational -> Destroyed -> Unknown/N/A).
    Click popup: Callsign, Grid, State, City/County, Time, overall score.

  F!104 Situation Reports — round pins colored by operational status.
    Green / Yellow / Red (Normal / Degraded / Significant Problems).
    Click popup: Callsign, Grid, State, Message, Time, and active
    F!304 Sitrep / F!306 Power Stability / F!305 Alert flags when present.

  F!309 Situation Map Pins — upward triangles colored by severity.
    Green / Yellow / Orange / Red / Gray (Minor -> Catastrophic -> Unknown).
    Click popup: Grid, Description, Affected Area, Category, Severity,
    Time Frame, Status, Expiration, and Time.

  CommStat StatReps — round pins colored to match the reported overall
    status directly: Green / Yellow / Red / Gray (Unknown). Reads from
    JS8Spotter's dedicated csstatrep table or JS8Call's own Directed Log
    (whichever report source is active), or via File > Reports
    Import/Export from an exported text file. Both of CommStat's current
    status-string formats — the full 12-digit form and the newer "+"
    all-Green shorthand — are fully recognized as valid input, not treated
    as an edge case.
    Click popup: Callsign, Group, Scope, Message ID, overall status,
    per-category status breakdown (Power, Water, Medical, Comms, Travel,
    Internet, Fuel, Food, Crime, Civil, Political), Notes, and Time.

Duplicate reports are always matched per callsign, so different stations
reporting from the same grid square each still get their own pin —
resolution per Settings > Filters (latest report only, or an average of
that station's reports for that square; F!505 only; F!104 and CommStat
always use latest, since there is nothing meaningful to average; F!309 is
never deduplicated at all) only collapses repeat submissions from the
same station.

Because that dedup is per report type, one grid square can still hold
pins from more than one type (or, for F!309, more than one report of the
same type). Pins are drawn oldest-to-newest per grid square so the most
recent report is always the one on top; any square holding more than one
report gets a numbered badge, and clicking it opens a picker (most recent
first) instead of resolving to a single fixed type.


KEY FEATURES
------------
- Offline map operation: works fully without an internet connection once
  tile data is in place
- Toolbar Grid Locator field + Go button: jump straight to a Maidenhead
  grid square, which is then outlined on the map; the last-used grid is
  remembered and re-centered on automatically the next time the program
  starts
- Pan (drag or arrow keys) and zoom (scroll wheel, toolbar +/-, or the
  keyboard) with a CONUS View reset button
- Toolbar View A / View B buttons: two saved-view slots for jumping back
  to a zoom level and center point of current interest — click to recall,
  right-click to save the current view into that slot; persists between
  sessions
- Multiple MBTiles files loaded simultaneously (overview + regional detail)
- Auto-detection of tile data on startup from a drive labelled SRMAP_NA,
  any other mounted drive, or the local tiles/ directory
- Time Lapse: step through the dates present in the loaded reports, with
  Rolling Window / Cumulative / Snapshot playback modes (Settings > Time
  Lapse) and an on-map date badge
- Report Library — import/export F!505/F!104/F!309/CommStat reports as
  files, for group members without a radio connection or on a different
  band/schedule; merges with whichever live source is active and
  survives that source's own re-scans
  - File > Import/Export Reports: raw per-type import from a plain-text
    log export, or SitRepMapper's own combined Report Library format
    (Import/Export Report Library…) covering all four types at once
  - Deleting a library report and later re-importing a file containing
    it offers to restore it instead of silently skipping it
  - View > Report Library… opens a sortable list of every library report
    (Type/Callsign/Grid/Date/Source), with Delete, Delete by Date
    Range…, and Deduplicate
- Flag Pins for manually-placed situational-awareness markers — a core
  tool for Area Study and preparedness-group information gathering
  - Right-click any map location — including an existing flag pin — to
    add a flag pin
  - Fields: Description, Maidenhead Grid, Date/Time (UTC), Source, Color,
    Group
  - Drag any flag pin to move it (dropping it onto another pin snaps it
    into an exact stack); click to view details, edit, or delete
  - Two or more flag pins sharing an exact spot show a numbered badge;
    clicking it lists all of them, most recent first, to choose which
    one to open
  - View > Flag Pins… opens a sortable list of every flag pin (click a
    column heading to sort), with Add/Edit/Delete/Jump-to-Map/Import/
    Export all available from that one window
  - Import/Export in sitrep_flags JSON format (interoperable with
    JS8Reporter and MHGridMapper flag files, and with Flag Pin Tool)
  - Deleting a flag pin and later re-importing a file containing it
    offers to restore it instead of silently skipping it
  - Group: an optional free-text tag (combobox suggests existing groups)
    for filtering exports and for View > Flag Pin Groups show/hide
- Areas — draw polygons, rectangles, and circles directly on the map as
  a second Area Study tool, for marking out regions rather than single
  points (a neighborhood, a patrol route, a supply radius)
  - Toolbar Draw Polygon / Draw Rectangle / Draw Circle buttons, with a
    live on-map readout of dimensions (radius / width+height / edge
    length, plus edge bearing for polygons) in decimal miles while
    drawing
  - Per-area description, color, line thickness, Group, an optional
    always-visible title with selectable text size (Small / Medium /
    Large / Extra Large), and — for circles — an editable real-world
    center and radius (center as Lat/Lon, radius as linked miles/km
    fields), with an optional center crosshair
  - Two or more circles sharing an exact center show a numbered stack
    badge and picker, the same as flag pins and report pins; drag a
    circle's center to move it — snapping onto another circle's exact
    center for a concentric "bullseye" — or Shift+drag to move every
    circle sharing that center as one group, each keeping its own
    radius; right-click Duplicate Circle (or Copy from an individual
    circle's popup, opened via the stack picker) stacks an identical
    copy on top for repositioning
  - Drag a rectangle's corner or side, or a polygon's vertex, to reshape
    it directly on the map instead of redrawing it — small square handle
    markers mark every draggable point
  - Right-click any map location inside a drawn area — or the area
    itself — for Edit/Delete Area or to add a flag pin at that spot
  - View > Areas… opens the same kind of sortable list/manage window as
    Flag Pins
  - Import/Export in its own sitrep_areas JSON format, so a group can
    build up a shared picture of their AO by exchanging both Areas and
    Flag Pin files
  - Group: same optional free-text tag as Flag Pins, independent of it,
    for filtering exports and for View > Area Groups show/hide
- Tools > Remove Duplicate Flag Pins… / Remove Duplicate Areas…:
  collapses flag pins or areas that match on everything but id and
  Date/Time (flag pins: description, grid, lat/lon, source, color,
  severity, status, Group; areas: shape, geometry, description, color,
  line thickness, title/crosshair settings, Group) down to the most
  recently updated copy. Group is part of the match either way, so pins
  or areas differing only by Group are never merged, since the same
  location is often tracked separately per group on purpose. Shows how
  many duplicates were found and asks for confirmation before removing
  anything.
- Tools > Grid Converter: converts between Maidenhead, MGRS/USNG, and
  decimal Lat/Lon, with a "Go to Grid on Map" shortcut
- Tools > Date Code Tool: converts between a Month/Day/Hour/Minute (UTC)
  date/time and the #XXXX datecode used on F! form prepared-time fields
- File > Download Tiles…: launches TileDownloader, a bundled companion
  tile-fetching utility, as an independent process
- Reports menu, grouped into a submenu per report type (F!505 Area
  Reports / F!104 Reports / CommStat Reports) now that it covers several
  report types: the 12 JS8Reporter text-report generators (Area
  Assessment Summary, Full Detail, Score Rankings, Category Focus, Alert
  Records, Geographic Summary, Critical Infrastructure, Trend Analysis,
  Infrastructure Heat Map, Data Quality/Coverage, Worst Conditions,
  Network Coverage), an F!104 Situation Report Summary, and a CommStat
  Status Roster (sortable by Callsign, Grid, or Status) — each viewable
  on-screen and saveable as a text file, to a user-configurable Export
  folder (Settings > General). Raw Reports (As Received)… lists every
  currently-visible report's literal raw text across all four types,
  grouped by type and sorted oldest-first, as a plain-text audit trail
  of exactly what came in
- Send menu: compose and transmit F!104, F!309, F!505, and CommStat
  StatRep reports, plus plain Unformatted Text, over JS8Call (requires
  JS8Call's TCP Server API — see SitRepMapper_Installation_Guide.txt)
  - Round-trip encode self-test blocks a send if the composed message
    wouldn't re-parse back to what was entered (the four structured
    report forms only — Unformatted Text has no encoded format to check)
  - Best-effort busy detection warns before sending if JS8Call looks like
    it's already transmitting or has a message staged
  - Save Draft / Send Now on every compose dialog; Send > Manage Drafts…
    lists, opens, and deletes saved drafts across all five form types
  - Scheduled sending on any saved draft — once at a specific date/time,
    or daily at one or more recurring times
  - Send > Pause Auto-Send temporarily stops scheduled drafts from firing
    without touching the schedules themselves
  - Missed scheduled sends are logged (not silently dropped) and
    summarized in a notice on the next launch
  - Send > View Sent Log… — a running, auto-refreshing record of every
    message actually sent, manual or scheduled
  - "Load into Send Form…" on any received report's map-pin popup
    pre-fills the matching compose dialog from that report
  - Unformatted Text: auto-uppercase, multi-line text with a live
    character count and a configurable length warning (Settings >
    General) — for quick messages or forwarding non-SitRepMapper form
    text as-is
- Busy (wait) cursor during the program's few genuinely slow, unavoidable
  moments — a map tile-cache miss, the one-time startup read of a large
  JS8Call Directed Log, and the brief pause while confirming a send —
  so those moments don't look like the program has frozen
- New pin highlight: optional magenta ring drawn around recently-received
  pins so new arrivals are visible at a glance (configurable time window,
  fractional hours like 0.5 accepted, Settings > Pin Colors)
- Date Filter: no filter, previous N days, or a specified date range,
  against either the record's received time or its form date code
  (Settings > Date Filter)
- Per-layer show/hide toggles (View menu) for every report type, Flag
  Pins, and Areas, plus Show All / Hide All, and a map legend
- View > Flag Pin Groups / Area Groups: per-Group show/hide (plus each
  submenu's own Show All Groups / Hide All Groups, named distinctly from
  the master Show All / Hide All above), layered on top of the master
  Flag Pins / Areas toggles above
- Icon Size / Flag Size selectors (small/medium/large/extra large)
- File > Export Map Image…: saves the currently visible map — tiles,
  pins, flags, and areas — as a PNG or JPEG file, rendered at 4x the
  on-screen resolution for a sharper result
- Settings persist automatically between sessions (~/.config/sitrepmapper)
- Auto-update check: on startup and on demand (Settings > Check for
  Updates Now), offers to open the download page when a newer version is
  posted; silent on failure, never applied automatically


TILE DATA
---------
Map tiles are not bundled with the program. SitRepMapper loads any
.mbtiles files it finds automatically from:

  1. A drive labelled SRMAP_NA
  2. Any other mounted drive under /media, /mnt, or /run/media
  3. The local tiles/ directory in the program folder

Tiles can be fetched with the bundled companion TileDownloader utility
(File > Download Tiles… — see SitRepMapper_Installation_Guide.txt and
tiledownloader/UserGuide.txt).


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 tile image compositing
- mgrs library for MGRS/USNG coordinate conversion
- MBTiles (SQLite) for local tile storage
- SQLite (read-only) for direct JS8Spotter database access
- Plain-text incremental log tailing (standard library only, no new
  dependency) for direct JS8Call Directed Log access
- JS8Call's own TCP API (standard library sockets, no new dependency) for
  the Send menu — one persistent connection held for the app's runtime
- Ghostscript (optional, system-level) for File > Export Map Image…
- perf_timing.py: an opt-in performance-timing/GC-pause logger (standard
  library only), off by default and invisible in normal use — set the
  SITREPMAPPER_PERF_LOG environment variable before launch to print each
  timed stage's duration to the console, for diagnosing slowness on a
  given machine
