KOContour

Contour map display for elevation data files or DEM elevation servers such as Open Topo Data and OpenTopography.

Overview

KOContour reads in elevation data files from your computer and displays them as contour maps. A typical data file would look like this:

type  latitude        longitude       altitude (ft)  name         desc
T     53.231479474    -6.299506408    1672.9         Stillorgan   Ireland
T     53.231479474    -6.299119017    1678.8
T     53.231479474    -6.298731626    1687.9
T     53.231479474    -6.298344235    1698.1
T     53.231479474    -6.297956845    1704.0
T     53.231479474    -6.297569454    1708.2
T     53.231479474    -6.297182063    1709.2

The example above assumes tab-separated columns, which is recommended so that your description field can then use commas. In the sections below there are screenshots showing how the main features work.

The most up to date version of this information will always be the online version.

Creating the Input Data Files

Use a DEM Server (recommended for most people)

There are a number of Digital Elevation Model (DEM) servers on the internet, and KOContour can fetch your elevation grid directly from two of them — no external website needed. These are built in, choose one from the DEM server suggestions which will pop up if you type open into the DEM server URL field.

• Open Topo Data https://api.opentopodata.org/ — needs no key. It limits you to 100 locations per call at one-second intervals and 100,000 points per day, so a large grid can be a little slow. You can also host this server yourself to remove those limits.
• OpenTopography https://portal.opentopography.org/ — fetches the whole region in a single call, so it is much faster for large or dense grids and offers more datasets (including 10 m USGS 3DEP for the USA). It needs a free API key: register on its site, then click the padlock button which appears beside the server box when the opentopography.org server is chosen, and paste in your key (tip: right-click that padlock to copy the “get a key” web address). KOContour picks the best dataset for your selected country automatically — COP30 worldwide, USGS 10 m for the US.

You should type the URL of your chosen server in the DEM server box. KOContour knows how to “talk” to these, and any others which use the same protocol, such as if you run your own in a Docker environment.

Open Topo Data — https://api.opentopodata.org/
OpenTopography — https://portal.opentopography.org/

The trailing /API is optional — KOContour accepts either form. Both are also already in the server dropdown, so you can just select one.

The “Open Topo Data API” — implements a custom REST API: GET/POST /v1/{dataset}?locations=lat,lon|lat,lon → JSON {results:[{elevation, location}]}. There is no formal standard name; it was deliberately modelled to look similar to the Google Maps Elevation API. It is one of a family of “elevation point-query” JSON APIs, but they are not drop-in compatible with one another.

This means KOContour can talk to the public Open Topo Data server (api.opentopodata.org) and to any self-hosted Open Topo Data instance (it is open-source and meant to be run on your own server) — or indeed any other server whose API matches Open Topo Data's format.

The “OpenTopography API” — implements custom REST endpoints (globaldem?demtype=…, usgsdem?datasetName=…) that return a raster file for a bounding box. You will need to request an API key to use this, but it is free.

The real standard for “give me a DEM raster for this bounding box” is OGC WCS (Web Coverage Service) — with its cousins WMS / WMTS for map images. Many DEM servers expose WCS (national mapping agencies, GeoServer / MapServer / THREDDS instances, and so on). OpenTopography's API plays the same role as WCS but is not WCS — it is its own thing.

When you have chosen your server, make sure you enter the API key using the padlock button in the lower right of the dialog. The grid resolution dropdown below the dataset name will be populated with suitable values (you may have to “tab off” the server name field), so select the one you want. Similarly a dataset recommendation will be selected, but you can override that if you wish. Once you are done setting up your selection parameters click Generate TSV from DEM server; a file picker lets you choose where to save the data — I recommend making a ContourMaps folder under your Pictures folder and use file type .tsv which is just tab-separated values. KOContour is registered as a handler for .tsv files so you can just double-click on them to open a map if you use that. Click the Save button and the download will begin.

You will then see a progress information popup, which you can hide by clicking the Close and keep going button (click on the main toolbar button to see it again), and you can cancel the operation if, for example, you are warned that the dataset you chose does not have elevations for the points you requested. A good choice for North America and the UK seems to be the Mapzen dataset, and the app will try to default to the best choice, but your mileage may vary. For the opentopodata.org server it is possible to display the actual progress percentage, but for opentopography.org an “indeterminate” (busy) progress bar has to be used. Once the download is complete you can close the progress box and then use the Load Data button to load the file you created.

