================================================================================
  MH Grid Mapper – Installation Guide
  Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================


TABLE OF CONTENTS
-----------------
  1.  System Requirements
  2.  Installation: Linux / Raspberry Pi
  3.  Installation: Windows
  4.  The Desktop Launcher (Linux / Raspberry Pi)
  5.  Starting the Program
  6.  Tile Data Setup
  7.  Troubleshooting


================================================================================
1.  SYSTEM REQUIREMENTS
================================================================================

Supported Platforms
-------------------
  - Raspberry Pi 4B running Raspberry Pi OS Bookworm or Bullseye (primary)
  - Linux (Ubuntu, Debian, and derivatives)
  - Windows 10 / 11

Python Version
--------------
  Python 3.9 or newer is required.

  Check your version:
      python3 --version       (Linux / Raspberry Pi)
      python  --version       (Windows)

Internet Connection
-------------------
  An internet connection is required for the initial package installation
  and tile data download only. After that, MH Grid Mapper runs completely
  offline.

Required Python Packages
------------------------
  Pillow  >= 9.0    (map tile rendering)
  mgrs    >= 1.4    (MGRS/USNG coordinate conversion)

  Optional (only needed for the tile downloader):
  requests >= 2.28

  Tkinter is also required. It is pre-installed on Raspberry Pi OS and most
  Linux distributions. See Troubleshooting (Section 7) if it is missing.


================================================================================
2.  INSTALLATION: LINUX / RASPBERRY PI
================================================================================

Step 1 — Copy the program files
---------------------------------
  Place the mhgridmapper folder wherever you prefer. The recommended location
  for a single-user installation is the home directory:

      /home/<username>/mhgridmapper

  For a system-wide installation accessible to all users, use:

      /opt/mhgridmapper

  The .desktop launcher file is pre-configured for /opt/mhgridmapper. If you
  install to a different location, see Section 4 for how to adjust the paths.

Step 2 — Install Python packages
----------------------------------
  Open a terminal and run:

      pip3 install Pillow mgrs

  If you see an error about "externally managed environment" (common on
  Ubuntu 23.04 and newer, Raspberry Pi OS Bookworm and newer), use one of
  these alternatives:

  Option A — Install for the current user only (recommended):
      pip3 install --user Pillow mgrs

  Option B — Install system-wide (requires elevated privileges):
      pip3 install Pillow mgrs --break-system-packages

  Option C — Use a virtual environment (cleanest approach):
      cd /home/<username>/mhgridmapper
      python3 -m venv venv
      venv/bin/pip install Pillow mgrs

      If using a virtual environment, replace all python3 and pip3 commands
      in these instructions with:
          /home/<username>/mhgridmapper/venv/bin/python3
          /home/<username>/mhgridmapper/venv/bin/pip

  To also enable the tile downloader (File > Download Tiles…):
      pip3 install requests        (append to the command above)

Step 3 — Install the desktop launcher
---------------------------------------
  See Section 4 for full details on the desktop launcher.

  Quick install (adjust the path to match your installation location):
      sed 's|/opt/mhgridmapper|/home/<username>/mhgridmapper|g' \
          /home/<username>/mhgridmapper/mhgridmapper.desktop \
          > ~/.local/share/applications/mhgridmapper.desktop
      cp ~/.local/share/applications/mhgridmapper.desktop ~/Desktop/
      update-desktop-database ~/.local/share/applications

  Or install from /opt (if using the recommended system-wide path, no
  path substitution is needed):
      cp /opt/mhgridmapper/mhgridmapper.desktop \
          ~/.local/share/applications/
      cp /opt/mhgridmapper/mhgridmapper.desktop ~/Desktop/
      chmod +x ~/Desktop/mhgridmapper.desktop
      update-desktop-database ~/.local/share/applications

Step 4 — Download tile data
-----------------------------
  See Section 6 for tile data setup. Tiles are required for the map to
  display. This step requires an internet connection and can take from a
  few minutes to several hours depending on coverage area selected.


================================================================================
3.  INSTALLATION: WINDOWS
================================================================================

Step 1 — Install Python
------------------------
  If Python is not already installed, download it from python.org.
  During installation, check the box labeled "Add Python to PATH."

  Verify the installation:
      python --version

Step 2 — Copy the program files
---------------------------------
  Place the mhgridmapper folder in a convenient location, for example:

      C:\Users\<username>\mhgridmapper

Step 3 — Install Python packages
----------------------------------
  Open a Command Prompt and run:

      pip install Pillow mgrs

  To also enable the tile downloader (File > Download Tiles…):
      pip install Pillow mgrs requests

