Automatically convert xlim/ylim to Web Mercator when tiles=True #1685

Copilot · 2025-10-10T16:10:11Z

Tested:
First is with xlim and ylim, 2nd is xlim, 3rd is ylim, 4th is none specified

Description

This PR implements automatic conversion of xlim and ylim parameters to Web Mercator (EPSG:3857) when tiles=True is used without geo=True, making the behavior consistent with how data coordinates are automatically converted.

Problem

Previously, when using tiles=True with geographic data (lat/lon coordinates), hvPlot would automatically convert the data coordinates to Web Mercator, but xlim and ylim parameters were not converted. This meant users had to manually calculate Web Mercator values for axis limits, which was inconvenient and error-prone:

# Before: Users had to manually convert xlim/ylim
df = pd.DataFrame({'lon': [-120, -100, -80], 'lat': [30, 35, 40]})
# xlim/ylim in lat/lon would not match the converted data coordinates
df.hvplot.points('lon', 'lat', tiles=True, xlim=(-130, -70), ylim=(25, 45))  # Wrong scale!

Solution

Now xlim and ylim are automatically converted to Web Mercator when appropriate, just like the data coordinates:

# After: Just use lat/lon coordinates - hvPlot handles the conversion automatically
df = pd.DataFrame({'lon': [-120, -100, -80], 'lat': [30, 35, 40]})
df.hvplot.points('lon', 'lat', tiles=True, xlim=(-130, -70), ylim=(25, 45))  # Works perfectly!

Implementation Details

The conversion logic:

Checks data bounds first: Before converting xlim/ylim, the code checks if the data coordinates are within typical lat/lon bounds (-180 <= lon <= 360, -90 <= lat <= 90). This prevents false positives where small numerical values might be within those ranges but represent non-geographic data.
Converts only when appropriate: Conversion happens only when:
- tiles=True is set
- geo=False (not using explicit geo mode)
- projection is not False (automatic projection not disabled)
- Data coordinates are within lat/lon bounds
- xlim/ylim values are within lat/lon bounds
Uses proper projection math:
- Easting (x) depends only on longitude: easting = longitude × origin_shift / 180
- Northing (y) depends only on latitude: northing = log(tan((90 + latitude) × π / 360)) × origin_shift / π

Examples

Geographic data (automatic conversion):

# San Francisco area
sf_data = pd.DataFrame({
    'lon': [-122.45, -122.42, -122.40],
    'lat': [37.75, 37.77, 37.79]
})
plot = sf_data.hvplot.points('lon', 'lat', tiles=True, 
                             xlim=(-122.5, -122.3), 
                             ylim=(37.7, 37.85))
# xlim and ylim are automatically converted to Web Mercator

Non-geographic data (no conversion):

# Scientific measurements
data = pd.DataFrame({'x': [1000, 2000, 3000], 'y': [500, 600, 700]})
plot = data.hvplot.points('x', 'y', tiles=True, 
                          xlim=(900, 3100), 
                          ylim=(400, 800))
# xlim and ylim remain unchanged (data is outside lat/lon bounds)

Testing

Added comprehensive tests covering:

✅ Conversion with geographic data and tiles
✅ No conversion without tiles
✅ No conversion when data is outside lat/lon bounds
✅ Edge cases: negative/positive longitudes, equatorial/polar latitudes, boundary values
✅ Partial specification (only xlim or only ylim)
✅ projection=False disables conversion

All tests pass and the implementation is fully backwards compatible with existing behavior.

Closes

Fixes the issue described in the problem statement where xlim/ylim were not automatically converted to Web Mercator when using tiles with lat/lon data.

Original prompt

This section details on the original issue you should resolve

<issue_title>Automatically convert xlim/ylim to Web Mercator when possible</issue_title>
<issue_description>We recently added automatic projection of lat/lon coordinates to Web Mercator when tiles=True so users can easily plot geodatasets in these classic coordinates (e.g. GPS). We should also automatically convert xlim and ylim.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1617

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: ahuang11 <[email protected]>

maximlt · 2025-10-14T07:27:08Z

I forgot a comment. Could you please document this feature? I think a simple mention in the xlim/ylim section would be fine, and a real example in the tiles section. I don't think the docstring needs to be updated.

ahuang11 · 2025-10-14T15:09:32Z

Okay added docs

hvplot/util.py

maximlt · 2025-10-14T05:24:22Z

hvplot/util.py

    ) from Exception(*errors)


+def is_within_latlon_bounds(data, x, y):


Can you please make these functions in util.py private by prepending their name with an underscore? That's the pattern I have adopted for new functions.

Hmm, I'm on the fence about making them private. Maybe is_within_latlon_bounds but others I can see people calling it, e.g. from holoviews.util.transform import lon_lat_to_easting_northing. I typically reserve underscores for private methods, less utils, or else it should be a private method?

I've made them private in my last commits. I've got way too much burnt by all the public-but-not-really utilities exposed in Param that need long deprecation cycles to be touched even for the smallest change. If we have a very useful utility that makes sense for hvPlot to expose, then it's easy to go from private to public, the other way is a chore.

maximlt · 2025-10-14T05:26:08Z

hvplot/util.py

+        max_x = np.max(data[x])
+        min_y = np.min(data[y])
+        max_y = np.max(data[y])
+    except (KeyError, ValueError, TypeError):


What cases do these exceptions cover?

I think the goal was for it to gracefully fail so this auto-conversion doesn't block the user for anything unexpected--now I simply just use Exception and warn on exception.

hvplot/util.py

hvplot/tests/testgeowithoutgv.py

maximlt · 2025-10-15T11:32:27Z

doc/gallery/geospatial/map_overlay.ipynb

+   "id": "8c428430",
+   "metadata": {},
+   "source": [
+    "If `xlim` and `ylim` are in `lat`/`lon` coordinates, they will be automatically transformed to Web Mercator coordinates."


Not sure we should document things this way in the gallery. Which is why I suggested doing it in the tiles example section, as this behavior is only enabled when tiles is enabled. For this example, I simply suggest updating the original snippet with xlim=..., ylim=....

Thanks for clarifying, that makes sense. I wasn’t really sure what “a real example in the tiles section” referred to since I haven't worked in hvplot docs for a while, so just a heads up a quick link to the hvPlot docs section would be helpful for future comments / contributors! 🙇🏻

Good point! 👍

doc/ref/plotting_options/axis.ipynb

maximlt · 2025-10-15T11:36:15Z

@ahuang11 sorry I thought I submitted my review yesterday, but no!

doc/ref/plotting_options/axis.ipynb

ahuang11 · 2025-11-23T10:55:05Z

hvplot/util.py



-def _convert_latlon_to_mercator(lon: np.ndarray, lat: np.ndarray):
+def _convert_latlon_to_mercator(lon: np.ndarray, lat: np.ndarray, lon_180: bool = True):


I think it would read better if this is use_lon_180 or similar.

Thanks, done in 43d75a7

maximlt · 2025-11-24T16:48:08Z

The main changes I've pushed are in c76976b where None handling is added (None meaning no lower or upper bound) and where longitude edge cases are better supported (e.g. (170, 190), (170, -10)).

Initial plan

289c5c1

Copilot AI assigned Copilot and ahuang11 Oct 10, 2025

Copilot started work on behalf of ahuang11 October 10, 2025 16:10 View session

Copilot AI and others added 3 commits October 10, 2025 16:21

Add automatic xlim/ylim conversion to Web Mercator when tiles=True

be6a030

Co-authored-by: ahuang11 <[email protected]>

Add comprehensive tests for xlim/ylim conversion scenarios

faf4428

Co-authored-by: ahuang11 <[email protected]>

Fix xlim/ylim conversion to check data bounds first

d1d6e6b

Co-authored-by: ahuang11 <[email protected]>

Copilot AI changed the title ~~[WIP] Add automatic conversion of xlim and ylim to Web Mercator~~ Automatically convert xlim/ylim to Web Mercator when tiles=True Oct 10, 2025

Copilot AI requested a review from ahuang11 October 10, 2025 16:37

Copilot finished work on behalf of ahuang11 October 10, 2025 16:37

ahuang11 added 4 commits October 10, 2025 10:46

clean up and tests

f55a2e4

clean up and fixes

3db249d

remove dup check

5f503b5

reduce call

de2de9d

ahuang11 requested a review from maximlt October 10, 2025 18:14

ahuang11 marked this pull request as ready for review October 10, 2025 18:14

Add doc

5f4f4a8

maximlt reviewed Oct 15, 2025

View reviewed changes

Azaya89 reviewed Oct 16, 2025

View reviewed changes

doc/ref/plotting_options/axis.ipynb Outdated Show resolved Hide resolved

ahuang11 and others added 3 commits October 22, 2025 16:19

address comments

51026d6

add tests and tweak

fa13680

Merge branch 'main' into copilot/automatically-convert-xlim-ylim

03d6021

ahuang11 requested review from Azaya89 and maximlt October 22, 2025 23:29

maximlt added 3 commits November 9, 2025 21:34

make the util functions private

c728d09

add util to generate unique names

2d3c52a

small refactor and use nan min/max

9d497b7

better none handling and lon edge cases

c76976b

ahuang11 reviewed Nov 23, 2025

View reviewed changes

rename based on suggestion

43d75a7

maximlt approved these changes Nov 24, 2025

View reviewed changes

maximlt merged commit 61ffb6c into main Nov 24, 2025
14 checks passed

maximlt deleted the copilot/automatically-convert-xlim-ylim branch November 24, 2025 16:48

		) from Exception(*errors)


		def is_within_latlon_bounds(data, x, y):



		def _convert_latlon_to_mercator(lon: np.ndarray, lat: np.ndarray):
		def _convert_latlon_to_mercator(lon: np.ndarray, lat: np.ndarray, lon_180: bool = True):

Uh oh!

Automatically convert xlim/ylim to Web Mercator when tiles=True #1685

Automatically convert xlim/ylim to Web Mercator when tiles=True #1685

Uh oh!

Conversation

Copilot AI commented Oct 10, 2025 • edited by ahuang11 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Problem

Solution

Implementation Details

Examples

Testing

Closes

Comments on the Issue (you are @copilot in this section)

Uh oh!

maximlt commented Oct 14, 2025

Uh oh!

ahuang11 commented Oct 14, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ahuang11 Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

maximlt commented Oct 15, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

maximlt commented Nov 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Oct 10, 2025 •

edited by ahuang11

Loading

ahuang11 Oct 22, 2025 •

edited

Loading