Saving Map Service Keys or Usernames

You can register for various free map services with DEM servers, or GeoNames which, for individual, low-use, are likely more than adequate in the speed and number of daily transactions.

Once you have your account and username or key, click on the padlock button, and paste the appropriate one into the popup dialog. Click Save to securely save the key in the local storage for your app. You are now ready to download data from the map service or elevation data for individual places from GeoNames.

How the main Open Topo Data public datasets compare for resolution/quality:

• General / global default: mapzen (it effectively is ASTER / SRTM plus better data where it exists).
• Region-specific, higher res: ned10m (US), eudem25m (UK / Europe), nzdem8m (NZ).
• aster30m is a fine fallback for places mapzen / srtm don't cover well (e.g. far north), but I wouldn't pick it as the everyday choice.

The main OpenTopography datasets (chosen from the same dataset dropdown) are:

• General / global default: COP30 (full coverage including the far north).
• USA, higher res: USGS10m (10 m, auto-selected when your chosen country is the US).
• Very large regions: drop to a 90 m set (COP90 / SRTMGL3) or use a smaller area, to keep the single-call download manageable.

(The dropdown also offers ellipsoidal-height variants SRTMGL1_E / AW3D30_E and a sub-ice GEBCOSubIceTopo, which are rarely needed for contour maps.)

Create elevation data for an area

KOContour draws its contours from a regular rectangular grid of elevation readings: the contouring algorithm needs evenly-spaced points laid out in rows and columns, not a scattering of random measurements. The Create data dialog (the same button described above) builds exactly such a grid for the area you specify — a centre latitude/longitude and a horizontal extent — and, with the DEM service option, looks up the elevation of every grid point for you and saves a ready-to-load .tsv file in one step. No external website is involved.

(The dialog also has a Create GPX file option that writes just the grid of latitude/longitude points with no elevations, in case you want to fill them in with a separate elevation tool of your own. Most people will simply use the DEM-server route above, which does the elevation lookup directly.)

Alternatively, here is a link to download Maui.tsv — a tab-separated data file for Maui, ready to use. As always, do a virus scan just as you would for any file you download.

Example: Create data for Maui

Find the centre of your area in your favourite map source, e.g. Google Maps: search for Maui, right-click the chosen spot, and left-click the coordinates that pop up to copy them to the clipboard — something like 20.800841, -156.327220. Then click the Create data button to open the dialog.

Click the field labelled Paste lat,lon here and paste the coordinates; the Latitude and Longitude fields fill in and stay in sync (you can also type them individually). As a quick alternative, type a place name into the Title field and choose an entry from the drop-down of suggestions that appears — selecting one fills in the coordinates for you; use the country selector beside the Title to restrict the search to a particular country. Fill in the other fields until they all show a green border, indicating they are valid.

Select the DEM service option and choose a server — Open Topo Data (no key needed) or OpenTopography (once you have pasted in its key). Pick a dataset and a grid resolution, then click Generate TSV from DEM server and save the file as Maui.tsv in your data folder. A progress popup shows while the elevations are fetched; when it finishes, close it and use Load Data to plot your new map.

Loading the Input Data Files

Click the highlighted button, which will show a standard file picker letting you select one of the input files you created above. A contour map will be generated from the data and should look similar to the picture below.

Contour map of Maui generated from the downloaded elevation data

When you load a data file it is added to the Show Favourites list dialog, and you can double-click on entries there to load the data again. Entries are sorted with the most recently loaded at the top. Superimposed on the map you can see the zoom and pan controls, along with the height scale on the left and the distance scale in the lower right.

To zoom into a particular area, click and drag a rectangle across the map. A white selection box — matching the proportions of the map window — follows the pointer as you drag, and releasing the mouse button zooms to the selected area. Press Esc while dragging to cancel without zooming. The zoom and pan buttons in the lower-right corner give step-by-step control.

On a touchscreen you can also use two-finger gestures on the map: pinch two fingers together or spread them apart to zoom out or in — the zoom is centred on the point midway between your fingers — and drag with two fingers to pan the map, which follows your fingers and stops at the edges of the loaded data so you cannot scroll off into empty space. Pinching and panning can be done together in one gesture. A mouse wheel (or precision-touchpad pinch) also zooms.

Choosing How the Contours are Drawn

The drop-down near the top of the window selects how the loaded data is drawn. There are four modes:

