GroundImage

Ground images are image overlays that are positioned geographically on the map. They are useful for displaying floor plans, satellite imagery, weather overlays, or any image-based data that needs to be anchored to specific geographic coordinates.

Composable Function

Basic GroundImage

@Composable
fun MapViewScope.GroundImage(
    bounds: GeoRectBounds,
    image: Drawable,
    opacity: Float = 0.5f,
    id: String? = null,
    extra: Serializable? = null
)

GroundImage with State

@Composable
fun MapViewScope.GroundImage(state: GroundImageState)

Parameters

• bounds: Geographic rectangular bounds where the image is positioned (GeoRectBounds)
• image: Drawable image to display (Drawable)
• opacity: Opacity level from 0.0 (transparent) to 1.0 (opaque) (default: 0.5f)
• id: Optional unique identifier for the GroundImage (String?)
• extra: Additional data attached to the GroundImage (Serializable?)

Usage Examples

Basic GroundImage

@Composable
fun BasicGroundImageExample(
    drawable: Drawable,
    modifier: Modifier = Modifier,
) {
    val mapViewState =
        rememberGoogleMapViewState(
            cameraPosition =
                MapCameraPosition(
                    position = GeoPoint(51.511649,-0.100761),
                    zoom = 12.0,
                ),
        )

    val bounds = GeoRectBounds(
        southWest = GeoPoint.fromLatLng(51.476747, -0.167729),
        northEast = GeoPoint.fromLatLng(51.546550,-0.033792),
    )
    GoogleMapView(
        modifier = modifier,
        state = mapViewState,
    ) {
        GroundImage(
            id = "groundimage",
            bounds = bounds,
            image = drawable,
            opacity = 0.6f
        )
    }
}

image: http://maps.bpl.org, CC BY 2.0, via Wikimedia Commons

Interactive GroundImage with Boundary Markers

@Composable
fun MapView(
    drawable: Drawable,
    modifier: Modifier = Modifier,
) {
    val mapViewState =
        rememberGoogleMapViewState(
            cameraPosition =
                MapCameraPosition(
                    position = GeoPoint(51.511649,-0.100761),
                    zoom = 12.0,
                ),
        )

    var marker1 by remember { mutableStateOf(MarkerState(
        position = GeoPoint.fromLatLong(51.476747,-0.167729),
        draggable = true,
    )) }
    var marker2 by remember { mutableStateOf(MarkerState(
        position = GeoPoint.fromLatLong(51.546550,-0.033792),
        draggable = true,
    )) }
    val bounds = GeoRectBounds(
        southWest = marker1.position as GeoPoint,
        northEast = marker2.position as GeoPoint,
    )
    var opacity by remember { mutableStateOf(0.7f) }

    Column(
        modifier = modifier,
    ) {
        Slider(
            value = opacity,
            onValueChange = { opacity = it },
            valueRange = 0f..1f,
            modifier = Modifier.padding(16.dp)
        )
        GoogleMapView(
            state = mapViewState,
        ) {
            Marker(marker1)
            Marker(marker2)
            GroundImage(
                id = "groundimage",
                bounds = bounds,
                image = drawable,
                opacity = opacity
            )
        }
    }
}

Event Handling

GroundImage interactions are handled by your map provider component:

@Composable
fun GroundImageEventHandlingExample(overlayImage: Drawable) {
    val mapViewState = rememberGoogleMapViewState()

    GoogleMapView(
        state = mapViewState
    ) {
        val imageBounds = GeoRectBounds(
            northWest = GeoPoint.fromLatLong(37.8, -122.5),
            southEast = GeoPoint.fromLatLong(37.7, -122.4)
        )

        GroundImage(
            bounds = imageBounds,
            image = overlayImage,
            opacity = 0.7f,
            extra = "Base map overlay",
            onClick = { groundImageEvent ->
                println("Ground image clicked at: ${groundImageEvent.clicked}")
                println("Ground image: ${groundImageEvent.state}")
            }
        )
    }
}