Introduce GroundImage, and refactor architecture

.claude/settings.local.json

@@ -1,7 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "Bash(./gradlew:*)"
+      "Bash(./gradlew:*)",
+      "Bash(grep:*)",
+      "Bash(rm:*)"
     ],
     "deny": []
   }

README.md

@@ -1,23 +1,94 @@
-# セットアップ
+# MapConductor Android SDK
 
-1. リポジトリをクローン
-```
+A unified mapping library that provides a common API for multiple map providers including Google Maps, Mapbox, HERE, and ArcGIS. Write once, deploy across all major mapping platforms.
+
+## Features
+
+- **🗺️ Multi-Provider Support**: Seamlessly switch between Google Maps, Mapbox, HERE, and ArcGIS with a single API
+- **🎯 Unified Interface**: Common abstractions for markers, circles, polylines, polygons, and ground overlays
+- **⚡ High Performance**: Spatial indexing with hexagonal cells for efficient marker clustering
+- **🔄 Reactive State**: Built on Kotlin StateFlow for reactive UI updates
+- **🎨 Jetpack Compose**: Modern Android UI toolkit integration
+
+## Architecture
+
+### Module Structure
+
+- **`mapconductor-core`**: Core abstractions and shared functionality
+- **`mapconductor-for-googlemaps`**: Google Maps implementation
+- **`mapconductor-for-mapbox`**: Mapbox implementation
+- **`mapconductor-for-here`**: HERE Maps implementation
+- **`mapconductor-for-arcgis`**: ArcGIS implementation
+- **`mapconductor-icons`**: Reusable marker icon components
+- **`example-app`**: Comprehensive demo application
+
+### Key Components
+
+- **MapViewController**: Abstract controller interface for all map providers
+- **MapViewBase**: Generic Compose-based map view component
+- **Overlay Managers**: Separate managers for markers, circles, polylines, and polygons
+- **Projection Utilities**: WebMercator and WGS84 coordinate transformations
+- **HexGeocell**: Spatial indexing system for performance optimization
+
+## Quick Start
+
+### 1. Setup
+
+Clone the repository:
+```bash
 git clone https://github.com/MapConductor/android-sdk.git
 ```
 
-2. https://github.com/MapConductor/map-sdk-credentials/ から`secrets.properties` をプロジェクトルートに追加保存する
+Add `secrets.properties` to the project root from https://github.com/MapConductor/map-sdk-credentials/
+
+### 2. Basic Usage
+
+```kotlin
+@Composable
+fun MyMapScreen() {
+    GoogleMapView(
+        modifier = Modifier.fillMaxSize(),
+        onMapReady = { controller ->
+            // Add markers, circles, polylines, etc.
+        }
+    ) { mapState, controller ->
+        // Your map content here
+    }
+}
+```
+
+### 3. Switch Map Providers
 
-3. Android Studioでビルド
+Simply change the map view component:
+```kotlin
+// Google Maps
+GoogleMapView { /* ... */ }
 
-# コーディングスタイル
+// Mapbox
+MapboxMapView { /* ... */ }
 
-KtLintに従います。ローカルで実行する場合は、下記コマンドを実行します（可能ならば自動修正されます）。
+// HERE Maps
+HereMapView { /* ... */ }
 