Step 4 — Create a desktop shortcut
-------------------------------------
  Windows does not use .desktop launcher files. To create a shortcut:

  1. Right-click the Desktop and select New > Shortcut.
  2. In the Location field, enter (adjust the path to match your install):
         python "C:\Users\<username>\mhgridmapper\main.py"
  3. Click Next, name it "MH Grid Mapper", and click Finish.
  4. To add the icon: right-click the shortcut > Properties > Change Icon…,
     browse to:
         C:\Users\<username>\mhgridmapper\assets\icon.png
     Note: Windows shortcut icons require .ico format. If the PNG icon does
     not display correctly, skip this step — the shortcut will still work.

  Alternatively, create a batch file (mhgridmapper.bat) in the program folder
  with the following contents and create a shortcut to it:
      @echo off
      python "C:\Users\<username>\mhgridmapper\main.py"

Step 5 — Download tile data
-----------------------------
  See Section 6 for tile data setup.


================================================================================
4.  THE DESKTOP LAUNCHER (LINUX / RASPBERRY PI)
================================================================================

What Is a .desktop File?
--------------------------
  On Linux desktops (including Raspberry Pi OS with LXDE, as well as GNOME,
  KDE, XFCE, and others), a .desktop file is the standard way to define a
  clickable application launcher. It tells the desktop environment the
  program name, the command to run, and which icon to display.

  Windows uses shortcut (.lnk) files for the same purpose. See Section 3
  for Windows shortcut creation.

The mhgridmapper.desktop File
-------------------------------
  The file mhgridmapper/mhgridmapper.desktop is pre-configured for an
  installation at /opt/mhgridmapper. If you installed to a different
  location, edit the Exec= and Icon= lines to reflect the correct path
  before copying it:

      Exec=/usr/bin/python3 /home/<username>/mhgridmapper/main.py %u
      Icon=/home/<username>/mhgridmapper/assets/icon.png

Installing the Launcher
------------------------
  Copy the (adjusted) .desktop file to two locations:

    ~/.local/share/applications/mhgridmapper.desktop
        Makes MH Grid Mapper appear in the application menu.

    ~/Desktop/mhgridmapper.desktop
        Places a clickable icon on the Desktop (only if ~/Desktop/ exists).

  After copying, refresh the application database:
      update-desktop-database ~/.local/share/applications

If the Desktop Icon Did Not Appear
-------------------------------------
  1. Verify the Exec= path in the .desktop file points to your actual
     installation location and that main.py exists there.

  2. Mark the Desktop copy as executable:
         chmod +x ~/Desktop/mhgridmapper.desktop

  3. Some GNOME configurations hide .desktop file icons on the Desktop
     by default. Right-click the Desktop and look for "Allow Launching."

  4. Try logging out and back in to force a full desktop refresh.

  5. Check that ~/Desktop/ exists. MH Grid Mapper will still appear in
     the application menu even if no Desktop icon was created.

Running Without a Desktop Icon
--------------------------------
  MH Grid Mapper can always be launched from a terminal:

      python3 /home/<username>/mhgridmapper/main.py

  Or with a starting grid locator:

      python3 /home/<username>/mhgridmapper/main.py EL99hc


================================================================================
5.  STARTING THE PROGRAM
================================================================================

Linux / Raspberry Pi
---------------------
  Double-click the MH Grid Mapper icon on the Desktop or application menu.

  Or from a terminal:
      python3 /home/<username>/mhgridmapper/main.py

Windows
--------
  Double-click the MH Grid Mapper shortcut on the Desktop.

  Or from a Command Prompt:
      python C:\Users\<username>\mhgridmapper\main.py

First-Time Use
---------------
  On first launch the map canvas will be gray — tile data has not been
  loaded yet. See Section 6 to download tile data. The program is otherwise
  fully functional: you can enter grid locators, use the converter, and
  import station files before tiles are present.

  The last-used grid locator is restored automatically on subsequent startups.


================================================================================
6.  TILE DATA SETUP
================================================================================

MH Grid Mapper requires local tile data to display the map. Tiles are sourced
from the USGS National Map (public domain, US coverage only) and stored in
MBTiles format (.mbtiles files). Tiles only need to be downloaded once.

Tile data is separate from the program files and can be stored anywhere —
on the local hard drive, an external drive, or a USB flash drive.

Auto-Detection
---------------
  On startup, MH Grid Mapper automatically searches for .mbtiles files in:
    1. A USB drive labelled MHMAP_NA (plug in before launching)
    2. Any mounted drive under /mnt, /media, or /run/media
    3. The local tiles/ directory inside the program folder

  All .mbtiles files found are loaded simultaneously, so an overview file
  and regional detail files work together without any manual selection.

