Design Proposal: Support pitch dynamic value in expressions

[adjourn]

Design Proposal: Support pitch dynamic value in expressions

Motivation

Since 2D and 3D are very different perspectives, it makes sense to provide APIs for developers to style them differently. It's possible to severely hurt the user experience by treating both the same way. I see it becoming more relevant and important since OSM 3D data (i.e building parts) is getting more accurate and widespread, it's also easier than ever before to generate your own vector tiles.

Simple example:

Extruded buildings can be helpful - recognisable skyline, buildings, etc but if you look at the map from above, a lot of readability can be lost: extrusions can hide important features, there's a lot more visual clutter in terms of sidewalls, "shadows", etc.

It could be simply addressed by e.g "fill-extrusion-height": ["interpolate", ["linear"], ["pitch"] ...] expression that could decrease extrusion amount if pitch approaches zero.

Similar behaviour can be seen in MapBox GL v3.beta demo: https://labs.mapbox.com/standard-style/.

Please note that this is not the only way to do it, we can dynamically set camera field of view with application code to achieve similar effect but it's just one example. You could use pitch to transition many different style values like colour, opacity, size, etc.

Proposed Change

Inspired by this: https://maplibre.org/maplibre-style-spec/expressions/#zooming

pitch

Gets the current pitch level. Note that in style layout and paint properties, ["pitch"] may only appear as the input to a top-level "step" or "interpolate" expression.

Syntax

["pitch"]: number

Optional

It could even go as far as supporting minpitch and maxpitch since implementing pitch the same way as zoom would most likely require very similar logic in same places.

Might be a good idea to consider how to avoid doing all these runtime checks if feature is not used.
I'm not familiar enough with the code base yet to tell if it's even an issue. Hence the next section..

Dreaming

Since there's also this proposal which would probably have very similar API (["interpolate", ["linear"], ["distance"] ...]), if both seem good ideas then it might be worth to think about this on a higher level since they should have quite similar logic flow with zoom - some kind of standardized base class/lifecycle hooks you need to register (no overhead otherwise).

If that was the case, then maybe some day developers could also use it to provide ANY dynamic value to styles and these spec proposals would be replaced with application layer code and npm packages.

// this is super ignorant pseudo code and none of these methods
// might not make any sense but hopefully the point will come across
map.registerExpressionDynamicValue({
  name: 'x', // i.e ["interpolate", ["linear"], ["x"] ...]
  commands: {
    // application could call map.setX(args); and map automagically updates with new "x" value
    setX: (args) => {},
    setLayerXRange: (args) => {}
  },
  // lifecycle hooks (implementation detail)
  onStylesDiff: (before, after) => {},
  onSourcesDiff: (before, after, commands, sourcesRemoved) => {},
  onLayersDiff: (before, after, commands) => {}
});

API Modifications

See the section above.

Migration Plan and Compatibility

This is an addition and opt-in API change, no backward compatibility issues.

Rejected Alternatives

Everything proposal would unlock, could be done with application code by subscribing to pitch changes and changing the style that way but the same case applies to zoom. I think it makes developers' life a bit easier and eliminates a footgun.

[wipfli]

Thanks for putting this together.

we can dynamically set camera field of view with application code to achieve similar effect but it's just one example

Camera field of view map.transform.fov is different from pitch, right?

Would be cool to have more camera controls in the style in general I think.

Maybe related: https://github.com/wipfli/field-of-view-demo

[HarelM]

I think pitch might not be a heavy lift, but I'm not sure about the rest of the stuff that are needed for:

• Design proposal: Ability to style based on distance from the camera or legibility #161

In general the main solution to pitch is to support changes that has properties like map and viewport to accommodate for pitch changes.

Can you share an example that the above map/viewport solution does not solve and needs a pitch expression support?

[HarelM]

In most cases the map deals with pitch using map and viewport setting for stuff like text and icons.
#161 requires more than just pitch, it requires possibly map center, screen area and in general probably adds a lot of calculations, so it's a different proposal and different complexity.

Can you give a use case (preferably not a theoretical one) that needs pitch that can't be handle with the above viewport and map configurations?

I think the complexity of a spec about "distance from camera" is high.
Adding a pitch which behaves similar to zoom should be relatively simple I believe, but I think it will need a good use case.