Rename Projection to ProjectionUtils

Author: afarber

openmapview/src/main/kotlin/de/afarber/openmapview/LatLngBounds.kt

@@ -0,0 +1,173 @@
+/*
+ * Copyright (c) 2025 Alexander Farber
+ * SPDX-License-Identifier: MIT
+ *
+ * This file is part of the OpenMapView project (https://github.com/afarber/OpenMapView)
+ */
+
+package de.afarber.openmapview
+
+import kotlin.math.max
+import kotlin.math.min
+
+/**
+ * An immutable class representing a latitude/longitude aligned rectangle.
+ *
+ * Compatible with Google Maps API. The bounds are defined by the southwest
+ * and northeast corners of the rectangle.
+ *
+ * @property southwest The southwest corner of the bounds
+ * @property northeast The northeast corner of the bounds
+ */
+data class LatLngBounds(
+    val southwest: LatLng,
+    val northeast: LatLng,
+) {
+    /**
+     * Returns whether this bounds contains the given point.
+     *
+     * @param point The point to test
+     * @return true if the point is contained within the bounds, false otherwise
+     */
+    fun contains(point: LatLng): Boolean {
+        val lat = point.latitude
+        val lng = point.longitude
+
+        val latContained = lat >= southwest.latitude && lat <= northeast.latitude
+
+        val lngContained =
+            if (southwest.longitude <= northeast.longitude) {
+                lng >= southwest.longitude && lng <= northeast.longitude
+            } else {
+                lng >= southwest.longitude || lng <= northeast.longitude
+            }
+
+        return latContained && lngContained
+    }
+
+    /**
+     * Returns the center of the bounds.
+     *
+     * @return The geographic center point
+     */
+    fun getCenter(): LatLng {
+        val lat = (southwest.latitude + northeast.latitude) / 2.0
+
+        val lng =
+            if (southwest.longitude <= northeast.longitude) {
+                (southwest.longitude + northeast.longitude) / 2.0
+            } else {
+                var center = (southwest.longitude + northeast.longitude + 360.0) / 2.0
+                if (center >= 180.0) center -= 360.0
+                center
+            }
+
+        return LatLng(lat, lng)
+    }
+
+    /**
+     * Returns a new bounds that extends this bounds to include the given point.
+     *
+     * @param point The point to include
+     * @return A new LatLngBounds that includes both the original bounds and the point
+     */
+    fun including(point: LatLng): LatLngBounds {
+        val minLat = min(southwest.latitude, point.latitude)
+        val maxLat = max(northeast.latitude, point.latitude)
+
+        val minLng: Double
+        val maxLng: Double
+
+        if (southwest.longitude <= northeast.longitude) {
+            minLng = min(southwest.longitude, point.longitude)
+            maxLng = max(northeast.longitude, point.longitude)
+        } else {
+            minLng = southwest.longitude
+            maxLng = northeast.longitude
+        }
+
+        return LatLngBounds(
+            southwest = LatLng(minLat, minLng),
+            northeast = LatLng(maxLat, maxLng),
+        )
+    }
+
+    companion object {
+        /**
+         * Creates a new builder for constructing bounds.
+         *
+         * @return A new Builder instance
+         */
+        fun builder(): Builder = Builder()
+    }
+
+    /**
+     * Builder for creating LatLngBounds by including multiple points.
+     *
+     * The builder calculates the minimum bounding box that contains all
+     * included points.
+     */
+    class Builder {
+        private var minLat: Double? = null
+        private var maxLat: Double? = null
+        private var minLng: Double? = null
+        private var maxLng: Double? = null
+
+        /**
+         * Includes a point in the bounds being built.
+         *
+         * The bounds will be extended to include this point.
+         *
+         * @param point The point to include
+         * @return This builder for method chaining
+         */
+        fun include(point: LatLng): Builder {
+            val lat = point.latitude
+            val lng = point.longitude
+
+            minLat =
+                if (minLat == null) {
+                    lat
+                } else {
+                    min(minLat!!, lat)
+                }
+            maxLat =
+                if (maxLat == null) {
+                    lat
+                } else {
+                    max(maxLat!!, lat)
+                }
+            minLng =
+                if (minLng == null) {
+                    lng
+                } else {
+                    min(minLng!!, lng)
+                }
+            maxLng =
+                if (maxLng == null) {
+                    lng
+                } else {
+                    max(maxLng!!, lng)
+                }
+
+            return this
+        }
+
+        /**
+         * Creates the LatLngBounds from the included points.
+         *
+         * @return The constructed LatLngBounds
+         * @throws IllegalStateException if no points have been included
+         */
+        fun build(): LatLngBounds {
+            require(minLat != null && maxLat != null && minLng != null && maxLng != null) {
+                "Cannot build LatLngBounds: no points have been included"
+            }
+
+            return LatLngBounds(
+                southwest = LatLng(minLat!!, minLng!!),
+                northeast = LatLng(maxLat!!, maxLng!!),
+            )
+        }
+    }
+}

