Labels

Customizing Esri's Vector Basemaps: Part 4

This is the fourth of five Story Maps looking at methods of customizing our selection of Vector Basemaps... or working with your own.

In this section I'm going to take a look at adjusting labels by working directly or indirectly with the JSON style.

I'll be using the current version of the  ArcGIS Vector Tile Style Editor  ('Vector Style Editor'). For all of these exercises I'm using the combined Light Gray Canvas layer as a starting point. It has a relatively small level of content, and the neutral palette makes it good for demonstrating changes. 

For more information, and a fuller introduction, go to  Part 1 .

Language

The 'Quick Edit' option includes a 'Language' selector. Use this to change most of the map labels to one of the 40 languages supported by ArcGIS.

Fonts

As outlined in Part 1, the fonts available are defined in ArcGIS Pro when the master vector tile package is created. Under normal circumstances this would limit you to whatever you can see in the default map layer.

However, extra fonts can be introduced by adding them to non-critical or non-visible layers, and we've taken the opportunity to include a varied selection in our basemaps, to give you some options. An itemized list of these is available in the  Reference Document  (and if you are working with the JSON Code you will need to have this list available to you), but here is a graphic representation of them:

Some of these are here for a reason: 

Avenir Next is used by Esri for its Brand, but it also happens to be a reasonable map font. It's a licensed font, but you are OK to use it in the context of these layers.

Arial Unicode offers a more complete set of diacritics and some non-roman alphabets. We use it extensively in the language-specific versions of our core maps.

All others are open source, with few restrictions on their use.

We've tried to include a good variety with this selection, but be disciplined. You don't want the font treatments to overshadow the map content! A rule-of-thumb is to limit yourself to two faces (Arial, Playfair Display, etc.), but as many fonts (Bold, Italic, etc.) as necessary.

Adjusting Fonts

Our label classification has become rather complex as we have tried to add more flexibility to our selection and sizing. When adjusting fonts, remember that multiple layers may be involved in representing one feature. The  Reference Document , as ever, is the resource if you want to understand the layer structure detail, or if you are using the JSON Code.

For this exercise I'm working with country names ('Admin0 point'). In both Canvas maps it is represented by seven items based on size, and relevance at different zoom levels. The Vector Style Editor identifies them like this:

Note that the following sequence is a graphic, and not the live application

In the Vector Style Editor, work through the nested layers to identify the ones for changing.

Highlighted left are the 7 that make up the country names.

A 'T' in the icon indicates that it is a label layer. Click on it, and the style controls open up.

A detailed breakdown of the options in the style panel can be found below.

If you prefer to use the JSON Code, search for the feature name (Admin0 point) to pick out the same layers.

Note that if you see a second font name (usually Arial Unicode), it is there to establish a substitute or fallback font. This is used if a particular character is not available in the preferred font. It's likely that you won't need to change this.

Clicking on the font name opens up a complete list of faces and fonts available. Scroll down or use the search function to find what you want. As you add new fonts to a map, the 'Style Fonts' option is a useful short cut.

Here I've changed to 'Oswald Bold', and adjusted the color and size as well to make it more prominent

Here is the completed change, across all 7 layers.

Adjusting Size

Label sizes are measured in pixels. Our maps are shown at 96 ppi on a normal screen, with 1px representing 0.75 points. We try not to go smaller than 9px (7 pt approx), but 10.5-12px (8 - 9 pt approx) is safer.

High definition screens will generate smaller labels, but their readability should be about the same.

The size window is intuitive, and, as with color and stroke width, stops can be added based on zoom level. The size will transition between stops, so you only need to include them at zoom levels where you wish to define the size specifically.

The aim is to make the transition as smooth as possible, so avoid large changes in size across adjacent zoom levels. In this case the size increases from Zoom 2 to Zoom 6 would be:

9px : 12.5px : 16px : 20px : 24px

Here is the line item in the JSON code:


Haloes

Legibility is an important aspect of any map, and this need is magnified online. Users may be prepared to look at a view for only a few seconds before moving on.

Adding a halo to a label can have a huge impact, but it can also be very destructive to the information underneath. Our basemaps use halos extensively, but you may not be aware of them.

In this example I've added some color to the larger scales of my version of the Light Gray basemap, and introduced an issue with the legibility of street names. A halo would resolve this.

So here is a typical white halo - larger than it needs to be, and the blocks of white break up the look of the map ..

But by using the background color in the halo and narrowing it, (in fact I've used a color mid-way between the background and the buildings), the labels are legible, but the map is more unified. The color does break up the flow of the streets though, and can be misleading. Some almost disappear.

In vector tile maps we have another option that improves things even more. I've lightened the halo considerably (but not used white) and added a blur to fade the halo into the background.

Here are the halo controls in the Vector Style Editor.

In the JSON Code Editor, the line items are added to the 'paint' section as "text-halo-width", "text-halo-color"... and "text-halo-blur"

When I'm working with halos I always try to build them as narrowly as possible, and I do whatever I can to make them unnoticeable.


Adjusting Individual Labels

It’s now possible to isolate and hide/customize individual labels using the JSON code.

In this example I want to modify the 'France' label.  To do this I'll remove it from the existing layer, then duplicate that layer and adjust the code to bring it back in on its own. Once it is isolated I can make custom modifications

In the VTSE, click on the label you want to customize (In this case 'France'). This will open-up the label tools and select that layer.

With the layer selected, open the ‘Edit JSON’ option. It will take you to the relevant section of code.  Find:

"filter": ["==","_label_class",1],

Note: The class number may vary depending on the layer you choose.

Change this to:

"filter": ["all", ["==", "_label_class", 1], ["!=","_name","France",]]’

“!=” is the instruction to remove the selected label from the layer.

“_name” is the text field. This may vary, and can be identified on the line "text-field": "{_____}"

“France” is the label I want to isolate

Update the map, and the ‘France’ label disappears.

Note that not all label layers will have a “filter” line (if the layer ID includes ‘/default’ it probably does not).

If this is the case, add this line below “source layer”:

"filter": ["!=","text field", "target label "],

Go back to the ‘edit layer styles’ option.

With the layer selected  go to ‘Actions’ at the top and duplicate the layer (The new layer has '/1' added to the name).

Alternatively you can copy/paste the relevant section of code for the same effect.

With the new layer selected, go back to the code.

In the second part, change ‘!=’ to “==”

The “==” is the instruction to use only your chosen label.

I’ve also taken this opportunity to change the name of the layer, adding 'France only', but this is not essential.

The ‘France’ label is now isolated. I’ve enlarged it a bit, and changed the color


Adding Information

It's also possible to add some extra text to labels, but you need to be aware of the implications:

Here I've made the counties the subject of the Light Gray Canvas Map, but I want to enhance it more by adding the word 'County'.

I've found the relevant layers and opened the JSON editor:

'text field' identifies the data source for the label ("_name"). By adding 'County' immediately after, that will be added as a suffix to the labels...

... but be careful! The suffix will be added to ALL third order (Admin 2) labels, regardless of the context.

If the map is to be used worldwide it could be misleading, and potentially insulting.

In France 'Yvelines' and 'Hauts-de-Seine are 'Départements'


Other Settings

There are various other commands that can be adjusted or added to 'tweak' the look of the label. Here is an aggregated list of the ones typically used in our basemaps, including some not discussed above:


More on Customizing Esri's Vector Basemaps

The final part of this in-depth look is:

The earlier parts of this Story Map sequence are:

The Vector Tile Style Editor can be found  here .

Andy Skinner, ArcGIS Living Atlas Team, 2021