Page MenuHomePhabricator

Investigation: update Maki icons
Closed, ResolvedPublic2 Estimated Story Points

Description

Background

Updating the limited amount of markers available for maps, and Kartographer in particular, was voiced as a wish in our initial interviews.

According to T145475: Update to latest maki updating the icons for Kartographer requires significant effort. Some icons currently also appear broken because of this T141304: Only a part of MAKI symbols is available (previously map icon "castle" broken).

Questions to answer:

  • Have the changes to the maps infrastructure T280767: Maps 2.0 roll-out plan made this easier?
    • No.
  • What is required to update the markers?
    • Coupling between maki and makizushi was only to pull the rendered icons. This was easy to redo with a newer version.
  • How much effort is this?
    • Low.
  • Is it possible to make an incremental improvement that is less effort?
    • Yes, adding the icons directly.

Code to review:

Event Timeline

thiemowmde set the point value for this task to 5.Jan 26 2022, 2:22 PM

First, I'm going to look at the possibility of upgrading maki within makizushi, which isn't the best long-term solution but at least would give us the new icons.

So, we can just swap out the icons. I've written a script to render the new SVG down to the expected formats and will upload to makizushi.

awight updated the task description. (Show Details)
awight set Final Story Points to 2.

Change 759536 had a related patch set uploaded (by Awight; author: Awight):

[mediawiki/services/kartotherian@master] [WIP] Upgrade to new maki icons

https://gerrit.wikimedia.org/r/759536

awight removed awight as the assignee of this task.Feb 3 2022, 4:49 PM
awight updated the task description. (Show Details)

So, we can just swap out the icons. I've written a script to render the new SVG down to the expected formats and will upload to makizushi.

Was this deployed too early? New icons now appear in dynamic view. These icons however don't quite fit in marker base, and also markers on static snapshot are different, some of which missing in dynamic view.

From https://www.mediawiki.org/wiki/Help:Extension:Kartographer/Icons:

Dynamic view:
maki20220214dynamic.png (429×453 px, 72 KB)
Static snapshot:
maki20220214static.png (407×450 px, 77 KB)

Was this deployed too early? New icons now appear in dynamic view.

Thanks for the report! It does look like it was deployed too early, but I don't understand how this happened. So far, we've bumped an npm package @kartotherian/makizushi from 3.0.1 to 3.0.2, which will include the new icons, but this shouldn't have been pulled into any of the server components yet. I'm especially confused by the missing icons and new images, because these appeared in a new version and should only be missing with old maki.

Icons not fitting in the marker / having centering issues seems like an important thing to fix too! Should be possible to fix by adjusting the rendering scale and possible moving the center point. I don't know why the center would have moved, we need to look at the raster images.

thiemowmde triaged this task as Unbreak Now! priority.

It does look like it was deployed too early, but I don't understand how this happened.

I failed to lock the makizushi version to prevent upgrading, so this happened inadvertently during a deployment last week.

I'm especially confused by the missing icons and new images, because these appeared in a new version and should only be missing with old maki.

We discovered that the new icon set has some renames (e.g. "toilets" -> "toilet") and deprecations (e.g. "american-football"). We're working on a way to alias old names so they continue to work.

I hand-crafted a list of aliases to map icons that existed in maki 0.5.0 but not in maki 7.0.0 any more. Some are simple renames. Some got removed and are now represented by a more generic icon.

america-football,american-football
camera,attraction
chemist,pharmacy
disability,wheelchair
emergency-telephone,emergency-phone
industrial,industry
land-use,landuse
london-underground,rail
minefield,danger
mobilephone,mobile-phone
oil-well,industry
park2,park
polling-place,post
rail-above,rail
rail-underground,rail
toilets,toilet

Notably:

  • "chemist" is heavily ambiguous. Could be a science lab on a campus. Could be an industrial site. Could be an alternative for a pharmacy.
  • There are many possible replacements for "minefield", e.g. "barrier" or "caution". "danger" felt most appropriate.
  • "london-underground", "rail-above" and "rail-underground" become "rail". I couldn't find a better alternative.
  • "polling-place" was a checkmark. I couldn't find anything like this and made it "post", a brief case.
  • "oil-well" is gone and became the more generic "industry".
  • Everything else are straight 1:1 mappings, even if some of the names sound different. "camera" and "attraction" are both a camera. "disability" and "wheelchair" are both a wheelchair. "park2" and "park" are both a tree.

I fine-tuned the command line to produce .png files that look as close as possible to how the rendered .png files looked like in the original version 0.5.0.

