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.
-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.