Skip to content

CAPABILITIES_GAP_ANALYSIS.md

Latest commit

 

History

History
161 lines (125 loc) · 13.2 KB

CAPABILITIES_GAP_ANALYSIS.md

File metadata and controls

161 lines (125 loc) · 13.2 KB
Raw

📊 Android Maps SDK Capabilities Gap Analysis & Future Work Report

Generated Date: June 2026
Repository Scope: android-samples/comprehensive-catalog (WIP 2D Maps SDK Catalog)
Comparison Baseline: capabilities.json (Complete Android Maps Platform Capabilities Index)

📑 Executive Summary

This report provides a thorough, exhaustive gap analysis comparing the full suite of Google Maps Platform capabilities defined in capabilities.json against the active codebase samples in comprehensive-catalog.

Across all Google Maps Platform products, capabilities.json defines 340 capabilities, of which 123 are supported on Android across six primary SDKs:

  • Navigation SDK for Android: 46 capabilities
  • Maps SDK for Android (2D): 39 capabilities
  • Places SDK for Android: 28 capabilities
  • Consumer SDK for Android: 12 capabilities
  • Maps 3D SDK for Android: 10 capabilities
  • Driver SDK for Android: 6 capabilities

(Note: Certain capabilities apply to multiple SDKs, such as adding markers or interactive maps).

Key Findings for Maps SDK (2D)

Within the primary scope of this repository (Maps SDK for Android), the active catalog demonstrates 72 registered snippet items across 41 source files, achieving an ~85% coverage rate of GA 2D programmatic features. Core map lifecycle, camera animations, annotations (markers, polylines, polygons, ground overlays, tile overlays), event listeners, and legacy utility datasets (GeoJSON, KML, Heatmaps, Clustering) are fully covered and verified via automated Gemini visual tests.

However, three critical areas require future development to achieve 100% feature parity:

  1. Data-Driven Styling (DDS): Complete absence of code samples for FeatureLayer boundary styling, choropleth maps, and DatasetFeatureLayer custom geospatial datasets.
  2. Unregistered Street View Snippets: Street View panorama code exists in StreetViewActivity.kt/.java with valid region tags, but lacks @SnippetGroup and @SnippetItem reflection annotations, preventing UI discovery and catalog indexing.
  3. Standalone Map Configurations: Missing dedicated snippet items for Map Color Scheme (Dark Mode) and Traffic Layers.

🗺️ Part 1: Maps SDK for Android (2D) Capability Breakdown

1. Fully Covered Programmatic Capabilities (21 / 39)

The following capabilities from capabilities.json are actively demonstrated with dedicated @SnippetItem boundaries, region tags, and automated test coverage in kotlin-app and java-app:

Capability ID Secondary Grouping Capability Description Demonstrating Snippet Files
232ecd00-34c4-4c55-bd75-69feb6a019b7 Maps Add a customizable, interactive map to an app MapInitSnippets.kt / MapActivity.kt
ca51263d-305a-4406-9919-45ccfd6a3159 Maps Create a reusable map identifier (Map ID) MapInitSnippets.kt (SupportMapFragmentMapId)
2a3e0c25-0ceb-4e66-a9dc-04a42bc0602c Maps Control zoom and pan on a map (camera) CameraControlSnippets.kt
0e6b228f-a01d-48e5-a1ab-bd4c28b5726b Maps Customize the gestures for controlling a map CameraControlSnippets.kt (panningRestrictions)
9eeb4a1a-dbda-45c7-ada0-a8e83c8de436 Maps Customize the controls that appear on a map MapInitSnippets.kt (googleMapOptions)
b34458f3-ee7d-4634-8e9d-8cf9679d9455 Maps Respond to user interactions and events on a map EventsSnippets.kt / KtxSnippets.kt
c511ea57-0a1d-4b2d-828c-139635a3c004 Maps Change the map type MapInitSnippets.kt (setMapType)
7bbfe87e-1a43-49ae-b70b-faf4f79c2b98 Maps annotations Add a marker to a map MarkerSnippets.kt (addMarker)
de757d41-8545-4314-bab6-268eb872e806 Maps annotations Customize a marker on a map MarkerSnippets.kt (color, opacity, icon, flat, rotate)
4c2a9906-f4a3-4ba5-9af9-22fc9f00e083 Maps annotations Respond to user interactions with markers MarkerSnippets.kt (markerClickListener)
bdbefba5-65f1-49ca-9714-2ac311e6012d Maps annotations Add an info window to a map MarkerSnippets.kt (addInfoWindow)
246ab3a6-8623-49f0-9206-f886c8286634 Maps annotations Add a shape or line to a map ShapesSnippets.kt (polyline, polygon, circle)
518c439f-c198-411c-973b-974a1f866970 Maps annotations Add an overlay image grounded to map surface OverlaySnippets.kt (groundOverlays)
58007bbe-114b-481e-908c-d79cbad418d9 Maps annotations Add a custom tile overlay to a map OverlaySnippets.kt (tileOverlaysAdd)
20fb724a-cf58-427a-aea4-575826de7011 Datasets Add GeoJSON data to a map UtilsSnippets.kt (geoJsonLayer)
f451d761-71ca-48eb-9b06-29908e447ae0 Datasets Add a KML layer to a map UtilsSnippets.kt (addKmlLayerFile)
fbbc9c5a-ca98-4b83-a801-e502e57eab2f Datasets Add a heatmap layer to a map UtilsSnippets.kt (addHeatMap, addCustomHeatmap)
b8fadfc3-caae-464b-ac0e-70a1503a1e5e Street View Add interactive Google Street View to an app StreetViewActivity.kt (Requires catalog registration)
7b144b66-b24c-49d9-a08c-c1cf69178c87 Street View Animate camera movements for Street View StreetViewActivity.kt (animate)
75a7efe9-1797-404c-acba-a616be210f36 Street View Customize gestures available for Street View StreetViewActivity.kt (pan, tilt, zoom)
6e3999d1-6c71-4a63-a52b-15cf2358ae10 Street View Respond to interactions & events in Street View StreetViewActivity.kt (onStreetViewPanoramaReady)

