Adding rotationAlignment: 'horizon' for markers on globe

[SnailBones]

Takeaway from the discussion in #11642 is that a globe-oriented rotation alignment property is useful (but not a pitch alignment), and the clearest name for the property is "horizon." This PR adds that feature accordingly.

const marker = new mapboxgl.Marker({
      rotationAlignment: 'horizon',
      pitchAlignment: 'viewport' // This line can also be left out.
  })

As the map zooms in and transitions from globe to Mercator, markers smoothly transition into rotationAlignment: viewport behavior.

marker-transition.mov

With custom pin markers:

pin-demoo.mov

Launch Checklist

• briefly describe the changes in this PR
• include before/after visuals or gifs if this PR includes visual changes
• write tests for all new functionality
• document any changes to public APIs
• manually test the debug page
• tagged @mapbox/map-design-team @mapbox/static-apis if this PR includes style spec API or visual changes
• add an entry inside this element for inclusion in the mapbox-gl-js changelog: <changelog>Adding new marker styling option: rotationAlignment: 'horizon' allowing marker rotation to match the curvature of the horizon in globe view</changelog>

cc @mapbox/map-design-team

[karimnaaji]

Nice addition! This will be a good feature to land for 2.9.1 🎉

I have a few stylistic comments regarding the newly added code. Otherwise, I haven't been able to locally test markers-custom, it seems like the page doesn't show the markers (only popups):

But it worked great and the other page markers

[SnailBones]

I have a few stylistic comments regarding the newly added code.

@karimnaaji I realized there was still a bit of vestigial logic accounting for the experimental horizon pitch alignment in #1642, so I've been able to simplify the code in a few places. It now seems that adding athis._enableHorizonAlignment() function wouldn't need to be used more than once, otherwise I've addressed your concerns.

Otherwise, I haven't been able to locally test markers-custom, it seems like the page doesn't show the markers (only popups):

Whoops, forgot to commit the custom icon! 🤦 That's now fixed.

[karimnaaji]

nit: Why move these out? I'd prefer locality, so the values aren't few hundreds of code lines away.

[SnailBones]

My thought was that this makes them less magic-numbery and more consistent with the other constants defined at the start of the file, but that's a good point. Do you think that ALIGN_TO_HORIZON_BELOW_ZOOM and ALIGN_TO_HORIZON_ABOVE_ZOOM should also be defined closer to where they are used?

[karimnaaji]

Do you think that ALIGN_TO_HORIZON_BELOW_ZOOM and ALIGN_TO_HORIZON_ABOVE_ZOOM should also be defined closer to where they are used?

I think so, since they're not really shared by anything else and not exported for use outside of this file, it's probably good to keep it local to the block they're used in as well instead of in the global scope. Being consistent in naming would also make sense if you keep here, e.g. making these two variables all caps similar to the other ones.

[karimnaaji]

Looks great! One last nit to address in #11894 (comment) either by making the naming consistent or moving it back to local scope, but otherwise good to merge.

It would be great once 2.9.1 gets released to update the public documentation with the example from markers-custom, so that we have better visibility for that option. Could you open a ticket so we follow up on that?