Basemap Basics

Customizing Esri's Vector Basemaps: Part 1

Esri Basemaps

Esri has made available a set of basemaps to support your work for a number of years now. But have you ever had that moment where you thought

This basemap would work really well, if only ...?

With Esri's Vector Basemaps and our editing apps, you can do something about that!

The Living Atlas includes vector versions of most of our traditional basemaps, and we are adding more all of the time, from multi-layered functional maps like 'Human Geography', to heavily stylized versions like 'Colored Pencil' , 'Nova', and 'Watercolour'. 

You are now in a position to make changes to them, and here I'm going to go over some of the basic information you need to get started.


What is a Basemap?

A basemap can be many things, but in this context it is a map that is designed to provide a foundation for the additional information in one or more online maps.

It's going to supply the raw information you need to provide a context for your map. Ideally it will do this in a way that doesn't compete with or detract from it.

... and what is a Vector Basemap?

This is a layer (or a number of layers) built from a Vector Tile Package. As with cached raster tiles the information is broken up into easily-rendered pieces, but now the vector data is retained.

It is built in PBF format, and it is rendered client-side (the final rendering is applied after the service is published). This is great for us because we only build the vector tile service once, and derive all of our basemaps from that (We have services for Esri Web Mercator, Esri GCS, and Open Street Map). Production time is a fraction of that for our old raster-cached services, as is its size, and that means that we can update the maps on a more frequent basis.

It's great for you, because the basemaps are more recent, more efficient, high resolution when necessary, and, most importantly for this exercise, editable! Any versions you create will be updated whenever we update our vector tile service.

Where are they?

You can find our suite of Vector Basemaps in two locations:

The Core Set 

Most, but not all, are available in the 'Basemaps' drop-down menu, unless your administrator has created a custom set. Regardless, you can find a fuller set  here , or access them through the  Living Atlas 

This set includes most of our traditional basemaps, available in Web Mercator and GCS projections and in multiple languages. An increasing number of additions, cover the gamut from functional to stylized. We also have a set based on Open Street Map. All are maintained and updated on a regular basis. As they stand you should be able to find one that is very close to your requirements for a basemap. For this exercise they are also good candidates for customization.

Creative Basemaps.

You can find these  here .

These are layers that we've created to demonstrate some of the capabilities of Vector Basemaps. As with the core set, they are available for you to customize. However, they are not maintained to the same level as our core (although all are in pretty good condition, and updated with the tile service). Some of the capabilities we demonstrate in them require a different level of work. Occasionally these maps will migrate to the core set.

A graphic showing five examples from the Creative Basemaps folder

Both sets include Layers (the original vector tile layers that we created), and Web Maps to demonstrate them. Either can be used to access the maps, but adjustments are made to the Layers.

How do they Work?

Our maps originated as a Vector Tile Package, built in and generated by ArcGIS Pro, and published with a generic style.

The Vector Tile Package establishes the maximum level of content available, and a defined scale range for each layer of information. Different basemaps do not necessarily use all of this content, or exploit the full scale range.

A vector tile package contains the vector tiles, and various formatting documents. Of interest to us is the Resources Folder. Separate folders can be generated for each of our basemaps.

It includes:

Style – A root.json file that establishes the symbolization of the map detail. This is editable, and it is the key to the discussion here. We can make changes to this code to affect color, line weight, label size/font, and scale range ... either directly, or through an editing app.

A graphic showing the contents of the Resources folder

Fonts – Any font that is built into the ArcGIS Pro map. Only fonts that are included in the package are available for use.

Sprites – Raster images created for special effects, such as textured patterns and point symbols.

The sprites for the Light Gray Canvas Layer are shown on the left. They include road marker backgrounds, and a hatch pattern for intermittent drainage. 

What do I use?

This is a link to our  Vector Basemaps Reference Document . Download this PDF and use it as your guide to understanding how our maps are structured. As the maps themselves have become more versatile (and we are trying to improve them all the time), our layer structure has become more complex. You can use this document to find your way through. It may be a little confusing at first, but the more you work with it, the more it will make sense. If you are using one of our 'Open Street Map' bases you can use  this  for reference. The structure of OSM is complicated, so this page will be important.

Don't feel you have to learn the content before you start work though (They are 'reference' documents!). 

Most if not all of your editing can be handled in one App:

The  ArcGIS Vector Tile Style Editor  ('Vector Style Editor') is intuitive, and leads you through most of the changes you can make to the style.

The above link will take you straight to it. You can also find it in the ArcGIS Online App gallery:

