Skip to content

feat: add rasterPixelAlignment map option - #8206

Open
burmatov-step wants to merge 2 commits into
maplibre:mainfrom
burmatov-step:feat/raster-pixel-alignment-option
Open

feat: add rasterPixelAlignment map option#8206
burmatov-step wants to merge 2 commits into
maplibre:mainfrom
burmatov-step:feat/raster-pixel-alignment-option

Conversation

@burmatov-step

@burmatov-step burmatov-step commented Aug 21, 2026

Copy link
Copy Markdown
video_maplibre.mp4

What I ran into. In my own projects I use raster tiles as the basemap, with markers and vector layers (lines) on top. Every time the camera stops moving — end of a pan, end of a flyTo, end of drag inertia — the basemap and the overlays jump relative to each other by a fraction of a pixel. What you see is the markers and the lines twitching against the map. Short slow drags show it best; inertia makes it happen twice per gesture.

Why it happens. Raster layers are drawn with a pixel-grid-aligned projection matrix, but only while the map is idle. Every other layer type always uses the unaligned one.

What this PR does. Adds a rasterPixelAlignment map option, default true, which is exactly today's behavior. Set it to false and raster, hillshade and color-relief layers never snap to the pixel grid, so nothing shifts relative to anything else.

  • No backports from Mapbox projects — this is original code; mapbox-gl-js#7426 is referenced only through this repo's CHANGELOG.
  • Read the AI policy. Disclosure: I used Claude Opus 5 (claude-opus-5[1m]) via Claude Code to find the code path and draft the tests. I verified all of it and ran the unit, build and render suites locally.

@HarelM

HarelM commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

Thanks for taking the time to open this PR.
Can you please share what the PR solves?
From the ton of words the AI generated it's hard to really understand what issue this PR is aiming to solve...
Better yet, rewrite the initial PR comment to be humanly readable and preferably a lot shorter or at least to the point...

@codecov

codecov Bot commented Aug 21, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.94%. Comparing base (3a0a4f7) to head (f251427).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #8206      +/-   ##
==========================================
- Coverage   93.94%   93.94%   -0.01%     
==========================================
  Files         290      290              
  Lines       24917    24922       +5     
  Branches     6576     6578       +2     
==========================================
+ Hits        23408    23412       +4     
- Misses       1509     1510       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@burmatov-step

Copy link
Copy Markdown
Author

Sorry, that was too much text. I've rewritten the description.

@HarelM

HarelM commented Aug 21, 2026

Copy link
Copy Markdown
Collaborator

Can you share a video?
Can this be considered a bug? Why not avoid this completely instead of adding a flag to allow switching this behavior?

@burmatov-step

Copy link
Copy Markdown
Author

Video attached above.

Yes, I'd call it a bug. The snapping is intentional; the fact that it applies to one family of
layers and not the others isn't, and that's what produces the jump.

I picked the flag because it's the one version that provably can't regress anyone — the default
is untouched.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants