Clarify icon-rotation-alignment values

[jfirebaugh]

Wrapped preview:

In combination with symbol-placement, determines the rotation behavior of icons. The value viewport produces icons whose x-axes are aligned with the x-axis of the viewport, regardless of the value of symbol-placement. When symbol-placement is set to point, the value map produces icons whose x-axes are aligned east-west, and the value auto is equivalent to viewport. When symbol-placement is set to line, the value map produces icons whose x-axes are aligned with the line, and the value auto is equivalent to map.

cc @1ec5

[jfirebaugh]

Similarly for text-rotation-alignment:

In combination with symbol-placement, determines the rotation behavior of the individual glyphs forming the text. The value viewport produces glyphs whose x-axes are aligned with the x-axis of the viewport, regardless of the value of symbol-placement. When symbol-placement is set to point, the value map produces glyphs whose x-axes are aligned east-west, and the value auto is equivalent to viewport. When symbol-placement is set to line, the value map produces glyphs whose x-axes are aligned with the line at the point where each glyph is placed, and the value auto is equivalent to map.

[jfirebaugh]

This documentation for text-rotation-alignment is ambiguous about whether, when combined with symbol-placement: line, text-rotation-alignment: viewport produces what it actually does, versus a layout

--l          h--i--s.-
   \        /
    i      t
     \    /
      k--e

[1ec5]

Thanks, this is definitely an improvement. It’s a bit more technical than I would’ve written, but I think developers can still follow along.

For what it’s worth, in mapbox/mapbox-gl-native#5245, which is for symbol-placed annotation views (but same idea), this is how I described a flag that is unset for icon-rotation-alignment: viewport and set for icon-rotation-alignment: map:

If this option is unset, the annotation view remains unchanged as the map is rotated. If this option is set, the annotation view rotates as the map rotates.

For example, you would set this option if the annotation view should be aligned with a street, regardless of the direction from which the user views the street.

I suppose describing use cases is beyond the scope of the documentation in this repository, so this is a 👍.