RD-1377: Add PixelRatio related map option and Commands - Kotlin (#87)

Co-authored-by: klokantechsysadmin <[email protected]>
Co-authored-by: sasaprodribaba <[email protected]>

Author: 3 people

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/commands/navigation/GetPixelRatio.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright (c) 2025, MapTiler
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD 3-Clause
+ */
+
+package com.maptiler.maptilersdk.commands.navigation
+
+import com.maptiler.maptilersdk.bridge.MTBridge
+import com.maptiler.maptilersdk.bridge.MTCommand
+
+internal class GetPixelRatio : MTCommand {
+    override val isPrimitiveReturnType: Boolean = true
+
+    override fun toJS(): String = "${MTBridge.MAP_OBJECT}.getPixelRatio();"
+}

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/commands/navigation/SetPixelRatio.kt

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025, MapTiler
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD 3-Clause
+ */
+
+package com.maptiler.maptilersdk.commands.navigation
+
+import com.maptiler.maptilersdk.bridge.MTBridge
+import com.maptiler.maptilersdk.bridge.MTCommand
+
+internal data class SetPixelRatio(
+    val pixelRatio: Double,
+) : MTCommand {
+    override val isPrimitiveReturnType: Boolean = false
+
+    override fun toJS(): String = "${MTBridge.MAP_OBJECT}.setPixelRatio($pixelRatio);"
+}

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/map/MTMapOptions.kt

@@ -231,6 +231,15 @@ class MTMapOptions {
     var maxTileCacheZoomLevels: Double? = null
         private set
 
+    /**
+     * Overrides the device pixel ratio used for rendering.
+     *
+     * Set this to values greater than `1.0` to force high-DPI rendering on low-density devices,
+     * or lower values to favour performance over sharpness.
+     */
+    var pixelRatio: Double? = null
+        private set
+
     /**
      * Boolean indicating whether the map's pitch control with drag to rotate interaction will be disabled.
      */
@@ -493,6 +502,7 @@ class MTMapOptions {
         maptilerLogoIsVisible: Boolean? = null,
         maxTileCacheSize: Double? = null,
         maxTileCacheZoomLevels: Double? = null,
+        pixelRatio: Double? = null,
         shouldPitchWithRotate: Boolean? = null,
         shouldRefreshExpiredTiles: Boolean? = null,
         shouldRenderWorldCopies: Boolean? = null,
@@ -539,6 +549,7 @@ class MTMapOptions {
         this.maptilerLogoIsVisible = maptilerLogoIsVisible
         this.maxTileCacheSize = maxTileCacheSize
         this.maxTileCacheZoomLevels = maxTileCacheZoomLevels
+        this.pixelRatio = pixelRatio
         this.shouldPitchWithRotate = shouldPitchWithRotate
         this.shouldRefreshExpiredTiles = shouldRefreshExpiredTiles
         this.shouldRenderWorldCopies = shouldRenderWorldCopies

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/map/MTMapViewController.kt

@@ -382,6 +382,11 @@ class MTMapViewController(
 
     override suspend fun getRenderWorldCopies(): Boolean = navigableWorker.getRenderWorldCopies()
 
+    /**
+     * Returns the pixel ratio currently used to render the map.
+     */
+    override suspend fun getPixelRatio(): Double = navigableWorker.getPixelRatio()
+
     /**
      * Returns the elevation of the map's center point in meters above sea level.
      */
@@ -416,6 +421,13 @@ class MTMapViewController(
     override fun setIsCenterClampedToGround(isCenterClampedToGround: Boolean) =
         navigableWorker.setIsCenterClampedToGround(isCenterClampedToGround)
 
+    /**
+     * Overrides the pixel ratio used to render the map.
+     *
+     * @param pixelRatio Desired pixel ratio. Values above `1.0` improve sharpness, values below trade detail for performance.
+     */
+    override fun setPixelRatio(pixelRatio: Double) = navigableWorker.setPixelRatio(pixelRatio)
+
     /**
      * Sets the elevation of the map's center point, in meters above sea level.
      *

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/map/workers/navigable/MTNavigable.kt

@@ -116,6 +116,11 @@ interface MTNavigable {
      */
     suspend fun getRenderWorldCopies(): Boolean
 
+    /**
+     * Returns the pixel ratio currently used to render the map.
+     */
+    suspend fun getPixelRatio(): Double
+
     /**
      * Returns the elevation of the map's center point in meters above sea level.
      */
@@ -147,6 +152,13 @@ interface MTNavigable {
      */
     fun setIsCenterClampedToGround(isCenterClampedToGround: Boolean)
 
+    /**
+     * Overrides the pixel ratio used to render the map.
+     *
+     * @param pixelRatio Desired pixel ratio. Values above `1.0` improve sharpness, values below trade detail for performance.
+     */
+    fun setPixelRatio(pixelRatio: Double)
+
     /**
      * Sets the elevation of the map's center point, in meters above sea level.
      *

MapTilerSDK/src/main/java/com/maptiler/maptilersdk/map/workers/navigable/NavigableWorker.kt

@@ -19,6 +19,7 @@ import com.maptiler.maptilersdk.commands.navigation.GetCenterElevation
 import com.maptiler.maptilersdk.commands.navigation.GetMaxPitch
 import com.maptiler.maptilersdk.commands.navigation.GetMinPitch
 import com.maptiler.maptilersdk.commands.navigation.GetPitch
+import com.maptiler.maptilersdk.commands.navigation.GetPixelRatio
 import com.maptiler.maptilersdk.commands.navigation.GetRenderWorldCopies
 import com.maptiler.maptilersdk.commands.navigation.GetRoll
 import com.maptiler.maptilersdk.commands.navigation.JumpTo
@@ -31,6 +32,7 @@ import com.maptiler.maptilersdk.commands.navigation.SetCenterClampedToGround
 import com.maptiler.maptilersdk.commands.navigation.SetCenterElevation
 import com.maptiler.maptilersdk.commands.navigation.SetPadding
 import com.maptiler.maptilersdk.commands.navigation.SetPitch
+import com.maptiler.maptilersdk.commands.navigation.SetPixelRatio
 import com.maptiler.maptilersdk.commands.navigation.SetRoll
 import com.maptiler.maptilersdk.helpers.JsonConfig
 import com.maptiler.maptilersdk.map.LngLat
@@ -233,6 +235,19 @@ internal class NavigableWorker(
         }
     }
 
+    override suspend fun getPixelRatio(): Double {
+        val returnTypeValue =
+            bridge.execute(
+                GetPixelRatio(),
+            )
+
+        return when (returnTypeValue) {
+            is DoubleValue -> returnTypeValue.value
+            is StringValue -> returnTypeValue.value.toDoubleOrNull() ?: 0.0
+            else -> 0.0
+        }
+    }
+
     override suspend fun getCenterElevation(): Double {
         val returnTypeValue =
             bridge.execute(
@@ -274,6 +289,21 @@ internal class NavigableWorker(
         }
     }
 
+    override fun setPixelRatio(pixelRatio: Double) {
+        val sanitized =
+            if (pixelRatio.isFinite()) {
+                pixelRatio.coerceAtLeast(0.0)
+            } else {
+                0.0
+            }
+
+        scope.launch {
+            bridge.execute(
+                SetPixelRatio(sanitized),
+            )
+        }
+    }
+
     override fun setCenterElevation(elevation: Double) {
         scope.launch {
             bridge.execute(

MapTilerSDK/src/test/java/com/maptiler/maptilersdk/NavigationTests.kt

@@ -13,13 +13,15 @@ import com.maptiler.maptilersdk.commands.navigation.GetMaxPitch
 import com.maptiler.maptilersdk.commands.navigation.GetMaxZoom
 import com.maptiler.maptilersdk.commands.navigation.GetMinPitch
 import com.maptiler.maptilersdk.commands.navigation.GetMinZoom
+import com.maptiler.maptilersdk.commands.navigation.GetPixelRatio
 import com.maptiler.maptilersdk.commands.navigation.GetRenderWorldCopies
 import com.maptiler.maptilersdk.commands.navigation.GetZoom
 import com.maptiler.maptilersdk.commands.navigation.PanBy
 import com.maptiler.maptilersdk.commands.navigation.PanTo
 import com.maptiler.maptilersdk.commands.navigation.Project
 import com.maptiler.maptilersdk.commands.navigation.SetMaxZoom
 import com.maptiler.maptilersdk.commands.navigation.SetMinZoom
+import com.maptiler.maptilersdk.commands.navigation.SetPixelRatio
 import com.maptiler.maptilersdk.commands.navigation.SetZoom
 import com.maptiler.maptilersdk.commands.navigation.ZoomIn
 import com.maptiler.maptilersdk.commands.navigation.ZoomOut
@@ -39,6 +41,11 @@ class NavigationTests {
         assertEquals("${MTBridge.MAP_OBJECT}.getRenderWorldCopies();", command.toJS())
     }
 
+    @Test fun getPixelRatioToJS_ReturnsCorrectJSString() {
+        val command = GetPixelRatio()
+        assertEquals("${MTBridge.MAP_OBJECT}.getPixelRatio();", command.toJS())
+    }
+
     @Test fun getCenterElevationToJS_ReturnsCorrectJSString() {
         val command = GetCenterElevation()
         assertEquals("${MTBridge.MAP_OBJECT}.getCenterElevation();", command.toJS())
@@ -94,6 +101,11 @@ class NavigationTests {
         assertEquals("${MTBridge.MAP_OBJECT}.setMinZoom(1.0);", command.toJS())
     }
 
+    @Test fun setPixelRatioToJS_ReturnsCorrectJSString() {
+        val command = SetPixelRatio(2.5)
+        assertEquals("${MTBridge.MAP_OBJECT}.setPixelRatio(2.5);", command.toJS())
+    }
+
     @Test fun panByToJS_ReturnsCorrectJSString() {
         val offset = MTPoint(1.0, 1.0)
         val command = PanBy(offset)