+// ArcGIS
+ArcGISMapView { /* ... */ }
 ```
+
+## Development
+
+### Building
+```bash
+./gradlew build
+```
+
+### Code Style
+This project follows KtLint conventions:
+```bash
 ./gradlew allLintChecks
 ```
 
-# 基本実装状況 (Android)
+
+## Feature Implementation Status
 
 |                 | Google Maps | Mapbox   | Here     | ArcGIS         |
 |-----------------|-------------|----------|----------|----------------|
@@ -26,6 +97,6 @@ KtLintに従います。ローカルで実行する場合は、下記コマン
 | Circle          | ☑    | ☑ | ☐ | ☐ (wip) |
 | Polyline        | ☑    | ☑ | ☑ | ☑       |
 | Polygon         | ☐    | ☐ | ☐ | ☐       |
-| GroundOverlay   | ☐    | ☐ | ☐ | ☐       |
+| GroundImage     | ☐    | N/A      | N/A      | N/A            |
 | RasterTileLayer | ☐    | ☐ | ☐ | ☐       |
 | VectorTileLayer | ☐    | ☐ | ☐ | ☐       |

build.gradle.kts

@@ -4,7 +4,7 @@ plugins {
     alias(libs.plugins.kotlin.android) apply false
     alias(libs.plugins.kotlin.compose) apply false
     alias(libs.plugins.android.library) apply false
-    id("org.jlleitschuh.gradle.ktlint") version "13.0.0-rc.1"
+    alias(libs.plugins.jlleitschuh.ktlint) apply false
 }
 
 buildscript {
@@ -17,22 +17,25 @@ buildscript {
     }
 }
 
-val modules: List<String> = rootDir.resolve("projects.properties").readLines()
-    .firstOrNull { it.startsWith("modules=") }
-    ?.removePrefix("modules=")
-    ?.split(",")
-    ?.map { it.trim() }
-    ?.filter { it.isNotEmpty() }
-    ?: emptyList()
+val modules: List<String> =
+    rootDir
+        .resolve("projects.properties")
+        .readLines()
+        .firstOrNull { it.startsWith("modules=") }
+        ?.removePrefix("modules=")
+        ?.split(",")
+        ?.map { it.trim() }
+        ?.filter { it.isNotEmpty() }
+        ?: emptyList()
 
 tasks.register("allLintChecks") {
     group = "verification"
     description = "Run ktlintFormat and lint for all modules"
 
-    val lintTasks = modules.map { module ->
-        listOf(":$module:ktlintFormat", ":$module:lint")
-    }
+    val lintTasks =
+        modules.map { module ->
+            listOf(":$module:ktlintFormat", ":$module:lint")
+        }
 
     dependsOn(lintTasks)
 }
-

example-app/build.gradle.kts

@@ -81,6 +81,7 @@ dependencies {
     implementation(libs.androidx.ui.tooling.preview)
     implementation(libs.androidx.material3)
     implementation(libs.androidx.appcompat)
+    implementation(platform(libs.firebase.bom))
 
     // Google Maps SDK
     implementation(libs.play.services.maps)
@@ -104,6 +105,7 @@ dependencies {
     implementation(project(":mapconductor-for-mapbox"))
     implementation(project(":mapconductor-for-arcgis"))
     implementation(libs.androidx.vectordrawable)
+    implementation(libs.androidx.room.runtime.android)
 
     testImplementation(libs.junit)
     testImplementation(libs.androidx.core)

example-app/src/main/java/com/mapconductor/example/DemoAppScreen.kt

@@ -17,6 +17,8 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.core.content.ContextCompat
+import androidx.lifecycle.ViewModel
+import androidx.lifecycle.ViewModelProvider
 import androidx.lifecycle.viewmodel.compose.viewModel
 import com.mapconductor.example.navigation.NavigationViewModel
 import com.mapconductor.example.pages.animation.AnimationMapPage
@@ -26,15 +28,30 @@ import com.mapconductor.example.pages.groundimage.GroundImageResources
 import com.mapconductor.example.pages.map.flyto.FlyToMapIcons
 import com.mapconductor.example.pages.map.flyto.FlyToMapPage
 import com.mapconductor.example.pages.mapDesign.MapDesignMapPage
+import com.mapconductor.example.pages.marker.MarkerBasicPage
+import com.mapconductor.example.pages.polygon.PolygonMapPage
 import com.mapconductor.example.pages.polyline.PolylineMapPage
 import com.mapconductor.example.pages.stores.StoreMapPage
 import com.mapconductor.example.ui.sidebar.Sidebar
 import com.mapconductor.example.ui.sidebar.SidebarItem
 import com.mapconductor.example.ui.theme.AppTheme
 
 @Composable
-fun DemoAppScreen() {
-    val navigationViewModel: NavigationViewModel = viewModel()
+fun DemoAppScreen(initPage: String = "map") {
+    val navigationViewModel: NavigationViewModel =
+        viewModel<NavigationViewModel>(
+            factory =
+                object : ViewModelProvider.Factory {
+                    override fun <T : ViewModel> create(modelClass: Class<T>): T {
+                        if (modelClass.isAssignableFrom(NavigationViewModel::class.java)) {
+                            @Suppress("UNCHECKED_CAST")
+                            return NavigationViewModel(initPage) as T
+                        }
+                        throw IllegalArgumentException("Unknown ViewModel class")
+                    }
+                },
+        )
+
     val currentPage by navigationViewModel.currentPage
     val isSidebarExpanded by navigationViewModel.isSidebarExpanded
     val context = LocalContext.current
@@ -65,6 +82,12 @@ fun DemoAppScreen() {
                 icon = Icons.Default.Home,
                 route = "map",
             ),
+            SidebarItem(
+                id = "marker-basic",
+                title = "Marker",
+                icon = Icons.Default.Home,
+                route = "marker-basic",
+            ),
             SidebarItem(
                 id = "flyTo",
                 title = "Move camera",
@@ -89,6 +112,12 @@ fun DemoAppScreen() {
                 icon = Icons.Default.PlayArrow,
                 route = "polyline",
             ),
+            SidebarItem(
+                id = "polygon",
+                title = "polygon ",
+                icon = Icons.Default.PlayArrow,
+                route = "polygon",
+            ),
             SidebarItem(
                 id = "animation",
                 title = "Animation ",
@@ -125,6 +154,11 @@ fun DemoAppScreen() {
                             onToggleSidebar = navigationViewModel::toggleSidebar,
                         )
                     }
+                    "marker-basic" -> {
+                        MarkerBasicPage(
+                            onToggleSidebar = navigationViewModel::toggleSidebar,
+                        )
+                    }
                     "circle" -> {
                         CircleMapPage(
                             onToggleSidebar = navigationViewModel::toggleSidebar,
@@ -135,14 +169,14 @@ fun DemoAppScreen() {
                             onToggleSidebar = navigationViewModel::toggleSidebar,
                         )
                     }
-                    "flyTo" -> {
-                        FlyToMapPage(
-                            icons = flyToMapPageIcons,
+                    "polygon" -> {
+                        PolygonMapPage(
                             onToggleSidebar = navigationViewModel::toggleSidebar,
                         )
                     }
-                    "animation" -> {
-                        AnimationMapPage(
+                    "flyTo" -> {
+                        FlyToMapPage(
+                            icons = flyToMapPageIcons,
                             onToggleSidebar = navigationViewModel::toggleSidebar,
                         )
                     }
@@ -152,6 +186,11 @@ fun DemoAppScreen() {
                             onToggleSidebar = navigationViewModel::toggleSidebar,
                         )
                     }
+                    "animation" -> {
+                        AnimationMapPage(
+                            onToggleSidebar = navigationViewModel::toggleSidebar,
+                        )
+                    }
                     "mapDesign" -> {
                         MapDesignMapPage(
                             onToggleSidebar = navigationViewModel::toggleSidebar,

example-app/src/main/java/com/mapconductor/example/MainActivity.kt

@@ -11,7 +11,9 @@ class MainActivity : ComponentActivity() {
         enableEdgeToEdge()
 
         setContent {
-            DemoAppScreen()
+            DemoAppScreen(
+                initPage = "map",
+            )
         }
     }
 }