Mapbox-gl-js: Transition root property seems to have no effect for first rendering of the map

[pathmapper]

mapbox-gl-js version: v0.44.2

The transition root property seems to have no effect (or I'm misunderstanding the concept of transition).

Steps to Trigger Behavior

1. Set a transition root property for a style and use this style for a map.
2. Change the values for duration and delay of the transition root property significantly and compare with the behavior before the change.

Example Style: style_5000.zip

Expected Behavior

The transition behavior changes according to the chosen values for duration and delay.

Actual Behavior

Transition behavior stays the same, regardless which values are chosen for duration and delay.

This jsbin example uses the example style (style_5000.zip) with the transition root property

"transition": {
  "duration": 5000,
  "delay": 5000
}

and the symbol layer itself has no transition settings, but the transition behavior of the text labels looks like the default:

"transition": {
  "duration": 300,
  "delay": 0
}

[pathmapper]

Some further testing shows that the transition root property has an effect e.g. when using map.setPaintProperty on map load.

http://jsbin.com/kutecapura/edit?html,output (5000 as value for duration and delay)

My expectation is that it should also have an effect for the first visually complete rendering of the map, so e.g. it would be possible to change the default "fade in duration" (300ms ?) of the text labels, right?

[pathmapper]

Updated demonstrations (v0.45.0 and style included):

Transition root property:
http://jsbin.com/fanihuqeni/edit?html,output

Transition root property + map.setPaintProperty
http://jsbin.com/bumajivoxa/edit?html,output

[maxwang7]

I am working on something similar where I would like to be able to change the text shading when you hover over an icon. Currently the text fades in and out which is visually jarring, so would ideally be able to turn off those transitions. Thanks!

[lbud]

Hm. There are two things at play here @pathmapper:

1. Fundamentally what happens when you change the value of a transitionable property (all those denoted as "transitionable" in the style spec documentation) is that the renderer, given the starting value (in your example, black) and the ending value (red) is able to calculate the interpolated value along each frame during the transition (whether that's the default 300ms or, in your example, 10000ms — 5000ms of no change + 5000 ms of transition). The reason the global transition doesn't have any effect on the initial render is that there is no initial value — the starting point before "rendered" is "not rendered," and while theoretically one could argue that the interpolation between "not rendered" and "rendered" is "varying levels of semitransparent", that's both (a) a design choice (what if someone expects it should fade in from black instead of white?) and (b) would require a pretty sizable rearchitecting of our render code. Fadein to first render is not on our roadmap at this time. But thanks for pointing this out — our documentation on the global transition property could be clearer; we'll work on that!

1. Label fade-in is a separate thing entirely. Symbols fade in and out because symbols are fundamentally different from any other layer type: symbols go through complex placement logic to display as much information as can fit well and makes sense, so for example, when you zoom out by a small fraction of a zoom level, the map may now be able to fit one more label in the space provided, so another label appears. We fade them in and out by default because labels appearing and disappearing suddenly is a pretty jarring popping effect. At present the duration of symbol fadein/fadeout is a global map property defaulting to 300ms — you can actually change this (by passing e.g. fadeDuration: 1000 as a map option). This option is currently not documented and is, notably, a global option — so it will apply to all symbols on the map, both in fadein and fadeout. We _may_ add more ways to customize label fading in the future but no concrete plans yet (cc @ChrisLoer).

[lbud]

Erm, more helpfully (hopefully) @pathmapper: if the effect you're trying to achieve is the one you've suggested in the jsbins you provided (start with labels hidden, and fade them in slowly), you'll probably want to use a transitionable paint property like text-opacity to transition from 0 to 1. (Depending on your transition duration — if it's particularly fast — this could interplay strangely with label fading, but it sounds like you're not looking for faster transitions.)

Also, you may already know this, but it's not well-documented either, so I'll just note here: you can also set custom transition properties per-property (for transitionable properties), e.g.

"text-opacity": 0,
"text-opacity-transition": {
    "duration": 5000,
}

and then you can leave the global transition setting alone for other layers/set transitions differently for different layers.

[lbud]

I'm going to close this because the issue on the tin has been resolved and I don't see other actionable items here — please open a new issue if you find unfiled transition bugs. Moving transition documentation action item to https://github.com/mapbox/mapbox-gl-js/issues/6689 + @ChrisLoer is going to document fadeDuration.

[lbud]

@maxwang7 from your description I'm not positive how you're using interactions, but in addition to the above suggestions you may be interested in following https://github.com/mapbox/mapbox-gl-js/issues/6692.

[ChrisLoer]

I ticketed fadeDuration documentation as https://github.com/mapbox/mapbox-gl-js/issues/6694.

[pathmapper]

Thank you so much @lbud for taking the time and writing it all down.

Now everything is clear.