From 67fdc4228825921b6b63d918462372eb5dd76aaa Mon Sep 17 00:00:00 2001
From: naulan-chrzaszcz <nonochrzaszcz@gmail.com>
Date: Thu, 24 Sep 2026 14:31:06 +0200
Subject: [PATCH] feat(provider): XYZ Tiles provider

---
 examples/processes/mapterhorn.yaml            |  34 +++++
 pom.xml                                       |   6 +
 .../java/fr/ign/voxatile/core/Voxatile.java   |   2 +
 .../core/inputs/FloatBufferedImageMatrix.java |  40 ++++++
 .../core/inputs/XYZTilesProvider.java         | 121 ++++++++++++++++++
 .../decoders/TerrariumFloatDecoder.java       |  17 +++
 .../core/models/FloatMatrixModel.java         |   8 +-
 .../providers/XYZTilesProviderParams.java     |  59 +++++++++
 8 files changed, 283 insertions(+), 4 deletions(-)
 create mode 100644 examples/processes/mapterhorn.yaml
 create mode 100644 src/main/java/fr/ign/voxatile/core/inputs/FloatBufferedImageMatrix.java
 create mode 100644 src/main/java/fr/ign/voxatile/core/inputs/XYZTilesProvider.java
 create mode 100644 src/main/java/fr/ign/voxatile/core/inputs/decoders/TerrariumFloatDecoder.java
 create mode 100644 src/main/java/fr/ign/voxatile/core/parameters/providers/XYZTilesProviderParams.java

diff --git a/examples/processes/mapterhorn.yaml b/examples/processes/mapterhorn.yaml
new file mode 100644
index 000000000..9a44d89c7
--- /dev/null
+++ b/examples/processes/mapterhorn.yaml
@@ -0,0 +1,34 @@
+heightmaps:
+  ground:
+    default: 0
+
+forEachTile:
+
+  altitude:
+    type: sequence
+    do:
+    - type: fetchData
+      modelType: altitude
+      provider:
+        type: xyz
+        url: https://tiles.mapterhorn.com/{z}/{x}/{y}.webp
+        zoom: 16
+    - type: populateHeightmap
+      models:
+        type: altitude
+      heightmap: ground
+    - type: setSpawn
+      heightmap:
+        sum: [ground, 1]
+      x: 0
+      y: 0
+    - type: renderHeightmap
+      at: ground
+      place:
+        structure:
+          - place: *voxel-grass
+            at: [0, 0, 0]
+          - place: *voxel-dirt
+            at: [0, 0, -3..-1]
+          - place: *voxel-stone
+            at: [0, 0, -20..-4]
diff --git a/pom.xml b/pom.xml
index b31f1d2cf..eb32e66a5 100644
--- a/pom.xml
+++ b/pom.xml
@@ -200,6 +200,12 @@
             <artifactId>osm4j-geometry</artifactId>
             <version>${osm4j.version}</version>
         </dependency>
+        <!-- TwelveMonkeys library for WebP support in ImageIO -->
+        <dependency>
+            <groupId>com.twelvemonkeys.imageio</groupId>
+            <artifactId>imageio-webp</artifactId>
+            <version>3.9.4</version>
+        </dependency>
 
         <!--
         TEST DEPENDENCIES
diff --git a/src/main/java/fr/ign/voxatile/core/Voxatile.java b/src/main/java/fr/ign/voxatile/core/Voxatile.java
index 9b30b8251..69508da83 100644
--- a/src/main/java/fr/ign/voxatile/core/Voxatile.java
+++ b/src/main/java/fr/ign/voxatile/core/Voxatile.java
@@ -34,6 +34,7 @@
 import fr.ign.voxatile.core.parameters.providers.ShapefileProviderParams;
 import fr.ign.voxatile.core.parameters.providers.WFSProviderParams;
 import fr.ign.voxatile.core.parameters.providers.WMSFloatBilProviderParams;
+import fr.ign.voxatile.core.parameters.providers.XYZTilesProviderParams;
 import fr.ign.voxatile.core.parameters.tasks.BuildLayoutTaskParams;
 import fr.ign.voxatile.core.parameters.tasks.CopyHeightmapTaskParams;
 import fr.ign.voxatile.core.parameters.tasks.FetchDataTaskParams;
@@ -139,6 +140,7 @@ public static void main(String[] args) throws FactoryException, InterruptedExcep
         parser.registerParams("renderFacades", RenderFacadesTaskParams.class);
         parser.registerParams("buildLayout", BuildLayoutTaskParams.class);
 
