symbol-clip: Render tests, debug page and distance matrix rework

[arindam1993]

This PR adds a bunch of render tests testing out various different code paths, I've grouped them at the first level by the type of symbol-placement used, so there are two folders point and line.
The tests in those folders use the same filter expression, but with different data Point features for the point placement and LineString features for line placement.

I also implemented a new set of centerDistanceMatrices in Transform to account for the small differences we need between the fog and symbol distance matrices. These differences are

• Its centered at z=0 and is used to calculate 2D distances along the sea-level plane.
• Its uses a simpler reference frame, the distance d calculation for any anchor point p ends up being

v = p * distance_matrix 
d = sign(v.y) * length(v)

This is because the matrix defines a co-ordinate system centered at the map center with +y pointing away and +x pointing to the right.

I also added a debug page that uses this matrix + turf to generate some geojson that draws out the distance scale as an overlay.

[arindam1993]

threw in this fix for the microbenchmarks as well.

[SnailBones]

Good work Arindam, I like the thorough tests!

One nitpicky question: can you explain the decision to put the new tests in such deeply nested folders? Do you expect us to add inside of dynamic-filter in a sibling directory to symbols?

I like the increased organization, but it's also bugging me a bit that it's inconsistent with the other tests (Others seem to be nested two directories deep, these new ones are four or five).

[arindam1993]

Good work Arindam, I like the thorough tests!

One nitpicky question: can you explain the decision to put the new tests in such deeply nested folders? Do you expect us to add inside of dynamic-filter in a sibling directory to symbols?

I like the increased organization, but it's also bugging me a bit that it's inconsistent with the other tests (Others seem to be nested two directories deep, these new ones are four or five).

mostly to avoid extra long names like this 😅

In the future if we add a feature to have a foreground clipping thread for say, fill-extrusions then I'd add a fill-extrusion sibling directory and expand out all the combinatorial possibilities from there.
Here the combinations expand out this way,
layer-type -> symbol-placement-type (point/line) -> expression-type -> (optional) multiple global states of same expression (varying pitch)

[SnailBones]

👍

[rreusser]

Things look good on a detailed level, but I did want to clarify my understanding of the precise definition(s) of distance with respect to clipping before giving it a final 👍

[rreusser]

Is distanceFromCamera a descriptive name? It seems like this is used to compute the distance from the view center/look at rather than the distance from the camera.

What catches my attention is that the difference seems to add a strong radial dependence to the cutoff. I don't immediately see the pros/cons of the strong radial dependence, as illustrated in the highlighted region below. Is this the main criteria people would use to clip based on distance? I'm not opposed to it and can imagine that some of the factors which made fog challenging may factor into the decision, but I'm at least weighing the mental overhead of another similar but slightly differently defined distance field. Are there reasons not to use a distance metric similar in definition to fog?

distance-to-center < -0.5:

[arindam1993]

Because this is how the fog distance field shifts around with pitch (this isnt a problem for fog because we only use it at high pitch where it doesnt shift) The shift is because of the translation the camera when pitching.
At pitch 0:

At pitch 20:

At pitch 60:

At pitch 80:

Whereas this stays locked at the center.

[arindam1993]

This is what I used to generate the geojson for the above viz

function generateDistanceScales() {
    const center = map.getCenter();
    const bearing = map.getBearing();
    const rings = 20;
    const step = 0.1;

    const matrix = glMatrix.mat4.invert([], map.transform.mercatorFogMatrix);
    const circles = [];
    for (let i = 1; i <= rings; i++) {
        const radius = step * i;

        for(let th = 0; th < 360; th+= 20) {
            const p = [radius * Math.sin(th * Math.PI/180), radius * Math.cos(th * Math.PI/180), 0];
            const coord = new mapboxgl.MercatorCoordinate(...glMatrix.vec3.transformMat4([], p, matrix)).toLngLat();
            const f = turf.point([coord.lng, coord.lat]);
            f.properties['distance'] =  `${(radius - 0.5 / Math.tan(map.transform.fov * 0.5)).toFixed(2)}`;
            circles.push(f);
        }
    }

    return turf.featureCollection(circles);
}

[SnailBones]

@arindam1993 What's the advantage of this staying locked at the center? The fog behavior seems closer to a distance from camera operation. Wouldn't that be more intuitive for users than the radial behavior from map center, particularly if it could be consistent with fog?

[arindam1993]

Because unlike fog this isn't a high-pitch only use-case, users can do whatever they want with the pitch and set much lower thresholds too if they wish. So imo having a nice and fixed reference frame is better so that the clipping boundaries arent moving around as much when pitching in the range of (0-40) deg.

[rreusser]

I've created a notebook here which illustrates fog units (which would be my vote to reuse as symbol-clip units as well): https://observablehq.com/d/50ec70cf44480b1d

The behavior at medium and high pitch seems preferable to me. The units make a little less sense at very low pitch, though the symbol-clip feature also makes a lot less sense to me at zero pitch as well. It would be straightforward to transition to viewport-fixed units (viewport size = 1.0) at zero pitch so that they would always make sense, but again, I'd want to be certain of the use case of symbol-clip at zero pitch before strongly suggesting that.

Also, regarding the fog elevation estimation, I'd imagine we could neglect elevation sampling for this distance metric when terrain is enabled, and similar issues like the units falling away to the horizon at high pitch in high-elevation terrain would be much, much, much less apparent than fog.

[rreusser]

Talked to Arindam. One downside of the above is that it adds additional dependence on pitch, which would be nice to avoid since it'll make symbols hide/show more often when pitching. We're currently trying out ground-fixed planar lines (no pitch-dependence).

[SnailBones]

I'm still struggling to understand the difference between how these approaches will effect symbol filtering. Do we have an example that more closely reflects real-world use case of this feature?

[arindam1993]

Got the planar lines implemented and tests updated.

[arindam1993]

@SnailBones the problem is the foreshortening of the far distances.
Sample case:
filter: [ '<', ['distance-from-center'], 0.5]
Here the value of 0.5 means that: Clip this symbol in the region beyond what would be the top of the screen at 0 pitch

But since the fog distance measures a 3d distance from the camera to the plane, the value of the distance at the same geographic location increases as pitch increases, which means that what wasn't being clipped at 0 pitch gets clipped at a higher pitch. You can see this in the GIF @rreusser posted, the first line corresponds to fog_distance=0.5, it starts of at the water at 0 pitch and then gets squished inwards.

[rreusser]

Looks good! Nice work. 👏 Presumably this will suffer from some of the same challenges as fog when terrain is active, but I assume it simply won't matter since it'll be so much harder to notice.

[rreusser]

It's been on my todo list for a while to switch these all to plain Arrays so that they'd be double precision with GL also still accepting them.

[arindam1993]

Thanks for all the feedback 🙇 , the switch the planar lines was a really good move!