[Feature] Allow "underzooming" to show entire map on non-square viewports when renderWorldCopies=false

[larsmaxfield]

Currently if renderWorldCopies = false and the viewport is not square, the map does not allow the user to zoom out enough to show the entire map.

You can see this in the render world copies example by fully zooming out and toggling the option:

Zooming out is limited to when the map's bounds are reached on the left and right sides (with a wide viewport) or the top and bottom sides (with a tall viewport). ~I assume this is the intended behavior.~ Edit: This appears to not be the intended behavior; see comment below.

However, this can be abrupt for users who expect to be able to see the entire map when they attempt to fully zoom out the map.

I would like an option to allow the map to be "underzoomed" until the entire map is visible when renderWorldCopies = false, whereby the background area outside the map is transparent or assigned a color:

Perhaps the option could be something like showEntireMap or allowUnderZoom, though I'm not familiar with best practices in naming and implementation.

(One could think of this as (un)constraining the zoom and pan of the map, which the OpenSeadragon image viewer does nicely here: https://openseadragon.github.io/examples/ui-zoom-and-pan/.)

[larsmaxfield]

The currently restricted zoom-out behavior is not intended if I understand the renderWorldCopies docs correctly:

When the map is zoomed out far enough that a single representation of the world does not fill the map's entire container, there will be blank space beyond 180 and -180 degrees longitude.

[sbachinin]

Restricted behaviour is intended, despite this quote. Making it non-restricted looked a bit problematic. Also I assumed that viewing the whole globe is an unlikely demand. Could you please describe the use case where it is necessary?

[larsmaxfield]

I was able to implement this by modifying a few lines of getConstrained() in transform.ts. Works nice on a 2D map:

(Edit: See below comment for a temporary workaround for 3D.) However, on a 3D terrain map, it locks up when under-zoomed below 0 or when pitching at zoom levels below 2, sometimes throwing an 'outside of bounds' error:

tile_id.ts:21  Uncaught Error: x=0, y=2, z=0.27 outside of bounds. 0<=x<1.2058078276907604, 0<=y<1.2058078276907604 0<=z<=25 
    at CanonicalTileID (tile_id.ts:21:19)
    at new OverscaledTileID (tile_id.ts:96:26)
    at Terrain._getOverscaledTileIDFromLngLatZoom (terrain.ts:455:24)
    at Terrain.getElevationForLngLatZoom (terrain.ts:187:53)
    at Map._elevateCameraIfInsideTerrain (camera.ts:1122:42)
    at camera.ts:1144:39
    at Map._applyUpdatedTransform (camera.ts:1161:17)
    at HandlerManager._fireEvents (handler_manager.ts:594:23)
    at HandlerManager.stop (handler_manager.ts:309:14)
    at HandlerManager.handleEvent (handler_manager.ts:359:18)

[larsmaxfield]

Restricted behaviour is intended, despite this quote. Making it non-restricted looked a bit problematic. Also I assumed that viewing the whole globe is an unlikely demand. Could you please describe the use case where it is necessary?

Hi @sbachinin, the general use case is for when users wish to see the entire map no matter the aspect ratio of the viewport. For me specifically, I am implementing MapLibre for visualizing scans of paintings as single maps, and users have requested the ability to "fully zoom out" where they expect to see the entire painting.

Current behavior with zooming out limited:

Desired behavior with under-zooming allowed:

[larsmaxfield]

Disabling the bounds error in the constructor for CanonicalTileID (tile_id.ts) allows 3D to work with under-zooming:

[HarelM]

I would say that for paintings you can have them shown in a larger zoom, can't you? i.e. show full painting in zoom 3, or even 7 would solve this, wouldn't it?

[larsmaxfield]

@HarelM ah, do you mean by padding the original images with a wide border so that the generated tilesets have plenty of empty space around the actual scan?

[sbachinin]

Not sure if it's the same as what Harel means but - if you don't stretch the paintings to the whole globe but render them somewhat smaller in the center of the globe, it must be better in every way. E.g., the paintings' aspect ratio can be any. I honestly don't know how to implement this but it must be doable

[larsmaxfield]

I use pyvips dzsave which tiles the painting by scaling the original image by half until it fits within a single tile, which then becomes the lowest zoom 0/0/0.jpg tile. The z-depth then depends on how many times the image was halved, or rather how large the original image was.

I hadn't yet considered rendering it smaller than the map. Perhaps because of how pyvips does the tiling. For me it makes more sense that the painting always fills the 0/0/0 tile. I don't need to keep track of minimum zoom or bounds.

I have considered centering the painting, but for coordinate transformation that adds one more step (an XY offset). Having (0,0) as the origin for everything is easier.

[HarelM]

You can use image source instead of tiling I believe.

[larsmaxfield]

The scans are of gigapixel magnitude — 100k × 100k px — so we rely on tiling.

[sbachinin]

In my opinion, the idea of "underzooming" (viewing the whole globe on a single-globe map) totally makes sense. It feels better to be able to zoom out enough to view the whole thing. So if this can be implemented without much complexity, why not? I also think that this can be the default behavior of a single-globe map, that is, I wouldn't introduce this new option because it looks a little odd. I don't think that anyone is going to suffer from having blank margins around the globe.

As for the complexity, I doubt that you can make it work well with little code. E.g., I think it should behave like this example from OpenSeadragon. That is, panning should still have some constraints (it must be impossible to outpan the map from the viewport completely). This is perhaps not a trivial task. Also there is a lot of stuff that (potentially) can be broken by this change, like markers and popups.

[larsmaxfield]

Good points. I agree that this should become the new default behavior for single-globe maps.

I'll give it a try and update here when I've got something working.

[larsmaxfield]

~I've proposed a solution in PR #4612.~

I've rescinded that solution as I've found a more intuitive design with two user settings — one for underzooming and one for overpanning. I'll explain here once I have a demo.