================================================================================
  TileDownloader — User Manual
  Version 0.1.0
  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================


OVERVIEW
--------
TileDownloader fetches USGS National Map topo tiles (public domain, US
coverage only) and saves them as .mbtiles files for offline use with
SitRepMapper (and MHGridMapper). It also shows what tile coverage you
already have on disk, and can find and remove tiles that are needlessly
duplicated across multiple files in your library.

TileDownloader is included with SitRepMapper — there is nothing separate
to install. SitRepMapper's File > Download Tiles… launches it as its own
window, as an independent program; it can also be run on its own (see
LAUNCHING below) with no dependency on SitRepMapper being open.

Key capabilities:
  - Download a rectangular area at a chosen zoom range, either by typing
    coordinates or by dragging a selection on the Graphical View map
  - Three area presets (Continental US, Alaska, Hawaii) as a starting point
  - A live estimate of tile count and download size before starting
  - A Tile Library list showing every .mbtiles file already on disk, its
    coverage area, zoom range, tile count, and size
  - Graphical View: a US-wide chart showing which tiles you already have
    at a given zoom level, so you can see gaps before downloading
  - Find & Remove Duplicate Tiles: reclaims space wasted when the same
    tile ends up saved in more than one file, without ever deleting
    anything outright

More Information:  SitRepNet.com


LAUNCHING THE PROGRAM
----------------------
From SitRepMapper:
  File > Download Tiles…

Standalone, from the terminal (path depends on where SitRepMapper is
installed — this is the tiledownloader/ subfolder inside it):
  python3 <sitrepmapper-folder>/tiledownloader/main.py     (Linux/RPi)
  python <sitrepmapper-folder>\tiledownloader\main.py      (Windows)

TileDownloader requires the "requests" Python package to actually
download tiles:
  pip3 install requests           (Linux / Raspberry Pi)
  pip install requests            (Windows)
Without it, the program still opens normally — the Tile Library list,
Graphical View, and duplicate cleanup all work — but starting a
download shows an error explaining that "requests" needs to be
installed.

Command-line usage (no GUI, for scripting a download):
  python3 tile_downloader.py --north <lat> --south <lat> \
      --east <lon> --west <lon> --zoom <min>-<max> --out <file.mbtiles>
  (Windows: same arguments, run with "python" instead of "python3")

  --zoom defaults to 5-12 if omitted. Progress and a final summary
  (tiles downloaded / skipped as already-present-elsewhere / errored)
  print to the terminal. This is the same download logic as the GUI's
  Start Download, including skipping tiles already present in a
  different .mbtiles file in the same output folder.


THE DOWNLOAD TAB
------------------
Tile Library Folder
  The folder .mbtiles files are downloaded into and read from. Browse…
  opens a folder picker; the folder is remembered between sessions.

Area to Download
  Type North/South/East/West latitude/longitude directly, or click a
  preset (Continental US, Alaska, Hawaii) to fill them in. Alaska and
  Hawaii aren't shown on the Graphical View chart, but downloading and
  the Tile Library list both work the same for them.

