PHYGHTMAP(1)

📦 version 2.23, in fedora 43, fedora 44

💖 PHYGHTMAP 💖

okay bestie, gather round — this is the manual page for phyghtmap, a NASA SRTM / GeoTiff → OSM xml (.osm), OSM pbf (.osm.pbf) or OSM o5m (.o5m) translator. she's giving main character energy and she makes contour lines. periodt. 🏔️✨

🌸 NAME 🌸

phyghtmap — NASA SRTM / GeoTiff → OSM xml (.osm), OSM pbf (.osm.pbf) or OSM o5m (.o5m) translator 💅

🦋 SYNOPSIS 🦋

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

like. that's it. that's the whole vibe. options plus some files if you feel like it 🎀

✨ DESCRIPTION ✨

okay so phyghtmap generates contour lines from NASA SRTM and similar data as well as from GeoTiff data in OSM formats. contour lines!! for maps!! we love a geographic queen 👑

for now, there are three ways to achieve this:

  1. process existing source files — you just hand her the files as arguments on the command line. easy. iconic. no notes. 🍓
  2. area definition as input 📐
  3. polygon definition 🗺️
ngl the filename thing is strict, so listen up: when you pass files directly, the filenames must have the format [N|S]YY[W|E]XXX.hgt, where YY is the latitude and XXX is the longitude of the lower left corner of the tile. no cap. if your filename isn't doing that, she's not gonna know what to do with it 😭

for the last two ways (area definition and polygon definition), phyghtmap will go looking for a cache directory — per default that's ./hgt/ — and the SRTM files she needs. 🔍

  • if no cache directory is found, she will create one. she's proactive like that 💁‍♀️
  • then she automatically downloads all the needed NASA SRTM data files if they aren't cached yet. no manual labour required, bestie 🫶

there's 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. so like, the glow-up is real 💖

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

but bestie, heads up: SRTM 1 arc second data is, however, only available for latitudes between 59 degrees of latitude south and 60 degrees of latitude north. outside that range? she simply does not have the data. it's giving geographically limited 💀

✨ OPTIONS ✨

okay bestie, this is the big one — every single flag, no skips, no skimming. grab a snack. 🍓

  • -h, --help — shows you this very help message and then dips out (exits). 🫶
  • -a LEFT:BOTTOM:RIGHT:TOP, --area=LEFT:BOTTOM:RIGHT:TOP — picks the area to generate osm SRTM data for, by bounding box. If it needs to, it'll download files from the NASA server. You write it as <left>:<bottom>:<right>:<top> in degrees of latitude and longitude, respectively. Latitudes south of the equator and longitudes west of Greenwich can be given as negative decimal numbers. Heads up: if you pass this option, any hgt files you specified get omitted. 💅
  • --polygon=FILENAME — use a polygon FILENAME (like the ones you download from http://download.geofabrik.de/clipbounds/) as the bounds for the output contour data. Lowkey the computation time will be somewhat higher then. And if you specify this, a bounding box passed to the --area option will be ignored. 🙈
  • --download-only — only download the needed files, don't write any contour data. That's it, that's the whole vibe.
  • -s STEP, --step=STEP — sets the contour line step size in meters, or in feet if you're using the --feet option. Default value is 20. ⭐
  • -f, --feet — output contour lines in feet steps instead of meters. imperial girlies rise. 👑
  • -0, --no-zero-contour — say this if you don't want the sea level contour line (0 m) showing up in the output — which sometimes looks rather ugly, fr fr.
  • -o PREFIX, --output-prefix=PREFIX — sets a prefix for the filenames of the output osm file(s).
  • -p PLOTPREFIX, --plot=PLOTPREFIX — sets the prefix for the files to write longitude/latitude/elevation data to, instead of generating contour osm. plot mode era. 🌸
  • -c ELEVATION_MAJOR,ELEVATION_MEDIUM, --line-cat=ELEVATION_MAJOR,ELEVATION_MEDIUM — give a string of two comma-separated integers for the 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). multitasking icon behavior.
  • --osm-version=OSM-VERSION — pass a number as OSM-VERSION to use for the output. Default value is 0.6. If you need an older version, try 0.5.
  • --write-timestamp — writes the timestamp attribute of node and way elements in OSM XML and o5m output. Some interpreters might need this. In o5m output, this also triggers writing of changeset and user information. 🎀
  • --start-node-id=NODE-ID — specify an integer as the id of the first written node in the output OSM xml. It defaults to 10000000, but some OSM xml mergers run into trouble when they encounter non-unique ids. In that case, and for the moment, it's safe to say 10000000000 (ten billion) then. 💀
  • --start-way-id=WAY-ID — specify an integer as the id of the first written way in the output OSM xml. It defaults to 10000000, but some OSM xml mergers run into trouble when they encounter non-unique ids. In that case, and for the moment, it's safe to say 10000000000 (ten billion) then. (yes, same deal as the node one, they're twins.)
  • --max-nodes-per-tile=MAXNODESPERTILE — specify an integer as the maximum number of nodes per generated tile. It defaults to 1000000, which is approximately the maximum number of nodes that mkgmap handles properly. For bigger tiles, try higher values. For a single file output, say 0 here.
  • --max-nodes-per-way=MAXNODESPERWAY — specify an integer as the 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 — simplifies contour lines using the Ramer-Douglas-Peucker (RDP) algorithm with this EPSILON value. The larger the value, the more simplified the contour lines get. The value you pass is used directly, i.e. in the 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 that reduce the output file size while preserving reasonable accuracy depend 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. 😭 (so much lore, but it ate)
  • --simplifyContoursMaxDistance=MAX_VERTEX_DISTANCE — when simplifying a contour line using RDP, don't delete all vertices — only delete points within this range. The default is to delete all dispensable vertices. Only use this option if you want the benefit of RDP but somehow need close-lying points because of rendering issues or so. Using this option will dramatically slow down contour line generation. 🔥 (dramatic, but it said what it said)
  • --gzip=COMPRESSLEVEL — turns on gzip compression of output files. This reduces the needed disk space but results in higher computation times. Specify an integer between 1 and 9. 1 means low compression and faster computation, 9 means high compression and lower computation. ⚖️
  • --pbf — writes 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 — writes 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 don't 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.