inkscape -w 23 --export-area=-2:-2:16:16 -o …-24.png icons/….svg
inkscape -w 17 --export-area=-2:-2:16:16 -o …-18.png icons/….svg
inkscape -w 11 --export-area=-2:-2:16:16 -o …-12.png icons/….svg

Yes, the size is actually 1 pixel off.

@MSantos IMHO we should revert the makizushi bump and lock to 3.0.1 until the upgrade issues are resolved. Alternatively, if you want to try a fix for just the missing icons, here's a PR: https://github.com/kartotherian/makizushi/pull/3

Change 762443 had a related patch set uploaded (by Awight; author: Awight):

[mediawiki/services/kartotherian@master] Pin to makizushi with older icons

https://gerrit.wikimedia.org/r/762443

Change 762443 merged by jenkins-bot:

[mediawiki/services/kartotherian@master] Pin to makizushi with older icons

https://gerrit.wikimedia.org/r/762443

Successfully rolled back for now!

thiemowmde lowered the priority of this task from Unbreak Now! to Needs Triage.Feb 15 2022, 8:16 AM

After some more fine-tuning, the icons fit nicely:

Large

image.png (426×454 px, 106 KB)

Medium

image.png (419×462 px, 96 KB)

Small

image.png (428×453 px, 78 KB)

awight changed Final Story Points from 2 to 5.

Getting there!

  • The large icons look like they are all shifted half a pixel to the right. It's probably not possible to fix this.
  • Can we shift the medium icons an extra pixel down?
  • The large icons look like they are all shifted half a pixel to the right. It's probably not possible to fix this.

It might be possible to change size of the large icons by 1 pixel, I'll see what can be done.

  • Can we shift the medium icons an extra pixel down?

Here's what it looks like. I personally prefer having the icon center concentric with the circle constructing the pin's body, but I can see there's also some benefit in making the centers of mass concentric instead. Maybe we get a design opinion as well? @ECohen_WMDE

Medium icons shifted one more pixel down:

image.png (435×453 px, 96 KB)

This is not an authoratitive source, but it seems that pin's circle head and the icon are always concentric on this doc page: https://docs.mapbox.com/help/getting-started/add-markers/#marker-images

awight moved this task from Doing to Tech Review on the WMDE-TechWish-Sprint-2022-02-02 board.

I personally prefer having the icon center concentric with the circle constructing the pin's body […]

That's why I asked. Quite a lot of the icons don't look like they are centered in the middle of the circular part (notably e.g. in the squares and most of the trains). The new version is way better.

Just in case, I mention that alphanumeric icons at the bottom are notably uncentered on last example images, but looked fine before size adjustments were applied.

I'm having some trouble figuring out the best way to review this from a design perspective. Is there somewhere that I can look other than these screenshots? What I would like to take a look at:

  • Decisions of which new icons are replacing which current icons (especially when a choice has been made between a few different options and when multiple icons have been merged into one new icon). In the merging cases, is it possible to keep any of the old icons if that's preferred? I.e. can we mix and match?
  • The current screenshots seem to show the same number of icons - I thought we were adding to the overall amount, not just updating existing icons. What new icons have been added?

Comments I already have:

  • As mentioned in story time, the letters and numbers in the bottom tow rows are significantly off center. @awight You mentioned that this is probably a separate problem and can be fixed. I also noticed that these have a black stroke outline that the other icons don't have. I would remove that here as well.
  • For both medium and large, the icons should be smaller in relation to the marker. This will also help them feel more centered. At the moment it's a bit cramped, especially in the large size.
  • The most recent layout in T300040#7714041 seems to be well centered. I think with the sizing adjustment, this will look pretty balanced but would like to check after.

I'm also curious - what's the difference between what we are doing now and the long-term solution you reference here:

First, I'm going to look at the possibility of upgrading maki within makizushi, which isn't the best long-term solution but at least would give us the new icons

A couple follow-ups:

Could the current version be deployed to beta? https://en.wikipedia.beta.wmflabs.org/wiki/User:Elisha_Cohen_(WMDE)/maki_test I created a test page there (planning to update so it has three maps, each with all icons and one map for each size)

Also how much is the current padding? https://labs.mapbox.com/maki-icons/editor/ When changing the padding here, I think it's looking good at 12px padding but I'm not sure given our marker size how small that would make the icons in our situation.

Sorry last comment:

