================================================================================ 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