🚨 bestie PLEASE read that one twice. unencrypted .phyghtmaprc, and anyone on your system can read a password you put on the command line. don't be out here leaking your secrets, i'm begging. 💀
  • --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 a comma-separated string. Available sources are 'srtm1', 'srtm3', 'view1' and 'view3'. If specified, the data source will be selected using this option as a 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 the 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 may be better to start with 0 here.
  • --corry=SRTM-CORRY — correct the 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. (same energy, y axis edition 🎀)
  • --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 — rewrites the index files and exits. Try this if phyghtmap encounters problems when trying to download data files. the lil fix-it button.
  • --void-range-max=MINIMUM_PLAUSIBLE_HEIGHT_VALUE — extends 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 — prints the version and exits. the "who even am i" flag. 💅

🌸 USAGE EXAMPLES 🌸

Okay bestie, this is the part where it all comes together. Here are some usage examples — copy them, remix them, make them your whole personality, idk. 💖

phyghtmap -a 8.59:49.34:8.78:49.45

Generate openstreetmap xml for the area around Heidelberg, Germany. Cute little city, cute little bounding box, iconic. 🎀

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. You're naming your babies now, slay. 💅

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

This will not work since no SRTM data is available north of 60 degrees of latitude. 🫠 Not me picking a bounding box that literally doesn't exist in the data. Tragic. The vibes are giving "empty results".

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. 🦋 Bestie we found the data, we're so back.

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. Sixteen. Processes. It's giving main character energy, the CPU is literally shaking. 🔥

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

Essentially the same as above. Yeah basically the same, just said different. Lowkey iconic either way. 💜

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. The way that 100,50 is doing the whole major/medium hierarchy thing — obsessed. ✨

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. Wonderful. WONDERFUL. It said what it said and it's correct. 🌈

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. Priority order, we love a ranking. 👑

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. Boundaries, bestie. We're setting them. 🎀

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. One file, many processes, max compression — it's giving efficiency icon. 💅

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. She reads the filename and just knows. iykyk. 💜

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. Plotting era. 📈

🐛 BUGS 🐛

If you find a bug, please report it to <phyghtmap@aldw.de>. Fr fr, tell them. Don't just suffer in silence, bestie. 🫶

💖 AUTHOR 💖

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

And that's the whole page, bestie! ✨ This was phyghtmap version 2.23, dated January 2021, and you read the entire PHYGHTMAP(1) man page like a champion. Go make some contour lines. 💅🌸🦋
📦 where this page comes from