Animate images with image overlay | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Animate a series of images with an image overlay.

Image of animate images with image overlay

Use case

An image overlay is useful for displaying fast and dynamic images; for example, rendering real-time sensor data captured from a drone. Each frame from the drone becomes a static image which is updated on the fly as the data is made available.

How to use the sample

The application loads a map of the Southwestern United States. Tap the “Start” or “Stop” button to toggle the radar animation. Use the drop down menu to select how quickly the animation plays. Move the slider to change the opacity of the image overlay.

How it works

Create an ImageOverlay and add it to the SceneView.
Set up a timer with an initial interval time of 17ms, which will display approximately 60 ImageFrames per second.
On every tick of the timer, add the next image frame to the image overlay.

Relevant API

ImageFrame
ImageOverlay
SceneView

About the data

These radar images were captured by the US National Weather Service (NWS). They highlight the Pacific Southwest sector which is made up of part the western United States and Mexico. For more information visit the National Weather Service website.

Additional information

The supported image formats are GeoTIFF, TIFF, JPEG, and PNG. ImageOverlay does not support the rich processing and rendering capabilities of a RasterLayer. Use Raster and RasterLayer for static image rendering, analysis, and persistence.

This sample uses the GeoViewCompose Toolkit module to implement a Composable MapView.

Sample code

AnimateImagesWithImageOverlayViewModel.kt

DownloadActivity.kt

MainActivity.kt

AnimateImagesWithImageOverlayScreen.kt

/* Copyright 2024 Esri
 *
 * 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.esri.arcgismaps.sample.animateimageswithimageoverlay.components

import android.app.Application
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableFloatStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import com.arcgismaps.geometry.Envelope
import com.arcgismaps.geometry.Point
import com.arcgismaps.geometry.SpatialReference
import com.arcgismaps.mapping.ArcGISScene
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.mapping.view.Camera
import com.arcgismaps.mapping.view.ImageFrame
import com.arcgismaps.mapping.view.ImageOverlay
import com.esri.arcgismaps.sample.animateimageswithimageoverlay.R
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialogViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch
import java.io.File
import java.util.Timer
import kotlin.concurrent.fixedRateTimer

class AnimateImagesWithImageOverlayViewModel(application: Application) : AndroidViewModel(application) {

    private val provisionPath: String by lazy {
        application.getExternalFilesDir(null)?.path.toString() + File.separator + application.getString(
            R.string.animate_images_with_image_overlay_app_name
        )
    }

    // Get the folder path containing all the image overlays
    private val filePath = "$provisionPath/PacificSouthWest"

    var opacity by mutableFloatStateOf(1.0f)
        private set

    fun updateOpacity(opacityFromSlider: Float) {
        opacity = opacityFromSlider
        imageOverlay.opacity = opacity
    }

    val fpsOptions = listOf(60, 30, 15)
    private val _fps = MutableStateFlow(fpsOptions[1])
    val fps = _fps.asStateFlow()

    fun updateFpsOption(fpsIndex: Int) {
        _fps.value = fpsOptions[fpsIndex]
    }

    var isStarted by mutableStateOf(true)
        private set

    fun updateIsStarted(isStartedFromButton: Boolean) {
        isStarted = isStartedFromButton
        toggleAnimationTimer()
    }


    // Create an envelope of the pacific southwest sector for displaying the image frame
    private val pointForImageFrame = Point(
        x = -120.0724,
        y = 35.1310,
        spatialReference = SpatialReference.wgs84()
    )
    private val pacificSouthwestEnvelope = Envelope(
        center = pointForImageFrame,
        width = 15.0958,
        height = -14.3770
    )

    // Create a scene with the dark gray basemap and elevation source
    val arcGISScene by mutableStateOf(ArcGISScene(BasemapStyle.ArcGISDarkGray).apply {
        // Create a camera, looking at the pacific southwest sector
        val observationPoint = Point(-116.621, 24.7773, 856977.0)
        val camera = Camera(observationPoint, 353.994, 48.5495, 0.0)
        initialViewpoint = Viewpoint(pacificSouthwestEnvelope, camera)
    })

    // Create a message dialog view model for handling error messages
    val messageDialogVM = MessageDialogViewModel()

    // Keep track of the list of image frames added in cache
    private var imageFrames = mutableListOf<ImageFrame>()

    // Keep track of the image frame currently in view
    private var imageFrameIndex = 0

    // Timer task to customize frame rates
    private var timer: Timer? = null

    var imageOverlay = ImageOverlay()
        private set

    init {

        // Get the image files from local storage
        (File(filePath).listFiles())?.sorted()?.forEach { imageFile ->
            // Create an image with the given path and use it to create an image frame
            val imageFrame = ImageFrame(imageFile.path, pacificSouthwestEnvelope)
            imageFrames.add(imageFrame)
        }
        // Set the initial image frame to image overlay
        imageOverlay.imageFrame = imageFrames[imageFrameIndex]

        viewModelScope.launch {
            arcGISScene.load().onFailure { error ->
                messageDialogVM.showMessageDialog(
                    "Failed to load map",
                    error.message.toString()
                )
            }

            // On changes to the fps, create a new timer
            _fps.collect {
                if (isStarted) {
                    createNewTimer()
                }
            }
        }

        // Start the animation timer
        createNewTimer()
    }

    /**
     * Create a new image frame from the image at the current index and add it to the image overlay.
     */
    private fun addNextImageFrameToImageOverlay() {
        // Set image frame to image overlay
        imageOverlay.imageFrame = imageFrames[imageFrameIndex]
        // Increment the index to keep track of which image to load next
        imageFrameIndex++
        // Reset index once all files have been loaded
        if (imageFrameIndex == imageFrames.size)
            imageFrameIndex = 0
    }

    /**
     * Create a new timer for the given period which repeatedly calls [addNextImageFrameToImageOverlay]..
     */
    private fun createNewTimer() {
        // Get the current period from the fps state flow
        val period = when (_fps.value) {
            60 -> 17 // 1000ms/17 = 60 fps
            30 -> 33 // 1000ms/33 = 30 fps
            15 -> 67 // 1000ms/67 = 15 fps
            else -> 0
        }
        // Cancel any timers that might be running
        timer?.cancel()
        timer = null
        // Create a new timer with the given period
        timer = fixedRateTimer("Image overlay timer", period = period.toLong()) {
            addNextImageFrameToImageOverlay()
        }
    }

    /**
     * Toggles starting and stopping the timer on button tap.
     */
    private fun toggleAnimationTimer() {
        timer?.let {
            // Cancel any running timer
            timer?.cancel()
            timer = null
            // Change the start/stop button to "start"
            isStarted = false
        } ?: run {
            createNewTimer()
            // Change the start/stop button to "stop"
            isStarted = true
        }
    }
}

