TopoTiler Readme
================

What Does This Do?
------------------

This program allows you to turn USGS GeoPDF files (such as those from the
`National Map <https://nationalmap.gov>`_ program) into tileable GeoTIFF
files.

By "tileable" I mean suitable for tiling into a complete raster
layer with gdalwarp or some other such tool. This implies that the so-called
"map collar" (i.e. the margin and any notation therein, basically anything
other than the represenataional body of the map) is removed and cropped
away.

Why Do This?
------------

It allows one to use such maps as the basis for a raster layer in QGIS
and other GIS programs.

The National Map products are very nice, high-quality topo maps. Their greatest
flaw is that they are distributed only as GeoPDF documents, and such a format
is really only useful for generating printed output (and not as input to a GIS).
Rendering such documents into tileable raster data is the easiest workaround
to this drawback.

Why Is This Only a Command-Line Program?
----------------------------------------

Two reasons:

1. I have not yet had time to write a GUI front end for it. I wrote TopoTiler
   to serve an occasional need of mine, and a command-line utility works well
   enough.
2. I am not yet certain if there is really a need to. A lot of that depends
   on the need for TopoTiler in the first place. If this program proves useful
   to a lot of people, and the consensus among its user base is that a GUI
   would be beneficial, I will probably add one.

Prerequisites
-------------

This program requires `python3 <https://python.org/>`_ (specifically, Python 3.9 or better), the
`Pillow Python library <https://python-pillow.org/>`_, and
`GDAL <https://gdal.org/>`_ to be installed.

make-tile
---------

This is the executable script to run.

Synopsis
^^^^^^^^

``make-tile`` [``-l``/``--layers`` *list*] [``-r``/``--resolution`` *dpi*] *file*

Convert USGS GeoPDF to tileable GeoTIFF. Input files must have an
extension of ``.pdf`` (case insensitive). Output files will be generated to
match each input file, with an extension of ``.tiff``.

Arguments
^^^^^^^^^

-l/--layers
        Comma-separated list of layers to include. See below for default.
-o/--output
        Specify output file. Defaults to input file with extention changed
        to .tiff.
-r/--resolution
        Output resolution in DPI. Default is 300.

Environment
^^^^^^^^^^^

``GDALBIN`` may be set to the directory containing the GDAL executables. If
so, they will only be looked for there. Else the standard execution path
will be searched.

``TMPDIR`` may be set to a place to write temporary files. Doing so is a
good idea if ``make-tile`` runs out of space in the default temporary files
area (this program makes very large scratch files).

Layers
^^^^^^

By default, all ``Map_Frame`` layers, except for
``Map_Frame.Projection_and_Grids`` and
``Map_Frame.Terrain.Shaded_Relief``, will be included. This behavior can be
changed with the ``--layers`` option.

MakeWaypoints
-------------

Synopsis
^^^^^^^^

``kotlin MakeWaypointsKt`` [``-latfirst``] *file*

Prompt for long, lat (or, with ``-latfirst``, lat, long) pairs and names and
create a file containing the specified waypoints. Coordinates are expected to
be two comma-separated floating-point numbers, with negative values indicating
locations in the southern or western hemispheres (i.e. the standard way of
representing coordinates in computer storage).

Basic sanity checks are performed on the coordinates entered.

Notes
^^^^^

This program is in Kotlin, despite my starting this project in Python, because
the JVM has a much more concise and simple way (i.e. ``XMLStreamWriter``) for
producing XML output.

Longitude, not latitude, is first by default because that is the way QGIS
exports coordinates.