================================================================================
  F104Mapper – Installation Guide
  Stephen Clay McGehee, KN4AM
================================================================================


TABLE OF CONTENTS
-----------------
  1.  System Requirements
  2.  First-Time Setup: Linux / Raspberry Pi / macOS
  3.  First-Time Setup: Windows
  4.  What setup.py Does
  5.  The Desktop Launcher (Linux / Raspberry Pi)
  6.  Starting the Program
  7.  Troubleshooting Setup Problems


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

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

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

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

Internet Connection
-------------------
  An internet connection is required for the one-time setup only.
  After setup, F104Mapper runs completely offline.


================================================================================
2.  FIRST-TIME SETUP: LINUX / RASPBERRY PI / MACOS
================================================================================

  1. Open a terminal and navigate to the F104Mapper folder:

         cd /home/<username>/f104mapper

  2. Run the setup script:

         python3 setup.py

     Setup will display progress as it works through three steps:
       [1/3]  Installing Python packages
       [2/3]  Downloading offline map data
       [3/3]  Installing desktop launcher

     The entire process takes a few minutes depending on your internet
     connection speed.

  3. When setup completes, start F104Mapper (see Section 6) and verify
     the map loaded correctly — the map of North America should display
     with its land masses, country borders, and state/province borders.

  setup.py is safe to re-run at any time — it will skip steps that are
  already complete and reinstall anything that is missing.


================================================================================
3.  FIRST-TIME SETUP: WINDOWS
================================================================================

  1. Open a Command Prompt and navigate to the F104Mapper folder:

         cd C:\Users\<username>\f104mapper

  2. Run the setup script:

         python setup.py

     Setup will display progress as it works through three steps:
       [1/3]  Installing Python packages
       [2/3]  Downloading offline map data
       [3/3]  Installing desktop launcher

     The entire process takes a few minutes depending on your internet
     connection speed.

  3. When setup completes, start F104Mapper (see Section 6) and verify
     the map loaded correctly — the map of North America should display
     with its land masses, country borders, and state/province borders.

  setup.py is safe to re-run at any time — it will skip steps that are
  already complete and reinstall anything that is missing.


================================================================================
4.  WHAT SETUP.PY DOES
================================================================================

  Step 1 of 3 – Python Virtual Environment
  -----------------------------------------
  Creates a self-contained Python environment in the f104mapper/venv/
  folder. This keeps F104Mapper's packages isolated from any other Python
  software on the system and ensures consistent behavior regardless of what
  else is installed.

  If a virtual environment already exists for a different Python version,
  setup.py removes it and creates a fresh one for the current version.

  Packages installed into the virtual environment:
    - matplotlib    (map rendering)
    - numpy         (numerical operations)
    - pyshp         (shapefile map data reader)
    - pillow        (image export support)

  Step 2 of 3 – Offline Map Data
  --------------------------------
  Downloads four Natural Earth 1:110m shapefiles used for the offline map:
    - Land masses
    - Country borders
    - State / province borders
    - Lakes

  Map data is saved to:   f104mapper/data/shapefiles/

  These files are downloaded once and never change. If the download is
  interrupted, re-run setup.py to resume.

  Step 3 of 3 – Desktop Launcher
  --------------------------------
  Linux / Raspberry Pi:
    Creates a desktop launcher in the standard FreeDesktop locations.
    See Section 5 for full details.

  Windows:
    Creates an F104Mapper.lnk shortcut on the Desktop using the
    104_icon.ico icon. The shortcut points to run.bat in the
    f104mapper folder.


================================================================================
5.  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 .lnk shortcut files for the same purpose. setup.py creates
  the correct launcher type automatically for each platform.

What setup.py Installs
------------------------
  setup.py reads f104mapper.desktop from the program folder, fills in the
  correct Exec= and Icon= paths for your system, marks it executable, and
  copies it to two locations:

    ~/.local/share/applications/f104mapper.desktop
        Makes F104Mapper appear in the application menu.

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

  After copying, setup.py refreshes the desktop application database so the
  launcher appears immediately — no logout is required.

The f104mapper.desktop File in the Program Folder
---------------------------------------------------
  The file f104mapper/f104mapper.desktop is a template used by setup.py.
  It contains placeholder paths that setup.py fills in at install time.

  Do not use this file directly as a launcher. The paths it contains will
  not match your system unless setup.py has already run and patched them.
  Always use the installed copy in ~/.local/share/applications/ or on your
  Desktop.

If the Desktop Icon Did Not Appear
-------------------------------------
  If setup.py ran without errors but no Desktop icon appeared:

  1. Re-run setup.py — it is safe to run again:

         cd /home/<username>/f104mapper
         python3 setup.py

  2. If the icon still does not appear after re-running, try logging out
     and back in to force a full desktop refresh.

  3. Some GNOME configurations hide .desktop file icons on the Desktop
     by default. Right-click the Desktop and look for an option such as
     "Allow Launching" to enable it.

  4. Check that ~/Desktop/ exists. If your system uses a different folder
     name for the Desktop (uncommon), the icon will not appear there, but
     F104Mapper will still be in the application menu.

Running Without a Desktop Icon
--------------------------------
  F104Mapper can always be launched from a terminal without any icon:

      bash /home/<username>/f104mapper/run.sh

  Or directly via the virtual environment Python:

      /home/<username>/f104mapper/venv/bin/python3 \
          /home/<username>/f104mapper/f104mapper.py


================================================================================
6.  STARTING THE PROGRAM
================================================================================

Linux / Raspberry Pi
---------------------
  Double-click the F104Mapper icon on the Desktop.

  Or from a terminal:
      bash /home/<username>/f104mapper/run.sh

  If setup has not been run yet, the launcher will display an error
  message explaining what to do.

Windows
--------
  Double-click the F104Mapper shortcut on the Desktop.

  Or from a Command Prompt:
      C:\Users\<username>\f104mapper\run.bat


================================================================================
7.  TROUBLESHOOTING SETUP PROBLEMS
================================================================================

setup.py fails during package installation
--------------------------------------------
  Confirm you have an active internet connection, then re-run setup.py.
  Check that Python 3.9 or newer is installed:

      python3 --version       (Linux / Raspberry Pi / macOS)
      python  --version       (Windows)

setup.py fails during map data download
------------------------------------------
  The Natural Earth data server (naciscdn.org) must be reachable.
  Check your internet connection and re-run setup.py. The download will
  restart from the beginning (files are small — under 1 MB each).

Map does not display / shows "matplotlib not installed"
---------------------------------------------------------
  The Python packages were not installed successfully. Re-run setup.py:

      cd /home/<username>/f104mapper
      python3 setup.py

  Then restart F104Mapper.

Map displays a plain green rectangle
--------------------------------------
  The shapefile map data did not download. Re-run setup.py (see above).
  The map should display land masses, borders, and coastlines after
  successful setup.

"Virtual environment not found" error on launch
-------------------------------------------------
  setup.py has not been run yet, or the venv/ folder was deleted.
  Open a terminal and run:

      cd /home/<username>/f104mapper
      python3 setup.py

Desktop icon does not appear after setup
------------------------------------------
  See "If the Desktop Icon Did Not Appear" in Section 5 above.

Application menu entry does not appear after setup
----------------------------------------------------
  The desktop application database may need a manual refresh:

      update-desktop-database ~/.local/share/applications

  Then check the application menu. If it still does not appear, try
  logging out and back in.


================================================================================
  End of F104Mapper Installation Guide
  F104Mapper is designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================