+        parser.registerParams("xyz", XYZTilesProviderParams.class);
         parser.registerParams("wfs", WFSProviderParams.class);
         parser.registerParams("gpkg", GeoPackageProviderParams.class);
         parser.registerParams("shapefile", ShapefileProviderParams.class);
diff --git a/src/main/java/fr/ign/voxatile/core/inputs/FloatBufferedImageMatrix.java b/src/main/java/fr/ign/voxatile/core/inputs/FloatBufferedImageMatrix.java
new file mode 100644
index 000000000..5850a7f2e
--- /dev/null
+++ b/src/main/java/fr/ign/voxatile/core/inputs/FloatBufferedImageMatrix.java
@@ -0,0 +1,40 @@
+package fr.ign.voxatile.core.inputs;
+
+import java.awt.image.BufferedImage;
+import java.util.function.IntToDoubleFunction;
+
+/**
+ * Represents a matrix of floating-point geographic data backed by a BufferedImage.
+ *
+ * @param image the backing BufferedImage
+ * @param decoder the float decoder
+ * @param cellSizeX the size of a cell in the X direction
+ * @param cellSizeY the size of a cell in the Y direction
+ * @param offsetX the X offset of the matrix
+ * @param offsetY the Y offset of the matrix
+ */
+public record FloatBufferedImageMatrix(
+    BufferedImage image,
+    IntToDoubleFunction decoder,
+    double cellSizeX,
+    double cellSizeY,
+    double offsetX,
+    double offsetY
+) implements FloatGeographicDataMatrix2d {
+
+    @Override
+    public int sizeX() {
+        return image.getWidth();
+    }
+
+    @Override
+    public int sizeY() {
+        return image.getHeight();
+    }
+
+    @Override
+    public float getFloat(int x, int y) {
+        int rgb = image.getRGB(x, image.getHeight() - 1 - y);
+        return (float) decoder.applyAsDouble(rgb);
+    }
+}
diff --git a/src/main/java/fr/ign/voxatile/core/inputs/XYZTilesProvider.java b/src/main/java/fr/ign/voxatile/core/inputs/XYZTilesProvider.java
new file mode 100644
index 000000000..efbfd425a
--- /dev/null
+++ b/src/main/java/fr/ign/voxatile/core/inputs/XYZTilesProvider.java
@@ -0,0 +1,121 @@
+package fr.ign.voxatile.core.inputs;
+
+import java.awt.image.BufferedImage;
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URI;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.function.IntToDoubleFunction;
+import javax.imageio.ImageIO;
+
+import org.geotools.api.referencing.FactoryException;
+import org.geotools.api.referencing.crs.CoordinateReferenceSystem;
+import org.geotools.geometry.jts.ReferencedEnvelope;
+import org.geotools.referencing.CRS;
+
+import fr.ign.voxatile.core.exceptions.GenerationFailedException;
+import fr.ign.voxatile.core.exceptions.RetryableException;
+import fr.ign.voxatile.core.exceptions.TransformException;
+import fr.ign.voxatile.core.utils.coordinates.EnvelopeProvider;
+import fr.ign.voxatile.core.utils.world3d.WorldBBox3d;
+
+/**
+ * Data provider reading images from generic XYZ URL endpoints.
+ */
+public class XYZTilesProvider implements Provider<FloatGeographicDataMatrix2d> {
+
+    private final String url;
+    private final int zoom;
+    private final IntToDoubleFunction decoder;
+    private final EnvelopeProvider envelopeProvider;
+
+    /**
+     * Creates a new {@code XYZTilesProvider}.
+     *
+     * @param url URL with {@code {z}}, {@code {x}}, and {@code {y}} placeholders
+     * @param zoom zoom level for the tiles
+     * @param decoder the elevation decoder format for the tiles
+     * @param envelopeProvider the provider used to compute the envelope for the given CRS and bounding box
+     */
+    public XYZTilesProvider(
+            String url,
+            int zoom,
+            IntToDoubleFunction decoder,
+            EnvelopeProvider envelopeProvider
+        ) {
+        this.url = url.replace("{z}", String.valueOf(zoom));
+        this.zoom = zoom;
+        this.decoder = decoder;
+        this.envelopeProvider = envelopeProvider;
+    }
+
+    @Override
+    public Class<FloatGeographicDataMatrix2d> providedType() {
+        return FloatGeographicDataMatrix2d.class;
+    }
+
+    @Override
+    public Result<FloatGeographicDataMatrix2d> provide(WorldBBox3d bbox) throws GenerationFailedException, RetryableException {
+        CoordinateReferenceSystem crs;
+        ReferencedEnvelope envelope;
+        try {
+            crs = CRS.decode("EPSG:4326", true);
+            envelope = envelopeProvider.computeForCRS(crs, bbox);
+        } catch (FactoryException | TransformException e) {
+            throw new GenerationFailedException(e);
+        }
+
+        int minX = (int) lon2tile(envelope.getMinX(), zoom);
+        int minY = (int) lat2tile(envelope.getMaxY(), zoom);
+        int maxX = (int) lon2tile(envelope.getMaxX(), zoom);
+        int maxY = (int) lat2tile(envelope.getMinY(), zoom);
+
+        List<FloatGeographicDataMatrix2d> tiles = new ArrayList<>();
+        for (int y = minY; y <= maxY; y++)
+            for (int x = minX; x <= maxX; x++) {
+                BufferedImage image;
+                try (InputStream stream = URI.create(url.replace("{x}", String.valueOf(x))
+                                                        .replace("{y}", String.valueOf(y))).toURL().openStream()) {
+                    image = ImageIO.read(stream);
+                } catch (IOException e) {
+                    throw new GenerationFailedException(e);
+                }
+
+                if (image != null) {
+                    double tileMinX = tile2lon(x, zoom);
+                    double tileMaxY = tile2lat(y, zoom);
+                    double cellSizeX = (tile2lon(x + 1, zoom) - tileMinX) / (image.getWidth() - 1);
+                    double cellSizeY = (tileMaxY - tile2lat(y + 1, zoom)) / (image.getHeight() - 1);
+                    double offsetX = tileMinX + (cellSizeX / 2.0);
+                    double offsetY = tileMaxY - (cellSizeY / 2.0);
+
+                    tiles.add(new FloatBufferedImageMatrix(image, decoder, cellSizeX, cellSizeY, offsetX, offsetY));
+                }
+            }
+
+        return new SimpleResult<>(crs, tiles.iterator());
+    }
+
+
+    /*
+        the formulas below are based on the Slippy map tilenames convention
+            https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames
+    */
+    private double tile2lon(int x, int z) {
+        return x * 360.0 / (1 << z) - 180.0;
+    }
+
+    private double lon2tile(double lon, int z) {
+        return (lon + 180.0) / 360.0 * (1 << z);
+    }
+
+    private double tile2lat(int y, int z) {
+        return Math.toDegrees(Math.atan(Math.sinh(Math.PI * (1 - 2.0 * y / (1 << z)))));
+    }
+
+    private double lat2tile(double lat, int z) {
+        double latRad = Math.toRadians(lat);
+        return (1 - Math.log(Math.tan(latRad) + 1 / Math.cos(latRad)) / Math.PI) / 2 * (1 << z);
+    }
+}
diff --git a/src/main/java/fr/ign/voxatile/core/inputs/decoders/TerrariumFloatDecoder.java b/src/main/java/fr/ign/voxatile/core/inputs/decoders/TerrariumFloatDecoder.java
new file mode 100644
index 000000000..8e79d90da
--- /dev/null
+++ b/src/main/java/fr/ign/voxatile/core/inputs/decoders/TerrariumFloatDecoder.java
@@ -0,0 +1,17 @@
+package fr.ign.voxatile.core.inputs.decoders;
+
+import java.util.function.IntToDoubleFunction;
+
+/**
+ * Decoder for Terrarium format RGB values to float elevation.
+ */
+public class TerrariumFloatDecoder implements IntToDoubleFunction {
+
+    @Override
+    public double applyAsDouble(int value) {
+        int r = (value >> 16) & 0xFF;
+        int g = (value >> 8) & 0xFF;
+        int b = value & 0xFF;
+        return (r * 256.0f + g + b / 256.0f) - 32768.0f;
+    }
+}
diff --git a/src/main/java/fr/ign/voxatile/core/models/FloatMatrixModel.java b/src/main/java/fr/ign/voxatile/core/models/FloatMatrixModel.java
index d683cf8cf..c617b7cb7 100644
--- a/src/main/java/fr/ign/voxatile/core/models/FloatMatrixModel.java
+++ b/src/main/java/fr/ign/voxatile/core/models/FloatMatrixModel.java
@@ -35,8 +35,8 @@ public FloatMatrixModel(FloatGeographicDataMatrix2d data, MapToWorldConverter co
 
         this.data = data;
 
-        double maxX = data.offsetX() + data.sizeX() * data.cellSizeX() - 1.0;
-        double maxY = data.offsetY() + data.sizeY() * data.cellSizeY() - 1.0;
+        double maxX = data.offsetX() + (data.sizeX() - 1) * data.cellSizeX();
+        double maxY = data.offsetY() + (data.sizeY() - 1) * data.cellSizeY();
 
         this.bbox = new WorldBBox2d(
             mapToWorld.convert(new MapCoordinates(data.offsetX(), data.offsetY())),
@@ -63,8 +63,8 @@ public Float get(WorldCoords2d coords) {
         }
 
         // We interpolate between cell centers (not cell upper left corner)
-        float x = (float) ((coordinates.x() + 0.5 - data.offsetX()) / data.cellSizeX() - 0.5);
-        float y = (float) ((coordinates.y() + 0.5 - data.offsetY()) / data.cellSizeY() - 0.5);
+        float x = (float) ((coordinates.x() - data.offsetX()) / data.cellSizeX());
+        float y = (float) ((coordinates.y() - data.offsetY()) / data.cellSizeY());
 
         // Using separate ceil & floor allows a good management of integer coordinates
         int xf = (int) Math.floor(x);
diff --git a/src/main/java/fr/ign/voxatile/core/parameters/providers/XYZTilesProviderParams.java b/src/main/java/fr/ign/voxatile/core/parameters/providers/XYZTilesProviderParams.java
new file mode 100644
index 000000000..f339018fb
--- /dev/null
+++ b/src/main/java/fr/ign/voxatile/core/parameters/providers/XYZTilesProviderParams.java
@@ -0,0 +1,59 @@
+package fr.ign.voxatile.core.parameters.providers;
+
+import java.beans.ConstructorProperties;
+
+import fr.ign.voxatile.core.generation.Generation;
+import fr.ign.voxatile.core.inputs.FloatGeographicDataMatrix2d;
+import fr.ign.voxatile.core.inputs.Provider;
+import fr.ign.voxatile.core.inputs.XYZTilesProvider;
+import fr.ign.voxatile.core.inputs.decoders.TerrariumFloatDecoder;
+import fr.ign.voxatile.core.parameters.processors.FloatMatrixProcessorParams;
+import fr.ign.voxatile.core.parameters.processors.ProcessorParams;
+
+/**
+ * Parameters for {@link XYZTilesProvider}.
+ */
+public class XYZTilesProviderParams extends ProviderParams {
+    /**
+     * URL carrying the {@code {z}}, {@code {x}} and {@code {y}} placeholders (required).
+     */
+    public String url;
+
+    /**
+     * Zoom level for the tiles (required).
+     */
+    public int zoom;
+
+    // TODO: field for float decoder
+    // public FloatDecoderParams format;
+
+    /**
+     * Constructs a new {@link XYZTilesProviderParams} with mandatory fields.
+     *
+     * @param url URL carrying the {@code {z}}, {@code {x}} and {@code {y}} placeholders
+     * @param zoom zoom level for the tiles
+     */
+    @ConstructorProperties({"url", "zoom"})
+    public XYZTilesProviderParams(String url, int zoom) {
+        this.url = url;
+        this.zoom = zoom;
+    }
+
+    @Override
+    public Provider<FloatGeographicDataMatrix2d> create(Generation generation) {
+        if (url == null || url.isBlank())
+            throw new IllegalArgumentException("An XYZ tiles provider needs a url");
+        if (!url.contains("{z}") || !url.contains("{x}") || !url.contains("{y}"))
+            throw new IllegalArgumentException("The url must carry the {z}, {x} and {y} placeholders, got \"%s\"".formatted(url));
+        if (zoom < 0)
+            throw new IllegalArgumentException("The zoom level must be non-negative, got " + zoom);
+
+        // TODO: Handle more float decoder
+        return new XYZTilesProvider(url, zoom, new TerrariumFloatDecoder(), generation::getEnvelopeForCRS);
+    }
+
+    @Override
+    public ProcessorParams defaultProcessor() {
+        return new FloatMatrixProcessorParams();
+    }
+}