Decisions of which new icons are replacing which current icons (especially when a choice has been made between a few different options and when multiple icons have been merged into one new icon). In the merging cases, is it possible to keep any of the old icons if that's preferred? I.e. can we mix and match?

This request is not just for me to review, but I think when this gets deployed we need to be able to very clearly communicate this for people who work on maps so they can navigate the changes. Most helpful would probably be a before and after table of some kind. @JStrodt_WMDE @Timur_Vorkul_WMDE Tagging you as I think we'll need to discuss this. Also wondering if this will need an announcement or if we can simply clearly outline the new state on the documentation page: https://www.mediawiki.org/wiki/Help:Extension:Kartographer/Icons

The best way to compare old vs. new icons is to open these two in new tabs and flip back and forth: maki20220214static.png (407×450 px, 77 KB) image.png (419×462 px, 96 KB)

Decisions of which new icons are replacing which current icons […]

I updated my comment T300040#7707095 to document all these decisions.

is it possible to keep any of the old icons […]

It's certainly possible, just a little complicated, fragile and generally not easy to maintain, and with possibly unwanted consequences. Most notably: When we really update to maki 7.0.0, what to do with the old icons then? Do we need to keep them as custom additions forever?

What new icons have been added?

Icons that didn't exist in maki 0.5.0, but do in 7.0.0: american-football, amusement-park, aquarium, arrow, attraction, bank-JP, barrier, bbq, beach, bicycle-share, blood-bank, bowling-alley, bridge, building-alt1, car-rental, car-repair, casino, castle-JP, castle, caution, cemetery-JP, charging-station, college-JP, communications-tower, confectionery, construction, convenience, defibrillator, diamond, doctor, drinking-water, elevator, emergency-phone, entrance-alt1, fence, ferry-JP, fire-station-JP, fitness-centre, florist, furniture, gaming, garden-centre, globe, hardware, highway-rest-area, home, horse-riding, hospital-JP, hot-spring, industry, information, jewelry-store, karaoke, landmark-JP, landmark, landuse, lighthouse-JP, mobile-phone, monument-JP, mountain, natural, observation-tower, optician, paint, park-alt1, picnic-site, police-JP, post-JP, racetrack-boat, racetrack-cycling, racetrack-horse, racetrack, ranger-station, recycling, religious-buddhist, religious-shinto, residential-community, restaurant-bbq, restaurant-noodle, restaurant-pizza, restaurant-seafood, restaurant-sushi, road-accident, school-JP, shelter, shoe, skateboard, slipway, snowmobile, stadium, table-tennis, teahouse, toilet, veterinary, viewpoint, volcano, volleyball, watch, waterfall, watermill, wheelchair, windmill. Note I didn't remove the renamed icons from T300040#7707095 as these are still "new" as in "do have a new name".

[…] these have a black stroke outline that the other icons don't have. I would remove that here as well.

This might not be possibly without manually editing the source .svg files. I suggest to make this a separate task and possibly let the community change this, if they want to.

what's the difference between what we are doing now and the long-term solution […]

What we do now is effectively a backport. We copy files from maki 7.0.0 to 0.5.0.

Replying to this thread,

what's the difference between what we are doing now and the long-term solution […]

What we do now is effectively a backport. We copy files from maki 7.0.0 to 0.5.0.

This is a proper upgrade, I can explain: when I wrote the point above, I thought that we were using some kind of node integration as well as the maki icons. Since then, I learned that we *only* use the icons so upgrading these is exactly what we want in the long-term.

The technical implementation is not a backport, so I'll quickly outline that as well: in maki-0.5.0, the library included SVG sources, and rendered PNG files. We relied directly on these rendered PNGs. In maki-7.x, the raster files are gone and there is only the SVG source. I ported the render script from maki-0.5.0 into our integration library makizushi, and use it to render maki-7.x PNGs to the makizushi repo.

thiemowmde changed the point value for this task from 5 to 2.
thiemowmde removed Final Story Points.

In today's story time we asked if it is possible to see how often an icon is used. I did a quick search on enwiki.

  • There are about 20 or so templates that somehow customize the icon.
  • Templates with a |marker_symbol= parameter are never used, it seems.
  • I can find about 1000 usages of |marker= parameters with one of the deprecated icon names.
    • Almost all of these are rail-above and rail-underground, which is highly relevant because these icons are gone.
    • The remaining few are industrial and camera, which is not a problem.
  • There are about 10 places that hard-code one of the deprecated icon names, without using a template.
    • Most of these are single-use and should not be relevant.
    • There are a few london-underground in articles and templates, but all super rarely used. 8 times in total.

