Satellite Background Map in Tableau - Part 3 - Labels and Styling

Version 1

    This is a continuation of a series, which assumes you have performed the examples and learned the skills in the previous documents.

     

     

    In this installment, we want to begin by adding labels for the counties. The shapefile we used in Part 2 contains the names of the counties, and a variety of other data related to each county. Why can't we just add CartoCSS to show the county name? Let's try it and see.

     

    1. In Docs, under the Text group, you can find that text-name is how to set the field to show. So, let's add that to our CartoCSS for the county boundary layer:

    #tl_2015_us_county {

      line-color: red;

      text-name: [NAME];

    }

     

    2. Save it, and we get an error saying that the property text-face-name is required for defining text styles. So, let's add text-face-name. In Docs, we can see that this is the font name and style. Copying from one of the example styles, we change it to:

    #tl_2015_us_county {

      line-color: red;

      text-name: [NAME];

      text-face-name: 'Arial Unicode MS Regular';

    }

     

    3. Save it, and we now see county names. The font is small and black, and we see too many of them. In this view, we see 4 copies of "Placer" in the small black font:

    What is going on? The problem is that we have hundreds or thousands of points forming the border, and that was rendered into tiles. In this example, it is placing one label per tile. If you were to add a property putting the text placement at each vertex (a vertex is a point where two line segments in the boundary of the polygon connect), you can see how extreme this can get:

     

    4. What if we only want one label in the center of each county? Time to bring QGIS into the mix. There are other articles with tips about using QGIS, so I will just get to the specifics we need. If you don't already have it, download and install it from http://www.qgis.org/en/site/. (It is free!)

     

    The steps are pretty simple:

    1. Open QGIS
    2. Browse to the county shape file you used in Part 2, and double-click it to view.
    3. From the menu, select Vector > Geometry Tools > Polygon centroids
    4. Browse to where you want the output file to go, enter a file name, and click Save
    5. Click OK, then Close when complete
    6. Close QGIS

     

    This new shapefile has one point for each county rather than multiple points forming the whole boundary. This point will be located at the "centroid," which is presumably roughly the average of the coordinates of the boundary for each county.

     

    5. Now, all we need to do is bring it into our Mapbox style. This is similar to what we did with the original boundary shapefile. There are two ways we can do this:

    1. We can create a completely new source with just the layer for the centeroids, just like we did before. In this case, in the Style layers, we would have two custom layers rather than one, for example "mapbox.satellite,mapbox.mapbox-terrain-v1,mapbox.mapbox-streets-v5,<map ID for borders>,<map ID for centeroids>"
    2. Or, we can put the two layers together in one source. In this scenario, just open the source you used before and add a new layer, selecting the centeroid shapefile as the datasource.

     

    In both of these scenarios, it is important to note that the order of the layers is important. For scenario #1, in the list of Sources for a Style, each layer in the sequence sits on top of the previous. So, the one at the end is the one on top. For scenario #2, the layers in the source are in the order they are in the map - the one at the top of the layer list is the one at the top in the map. For things that never overlap, the layer order may not seem important. However, when a county name overlaps a county border, the layer order will determine whether the boundary line crosses behind or in front of the label.

     

    6. You will want to note is the buffer size for the layer. In the layer configuration in the Source, at the bottom of the panel, you can set the buffer size. It defaults to a small number, like 8. What does this do? This is the amount of overlap between tiles for the information on this layer. For things like a boundary line, which is very thin, this can be quite small. However, with something like a county name, depending on the length of the name of the county, and the number and size of the tiles at different zoom levels, if this number is too small, the county name will be clipped in the view. I recommend setting this to the maximum of 64 for the centeroid layer.

     

    7. After you save and upload the Source like you did before, you can update or build a new Style using that source as you did before.

     

    Go'in Out in Style!

    The rest is CartoCSS. I am not going to cover every option in detail, but just point out a few things I found in exploration that might help you get started.

     

    In my project, this is the CartoCSS I used for the "counties" layer:

    #county_centeroids {

      text-allow-overlap: false;

      text-name: [NAMELSAD];

      text-face-name: 'Open Sans Regular';

      text-fill: #fff;

      text-halo-fill: black;

      text-halo-radius: 3;

      text-halo-opacity: 0.2;

      text-opacity: 0.8;

      [zoom>=9] {

        text-size: 20;

      }

      [zoom=8] {

        text-size: 12;

      }

      [zoom=7] {

        text-size: 10;

        text-name: [NAME];

      }

    }

     

    I'll review the ones that we haven't already discussed:

     

    text-allow-overlap: false;     This determines whether the labels are allowed to stack on top of each other. This line actually does nothing, since the default value is false. I added the line to see what happens when the value is true. I didn't like it so I turned it off again.

     

    text-name: [NAMELSAD];     As previously discussed, the text-name defines what field in the shapefile data is rendered in the text. I point it out here to show that the previous example used [NAME], which is the county name, such as "Sacramento" or "Orleans," whereas [NAMELSAD] is the county name along with the "legal/statistical area description," or "Sacramento County" or "Orleans Parish."

     

    text-fill: #fff;       This sets the color of the text. #fff is the same as entering "white."

     

    text-halo-fill: black;     The "halo" is an area around the letters of the text. Black helps it stand out, especially against lighter color backgrounds since the text is white.

     

    text-halo-radius: 3;     This is the number of pixels for the size of the halo.

     

    text-halo-opacity: 0.2;     Opacity is the opposite of transparency, and has a range of zero to one, where zero is invisible and one is completely opaque. In this case, it opacity as applied to the text halo. So, 0.2 makes the background show through significantly.

     

    text-opacity: 0.8;     Opacity as defined above, but applying to the text itself. 0.8 makes it nearly opaque, but will show the background slightly.

     

    [zoom>=9] {

        text-size: 20;

      }

      [zoom=8] {

        text-size: 12;

      }

      [zoom=7] {

        text-size: 10;

        text-name: [NAME];

      }

    This block allows different text formatting based on various zoom levels. When the zoom level is higher, the font size is larger, and when the zoom level is lower, the font size is smaller. And at the most extreme zoom levels the label changes from the [NAMELSAD] (the default defined for the layer) to [NAME] which is shorter.

     

    So far, all I have shown is styling our custom layers. We can also control styling of the built-in layers of the templates we used. For example, there are a few characteristics of the "Satellite Afternoon" style that I didn't like. This is the default view of an area near me at zoom level 15:

    The color blotches may have some sort of meaning, but they were not appealing to me. After some tinkering, I learned that much of it was determined by this section in the "styles" tab:

    // Southern Hemisphere:

    #hillshade {

      comp-op: overlay;

      polygon-opacity: 0.5;

      [class='medium_shadow'] { polygon-fill: #46a; }

      [class='full_shadow'] { polygon-fill: #246; }

      [class='medium_highlight'] { polygon-fill: #ea8; }

      [class='full_highlight'] { polygon-fill: #fea; }

    }

     

    Comment lines begin with //, and have no affect on the output. Comment blocks can be any length, on one line or multiple, and begin with /* and end with */.

    Why this section has the comment "//Southern Hemisphere" I don't know, since this location is in the Northern Hemisphere. But it clearly has an effect, because when I commented it out, it looks like this:

    It is better, but a bit monochromatic. That appears to be due to the image-filters line in this section:

    #mapbox_satellite_full,

    #mapbox_satellite_watermask  {

      raster-opacity: 1;

      image-filters: scale-hsla( 0.5,0.6, 0.0,0.2, 0.4,0.8, 0,1 );

    }

     

    Commenting out that line, gives us this:

    I haven't spent the time to learn the details of how the image-filters work, but suffice it to say that you have control. For example, if you need the satellite background to be washed-out so your marks are more clear and obvious, you can do that via image-filters.

     

    I hope that gets you started with Mapbox.

     

    Epilogue

     

    Unfortunately, after all this work, I was disappointed with Mapbox's pricing structure. I work for a non-profit organization and only 3 of our users really need this functionality at this time, so I inquired as to pricing for our situation. I was informed that they would give us only a 10% discount off the Premium plan, which is the only one available for "internal users." That amounts to $450 per month, which is many times the cost of Tableau Server licenses for those users. Yet 75,000 "mobile users" in Mapbox costs only $49 per month.  I am completely baffled why 3 internal users costs almost 230,000 times more than "mobile users." Even if every user in our organization used it, or if they knocked a zero off the price, it would be very unbalanced. So, I guess they greatly prefer mobile and public users over Tableau users. If they change their pricing structure, I will post it here. In the meantime, I guess it was an interesting exercise.

     

    I hope you find this helpful. If you have questions about this document itself, like a step I missed or something that wasn't clear, feel free to post it here so I can improve the quality of the document. However, if you have general questions about Mapbox, or other things you are wanting to accomplish, please post them in the Forum, where others will see it and contribute.