Recommended Tile Set
---------------------
  Two zoom levels are recommended for full usability:

  Zoom 4–9 (continental overview, ~112 MB):
    python3 /home/<username>/mhgridmapper/tile_downloader.py \
      --bbox 24.0 -125.0 50.0 -66.0 \
      --zoom 4-9 \
      --out /path/to/na_overview.mbtiles

  Zoom 9–12 (regional detail, ~400–900 MB per region):
    python3 /home/<username>/mhgridmapper/tile_downloader.py \
      --grid EL99hc \
      --zoom 9-12 \
      --out /path/to/local_detail.mbtiles

  Replace EL99hc with your home grid locator. The --grid flag automatically
  expands the bounding box a few degrees around that locator.

  For full continental US coverage at zoom 9–12, download by region
  (approximately 4.4 GB total when all regions are complete):

    Region           Approximate Size   Time at Default Rate
    ---------------  -----------------  --------------------
    Continental US overview  112 MB           20 min
    Southeast                810 MB            3 hrs
    Northeast                535 MB            2 hrs
    Midwest                  913 MB            3 hrs
    South Central            471 MB            2 hrs
    Mountain West            971 MB            3 hrs
    West Coast               599 MB            2 hrs

  Each download can be run independently and results stored in separate
  .mbtiles files. The app loads all files automatically.

Using the GUI Downloader
-------------------------
  File > Download Tiles… opens a dialog with region presets, zoom range
  selector, estimated tile count, and a progress bar.

Flash Drive Setup
------------------
  To use a USB flash drive for portable tile storage:
    1. Format the drive (exFAT recommended for files over 4 GB).
    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.

  Other files on the drive do not interfere with map operation.

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

Loading a Tile File Manually
------------------------------
  If tiles are not auto-detected, load them manually:
      File > Open MBTiles…    — select a single .mbtiles file
      File > Select Tile Folder… — select a directory tile cache


================================================================================
7.  TROUBLESHOOTING
================================================================================

"ModuleNotFoundError: No module named 'PIL'" on launch
--------------------------------------------------------
  Pillow is not installed. Open a terminal and run:
      pip3 install Pillow            (Linux / Raspberry Pi)
      pip install Pillow             (Windows)

  If you see "externally managed environment," add --user:
      pip3 install --user Pillow

"ModuleNotFoundError: No module named 'mgrs'" / Tools > Grid Converter does nothing
-------------------------------------------------------------------------------------
  The mgrs library is not installed. This error fires when you open
  Tools > Grid Converter, not on launch, so the rest of the app works.
  Install it with:
      pip3 install mgrs              (Linux / Raspberry Pi)
      pip install mgrs               (Windows)

"ModuleNotFoundError: No module named 'tkinter'"
-------------------------------------------------
  Tkinter is not installed. On Raspberry Pi OS, Ubuntu, or Debian:
      sudo apt install python3-tk

  Then launch MH Grid Mapper again.

"ModuleNotFoundError: No module named 'requests'"
--------------------------------------------------
  The requests library is only needed for the tile downloader
  (File > Download Tiles…). Install it with:
      pip3 install requests          (Linux / Raspberry Pi)
      pip install requests           (Windows)

  The rest of the program works without it.

Gray canvas on launch / "No tile data loaded" warning
------------------------------------------------------
  No tile data has been found. Either:
    - Tiles have not been downloaded yet (see Section 6).
    - The .mbtiles files are not in an auto-detected location.
  Use File > Open MBTiles… to load a file manually, or see Section 6 to
  download tiles and place them in an auto-detected location.

Map tiles appear blurry at high zoom
--------------------------------------
  The loaded .mbtiles files do not have data at the current zoom level.
  The app scales up the nearest available zoom level as a fallback.
  Download zoom 9–12 tiles for the region to get full detail.

Desktop icon does not appear after installation (Linux / Raspberry Pi)
-----------------------------------------------------------------------
  See "If the Desktop Icon Did Not Appear" in Section 4 above.

Desktop shortcut not visible after creation (Windows)
------------------------------------------------------
  The most common cause on Windows 11 is a OneDrive Desktop redirect.
  When OneDrive is active, the Desktop folder may be at:
      C:\Users\<username>\OneDrive\Desktop
  rather than:
      C:\Users\<username>\Desktop

  Create the shortcut directly in the OneDrive Desktop folder, or look
  for the shortcut in C:\Users\<username>\Desktop and move it.

Application menu entry does not appear (Linux)
-----------------------------------------------
  Refresh the desktop application database:
      update-desktop-database ~/.local/share/applications
  Then check the application menu. If it still does not appear, try
  logging out and back in.

Tile download is blocked or returns errors
-------------------------------------------
  Tile data is sourced from the USGS National Map
  (basemap.nationalmap.gov). Confirm you have an active internet
  connection. USGS services are occasionally offline for maintenance;
  wait a few minutes and try again.

  A high error count during download is normal when the bounding box
  covers open water — USGS has no topo data for ocean or large lake
  tiles, which are counted as errors and skipped.

Program opens but immediately closes (Windows)
-----------------------------------------------
  This usually means Python could not find a required module. Run the
  program from a Command Prompt to see the error message:
      python C:\Users\<username>\mhgridmapper\main.py
  Then install any missing packages reported (see above).

Config file location
---------------------
  Settings are saved to:
      Linux / Raspberry Pi:  ~/.config/mhgridmapper/config.json
      Windows:               C:\Users\<username>\.config\mhgridmapper\config.json

  Deleting this file resets all settings to defaults.


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