Style reference: document sdf icons

[nickidlugash]

We need to document sdf icons usage.

[maletor]

👍

[jordi-adame]

please

[buchanae]

I spent a lot of time trying to hunt down the details of SDF today. These are some of the questions/answers I have:

• What does SDF stand for?
  • Signed Distance Function.
• What does that mean?
  • A simple google search can be confusing. In short, it's a simple vector format and a method commonly used for rendering fonts. Luckily Mapbox has written a nice article about this before here.
• What are the limitations?
  • They are single color.
• How does this relate to Mapbox?
  • Vector is pretty! Most of the default Mapbox sprites are not vector. All the cool kids are using vector.
  • You can't change the color of the default Mapbox sprites.
  • Maybe the Mapbox sprites don't have everything you need and you want to add some custom icons.
• How do I do that?
  • First, you need a set of SDF images. Maki has some here. Or, if you want to render your own from SVG files, Maki has a node script you can start with here
  • You need to build those images into a spritesheet with corresponding JSON info. Trying to track down Mapbox's method of building sprites is tricky (build_sprite.js, spritenik, spritezero). I ended up using gulp-spritesmith in my code here.
  • Notice that you need a corresponding JSON file that describes the position and other information of each icon in your sprite. For each SDF icon in that file, you need sdf to be true
  • Maki doesn't build the SDF sprite (yet) so I've posted that in a gist here
  • Set the [sprite](https://www.mapbox.com/mapbox-gl-style-spec/#sprite] property use your SDF spritesheet.

I'm not sure how much of this belongs in the style spec. At this point, in order to go from 100% ignorant of SDF to being able to use it, a solid tutorial with examples is needed. Maybe that belongs in the mapbox-gl-js examples section? With minimal information added to the spec?

[edit: remove comment about limited style-ability of SDF, that was backwards]

[tmcw]

Some notes / corrections:

• SDF = Signed Distance Field

A simple google search can be confusing. In short, it's a simple vector format and a method commonly used for rendering fonts. Luckily Mapbox has written a nice article about this before here.

SDF is a raster format, not a vector one. Vector formats store geometry, raster formats store pixels. SDF is a raster format that is optimized for displaying resized, recolored, and rotated raster images.

You need to build those images into a spritesheet with corresponding JSON info. Trying to track down Mapbox's method of building sprites is tricky (build_sprite.js, spritenik, spritezero). I ended up using gulp-spritesmith in my code here.

Sorry about that mess:

• spritenik is an abandoned prototype. I just re-titled and relabeled it to make that clearer.
• build_sprite.js was removed from mapbox-gl-js quite a while ago: you might find it by Github's search, but otherwise it is the same as any deleted file: it's not recommended or supported.
• spritezero is the way to go: it's how you should make sprites.

---

We use SDF already and always for fonts: rotating and resizing fonts is only possible via SDF.

We don't use SDF commonly for icons, and tools like Mapbox Studio don't create SDF icons. This is because SDF supports a single color. When that limitation is eliminated, a switch will be possible, but for now it's a hard blocker for using SDF as an icon format in end-user technology.

Hence the lack of examples, of documentation, and so on: SDF is not actually used for icons in the vast majority of cases, and the one color limitation would lead most people to think it's broken.

[fchabouis]

Just to be clear : there is currently no simple way to display icons/markers in Mapbox gl and change their color, except using the Circle layer type. Am I right ?

[gertcuykens]

Can at least the icon image be consistent between street and satellite?

[1ec5]

For what it’s worth, iOS and macOS developers can add a template image to their asset catalog and add it to the style using -[MGLStyle setImage:forName:]. The iOS and macOS SDKs automatically convert template images to SDF icons, as a developer would expect on those platforms. No documentation is needed for this particular use of SDF icons, which is internal to the native SDKs and doesn’t touch style JSON at all. For future reference, the format is essentially defined here.

[lucaswoj]

Closing in favor of #444 and mapbox/mapbox-gl-js#3605