feat: Maps 3D Compose Wrapper and Samples

Maps3DSamples/ApiDemos/java-app/build.gradle.kts

@@ -64,10 +64,6 @@ if (!isCI) {
             if (apiKey.isNullOrBlank() || !apiKey.matches(Regex("^AIza[a-zA-Z0-9_-]{35}$"))) {
                 throw GradleException("Invalid or missing MAPS3D_API_KEY in secrets.properties. Please provide a valid Google Maps API key (starts with 'AIza').")
             }
-
-            if (secrets.getProperty("MAPS_API_KEY") != null) {
-                println("Warning: Found MAPS_API_KEY in secrets.properties. This project relies exclusively on MAPS3D_API_KEY.")
-            }
         }
     }
 }

Maps3DSamples/ApiDemos/java-app/src/main/java/com/example/maps3djava/markers/MarkersActivity.java

@@ -495,7 +495,7 @@ private void advanceTour(GoogleMap3D map) {
                 .thenComposeAsync(isSteady -> {
                     // If the user tapped "Stop" while we were waiting, gracefully exit the chain.
                     if (!isTourActive)
-                        return CompletableFuture.completedFuture((Void) null);
+                        return CompletableFuture.completedFuture(null);
 
                     FlyAroundOptions orbitOptions = new FlyAroundOptions(camera, 5000L, 1.0);
                     return com.example.maps3djava.common.MapUtils.awaitCameraAnimation(map, orbitOptions);

Maps3DSamples/ApiDemos/kotlin-app/build.gradle.kts

@@ -65,10 +65,6 @@ if (!isCI) {
             if (apiKey.isNullOrBlank() || !apiKey.matches(Regex("^AIza[a-zA-Z0-9_-]{35}$"))) {
                 throw GradleException("Invalid or missing MAPS3D_API_KEY in secrets.properties. Please provide a valid Google Maps API key (starts with 'AIza').")
             }
-
-            if (secrets.getProperty("MAPS_API_KEY") != null) {
-                println("Warning: Found MAPS_API_KEY in secrets.properties. This project relies exclusively on MAPS3D_API_KEY.")
-            }
         }
     }
 }

Maps3DSamples/ApiDemos/kotlin-app/src/main/java/com/example/maps3dkotlin/models/ModelsActivity.kt

@@ -20,7 +20,6 @@ import android.widget.Toast
 import androidx.lifecycle.lifecycleScope
 import com.example.maps3d.common.awaitCameraUpdate
 import com.example.maps3d.common.toCameraUpdate
-import com.example.maps3d.common.toValidCamera
 import com.example.maps3dcommon.R
 import com.example.maps3dkotlin.sampleactivity.SampleBaseActivity
 import com.google.android.gms.maps3d.GoogleMap3D
@@ -35,10 +34,9 @@ import com.google.android.gms.maps3d.model.orientation
 import com.google.android.gms.maps3d.model.vector3D
 import com.google.android.material.button.MaterialButton
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
-import kotlinx.coroutines.FlowPreview
-import kotlinx.coroutines.flow.sample
 import kotlinx.coroutines.launch
 import kotlin.time.Duration.Companion.milliseconds
 import kotlin.time.Duration.Companion.seconds

Maps3DSamples/ApiDemos/kotlin-app/src/main/java/com/example/maps3dkotlin/polygons/PolygonsActivity.kt

@@ -15,7 +15,6 @@
 package com.example.maps3dkotlin.polygons
 
 import android.graphics.Color
-import android.os.Bundle
 import android.util.Log
 import android.widget.Toast
 import androidx.lifecycle.lifecycleScope
@@ -36,8 +35,6 @@ import com.google.android.gms.maps3d.model.latLngAltitude
 import com.google.android.gms.maps3d.model.polygonOptions
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
-import kotlin.time.Duration.Companion.milliseconds
-import kotlin.time.Duration.Companion.seconds
 
 /**
  * This activity demonstrates how to create and display polygons on a 3D map. It showcases
@@ -163,7 +160,6 @@ class PolygonsActivity : SampleBaseActivity() {
     }
 
     companion object {
-        private val TAG = PolygonsActivity::class.java.simpleName
         private const val DENVER_LATITUDE = 39.748477
         private const val DENVER_LONGITUDE = -104.947575
 

Maps3DSamples/advanced/app/build.gradle.kts

@@ -64,10 +64,6 @@ if (!isCI) {
             if (apiKey.isNullOrBlank() || !apiKey.matches(Regex("^AIza[a-zA-Z0-9_-]{35}$"))) {
                 throw GradleException("Invalid or missing MAPS3D_API_KEY in secrets.properties. Please provide a valid Google Maps API key (starts with 'AIza').")
             }
-
-            if (secrets.getProperty("MAPS_API_KEY") != null) {
-                println("Warning: Found MAPS_API_KEY in secrets.properties. This project relies exclusively on MAPS3D_API_KEY.")
-            }
         }
     }
 }

README.md

@@ -49,6 +49,16 @@ The [Maps3DSamples/ApiDemos/common](Maps3DSamples/ApiDemos/common) module contai
 It also has [Map3dViewModel](Maps3DSamples/advanced/app/src/main/java/com/example/advancedmaps3dsamples/common/Map3dViewModel.kt) which demonstrates how to
 create an abstract base class for view models needing to interact with the Maps3DView via a GoogleMap3D.
 
+## Experimental Compose Wrapper
+
+In addition to the advanced sample, this repository contains an experimental, declarative Compose wrapper for the Maps 3D SDK:
+
+* **[maps3d-compose](maps3d-compose)**: Provides the `GoogleMap3D` composable and supports declarative state management for markers, polylines, polygons, models, and popovers.
+* **[maps3d-compose-demo](maps3d-compose-demo)**: Contains sample activities demonstrating how to use the wrapper.
+
+> [!WARNING]
+> These modules are a **Work In Progress (WIP) experiment** and serve as a **reference implementation**. They are not intended for production use.
+
 ## Requirements
 
 To run the samples, you will need:

maps3d-compose-demo/README.md

@@ -0,0 +1,22 @@
+# Maps 3D Compose Demo
+
+This module is a sample application that demonstrates how to use the `maps3d-compose` wrapper library.
+
+> [!WARNING]
+> **Status**: This application serves as a **reference implementation** for using the experimental Compose wrapper. It is a WIP experiment.
+
+## What's Inside
+
+You can find several sample activities demonstrating different features of the 3D Map in Compose:
+- **Basic Map**: A simple map with camera controls.
+- **Map Options**: Demonstrates changing map modes (Satellite/Hybrid) and applying camera restrictions.
+- **Models**: Shows how to add and interact with 3D models (glTF) on the map, including click listeners.
+- **Popovers**: Demonstrates the declarative Popover API, rendering Compose content inside native map popovers.
+
+## How to Run
+
+You can install and run this demo on a connected device or emulator using:
+```bash
+./gradlew :maps3d-compose-demo:installDebug
+```
+Then launch any of the activities via the launcher or ADB.

maps3d-compose-demo/build.gradle.kts

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.secrets.gradle.plugin)
+    id("com.diffplug.spotless") version "6.25.0"
+}
+
+configure<com.diffplug.gradle.spotless.SpotlessExtension> {
+    kotlin {
+        target("**/*.kt")
+        ktlint().editorConfigOverride(mapOf("indent_size" to "4", "ktlint_function_naming_ignore_when_annotated_with" to "Composable"))
+        trimTrailingWhitespace()
+        endWithNewline()
+    }
+}
+
+android {
+    namespace = "com.example.maps3dcomposedemo"
+    compileSdk = libs.versions.compileSdk.get().toInt()
+
+    defaultConfig {
+        applicationId = "com.example.maps3dcomposedemo"
+        minSdk = libs.versions.minSdk.get().toInt()
+        targetSdk = libs.versions.targetSdk.get().toInt()
+        versionCode = 1
+        versionName = "1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+        vectorDrawables {
+            useSupportLibrary = true
+        }
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+    kotlin {
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+        }
+    }
+    buildFeatures {
+        compose = true
+        buildConfig = true
+    }
+    packaging {
+        resources {
+            excludes += "/META-INF/{AL2.0,LGPL2.1}"
+        }
+    }
+}
+
+dependencies {
+    implementation(project(":maps3d-compose"))
+
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.activity.compose)
+
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.ui)
+    implementation(libs.androidx.ui.graphics)
+    implementation(libs.androidx.ui.tooling.preview)
+    implementation(libs.androidx.material3)
+
+    // Maps 3D SDK
+    implementation(libs.play.services.maps3d)
+
+    testImplementation(libs.junit)
+    androidTestImplementation(libs.androidx.junit)
+    androidTestImplementation(libs.androidx.espresso.core)
+    androidTestImplementation(platform(libs.androidx.compose.bom))
+    androidTestImplementation(libs.androidx.ui.test.junit4)
+    androidTestImplementation(libs.androidx.uiautomator)
+    androidTestImplementation(libs.kotlinx.serialization.json)
+    androidTestImplementation(project(":visual-testing"))
+    debugImplementation(libs.androidx.ui.tooling)
+    debugImplementation(libs.androidx.ui.test.manifest)
+}
+
+secrets {
+    propertiesFileName = "secrets.properties"
+}
+
+tasks.register<Exec>("installAndLaunch") {
+    description = "Installs and launches the demo app."
+    group = "install"
+    dependsOn("installDebug")
+    commandLine("adb", "shell", "am", "start", "-n", "com.example.maps3dcomposedemo/.MainActivity")
+}

maps3d-compose-demo/src/androidTest/java/com/example/maps3dcomposedemo/BaseVisualTest.kt

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.example.maps3dcomposedemo
+
+import android.app.Instrumentation
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.uiautomator.By
+import androidx.test.uiautomator.UiDevice
+import androidx.test.uiautomator.Until
+import com.google.maps.android.visualtesting.GeminiVisualTestHelper
+import org.junit.Assert.assertTrue
+import java.io.File
+
+abstract class BaseVisualTest {
+
+    protected val instrumentation: Instrumentation = InstrumentationRegistry.getInstrumentation()
+    protected val uiDevice = UiDevice.getInstance(instrumentation)
+    protected val context: Context = instrumentation.targetContext
+    protected val helper = GeminiVisualTestHelper()
+
+    protected val geminiApiKey: String by lazy {
+        val key = BuildConfig.GEMINI_API_KEY
+        assertTrue(
+            "GEMINI_API_KEY is not set in secrets.properties. Please add GEMINI_API_KEY=YOUR_API_KEY to your secrets.properties file.",
+            key != "YOUR_GEMINI_API_KEY",
+        )
+        key
+    }
+
+    protected fun captureScreenshot(filename: String = "screenshot_${System.currentTimeMillis()}.png"): Bitmap {
+        val screenshotFile = File(context.getExternalFilesDir(null), filename)
+        val screenshotTaken = uiDevice.takeScreenshot(screenshotFile)
+        assertTrue("Failed to take screenshot: $filename", screenshotTaken)
+
+        val bitmap = BitmapFactory.decodeFile(screenshotFile.absolutePath)
+        assertTrue("Failed to decode screenshot file: $filename", bitmap != null)
+
+        println("Screenshot saved to device: ${screenshotFile.absolutePath}")
+        println("To pull: adb pull ${screenshotFile.absolutePath}")
+
+        return bitmap
+    }
+
+    /**
+     * Waits for the map to render.
+     * Since MapView content (tiles, markers) is rendered on a GL surface and not exposed as
+     * accessibility nodes, we cannot rely on UiAutomator looking for text/markers.
+     * We use a stable delay to ensure rendering is complete.
+     */
+    protected fun waitForMapRendering(timeoutSeconds: Long = 30) {
+        val found = uiDevice.wait(Until.hasObject(By.desc("MapSteady")), timeoutSeconds * 1000)
+        assertTrue("Map did not become steady within $timeoutSeconds seconds", found)
+    }
+}