expo-gaode-map 2.2.32 → 2.2.33

package/README.md

@@ -32,7 +32,6 @@
 - ✅ 默认实现了优化地图加载，减少内存占用
 - ✅ 几何运算（距离/面积、点在圆/多边形、质心/边界、路径长度/抽稀、GeoHash、瓦片/像素坐标转换、最近点、热力网格等，由 C++ 实现）
 - ✅ 丰富的使用案例
-- ✅ 提供AI编程助手，帮助开发者快速集成和使用（https://TomWq.github.io/expo-gaode-map/guide/ai-skills.html）
 - ✅ 更多内容和功能请查看 [完整文档](https://TomWq.github.io/expo-gaode-map/)
 
 
@@ -48,9 +47,9 @@
 > - 如果你的项目使用 **Expo SDK 54 及以上**，请安装 默认的 版本。
 > - 如果你的项目使用 **Expo SDK 53 及以下**（如 50, 51, 52, 53），请使用 **V1** 版本（Tag: `v1`）。
 >   ```bash
->   npm install expo-gaode-map@v1
+>   npm install expo-gaode-map@v1.2.3
 >   ```
->   **说明**：V1 版本除了不支持**世界地图**功能外，其余 API 与 V2 (Latest) 版本完全一致。
+>   **说明**：V1 版本不支持世界地图，只是为了兼容佬项目使用，请尽快升级你的 expo 版本到 54 及以上，使用最新的 V2 版本。
 
 ### 方案一：仅使用地图和定位（核心包）
 

package/android/src/main/cpp/cluster_jni.cpp

@@ -606,6 +606,62 @@ Java_expo_modules_gaodemap_utils_GeometryUtils_nativeCalculatePathBounds(
 #endif
 }
 
+extern "C" JNIEXPORT jdouble JNICALL
+Java_expo_modules_gaodemap_utils_GeometryUtils_nativeCalculateFitZoom(
+    JNIEnv* env,
+    jclass,
+    jdoubleArray latitudes,
+    jdoubleArray longitudes,
+    jdouble viewportWidthPx,
+    jdouble viewportHeightPx,
+    jdouble paddingPx,
+    jint minZoom,
+    jint maxZoom
+) {
+#if GAODE_HAVE_JNI
+    if (!latitudes || !longitudes) {
+        return static_cast<jdouble>(minZoom);
+    }
+
+    const jsize countLat = env->GetArrayLength(latitudes);
+    const jsize countLon = env->GetArrayLength(longitudes);
+    if (countLat == 0 || countLat != countLon) {
+        return static_cast<jdouble>(minZoom);
+    }
+
+    jdouble* latValues = env->GetDoubleArrayElements(latitudes, nullptr);
+    jdouble* lonValues = env->GetDoubleArrayElements(longitudes, nullptr);
+
+    std::vector<gaodemap::GeoPoint> points;
+    points.reserve(static_cast<size_t>(countLat));
+    for (jsize i = 0; i < countLat; ++i) {
+        points.push_back({latValues[i], lonValues[i]});
+    }
+
+    env->ReleaseDoubleArrayElements(latitudes, latValues, JNI_ABORT);
+    env->ReleaseDoubleArrayElements(longitudes, lonValues, JNI_ABORT);
+
+    return static_cast<jdouble>(gaodemap::calculateFitZoomForPoints(
+        points,
+        static_cast<double>(viewportWidthPx),
+        static_cast<double>(viewportHeightPx),
+        static_cast<double>(paddingPx),
+        static_cast<int>(minZoom),
+        static_cast<int>(maxZoom)
+    ));
+#else
+    (void)env;
+    (void)latitudes;
+    (void)longitudes;
+    (void)viewportWidthPx;
+    (void)viewportHeightPx;
+    (void)paddingPx;
+    (void)minZoom;
+    (void)maxZoom;
+    return 3.0;
+#endif
+}
+
 extern "C" JNIEXPORT jdoubleArray JNICALL
 Java_expo_modules_gaodemap_utils_GeometryUtils_nativeCalculateCentroid(
     JNIEnv* env,

package/android/src/main/java/expo/modules/gaodemap/ExpoGaodeMapModule.kt

@@ -51,7 +51,7 @@ class ExpoGaodeMapModule : Module() {
         } else if (!SDKInitializer.isPrivacyReady()) {
           throw expo.modules.kotlin.exception.CodedException(
             "PRIVACY_NOT_AGREED",
-            "隐私协议未完成确认，请先调用 setPrivacyShow/setPrivacyAgree",
+            "隐私协议未完成确认，请先调用 setPrivacyConfig",
             null
           )
         } else {
@@ -69,12 +69,20 @@ class ExpoGaodeMapModule : Module() {
       }
     }
 
-    Function("setPrivacyShow") { hasShow: Boolean, hasContainsPrivacy: Boolean ->
-      SDKInitializer.setPrivacyShow(appContext.reactContext!!, hasShow, hasContainsPrivacy)
-    }
+    Function("setPrivacyConfig") { config: Map<String, Any?> ->
+      val hasShow = config["hasShow"] as? Boolean ?: false
+      val hasContainsPrivacy = config["hasContainsPrivacy"] as? Boolean ?: hasShow
+      val hasAgree = config["hasAgree"] as? Boolean ?: false
+      val privacyVersion = config["privacyVersion"] as? String
 
-    Function("setPrivacyAgree") { hasAgree: Boolean ->
-      SDKInitializer.setPrivacyAgree(appContext.reactContext!!, hasAgree)
+      SDKInitializer.setPrivacyConfig(
+        appContext.reactContext!!,
+        hasShow,
+        hasContainsPrivacy,
+        hasAgree,
+        privacyVersion,
+        config.containsKey("privacyVersion")
+      )
     }
 
     Function("setPrivacyVersion") { version: String ->
@@ -187,6 +195,37 @@ class ExpoGaodeMapModule : Module() {
       }
     }
 
+    /**
+     * 根据多个坐标点计算可同时可见的推荐缩放级别
+     * @param points 坐标点（至少 1 个）
+     * @param viewportWidthPx 视口宽度（像素）
+     * @param viewportHeightPx 视口高度（像素）
+     * @param paddingPx 内边距（像素）
+     * @param minZoom 最小缩放
+     * @param maxZoom 最大缩放
+     */
+    Function("calculateFitZoom") {
+      points: List<Any>?,
+      viewportWidthPx: Double?,
+      viewportHeightPx: Double?,
+      paddingPx: Double?,
+      minZoom: Int?,
+      maxZoom: Int? ->
+      val normalized = LatLngParser.parseLatLngList(points)
+      val safeMinZoom = minZoom ?: 3
+      val safeMaxZoom = maxZoom ?: 20
+      if (normalized.isEmpty()) return@Function safeMinZoom.toDouble()
+
+      GeometryUtils.calculateFitZoom(
+        normalized,
+        viewportWidthPx ?: 390.0,
+        viewportHeightPx ?: 844.0,
+        paddingPx ?: 48.0,
+        safeMinZoom,
+        safeMaxZoom
+      )
+    }
+
     /**
      * 计算多边形面积
      * @param points 多边形顶点坐标数组，支持嵌套数组（多边形空洞）

package/android/src/main/java/expo/modules/gaodemap/ExpoGaodeMapOfflineModule.kt

@@ -42,7 +42,7 @@ class ExpoGaodeMapOfflineModule : Module() {
     if (!SDKInitializer.isPrivacyReady()) {
       throw CodedException(
         "PRIVACY_NOT_AGREED",
-        "隐私协议未完成确认，请先调用 setPrivacyShow/setPrivacyAgree",
+        "隐私协议未完成确认，请先调用 setPrivacyConfig",
         null
       )
     }

package/android/src/main/java/expo/modules/gaodemap/modules/SDKInitializer.kt

@@ -56,22 +56,6 @@ object SDKInitializer {
         applyPrivacyState(appContext)
     }
 
-    fun setPrivacyShow(context: Context, hasShow: Boolean, hasContainsPrivacy: Boolean) {
-        privacyShown = hasShow
-        privacyContains = hasContainsPrivacy
-        val appContext = resolveContext(context)
-        persistState(appContext)
-        applyPrivacyState(appContext)
-    }
-
-    fun setPrivacyAgree(context: Context, hasAgree: Boolean) {
-        privacyAgreed = hasAgree
-        agreedPrivacyVersion = if (hasAgree) privacyVersion else null
-        val appContext = resolveContext(context)
-        persistState(appContext)
-        applyPrivacyState(appContext)
-    }
-
     fun setPrivacyVersion(context: Context, version: String) {
         val sanitizedVersion = version.trim().takeIf { it.isNotEmpty() }
         privacyVersion = sanitizedVersion
@@ -89,6 +73,28 @@ object SDKInitializer {
         applyPrivacyState(appContext)
     }
 
+    fun setPrivacyConfig(
+        context: Context,
+        hasShow: Boolean,
+        hasContainsPrivacy: Boolean,
+        hasAgree: Boolean,
+        version: String?,
+        shouldUpdateVersion: Boolean
+    ) {
+        val appContext = resolveContext(context)
+
+        if (shouldUpdateVersion) {
+            privacyVersion = version?.trim()?.takeIf { it.isNotEmpty() }
+        }
+        privacyShown = hasShow
+        privacyContains = hasContainsPrivacy
+        privacyAgreed = hasAgree
+        agreedPrivacyVersion = if (hasAgree) privacyVersion else null
+
+        persistState(appContext)
+        applyPrivacyState(appContext)
+    }
+
     fun resetPrivacyConsent(context: Context) {
         val appContext = resolveContext(context)
         clearConsentPersistedState(appContext, keepCurrentVersion = false)
@@ -137,7 +143,7 @@ object SDKInitializer {
         if (!isPrivacyReady()) {
             throw expo.modules.kotlin.exception.CodedException(
                 "PRIVACY_NOT_AGREED",
-                "隐私协议未完成确认，请先调用 setPrivacyShow/setPrivacyAgree",
+                "隐私协议未完成确认，请先调用 setPrivacyConfig",
                 null
             )
         }

package/android/src/main/java/expo/modules/gaodemap/overlays/MarkerBitmapRenderer.kt

@@ -51,8 +51,8 @@ internal object MarkerBitmapRenderer {
 
     fun resolveSnapshot(
         container: ViewGroup,
-        customViewWidth: Int,
-        customViewHeight: Int,
+        contentWidth: Int,
+        contentHeight: Int,
         cacheKey: String?,
     ): MarkerBitmapSnapshot? {
         if (container.childCount == 0) {
@@ -76,17 +76,19 @@ internal object MarkerBitmapRenderer {
                 ?: child.measuredHeight
                 ?: 0
 
-        val finalWidth = if (measuredWidth > 0) measuredWidth else customViewWidth
-        val finalHeight = if (measuredHeight > 0) measuredHeight else customViewHeight
+        val finalWidth = if (measuredWidth > 0) measuredWidth else contentWidth
+        val finalHeight = if (measuredHeight > 0) measuredHeight else contentHeight
 
         if (finalWidth <= 0 || finalHeight <= 0) {
             return null
         }
 
-        val fingerprint = computeViewFingerprint(container)
+        // 业务层已经显式传入稳定 cacheKey 时，直接信任它。
+        // 否则点击、重排或 drawable 实例抖动仍会让 key 变化，导致 children marker 反复重建。
+        val keyPart = cacheKey?.takeIf { it.isNotBlank() } ?: computeViewFingerprint(container)
 
         return MarkerBitmapSnapshot(
-            keyPart = cacheKey?.let { "$it|$fingerprint" } ?: fingerprint,
+            keyPart = keyPart,
             width = finalWidth,
             height = finalHeight,
         )
@@ -95,8 +97,8 @@ internal object MarkerBitmapRenderer {
     fun createBitmap(
         container: ViewGroup,
         snapshot: MarkerBitmapSnapshot,
-        customViewWidth: Int,
-        customViewHeight: Int,
+        contentWidth: Int,
+        contentHeight: Int,
         mainHandler: Handler,
     ): Bitmap? {
         IconBitmapCache.get(snapshot.fullCacheKey)?.let { return it }
@@ -107,8 +109,8 @@ internal object MarkerBitmapRenderer {
                     container = container,
                     finalWidth = snapshot.width,
                     finalHeight = snapshot.height,
-                    customViewWidth = customViewWidth,
-                    customViewHeight = customViewHeight,
+                    contentWidth = contentWidth,
+                    contentHeight = contentHeight,
                 )
             } else {
                 val latch = CountDownLatch(1)
@@ -120,8 +122,8 @@ internal object MarkerBitmapRenderer {
                                 container = container,
                                 finalWidth = snapshot.width,
                                 finalHeight = snapshot.height,
-                                customViewWidth = customViewWidth,
-                                customViewHeight = customViewHeight,
+                                contentWidth = contentWidth,
+                                contentHeight = contentHeight,
                             )
                     } finally {
                         latch.countDown()
@@ -227,7 +229,19 @@ internal object MarkerBitmapRenderer {
                     } else {
                         val drawable = v.drawable
                         if (drawable != null) {
-                            sb.append("[drawableHash=").append(drawable.hashCode()).append("]")
+                            val constantState = drawable.constantState
+                            if (constantState != null) {
+                                sb.append("[drawableState=").append(constantState.hashCode()).append("]")
+                            } else {
+                                sb
+                                    .append("[drawable=")
+                                    .append(drawable.javaClass.simpleName)
+                                    .append(':')
+                                    .append(drawable.intrinsicWidth)
+                                    .append('x')
+                                    .append(drawable.intrinsicHeight)
+                                    .append("]")
+                            }
                         }
                     }
                 }
@@ -248,8 +262,8 @@ internal object MarkerBitmapRenderer {
         container: ViewGroup,
         finalWidth: Int,
         finalHeight: Int,
-        customViewWidth: Int,
-        customViewHeight: Int,
+        contentWidth: Int,
+        contentHeight: Int,
     ): Bitmap? {
         try {
             val childView = container.getChildAt(0) ?: return null
@@ -271,7 +285,7 @@ internal object MarkerBitmapRenderer {
             val canvas = Canvas(bitmap)
             childView.draw(canvas)
 
-            val shouldTrimTransparentPadding = customViewWidth <= 0 && customViewHeight <= 0
+            val shouldTrimTransparentPadding = contentWidth <= 0 && contentHeight <= 0
             return if (shouldTrimTransparentPadding) trimTransparentPadding(bitmap) else bitmap
         } catch (_: Exception) {
             return null

package/android/src/main/java/expo/modules/gaodemap/overlays/MarkerView.kt

@@ -82,16 +82,16 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
     override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
         val selfParams = this.layoutParams
         if (selfParams == null || selfParams !is LayoutParams) {
-            val width = if (customViewWidth > 0) {
-                customViewWidth
+            val width = if (contentWidth > 0) {
+                contentWidth
             } else if (selfParams != null && selfParams.width > 0) {
                 selfParams.width
             } else {
                 LayoutParams.WRAP_CONTENT
             }
 
-            val height = if (customViewHeight > 0) {
-                customViewHeight
+            val height = if (contentHeight > 0) {
+                contentHeight
             } else if (selfParams != null && selfParams.height > 0) {
                 selfParams.height
             } else {
@@ -123,12 +123,12 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
         val fallbackHeightSize = resolveExplicitMeasureSize(parentHeightSize, false)
 
         val contentWidthSpec = when {
-            customViewWidth > 0 -> MeasureSpec.makeMeasureSpec(customViewWidth, MeasureSpec.EXACTLY)
+            contentWidth > 0 -> MeasureSpec.makeMeasureSpec(contentWidth, MeasureSpec.EXACTLY)
             fallbackWidthSize > 0 -> MeasureSpec.makeMeasureSpec(fallbackWidthSize, MeasureSpec.AT_MOST)
             else -> MeasureSpec.makeMeasureSpec(1, MeasureSpec.EXACTLY)
         }
         val contentHeightSpec = when {
-            customViewHeight > 0 -> MeasureSpec.makeMeasureSpec(customViewHeight, MeasureSpec.EXACTLY)
+            contentHeight > 0 -> MeasureSpec.makeMeasureSpec(contentHeight, MeasureSpec.EXACTLY)
             fallbackHeightSize > 0 -> MeasureSpec.makeMeasureSpec(fallbackHeightSize, MeasureSpec.AT_MOST)
             else -> MeasureSpec.makeMeasureSpec(1, MeasureSpec.EXACTLY)
         }
@@ -158,13 +158,13 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
             measuredContentHeight = max(measuredContentHeight, childBounds?.height() ?: child.measuredHeight)
         }
 
-        val desiredWidth = if (customViewWidth > 0) {
-            customViewWidth
+        val desiredWidth = if (contentWidth > 0) {
+            contentWidth
         } else {
             measuredContentWidth + paddingLeft + paddingRight
         }
-        val desiredHeight = if (customViewHeight > 0) {
-            customViewHeight
+        val desiredHeight = if (contentHeight > 0) {
+            contentHeight
         } else {
             measuredContentHeight + paddingTop + paddingBottom
         }
@@ -218,8 +218,8 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
     private var pendingLongitude: Double? = null  // 临时存储经度
     private var iconWidth: Int = 0  // 用于自定义图标的宽度
     private var iconHeight: Int = 0  // 用于自定义图标的高度
-    private var customViewWidth: Int = 0  // 用于自定义视图（children）的宽度
-    private var customViewHeight: Int = 0  // 用于自定义视图（children）的高度
+    private var contentWidth: Int = 0  // 用于自定义视图（children）的宽度
+    private var contentHeight: Int = 0  // 用于自定义视图（children）的高度
     private val mainHandler = Handler(Looper.getMainLooper())
     private var isRemoving = false  // 标记是否正在被移除
     private var pendingMarkerIconUpdate: Runnable? = null
@@ -479,7 +479,7 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
             return
         }
 
-        invalidateAppliedCustomMarkerCaches()
+        invalidateAppliedCustomMarkerCaches(clearGlobalCache = true)
         cacheKey = key
         updateMarkerIcon()
     }
@@ -738,32 +738,32 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
     }
 
     /**
-     * 设置自定义视图宽度（用于 children 属性）
+     * 设置内容宽度（用于 children 属性）
      * 注意：React Native 传入的是 DP 值，需要转换为 PX
      */
-    fun setCustomViewWidth(width: Int) {
+    fun setContentWidth(width: Int) {
         val density = context.resources.displayMetrics.density
         val resolvedWidth = (width * density).toInt()
-        if (customViewWidth == resolvedWidth) {
+        if (contentWidth == resolvedWidth) {
             return
         }
 
-        customViewWidth = resolvedWidth
+        contentWidth = resolvedWidth
         markCustomMarkerContentDirty()
     }
 
     /**
-     * 设置自定义视图高度（用于 children 属性）
+     * 设置内容高度（用于 children 属性）
      * 注意：React Native 传入的是 DP 值，需要转换为 PX
      */
-    fun setCustomViewHeight(height: Int) {
+    fun setContentHeight(height: Int) {
         val density = context.resources.displayMetrics.density
         val resolvedHeight = (height * density).toInt()
-        if (customViewHeight == resolvedHeight) {
+        if (contentHeight == resolvedHeight) {
             return
         }
 
-        customViewHeight = resolvedHeight
+        contentHeight = resolvedHeight
         markCustomMarkerContentDirty()
     }
 
@@ -904,8 +904,8 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
         return MarkerBitmapRenderer.createBitmap(
             container = this,
             snapshot = resolvedSnapshot,
-            customViewWidth = customViewWidth,
-            customViewHeight = customViewHeight,
+            contentWidth = contentWidth,
+            contentHeight = contentHeight,
             mainHandler = mainHandler,
         )
     }
@@ -997,10 +997,12 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
         }
     }
 
-    private fun invalidateAppliedCustomMarkerCaches() {
+    private fun invalidateAppliedCustomMarkerCaches(clearGlobalCache: Boolean = false) {
         val key = lastAppliedCustomMarkerKey ?: return
-        BitmapDescriptorCache.remove(key)
-        IconBitmapCache.remove(key)
+        if (clearGlobalCache) {
+            BitmapDescriptorCache.remove(key)
+            IconBitmapCache.remove(key)
+        }
         lastAppliedCustomMarkerKey = null
     }
 
@@ -1009,7 +1011,10 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
             return
         }
 
-        invalidateAppliedCustomMarkerCaches()
+        // children（尤其是 Image）异步加载完成后，需要强制淘汰当前 marker 已应用的位图缓存，
+        // 否则同一个 cacheKey 会一直命中“占位态”的旧 bitmap，表现为灰块/蒙层不更新。
+        // 这里仅清理当前 marker 已应用的 key，不会影响其它 marker。
+        invalidateAppliedCustomMarkerCaches(clearGlobalCache = true)
         if (marker != null) {
             scheduleMarkerIconUpdate(delayMs)
         }
@@ -1048,8 +1053,8 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
     private fun resolveMarkerBitmapSnapshot(): MarkerBitmapSnapshot? =
         MarkerBitmapRenderer.resolveSnapshot(
             container = this,
-            customViewWidth = customViewWidth,
-            customViewHeight = customViewHeight,
+            contentWidth = contentWidth,
+            contentHeight = contentHeight,
             cacheKey = cacheKey,
         )
 
@@ -1059,13 +1064,13 @@ class MarkerView(context: Context, appContext: AppContext) : ExpoView(context, a
       val childCountBefore = childCount
 
       val sourceWidth = when {
-        customViewWidth > 0 -> customViewWidth
+        contentWidth > 0 -> contentWidth
         params?.width != null && params.width > 0 -> params.width
         else -> LayoutParams.WRAP_CONTENT
       }
 
       val sourceHeight = when {
-        customViewHeight > 0 -> customViewHeight
+        contentHeight > 0 -> contentHeight
         params?.height != null && params.height > 0 -> params.height
         else -> LayoutParams.WRAP_CONTENT
       }

package/android/src/main/java/expo/modules/gaodemap/overlays/MarkerViewModule.kt

@@ -69,13 +69,13 @@ class MarkerViewModule : Module() {
       Prop<Int>("iconHeight") { view, height ->
         view.setIconHeight(height)
       }
-      // 自定义视图宽度
-      Prop<Int>("customViewWidth") { view, width ->
-        view.setCustomViewWidth(width)
+      // 内容宽度
+      Prop<Int>("contentWidth") { view, width ->
+        view.setContentWidth(width)
       }
-      // 自定义视图高度
-      Prop<Int>("customViewHeight") { view, height ->
-        view.setCustomViewHeight(height)
+      // 内容高度
+      Prop<Int>("contentHeight") { view, height ->
+        view.setContentHeight(height)
       }
       // 缓存key
       Prop<String?>("cacheKey") { view, key ->

package/android/src/main/java/expo/modules/gaodemap/utils/GeometryUtils.kt

@@ -83,6 +83,16 @@ object GeometryUtils {
         longitudes: DoubleArray
     ): DoubleArray?
 
+    private external fun nativeCalculateFitZoom(
+        latitudes: DoubleArray,
+        longitudes: DoubleArray,
+        viewportWidthPx: Double,
+        viewportHeightPx: Double,
+        paddingPx: Double,
+        minZoom: Int,
+        maxZoom: Int
+    ): Double
+
     private external fun nativeEncodeGeoHash(
         lat: Double,
         lon: Double,
@@ -401,6 +411,99 @@ object GeometryUtils {
         }
     }
 
+    private fun mercatorX01(lon: Double): Double {
+        var wrapped = (lon + 180.0) % 360.0
+        if (wrapped < 0.0) wrapped += 360.0
+        return wrapped / 360.0
+    }
+
+    private fun mercatorY01(lat: Double): Double {
+        val clamped = lat.coerceIn(-85.05112878, 85.05112878)
+        val rad = Math.toRadians(clamped)
+        val y = (1.0 - asinh(tan(rad)) / Math.PI) * 0.5
+        return y.coerceIn(0.0, 1.0)
+    }
+
+    private fun wrappedSpan01(values: List<Double>): Double {
+        if (values.size <= 1) return 0.0
+        val sorted = values.sorted()
+        var maxGap = 0.0
+        for (i in 0 until sorted.size - 1) {
+            maxGap = max(maxGap, sorted[i + 1] - sorted[i])
+        }
+        maxGap = max(maxGap, sorted.first() + 1.0 - sorted.last())
+        return (1.0 - maxGap).coerceAtLeast(0.0)
+    }
+
+    private fun fallbackCalculateFitZoom(
+        points: List<LatLng>,
+        viewportWidthPx: Double,
+        viewportHeightPx: Double,
+        paddingPx: Double,
+        minZoom: Int,
+        maxZoom: Int
+    ): Double {
+        if (points.isEmpty()) return minZoom.toDouble()
+        if (points.size == 1) return maxZoom.toDouble()
+
+        val safeMinZoom = min(minZoom, maxZoom)
+        val safeMaxZoom = max(minZoom, maxZoom)
+        val safeWidth = if (viewportWidthPx > 1.0) viewportWidthPx else 390.0
+        val safeHeight = if (viewportHeightPx > 1.0) viewportHeightPx else 844.0
+        val safePadding = max(0.0, paddingPx)
+        val availableWidth = max(1.0, safeWidth - safePadding * 2.0)
+        val availableHeight = max(1.0, safeHeight - safePadding * 2.0)
+
+        val xs = points.map { mercatorX01(it.longitude) }
+        val ys = points.map { mercatorY01(it.latitude) }
+        val spanX = wrappedSpan01(xs)
+        val spanY = (ys.maxOrNull() ?: 0.0) - (ys.minOrNull() ?: 0.0)
+        val tileSize = 256.0
+
+        val zoomX = if (spanX <= 1e-12) safeMaxZoom.toDouble() else log2(availableWidth / (tileSize * spanX))
+        val zoomY = if (spanY <= 1e-12) safeMaxZoom.toDouble() else log2(availableHeight / (tileSize * spanY))
+        val fitZoom = min(zoomX, zoomY)
+        if (!fitZoom.isFinite()) return safeMinZoom.toDouble()
+        return fitZoom.coerceIn(safeMinZoom.toDouble(), safeMaxZoom.toDouble())
+    }
+
+    fun calculateFitZoom(
+        points: List<LatLng>,
+        viewportWidthPx: Double,
+        viewportHeightPx: Double,
+        paddingPx: Double,
+        minZoom: Int,
+        maxZoom: Int
+    ): Double {
+        if (points.isEmpty()) return minZoom.toDouble()
+        return try {
+            val latitudes = DoubleArray(points.size)
+            val longitudes = DoubleArray(points.size)
+            for (i in points.indices) {
+                latitudes[i] = points[i].latitude
+                longitudes[i] = points[i].longitude
+            }
+            nativeCalculateFitZoom(
+                latitudes,
+                longitudes,
+                viewportWidthPx,
+                viewportHeightPx,
+                paddingPx,
+                minZoom,
+                maxZoom
+            )
+        } catch (_: Throwable) {
+            fallbackCalculateFitZoom(
+                points,
+                viewportWidthPx,
+                viewportHeightPx,
+                paddingPx,
+                minZoom,
+                maxZoom
+            )
+        }
+    }
+
     fun encodeGeoHash(point: LatLng, precision: Int): String {
         return try {
             nativeEncodeGeoHash(point.latitude, point.longitude, precision)