phyghtmap - Man Page

phyghtmap [options] [<hgt or GeoTiff file>] [<hgt or GeoTiff files>]

phyghtmap generates contour lines from NASA SRTM and smiliar data as well as from GeoTiff data in OSM formats.  For now, there are three ways to achieve this. First, it can be used to process existing source files given as arguments on the command line.  Note that the filenames must have the format [N|S]YY[W|E]XXX.hgt, with YY the latitude and XXX the longitude of the lower left corner of the tile.  Second, it can be used with an area definition as input.  The third way to use phyghtmap is to specify a polygon definition.  In the last two cases, phyghtmap will look for a cache directory (per default: ./hgt/) and the needed SRTM files.  If no cache directory is found, it will be created.  It then downloads all the needed NASA SRTM data files automatically if they are not cached yet.  There is also the possibility of masking the NASA SRTM data with data from www.viewfinderpanoramas.org which fills voids and other data lacking in the original NASA data set.  Since the 3 arc second data available from www.viewfinderpanoramas.org is complete for the whole world, good results can be achieved by specifying --source=view3.  For higher resolution, the 1 arc second SRTM data in version 3.0 can be used by specifying --source=srtm1 in combination with --srtm-version=3.0. SRTM 1 arc second data is, however, only available for latitudes between 59 degrees of latitude south and 60 degrees of latitude north.

-h,  --help

show this help message and exit

-a LEFT:BOTTOM:RIGHT:TOP, --area=LEFT:BOTTOM:RIGHT:TOP

choses the area to generate osm SRTM data for by bounding box. If necessary, files are downloaded from the NASA server.  Specify as <left>:<bottom>:<right>:<top> in degrees of latitude and longitude, respectively. Latitudes south of the equator and longitudes west of Greenwich may be given as negative decimal numbers. If this option is given, specified hgt files will be omitted.

--polygon=FILENAME

use polygon FILENAME as downloaded from http://download.geofabrik.de/clipbounds/ as bounds for the output contour data.  The computation time will be somewhat higher then.  If specified, a bounding box passed to the --area option will be ignored.

--download-only

only download needed files, don't write contour data.

-s STEP, --step=STEP

specify contour line step size in meters or feet, if using the --feet option. The default value is 20.

-f,  --feet

output contour lines in feet steps rather than in meters.

-0,  --no-zero-contour

say this, if you don't want the sea level contour line (0 m) (which sometimes looks rather ugly) to appear in the output.

-o PREFIX, --output-prefix=PREFIX

specify a prefix for the filenames of the output osm file(s).

-p PLOTPREFIX, --plot=PLOTPREFIX

specify the prefix for the files to write longitude/latitude/elevation data to instead of generating contour osm.

-c ELEVATION_MAJOR,ELEVATION_MEDIUM, --line-cat=ELEVATION_MAJOR,ELEVATION_MEDIUM

specify a string of two comma seperated integers for major and medium elevation categories, e. g. '200,100' which is the default. This is needed for fancy rendering.

-j NJOBS, --jobs=NJOBS

number of jobs to be run in parallel (POSIX only)

--osm-version=OSM-VERSION

pass a number as OSM-VERSION to use for the output. The default value is 0.6.  If you need an older version, try 0.5.

--write-timestamp

write the timestamp attribute of node and way elements in OSM XML and o5m output.  This might be needed by some interpreters.  In o5m output, this also triggers writing of changeset and user information.

--start-node-id=NODE-ID

specify an integer as id of the first written node in the output OSM xml.  It defaults to 10000000 but some OSM xml mergers are running into trouble when encountering non unique ids.  In this case and for the moment, it is safe to say 10000000000 (ten billion) then.

--start-way-id=WAY-ID

specify an integer as id of the first written way in the output OSM xml.  It defaults to 10000000 but some OSM xml mergers are running into trouble when encountering non unique ids.  In this case and for the moment, it is safe to say 10000000000 (ten billion) then.

--max-nodes-per-tile=MAXNODESPERTILE

specify an integer as a maximum number of nodes per generated tile.  It defaults to 1000000, which is approximately the maximum number of nodes handled properly by mkgmap.  For bigger tiles, try higher values.  For a single file output, say 0 here.

--max-nodes-per-way=MAXNODESPERWAY

specify an integer as a maximum number of nodes per way.  It defaults to 2000, which is the maximum value for OSM api version 0.6.  Say 0 here, if you want unsplitted ways.

