annotate Readme.rst @ 12:698b3335a63d default tip

Fix leading comment.
author David Barts <n5jrn@me.com>
date Thu, 26 Aug 2021 23:06:33 -0700
parents 1944acce0e6f
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
1 TopoTiler Readme
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
2 ================
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
3
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
4 What Does This Do?
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
5 ------------------
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
6
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
7 This program allows you to turn USGS GeoPDF files (such as those from the
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
8 `National Map <https://nationalmap.gov>`_ program) into tileable GeoTIFF
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
9 files.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
10
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
11 By "tileable" I mean suitable for tiling into a complete raster
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
12 layer with gdalwarp or some other such tool. This implies that the so-called
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
13 "map collar" (i.e. the margin and any notation therein, basically anything
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
14 other than the represenataional body of the map) is removed and cropped
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
15 away.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
16
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
17 Why Do This?
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
18 ------------
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
19
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
20 It allows one to use such maps as the basis for a raster layer in QGIS
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
21 and other GIS programs.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
22
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
23 The National Map products are very nice, high-quality topo maps. Their greatest
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
24 flaw is that they are distributed only as GeoPDF documents, and such a format
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
25 is really only useful for generating printed output (and not as input to a GIS).
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
26 Rendering such documents into tileable raster data is the easiest workaround
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
27 to this drawback.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
28
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
29 Why Is This Only a Command-Line Program?
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
30 ----------------------------------------
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
31
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
32 Two reasons:
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
33
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
34 1. I have not yet had time to write a GUI front end for it. I wrote TopoTiler
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
35 to serve an occasional need of mine, and a command-line utility works well
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
36 enough.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
37 2. I am not yet certain if there is really a need to. A lot of that depends
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
38 on the need for TopoTiler in the first place. If this program proves useful
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
39 to a lot of people, and the consensus among its user base is that a GUI
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
40 would be beneficial, I will probably add one.
10
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
41
0
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
42 Prerequisites
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
43 -------------
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
44
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
45 This program requires `python3 <https://python.org/>`_ (specifically, Python 3.9 or better), the
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
46 `Pillow Python library <https://python-pillow.org/>`_, and
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
47 `GDAL <https://gdal.org/>`_ to be installed.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
48
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
49 make-tile
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
50 ---------
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
51
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
52 This is the executable script to run.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
53
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
54 Synopsis
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
55 ^^^^^^^^
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
56
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
57 ``make-tile`` [``-l``/``--layers`` *list*] [``-r``/``--resolution`` *dpi*] *file*
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
58
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
59 Convert USGS GeoPDF to tileable GeoTIFF. Input files must have an
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
60 extension of ``.pdf`` (case insensitive). Output files will be generated to
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
61 match each input file, with an extension of ``.tiff``.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
62
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
63 Arguments
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
64 ^^^^^^^^^
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
65
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
66 -l/--layers
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
67 Comma-separated list of layers to include. See below for default.
10
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
68 -o/--output
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
69 Specify output file. Defaults to input file with extention changed
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
70 to .tiff.
0
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
71 -r/--resolution
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
72 Output resolution in DPI. Default is 300.
10
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
73
0
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
74 Environment
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
75 ^^^^^^^^^^^
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
76
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
77 ``GDALBIN`` may be set to the directory containing the GDAL executables. If
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
78 so, they will only be looked for there. Else the standard execution path
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
79 will be searched.
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
80
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
81 ``TMPDIR`` may be set to a place to write temporary files. Doing so is a
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
82 good idea if ``make-tile`` runs out of space in the default temporary files
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
83 area (this program makes very large scratch files).
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
84
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
85 Layers
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
86 ^^^^^^
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
87
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
88 By default, all ``Map_Frame`` layers, except for
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
89 ``Map_Frame.Projection_and_Grids`` and
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
90 ``Map_Frame.Terrain.Shaded_Relief``, will be included. This behavior can be
10
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
91 changed with the ``--layers`` option.
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
92
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
93 MakeWaypoints
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
94 -------------
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
95
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
96 Synopsis
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
97 ^^^^^^^^
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
98
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
99 ``kotlin MakeWaypointsKt`` [``-latfirst``] *file*
0
c20b5314774f Initial commit.
David Barts <n5jrn@me.com>
parents:
diff changeset
100
10
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
101 Prompt for long, lat (or, with ``-latfirst``, lat, long) pairs and names and
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
102 create a file containing the specified waypoints. Coordinates are expected to
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
103 be two comma-separated floating-point numbers, with negative values indicating
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
104 locations in the southern or western hemispheres (i.e. the standard way of
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
105 representing coordinates in computer storage).
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
106
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
107 Basic sanity checks are performed on the coordinates entered.
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
108
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
109 Notes
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
110 ^^^^^
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
111
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
112 This program is in Kotlin, despite my starting this project in Python, because
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
113 the JVM has a much more concise and simple way (i.e. ``XMLStreamWriter``) for
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
114 producing XML output.
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
115
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
116 Longitude, not latitude, is first by default because that is the way QGIS
1944acce0e6f Add --output= option.
David Barts <n5jrn@me.com>
parents: 0
diff changeset
117 exports coordinates.