================================================================================ 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//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//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//mhgridmapper/venv/bin/python3 /home//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//mhgridmapper|g' \ /home//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\\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\\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\\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\\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//mhgridmapper/main.py %u Icon=/home//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//mhgridmapper/main.py Or with a starting grid locator: python3 /home//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//mhgridmapper/main.py Windows -------- Double-click the MH Grid Mapper shortcut on the Desktop. Or from a Command Prompt: python C:\Users\\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//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//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\\OneDrive\Desktop rather than: C:\Users\\Desktop Create the shortcut directly in the OneDrive Desktop folder, or look for the shortcut in C:\Users\\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\\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\\.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 ================================================================================