--simplifyContoursEpsilon=EPSILON

simplify contour lines using the Ramer-Douglas-Peucker (RDP) algorithm with this EPSILON value.  The larger the value, the more simplified the contour lines.  The value passed will be directly used, i. e. in case of WGS84 based reference systems like EPSG:4326, the passed value is interpreted as degrees of latitude and longitude, respectively.  Use a value of 0.0 to remove only vertices on straight lines.  Sensible values to reduce the output file size while preserving resonable accuracy are dependent on the file resolution.  For SRTM3 data, some value between 0.0001 and 0.0005 seems reasonable, reducing the file size by something like one or two thirds.  Note that using contour line simplification will slow down contour line generation. The default is not to use RDP.

--simplifyContoursMaxDistance=MAX_VERTEX_DISTANCE

Do not delete all vertices while simplifying a contour line using RDP but only delete points within this range.  The default is to delete all dispensable vertices.  Only use this option if you want to get the benefit of RDP but need somehow close-lying points because of rendering issues or so. Using this option will dramatically slow down contour line generation.

--gzip=COMPRESSLEVEL

turn on gzip compression of output files. This reduces the needed disk space but results in higher computation times.  Specifiy an integer between 1 and 9.  1 means low compression and faster computation, 9 means high compression and lower computation.

--pbf

write protobuf binary files instead of OSM XML.  This reduces the needed disk space. Be sure the programs you want to use the output files with are capable of pbf parsing.  The output files will have the .osm.pbf extension.

--o5m

write o5m binary files instead of OSM XML.  This reduces the needed disk space. Be sure the programs you want to use the output files with are capable of o5m parsing.  The output files will have the .o5m extension.

--srtm=SRTM-RESOLUTION

use SRTM resolution of SRTM-RESOLUTION arc seconds. Possible values are 1 and 3, the default value is 3. For different SRTM data versions and map coverage, see the --srtm-version option.

--srtm-version=VERSION

use this VERSION of SRTM data. Supported SRTM versions are 2.1 and 3.  Version 2.1 has voids which were filled in version 3 using ASTER GDEM and other data. In version 2.1, only the US territory is included in the 1 arc second dataset.  In version 3, nearly the whole world is covered.  The default for this option is 3.  If you want the old version, say --srtmversion=2.1 here

--earthexplorer-user=EARTHEXPLORER_USERNAME

the username to use for earthexplorer login.  This is needed if you want to use NASA SRTM sources in version 3.0.  If you do not yet have an earthexplorer login, visit https://ers.cr.usgs.gov/register/ and create one.  Once specified, phyghtmap will store the earthexplorer login credentials unencrypted in a file called '.phyghtmaprc' in your home directory.  I. e., you only have to specify this option (and the --earthexplorer-password option) once.  In addition, the password specified on the command line may be read by every user on your system.  So, don't choose a password which you don't want to be disclosed to others.  This option should be specified in combination with the --earthexplorer-password option.

--earthexplorer-password=EARTHEXPLORER_PASSWORD

the password to use for earthexplorer login.  This option should be specified in combination with the --earthexplorer-user option.  For further explanation, see the help given for the --earthexplorer-user option.

--viewfinder-mask=VIEWFINDER-RESOLUTION

if specified, NASA SRTM data are masked with data from www.viewfinderpanoramas.org.  Possible values are 1 and 3 (for explanation, see the --srtm option).

--source=DATA-SOURCE, --data-source=DATA-SOURCE

specify a list of sources to use as comma-seperated string.  Available sources are 'srtm1', 'srtm3', 'view1' and 'view3'.  If specified, the data source will be selected using this option as preference list. Specifying --source=view3,srtm3 for example will prefer viewfinder 3 arc second data to NASA SRTM 3 arc second data.  Also see the --srtm-version option for different versions of SRTM data.

--corrx=SRTM-CORRX

correct x offset of contour lines.  A setting of --corrx=0.0005 was reported to give good results. However, the correct setting seems to depend on where you are, so it is may be better to start with 0 here.

--corry=SRTM-CORRY

correct y offset of contour lines.  A setting of --corry=0.0005 was reported to give good results. However, the correct setting seems to depend on where you are, so it may be better to start with 0 here.

--hgtdir=DIRECTORY

