Provide a means to determine occlusion of LatLng positions when using setTerrain()

[jaybo]

Motivation

I have an app which projects pixel based animations using a D3 canvas onto a mapboxgl map. All of the animated objects are at sea level and represent dynamic current velocities or tide stations. In V2, after enabling 3D terrains via setTerrain(), my D3 canvas objects don't correctly disappear when occluded by intervening terrain.

In the image below, the foreground arrows are correctly displayed, but all of the background yellow boxes (at sea level on another body of water in the distance) should not be visible since they should be hidden behind the intervening mountains. When the world was "flat" this wasn't an issue, but now with setTerrain() enabled, there is visual confusion.

Design Alternatives

While I could rewrite everything to project my pixel based D3 animations into geojson and add them to a mapbox layer, this is, er, work and I have no idea if performance would be impacted. And this seems like a general issue that others will also likely confront.

I would assume map.project() would be the best place to return this information. The current return value is:

Returns a Point representing pixel coordinates, relative to the map's container, 
that correspond to the specified geographical location.  

When the map is pitched and lnglat is completely behind the camera, 
there are no pixel coordinates corresponding to that location. 
In that case, the x and y components of the returned Point are set to Number.MAX_VALUE.

Design

Add an optional parameter to map.project() indicating that Number.MAX_VALUE should be returned also in the case of occlusion.

map.project(coordinate, onlyIfVisible = false);

This would introduce no backward compatibility issues.

A more general solution would be to add an additional API which explicitly handles elevation such as:

map.project3D(coordinate3D, onlyIfVisible = false);

Mock-Up

Concepts

Implementation

[karimnaaji]

Capturing some of the discussion about this API with @arindam1993 :

• The API should allow to be used for custom layers while drawing a 3d model, in such case, an AABB of latlng + altitude should be allowed as the input of this function
• To honor the simple case of just checking a single point against occlusion, a latlng should also be allowed

This specific function signature seems to be the most flexible to honor the above use cases:

getOcclusion({min:{latlng, altitude}, max:{latlng, altitude}} | {latlng, altitude?}) : bool | null

• If {min:{latlng, altitude}, max:{latlng, altitude}} is provided, the height point of the cube represented by min and max will be checked for occlusion against terrain. If any point is visible, the function will return false, and true otherwise.
• If {latlng, altitude?} is provided, the latlng + altitude point will be checked for occlusion. If altitude is omitted, we will automatically sample terrain at the given latlng and check for occlusion.
• If occlusion can't be checked due to missing terrain, the function should return null, to not misinterpret the result as non-occluded when terrain tiles aren't available

[karimnaaji]

As for naming, I think queryOcclusion would also work, as it seems like it's more common in our naming convention.

[valentinbdv]

Hello, I hope all is well at Mapbox.

I would need something like this for a complex map project using terrain and 3D objects. As the issue is quite old, is there a solution already implemented to handle this or do you plan to make progress on this?

Thank you very much for your feedback.