add support for non-mercator projections

[ansis]

This adds support for rendering maps with non-mercator projections using existing styles and tilesets. The mercator-tiled tilesets are reprojected in the browser. Vector reprojection, instead of raster reprojection, is used for vector data to keep rendering perfectly sharp.

As you zoom in, the projection the map is gradually unskewed so that at high zoom levels the map is rendered the same as in mercator. This gives you the benefits of projections at lower zoom levels without the distortion at high zoom levels.

projections.mp4

#3184

Projections cannot be used together with 3D terrain yet.

// in the constructor
const map = new Map({
    projection: {name: 'winkelTripel'},
    ...
});

// at runtime
map.setProjection({name: 'winkelTripel'});

// or in the stylesheet
"projection": {"name": "winkelTripel"}

Projections specified in the constructor take precedence over projections set in the style.

Supported projections

Albers

Supports parameters center and parallels.

Equal Earth

Equirectangular

Lambert conformal conic

Supports parameters center and parallels.

Natural Earth

Winkel tripel

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
• post benchmark scores
• manually test the debug page
• apply changelog label ('bug', 'feature', 'docs', etc) or use the label 'skip changelog'
• add an entry inside this element for inclusion in the mapbox-gl-js changelog: <changelog>Add support for a variety of new map projections beyond the standard Web Mercator. Alternate projections can be used together with any existing styles and sources, and adopt a novel design that minimizes distortion across the zoom range and keeps vector rendering sharp. For the first time, this makes using alternate projections with full-featured interactive maps a seamless experience.</changelog>

[karimnaaji]

A first review pass! I'm planning on doing more testing, but so far:

• My biggest concern is around combination of non-compatible features (projection/terrain, projection/fog...) and finding mechanisms at disabling them.
• Also, high pitch seem to trigger a few issues in the tile cover in non-mercator projections. I tend to think that high pitch is only beneficial for 3d (terrain/fog/fill-extrusion) and has relatively low value for 2d projections under low zoom. Have we considered enforcing a max pitch per projection?
• There seem to be a leak for tile buffer memory, we should find a place for release (e.g. buffers created from _makeTileBoundsBuffers)

[karimnaaji]

Not a blocker for this review. But we should capture these small tweaks to address separately: this.parallels is always used in radians in project() and unproject(). We could move that conversion once when assigning this value to the projection.

[Titov163q]

53°07'25.3"N, 48°23'45.6"E

[karimnaaji]

Should we use getInterpolationT to fade out sky layers similar to the shear adjustments? I haven't tried projections with this layer specific to 3d layer yet but it should be a fairly small change based on the current projection here.

[ansis]

Sky seems to work about as well with other projections as it does with mercator. It's kind of weird for both at the lowest zoom levels where the map doesn't reach the horizon (and where it's weird seeing a non-curved earth when pitched). Fading out might be a good thing to do but I think it's a separate decision.

I think we should also use a different range to fade it out since I think we want to do it consistently for all projections

[ansis]

Looks like this branch makes loading mercator maps (with no visual change) 1% slower. Most of this seems to come from increased tile parsing time. My guess would be the extra complexity around loadGeometry(...) adds up. We should look at eliminating this but it also seems acceptable for a feature of this size.

Diagnostic metrics

[karimnaaji]

Code looks great and LGTM, nice work!

@ansis I kept notes notes while reviewing about issues I encountered that we should address, I'm not sure about when based on the deadline, but I suggest triaging these and making sure to order and prioritize them if the impact is high enough. Feel free to reevaluate whether merging should happen now if any of these is critical for the immediate usability of the feature at launch, or defer the launch of a few of these projections (Albers seem to have a few usability issues with gestures).

Tile bounds buffer may be created unnecessarily

A potential optimization: we should be able to create tile bound buffers only for tiles that are in the 'loaded' state, on-demand for visible tiles. Creating the tile bounds buffer can be a non-trivial amount of work. These buffers are created in the tile constructor, but tiles may never reach the 'loaded' state, resulting in these buffers being created and destroyed wastefully.

Warning after reaching max allowed extent

Tile retention issues may lead to flickering

Some tiles may flicker when zooming in or out, could be that the source cache may not retain those tiles with projections.

tile-retention-projection.mov

Custom geojson does not respect world bounds

Might be directly related to #11130?

Gesture issues with Albers projection

Gestures seem to have a few usability issue, and the map center may wrap when panning on the map at world boundaries when flinging or panning under Albers.

gesture-fling.mov

Currently under Albers projection the user isn't able to see a large part of the South America, blocked around here:

Should we leave Albers in the code, but remove it from this launch?

Low unit and render test coverage

Considering the high chance of overlap with the globe view, we should be particularly careful about not breaking existing behaviors of projection and introducing regressions. I recommend to increase the coverage before any other work for globe view happens.

[karimnaaji]

Gesture issues with Albers projection

Resolved offline:

Albers is a projection that works well under one parallel, but a risk might be that devs may not use max bounds and let users pan and zoom around freely, eventually accessing the issues mentioned once panning too far from the original center and parallel. If we were to enforce the bounds, the nice point is that we're sure the user can't see those issues, but that adds an implicit behavior. Since conical projections can use different regions by changing the parallels and center, the max bounds isn't well defined: we would have to override the default bounds per center and parallel. It's best to suggest it by having an explicit mention of map bounds in conical projections (5af4076).

[karimnaaji]

Tile retention issues may lead to flickering

Seem to be fixed after d0afb1b. No more repro of this particular issue.

[ansis]

Opened issues for the remaining problems:

Tile bounds buffer may be created unnecessarily

#11138

Warning after reaching max allowed extent

#11137

Custom geojson does not respect world bounds

#11130