set-dem-source Command

Contents

Specifies which DEM (digital elevation model) source Maperitive should use for various DEM-related operations. You can specify built-in sources (like SRTM1 and SRTM3) or your custom source.

Usage 

 set-dem-source 
     name=<DEM source name>

Parameters:

Using Built-In DEM Sources

Built-in DEM sources are easier to use because Maperitive automatically downloads the DEM data from the required web server. Currently there are three DEM sources built into Maperitive:

Access to SRTM V3

NASA's SRTM V3 is generally the best DEM source that you can get. It does not have data voids and its R1 (1 arc second) variant is now available for most of the world. The only drawback is that the data can only be accessed through NASA's EarthData portal login (and not anonymously like it is possible for the old V2 data).

Technical Details

EarthData uses OAuth 2 protocol, but NASA does not seem to allow external applications (like Maperitive) to register and receive user authentication tokens. The only way I could find to allow Maperitive to access their DEM data was to insert OAuth authentication token directly into HTTP requests. Each user that wants to use SRTM V3 data will need to register on EarthData portal and then perform the (somewhat hacky) procedure described in following subsections.

NOTE: Maperitive stores the authentication token in cleartext in its settings file. While I do not see EarthData as a very important or security-sensitive application, I still feel obliged to warn you about this. If you do not want this piece of information to be stored in cleartext, do not provide it to Maperitive and do not use the SRTM V3 dataset.

The Procedure

The procedure assumes you are using Chrome as your browser and it describes instructions on how to inspect the HTTP request using Chrome's Developer Tools. Most (all?) other browsers also allow HTTP request inspection, either through built-in tools or using a browser extension. Google is your friend here.

Delete Existing SRTMV3R1/SRTMV3R3 Cache Index

In order for this procedure to work correctly, you may need to delete any existing tile index files stored in the cache, if they were created by Maperitive prior to version 2.4.0. The two files to delete are Cache/Rasters/SRTMV3R1/TileIndex.dat and Cache/Rasters/SRTMV3R3/TileIndex.dat under the Maperitive installation directory.

Registering on EarthData Portal

The first thing you need to do is to register yourself on the EarthData portal, if you haven't done that already. You will also have to allow NASA's applications access to your newly registered account (read the instructions on the portal).

Access A Sample SRTM File

After registering on the EarthData portal, visit the SRTM V3 server by entering https://e4ftl01.cr.usgs.gov/MEASURES/SRTMGL3.003/2000.02.11/ URL in the browser. Be patient while it loads the directory list, the file list is huge and the server is slow.

Now open Chrome's Developer Tools (F12 keyboard shortcut) and click on its Network tab. After that, click on one of the .hgt.zip files in the directory list (like https://e4ftl01.cr.usgs.gov/MEASURES/SRTMGL3.003/2000.02.11/N00E006.SRTMGL3.hgt.zip) to download it. The browser will ask you for EarthData login credentials and after the successful login, the network tab should contain an entry that looks something like the one below (be sure to use the one with status 200, not 302!):

Now click on that entry and the details pane will show up:

Scroll down to Request Headers section and look for Cookie entry starting with 'DATA=':

What comes after that '=' character is a string called authentication token and we need to supply it to Maperitive for it to be able to download SRTM tiles on your behalf. So copy the token into the clipboard (or a text editor) and continue to the final step.

Give Maperitive the Authentication Token

Run Maperitive and enter the following command in the Command Prompt:

 set-setting name=user.earthdata-auth-token value=<auth token>

(replace <auth token> with your own authentication token copied in the clipboard, without <> brackets).

That is it. Now you should be able to access the SRTM V3 tiles within Maperitive - try it out using one of Maperitive's relief functions. And also be sure to read the following Troubleshooting section.

Troubleshooting SRTM V3 Access

You may encounter several errors when trying to download SRTM V3 tiles:

  1. "OAuth 2 authentication token for NASA's server is not provided, unable to access the SRTM data" - this means you have not provided the authentication token.
  2. "The remote server returned an error: (401) Unauthorized" - the authentication token you provided is no longer valid. This either means you have switched your computer to another network or that the token is too old.
  3. "There is no 'SRTMV3R1' DEM coverage for the requested area" - you probably did not delete the existing tile index files.

In all of the above cases, repeat the procedure described above.

Using Your Own Custom DEM Sources

TODO

See also: