s̶y̶m̶b̶o̶l̶-̶c̶l̶i̶p̶ dynamic-filtering with pitch and distance-from-camera expressions

[arindam1993]

Lots changed with the design and implementation of this since I first started this, leaving behind the original post under ----------OLD------------- for documentation.

The first part(#10923) was changing it so the user doesn't have to write their own separate filter and symbol-clip expressions. Instead this allows the user to write one single filter expression that then gets split during the filter compilation into separate filter and dynamicFilter expressions.

The filter part is evaluated in the worker just like before, whereas the dynamicFilter part is evaluated continuously during placement.

The next part was adding all of this new filter validation logic to the style-spec package(#10977)

The last part was tweaking the distance metric slightly and making it slightly different from fog (#11065).

Instead of being a distance measured from a point, its now a distance measured from a line passing through the center, perpendicular to the bearing.

@mapbox/map-design-team @mapbox/gl-native

------------------ OLD-------------------------

This PR adds a new boolean spec-property for the symbol layer that lets the user define clipping constraints based on the current state of the camera.
When this property is true for a given symbol, the symbol gets hidden, and when its false it gets displayed. Thus to keep it backwards compatible is false by default.

The primary goal of this is to be able to control-ably reduce symbol density in the far distance when the map is pitched.
With this in mind this spec property:

• Supports data-driven styling

• Supports zoom , pitch and distance-from-camera expressions

• Has NO restrictions on where in the expression zoom, pitch and distance-from-camera can appear (Currently we only support zoom as a top-level param to an interpolate expression)

• pitch expression returns the pitch in degrees

• distance-from-camera expression returns the distance of the symbol from the camera in the same viewport size normalized units that are used for near and far distance measurements for fog.

Demo:

With the following code:

map.setLayoutProperty('building-number-label', 'symbol-clip',
    ["case",
        ["<", ["pitch"], 60], false, // Don't clip any symbols when pitch is LOW
        ["all", [">=", ["pitch"], 60], ["<", ["distance-from-camera"], 2]], false, // When pitch is HIGH, don't clip symbols near to camera
        true // Otherwise hide the symbol (because its far-away, and pitch is high)
    ]
    );

    map.setLayoutProperty('poi-label', 'symbol-clip',
        ["case",
            ["<", ["pitch"], 60], false,
            ["all", [">=", ["pitch"], 60], ["<", ["distance-from-camera"], 4]], false,
            true
        ]
    );

    map.setLayoutProperty('transit-label', 'symbol-clip',
    ["case",
        ["<", ["pitch"], 60], false,
        ["all", [">=", ["pitch"], 60], ["<", ["distance-from-camera"], 3]], false,
        true
    ]
    );

Screen.Recording.2021-06-07.at.3.17.27.PM.mov

This hides all POI labels in the far-distance, and lets street labels show through. This works because clipping takes place before collisions, thus the screen real-estate freed manually up by carefully crafted constraints can be filled with more pertinent information automatically by the placement engine.

How this works

This expression is evaluated on the main thread during placement , if the symbol needs to be clipped it early-exits and completely skips placing it. For a collision box debug-view rendering it gets treated it as an "unused" symbol, same as rejected placement locations for text-variable-anchor based symbols are treated.

• Box sizing, and projection logic on the main thread is skipped
• Insertion into collision grid and collision evaluation for it is skipped.
• They still get drawn with 0 opacity overdraw just like symbols that are hidden due to collision.

What about performance?

Still very early, but framerate for the case I described above in the Demo seems much better. At high pitch viewport-aligned symbols at a far distance overlap a LOT and that places a lot of load on the collision evaluation. This skips all of that work.
A particularly bad case:
Before:

After:

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
• tagged @mapbox/map-design-team @mapbox/static-apis if this PR includes style spec API or visual changes
• tagged @mapbox/gl-native if this PR includes shader changes or needs a native port
• 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 the ability to use ["pitch"]and["distance-from-center"]expressions infilterfield ofsymbol layers. </changelog>

[arindam1993]

This Observable hosts a playground for prototyping styles with this prop

https://observablehq.com/@arindam-mapbox/symbol-clipping-playground

[SnailBones]

I like the line-based distance metric!
Can you provide more context on the example? Should I be entering expressions here? Do you have some example expressions that might be common use cases?

[arindam1993]

Ran the full-loading benchmarks and seeing a ~1.6% slowdown in loadTime.
The diagnostic metrics are a bit confusing because it shows an increase in the workerIdle part, which doesnt make sense for the changes in this PR.
Maybe its because of importing v8.json directly which might be causing an increase in the bundle size.

[arindam1993]

Ok, I've been able to get the load times much more under control by hackily removing the duplication of the filterSpec in v8.json.

But that also removes the metadata studio would like, trying to think of a solution.

[arindam1993]

ran one more benchmap run, looks like the latest commit with the lazy filter compilation actually helps much more with load times.

[karimnaaji]

Nice work @arindam1993 ! LGTM 🟢

[CptHolzschnauz]

VERY nice feature but i can't get it to run, not even on your playground:

properties.js:374 Uncaught TypeError: Cannot read properties of undefined (reading 'value')
at gs.getValue (properties.js:374)
at Lh.getLayoutProperty (style_layer.js:124)
at je.setLayoutProperty (style.js:1050)
at Map.setLayoutProperty (map.js:2348)
at Map. (map56.html:1346)
at Map.fire (evented.js:129)
at Map._render (map.js:2911)
at map.js:3216

Can you add a example (Full code or include it somewhere in the Mapbox examples) ? Thx

[SnailBones]

@CptHolzschnauz We're currently putting together some examples, they'll be live with our launch within a few days.

[CptHolzschnauz]

Thx. Whatever i try, i can't see any filter effect on my layer. This amazing feature deserves a fully working example.

[CptHolzschnauz]

If someone finds this thread:
https://docs.mapbox.com/mapbox-gl-js/example/switch-symbol-style-pitch/