“Image stacks” for image properties

[1ec5]

The image properties – background-pattern, fill-extrusion-pattern, fill-pattern, line-pattern, icon-image – should accept an array of strings as an alternative to a single string. As with text-font’s “font stack”, the renderer should loop over the items of the array, selecting the first value that corresponds to a valid image in the style. Tokens in each item should be evaluated as they are now. Studio would provide a UI for icon-image very similar to the UI for text-font:

This is an alternative to the “token-selection” syntax proposed in #104 (comment). Unlike the other use cases being discussed in #104, selecting an image is special because it is the evaluated string as a whole that must be tested for validity, not an individual token with the string. Any syntax we eventually introduce for conditionals or token defaults would coexist with the image stack syntax.

/cc @mapbox/cartography-cats @mapbox/gl

[jfirebaugh]

Can you say more about the rationale for this feature? Why is it useful?

[ajashton]

Map designer POV: Say I want to make a set of totally custom icons for my map but still take advantage of the {maki} name token from Mapbox Streets. That means I need to either provide an icon image for every possible value of {maki}, or create a rather lengthy filter on the layer to specify the exact maki values I want to include. With a fallback I can create a generic default icon, and focus on designing the icons that matter to me most. It's also easy to gradually add new icons to the sprite without worrying about updating the layer filters to match. You could get even more interesting and start making custom icons based on the name field, eg for major world landmarks or cities.

Mapbox Streets vector tile maintainer POV: right now adding new values to fields like maki, shield, network etc is considered a breaking change because these are commonly used as tokens for symbol image names. We have some nice new icons recently added to the Maki project, but we can't add these to the Mapbox Streets maki field because that would break existing styles that don't have images for those names. For the next version of Mapbox Streets, we could recommend always including a generic fallback for these fields and perhaps feel ok about adding new icons & shields without a major version bump of the vector tile schema.

[1ec5]

Along these lines, a style designer currently needs to jump through a lot of hoops to implement highway shields. The Mapbox Streets source’s {shield} field may be one of dozens of values, each of which (together with {reflen}) corresponds to a series of images in the style. For example, ro-communal corresponds to the images named ro-communal-2 through ro-communal-6. Mapbox Streets has two layers each with unwieldy filters to avoid specifying an image that doesn’t exist:

   {
      "id": "road-shields-black",
      "type": "symbol",
      …
      "filter": [
        "all",
        [
          "<=",
          "reflen",
          6
        ],
        [
          "!in",
          "shield",
          "at-expressway",
          "at-motorway",
          "at-state-b",
          "bg-motorway",
          "bg-national",
          "ch-main",
          "ch-motorway",
          "cz-motorway",
          "cz-road",
          "de-motorway",
          "e-road",
          "fi-main",
          "gr-motorway",
          "gr-national",
          "hr-motorway",
          "hr-state",
          "hu-main",
          "hu-motorway",
          "nz-state",
          "pl-expressway",
          "pl-motorway",
          "pl-national",
          "ro-county",
          "ro-motorway",
          "ro-national",
          "rs-motorway",
          "rs-state-1b",
          "se-main",
          "si-expressway",
          "si-motorway",
          "sk-highway",
          "sk-road",
          "us-interstate",
          "us-interstate-business",
          "us-interstate-duplex",
          "us-interstate-truck",
          "za-metropolitan",
          "za-national",
          "za-provincial",
          "za-regional"
        ]
      ],
      "layout": {
        …
        "icon-image": "{shield}-{reflen}",
        …
        "text-field": "{ref}",
        …
      },
      …
    },

And another one like it for shields with white text. This filter has to be kept in sync with the list of possible values.

This proposal would simplify that layer dramatically:

   {
      "id": "road-shields-black",
      "type": "symbol",
      …
      "filter": [
        "all",
        [
          "<=",
          "reflen",
          6
        ],
        [
          "has",
          "shield"
        ],
      ],
      "layout": {
        …
        "icon-image": [
          "{shield}-{reflen}-black"
          "generic-{reflen}-black"
        ],
        …
        "text-field": "{ref}",
        …
      },
      …
    },

(This example would require -black and -white to be appended to the style images’ names.)

[1ec5]

The implementation for this feature in GL JS would look very similar to the 1ec5-token-selection-104 branch (which is a proposed implementation of #104), but more tightly scoped so that non-image fields are unaffected by the changes. For simplicity’s sake, we’d continue to represent tokens with the {token} syntax until we decide on an approach for #104.

[lucaswoj]

This issue was moved to mapbox/mapbox-gl-js#4149