@maydon_tech/react-native-nitro-maps 0.1.4 → 0.2.0

package/android/src/main/kotlin/com/margelo/nitro/nitromap/providers/google/GoogleMapProvider+Clustering.kt

@@ -0,0 +1,524 @@
+package com.margelo.nitro.nitromap.providers.google
+
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import com.google.android.gms.maps.model.BitmapDescriptorFactory
+import com.google.android.gms.maps.model.LatLng
+import com.google.android.gms.maps.model.LatLngBounds
+import com.google.android.gms.maps.model.Marker
+import com.google.android.gms.maps.model.MarkerOptions
+import com.margelo.nitro.nitromap.*
+import com.margelo.nitro.nitromap.clustering.ClusteringManager
+import com.margelo.nitro.nitromap.clustering.NitroClusterEngine
+import kotlin.math.*
+
+/**
+ * Clustering pipeline for GoogleMapProvider.
+ * Mirrors iOS GoogleMapProvider+Clustering.swift (~445 lines).
+ *
+ * Pipeline:
+ *   1. Query visible region + renderBuffer expansion
+ *   2. Call ClusteringManager.cluster() → C++ Supercluster result
+ *   3. Build render items (clusters + singles)
+ *   4. Apply strategy (supercluster vs hideOnOverlap)
+ *   5. Render new markers BEFORE removing old ones (prevents flicker)
+ *   6. Handle selected marker exclusion from clusters
+ */
+
+// ============================================================================
+// MARK: - Render Item (internal to clustering pipeline)
+// ============================================================================
+
+private data class RenderItem(
+    val latitude: Double,
+    val longitude: Double,
+    val kind: RenderKind,
+    val iconWidth: Double,
+    val iconHeight: Double,
+    val priority: Int  // Higher = more important (clusters > singles)
+)
+
+private sealed class RenderKind {
+    data class Cluster(
+        val markerIds: List<String>,
+        val count: Int,
+        val iconSize: Double
+    ) : RenderKind()
+
+    data class Single(val markerId: String) : RenderKind()
+}
+
+// ============================================================================
+// MARK: - Clustering Pipeline
+// ============================================================================
+
+/** Propagate config to ClusteringManager + re-cluster (mirrors iOS updateClusterConfig) */
+fun GoogleMapProvider.updateClusterConfig() {
+    clusteringManager?.clusterConfig = clusterConfig
+    performClustering()
+}
+
+/** Debounced clustering — fires after 100ms of silence */
+fun GoogleMapProvider.performClustering() {
+    clusteringManager?.debounce {
+        performClusteringImmediate()
+    }
+}
+
+/** Throttled clustering — fires at most once per interval during gestures */
+fun GoogleMapProvider.performClusteringThrottled() {
+    if (throttleActive) return
+
+    performClusteringImmediate()
+
+    val intervalMs = (clusterConfig?.throttleInterval ?: 150.0).toLong()
+    throttleActive = true
+    Handler(Looper.getMainLooper()).postDelayed({
+        throttleActive = false
+    }, intervalMs)
+}
+
+/** Full clustering pipeline */
+fun GoogleMapProvider.performClusteringImmediate() {
+    val map = googleMap ?: return
+    val manager = clusteringManager ?: return
+    val mapView = currentMapView ?: return
+
+    val width = mapView.width.toDouble()
+    val height = mapView.height.toDouble()
+    if (width <= 0 || height <= 0) return
+
+    val enabled = clusterConfig?.enabled ?: true
+    if (!enabled) {
+        clearRenderedClusterMarkers()
+        renderAllMarkersIndividually()
+        return
+    }
+
+    // --- Phase 1: Query region with renderBuffer expansion ---
+    val visibleRegion = map.projection.visibleRegion
+    val bounds = LatLngBounds.builder()
+        .include(visibleRegion.nearLeft)
+        .include(visibleRegion.nearRight)
+        .include(visibleRegion.farLeft)
+        .include(visibleRegion.farRight)
+        .build()
+
+    val zoom = map.cameraPosition.zoom.toDouble()
+    val padding = clusterConfig?.renderBuffer ?: 0.0
+    val latSpan = bounds.northeast.latitude - bounds.southwest.latitude
+    val lonSpan = bounds.northeast.longitude - bounds.southwest.longitude
+
+    val queryMinLat = bounds.southwest.latitude - latSpan * padding
+    val queryMaxLat = bounds.northeast.latitude + latSpan * padding
+    val queryMinLon = bounds.southwest.longitude - lonSpan * padding
+    val queryMaxLon = bounds.northeast.longitude + lonSpan * padding
+
+    val result = manager.cluster(queryMinLat, queryMaxLat, queryMinLon, queryMaxLon, zoom, width, height)
+    val minClusterSize = (clusterConfig?.minimumClusterSize ?: 2.0).toInt()
+    val strategy = clusterConfig?.strategy ?: ClusterStrategy.SUPERCLUSTER
+
+    // Build the actual visible polygon from the 4 corners of the rotated viewport.
+    // The C++ engine returns markers within the axis-aligned bounding box, which is
+    // larger than the actual viewport when the map is rotated (bearing ≠ 0).
+    // We filter results against this polygon to ensure markers outside the rotated
+    // viewport are properly excluded.
+    val bearing = map.cameraPosition.bearing
+    val isRotated = bearing % 360.0 != 0.0
+
+    // Expand the visible polygon outward by renderBuffer so that markers near the
+    // screen edge (whose icons overlap onto the visible area) are not clipped early.
+    val visiblePolygon = if (isRotated) {
+        expandPolygon(
+            listOf(
+                visibleRegion.nearLeft,
+                visibleRegion.nearRight,
+                visibleRegion.farRight,
+                visibleRegion.farLeft
+            ),
+            padding
+        )
+    } else null  // No polygon filter needed at 0° — axis-aligned bounds are exact
+
+    // --- Phase 2: Build renderable items ---
+    val renderItems = mutableListOf<RenderItem>()
+
+    for (cluster in result.clusters) {
+        // When rotated, filter out clusters outside the actual visible polygon
+        if (visiblePolygon != null && !pointInConvexQuad(cluster.latitude, cluster.longitude, visiblePolygon)) continue
+
+        val containsSelected = selectedMarkerId != null && cluster.markerIds.contains(selectedMarkerId)
+        val adjustedCount = if (containsSelected) cluster.count - 1 else cluster.count
+        if (adjustedCount < minClusterSize) continue
+
+        val adjustedIds = if (containsSelected) cluster.markerIds.filter { it != selectedMarkerId } else cluster.markerIds
+        val iconDiameter = cluster.iconSize
+
+        renderItems.add(RenderItem(
+            latitude = cluster.latitude,
+            longitude = cluster.longitude,
+            kind = RenderKind.Cluster(adjustedIds, adjustedCount, iconDiameter),
+            iconWidth = iconDiameter,
+            iconHeight = iconDiameter,
+            priority = adjustedCount + 10000
+        ))
+    }
+
+    // L-3: Use density-aware marker dimensions instead of hardcoded 27x43
+    val density = context.resources.displayMetrics.density
+    val defaultIconW = 27.0 * density  // Google Maps default marker width in px
+    val defaultIconH = 43.0 * density  // Google Maps default marker height in px
+
+    for (single in result.singleMarkers) {
+        // When rotated, filter out singles outside the actual visible polygon
+        if (visiblePolygon != null && !pointInConvexQuad(single.latitude, single.longitude, visiblePolygon)) continue
+
+        if (single.markerId == selectedMarkerId) continue
+        if (nonClusteredMarkers.containsKey(single.markerId)) continue
+        // H-3: Use markerData (single source of truth) instead of clusterableMarkerData
+        val data = markerData[single.markerId] ?: continue
+        if (!data.clusteringEnabled) continue  // Non-clusterable markers rendered directly
+
+        renderItems.add(RenderItem(
+            latitude = single.latitude,
+            longitude = single.longitude,
+            kind = RenderKind.Single(single.markerId),
+            iconWidth = defaultIconW,
+            iconHeight = defaultIconH,
+            priority = 0
+        ))
+    }
+
+    // --- Phase 2b: Apply strategy ---
+    val visibleItems = if (strategy == ClusterStrategy.HIDEONOVERLAP) {
+        resolveOverlaps(renderItems, zoom, width)
+    } else {
+        renderItems
+    }
+
+    // --- Phase 3: Render — add new BEFORE removing old (prevents flicker) ---
+    val isFirstRender = renderedClusterMarkers.isEmpty() && renderedSingleMarkers.isEmpty()
+    val oldClusterMarkers = renderedClusterMarkers.toList()
+    val oldSingleMarkers = renderedSingleMarkers.toMap()
+    renderedClusterMarkers.clear()
+    renderedSingleMarkers.clear()
+
+    // Preserve selected marker
+    selectedMarkerId?.let { selId ->
+        oldSingleMarkers[selId]?.let { selMarker ->
+            renderedSingleMarkers[selId] = selMarker
+        }
+    }
+
+    // Restore hidden non-clustered markers
+    for (id in hiddenNonClusteredIds) {
+        nonClusteredMarkers[id]?.isVisible = true
+    }
+    hiddenNonClusteredIds.clear()
+
+    // Render new items
+    for ((renderIndex, item) in visibleItems.withIndex()) {
+        when (val kind = item.kind) {
+            is RenderKind.Cluster -> {
+                val icon = manager.clusterIcon(kind.count)
+                val opts = MarkerOptions()
+                    .position(LatLng(item.latitude, item.longitude))
+                    .anchor(0.5f, 0.5f)
+                    .zIndex((kind.count + 1000).toFloat())
+
+                icon?.let { opts.icon(BitmapDescriptorFactory.fromBitmap(it)) }
+
+                val marker = map.addMarker(opts)
+                if (marker != null) {
+                    marker.tag = MarkerTagData.Cluster(kind.markerIds, kind.count)
+                    renderedClusterMarkers.add(marker)
+                    // Animate cluster icons when animatesClusters is enabled.
+                    // Only animate when cluster structure actually changes:
+                    // - First render, zoom level change, or markers added/removed.
+                    // Skip on pure pan at same zoom (same clusters, just repositioned).
+                    val zoomChanged = Math.floor(zoom) != Math.floor(lastClusteredZoom.toDouble())
+                    val structureChanged = isFirstRender || zoomChanged || clusteringDirty
+                    val animateOnReappear = clusterConfig?.animateOnReappear ?: true
+                    val animEnabled = (clusterConfig?.animatesClusters ?: true)
+                        && (isFirstRender || (animateOnReappear && structureChanged))
+                    if (animEnabled) {
+                        val duration = clusterConfig?.animationDuration ?: 0.3
+                        applyMarkerAnimation(marker, MarkerAnimation.APPEAR, duration)
+                    }
+                }
+            }
+
+            is RenderKind.Single -> {
+                // H-3: Use markerData (single source of truth)
+                val data = markerData[kind.markerId] ?: continue
+
+                val existing = oldSingleMarkers[kind.markerId]
+                if (existing != null) {
+                    // Reuse existing marker — skip full property update.
+                    // The marker already has correct props from updateMarkerInPlace().
+                    // Only zIndex (render order) changes between clustering cycles.
+                    // Re-setting icon was causing flicker on every camera idle
+                    // (e.g. during user location tracking).
+                    existing.zIndex = renderIndex.toFloat()
+                    renderedSingleMarkers[kind.markerId] = existing
+                } else {
+                    val opts = buildMarkerOptions(data)
+                    opts.zIndex(renderIndex.toFloat())
+                    val marker = map.addMarker(opts)
+                    if (marker != null) {
+                        marker.tag = MarkerTagData.Regular(kind.markerId)
+                        renderedSingleMarkers[kind.markerId] = marker
+                        // Animate new markers emerging from clusters (matches iOS behavior)
+                        if (data.animateOnReappear && data.animation != MarkerAnimation.NONE) {
+                            applyMarkerAnimation(marker, data.animation, data.animationDuration)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    // Remove old markers AFTER new ones are visible
+    for (marker in oldClusterMarkers) {
+        marker.remove()
+    }
+    for ((id, marker) in oldSingleMarkers) {
+        if (renderedSingleMarkers.containsKey(id)) continue
+        if (id == selectedMarkerId) continue
+        marker.remove()
+    }
+
+    // Handle non-clustered markers with hideOnOverlap
+    if (strategy == ClusterStrategy.HIDEONOVERLAP) {
+        hideOverlappingNonClusteredMarkers(visibleItems, zoom, width)
+    }
+
+    // Track state for next cycle's animation decisions
+    lastClusteredZoom = zoom.toFloat()
+    clusteringDirty = false
+}
+
+// ============================================================================
+// MARK: - Overlap Resolution (hideOnOverlap strategy)
+// ============================================================================
+
+private fun resolveOverlaps(
+    items: List<RenderItem>,
+    zoom: Double,
+    mapWidth: Double
+): List<RenderItem> {
+    val sorted = items.sortedByDescending { it.priority }
+    val visible = mutableListOf<RenderItem>()
+    val worldSize = 256.0 * 2.0.pow(zoom)
+
+    for (item in sorted) {
+        var hasOverlap = false
+        for (existing in visible) {
+            if (itemsOverlap(item, existing, worldSize)) {
+                hasOverlap = true
+                break
+            }
+        }
+        if (!hasOverlap) {
+            visible.add(item)
+        }
+    }
+    return visible
+}
+
+private fun GoogleMapProvider.hideOverlappingNonClusteredMarkers(
+    visibleItems: List<RenderItem>,
+    zoom: Double,
+    mapWidth: Double
+) {
+    val worldSize = 256.0 * 2.0.pow(zoom)
+
+    for ((id, ncMarker) in nonClusteredMarkers) {
+        val ncItem = RenderItem(
+            latitude = ncMarker.position.latitude,
+            longitude = ncMarker.position.longitude,
+            kind = RenderKind.Single(id),
+            iconWidth = 44.0,
+            iconHeight = 44.0,
+            priority = 0
+        )
+
+        var hasOverlap = false
+        for (existing in visibleItems) {
+            if (itemsOverlap(ncItem, existing, worldSize)) {
+                hasOverlap = true
+                break
+            }
+        }
+
+        if (hasOverlap) {
+            ncMarker.isVisible = false
+            hiddenNonClusteredIds.add(id)
+        }
+    }
+}
+
+private fun itemsOverlap(a: RenderItem, b: RenderItem, worldSize: Double): Boolean {
+    val dx = mercatorX(a.longitude, worldSize) - mercatorX(b.longitude, worldSize)
+    val dy = mercatorY(a.latitude, worldSize) - mercatorY(b.latitude, worldSize)
+    val minSepX = (a.iconWidth + b.iconWidth) / 2.0
+    val minSepY = (a.iconHeight + b.iconHeight) / 2.0
+    return abs(dx) < minSepX && abs(dy) < minSepY
+}
+
+private fun mercatorX(longitude: Double, worldSize: Double): Double {
+    return (longitude + 180.0) / 360.0 * worldSize
+}
+
+private fun mercatorY(latitude: Double, worldSize: Double): Double {
+    val latRad = latitude * Math.PI / 180.0
+    return (1.0 - ln(tan(latRad) + 1.0 / cos(latRad)) / Math.PI) / 2.0 * worldSize
+}
+
+// ============================================================================
+// MARK: - Marker Pool Management
+// ============================================================================
+
+fun GoogleMapProvider.clearRenderedClusterMarkers() {
+    for (marker in renderedClusterMarkers) {
+        marker.remove()
+    }
+    renderedClusterMarkers.clear()
+
+    for ((id, marker) in renderedSingleMarkers) {
+        if (id == selectedMarkerId) continue
+        marker.remove()
+    }
+    if (selectedMarkerId != null) {
+        val selectedMarker = renderedSingleMarkers[selectedMarkerId]
+        renderedSingleMarkers.clear()
+        selectedMarker?.let { renderedSingleMarkers[selectedMarkerId!!] = it }
+    } else {
+        renderedSingleMarkers.clear()
+    }
+}
+
+fun GoogleMapProvider.renderAllMarkersIndividually() {
+    val map = googleMap ?: return
+    // H-3: Use markerData (single source of truth)
+    // When global clustering is disabled, render ALL markers individually —
+    // don't filter by per-marker clusteringEnabled, because updateMarker may
+    // have already set it to false before this debounced call fires.
+    for ((_, data) in markerData) {
+        if (renderedSingleMarkers.containsKey(data.id)) continue
+        if (nonClusteredMarkers.containsKey(data.id)) continue
+        val opts = buildMarkerOptions(data)
+        val marker = map.addMarker(opts)
+        if (marker != null) {
+            marker.tag = MarkerTagData.Regular(data.id)
+            renderedSingleMarkers[data.id] = marker
+        }
+    }
+}
+
+// ============================================================================
+// MARK: - Clustering Control
+// ============================================================================
+
+internal fun GoogleMapProvider.setClusteringEnabledInternal(enabled: Boolean) {
+    val existingConfig = clusterConfig
+    clusterConfig = if (existingConfig != null) {
+        ClusterConfig(
+            enabled = enabled,
+            strategy = existingConfig.strategy,
+            radius = existingConfig.radius,
+            minimumClusterSize = existingConfig.minimumClusterSize,
+            maxZoom = existingConfig.maxZoom,
+            backgroundColor = existingConfig.backgroundColor,
+            textColor = existingConfig.textColor,
+            borderWidth = existingConfig.borderWidth,
+            borderColor = existingConfig.borderColor,
+            animatesClusters = existingConfig.animatesClusters,
+            animateOnReappear = existingConfig.animateOnReappear,
+            animationDuration = existingConfig.animationDuration,
+            realtimeClustering = existingConfig.realtimeClustering,
+            renderBuffer = existingConfig.renderBuffer,
+            throttleInterval = existingConfig.throttleInterval
+        )
+    } else {
+        ClusterConfig(
+            enabled = enabled,
+            strategy = null, radius = null, minimumClusterSize = null,
+            maxZoom = null, backgroundColor = null, textColor = null,
+            borderWidth = null, borderColor = null, animatesClusters = null,
+            animateOnReappear = null, animationDuration = null,
+            realtimeClustering = null, renderBuffer = null, throttleInterval = null
+        )
+    }
+    performClustering()
+}
+
+internal fun GoogleMapProvider.refreshClustersInternal() {
+    performClustering()
+}
+
+// M-1: buildMarkerOptions and applyMarkerProperties are now shared functions
+// defined in GoogleMapProvider+Markers.kt — no duplicates here.
+
+// ============================================================================
+// MARK: - Viewport Polygon Helpers (rotation-aware visibility)
+// ============================================================================
+
+/**
+ * Point-in-convex-quadrilateral test using cross products.
+ * The polygon must have vertices in order (CW or CCW).
+ * Returns true if (lat, lon) is inside the quadrilateral.
+ *
+ * For a convex polygon, a point is inside if it's on the same side
+ * of all edges. We check the sign of the cross product for each edge.
+ */
+private fun pointInConvexQuad(lat: Double, lon: Double, quad: List<LatLng>): Boolean {
+    val n = quad.size
+    var positive = 0
+    var negative = 0
+
+    for (i in 0 until n) {
+        val x1 = quad[i].longitude
+        val y1 = quad[i].latitude
+        val x2 = quad[(i + 1) % n].longitude
+        val y2 = quad[(i + 1) % n].latitude
+
+        // Cross product of edge vector and point vector
+        val cross = (x2 - x1) * (lat - y1) - (y2 - y1) * (lon - x1)
+
+        if (cross > 0) positive++
+        else if (cross < 0) negative++
+
+        // If we have both positive and negative, point is outside
+        if (positive > 0 && negative > 0) return false
+    }
+    return true
+}
+
+/**
+ * Expands a convex polygon outward from its centroid by a fraction.
+ * Used to account for renderBuffer so markers near viewport edges
+ * aren't clipped prematurely.
+ */
+private fun expandPolygon(polygon: List<LatLng>, fraction: Double): List<LatLng> {
+    if (fraction <= 0.0) return polygon
+
+    // Compute centroid
+    var cLat = 0.0
+    var cLon = 0.0
+    for (p in polygon) {
+        cLat += p.latitude
+        cLon += p.longitude
+    }
+    cLat /= polygon.size
+    cLon /= polygon.size
+
+    // Expand each vertex outward from centroid
+    return polygon.map { p ->
+        LatLng(
+            cLat + (p.latitude - cLat) * (1.0 + fraction),
+            cLon + (p.longitude - cLon) * (1.0 + fraction)
+        )
+    }
+}