Cache directory for hgt files. The downloaded SRTM files are stored in a cache directory for later use. The default directory for this is ./hgt/ in the current directory.  You can specify another cache directory with this option.

--rewrite-indices

rewrite the index files and exit.  Try this if phyghtmap encounters problems when trying to download data files.

--void-range-max=MINIMUM_PLAUSIBLE_HEIGHT_VALUE

extend the void value range up to this height.  The hgt file format uses a void value which is -0x8000 or, in terms of decimal numbers, -32768.  Some hgt files contain other negative values which are implausible as height values, e. g. -0x4000 (-16384) or similar. Since the lowest place on earth is about -420 m below sea level, it should be safe to say -500 here in case you encounter strange phyghtmap behaviour such as program aborts due to exceeding the maximum allowed number of recursions.

-v,  --version

print version and exit.

Here are some usage examples

phyghtmap -a 8.59:49.34:8.78:49.45

generate openstreetmap xml for the area around Heidelberg, Germany

phyghtmap -a 8.59:49.34:8.78:49.45 -o heidelberg

same as above but save data to heidelberg_*.osm files instead of automatically generated filenames

phyghtmap -a -25:62:-12:68 -o iceland

This will not work since no SRTM data is available north of 60 degrees of latitude.

phyghtmap -a -25:62:-12:68 -o iceland --viewfinder-mask=3

Yes, this works.  There is data available for that area at www.viewfinderpanoramas.org.

phyghtmap -a -25:62:-12:68 -o iceland --viewfinder-mask=3 -j 16

Same as above but use 16 parallel processes for the contour line calculation.

phyghtmap -a -25:62:-12:68 -o iceland --source=view3,srtm3 -j 16

Essentially the same as above.

phyghtmap -a -25:62:-12:68 -o iceland -s 10 -c 100,50

Say this, if you want contour lines for Iceland with a step size of ten meters and major contour lines every 100 meters and medium contour lines every 50 meters.

phyghtmap -a 6:44:9:47 -o high_alps --viewfinder-mask=1

With this, you get wonderful contour line .osm with a resolution of 1 arc second where data is available at www.viewfinderpanoramas.org and NASA SRTM 3 arc second data elsewhere.

phyghtmap -a 6:44:9:47 -o high_alps --source=view1,view3,srtm3

Similar to the example above, but try to use viewfinder 1 arc second data first, viewfinder 3 arc second data second and srtm 3 arc second data last.

phyghtmap -a 6:44:9:47 --max-nodes-per-tile=100000 --max-nodes-per-way=400

This generates contour lines for the high alps.  Each output file will contain not more than 100000 nodes, each way therein will not contain more than 400 nodes.

phyghtmap -a 6:44:9:47 -j 2 --max-nodes-per-tile=0 --max-nodes-per-way=0 --gzip=9

This generates contour lines for the high alps and writes them to a single output file.  Note that it is possible to use multiple processes in parallel. --max-nodes-per-way=0 means that the ways will be as long as possible. --gzip=9 will produce gzipped output with a compression level of 9.

phyghtmap -a 6:44:9:47 -j 2 --max-nodes-per-tile=0 --max-nodes-per-way=0 --pbf

Same as above but output will be a osm protobuf binary file (.osm.pbf).

phyghtmap -a 6:44:9:47 -j 2 --max-nodes-per-tile=0 --max-nodes-per-way=0 --o5m

Same as above but output will be a o5m binary file (.o5m).

phyghtmap -s 5 NXXEYYY.hgt

Make contour line .osm with steps of 5 meters from file NXXEYYY.hgt. Note that no area was specified here, the area is read from the filename. You can use phyghtmap like this with .hgt files from sources other than NASA SRTM or www.viewfinderpanoramas.org, as long as the filenames contain the needed geographic information.

phyghtmap -p example_plotname -a 8.9:49.0:9.0:49.1

Do not generate contour line OSM xml but write a file example_plotname_*.xyz with lines containing space seperated values of longitude, latitude and elevation for each point stored in the corresponding .hgt file within the specified area.  For bigger areas, you will probably get more than one output file.

If you find a bug, please report it to <phyghtmap@aldw.de>.

Adrian Dempwolff <phyghtmap@aldw.de>

Copyright (c) 2009-2021 Adrian Dempwolff.  This code is distributed under the GNU General Public License version 2, or, at your option, any later version  <http://gnu.org/licenses/gpl.html>.