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

package/android/src/main/kotlin/com/margelo/nitro/nitromap/UserLocationManager.kt

@@ -0,0 +1,295 @@
+package com.margelo.nitro.nitromap
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.hardware.Sensor
+import android.hardware.SensorEvent
+import android.hardware.SensorEventListener
+import android.hardware.SensorManager
+import android.location.Location
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.core.content.ContextCompat
+import com.google.android.gms.location.FusedLocationProviderClient
+import com.google.android.gms.location.LocationCallback
+import com.google.android.gms.location.LocationRequest
+import com.google.android.gms.location.LocationResult
+import com.google.android.gms.location.LocationServices
+import com.google.android.gms.location.Priority
+import kotlin.math.abs
+import kotlin.math.atan2
+import kotlin.math.cos
+import kotlin.math.sin
+
+/**
+ * Android equivalent of iOS NitroLocationManager.
+ *
+ * Wraps FusedLocationProviderClient for position updates and
+ * SensorManager for compass heading (Android has no CLHeading equivalent).
+ *
+ * Heading is smoothed with a low-pass filter on raw sensor data and
+ * circular exponential smoothing on the computed azimuth, matching
+ * the stability of iOS CLHeading.trueHeading.
+ *
+ * Thread safety: All callbacks fire on the main thread.
+ */
+class UserLocationManager(private val context: Context) {
+
+    companion object {
+        private const val TAG = "NitroMap"
+        private const val UPDATE_INTERVAL_MS = 1000L
+        private const val FASTEST_INTERVAL_MS = 500L
+
+        /** Low-pass filter alpha for raw sensor arrays (0 = ignore new, 1 = no filter) */
+        private const val SENSOR_ALPHA = 0.15f
+
+        /** Exponential smoothing alpha for the final heading angle */
+        private const val HEADING_ALPHA = 0.25f
+
+        /**
+         * Minimum heading change (degrees) before firing an independent heading
+         * update — mirrors iOS CLLocationManager.headingFilter = 1.
+         */
+        private const val HEADING_FILTER_DEGREES = 2f
+
+        /**
+         * Minimum interval (ms) between independent heading-only updates.
+         * Prevents overwhelming the main thread when combined with 3000+ markers
+         * and clustering. 200ms = max 5 heading updates/second.
+         */
+        private const val MIN_HEADING_INTERVAL_MS = 200L
+    }
+
+    // MARK: - Callbacks
+
+    /** Called with (location, headingDegrees) — heading may be null if sensors unavailable */
+    var onLocationUpdate: ((Location, Float?) -> Unit)? = null
+
+    /** Called with (errorCode, errorMessage) */
+    var onLocationError: ((String, String) -> Unit)? = null
+
+    // MARK: - Location Provider
+
+    private var fusedClient: FusedLocationProviderClient? = null
+    private var locationCallback: LocationCallback? = null
+    private var isUpdating = false
+
+    /** Latest location — kept so heading-only updates can re-fire with position */
+    private var latestLocation: Location? = null
+
+    // MARK: - Heading (Compass) via Sensors
+
+    private var sensorManager: SensorManager? = null
+    private var accelerometerSensor: Sensor? = null
+    private var magneticSensor: Sensor? = null
+    private var sensorListener: SensorEventListener? = null
+
+    /** Low-pass filtered gravity values */
+    private var filteredGravity: FloatArray? = null
+    /** Low-pass filtered magnetic field values */
+    private var filteredGeomagnetic: FloatArray? = null
+
+    /** Smoothed heading (degrees, 0-360) — null until first valid reading */
+    private var smoothedHeading: Float? = null
+
+    /** Last heading value that was delivered to the callback */
+    private var lastDeliveredHeading: Float? = null
+
+    /** Timestamp of the last independent heading-only update delivery */
+    private var lastHeadingDeliveryTime: Long = 0L
+
+    // MARK: - Public API
+
+    fun startUpdating() {
+        if (isUpdating) return
+
+        // Check permission
+        if (ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION)
+            != PackageManager.PERMISSION_GRANTED &&
+            ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION)
+            != PackageManager.PERMISSION_GRANTED
+        ) {
+            Log.w(TAG, "Location permission not granted")
+            onLocationError?.invoke("PERMISSION_DENIED", "Location permission not granted")
+            return
+        }
+
+        isUpdating = true
+
+        // Start location updates
+        val client = LocationServices.getFusedLocationProviderClient(context)
+        fusedClient = client
+
+        val request = LocationRequest.Builder(Priority.PRIORITY_HIGH_ACCURACY, UPDATE_INTERVAL_MS)
+            .setMinUpdateIntervalMillis(FASTEST_INTERVAL_MS)
+            .build()
+
+        val callback = object : LocationCallback() {
+            override fun onLocationResult(result: LocationResult) {
+                val location = result.lastLocation ?: return
+                latestLocation = location
+                onLocationUpdate?.invoke(location, smoothedHeading)
+            }
+        }
+        locationCallback = callback
+
+        try {
+            client.requestLocationUpdates(request, callback, Looper.getMainLooper())
+            Log.d(TAG, "Location updates started")
+        } catch (e: SecurityException) {
+            Log.e(TAG, "Location security exception: ${e.message}")
+            onLocationError?.invoke("PERMISSION_DENIED", "Location permission revoked: ${e.message}")
+            isUpdating = false
+            return
+        }
+
+        // Start heading sensor
+        startHeadingSensor()
+    }
+
+    fun stopUpdating() {
+        if (!isUpdating) return
+        isUpdating = false
+
+        locationCallback?.let { callback ->
+            fusedClient?.removeLocationUpdates(callback)
+        }
+        locationCallback = null
+        fusedClient = null
+
+        stopHeadingSensor()
+        latestLocation = null
+        Log.d(TAG, "Location updates stopped")
+    }
+
+    // MARK: - Heading Sensor
+
+    private fun startHeadingSensor() {
+        val sm = context.getSystemService(Context.SENSOR_SERVICE) as? SensorManager ?: return
+        sensorManager = sm
+
+        accelerometerSensor = sm.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)
+        magneticSensor = sm.getDefaultSensor(Sensor.TYPE_MAGNETIC_FIELD)
+
+        if (accelerometerSensor == null || magneticSensor == null) {
+            Log.w(TAG, "Compass sensors not available")
+            return
+        }
+
+        val listener = object : SensorEventListener {
+            override fun onSensorChanged(event: SensorEvent) {
+                when (event.sensor.type) {
+                    Sensor.TYPE_ACCELEROMETER ->
+                        filteredGravity = lowPassFilter(event.values, filteredGravity)
+                    Sensor.TYPE_MAGNETIC_FIELD ->
+                        filteredGeomagnetic = lowPassFilter(event.values, filteredGeomagnetic)
+                }
+
+                val g = filteredGravity ?: return
+                val m = filteredGeomagnetic ?: return
+
+                val R = FloatArray(9)
+                val I = FloatArray(9)
+                if (!SensorManager.getRotationMatrix(R, I, g, m)) return
+
+                val orientation = FloatArray(3)
+                SensorManager.getOrientation(R, orientation)
+
+                // orientation[0] = azimuth in radians
+                var rawHeading = Math.toDegrees(orientation[0].toDouble()).toFloat()
+                if (rawHeading < 0) rawHeading += 360f
+
+                // Apply circular exponential smoothing
+                val prev = smoothedHeading
+                smoothedHeading = if (prev == null) {
+                    rawHeading
+                } else {
+                    circularSmooth(prev, rawHeading, HEADING_ALPHA)
+                }
+
+                // Fire heading update independently (mirrors iOS didUpdateHeading)
+                // only when heading changed by more than the filter threshold
+                // AND enough time has passed (throttle to avoid flooding main thread)
+                val delivered = lastDeliveredHeading
+                val current = smoothedHeading ?: return
+                val now = System.currentTimeMillis()
+                if ((delivered == null || circularDistance(delivered, current) >= HEADING_FILTER_DEGREES)
+                    && (now - lastHeadingDeliveryTime >= MIN_HEADING_INTERVAL_MS)
+                ) {
+                    lastDeliveredHeading = current
+                    lastHeadingDeliveryTime = now
+                    val loc = latestLocation ?: return
+                    onLocationUpdate?.invoke(loc, current)
+                }
+            }
+
+            override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {}
+        }
+        sensorListener = listener
+
+        val mainHandler = Handler(Looper.getMainLooper())
+        sm.registerListener(listener, accelerometerSensor, SensorManager.SENSOR_DELAY_UI, mainHandler)
+        sm.registerListener(listener, magneticSensor, SensorManager.SENSOR_DELAY_UI, mainHandler)
+    }
+
+    private fun stopHeadingSensor() {
+        sensorListener?.let { listener ->
+            sensorManager?.unregisterListener(listener)
+        }
+        sensorListener = null
+        sensorManager = null
+        accelerometerSensor = null
+        magneticSensor = null
+        filteredGravity = null
+        filteredGeomagnetic = null
+        smoothedHeading = null
+        lastDeliveredHeading = null
+        lastHeadingDeliveryTime = 0L
+    }
+
+    // MARK: - Signal Processing Helpers
+
+    /**
+     * Low-pass filter for raw sensor arrays.
+     * Smooths out high-frequency jitter in accelerometer/magnetometer readings.
+     */
+    private fun lowPassFilter(input: FloatArray, output: FloatArray?): FloatArray {
+        if (output == null) return input.clone()
+        for (i in input.indices) {
+            output[i] = output[i] + SENSOR_ALPHA * (input[i] - output[i])
+        }
+        return output
+    }
+
+    /**
+     * Circular exponential smoothing that handles the 0°/360° wraparound correctly.
+     * Uses sin/cos decomposition to avoid the discontinuity at north.
+     */
+    private fun circularSmooth(prev: Float, next: Float, alpha: Float): Float {
+        val prevRad = Math.toRadians(prev.toDouble())
+        val nextRad = Math.toRadians(next.toDouble())
+
+        val sinSmooth = sin(prevRad) + alpha * (sin(nextRad) - sin(prevRad))
+        val cosSmooth = cos(prevRad) + alpha * (cos(nextRad) - cos(prevRad))
+
+        var result = Math.toDegrees(atan2(sinSmooth, cosSmooth)).toFloat()
+        if (result < 0) result += 360f
+        return result
+    }
+
+    /**
+     * Shortest angular distance between two headings (0-180 range).
+     */
+    private fun circularDistance(a: Float, b: Float): Float {
+        val diff = abs(a - b) % 360f
+        return if (diff > 180f) 360f - diff else diff
+    }
+
+    fun destroy() {
+        stopUpdating()
+        onLocationUpdate = null
+        onLocationError = null
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/clustering/ClusterIconRenderer.kt

@@ -0,0 +1,111 @@
+package com.margelo.nitro.nitromap.clustering
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.Paint
+import android.graphics.Typeface
+import android.util.LruCache
+import com.margelo.nitro.nitromap.ClusterConfig
+import com.margelo.nitro.nitromap.markers.PriceMarkerRenderer
+
+/**
+ * Renders cluster icons as circle + count text.
+ * Mirrors iOS ClusterIconRenderer.swift.
+ *
+ * Uses LruCache to avoid re-rendering the same cluster icon at each zoom level.
+ */
+object ClusterIconRenderer {
+
+    private const val MAX_CACHE_SIZE = 100
+    // L-2: Override entryRemoved to recycle evicted bitmaps and prevent memory leaks
+    private val cache = object : LruCache<String, Bitmap>(MAX_CACHE_SIZE) {
+        override fun entryRemoved(evicted: Boolean, key: String?, oldValue: Bitmap?, newValue: Bitmap?) {
+            if (evicted && oldValue != null && !oldValue.isRecycled) {
+                oldValue.recycle()
+            }
+        }
+    }
+
+    /**
+     * Render a cluster icon bitmap.
+     *
+     * @param count Number of markers in the cluster
+     * @param config Optional cluster configuration for colors/border
+     * @param density Screen density for sizing
+     * @return Rendered cluster icon bitmap
+     */
+    fun renderIcon(count: Int, config: ClusterConfig?, density: Float): Bitmap {
+        // Check cache
+        val cacheKey = buildCacheKey(count, config)
+        cache.get(cacheKey)?.let { return it }
+
+        val diameter = clusterDiameter(count) * density
+        val diameterInt = diameter.toInt()
+
+        val bitmap = Bitmap.createBitmap(diameterInt, diameterInt, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(bitmap)
+
+        // M-4: Use shared resolveColor from PriceMarkerRenderer
+        val bgColor = PriceMarkerRenderer.resolveColor(config?.backgroundColor, Color.argb(255, 0, 122, 255))
+        val textColor = PriceMarkerRenderer.resolveColor(config?.textColor, Color.WHITE)
+        val borderColor = PriceMarkerRenderer.resolveColor(config?.borderColor, Color.WHITE)
+        val borderWidth = ((config?.borderWidth ?: 2.0) * density).toFloat()
+
+        // Draw border circle
+        val borderPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = borderColor
+            style = Paint.Style.FILL
+        }
+        canvas.drawCircle(diameter / 2f, diameter / 2f, diameter / 2f, borderPaint)
+
+        // Draw background circle (inset by border width)
+        val bgPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = bgColor
+            style = Paint.Style.FILL
+        }
+        canvas.drawCircle(diameter / 2f, diameter / 2f, diameter / 2f - borderWidth, bgPaint)
+
+        // Draw count text
+        val textPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            color = textColor
+            textSize = diameter * 0.35f
+            typeface = Typeface.DEFAULT_BOLD
+            textAlign = Paint.Align.CENTER
+        }
+        val textBounds = android.graphics.Rect()
+        val text = "$count"
+        textPaint.getTextBounds(text, 0, text.length, textBounds)
+        val textY = diameter / 2f + textBounds.height() / 2f
+        canvas.drawText(text, diameter / 2f, textY, textPaint)
+
+        cache.put(cacheKey, bitmap)
+        return bitmap
+    }
+
+    /**
+     * Standard cluster diameter in dp based on count.
+     * Matches iOS: 44pt for <10, 52pt for <100, 60pt for ≥100.
+     */
+    fun clusterDiameter(count: Int): Float {
+        return when {
+            count < 10 -> 44f
+            count < 100 -> 52f
+            else -> 60f
+        }
+    }
+
+    fun clearCache() {
+        cache.evictAll()
+    }
+
+    private fun buildCacheKey(count: Int, config: ClusterConfig?): String {
+        val bgHash = config?.backgroundColor?.hashCode() ?: 0
+        val textHash = config?.textColor?.hashCode() ?: 0
+        val borderHash = config?.borderColor?.hashCode() ?: 0
+        val borderW = config?.borderWidth ?: 2.0
+        return "cluster_${count}_${bgHash}_${textHash}_${borderHash}_${borderW}"
+    }
+
+    // M-4: resolveColor is now shared via PriceMarkerRenderer.resolveColor()
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/clustering/ClusteringManager.kt