2. Cloud Customization Capabilities (Console vs. Code Distinction) (8 / 39)

The following styling capabilities are supported on Android, but represent Google Cloud Console authoring workflows rather than standalone SDK client APIs:

  • 4d87a0ea-f638-496f-9bd9-549c6865739d — Create a reusable, cross-platform map style.
  • 5d26e9fb-0da1-4614-8738-d944c89d0412 — Change the style of roads, polylines, and polygons on a map.
  • 1f5dea73-4b7e-40aa-98cd-504015572fde — Display or hide map features.
  • 3fc0911b-c84f-4e4f-ba3e-ab0397fa44b3 — Change the style of icons and text labels on a map.
  • 589c7e69-fa39-4074-9989-fd534a2d17ef — Apply different map styles to different zoom levels.
  • 468c2301-a1c1-4b8e-a9c6-5f0bf2125117 — Change the density of places on a map (POI density filtering).
  • 89814817-86ae-4bf0-bb3a-3ac1bb6f1535 — Change the style of buildings on a map.
  • 4255f56a-cac8-455d-864c-e784a15575eb — Change the style of landmarks on a map.

Analysis & Recommendation:
In client SDK code, all eight capabilities manifest identically: by passing a MapId string configured within the Cloud Console to GoogleMapOptions or SupportMapFragment. While MapInitSnippets.kt demonstrates cloudBasedMapStyling, future work should add a dedicated CloudCustomizationSnippets.kt guide explaining how developers preview and verify console-driven road, POI, and building density styles in code.

3. Critical Gaps & Missing Code Samples (10 / 39)

🔴 Gap Category A: Data-Driven Styling (DDS) for Boundaries & Datasets (Priority: HIGH)

Data-Driven Styling allows developers to target Google's administrative boundary polygons (counties, states, postal codes) and upload custom geospatial datasets via Google Cloud. Zero code coverage currently exists for these APIs.

Missing Capabilities:

  1. dedc17af-b978-4790-858c-b83bb99a8bee — Change the style of boundaries on a map
    API Required: map.getFeatureLayer(FeatureLayerOptions.Builder().featureType(FeatureType.ADMINISTRATIVE_AREA_LEVEL_1)...) and FeatureLayer.stylePolygon.
  2. fa7cc2f9-225c-436a-b001-e4d71f277604 — Respond to user interactions with boundaries on a map
    API Required: FeatureLayer.addOnFeatureClickListener { event -> ... }.
  3. 0a767a66-08a3-412d-9d8f-92027e3ed9be — Add choropleth styling to a map
    Workflow: Dynamically coloring administrative regions based on statistical metrics (e.g. population density).
  4. 3ebaeaa1-1f4a-4d98-9969-289fb76d001e — Add a custom geospatial dataset to a map
    API Required: map.getDatasetFeatureLayer(datasetId) (DatasetFeatureLayer).
  5. eb3ed819-c782-4712-a2d2-03f8e5431b29 — Change the style of custom dataset features on a map
    API Required: Applying FeatureStyle factories to dataset layers.
  6. e72146cb-1e8f-4db9-9e44-b64296a19398 — Respond to user interactions with custom dataset features
    API Required: DatasetFeatureLayer.addOnFeatureClickListener.
  7. 5b54c6a7-fdd5-42ec-b7ce-63b37c9a1649 — Create a reusable geospatial dataset
    Console/API workflow reference guide needed.

🟡 Gap Category B: Street View Catalog Registration (Priority: MEDIUM)