• Lines — the classic contour map, each level drawn as a coloured line.
• Gradient Shade — the map is filled with a smooth colour gradient that blends from one contour level to the next.
• Block shade — each contour band is filled with a single solid colour, giving a stepped, "layer-cake" look.
• 3D — the terrain is drawn as a shaded three-dimensional relief surface that you can rotate and zoom (see The 3D Relief View below).

The colours used by every mode are set by the colour scheme, and the number of bands by the contour-levels slider, both described below.

Adjusting the Number of Contour Levels

The slider near the top of the window sets how many contour levels are drawn; the "N contour levels" label beneath it shows the current count. The levels snap to "nice" round step sizes (for example 5, 10, 50, 100 …) so the colour key stays easy to read. With the slider focused, the left and right arrow keys step down or up to the next preferred set of levels.

The 3D Relief View

Choosing 3D in the display-mode drop-down draws the data as a shaded relief surface, lit from the north-west. Any places you have added appear as little flagpoles whose flags carry the place names, and the red N compass arrow points to the projected north.

Rotate the view by dragging on it with the mouse (or one finger): dragging left/right spins the view (its compass bearing) while dragging up/down tilts it between almost straight-down and nearly edge-on.

Two vertical sliders sit beside the view:

• The Height slider on the right exaggerates or flattens the vertical scale, making subtle terrain easier to see; the flagpoles grow and shrink along with the relief.
• The Grid slider on the upper-left sets the mesh granularity — higher gives a finer, more detailed surface (slower to draw), lower a coarser, faster one.

Zoom the 3D view by pinching with two fingers, or with the mouse wheel / trackpad. The terrain and its labels zoom together.

For smooth rotation the 3D surface is drawn on your graphics card (GPU) where a suitable one is available, falling back to the processor otherwise. A small marker in the lower-left corner of the map shows which is in use (for example GPU 3D: …, or CPU only).

Contour Colour Schemes

Tap (or click) the contour-levels key in the lower-left of the map to open the Contour colour scheme chooser. Each option shows a preview strip of the colours your current contour heights would have under that scheme. The schemes are:

• Hue Ramp — HSL hue ramp, blue "sea level" then green through violet.
• Greyscale — dark for low ground through to near-white for the highest.
• Hypsometric — the classic atlas terrain tints: green lowlands through yellow and tan to brown uplands and grey/white peaks.
• Terrain + water — like hypsometric, but sea level and below are shown in blue (deeper = darker), which is handy for data that dips below zero.
• Viridis — a perceptually-uniform, colour-blind-friendly ramp (purple-blue through teal and green to yellow), where equal colour steps mean equal elevation steps.

At the top of the chooser are sliders that fine-tune the scheme they belong to — each one is enabled only while its scheme is selected:

• Hue start and Hue range — shift and widen the band of colours used by the Hue Ramp scheme.
• Shade mute — tones down (desaturates) the filled Hypsometric colours towards grey, so large shaded areas look less garish. Its setting is remembered between sessions.

The map updates live as you change the scheme, the sliders, or the switches below, so you can see the effect straight away. Reset puts everything back to how it was when you opened the chooser, Cancel discards your changes, and OK keeps them. The chosen scheme applies to every display mode, including the 3D view, and is remembered between sessions.

The chooser also has a 3D block sides section with two switches for the 3D relief view:

• Fill the data-block side walls — closes in the four vertical edges of the data so the relief looks like a solid block sitting on its lowest-elevation plane, rather than a floating sheet. The faces are shaded by the same light as the terrain.
• Mystery Bonus

  Sandy rock with dinosaur fossils — just for fun: draws those walls as a dark sandy rock face with the occasional dinosaur skeleton (a T-Rex, a long-necked sauropod, a plated stegosaurus, a horned triceratops — plus the odd bone, ammonite, fish or footprint) embedded in the strata. The fossils stay put in the rock as you rotate.
  Both switches are remembered between sessions.

Adding and Editing Places

Click the highlighted button to show the Add or Edit a Place dialog. This lets you enter a place name, description, coordinates, and elevation for a new place, and add it to the list in the Show Places list dialog. If you double-click on a place in that list it will also invoke the Add or Edit a Place dialog. If the place does not have elevation data (shown as empty or −1000000) and it is within the currently loaded map data, the elevation field will be highlighted in purple with a suggested value filled in. Click Update Place / Add Place to save, or Cancel to exit without changes.