/* Copyright 2024 Esri
 *
 * 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.esri.arcgismaps.sample.animateimageswithimageoverlay

import android.content.Intent
import android.os.Bundle
import com.esri.arcgismaps.sample.sampleslib.DownloaderActivity

class DownloadActivity : DownloaderActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        downloadAndStartSample(
            Intent(this, MainActivity::class.java),
            // get the app name of the sample
            getString(R.string.animate_images_with_image_overlay_app_name),
            listOf(
                // ArcGIS Portal item containing the zip of Reflectivity radar images.
                "https://www.arcgis.com/home/item.html?id=9465e8c02b294c69bdb42de056a23ab1"
            )
        )
    }
}

/* Copyright 2024 Esri
 *
 * 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.esri.arcgismaps.sample.animateimageswithimageoverlay

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.runtime.Composable
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.esri.arcgismaps.sample.animateimageswithimageoverlay.screens.AnimateImagesWithImageOverlayScreen
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Authentication with an API key or named user is
        // required to access basemaps and other location services
        ArcGISEnvironment.apiKey = ApiKey.create(BuildConfig.ACCESS_TOKEN)

        enableEdgeToEdge()
        setContent {
            SampleAppTheme {
                AnimateImagesWithImageOverlayApp()
            }
        }
    }

    @Composable
    private fun AnimateImagesWithImageOverlayApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            AnimateImagesWithImageOverlayScreen(
                sampleName = getString(R.string.animate_images_with_image_overlay_app_name)
            )
        }
    }
}

/* Copyright 2024 Esri
 *
 * 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.esri.arcgismaps.sample.animateimageswithimageoverlay.screens

import android.content.res.Configuration
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.layout.wrapContentHeight
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Settings
import androidx.compose.material3.Button
import androidx.compose.material3.DropdownMenuItem
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.ExposedDropdownMenuBox
import androidx.compose.material3.ExposedDropdownMenuDefaults
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.MenuAnchorType
import androidx.compose.material3.ModalBottomSheet
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Slider
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.material3.TextField
import androidx.compose.material3.rememberModalBottomSheetState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.toolkit.geoviewcompose.SceneView
import com.esri.arcgismaps.sample.animateimageswithimageoverlay.components.AnimateImagesWithImageOverlayViewModel
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialog
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
import kotlin.math.roundToInt


/**
 * Main screen layout for the sample app
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun AnimateImagesWithImageOverlayScreen(sampleName: String) {
    val sceneViewModel: AnimateImagesWithImageOverlayViewModel = viewModel()
    // Set up the bottom sheet controls
    val controlsBottomSheetState = rememberModalBottomSheetState(skipPartiallyExpanded = true)
    var isBottomSheetVisible by remember { mutableStateOf(false) }
    LaunchedEffect(isBottomSheetVisible) {
        when {
            isBottomSheetVisible -> controlsBottomSheetState.show()
            else -> controlsBottomSheetState.hide()
        }
    }

    Scaffold(
        topBar = { SampleTopAppBar(title = sampleName) },
        floatingActionButton = {
            if (!isBottomSheetVisible) {
                FloatingActionButton(
                    modifier = Modifier.padding(bottom = 36.dp, end = 12.dp),
                    onClick = { isBottomSheetVisible = true }
                ) { Icon(Icons.Filled.Settings, contentDescription = "Show ImageOverlay menu") }
            }
        },
        content = {
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(it)
            ) {
                SceneView(
                    modifier = Modifier
                        .fillMaxSize(),
                    arcGISScene = sceneViewModel.arcGISScene,
                    imageOverlays = listOf(sceneViewModel.imageOverlay)
                )
                if (isBottomSheetVisible) {
                    ModalBottomSheet(
                        modifier = Modifier.wrapContentHeight(),
                        sheetState = controlsBottomSheetState,
                        onDismissRequest = { isBottomSheetVisible = false }
                    ) {
                        ImageOverlayMenu(
                            isStarted = sceneViewModel.isStarted,
                            fps = sceneViewModel.fps.collectAsState().value,
                            opacity = sceneViewModel.opacity,
                            fpsOptions = sceneViewModel.fpsOptions,
                            onFpsOptionSelected = sceneViewModel::updateFpsOption,
                            onOpacityChanged = sceneViewModel::updateOpacity,
                            onIsStartedChanged = sceneViewModel::updateIsStarted
                        )
                    }
                }
                sceneViewModel.messageDialogVM.apply {
                    if (dialogStatus) {
                        MessageDialog(
                            title = messageTitle,
                            description = messageDescription,
                            onDismissRequest = ::dismissDialog
                        )
                    }
                }
            }
        })
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
private fun ImageOverlayMenu(
    isStarted: Boolean,
    fps: Int,
    opacity: Float,
    fpsOptions: List<Int>,
    onFpsOptionSelected: (Int) -> Unit,
    onOpacityChanged: (Float) -> Unit,
    onIsStartedChanged: (Boolean) -> Unit
) {

    Column(
        modifier = Modifier
            .fillMaxWidth()
            .padding(24.dp),
        verticalArrangement = Arrangement.spacedBy(12.dp),
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text(
            text = "Image overlay options",
            style = MaterialTheme.typography.headlineSmall
        )

        HorizontalDivider()

        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            Text(
                text = "Opacity:",
                style = MaterialTheme.typography.labelLarge
            )
            Text(
                text = (opacity * 100).roundToInt().toString() + "%",
                style = MaterialTheme.typography.labelLarge
            )
        }

        // Opacity Slider
        Slider(
            modifier = Modifier
                .fillMaxWidth()
                .padding(horizontal = 24.dp),
            value = opacity,
            onValueChange = { onOpacityChanged(it) },
            valueRange = 0f..1.0f
        )

        Row(
            modifier = Modifier.fillMaxWidth(),
            horizontalArrangement = Arrangement.SpaceEvenly,
            verticalAlignment = Alignment.CenterVertically
        ) {
            // FPS Dropdown Menu
            var expanded by remember { mutableStateOf(false) }
            ExposedDropdownMenuBox(
                modifier = Modifier.width(150.dp),
                expanded = expanded,
                onExpandedChange = { expanded = !expanded }
            ) {
                TextField(
                    value = "$fps fps",
                    onValueChange = {},
                    readOnly = true,
                    trailingIcon = { ExposedDropdownMenuDefaults.TrailingIcon(expanded = expanded) },
                    modifier = Modifier.menuAnchor(type = MenuAnchorType.PrimaryNotEditable)
                )
                ExposedDropdownMenu(
                    expanded = expanded,
                    onDismissRequest = { expanded = false }
                ) {
                    fpsOptions.forEachIndexed { index, fps ->
                        DropdownMenuItem(
                            text = { Text("$fps fps") },
                            onClick = {
                                onFpsOptionSelected(index)
                                expanded = false
                            })
                        // Show a divider between dropdown menu options
                        if (index < fpsOptions.lastIndex) {
                            HorizontalDivider()
                        }
                    }
                }
            }

            // Start/Stop Button
            Button(onClick = { onIsStartedChanged(!isStarted) }) {
                Text(if (isStarted) "Stop" else "Start")
            }
        }
    }
}

@Preview(showBackground = true)
@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES, showBackground = true)
@Composable
fun ClusterInfoContentPreview() {
    SampleAppTheme {
        Surface {
            ImageOverlayMenu(
                isStarted = true,
                fps = 60,
                opacity = 1F,
                fpsOptions = listOf(60, 30, 15),
                onFpsOptionSelected = { },
                onOpacityChanged = { },
                onIsStartedChanged = { }
            )
        }
    }
}