WAML Pre-Conference Workshop: OpenIndexMaps

Exercise 1: Create a polygon index map from an existing shapefile

If you have not already downloaded the data for this workshop, do so now:

Download Data

Be sure to extract the contents of the .zip file to your computer.

1. Add the data to QGIS

Let’s verify that the data is in the correct location by adding a basemap, and set our map to use the CRS of the basemap.

2. Add some style

To improve the visibility of both the index map and the basemap, let’s change the style of the index map:

3. Explore the data

Let’s explore the values in the table, to get an idea of how we might want to convert the fields into OpenIndexMaps properties.

Notice the values found in the different fields.

This example shapefile is a slightly modified extraction from the American Geogrpaphical Society Library’s (AGSL) Geodex system, which uses it’s own schema that pre-dates the OpenIndexMap schema.

Existing Fields:

Note that some of the data is the same for each sheet in the set. See the note about set- and flight-level metadata in the schema documentation.

QGIS has a processing tool called “Refactor fields” that will let us rename, delete, and manipulate the values of these fields.

4. Refactor Fields

In the processing toolbox, search for “refactor fields” and open the tool. The settings below will output a copy of the index map with just four fields: title, label, note, and downloadUrl. In this case, we are putting the size into a note so that it will display in the GBL interface.

Be sure to set all the types to string and set the Length to 255! The schema specifies no limit to the length of the string in any element, but in this case, setting a reasonably high limit only impacts the layer created in memory and not the output GeoJSON.

"before" view of Refactor Fields window

Before view

Field Mapping:

When deciding which fields to use for north, south, east, and west ensure that you look closely how the input data is formatted. Remember that negative longitudes indicate the western hemisphere and negative latitudes represent the southern hemisphere.

The source expressions can be typed in directly, but if you click on the epsilon (ε), QGIS will open an expression editor that provides a full list of available functions, along with syntax highlighting, error checking, and a preview of the output based on the first record.

Pay close attention to quotes in expressions. Double quotes (sometimes optional) indicate a field name, whereas single quotes indicate a literal text string.

* For the location field, we need to write an expression to ensure that we format our simple comma delimited string of locations as a valid GeoJSON array:

expression dialog for location field

Type this exactly or copy-paste into the expression editor.

if(length("TOWNS") > 0,concat('["',replace("TOWNS",',','","'),'"]'),NULL)

The expression above checks the length of the existing TOWNS field. If the length is greater than 0, or in other words, there are towns listed, it formats the list as a valid JSON string by adding square brackets and double quotes to the list. If the length is not greater than 0, or in other words, it is Null, then it simply keeps the field null.

"after" view of Refactor Fields window

After view. Yours may look different if you made different choices!

You should have a new layer called “Refactored” on your map. Use the identify tool or look at the attribute table to make sure the results look right. If you need to make any corrections, remove the “Refactored” layer, then go back to the “Parameters” tab of the dialog, make your changes and run it again.

5. Save as GeoJSON

Once we’re satisfied with the output, we are ready to save it as a GeoJSON file.

Now you should have an index map saved as a GeoJSON file! If you open it in a text editor, you’ll see that it starts something like this:

{
"type": "FeatureCollection",
"name": "cuba_62k_1913_gdx",
"features": [

You could also copy or drag the GeoJSON into geojsonlint.com, which will check for any parsing errors and also render the GeoJSON in a map.

Notice that only set-level metadata is the “name”, which we be whatever you named the file. It would be a good idea to provide a bit more information, which could be added manually. At this time, there are no standard properties for the index map as a whole, but that is something that OpenIndexMaps may develop in the future. Here is an example of what Cornell University does in their CUGIR portal:

{
"type": "FeatureCollection",
"name": "cugir-009099-index",
"title": "Index of 2-meter DEM, Tompkins County NY, 2008",
"websiteUrl": "https://cugir.library.cornell.edu/catalog/cugir-009099",

For the cuba example, you could make two separate index maps for the Carta Militar De La Republica De Cuba 1:62,500 set and the Military Map of Cuba 1:62,500 set.

A word of warning

Due to over-enthusastic date-detection in GDAL (the format translator software that QGIS uses under the hood), if you try to edit an existing GeoJSON file that has date strings, they might get silently mangled into a different date string format.

If you plan on making further edits to your index map, I would suggest first saving it to another format such as geopackage, edit that, then generate geojson from there.

Next: Exercise 2

This site is open source. Improve this page.