MapView.java
/*
* *************************************************************************************************************************************************************
*
* MapView: a JavaFX map renderer for tile-based servers
* http://tidalwave.it/projects/mapview
*
* Copyright (C) 2024 - 2025 by Tidalwave s.a.s. (http://tidalwave.it)
*
* *************************************************************************************************************************************************************
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
* CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
*
* *************************************************************************************************************************************************************
*
* git clone https://bitbucket.org/tidalwave/mapview-src
* git clone https://github.com/tidalwave-it/mapview-src
*
* *************************************************************************************************************************************************************
*/
package it.tidalwave.mapviewer.javafx;
import jakarta.annotation.Nonnull;
import java.util.Collection;
import java.util.function.Consumer;
import java.nio.file.Path;
import javafx.animation.Interpolatable;
import javafx.animation.Interpolator;
import javafx.animation.KeyFrame;
import javafx.animation.KeyValue;
import javafx.animation.Timeline;
import javafx.beans.property.DoubleProperty;
import javafx.beans.property.ObjectProperty;
import javafx.beans.property.ReadOnlyDoubleProperty;
import javafx.beans.property.SimpleDoubleProperty;
import javafx.beans.property.SimpleObjectProperty;
import javafx.collections.ObservableList;
import javafx.scene.Node;
import javafx.scene.input.MouseEvent;
import javafx.scene.input.ScrollEvent;
import javafx.scene.input.ZoomEvent;
import javafx.scene.layout.AnchorPane;
import javafx.scene.layout.Region;
import javafx.util.Duration;
import javafx.application.Platform;
import edu.umd.cs.findbugs.annotations.SuppressFBWarnings;
import it.tidalwave.mapviewer.MapArea;
import it.tidalwave.mapviewer.MapCoordinates;
import it.tidalwave.mapviewer.MapViewPoint;
import it.tidalwave.mapviewer.OpenStreetMapTileSource;
import it.tidalwave.mapviewer.TileSource;
import it.tidalwave.mapviewer.impl.MapViewModel;
import it.tidalwave.mapviewer.impl.RangeLimitedDoubleProperty;
import it.tidalwave.mapviewer.javafx.impl.TileCache;
import it.tidalwave.mapviewer.javafx.impl.TileGrid;
import it.tidalwave.mapviewer.javafx.impl.Translation;
import lombok.Getter;
import lombok.RequiredArgsConstructor;
import lombok.Setter;
import lombok.With;
import lombok.experimental.Accessors;
import lombok.extern.slf4j.Slf4j;
import static java.lang.Double.doubleToLongBits;
import static javafx.util.Duration.ZERO;
/***************************************************************************************************************************************************************
*
* A JavaFX control capable to render a map based on tiles. It must be associated to a {@link TileSource} that provides the tile bitmaps; two instances are
* provided, {@link OpenStreetMapTileSource} and {@link it.tidalwave.mapviewer.OpenTopoMapTileSource}. Further sources can be easily implemented by overriding
* {@link it.tidalwave.mapviewer.spi.TileSourceSupport}.
* The basic properties of a {@code MapView} are:
*
* <ul>
* <li>{@link #tileSourceProperty()}: the tile source (that can be changed during the life of {@code MapView});</li>
* <li>{@link #centerProperty()}: the coordinates that are rendered at the center of the screen;</li>
* <li>{@link #zoomProperty()}: the detail level for the map, going from 1 (the lowest) to a value depending on the tile source.</li>
* </ul>
*
* Other properties are:
*
* <ul>
* <li>{@link #minZoomProperty()} (read only): the minimum zoom level allowed;</li>
* <li>{@link #maxZoomProperty()} (read only): the maximum zoom level allowed;</li>
* <li>{@link #coordinatesUnderMouseProperty()} (read only): the coordinates corresponding to the point where the mouse is;</li>
* <li>{@link #areaProperty()} (read only): the rectangular area delimited by north, east, south, west coordinates that is currently rendered.</li>
* </ul>
*
* The method {@link #fitArea(MapArea)} can be used to adapt rendering parameters so that the given area is rendered; this is useful e.g. when one wants to
* render a GPS track.
*
* Maps can be scrolled by dragging and re-centered by double-clicking on a point (use {@link #setRecenterOnDoubleClick(boolean)} to enable this behaviour).
*
* It is possible to add and remove overlays that move in solid with the map:
*
* <ul>
* <li>{@link #addOverlay(String, Consumer)}</li>
* <li>{@link #removeOverlay(String)}</li>
* <li>{@link #removeAllOverlays()}</li>
* </ul>
*
* @see OpenStreetMapTileSource
* @see it.tidalwave.mapviewer.OpenTopoMapTileSource
*
* @author Fabrizio Giudici
*
**************************************************************************************************************************************************************/
@Slf4j
public class MapView extends Region
{
private static final int DEFAULT_TILE_POOL_SIZE = 10;
private static final int DEFAULT_TILE_QUEUE_CAPACITY = 1000;
private static final OpenStreetMapTileSource DEFAULT_TILE_SOURCE = new OpenStreetMapTileSource();
/***********************************************************************************************************************************************************
* This helper class provides methods useful for creating map overlays.
**********************************************************************************************************************************************************/
@RequiredArgsConstructor(staticName = "of") @Accessors(fluent = true)
public static class OverlayHelper
{
@Nonnull
private final MapViewModel model;
@Nonnull
private final ObservableList<Node> children;
/*******************************************************************************************************************************************************
* Adds a {@link Node} to the overlay.
* @param node the {@code Node}
******************************************************************************************************************************************************/
public void add (@Nonnull final Node node)
{
children.add(node);
}
/*******************************************************************************************************************************************************
* Adds multiple {@link Node}s to the overlay.
* @param nodes the {@code Node}s
******************************************************************************************************************************************************/
public void addAll (@Nonnull final Collection<? extends Node> nodes)
{
children.addAll(nodes);
}
/*******************************************************************************************************************************************************
* {@return a map view point corresponding to the given coordinates}. This view point must be used to draw to the overlay.
* @param coordinates the coordinates
******************************************************************************************************************************************************/
@Nonnull
public MapViewPoint toMapViewPoint (@Nonnull final MapCoordinates coordinates)
{
final var gridOffset = model.gridOffset();
final var point = model.coordinatesToMapViewPoint(coordinates);
return MapViewPoint.of(point.x() - gridOffset.x(), point.y() - gridOffset.y());
}
/*******************************************************************************************************************************************************
* {@return the area rendered in the map view}.
******************************************************************************************************************************************************/
@Nonnull
public MapArea getArea()
{
return model.getArea();
}
}
/***********************************************************************************************************************************************************
* Options for creating a {@code MapView}.
* @param cacheFolder the {@link Path} of the folder where cached tiles are stored
* @param downloadAllowed whether downloading tiles is allowed
* @param poolSize the number of parallel thread of the tile downloader
* @param tileQueueCapacity the capacity of the tile queue
**********************************************************************************************************************************************************/
@With
public record Options(@Nonnull Path cacheFolder, boolean downloadAllowed, int poolSize, int tileQueueCapacity) {}
/** The tile source. */
@Nonnull
private final SimpleObjectProperty<TileSource> tileSource;
/** The coordinates at the center of the map view. */
@Nonnull
private final SimpleObjectProperty<MapCoordinates> center;
/** The zoom level. */
@Nonnull
private final RangeLimitedDoubleProperty zoom;
/** The minimum zoom level. */
@Nonnull
private final SimpleDoubleProperty minZoom;
/** The maximum zoom level. */
@Nonnull
private final SimpleDoubleProperty maxZoom;
/** The coordinates corresponding to the mouse position on the map. */
@Nonnull
private final SimpleObjectProperty<MapCoordinates> coordinatesUnderMouse;
/** The rectangular area in the view. */
@Nonnull
private final SimpleObjectProperty<MapArea> area;
/** The model for this control. */
@Nonnull
private final MapViewModel model;
/** The tile grid that the rendering relies upon. */
@Nonnull
private final TileGrid tileGrid;
/** A cache for tiles. */
@Nonnull
private final TileCache tileCache;
/** Whether double click re-centers the map to the clicked point. */
@Getter @Setter
private boolean recenterOnDoubleClick = true;
/** Whether the vertical scroll gesture should zoom. */
@Getter @Setter
private boolean scrollToZoom = false;
/** The duration of the re-centering animation. */
@Getter @Setter
private Duration recenterDuration = Duration.millis(200);
/** True if a zoom operation is in progress. */
private boolean zooming;
/** True if a drag operation is in progress. */
private boolean dragging;
/** The latest x coordinate in drag. */
private double dragX;
/** The latest y coordinate in drag. */
private double dragY;
/** The latest value in scroll. */
private double scroll;
/***********************************************************************************************************************************************************
* Creates a new instance.
* @param options options for the control
**********************************************************************************************************************************************************/
@SuppressWarnings("this-escape") @SuppressFBWarnings({"MALICIOUS_CODE", "CT_CONSTRUCTOR_THROW"})
public MapView (@Nonnull final Options options)
{
if (!Platform.isFxApplicationThread())
{
throw new IllegalStateException("Must be instantiated on JavaFX thread");
}
tileSource = new SimpleObjectProperty<>(this, "tileSource", DEFAULT_TILE_SOURCE);
model = new MapViewModel(tileSource.get());
tileCache = new TileCache(options);
tileGrid = new TileGrid(this, model, tileSource, tileCache);
center = new SimpleObjectProperty<>(this, "center", tileGrid.getCenter());
zoom = new RangeLimitedDoubleProperty(this, "zoom", model.zoom(), tileSource.get().getMinZoomLevel(), tileSource.get().getMaxZoomLevel());
minZoom = new SimpleDoubleProperty(this, "minZoom", tileSource.get().getMinZoomLevel());
maxZoom = new SimpleDoubleProperty(this, "maxZoom", tileSource.get().getMaxZoomLevel());
coordinatesUnderMouse = new SimpleObjectProperty<>(this, "coordinatesUnderMouse", MapCoordinates.of(0, 0));
area = new SimpleObjectProperty<>(this, "area", MapArea.of(0, 0, 0, 0));
tileSource.addListener((_1, _2, _3) -> onTileSourceChanged());
center.addListener((_1, _2, newValue) -> setCenterAndZoom(newValue, zoom.get()));
zoom.addListener((_1, _2, newValue) -> setCenterAndZoom(center.get(), newValue.intValue()));
getChildren().add(tileGrid);
AnchorPane.setLeftAnchor(tileGrid, 0d);
AnchorPane.setRightAnchor(tileGrid, 0d);
AnchorPane.setTopAnchor(tileGrid, 0d);
AnchorPane.setBottomAnchor(tileGrid, 0d);
// needRefresh();
setOnMouseClicked(this::onMouseClicked);
setOnZoom(this::onZoom);
setOnZoomStarted(this::onZoomStarted);
setOnZoomFinished(this::onZoomFinished);
setOnMouseMoved(this::onMouseMoved);
setOnScroll(this::onScroll);
tileGrid.setOnMousePressed(this::onMousePressed);
tileGrid.setOnMouseReleased(this::onMouseReleased);
tileGrid.setOnMouseDragged(this::onMouseDragged);
}
/***********************************************************************************************************************************************************
* {@return a new set of default options}.
**********************************************************************************************************************************************************/
@Nonnull
public static Options options()
{
return new Options(Path.of(System.getProperty("java.io.tmpdir")), true, DEFAULT_TILE_POOL_SIZE, DEFAULT_TILE_QUEUE_CAPACITY);
}
/***********************************************************************************************************************************************************
* {@return the tile source}.
* @see #setTileSource(TileSource)
* @see #tileSourceProperty()
**********************************************************************************************************************************************************/
@Nonnull
public final TileSource getTileSource()
{
return tileSource.get();
}
/***********************************************************************************************************************************************************
* Sets the tile source. Changing the tile source might change the zoom level to make sure it is within the limits of the new source.
* @param tileSource the tile source
* @see #getTileSource()
* @see #tileSourceProperty()
**********************************************************************************************************************************************************/
public final void setTileSource (@Nonnull final TileSource tileSource)
{
this.tileSource.set(tileSource);
}
/***********************************************************************************************************************************************************
* {@return the tile source property}.
* @see #setTileSource(TileSource)
* @see #getTileSource()
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ObjectProperty<TileSource> tileSourceProperty()
{
return tileSource;
}
/***********************************************************************************************************************************************************
* {@return the center coordinates}.
* @see #setCenter(MapCoordinates)
* @see #centerProperty()
**********************************************************************************************************************************************************/
@Nonnull
public final MapCoordinates getCenter()
{
return center.get();
}
/***********************************************************************************************************************************************************
* Sets the coordinates to show at the center of the map.
* @param center the center coordinates
* @see #getCenter()
* @see #centerProperty()
**********************************************************************************************************************************************************/
public final void setCenter (@Nonnull final MapCoordinates center)
{
this.center.set(center);
}
/***********************************************************************************************************************************************************
* {@return the center property}.
* @see #getCenter()
* @see #setCenter(MapCoordinates)
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ObjectProperty<MapCoordinates> centerProperty()
{
return center;
}
/***********************************************************************************************************************************************************
* {@return the zoom level}.
* @see #setZoom(double)
* @see #zoomProperty()
**********************************************************************************************************************************************************/
public final double getZoom()
{
return zoom.get();
}
/***********************************************************************************************************************************************************
* Sets the zoom level.
* @param zoom the zoom level
* @see #getZoom()
* @see #zoomProperty()
**********************************************************************************************************************************************************/
public final void setZoom (final double zoom)
{
this.zoom.set(zoom);
}
/***********************************************************************************************************************************************************
* {@return the zoom level property}.
* @see #getZoom()
* @see #setZoom(double)
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final DoubleProperty zoomProperty()
{
return zoom;
}
/***********************************************************************************************************************************************************
* {@return the min zoom level}.
* @see #minZoomProperty()
**********************************************************************************************************************************************************/
public final double getMinZoom()
{
return minZoom.get();
}
/***********************************************************************************************************************************************************
* {@return the min zoom level property}.
* @see #getMinZoom()
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ReadOnlyDoubleProperty minZoomProperty()
{
return minZoom;
}
/***********************************************************************************************************************************************************
* {@return the max zoom level}.
* @see #maxZoomProperty()
**********************************************************************************************************************************************************/
public final double getMaxZoom()
{
return maxZoom.get();
}
/***********************************************************************************************************************************************************
* {@return the max zoom level property}.
* @see #getMaxZoom()
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ReadOnlyDoubleProperty maxZoomProperty()
{
return maxZoom;
}
/***********************************************************************************************************************************************************
* {@return the coordinates corresponding to the point where the mouse is}.
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ObjectProperty<MapCoordinates> coordinatesUnderMouseProperty()
{
return coordinatesUnderMouse;
}
/***********************************************************************************************************************************************************
* {@return the area rendered on the map}.
* @see #areaProperty()
* @see #fitArea(MapArea)
**********************************************************************************************************************************************************/
@Nonnull
public final MapArea getArea()
{
return area.get();
}
/***********************************************************************************************************************************************************
* {@return the area rendered on the map}.
* @see #getArea()
* @see #fitArea(MapArea)
**********************************************************************************************************************************************************/
@Nonnull @SuppressFBWarnings("EI_EXPOSE_REP")
public final ObjectProperty<MapArea> areaProperty()
{
return area;
}
/***********************************************************************************************************************************************************
* Fits the zoom level and centers the map so that the two corners are visible.
* @param area the area to fit
* @see #getArea()
* @see #areaProperty()
**********************************************************************************************************************************************************/
public void fitArea (@Nonnull final MapArea area)
{
log.debug("fitArea({})", area);
setCenterAndZoom(area.getCenter(), model.computeFittingZoom(area));
}
/***********************************************************************************************************************************************************
* {@return the scale of the map in meters per pixel}.
**********************************************************************************************************************************************************/
// @Nonnegative
public double getMetersPerPixel()
{
return tileSource.get().metersPerPixel(tileGrid.getCenter(), zoom.get());
}
/***********************************************************************************************************************************************************
* {@return a point on the map corresponding to the given coordinates}.
* @param coordinates the coordinates
**********************************************************************************************************************************************************/
@Nonnull
public MapViewPoint coordinatesToPoint (@Nonnull final MapCoordinates coordinates)
{
return model.coordinatesToMapViewPoint(coordinates);
}
/***********************************************************************************************************************************************************
* {@return the coordinates corresponding to a given point on the map}.
* @param point the point on the map
**********************************************************************************************************************************************************/
@Nonnull
public MapCoordinates pointToCoordinates (@Nonnull final MapViewPoint point)
{
return model.mapViewPointToCoordinates(point);
}
/***********************************************************************************************************************************************************
* Adds an overlay, passing a callback that will be responsible for rendering the overlay, when needed.
* @param name the name of the overlay
* @param creator the overlay creator
* @see OverlayHelper
**********************************************************************************************************************************************************/
public void addOverlay (@Nonnull final String name, @Nonnull final Consumer<OverlayHelper> creator)
{
tileGrid.addOverlay(name, creator);
}
/***********************************************************************************************************************************************************
* Removes an overlay.
* @param name the name of the overlay to remove
**********************************************************************************************************************************************************/
public void removeOverlay (@Nonnull final String name)
{
tileGrid.removeOverlay(name);
}
/***********************************************************************************************************************************************************
* Removes all overlays.
**********************************************************************************************************************************************************/
public void removeAllOverlays()
{
tileGrid.removeAllOverlays();
}
/***********************************************************************************************************************************************************
* Sets both the center and the zoom level.
* @param center the center
* @param zoom the zoom level
**********************************************************************************************************************************************************/
private void setCenterAndZoom (@Nonnull final MapCoordinates center, final double zoom)
{
log.trace("setCenterAndZoom({}, {})", center, zoom);
if (!center.equals(tileGrid.getCenter()) || doubleToLongBits(zoom) != doubleToLongBits(model.zoom()))
{
tileCache.retainPendingTiles((int)zoom);
tileGrid.setCenterAndZoom(center, zoom);
this.center.set(center);
this.zoom.set(zoom);
area.set(model.getArea());
}
}
/***********************************************************************************************************************************************************
* Translate the map center by the specified amount.
* @param dx the horizontal amount
* @param dy the vertical amount
**********************************************************************************************************************************************************/
private void translateCenter (final double dx, final double dy)
{
tileGrid.translate(dx, dy);
center.set(model.center());
area.set(model.getArea());
}
/***********************************************************************************************************************************************************
* This method is called when the tile source has been changed.
**********************************************************************************************************************************************************/
private void onTileSourceChanged()
{
final var minZoom = tileSourceProperty().get().getMinZoomLevel();
final var maxZoom = tileSourceProperty().get().getMaxZoomLevel();
zoom.setLimits(minZoom, maxZoom);
this.minZoom.set(minZoom);
this.maxZoom.set(maxZoom);
setNeedsLayout(true);
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onMousePressed (@Nonnull final MouseEvent event)
{
if (!zooming)
{
dragging = true;
dragX = event.getSceneX();
dragY = event.getSceneY();
log.trace("onMousePressed: {} {}", dragX, dragY);
}
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onMouseReleased (@Nonnull final MouseEvent ignored)
{
log.trace("onMouseReleased");
dragging = false;
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onMouseDragged (@Nonnull final MouseEvent event)
{
if (!zooming && dragging)
{
translateCenter(event.getSceneX() - dragX, event.getSceneY() - dragY);
dragX = event.getSceneX();
dragY = event.getSceneY();
}
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onMouseClicked (@Nonnull final MouseEvent event)
{
if (recenterOnDoubleClick && (event.getClickCount() == 2))
{
final var delta = Translation.of(getWidth() / 2 - event.getX(), getHeight() / 2 - event.getY());
final var target = new SimpleObjectProperty<>(Translation.of(0, 0));
target.addListener((__, oldValue, newValue) ->
translateCenter(newValue.x - oldValue.x, newValue.y - oldValue.y));
animate(target, Translation.of(0, 0), delta, recenterDuration);
}
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onMouseMoved (@Nonnull final MouseEvent event)
{
coordinatesUnderMouse.set(pointToCoordinates(MapViewPoint.of(event)));
}
/***********************************************************************************************************************************************************
* Gesture callback.
**********************************************************************************************************************************************************/
private void onZoomStarted (@Nonnull final ZoomEvent event)
{
log.trace("onZoomStarted({})", event);
zooming = true;
dragging = false;
}
/***********************************************************************************************************************************************************
* Gesture callback.
**********************************************************************************************************************************************************/
private void onZoomFinished (@Nonnull final ZoomEvent event)
{
log.trace("onZoomFinished({})", event);
zooming = false;
}
/***********************************************************************************************************************************************************
* Gesture callback.
**********************************************************************************************************************************************************/
private void onZoom (@Nonnull final ZoomEvent event)
{
log.trace("onZoom({})", event);
}
/***********************************************************************************************************************************************************
* Mouse callback.
**********************************************************************************************************************************************************/
private void onScroll (@Nonnull final ScrollEvent event)
{
if (scrollToZoom)
{
log.info("onScroll({})", event);
final var amount = -Math.signum(Math.floor(event.getDeltaY() - scroll));
scroll = event.getDeltaY();
log.debug("zoom change for scroll: {}", amount);
System.err.println("AMOUNT " + amount);
zoom.set(Math.round(zoom.get() + amount));
}
}
/***********************************************************************************************************************************************************
* Animates a property. If the duration is zero, the property is immediately set.
* @param <T> the static type of the property to animate
* @param target the property to animate
* @param startValue the start value of the property
* @param endValue the end value of the property
* @param duration the duration of the animation
**********************************************************************************************************************************************************/
private static <T extends Interpolatable<T>> void animate (@Nonnull final ObjectProperty<T> target,
@Nonnull final T startValue,
@Nonnull final T endValue,
@Nonnull final Duration duration)
{
if (duration.equals(ZERO))
{
target.set(endValue);
}
else
{
final var start = new KeyFrame(ZERO, new KeyValue(target, startValue));
final var end = new KeyFrame(duration, new KeyValue(target, endValue, Interpolator.EASE_OUT));
new Timeline(start, end).play();
}
}
// FIXME: on close shut down the tile cache executor service.
}