Or, if you already have a vector tile layer available to you, you can activate it directly via the Details page:

Opening the Vector Style Editor gives you access to your content. Hitting 'New Style' gives you access to our core map styles. You can use any of these as a starting point for your map.

The post-log in screen of the Vector Style Editor

Not surprisingly we don't let you work on our master copies of these maps, so you need to establish your own version. For this you will need to sign-in to your organizational account. Once you make your choice, 'Save as' will allow you to save it to your preferred location.

Tip: For your sake (but mostly for the rest of us!), change the name of your copy to something that makes sense to you rather than leaving the default. I suspect that we have all spent more time than we can really spare sifting through the multiple versions of 'Light Gray Canvas' (as well as our other basemaps) created as 'quick' copies by other users.

While you are doing that, it might be a good time to add descriptions, tags etc. to the Details page.

Choosing the Basemap to work with

Ideally, you should choose the basemap that is closest in content to what you require.

The 'Canvas' and 'Human Geography' maps are probably the easiest to work from if you want to develop a unique color palette - There will be fewer conflicts. However, the level of detail is stripped down and may not be enough for you.

The Street and Topographic maps are at the other extreme - Lots of content, particularly at larger scales, but more symbolization to work around.

The stylized maps such as 'Colored Pencil' and 'Nova' may be the most difficult to change because of there distinctive symbology, and unless you are very sure of what you want to do, you should restrict yourself to small adjustments.

The ArcGIS Vector Tile Style Editor

Here is the opening screen for the current version:

There are 4 preview screens for you to see how your changes affect different scales. The additions can be switched off if preferred, and the background of the preview map can be changed.

The 'Quick Edit' option (shown above), allows you to make changes by broad groups of information. It can be a very effective way of changing a map quickly, but remember to check the results through all layers, and be prepared to 'tweak it'. It includes a random color generator, which doesn't return a finished product, but is great for inspiration! 

The 'Edit by color' option allows you to select all items with a specific color value and make a universal color change.

The 'Edit icons and patterns' option is explained in detail in  part 5  of this sequence.

The 'Layers' option allows you to drill down into the layers of information on the map and change each individually, or by category. This is where some really detailed work can be done.

The 'Edit json' option allows you to get into the code. It is particularly useful if you want to add features from the Vector Tile Package that are not included in this style (See  part 3  of this sequence).

Understanding the json

If you are not interested in this you can move on now to the second section:  'Color' 

The 'Edit json' option in the Vector Style Editor allows you to get into the code. It is particularly useful if you want to add features from the Vector Tile Package that are not included in this style.

This is a small section of the code for the Light Gray Canvas basemap.

For this map, and in this format, there are around 8,500 lines in total, so keep that reference document nearby if you plan to work directly with it!

Each item, or section of code, represents one layer of information in the final basemap. 

It is organized in drawing order. The first layer in the code is the first to draw, and therefore at the bottom of the map hierarchy.

Here are a couple of sections of the code relating to water polygons.

"minzoom" and "maxzoom" control the scale range at which the feature is visible, based on zoom level.

"layout" controls the way in which the items in the layer interact, including font and label settings. Because this water area is a simple fill, it is not in use here.

"paint" controls the look of the feature - colors (including labels), and line widths.

Adding new information layers is as simple as adding a new section of code, and this is where the Reference Document comes in

Only layers that were built into the original Vector Tile Package from the Pro document can be added*.

Some maps, such as Street and Topographic, use most of the information available, so there is not much to work with.

Others, like the Canvas maps, use only a small subset of this information, so there is more that can be added.

(For more on this go to the third story map in this sequence, dealing with  Lines ).

  • Note that our Open Street Map ('OSM') basemaps are built using a different vector tile package to our 'Esri' basemaps. Layers cannot be transferred between the two packages

Troubleshooting

JSON code can be unforgiving. It needs to be written very precisely or the rendering may fail, and tracking down, for example, a missing or superfluous comma, can be frustrating.

The code option in the Vector Style Editor does a very good job at finding problems (it won't let you update if the code is compromised), but you may need to do some detective work to figure out what the problem is. Apps like ' JSON Lint ' can be lifesavers. Copy your code in, run 'Validate', and it will seek out and flag most issues.


More on Customizing Esri's Vector Basemaps

In the following story maps I will look at how to make adjustments to the style.

The Vector Tile Style Editor can be found  here .

Andy Skinner, ArcGIS Living Atlas Team, 2021

The post-log in screen of the Vector Style Editor