Refactor the code and improve javadoc

baremaps-cli/src/main/java/org/apache/baremaps/cli/raster/HillShade.java

@@ -41,7 +41,7 @@
 import java.util.function.Function;
 import java.util.function.Supplier;
 import javax.imageio.ImageIO;
-import org.apache.baremaps.raster.ImageUtils;
+import org.apache.baremaps.raster.ElevationUtils;
 import org.apache.baremaps.tilestore.TileCoord;
 import org.apache.baremaps.tilestore.TileStore;
 import org.apache.baremaps.tilestore.TileStoreException;
@@ -104,7 +104,8 @@ public Integer call() throws Exception {
   public static class HillShadeTileStore implements TileStore {
 
     // private String url = "https://s3.amazonaws.com/elevation-tiles-prod/geotiff/{z}/{x}/{y}.tif";
-    private String url = "https://demotiles.maplibre.org/terrain-tiles/{z}/{x}/{y}.png";
+    // private String url = "https://demotiles.maplibre.org/terrain-tiles/{z}/{x}/{y}.png";
+    private String url = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/{z}/{x}/{y}.png";
 
     private final LoadingCache<TileCoord, BufferedImage> cache = Caffeine.newBuilder()
         .maximumSize(1000)
@@ -171,8 +172,8 @@ public ByteBuffer read(TileCoord tileCoord) throws TileStoreException {
             image.getWidth() + 2,
             image.getHeight() + 2);
 
-        var grid = ImageUtils.grid(buffer);
-        var hillshade = org.apache.baremaps.raster.hillshade.HillShade.hillShade(grid,
+        var grid = ElevationUtils.imageToGrid(buffer);
+        var hillshade = org.apache.baremaps.raster.elevation.HillShade.hillShade(grid,
             buffer.getWidth(), buffer.getHeight(), 45, 315);
 
         // Create an output image

baremaps-raster/pom.xml

@@ -11,7 +11,10 @@
     <dependency>
       <groupId>com.twelvemonkeys.imageio</groupId>
       <artifactId>imageio-tiff</artifactId>
-      <version>3.11.0</version>
+    </dependency>
+    <dependency>
+      <groupId>org.locationtech.jts</groupId>
+      <artifactId>jts-core</artifactId>
     </dependency>
   </dependencies>
 </project>

baremaps-raster/src/main/java/org/apache/baremaps/raster/ElevationUtils.java

@@ -0,0 +1,112 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to you 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.
+ */
+
+package org.apache.baremaps.raster;
+
+import java.awt.image.BufferedImage;
+
+/**
+ * Provides utility methods for processing raster images, particularly for elevation data.
+ */
+public class ElevationUtils {
+
+  private static final double ELEVATION_SCALE = 256.0 * 256.0;
+  private static final double ELEVATION_OFFSET = 10000.0;
+
+  private ElevationUtils() {
+    // Private constructor to prevent instantiation
+  }
+
+  /**
+   * Converts a BufferedImage to a grid of elevation values.
+   *
+   * @param image The input BufferedImage
+   * @return A double array representing the elevation grid
+   */
+  public static double[] imageToGrid(BufferedImage image) {
+    validateImage(image);
+    int width = image.getWidth();
+    int height = image.getHeight();
+    double[] grid = new double[width * height];
+
+    for (int y = 0; y < height; y++) {
+      for (int x = 0; x < width; x++) {
+        grid[y * width + x] = pixelToElevation(image.getRGB(x, y));
+      }
+    }
+
+    return grid;
+  }
+
+  /**
+   * Converts a grid of elevation values to a BufferedImage.
+   *
+   * @param grid The input elevation grid
+   * @param width The width of the grid
+   * @param height The height of the grid
+   * @return A BufferedImage representing the elevation data
+   */
+  public static BufferedImage gridToImage(double[] grid, int width, int height) {
+    validateGrid(grid, width, height);
+    BufferedImage image = new BufferedImage(width, height, BufferedImage.TYPE_INT_RGB);
+
+    for (int y = 0; y < height; y++) {
+      for (int x = 0; x < width; x++) {
+        image.setRGB(x, y, elevationToPixel(grid[y * width + x]));
+      }
+    }
+
+    return image;
+  }
+
+  private static double pixelToElevation(int rgb) {
+    int r = (rgb >> 16) & 0xFF;
+    int g = (rgb >> 8) & 0xFF;
+    int b = rgb & 0xFF;
+    return (r * ELEVATION_SCALE + g * 256.0 + b) / 10.0 - ELEVATION_OFFSET;
+  }
+
+  private static int elevationToPixel(double elevation) {
+    int value = (int) ((elevation + ELEVATION_OFFSET) * 10.0);
+    int r = (value >> 16) & 0xFF;
+    int g = (value >> 8) & 0xFF;
+    int b = value & 0xFF;
+    return (r << 16) | (g << 8) | b;
+  }
+
+  private static void validateImage(BufferedImage image) {
+    if (image == null) {
+      throw new IllegalArgumentException("Input image cannot be null");
+    }
+    if (image.getWidth() <= 0 || image.getHeight() <= 0) {
+      throw new IllegalArgumentException("Image dimensions must be positive");
+    }
+  }
+
+  private static void validateGrid(double[] grid, int width, int height) {
+    if (grid == null || grid.length == 0) {
+      throw new IllegalArgumentException("Grid array cannot be null or empty");
+    }
+    if (width <= 0 || height <= 0) {
+      throw new IllegalArgumentException("Width and height must be positive");
+    }
+    if (grid.length != width * height) {
+      throw new IllegalArgumentException("Grid array length does not match width * height");
+    }
+  }
+
+}