Zoom Levels
  Min/Max spinboxes (2-16). Higher zoom means more detail and
  exponentially more tiles — click Estimate to see the total tile count
  and an approximate download size (~15 KB/tile) for the current area
  and zoom range before committing.

  For a sense of scale, here's the Continental US preset at increasing
  zoom ranges (each added level roughly quadruples the tile count, so a
  range's size is dominated by its highest zoom):

    Zoom     Tiles      Size
    ------   -------    --------
    5             28    ~420 KB   (whole country, no scrolling)
    5-8        1,473    ~22 MB    (down to state/regional detail)
    5-10      21,608    ~317 MB
    5-12     340,032    ~4.9 GB

  Example — download zoom 5-8 for the whole CONUS from the command line
  (~22 MB total):
    python3 tile_downloader.py --north 50.0 --south 24.0 \
        --east -66.0 --west -125.0 --zoom 5-8 --out conus_5-8.mbtiles
  Or in the GUI: click the Continental US preset, set Zoom Min/Max to
  5 and 8, click Estimate to confirm, then Start Download.

Download
  Save as: the output .mbtiles filename. If that name already exists in
  the Tile Library Folder, a number is added automatically (_2, _3, …,
  incrementing an existing number rather than stacking a new one) — a
  download never overwrites an earlier file. Characters not valid in a
  plain filename, or not recognized by SitRepMapper's own file loading,
  are stripped automatically; you're told if that happened.

  Start Download begins fetching tiles into the named file, with a
  progress bar and status line. Downloading only skips tiles that
  already exist in a DIFFERENT, already-downloaded .mbtiles file
  elsewhere in your Tile Library Folder — it does not skip anything from
  the current run. Stop cancels the download in progress: nothing from
  that run is kept, not even the tiles already fetched before you
  clicked Stop, so a stopped download must be started over from scratch,
  not resumed.

Tile Library — what you already have
  Lists every .mbtiles file in the Tile Library Folder: its geographic
  coverage, zoom range, tile count, and file size. Refresh Library
  rescans the folder (useful if you added or removed files outside the
  program).


GRAPHICAL VIEW TAB
---------------------
A US-wide chart (Continental US only) for seeing what you have before
you download, rather than guessing from coordinates.

  Zoom Level (left sidebar): pick a single zoom level to inspect. The
  number beside each level is how many tiles you already have at that
  zoom, summed across your whole library. A Legend below it shows what
  each color on the chart means (already downloaded, not yet downloaded,
  your dragged selection).

  Drag on the chart to mark a rectangular area. On release, the chart
  overlays a per-tile grid at the selected zoom level:
    green fill        = already downloaded
    dashed orange      = not yet downloaded
  The status line reports the total tile count at that zoom, how many
  you already have, and how many are still needed. If the selected area
  is too large at that zoom level (too many tiles to grid out), you're
  told to draw a smaller area or pick a lower zoom instead.

  Use this area → copies the dragged area's coordinates and the selected
  zoom (as both Min and Max) back to the Download tab and switches to
  it, ready for Estimate / Start Download. Adjust the zoom range there
  afterward if you want more than one level.


FIND & REMOVE DUPLICATE TILES
--------------------------------
Tools > Find & Remove Duplicate Tiles… scans every .mbtiles file in the
current Tile Library Folder for tiles stored in more than one file (this
can happen after downloading overlapping areas, or after the file-
naming bug that used to stack numeric suffixes instead of incrementing
them). If nothing overlaps, you're told so and nothing changes.

If duplicates are found, a plan is shown: files are ranked by total tile
count (largest first), and for any tile stored in more than one file,
the copy in the highest-ranked file is kept — every other copy is
counted as reclaimable. Click Remove Duplicates to proceed, or Cancel to
back out with nothing changed.

Nothing is ever deleted outright. Redundant tiles are copied into a
RemovedDuplicates folder inside your Tile Library Folder first, then
removed from the smaller file and that file is compacted — or, if
removing its duplicates would leave a file with zero tiles left, the
now-empty file itself is removed (its tiles are already safe in the
archive). Disk space isn't actually freed until you delete the
RemovedDuplicates folder yourself, once you're confident you don't need
the safety copies. Re-running this later just adds any new duplicates
to the same archive.


CONFIGURATION
--------------
Settings (Tile Library Folder, last-used area/zoom, window size/position)
are saved to:
  Linux / Raspberry Pi:  ~/.config/tiledownloader/config.json
  Windows:                C:\Users\<username>\.config\tiledownloader\config.json

Deleting this file resets everything to defaults; it does not touch any
.mbtiles files in your Tile Library Folder.


MENU REFERENCE
-----------------
  File > Quit                              Save settings and exit
  Tools > Find & Remove Duplicate Tiles…   See above
  Help > About                             Version and credits


TROUBLESHOOTING
------------------
"The 'requests' library is required for downloading tiles"
  Install it with:
      pip3 install requests           (Linux / Raspberry Pi)
      pip install requests            (Windows)
  Everything except actually downloading tiles works without it.

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

Download seems stuck / very slow
  Tiles are fetched one at a time with a short delay between requests
  (courtesy to the USGS tile server) — a large area at a high zoom can
  legitimately take a long time. Check the progress bar and status line
  for actual progress. Note that Stop discards the entire run rather
  than saving partial progress (see above) — for a very large area,
  consider downloading a smaller piece at a time instead of starting
  over repeatedly.

A file appears twice in the Tile Library list with slightly different
coverage or zoom ranges
  This can happen from downloading the same area in more than one
  session at different zoom levels. It isn't a problem by itself —
  SitRepMapper loads every .mbtiles file in a folder together — but
  Tools > Find & Remove Duplicate Tiles… will reclaim any tiles that
  actually ended up saved in both.


================================================================================
  End of TileDownloader User Manual
  Designed and developed by Stephen Clay McGehee, KN4AM
  Coding done using Claude Code AI
  See SitRepNet.com for more information
================================================================================
