Add paint property for icon image URL

[1ec5]

The icon-image property takes the name of an icon in the style’s sprite property, which means symbols can only wear the images provided by the style at design time. For parity with Apple’s MapKit framework and the Google Maps SDK, the mapbox-gl-native project and its SDKs support an alternative annotation API that facilitates point and shape overlays in an imperative programming style. One of its distinguishing features is that you can “install” an arbitrary PNG data blob – whether read from a local or remote URL or rendered on the fly – and apply it to one or more point annotations. Whereas design-time sprites are often reused heavily, it’s very common in mobile applications for each individual annotation to wear a distinct image.

In order for the runtime styling API (which implements this style specification) to reach parity with the annotation API, we should add a paint property icon-image-url that can be set to a URL or URI. To support images rendered dynamically at runtime, data: URIs should also be allowed by the specification. It would be nice if HTTP(S) URLs could be used to display remote images in symbol layers, but this might be more complex to implement, considering that remote images would have to load asynchronously. Tokens should be supported, so that source data can determine the icon on a point-by-point basis.

I’m unsure whether this property should take precedence over icon-image if both are specified on the same layer.

/ref mapbox/mapbox-gl-native#5626 (comment)
/cc @mapbox/gl

[jfirebaugh]

Ref mapbox/mapbox-gl-js#358. In particular mapbox/mapbox-gl-js#358 (comment) proposes extending the icon-image property with a CSS-like url(...) syntax rather than introducing a new property.

[jfirebaugh]

Another approach -- one which I think we should follow even if we also add support for image URLs -- is to treat the icon set as an inline portion of the style itself rather than an independent resource requested by URL reference (c.f. #220 (comment)) and then introduce icon CRUD operations to the runtime styling API.

[1ec5]

extending the icon-image property with a CSS-like url(...) syntax rather than introducing a new property

Given the discussions around token defaults in #104, we probably wouldn’t want to introduce a mini-language syntax that would break compatibility with existing icon-image usage. An object with a url property would be more consistent with the proposals in #104.

[kkaefer]

Another approach -- one which I think we should follow even if we also add support for image URLs -- is to treat the icon set as an inline portion of the style itself rather than an independent resource requested by URL reference (c.f. #220 (comment)) and then introduce icon CRUD operations to the runtime styling API.

This makes sense and mirrors the way we handle GeoJSON and TileJSON data.

[lucaswoj]

Closing in favor of mapbox/mapbox-gl-js#2059 & #220