The Basics
Customizing Esri's Vector Basemaps: Part 1
Please Note:
An updated version of this Story can be found here
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 ...'?
Now , with Esri's Vector Basemaps and our editing apps, you can do something about that!
The Esri Living Atlas Content Team has added 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.
We have two editing apps available for you now. One aims to simplify the process of redesigning the basemap, and can be accessed directly from your map layer in ArcGIS Online. The other is opened separately, and gives you access to the JSON code for more sophisticated adjustments.
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 tiles the information is broken up into easily-rendered pieces, but 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 core service once, and derive all of our basemaps from that. Production time is a fraction of that for our traditional 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!
Where are they?
You can find our suite of Vector Basemaps in two locations:
Here you will find our Core Set (illustrated above). You can also 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, and an increasing number of additions, covering the gamut from functional to stylized. Some of them are available from the drop-down menu in your 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.
And here you will find our Sample Basemaps. 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 some of the capabilities we demonstrate in them require a different level of work.
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.
Tip: If you are adding a core vector basemap layer to an existing map without using the drop-down menu, the easiest way is through the Living Atlas. Use the 'Add' button, and 'Browse Living Atlas Layers'. In the 'Filter' option, choose the 'Basemaps' category, and 'Vector Tiles'. Set the 'Item Type' to 'Tile Layers', and the 'Tag' to 'Esri'. This will focus your search on the latest versions of our vector basemaps. If you know which map you plan to use, you can enter it directly into 'Search' ..
If you are looking for one of our sample basemaps, search for 'sample basemap' on ArcGIS Online.
How do they work?
The Vector Tile Package
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. However, different basemaps do not necessarily use all of this content, or exploit the full scale range.
Separate style documents are built for each of our basemaps in JSON code.
A vector tile package contains the vector tiles, and various formatting documents.
Of interest to us is the Resources Folder, which includes:
Fonts – Any font that is built into the ArcGIS Pro map.
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.
Styles – 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.
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, and 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.
Don't feel you have to learn it before you start work though (It's a 'reference' document!).
We provide two editing apps to help you on your way.
The ArcGIS Vector Tile Style Editor ('Vector Style Editor') is available when you use the 'change style' option in your basemap tile layer (It can be accessed outside of ArcGIS online here). It is an intuitive app that leads you through most of the changes you can make to the style.
The JSON Code Editor has to be opened separately, but it will help you to navigate to the layer you want to work with. It pairs the JSON style with a preview map as an easy way for you to work directly with the code and see the results.
For most tasks the first option will make life much easier for you.
However, if you are confident in your ability to manipulate code, the JSON style file gives you access to some more sophisticated options, and is a requirement if you want to add data layers to the style.
(For more information on adding data, go to the third story map in this sequence, dealing with Lines).
I'm a Cartographer of 40+ years standing, and initially I was resistant to the idea of having to work with JSON code. However, although I'm by no means an expert, I got comfortable with this environment very quickly. The basic information is much the same as it has always been. It's just approached and organized differently.
Getting Started
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. This is the basic way of setting-up your own version:
Setting up your own basemap
The Vector Style Editor helps you with the process. If you haven't created a copy layer already in ArcGIS Online you are forced to save one when you click on the 'change style' button.
Opening the Vector Style Editor separately gives you one-touch access to all of our core map styles, and to your own content. 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.
If you want to control the process yourself, or if you plan to work in the JSON Code Editor, the following is the basic way of setting-up a working layer:
Find the basemap you want to start from, and add it to a map or open it. I'm going to use the combined Light Gray Canvas layer to demonstrate.
Make a copy of the layer, then save it (Use the 'Save Layer' command in the sidebar, not the 'Save' command at the top)
Open the Details page for the new layer. Take this opportunity to personalize the summary, description and tags.
If you used the Vector Style Editor to establish your copy, don't forget to update the Details page later.
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.
There is another complication though. All of our Basemaps contain the Sprites mentioned above. Depending on which map you use this may be no more than road shield backgrounds, but some include complex textures and patterns (the stylized maps in particular). The Vector Style Editor now permits you to add and/or edit sprites, but this is not possible if you are working directly with the json code.
Making Changes
Vector Style Editor
There are 4 preview screens to see how your changes affect different scales.
The 'Layers' option allows you to drill down into the layers of information on the map and change each individually, or by category.
An 'edit by color' option allows you to select all items with a specific color value and provide a universal color change.
The 'Quick Edit' option (shown above), allows you to make changes by broad groups of information. It includes a random color generator, which doesn't return a finished product, but is great for inspiration!
JSON Code Editor
To use this you must have your own basemap layer already established. On opening, it accesses the Style JSON directly, with the code on the left and a preview map on the right. Changes to the code can be checked out in the preview map using the 'Apply Style' button, then saved when you are happy with those changes.
The Code in Detail
You may not need to use this if you are working with the Vector Style Editor, but it's useful to understand how this environment works. However, if you prefer to move on, go to the second in this series - 'Colors'
This is a small section of the code for the Light Gray Canvas basemap.
For this map, and in this format, there are around 5,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.
Note that "fill pattern" indicates that a sprite is in use, and this is not editable through the code.
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).
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.
Apps like 'JSON Lint' can be lifesavers. Copy your code in, run 'Validate', and it will seek out and flag any issues.
Andy Skinner, Living Atlas Content team, 2019
The Vector Tile Style Editor can be found here.
In the following story maps we will look at how to make adjustments to the style.
| An error has occurred |