Add a mesh to image source to solve edge cases.

[HarelM]

Launch Checklist

This refferes to an issue reported here with the latest fix to image source:
mapmelabs/maplibregl-area-transform#13

I've let AI try and solve this, so I'm not sure I fully understand the solution here...
Would be great to have someone else look at this.
@i4innovationnet @igalgh

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Link to related issues.
• Include before/after visuals or gifs if this PR includes visual changes. - see render test and linked PR.
• Write tests for all new functionality.
• Document any changes to public APIs.
• If you changed code in a file that has a benchmark file next to it (*.bench.ts), post before/after results of npm run bench (the compare workflow is in test/bench/README.md).
• Add an entry to CHANGELOG.md under the ## main section.
• Confirm you have read our AI policy here.

Generated-By: Claude code Opus 5.0

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.92%. Comparing base (ef90e66) to head (72713a6).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8172   +/-   ##
=======================================
  Coverage   93.92%   93.92%           
=======================================
  Files         290      290           
  Lines       24916    24920    +4     
  Branches     6575     6575           
=======================================
+ Hits        23402    23407    +5     
+ Misses       1514     1513    -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.

[CommanderStorm]

Lgtm

[eminmapme]

Hi @HarelM,
With this PR, extreme foreshortening uses the mesh and looks correct, but moderate free-transform quads still use the projective path and appear to rotate/spin around the diagonal while dragging corners. Only after the ratio crosses the threshold (> 4) does the stretch look right.
It would be great if the image could stretch with the quad throughout the drag, without that intermediate spin.

More context + video: https://github.com/mapmelabs/mapme-main/pull/3407#issuecomment-5309946759

[HarelM]

@eminmapme can you post the video here? mapme-main is not a public repo...

[eminmapme]

@eminmapme can you post the video here? mapme-main is not a public repo...

@HarelM Free-transform uses native ImageSource. On moderate quads, MapLibre’s projective warp can make the image appear to spin around the diagonal; extreme foreshortening is better after this pr, but the intermediate spin can still happen until their mesh threshold is hit.

QA editor/map: https://app-qa1.test.mapme.com/d7fccad0-0122-4fc5-affc-bedf6142d51a/story/68f5b203-0962-460e-ba72-ea77ad23fec3/geofeature/17aa99da-047f-4d98-a31e-9d72783a361f?expand=none

Video: https://drive.google.com/file/d/1miElPTwE5jGDVenhVsxMRrrPgHo9pvXg/view?usp=sharing

[HarelM]

@eminmapme thanks for the video! I'll look into it.

[HarelM]

I've looked into what it would take to change the entire non-Parallelogram case to use bilinear with quads and I've noticed the the trapezoid case looks weird (left current main, right after making non parallelogram use the mesh):

I'll continue to think about it, I'm not sure there's a good solution to this to be honest...

[HarelM]

@eminmapme can you check if the latest version pushed here is better?
You should be able to download the dist folder from here (scroll down to the bottom of the summary):
https://github.com/maplibre/maplibre-gl-js/actions/runs/32018613096?pr=8172

[eminmapme]

@eminmapme can you check if the latest version pushed here is better? You should be able to download the dist folder from here (scroll down to the bottom of the summary): https://github.com/maplibre/maplibre-gl-js/actions/runs/32018613096?pr=8172

@HarelM It looks much better to me, thanks!

Video: https://drive.google.com/file/d/1CBwI_J_pxXconmiWeBGL5L9g7_PSJsaq/view?usp=sharing

[larsmaxfield]

Video: https://drive.google.com/file/d/1CBwI_J_pxXconmiWeBGL5L9g7_PSJsaq/view?usp=sharing

I don't think we should combine the perspective and mesh approaches. Or, at the very least, I think there should be option to set which approach is used:

1. hybrid (this PR)
2. perspective (original PR)
3. mesh

We use GL JS for viewing image data of paintings like high-resolution scans, photographs, and X-rays. Those images are not usually aligned, meaning our users need to create prealigned copies to accurately compare them. The perspective transform is the most common and effective way to (at least generally) align two images. We typically employ OpenCV's warpPerspective function for this.

The perspective transform in the original PR is very exciting for us because we can skip prealignment; we can use the original images directly and align them on-the-fly based on the corner control points.

My concern with a hybrid solution is that I as a developer can't guarantee a perspective transform will be used, and that we're under the mercy of the logic that triggers perspective versus mesh. If I could set the mode to perspective and guarantee that approach, it would make my life easier.

[HarelM]

I'm not sure this is worth the extra style spec complexity tour.
@larsmaxfield if you can solve the issue that was reported by @eminmapme in a different way that still uses perspective projection that could be a way forward, by currently the problem highlighted by @eminmapme requires a fix I believe.

[larsmaxfield]

I don't have time to solve this unfortunately. Adding the spec option would be my wish. But I agree it complicates things.

Let me downgrade my concern to this: As a developer, I would like us to state the criteria by which the projection is selected. Perhaps a comment or docs entry along the lines of:

... An image source is projected using a perspective transform when the four coordinates do not form a parallelogram. If three coordinates approach collinearity (for example, when the four coordinates approach the shape of a triangle), the perspective transform is blended with a mesh solution. The mesh is defined by [X]. The blend is triggered by [Y].

(GitHub isn't loading the PR changes so I can't see whether this is already in the docs.)

As long as I can accurately predict when the perspective transform is used, I'm OK with this PR.

[HarelM]

This is not well documented. There's a threshold, but it uses blending to make the transition smooth.
Since mapme requires both options I'll think of a way to either support this or encourage plugin writing for the not supported configuration.
I'll sleep on it...