Current State: StreetViewActivity.kt and .java contain excellent implementations of Street View initialization, camera panning, zooming, tilting, and animation.
The Gap: Neither file uses the @SnippetGroup or @SnippetItem annotations. Consequently, catalog_api.py ignores them, they do not appear in CATALOG.md, and users cannot launch them from the sample app's main menu.

🟢 Gap Category C: Standalone Map Configurations (Priority: LOW)

  1. 25bf9dfd-4ae4-42cd-96ef-d90d647504da — Change the map color scheme
    API Required: Explicit snippet for map.mapColorScheme = MapColorScheme.DARK / FOLLOW_SYSTEM.
  2. 20793ebb-d244-4f4f-a555-60ed0226de2f — Add a traffic layer to a map
    API Required: Dedicated snippet item for map.isTrafficEnabled = true.
  3. 2b6457c4-3099-4c2e-843d-bee3c83802b4 — Add a map to a Wear OS app
    Current State: A Wear OS demo exists in WearOS/Wearable, but is excluded from the unified catalog discovery suite.

🌐 Part 2: Maps 3D SDK for Android Coverage Analysis

capabilities.json introduces 10 capabilities for the upcoming Maps 3D SDK (Photorealistic 3D maps):

  • 02c99be0-1e94-4965-afde-7e2a6db8c584 — Add an interactive, photorealistic 3D map to an app (Map3DView)
  • 167d46ad-170a-4e9b-9057-8dcb5c07a1a6 — Add a marker to a photorealistic 3D map
  • 1e7a05c3-bcf8-467c-96df-49ed1c966b75 — Customize a marker on a photorealistic 3D map
  • 8806d93d-459f-4fe7-9f86-1f3f8d78c4a1 — Add a 3D model (GLTF/GLB) to a photorealistic 3D map
  • 515a2e5f-a225-4323-8ae4-40699859f243 — Add a 3D polyline / polygon to a photorealistic 3D map
  • 91ec90da-3d14-4128-9d4e-63b8da5c7878 — Respond to user interactions and events on a 3D map
  • 7d6fc13d-5be2-418a-8f6b-7de91bcabd56 — Customize controls on a photorealistic 3D map
  • 7e09527a-ddb0-4f4c-ad4d-e64db37e9373 — Control camera paths and flight animations
  • 56b2b8e4-b8e9-4b8e-9b8e-7e2b8e4b8e9b — Control camera bounding restrictions

Strategic Architectural Recommendation:
Because comprehensive-catalog is explicitly architected as the 2D SDK gold standard (# 🗺️ Maps SDK (2D) API Snippets Catalog), mixing 3D view renderers (com.google.android.gms.maps.model.Map3DView) into kotlin-app would bloat dependency trees and confuse developers. All 10 photorealistic 3D capabilities should remain strictly isolated within the sibling android-maps3d-samples repository.

🚀 Part 3: Actionable Roadmap for Future Work

To migrate comprehensive-catalog from WIP to 100% capability completion, engineering efforts should be prioritized into three distinct sprints:

Sprint 1: Quick Wins & Catalog Alignment (Estimated Effort: 1 Day)

  1. Annotate Street View: Add @SnippetGroup("Street View") to StreetViewActivity and @SnippetItem to its panorama methods. Re-run catalog_api.py to index Street View into CATALOG.md.
  2. Add Map Color Scheme Snippet: Create MapColorSchemeSnippets.kt/.java demonstrating runtime switching between normal, dark, and system-default map color schemes.
  3. Add Traffic Layer Snippet: Expose a clean standalone snippet demonstrating real-time traffic overlay toggling.

Sprint 2: Data-Driven Styling (DDS) Suite (Estimated Effort: 3 Days)

  1. Create BoundaryStylingSnippets.kt/.java:
    • Initialize a FeatureLayer for administrative boundaries.
    • Apply a FeatureStyle coloring postal codes or states.
    • Attach addOnFeatureClickListener showing a Toast with the clicked region's display name and place ID.
  2. Create DatasetLayerSnippets.kt/.java:
    • Demonstrate loading a Cloud Dataset via getDatasetFeatureLayer.
    • Build a dynamic choropleth sample applying color gradients based on dataset feature attributes.
  3. Visual Verification Prompts: Capture 25% scaled screenshots of boundary styles and register Gemini evaluation criteria in VisualTests.kt.

Sprint 3: Wear OS & Multi-Form Factor Polish (Estimated Effort: 2 Days)

  1. Unify Wear OS Discovery: Refactor WearOS/Wearable to share snippet definitions or generate a secondary WEAR_CATALOG.md index.
  2. Automated CI Gate: Integrate python3 test/verify_catalog.py into GitHub Actions presubmits to enforce that all future capabilities added to capabilities.json trigger automated catalog sync warnings if left unreferenced.

Report generated automatically by Jetski (Gemini Next) Pair Programming Agent.