icon-overlap with cooperative mode

[lhapaipai]

Hi every one,
I'm a bit confused about icon-overlap: cooperative option.

After reading the doc: https://maplibre.org/maplibre-style-spec/layers/#icon-overlap

cooperative: If the icon collides with another previously drawn symbol, the overlap mode for that symbol is checked. If the previous symbol was placed using never overlap mode, the new icon is hidden. If the previous symbol was placed using always or cooperative overlap mode, the new icon is visible.

But when I try in my own playground, I don't find this behavior.

example : https://jsbin.com/qurafam/edit?html,js,output

• the previous symbol (A) was placed using never overlap mode.
• the current symbol (B) was placed using cooperative overlap mode.
• in the documentation the new icon (B) should be hidden but for me the new icon (B) is visible

documentation reference : #347

Do you have any feedback on this?
thank you

[HarelM]

This looks like a bug in the implementation from a very shallow look.
Looking at the linked PR it seems that this "simple" case is not there as far as I can tell.
You can check the images and the style.json in the PR and see what tests were added to cover this change.
@drwestco do you know if the case described here was ever tested?

[drwestco]

It's been a long time since I looked at this, but aren't layers placed front to back, so last layer in the JSON gets placed first?

…

On Sun, Jun 15, 2025, 1:15 PM Harel M ***@***.***> wrote: This looks like a bug in the implementation from a very shallow look. Looking at the linked PR it seems that this "simple" case is not there as far as I can tell. You can check the images and the style.json in the PR and see what tests were added to cover this change. @drwestco <https://github.com/drwestco> do you know if the case described here was ever tested? — Reply to this email directly, view it on GitHub <#6022 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFVM5WTH76ZDHPUTGYOJ5D3DXH7DAVCNFSM6AAAAAB7LB3QICVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBXGY2DMOA> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[HarelM]

I thought that might be it, but the B icon seems to look on top of A if both are placed, so I think the order of the layers is from top to bottom...

[drwestco]

First layer (A) in JSON is on bottom. Last layer (B) is placed first. So B is considered first and placed. Then A is considered, is seen to overlap B and is rejected. Or am I misremembering? There's an integration test that uses a mix of cooperative and never modes. It may not be working properly though. I'd expect at least one of the icons marked as never to show up.

…

On Sun, Jun 15, 2025, 1:50 PM Harel M ***@***.***> wrote: I thought that might be it, but the B icon seems to look on top of A if both are placed, so I think the order of the layers is from top to bottom... — Reply to this email directly, view it on GitHub <#6022 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFVM5WCEYQTYQAV6OAJW3D3DXMBNAVCNFSM6AAAAAB7LB3QICVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGNBXGY3DEMY> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[lhapaipai]

Hi and thank you for your answers !

First layer (A in red) in JSON is defined with icon-overlap: never
Second layer (B in blue) in JSON is defined with icon-overlap: cooperative.

from what I understood

• First : A is considered.
• Second : B is considered. as it is in cooperative mode A is considered again and as it was placed with never. B should be rejected.
• finally we should therefore only see A in red

[drwestco]

It's confusing, but placement is done front-to-back (B, then A). Rendering is then done back-to-front (A, then B). The last layer in the JSON (B, here) is in front, and thus has priority for placement.

You get the same behavior using the old icon-allow-overlap property. Indeed, "icon-allow-overlap": true maps to "icon-overlap": "always", and "icon-allow-overlap": false maps to "icon-overlap": never.

So I believe the example is working as expected.

[HarelM]

So confusing.
I hope that since it's that confusing I won't forget it... :-)

[lhapaipai]

Hum, thank you @drwestco for your feedback.

Can you confirm, if I've understood this correctl?
The cooperative mode is checked during the placement step (front-to-back). so when you say:

If the previous symbol was placed using never overlap mode, the new icon is hidden.

that means the previous symbol is on top. my example wasn't appropriate, I should have used the cooperative option for the back layer.

• the previous symbol (A in the front) was placed using never overlap mode.
• the current symbol (B in the back) was placed using cooperative overlap mode.
• the new icon (B) is hidden

🎉🎉