Text symbol with placement `line` placed along wrong feature

[madoci]

maplibre-gl-js version: 5.7.0

browser: Firefox & Chrome

Steps to Trigger Behavior

1. Add a source with at least two LineString touching each other.
2. Add a symbol layer with placement "line" and a text field that evaluates to the same value for both LineString (a constant 'text-field' can do).
3. Some text symbols of one LineString appear on the other LineString. It can be visible either by applying a different color to each feature, or by adding a listener to the symbol layer and looking a the event feature (with some kind of id to differentiate the two feature).

From my tests, it seems the problem doesn't occur if :

• 'symbol-placement' is 'line-center' or 'point'
• the lines do not touch
• the evaluated labels are different

Link to Demonstration

https://jsbin.com/nobehezina/edit?html,console,output

Expected Behavior

The text symbol displayed alongside a LineString feature should always be tied to that specific feature.

Actual Behavior

The text symbol displayed alongside a LineString feature can sometimes belong to another feature.

[madoci]

From further analysis, it seems to be because adjacent lines are merged if they have the same text :

maplibre-gl-js/src/data/bucket/symbol_bucket.ts

Lines 548 to 551 in 1e9c877

	if (layout.get('symbol-placement') === 'line') {
	// Merge adjacent lines with the same text to improve labelling.
	// It's better to place labels on one long line than on many short segments.
	this.features = mergeLines(this.features);

I don't know where to go from there. It feels wrong to me to merge features just because the text is the same, even though other style properties might differ (plus the fact we get the wrong feature in events). Could we check if style is the same, although it could hurt performance evaluating all the properties at that point ? Or add a property to the symbol layer specification to opt out of this behavior ?

[HarelM]

I'm guessing you can adjust the key to include the color as well, but this looks intentional in general...

[HarelM]

I think the original implementation is in this PR:

• Merge adjacent roads with the same text for labeling mapbox/mapbox-gl-js#683

And the original issue is here:

• Join roads with the same name for labelling mapbox/mapbox-gl-js#56

[madoci]

Yeah, it's obviously made for road labels, which probably is the most common use of text on line, but still is a very specific usage of line-placed symbol layers.
Adjusting the key to include color will only solve my use case without addressing the underlying problem, and I fear it could break things for some users (does everyone relying on this "merging lines" feature use a constant color ?).

Would adding a property to the symbol layer specification be a valid solution ? I don't know how much the style specification should be implementation-agnostic.
And if we were to add a property, I currently see two ways of approaching this :

• A single non-data-driven property that enables or disables the merging of lines.
• A data-driven line key property that would be included in the keys used by the mergeLines function. That would allow merging some and not all features.

[HarelM]

I'm not sure this should be a style-spec property and not a map option, IDK...
@louwers do you know what is the behavior of this case in native? Does it also merges lines?

The following is the style to test:

{
        zoom: 3,
        center: [-12, -8],
        version: 8,
        glyphs: "https://demotiles.maplibre.org/font/{fontstack}/{range}.pbf",
        sources: {
          test: {
            type: 'geojson',
            data: {
              type: 'FeatureCollection',
              features: [{
                    type: 'Feature',
                    properties: {
                      id: 1,
                      color: "#DF74F7",
                    },
                    geometry: {
                      type: 'LineString',
                      coordinates: [[-20, -20], [-12, -8]]
                    }
              }, {
                    type: 'Feature',
                    properties: {
                      id: 1,
                      color: "#FAB350",
                    },
                    geometry: {
                      type: 'LineString',
                      coordinates: [[-12, -8], [0, 0]]
                    }
              }]
            }
          }
        },
        layers: [{
          id: 'test-line',
          type: 'line',
          source: 'test',
          paint: {
            'line-width': 3,
            'line-color': ['get', 'color']
          },
        }, {
          id: 'test-text',
          type: 'symbol',
          source: 'test',
          layout: {
            'symbol-placement': 'line',
            'text-field': 'LABEL',
            'text-offset': [0, -1],
          },
          paint: {
            'text-color': ['get', 'color'],
          }
        }]
      }

Which looks like this due to line merges (the labels' color should match the line color):

[louwers]

Does this help?

Screen.Recording.2025-09-03.at.22.17.39.mov

Looks like the same behavior.

[HarelM]

Yes! Thanks for the info.

[HarelM]

It might be a good idea to talk about it in the next monthly meeting which is less than a week from now. @madoci will you be able to join?