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


PURPOSE
-------
Flag Pin Tool is a standalone editor for creating and managing Flag Pin files
(.flags.json) used by JS8Reporter and MH Grid Mapper. It provides a dedicated,
full-featured interface for building flag pin datasets manually, importing from
raw CSV or TSV data, and exporting files ready for direct use in either of those
programs.

Prior to Flag Pin Tool, flag pins could only be created one at a time inside
JS8Reporter or MH Grid Mapper. Flag Pin Tool makes it practical to build large
pin sets quickly — including bulk import from spreadsheet or tabular data —
without needing either mapping program open.


WHAT IT IS NOT
--------------
Flag Pin Tool does not display a map. It is a data editor, not a mapping program.
To visualize the flag pins on a map, import the exported .flags.json file into
JS8Reporter or MH Grid Mapper.

Flag Pin Tool does not connect to a radio, TNC, or any external hardware. It is
a standalone file editor that works entirely on locally stored data.


KEY FEATURES
------------
- Grid Converter tool (Tools menu): converts between Maidenhead, MGRS/USNG,
  and decimal Lat/Lon — auto-detects input format
- Spreadsheet-style list view of all flag pins with sortable, filterable columns
- Add, Edit, Delete, and Duplicate individual pin entries via a full dialog
- Quick Add strip for rapid bulk entry: type Description + Grid, press Add
- Grid ↔ Latitude/Longitude auto-sync: enter any one, the others fill in
- Import raw data from CSV or TSV files with an auto-mapping column dialog
- Merge existing .flags.json files using the shared timestamp-based merge logic
- Export .flags.json files compatible with JS8Reporter and MH Grid Mapper
- Open and Save .flags.json files as working documents
- Row backgrounds color-tinted by pin color for visual identification
- Live Filter field: type any text to narrow the list instantly
- Named color list plus "Custom…" option for any arbitrary hex color
- Blink flag support (pins flash on map in JS8Reporter / MH Grid Mapper)
- Severity (Low / Medium / High / Critical) and Status (Active / Ongoing / Resolved)
- Unsaved-changes guard on exit, new file, and open
- Settings for default station callsign, pin color, import/export folders
- Auto-update version check with configurable URL
- No installation or setup required for core features: single Python file,
  standard library only; Grid Converter additionally requires pip install mgrs
- Runs on Linux, Raspberry Pi OS, and Windows


THE FLAG PIN FORMAT  (sitrep_flags v1.0)
-----------------------------------------
Flag pins are stored in JSON files with the .flags.json extension. The format
is shared across the entire SitRepNet tool family:

  {
    "format":      "sitrep_flags",
    "version":     "1.0",
    "exported_at": "2026-06-14T12:00:00Z",
    "created_by":  "KN4AM",
    "flags": [
      {
        "id":          "uuid",
        "description": "Home",
        "grid":        "EL99hc",
        "lat":         29.10417,
        "lon":         -81.375,
        "datetime":    "2026-06-14T12:00:00Z",
        "source":      "KN4AM",
        "color":       "#CC3300",
        "blink":       false,
        "severity":    "",
        "status":      "",
        "updated_at":  "2026-06-14T12:00:00Z"
      }
    ]
  }

All date/time values are UTC in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
Colors are standard hex notation (#RRGGBB).
Grid locators are Maidenhead format, 4 or 6 characters (e.g., EL99, EL99hc).


CSV / TSV IMPORT
----------------
Flag Pin Tool accepts any comma-separated (CSV) or tab-separated (TSV) file.
A column-mapping dialog auto-detects header names and lets you assign each
column to the correct flag pin field before importing.

Minimum required: one column mapped to Grid, or two columns mapped to Latitude
and Longitude. All other fields are optional and default to sensible values
(current UTC timestamp, station callsign as Source, default color).

Color values in CSV files are accepted as hex codes (#CC3300) or named colors
(Red, Dark Red, Orange, Yellow, Green, Dark Green, Cyan, Blue, Magenta, Purple,
White, Black).


PROGRAM ECOSYSTEM
-----------------
Flag Pin Tool is part of the SitRepNet EMCOMM tool family:

  JS8Reporter      — Receives and displays MCF505 Area Assessment reports
                     received via JS8Call. Displays flag pins on a North
                     America map alongside assessment data.

  MH Grid Mapper   — Offline topographic map viewer with Maidenhead grid
                     locator lookup. Displays flag pins as draggable markers
                     on the map.

  Flag Pin Tool    — Standalone editor for creating and managing .flags.json
                     files used by both programs above.

All three programs share the sitrep_flags v1.0 JSON format. A .flags.json file
created in Flag Pin Tool can be opened directly in either JS8Reporter or MH Grid
Mapper without conversion.


TECHNOLOGY
----------
- Python 3.9+ with Tkinter (standard library)
- Maidenhead grid conversion built in
- mgrs package required for Tools > Grid Converter (pip3 install mgrs);
  all other features work without it
- Settings and flag pin data stored as JSON in the data/ subdirectory
- Single-file design: flagpintool.py contains the complete application