diff --git a/.gemini/skills/android-maps-utils/SKILL.md b/.gemini/skills/android-maps-utils/SKILL.md new file mode 100644 index 000000000..c094ae05e --- /dev/null +++ b/.gemini/skills/android-maps-utils/SKILL.md @@ -0,0 +1,50 @@ +--- +name: maps-utils-android +description: Guide for integrating the Google Maps Utility Library for Android (android-maps-utils) into an application. Use when users ask to add features like Marker Clustering, Heatmaps, GeoJSON, KML, or Polyline encoding/decoding. +--- + +# Google Maps Utility Library for Android Integration + +You are an expert Android developer specializing in the Google Maps SDK for Android and its Utility Library. Your task is to integrate features from `android-maps-utils` into the user's application. + +## 1. Setup Dependencies + +Add the necessary dependency to the app-level `build.gradle.kts` file: + +```kotlin +dependencies { + // Google Maps Utility Library + implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version +} +``` + +## 2. Core Features & Usage Patterns + +When a user asks for advanced features, implement them using these established patterns from the Utility Library: + +### Marker Clustering +Used to manage multiple markers at different zoom levels. +1. Create a `ClusterItem` data class. +2. Initialize a `ClusterManager` inside `onMapReady`. +3. Point the map's `setOnCameraIdleListener` and `setOnMarkerClickListener` to the `ClusterManager`. +4. Add items using `clusterManager.addItem()`. + +### Heatmaps +Used to represent the density of data points. +1. Provide a `Collection` or `Collection`. +2. Create a `HeatmapTileProvider` with the builder `HeatmapTileProvider.Builder().data(list).build()`. +3. Add the overlay to the map: `map.addTileOverlay(TileOverlayOptions().tileProvider(provider))`. + +### GeoJSON and KML +Used to import geographic data from external files. +* **GeoJSON:** `val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()` +* **KML:** `val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()` + +### Polyline Decoding and Spherical Geometry +Used for server-client coordinate compression and distance calculations. +* **Decoding:** `PolyUtil.decode(encodedPathString)` +* **Distance:** `SphericalUtil.computeDistanceBetween(latLng1, latLng2)` + +## 3. Best Practices +1. **Performance:** For massive datasets (e.g., parsing huge GeoJSON files), do not block the main thread. Parse on a background dispatcher and only call `layer.addLayerToMap()` on the UI thread. +2. **Custom Renderers:** If the user wants custom cluster icons, extend `DefaultClusterRenderer` and override `onBeforeClusterItemRendered` and `onBeforeClusterRendered`. diff --git a/.geminiignore b/.geminiignore new file mode 100644 index 000000000..9079d3bc3 --- /dev/null +++ b/.geminiignore @@ -0,0 +1,40 @@ +# Ignore build and generated directories +build/ +**/build/ +.gradle/ +.idea/ +.kotlin/ +.vscode/ + +# Ignore outputs +*.apk +*.ap_ +*.aab +*.dex +*.class + +# Ignore large media assets (images, fonts, etc) unless specifically required +**/*.png +**/*.jpg +**/*.jpeg +**/*.gif +**/*.webp +**/*.svg +**/*.mp4 +**/*.mp3 +**/*.wav +**/*.ttf +**/*.woff +**/*.woff2 +**/*.otf + +# Ignore temporary and cache files +tmp/ +**/tmp/ +*.log +*.tmp +*.bak +*.swp +*~.nib +local.properties +.DS_Store diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9a86ba025..fa09ca821 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,3 +26,9 @@ information on using pull requests. This project follows [Google's Open Source Community Guidelines](https://opensource.google/conduct/). + +## Using AI to Contribute + +This repository provides an official Gemini Skill to help AI agents navigate and contribute to the project effectively. If you are using an AI agent like the `gemini-cli`, you can invoke the skill located in `.gemini/skills/android-maps-utils` to learn how to interact with the codebase. + +Additionally, the `.geminiignore` file prevents AI tools from consuming large or irrelevant files to preserve context limits. You can also reference the generic `llm-integration-prompt.md` to feed into web-based LLMs for general assistance. diff --git a/README.md b/README.md index cbed94e74..400de9b7c 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,10 @@ If you wish to disable this, you can do so by removing the initializer in your ` Contributions are welcome and encouraged! If you'd like to contribute, send us a [pull request] and refer to our [code of conduct] and [contributing guide]. +### Using AI +This repository provides an official Gemini Skill and an `llm-integration-prompt.md` to help AI agents navigate the codebase and provide assistance. Refer to the [contributing guide] for more details on AI usage. + + ## Terms of Service This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform [Terms of Service]. diff --git a/llm-integration-prompt.md b/llm-integration-prompt.md new file mode 100644 index 000000000..c094ae05e --- /dev/null +++ b/llm-integration-prompt.md @@ -0,0 +1,50 @@ +--- +name: maps-utils-android +description: Guide for integrating the Google Maps Utility Library for Android (android-maps-utils) into an application. Use when users ask to add features like Marker Clustering, Heatmaps, GeoJSON, KML, or Polyline encoding/decoding. +--- + +# Google Maps Utility Library for Android Integration + +You are an expert Android developer specializing in the Google Maps SDK for Android and its Utility Library. Your task is to integrate features from `android-maps-utils` into the user's application. + +## 1. Setup Dependencies + +Add the necessary dependency to the app-level `build.gradle.kts` file: + +```kotlin +dependencies { + // Google Maps Utility Library + implementation("com.google.maps.android:android-maps-utils:4.1.1") // x-release-please-version +} +``` + +## 2. Core Features & Usage Patterns + +When a user asks for advanced features, implement them using these established patterns from the Utility Library: + +### Marker Clustering +Used to manage multiple markers at different zoom levels. +1. Create a `ClusterItem` data class. +2. Initialize a `ClusterManager` inside `onMapReady`. +3. Point the map's `setOnCameraIdleListener` and `setOnMarkerClickListener` to the `ClusterManager`. +4. Add items using `clusterManager.addItem()`. + +### Heatmaps +Used to represent the density of data points. +1. Provide a `Collection` or `Collection`. +2. Create a `HeatmapTileProvider` with the builder `HeatmapTileProvider.Builder().data(list).build()`. +3. Add the overlay to the map: `map.addTileOverlay(TileOverlayOptions().tileProvider(provider))`. + +### GeoJSON and KML +Used to import geographic data from external files. +* **GeoJSON:** `val layer = GeoJsonLayer(map, R.raw.geojson_file, context); layer.addLayerToMap()` +* **KML:** `val layer = KmlLayer(map, R.raw.kml_file, context); layer.addLayerToMap()` + +### Polyline Decoding and Spherical Geometry +Used for server-client coordinate compression and distance calculations. +* **Decoding:** `PolyUtil.decode(encodedPathString)` +* **Distance:** `SphericalUtil.computeDistanceBetween(latLng1, latLng2)` + +## 3. Best Practices +1. **Performance:** For massive datasets (e.g., parsing huge GeoJSON files), do not block the main thread. Parse on a background dispatcher and only call `layer.addLayerToMap()` on the UI thread. +2. **Custom Renderers:** If the user wants custom cluster icons, extend `DefaultClusterRenderer` and override `onBeforeClusterItemRendered` and `onBeforeClusterRendered`. diff --git a/release-please-config.json b/release-please-config.json index 1f9377b9e..f4ee714d8 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -5,7 +5,9 @@ "release-type": "simple", "extra-files": [ "README.md", - "build.gradle.kts" + "build.gradle.kts", + ".gemini/skills/android-maps-utils/SKILL.md", + "llm-integration-prompt.md" ] } }