openmapview/src/main/kotlin/de/afarber/openmapview/MapController.kt

@@ -203,6 +203,24 @@ class MapController(
             zoom = zoom,
         )
 
+    /**
+     * Creates a Projection instance for coordinate conversions.
+     *
+     * The projection captures the current map state (center, zoom, view size, pan offset)
+     * and provides methods for converting between screen and geographic coordinates.
+     *
+     * @return A Projection instance for the current map state
+     */
+    fun createProjection(): Projection =
+        Projection(
+            center = center,
+            zoom = zoom,
+            viewWidth = viewWidth,
+            viewHeight = viewHeight,
+            panOffsetX = panOffsetX,
+            panOffsetY = panOffsetY,
+        )
+
     /**
      * Converts screen coordinates to geographic coordinates.
      *
@@ -217,15 +235,15 @@ class MapController(
         screenY: Float,
     ): LatLng {
         // Get center pixel coordinates at current zoom
-        val (centerPixelX, centerPixelY) = Projection.latLngToPixel(center, zoom.toInt())
+        val (centerPixelX, centerPixelY) = ProjectionUtils.latLngToPixel(center, zoom.toInt())
 
         // Convert screen coordinates to pixel coordinates
         // Account for view center offset and pan offset
         val pixelX = (centerPixelX + (screenX - viewWidth / 2 + panOffsetX).toDouble()).toInt()
         val pixelY = (centerPixelY + (screenY - viewHeight / 2 + panOffsetY).toDouble()).toInt()
 
         // Convert pixel coordinates to LatLng
-        return Projection.pixelToLatLng(pixelX, pixelY, zoom.toInt())
+        return ProjectionUtils.pixelToLatLng(pixelX, pixelY, zoom.toInt())
     }
 
     /**
@@ -432,11 +450,11 @@ class MapController(
         if (panOffsetX == 0f && panOffsetY == 0f) return
 
         // Convert accumulated pan offset to new center
-        val (centerPixelX, centerPixelY) = Projection.latLngToPixel(center, zoom.toInt())
+        val (centerPixelX, centerPixelY) = ProjectionUtils.latLngToPixel(center, zoom.toInt())
         val newCenterPixelX = (centerPixelX + panOffsetX).toInt()
         val newCenterPixelY = (centerPixelY + panOffsetY).toInt()
 
-        center = Projection.pixelToLatLng(newCenterPixelX, newCenterPixelY, zoom.toInt())
+        center = ProjectionUtils.pixelToLatLng(newCenterPixelX, newCenterPixelY, zoom.toInt())
 
         // Reset pan offset
         panOffsetX = 0f
@@ -466,10 +484,10 @@ class MapController(
                 panOffsetY,
             )
 
-        val (centerPixelX, centerPixelY) = Projection.latLngToPixel(center, zoom.toInt())
+        val (centerPixelX, centerPixelY) = ProjectionUtils.latLngToPixel(center, zoom.toInt())
 
         for (tile in visibleTiles) {
-            val (tilePixelX, tilePixelY) = Projection.tileToPixel(tile)
+            val (tilePixelX, tilePixelY) = ProjectionUtils.tileToPixel(tile)
 
             val screenX = (tilePixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
             val screenY = (tilePixelY - centerPixelY + viewHeight / 2 - panOffsetY).toFloat()
@@ -549,7 +567,7 @@ class MapController(
             var isFirst = true
 
             for (point in polyline.points) {
-                val (pixelX, pixelY) = Projection.latLngToPixel(point, zoom.toInt())
+                val (pixelX, pixelY) = ProjectionUtils.latLngToPixel(point, zoom.toInt())
                 val screenX = (pixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
                 val screenY = (pixelY - centerPixelY + viewHeight / 2 - panOffsetY).toFloat()
 
@@ -593,7 +611,7 @@ class MapController(
             // Draw main polygon outline
             var isFirst = true
             for (point in polygon.points) {
-                val (pixelX, pixelY) = Projection.latLngToPixel(point, zoom.toInt())
+                val (pixelX, pixelY) = ProjectionUtils.latLngToPixel(point, zoom.toInt())
                 val screenX = (pixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
                 val screenY = (pixelY - centerPixelY + viewHeight / 2 - panOffsetY).toFloat()
 
@@ -611,7 +629,7 @@ class MapController(
                 if (hole.size < 3) continue
                 isFirst = true
                 for (point in hole) {
-                    val (pixelX, pixelY) = Projection.latLngToPixel(point, zoom.toInt())
+                    val (pixelX, pixelY) = ProjectionUtils.latLngToPixel(point, zoom.toInt())
                     val screenX = (pixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
                     val screenY = (pixelY - centerPixelY + viewHeight / 2 - panOffsetY).toFloat()
 
@@ -641,7 +659,7 @@ class MapController(
             if (!marker.visible) continue
 
             // Convert marker position to pixel coordinates
-            val (markerPixelX, markerPixelY) = Projection.latLngToPixel(marker.position, zoom.toInt())
+            val (markerPixelX, markerPixelY) = ProjectionUtils.latLngToPixel(marker.position, zoom.toInt())
 
             // Calculate screen position
             val screenX = (markerPixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
@@ -818,11 +836,11 @@ class MapController(
         x: Float,
         y: Float,
     ): Marker? {
-        val (centerPixelX, centerPixelY) = Projection.latLngToPixel(center, zoom.toInt())
+        val (centerPixelX, centerPixelY) = ProjectionUtils.latLngToPixel(center, zoom.toInt())
 
         // Check markers in reverse order (top to bottom) for correct z-ordering
         for (marker in markers.reversed()) {
-            val (markerPixelX, markerPixelY) = Projection.latLngToPixel(marker.position, zoom.toInt())
+            val (markerPixelX, markerPixelY) = ProjectionUtils.latLngToPixel(marker.position, zoom.toInt())
 
             val screenX = (markerPixelX - centerPixelX + viewWidth / 2 - panOffsetX).toFloat()
             val screenY = (markerPixelY - centerPixelY + viewHeight / 2 - panOffsetY).toFloat()

openmapview/src/main/kotlin/de/afarber/openmapview/OpenMapView.kt

@@ -252,6 +252,24 @@ class OpenMapView
          */
         fun getCameraPosition(): CameraPosition = controller.getCameraPosition()
 
+        /**
+         * Returns a Projection object for coordinate transformations.
+         *
+         * The Projection allows you to convert between screen coordinates (in pixels)
+         * and geographic coordinates (LatLng), as well as query the visible region.
+         *
+         * Example:
+         * ```kotlin
+         * val projection = mapView.getProjection()
+         * val latLng = projection.fromScreenLocation(Point(100, 100))
+         * val screenPoint = projection.toScreenLocation(LatLng(51.5074, -0.1278))
+         * val visibleRegion = projection.getVisibleRegion()
+         * ```
+         *
+         * @return A Projection instance for the current map state
+         */
+        fun getProjection(): Projection = controller.createProjection()
+
         /**
          * Moves the camera to a new position instantly, without animation.
          *