@@ -0,0 +1,104 @@
+package com.margelo.nitro.nitromap.clustering
+
+import android.graphics.Bitmap
+import android.os.Handler
+import android.os.Looper
+import com.margelo.nitro.nitromap.ClusterConfig
+import com.margelo.nitro.nitromap.MarkerData
+
+/**
+ * Clustering manager — wraps NitroClusterEngine and ClusterIconRenderer.
+ * Mirrors iOS ClusteringManager.swift.
+ *
+ * Provides:
+ * - Marker management → feeds to C++ engine
+ * - Configuration → radius, minSize, maxZoom
+ * - Clustering query → bounds-based spatial grouping
+ * - Debounce → timer-based to prevent rapid re-clustering
+ * - Icon generation → delegates to ClusterIconRenderer
+ */
+class ClusteringManager(
+    clusterRadius: Double = 80.0,
+    minClusterSize: Int = 2,
+    maxZoom: Double = 20.0,
+    private val debounceIntervalMs: Long = 100L
+) {
+
+    private val engine = NitroClusterEngine()
+    private val mainHandler = Handler(Looper.getMainLooper())
+    private var debounceRunnable: Runnable? = null
+    private var density: Float = 1f
+
+    var clusterConfig: ClusterConfig? = null
+        set(value) {
+            field = value
+            value?.let {
+                engine.setClusterRadius(it.radius ?: 80.0)
+                engine.setMinClusterSize((it.minimumClusterSize ?: 2.0).toInt())
+                engine.setMaxZoom(it.maxZoom ?: 20.0)
+            }
+        }
+
+    init {
+        engine.setClusterRadius(clusterRadius)
+        engine.setMinClusterSize(minClusterSize)
+        engine.setMaxZoom(maxZoom)
+    }
+
+    fun setDensity(density: Float) {
+        this.density = density
+    }
+
+    // MARK: - Marker Management
+
+    fun addMarker(marker: MarkerData) {
+        engine.addMarker(
+            marker.id,
+            marker.coordinate.latitude,
+            marker.coordinate.longitude
+        )
+    }
+
+    fun removeMarker(id: String) {
+        engine.removeMarker(id)
+    }
+
+    fun clearMarkers() {
+        engine.clearMarkers()
+    }
+
+    // MARK: - Clustering
+
+    fun cluster(
+        minLat: Double, maxLat: Double,
+        minLon: Double, maxLon: Double,
+        zoom: Double,
+        mapWidth: Double, mapHeight: Double
+    ): NitroClusterEngine.ClusteringResult {
+        return engine.clusterWithBounds(minLat, maxLat, minLon, maxLon, zoom, mapWidth, mapHeight)
+    }
+
+    // MARK: - Debounce
+
+    fun debounce(action: () -> Unit) {
+        debounceRunnable?.let { mainHandler.removeCallbacks(it) }
+        val runnable = Runnable { action() }
+        debounceRunnable = runnable
+        mainHandler.postDelayed(runnable, debounceIntervalMs)
+    }
+
+    // MARK: - Icon Generation
+
+    fun clusterIcon(forCount: Int): Bitmap? {
+        return ClusterIconRenderer.renderIcon(forCount, clusterConfig, density)
+    }
+
+    // MARK: - Cleanup
+
+    fun destroy() {
+        debounceRunnable?.let { mainHandler.removeCallbacks(it) }
+        debounceRunnable = null
+        engine.destroy()
+        ClusterIconRenderer.clearCache()
+    }
+}

