Adding a change to "OSM Carto" (the "standard" map style)

Posted by SomeoneElse on 29 December 2017 in English (English). Last updated on 31 January 2018.

There’s a discussion over on talk about contributions to OSM’s Standard map style. This diary entry explains what I did in order for a change to fix a problem with bus guideways that was visible in that style. It’s provided here so that hopefully it can help more people that want to (but don’t necessarily know how to) to contribute.

The first thing I did was log an issue for the problem that needed to be fixed. As well as describing the problem that also outlined the fix (actually I referenced some code in a different map style where I’d already fixed the problem). The initial discussion on the issue was helpful in that other people said that yes, they thought that it was a problem too.

However, describing the problem is only part of the way towards actually fixing it. In order to do that, I started by reading the “contributing” guidelines and the links from there.

I already had a github account. I forked OSM Carto into my area to create this. Within there, I created a new branch “guideways_low_zoom” (since deleted) just by typing the name in into the github UI.

I already had a virtual machine running Ubuntu 16.04.3 LTS (server) with all the pre-requisites in place. I’d set it up as per the switch2osm guide, but mainly use it for developing a different map style based on an older version of OSM Carto. Another option is to follow the recommendation in the OSM Carto repository and use Docker.

I then had to “git clone” my forked repository to set it up on that machine, and I then did:

git fetch --all
git checkout --track origin/guideways_low_zoom

to get the correct branch there.

In order to actually get the vanilla copy of OSM Carto working, I had to follow the instructions in the “Shapefile download” section of the switch2osm instructions (essentially running “scripts/”).

I then created a shell script to load a small section of data, similar to this script which I use for my own map style, but with slightly different osm2pgql parameters as specified both in the “switch2osm” guide and also OSM Carto’s “install” guide.

The next thing to do was the actual code change. 2 files were affected, as can be seen here. The “project.mml” file decides what data is sent through to each layer and the “roads.mss” file contains the layer that we’re interested in (“guideways”).

There’s one change to “project.mml” - reduce the minimum zoom that’s sent through to the “guideways” layer from 13 to 11.

There are two changes to “roads.mss”. The existing code just contained “[zoom >= 13]”, so I added a new section for “[zoom >= 11][zoom < 13]” based on the equivalent zoom railways code.

I also changed the colour slightly from “#6666ff;” to “#6699ff;”, and used the much maligned w3schools to “nudge” the colour in the direction that I wanted to go. The reason for the colour change was to make the bus guideway blue at zoom 13 less “in your face” at that zoom level; it previously dominated the view of that area. Colours need to be varied with line width to balance the overall visual impact.

In order to test the change locally I used a variant of a script that I already had, changed just to get the latest version of the OSM Carto style, reload it, restart renderd and apache2 and remove previously rendered map tiles. To bypass the browser cache of tiles I used “shift reload” to fetch tiles from the server.

I had to tweak both the line width at the new lower zooms and also the colour until I was happy with both. Once that was done I checked my changes into my repository (“git checkin” with a sensible description and then “git push”) and created a pull request via “New pull request” in the github UI. This created this pull reqest.

What I should have done next was upload examples of the new rendering in the discussion of the new pull request. I’d actually already added them to the original issue instead.

I then answered a couple of questions about the change. On the original issue, I tried to explain why treating bus guideways as trams was not a good idea (they’re similar forms of transport but used very differently in OSM). Also on the pull request I explained why the new guideway rendering should be handled by “[zoom >= 11][zoom < 13]” rather than just “[zoom >= 11]”. The inclusion of that code was actually accidental (it had come from the railways low zoom section) but a check of the resultant mapnik.xml showed that it was smaller with “[zoom >= 11][zoom < 13]” so I kept that version.

The code was then merged within a few days and I deleted the local branch that I’d created and did a “git checkout master” to switch to the master branch again.

In order to keep my copy of OSM Carto up to date with changes that were made subsequently, I needed to do this:

git remote add upstream
git fetch upstream
git checkout master
git rebase upstream/master
git push -f origin master

In github it now says “This branch is even with gravitystorm:master.”, so the whole process can now be repeated for the next change.


I’ve just noticed that this page exists - those tutorials are really useful so if you’ve read this far I’d definitely read that too.

Login to leave a comment