I did a few similar searches on enwikivoyage but couldn't find anything relevant. Only one or two camera or toilets icons, which are not a problem. dewikivoyage apparently has a template with a differently named |symbol= parameter, but this is not used with problematic icon names.

Regarding the alphanum marker offsets, I found the script responsible for building the images: https://github.com/kartotherian/makizushi/blob/master/markers-src/alphanum/build-retina.sh , and also discovered that the offsets are fine when running locally so we'll have to experiment what caused this in production.

Intense detail—the alphanum markers are picked out of this document, so any changes will require that we edit the file: https://github.com/kartotherian/makizushi/blob/master/markers-src/alphanum/alphanum.svg

I updated my comment T300040#7707095 to document all these decisions.

Thanks @thiemowmde! Does it mean that chemist icons are at the moment replaced with pharmacy? I agree it's not really a good fit; I wonder if it's better to replace these with an empty marker than something that could really be communicating the wrong information. I think for polling-place it's also a bit odd but wouldn't feel totally wrong in a voting context. The minefield and oil-well replacements work well.

I think it makes sense to change our approach for the rail icons (esp in relation to the frequent usage you found). I think rail-undergound, rail-metro and london-underground are all more related to rail-metro. Then if only rail-above becomes rail, maps which use both the above and underground icons will still show some distinction between the two.

Depracations and replacements.png (416×303 px, 15 KB)

I think if we go forward with this plan then it wouldn't be necessary to keep the old ones around. I tried to do some quick searches on wikivoyage to see if they have significantly different icon usage but it seems like their {mapframe} templates don't have a parameter for icons and they primarily use the automatic numbering system.

Screen Shot 2022-02-25 at 14.55.36.png (1×1 px, 821 KB)

In my investigations I noticed that the map itself uses the old maki icons. Is this something we could also update to match? Or is that coming from the "OSM Bright for Mapbox Studio" tiles?

Intense detail—the alphanum markers are picked out of this document, so any changes will require that we edit the file: https://github.com/kartotherian/makizushi/blob/master/markers-src/alphanum/alphanum.svg

Wow! Interesting approach. Does that mean that if we added higher numbers to this file, the numbering could go past 99? It doesn't seem like to much effort for me to make a new svg as long as I understand the constraints of how it's being used to generate markers.

I noticed that the map itself uses the old maki icons. […]

This is the tiles renderer. It would need a separate update. I don't know how complicated this this, but I suspect the costs are rather high.

Does that mean that if we added higher numbers to this file, the numbering could go past 99?

Certainly possibly, but not necessarily trivial. I had a look at the render script for the letters and numbers and the .svg source. What's apparently needed is a group <g id="100-12">, <g id="100-18">, and <g id="100-24"> that shows the number 100 in the 3 sizes, and so on for all other numbers.

Do we know how often this would be used, and if it even makes sense to bombard possibly slow mobile devices with up to a thousand markers?

But let's better continue discussing this in T141335: Add maps support for marks with 3 digits.

Does it mean that chemist icons are at the moment replaced with pharmacy? I agree it's not really a good fit […]

Sorry, my analysis was probably confusing. I'm 99% sure the chemist icon is meant to represent a pharmacy in the Wikimedia context we care about. But yea, mapping it to an empty marker is a good idea. This effectively acts as a "please replace with a less ambiguous icon" call to action, and we avoid having to make a decision that might turn out to be wrong.

The refined rail replacements look great! 👍

Glad the icon changes make sense to you. I would go forward with that plan then. I think this ticket is ready to move out of the UX/PM review column. That means that from my perspective all that needs to change still is:

  • Make the icon adjustments (rail and pharmacy as outlined in T300040#7737994)
  • Make both the M/L icon sizes a bit smaller, increasing the padding around them

I'd like to take another look at screenshots after that's done since it's hard to be exact with the sizing without knowing the current size.


This is the tiles renderer. It would need a separate update. I don't know how complicated this this, but I suspect the costs are rather high.

Ok makes sense. This doesn't seem particularly needed to me; I don't think most people would notice. Just wanted to check in case there was a way that the update could easily affect both situations.

Do we know how often this would be used, and if it even makes sense to bombard possibly slow mobile devices with up to a thousand markers?

Good point. I think this is primarily a problem reported by Wikivoyage users, but haven't done much research into it. Just wanted to see if it was more or less straightforward now that we know where it's coming from. Seems like this is a separate situation and should be a separate decision if we move forward investigating it.