package/android/src/main/kotlin/com/margelo/nitro/nitromap/clustering/NitroClusterEngine.kt

@@ -0,0 +1,166 @@
+package com.margelo.nitro.nitromap.clustering
+
+/**
+ * Kotlin wrapper for C++ ClusterEngine via JNI.
+ * Mirrors iOS NitroClusterEngine.swift.
+ *
+ * Pure spatial grouping — no icon dimensions.
+ * Caller (GoogleMapProvider+Clustering) handles visual collision with real rendered sizes.
+ */
+// H-5: Implement AutoCloseable instead of relying on unreliable finalize()
+class NitroClusterEngine : AutoCloseable {
+
+    // Native pointer to C++ ClusterEngine
+    private var nativePtr: Long = nativeCreate()
+
+    // MARK: - JNI Data Classes
+
+    /** JNI-friendly cluster data — created in C++ JNI bridge */
+    class ClusterDataJNI(
+        val latitude: Double,
+        val longitude: Double,
+        val count: Int,
+        val markerIds: Array<String>,
+        val iconSize: Double
+    )
+
+    /** JNI-friendly single marker point */
+    class SingleMarkerJNI(
+        val markerId: String,
+        val latitude: Double,
+        val longitude: Double
+    )
+
+    /** JNI-friendly clustering result */
+    class ClusteringResultJNI(
+        val clusters: Array<ClusterDataJNI>,
+        val singles: Array<SingleMarkerJNI>
+    )
+
+    // MARK: - Public Result Types (clean Kotlin API)
+
+    data class ClusterDataResult(
+        val latitude: Double,
+        val longitude: Double,
+        val markerIds: List<String>,
+        val count: Int,
+        val iconSize: Double
+    )
+
+    data class SingleMarkerResult(
+        val markerId: String,
+        val latitude: Double,
+        val longitude: Double
+    )
+
+    data class ClusteringResult(
+        val clusters: List<ClusterDataResult>,
+        val singleMarkers: List<SingleMarkerResult>
+    )
+
+    // MARK: - Configuration
+    // M-6: All public methods guard against use-after-destroy (nativePtr == 0L)
+
+    fun setClusterRadius(radius: Double) {
+        if (nativePtr == 0L) return
+        nativeSetClusterRadius(nativePtr, radius)
+    }
+    fun setMinClusterSize(size: Int) {
+        if (nativePtr == 0L) return
+        nativeSetMinClusterSize(nativePtr, size)
+    }
+    fun setMaxZoom(zoom: Double) {
+        if (nativePtr == 0L) return
+        nativeSetMaxZoom(nativePtr, zoom)
+    }
+
+    // MARK: - Marker Management
+
+    fun addMarker(id: String, latitude: Double, longitude: Double) {
+        if (nativePtr == 0L) return
+        nativeAddMarker(nativePtr, id, latitude, longitude)
+    }
+
+    fun removeMarker(id: String) {
+        if (nativePtr == 0L) return
+        nativeRemoveMarker(nativePtr, id)
+    }
+    fun clearMarkers() {
+        if (nativePtr == 0L) return
+        nativeClearMarkers(nativePtr)
+    }
+    fun markerCount(): Int {
+        if (nativePtr == 0L) return 0
+        return nativeMarkerCount(nativePtr)
+    }
+
+    // MARK: - Clustering
+
+    fun clusterWithBounds(
+        minLat: Double, maxLat: Double,
+        minLon: Double, maxLon: Double,
+        zoom: Double,
+        mapWidth: Double, mapHeight: Double
+    ): ClusteringResult {
+        if (nativePtr == 0L) return ClusteringResult(emptyList(), emptyList())
+        val jniResults = nativeCluster(nativePtr, minLat, maxLat, minLon, maxLon, zoom, mapWidth, mapHeight)
+
+        if (jniResults.isEmpty()) {
+            return ClusteringResult(emptyList(), emptyList())
+        }
+
+        val jniResult = jniResults[0]
+
+        val clusters = jniResult.clusters.map { c ->
+            ClusterDataResult(
+                latitude = c.latitude,
+                longitude = c.longitude,
+                markerIds = c.markerIds.toList(),
+                count = c.count,
+                iconSize = c.iconSize
+            )
+        }
+
+        val singles = jniResult.singles.map { s ->
+            SingleMarkerResult(
+                markerId = s.markerId,
+                latitude = s.latitude,
+                longitude = s.longitude
+            )
+        }
+
+        return ClusteringResult(clusters, singles)
+    }
+
+    // MARK: - Cleanup
+
+    fun destroy() {
+        if (nativePtr != 0L) {
+            nativeDestroy(nativePtr)
+            nativePtr = 0
+        }
+    }
+
+    // H-5: AutoCloseable.close() — deterministic cleanup via try-with-resources or explicit close
+    override fun close() {
+        destroy()
+    }
+
+    // MARK: - JNI External Functions
+
+    private external fun nativeCreate(): Long
+    private external fun nativeDestroy(ptr: Long)
+    private external fun nativeSetClusterRadius(ptr: Long, radius: Double)
+    private external fun nativeSetMinClusterSize(ptr: Long, size: Int)
+    private external fun nativeSetMaxZoom(ptr: Long, zoom: Double)
+    private external fun nativeAddMarker(ptr: Long, id: String, lat: Double, lon: Double)
+    private external fun nativeRemoveMarker(ptr: Long, id: String)
+    private external fun nativeClearMarkers(ptr: Long)
+    private external fun nativeMarkerCount(ptr: Long): Int
+    private external fun nativeCluster(
+        ptr: Long,
+        minLat: Double, maxLat: Double,
+        minLon: Double, maxLon: Double,
+        zoom: Double, mapW: Double, mapH: Double
+    ): Array<ClusteringResultJNI>
+}