If you load a GeoJSON file as a custom map in Pyramid and do not get any shapes displayed, it could be the coordinate system you are using, especially if you converted another file format to GeoJSON.

Pyramid gives us the ability to load our own custom map shapes to overlay on an empty world map. This is useful where we want to show individual regions that are not an existing MapBox layer; MapBox provide the maps used in Pyramid. For example, I want to show a map of the UK with each council or unitary authority area identified and coloured according to some measure.

MapBox doesn't have this level of detail, but with a bit of Googling I can find map files that do. For use in Pyramid I want a file encoded as GeoJSON, but it's not always possible to find one for the detail I need. Shapefiles, a standard developed by Esri but widely used with GIS software are often available, but Pyramid cannot read these. We need to convert the format to GeoJSON.

Fortunately this is a common enough task for a number of free (and paid for) conversion tools to exist. I’ve had success with https://mapshaper.org, an online tool under an MPL2.0 license.

Assuming I found a Shapefile, or other format supported by mapshaper, I can drag it onto the mapshaper landing page.

A Shapefile is actually several different files, usually zipped together and mapshaper supports the zip or individual files.

Once I’ve identified the files I need, I can click “import”. I am then shown an image of the file so I can check it’s what I thought it was going to show. All good here.

The button in the top right of the screen then allows me to export, but before I do that it’s a good idea to check the coordinate system being used. There are a lot of coordinate systems in use because basing a system on a datum point local to the area being mapped increases accuracy. But unless you’re sending in the bulldozers to make way for a motorway next to a primary school it probably doesn’t matter too much. Worse case you might be a few hundred meters out converting a local coordinate system to a standard, global system.

By default GeoJSON uses the global WGS84 coordinate system, and Pyramid likes to use this too. However GeoJSON is happy with any coordinate system and if you give it data using SR-ORG:8704 then that will be pretty good for representing positions on the surface of Mars, but much less useful for pinpointing a supermarket in Huddersfield (an English town, not anywhere near Mars).

Back to my map file. To check the coordinate system I can click on the “console” button in the top right of the screen. This opens a console box, and I can enter mapshaper commands; these are documented here.

-info

will show me useful metadata about my file.

I want to check the CRS (Coordinate Reference System), and I want the datum to be WGS84. But it’s not. OSGB36 is a datum point generated by the Ordnance Survey for mapping Great Britain in 1936. If I export this to GeoJSON, mapshaper will honour the CRS, but that won’t display in Pyramid because Pyramid uses global maps not just British maps. So before I export I need to convert from OSGB36 to WGS84, which fortunately is easy with the console and the proj(ections) command.

-proj crs=wgs84

Despite what the metdata reports, wgs should be in lower case. And we can then use -info to check the conversion.

Now I can export my file, using the “export” button in the top right hand of the screen. This pops up the export menu and I can choose GeoJSON.

This file will be of the correct format to load into Pyramid. But we can make a final check of the GeoJson file. I can use a text editor such as Notepad to look at this.

There is no CRS data shown, which is fine. GeoJSON defaults to WGS84. Also note that the “coordinates” values are all in the range -180 to +180, standard longitude and latitude descriptions. By contrast look at this GeoJSON file that loaded to Pyramid but would not display any shapes.

The CRS is shown but it is not WGS84. Actually, EPSG:27700 is another way to represent OSGB36. Also note the coordinates with numbers like 448868.30399, well outside of the -180 to +180 range. In this case I could still use mapshaper to convert this to a usable format, but I found I had to tell mapshaper what the CRS was. When I used -info the CRS showed as “unknown”. The command to explicitly state the current CRS was

-proj from=EPSG:27700 crs=wgs84

Adding GeoJSON files to Pyramid is simple. And documented here. One tip, if you are loading large files (more than a few MB) the import may appear to be doing nothing. It’s working in the background. Have patience, maybe hit refresh a few times and it will show up.