feat: allow polylines & polygons to cross world boundary

[monsieurtanuki]

What

• This PR deals with polylines and polygons (with or without holes) across longitudes +-180 (cf. [BUG] Crossing W/E Extremity With Polyline Results In Unexpected Lines #1338)
• The main issue was that longitudes -179 and 179 were projected in opposite sides of the world, although they are geographically nearby.
• The solution is to build incrementally the list of projected points: if two consecutive projected points are obviously too far away (more than half a world away), we add/remove one world width to the latter point.
• Doing so, we avoid jumping around -180 and +180, and we ensure the continuity among the points.
• The PR doesn't deal with the "teleportation" effect. This will be done in another PR, once we're confident with that "add/remove a world width" strategy.

Screenshots

Polyline: before / after

Polygon with hole: before / after

Impacted files

• crs.dart: new methods getHalfWorldWidth and projectList
• painter.dart: refactored using pre-computed List<Double>
• polygon.dart: added an example around longitude 180
• polyline.dart: added an example around longitude 180
• polyline_layer.dart: we don't cull polylines that go beyond longitude 180
• projected_polygon.dart: using new method Projection.projectList
• projected_polyline.dart: using new method Projection.projectList

[josxha]

Thanks for the pull request @monsieurtanuki! I did some quick testing and your added examples work like intended (thanks for adding them).

Some additional thoughts:
The main use case of line wrapping are paths that cross the -180/180 longitude for example when we want to display flights. We need to figure out a solution when the user follows a polyline or polygon accross the world border. Currently the line suddenly disapears. This, of course, is not in scope for this this pull request. (:

line.wrapping.mp4

[monsieurtanuki]

Some additional thoughts: The main use case of line wrapping are paths that cross the -180/180 longitude for example when we want to display flights. We need to figure out a solution when the user follows a polyline or polygon accross the world border. Currently the line suddenly disapears. This, of course, is not in scope for this this pull request. (:

Oh it's a bug then! Probably related to the "teleportation" issue.
I'll have a look at it, and I may fix that in the current PR.
I keep you posted.

[josxha]

Oh it's a bug then! Probably related to the "teleportation" issue.
I'll have a look at it, and I may fix that in the current PR.

I actually don't think it's an bug. The line just moves to the new world that comes into center. So the line is still active but basically on the other side of the world. If you plan to look into this as well how it can get improved that's awesome of couse. (:

[monsieurtanuki]

@josxha Your description is correct: it's the "teleportation" issue (I can see a unique polyline jumping from world to world on the same zoom 0 map) but when the zoom is high - the "other" world is not visible.

I still think it's a bug, probably not a new bug, but a fair user expectation is to see at least one polyline.

Working on it. The current PR is relatively small (7 files changed), so I'll see how review-able it would become when including that bug fix.

[monsieurtanuki]

@josxha Fixed! One visible copy of the polyline, with a small or a large zoom.

[JaffaKetchup]

LGTM in general! Some documentation about what the whole 'half world width' stuff is about would be nice. I'll leave to @josxha to give final review :) Thanks!

[JaffaKetchup]

Just a thought, what happens with CircleMarkers?

[monsieurtanuki]

Just a thought, what happens with CircleMarkers?

Nothing.
This PR is specific to polylines (make them connect beyond the limits of the world, and make them visible if possible).
Unfortunately, all the "many worlds/teleportation" code improvements have to be done on each "geo widget" (marker, polygon, polyline, circlemarker, ...).
We may refactor elegantly at the end, but I wouldn't count on that. And we're not at the end anyway.

[monsieurtanuki]

@JaffaKetchup @josxha I've just pushed some changes that make the code (somehow) more readable.
In particular, I've switched to getWorldWidth (no more "half") and I've added comments:

  /// Returns the width of the world in geometry coordinates.
  ///
  /// Is used at least in 2 cases:
  /// * my polyline crosses longitude 180, and I somehow need to "add a world"
  /// to the coordinates in order to display a continuous polyline
  /// * when my map scrolls around longitude 180 and I have a marker in this
  /// area, the marker may be projected a world away, depending on the map being
  /// centered either in the 179 or the -179 part - again, we can "add a world"
  double getWorldWidth() {
    final (x0, _) = projectXY(const LatLng(0, 0));
    final (x180, _) = projectXY(const LatLng(0, 180));
    return 2 * (x0 > x180 ? x0 - x180 : x180 - x0);
  }

[monsieurtanuki]

The review should probably be put on hold until the fix for #1976 is coded (by me) (like, today), reviewed and merged.

Now back to polygons and polylines in multi-worlds!

[monsieurtanuki]

Ping

[JaffaKetchup]

Oops, apologies, thought you needed more time to work on this. I'll review now.

[JaffaKetchup]

LGTM, and some nice removal of duplications as well :) One question, then ready to merge.

---

This also appears on master, but is caused by the infinite scroll feature. Not sure if its a bug exactly? Using a cameraConstraint with the entire world will cause the map to stick against the edges during a fling animation, but will jump once the fling is complete. A drag does not work at all (causes sticking).

cameraConstraint: CameraConstraint.contain(
	bounds: LatLngBounds(
		const LatLng(-90, -180),
        const LatLng(90, 180),
    ),
),

Recording.2024-12-02.214029.mp4

[mootw]

looks good pending the one dependency comment!

[monsieurtanuki]

@JaffaKetchup I'm not an expert on cameraConstraint and fling effect, but I think the possible bug you're mentioning goes beyond this PR and would deserve its own issue.
@mootw Removed the useless new explicit package dependency.

[monsieurtanuki]

Thank you @JaffaKetchup @mootw @josxha for your reviews!

[JaffaKetchup]

Hey @monsieurtanuki, just plotting our next release schedule. Do you think you'll be able to work on the teleporting issue any time soon? Of course, no problem at all if not! Thanks for all your hard work so far :)

[monsieurtanuki]

@JaffaKetchup I guess I should be able to fix the teleporting effect within a month - including reviews and feedbacks.

Keep in mind though that:

• the teleporting is to be coded specifically for each widget (marker, circlemarker, polygon and polyline) - several potential sources of bugs
• [BUG] unbounded horizontal scroll breaks most tile grids #1976 (reported by @arneke) about the multiworld feature having non webmercator maps not working anymore
• the teleporting goes a bit beyond the "multiworld" and "pacific polygons" issues, adding a "low zoom" flavor

Imagining an arbitrary "let's publish a release before 2025" goal, I believe it would be safer not to jeopardize the next release, possibly to test again, and to keep the teleporting for afterwards.