The Place Name field is also a search box: start typing and a drop-down list of matching places appears. Use the country selector beside it to narrow the search to a particular country. Choosing a place fills in its coordinates, sets the description to Place, County, Country, and fills in the elevation automatically. Place search is powered by GeoNames.

You can also right-click (or press and hold) anywhere on the map to see a list of the nearest places. Choosing one opens the Add or Edit a Place dialog ready-filled with that place's name, description and coordinates, together with its elevation where available. The most recently chosen place is remembered, so clicking the Add or Edit a Place button afterwards re-opens the dialog pre-filled with it.

As an example, let's add Lahaina.

If you have not yet set up a free GeoNames account (and I would strongly recommend that you do) you can use Google Maps as described above to get the coordinates for Lahaina and paste them into the dialog, then add the other details If you have set up your GeoNames account, and entered the username then you can type the first few letters of the place name and a list of suggestions will pop up. Click on the one you you want, and it will populate all the fields in the dialog for you. This is the easiest way of getting the data.

With the coordinates filled in, give the location a name and a short description, and add an elevation if you know it — or leave the elevation blank and let KOContour suggest one from the loaded map data. As a shortcut you can type the place name straight into the Place Name search box and pick it from the drop-down list, which fills in the coordinates (and elevation) for you. When every field shows a valid (green) value, click Add Place to save it.

Lahaina will appear on the map and be highlighted as shown.

Try adding another place such as Paia. Leave the elevation unset and save the new place, then continue to the next section.

Showing the Places List

Click the highlighted button to show the Show Places list dialog. Places are maintained in alphabetical order. Double-clicking an entry launches the Add or Edit a Place dialog. If a place does not have elevation data and it is within the currently loaded map data, the elevation field will be highlighted in purple with a suggested value.

Try looking for Paia — you can jump to the P section by pressing the P key. Double-click on Paia; if the elevation was left as the default (−1000000 means undefined), it will suggest an elevation based on the nearest contour line and highlight it as shown — 200 feet in this case. Places visible on the currently loaded map are shown in cyan, otherwise they are shown in light gray. If you re-type in the place name it will suggest a more accurate elevation from GeoNames - 232.9 feet - if you have set up your account on that as described below.

GeoNames requires creating an account for programmatic use, but it is totally free and does NOT require a payment card, or credit-card-on-file. I would strongly recommend doing so since it lets you do automated lookups of the latitudes and longitudes of named places, or places you click on the map, and takes only a couple of minutes:

1. Register at https://www.geonames.org/login — just a username, email, and password.
2. Confirm the email they send you.
3. Enable web services — this is the easily-missed step. Log in, go to https://www.geonames.org/manageaccount, and click the link at the bottom to "enable the account for use of the free web services." Until you do this, every API call returns user account not enabled to use the free webservice, even though the account exists.
4. Set GeoHelpers.GeoNamesUserName to that username in the app.

The username is the credential — there's no separate API key or secret. You just pass &username=yourname on each request (which is why it's plain http, and why you shouldn't hardcode a username you care about into a widely-distributed app, since anyone can read it and spend your daily quota).

You can easily test your account by entering the following into the address field of your browser:

http://api.geonames.org/searchJSON?name_startsWith=<placename>&featureClass=P&maxRows=10&username=<username>

Replace <placename> and <username> with the appropriate values for your chosen place, and your account. This will return a list of place names and the data for each.

Click Update Place to save the place data and elevation, which will then appear on the map under the place name.

Finding the Elevation

To find the elevation of a point, click on the map at the desired location. A marker will appear showing the elevation along with the latitude and longitude. To remove it, click again in the centre of the crosshair.

Distances and Compass Bearing

To find the distance between two points, hold the Ctrl key and click on the map at the first location. A marker will appear. Keep holding Ctrl and click the second point. A line will be drawn between the points showing the distance and compass bearing. To remove the measurement tool, click again in the centre of either crosshair.

Showing the Favourites List

Click the highlighted button to show the Show Favourites list dialog. The list is maintained in last-access order, most recent first. Double-click an entry to load that data file. If the file no longer exists you will be asked if you would like to remove it from the list.

Toolbar Option Checkboxes

The Light Theme checkbox switches to a light background, which is sometimes better for printing. The Load at startup checkbox causes the app to automatically load the last successfully loaded data file at launch, if it still exists. Both of these settings are persisted across launches. The Show places option is not persisted.

Everything else is easy to figure out from the tooltips and prompts — have fun exploring!

Features

Download and Install

KOContour is free software.
← Back to KLO Software