Add dynamic entity layer | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Display data from an ArcGIS stream service using a dynamic entity layer.

Image of add dynamic entity layer

Use case

A stream service is a type of service provided by ArcGIS Velocity and GeoEvent Server that allows clients to receive a stream of data observations via a web socket. ArcGIS Maps SDK for Kotlin allows you to connect to a stream service and manage the information as dynamic entities and display them in a dynamic entity layer. Displaying information from feeds such as a stream service is important in applications like dashboards where users need to visualize and track updates of real-world objects in real-time.

Use ArcGISStreamService to manage the connection to the stream service and purge options to manage how much data is stored and maintained by the application. The dynamic entity layer will display the latest received observation, and you can set track display properties to determine how to display historical information for each dynamic entity. This includes the number of previous observations to show, whether to display track lines in-between previous observations, and setting renderers.

How to use the sample

Use the controls to connect to or disconnect from the stream service, modify display properties in the dynamic entity layer, and purge all observations from the application.

How it works

Create an ArcGIStreamService using a Url.
Set a DynamicEntityFilter on the stream service to limit the amount of data coming from the server.
Set the MaximumDuration property of the stream service PurgeOptions to limit the amount of data managed by the application.
Create a DynamicEntityLayer using the stream service.
Update values in the layer’s TrackDisplayProperties to customize the layer’s appearance.
Add the DynamicEntityLayer to the map.

Relevant API

ArcGISStreamService
DynamicEntity
DynamicEntityFilter
DynamicEntityLayer
DynamicEntityPurgeOptions
TrackDisplayProperties

About the data

This sample uses a stream service that simulates live data coming from snowplows near Sandy, Utah. There are multiple vehicle types and multiple agencies operating the snowplows.

Additional information

This sample uses the GeoView-Compose Toolkit module to be able to implement a composable MapView. More information about dynamic entities can be found in the guide documentation.

Sample Code

MainActivity.kt

BottomSheetContent.kt

MapViewModel.kt

MainScreen.kt

/* Copyright 2023 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.adddynamicentitylayer

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.sampleslib.theme.SampleAppTheme
import com.esri.arcgismaps.sample.adddynamicentitylayer.screens.MainScreen

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 {
                AddDynamicEntityLayerApp()
            }
        }
    }

    @Composable
    private fun AddDynamicEntityLayerApp() {
        Surface(
            color = MaterialTheme.colorScheme.background
        ) {
            MainScreen(
                sampleName = getString(R.string.add_dynamic_entity_layer_app_name)
            )
        }
    }
}

/* Copyright 2023 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.adddynamicentitylayer.components

import android.content.res.Configuration
import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.shape.RoundedCornerShape
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Slider
import androidx.compose.material3.Surface
import androidx.compose.material3.Switch
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.ui.Alignment
import androidx.compose.ui.Alignment.Companion.CenterHorizontally
import androidx.compose.ui.Modifier
import androidx.compose.ui.tooling.preview.Preview
import androidx.compose.ui.unit.dp
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
import com.esri.arcgismaps.sample.sampleslib.theme.SampleTypography
import kotlin.math.roundToInt

/**
 * Composable component to display Dynamic Entity Layer Settings
 */
@Composable
fun DynamicEntityLayerProperties(
    onTrackLineVisibilityChanged: (Boolean) -> Unit = { },
    onPrevObservationsVisibilityChanged: (Boolean) -> Unit = { },
    onObservationsChanged: (Float) -> Unit = { },
    onPurgeAllObservations: () -> Unit = { },
    isTrackLineVisible: Boolean,
    isPrevObservationsVisible: Boolean,
    observationsPerTrack: Float,
    onDismiss: () -> Unit = { }
) {
    Column(Modifier.background(MaterialTheme.colorScheme.background)) {
        Row(
            modifier = Modifier.fillMaxWidth().padding(20.dp, 20.dp, 20.dp, 0.dp),
            verticalAlignment = Alignment.CenterVertically,
            horizontalArrangement = Arrangement.SpaceBetween
        ) {
            Text(
                style = SampleTypography.titleMedium,
                text = "Dynamic Entity Settings",
                color = MaterialTheme.colorScheme.primary
            )
            TextButton(
                onClick = onDismiss
            ) {
                Text(text = "Done")
            }
        }

        Surface(
            modifier = Modifier.padding(20.dp),
            tonalElevation = 1.dp,
            shape = RoundedCornerShape(20.dp),
            border = BorderStroke(1.dp, MaterialTheme.colorScheme.outlineVariant)
        ) {
            Column(
                modifier = Modifier.padding(14.dp)
            ) {
                Row(
                    modifier = Modifier.fillMaxWidth(),
                    verticalAlignment = Alignment.CenterVertically,
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    Text(
                        text = "Track Lines",
                        style = SampleTypography.bodyLarge
                    )
                    Switch(
                        checked = isTrackLineVisible,
                        onCheckedChange = {
                            onTrackLineVisibilityChanged(it)
                        }
                    )
                }
                HorizontalDivider(thickness = 0.5.dp)
                Row(
                    modifier = Modifier
                        .fillMaxWidth(),
                    verticalAlignment = Alignment.CenterVertically,
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    Text(
                        text = "Previous Observations",
                        style = SampleTypography.bodyLarge
                    )
                    Switch(
                        checked = isPrevObservationsVisible,
                        onCheckedChange = {
                            onPrevObservationsVisibilityChanged(it)
                        }
                    )
                }
            }
        }

        Surface(
            modifier = Modifier.padding(20.dp),
            tonalElevation = 1.dp,
            shape = RoundedCornerShape(20.dp),
            border = BorderStroke(1.dp, MaterialTheme.colorScheme.outlineVariant)
        ) {
            Column(
                modifier = Modifier.padding(14.dp)
            ) {
                Column {
                    Row {
                        Text(
                            modifier = Modifier.weight(12f),
                            text = "Observations per track",
                        )
                        Text(
                            modifier = Modifier.weight(1f),
                            text = observationsPerTrack.roundToInt().toString()
                        )
                    }
                    Slider(
                        value = observationsPerTrack,
                        onValueChange = {
                            onObservationsChanged(it)
                        },
                        valueRange = 1f..16f
                    )
                }
                HorizontalDivider(thickness = 0.5.dp)
                TextButton(
                    modifier = Modifier.align(CenterHorizontally),
                    onClick = onPurgeAllObservations
                )
                {
                    Text(text = "Purge All Observations")
                }
            }
        }
    }
}

@Preview(showBackground = true)
@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES, showBackground = true)
@Composable
fun DynamicEntityLayerPropertiesPreview() {
    SampleAppTheme {
        DynamicEntityLayerProperties(
            isTrackLineVisible = true,
            isPrevObservationsVisible = true,
            observationsPerTrack = 5f
        )
    }
}

/* Copyright 2023 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.adddynamicentitylayer.components

import android.app.Application
import androidx.compose.runtime.mutableFloatStateOf
import androidx.compose.runtime.mutableStateOf
import androidx.lifecycle.AndroidViewModel
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.mapping.layers.DynamicEntityLayer
import com.arcgismaps.realtime.ArcGISStreamService
import com.arcgismaps.realtime.ArcGISStreamServiceFilter
import com.esri.arcgismaps.sample.adddynamicentitylayer.R
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.launch

class MapViewModel(
    application: Application,
    private val sampleCoroutineScope: CoroutineScope,
) : AndroidViewModel(application) {

    // set the state of the switches and slider
    val trackLineCheckedState = mutableStateOf(false)
    val prevObservationCheckedState = mutableStateOf(false)
    val trackSliderValue = mutableFloatStateOf(5f)

    // flag to show or dismiss the bottom sheet
    val isBottomSheetVisible = mutableStateOf(false)

    // create ArcGIS Stream Service
    private val streamService =
        ArcGISStreamService(application.getString(R.string.stream_service_url))

    // create ArcGISStreamServiceFilter
    private val streamServiceFilter = ArcGISStreamServiceFilter()

    // layer displaying the dynamic entities on the map
    private val dynamicEntityLayer: DynamicEntityLayer

    // define ArcGIS map using Streets basemap
    val map = ArcGISMap(BasemapStyle.ArcGISStreets).apply {
        initialViewpoint = Viewpoint(40.559691, -111.869001, 150000.0)
    }

    /**
     * set the data source for the dynamic entity layer.
     */
    init {
        // set condition on the ArcGISStreamServiceFilter to limit the amount of data coming from the server
        streamServiceFilter.whereClause = "speed > 0"
        streamService.apply {
            filter = streamServiceFilter
            // sets the maximum time (in seconds) an observation remains in the application.
            purgeOptions.maximumDuration = 300.0
        }
        dynamicEntityLayer = DynamicEntityLayer(streamService)

        // add the dynamic entity layer to the map's operational layers
        map.operationalLayers.add(dynamicEntityLayer)
    }

    // disconnects the stream service
    fun disconnectStreamService() {
        sampleCoroutineScope.launch {
            streamService.disconnect()
        }
    }

    // connects the stream service
    fun connectStreamService() {
        sampleCoroutineScope.launch {
            streamService.connect()
        }
    }

    // to dismiss the bottom sheet
    fun dismissBottomSheet() {
        isBottomSheetVisible.value = false
    }

    // to manage bottomSheet visibility
    fun showBottomSheet() {
        isBottomSheetVisible.value = true
    }

    // to manage track lines visibility
    fun trackLineVisibility(checkedValue: Boolean) {
        trackLineCheckedState.value = checkedValue
        dynamicEntityLayer.trackDisplayProperties.showTrackLine = trackLineCheckedState.value
    }

    // to manage previous observations visibility
    fun prevObservationsVisibility(checkedValue: Boolean) {
        prevObservationCheckedState.value = checkedValue
        dynamicEntityLayer.trackDisplayProperties.showPreviousObservations =
            prevObservationCheckedState.value
    }

    // to set the maximum number of observations displayed per track
    fun setObservations(sliderValue: Float) {
        trackSliderValue.floatValue = sliderValue
        dynamicEntityLayer.trackDisplayProperties.maximumObservations =
            trackSliderValue.floatValue.toInt()
    }

    // remove all dynamic entity observations from the in-memory data cache as well as from the map
    fun purgeAllObservations() {
        sampleCoroutineScope.launch {
            streamService.purgeAll()
        }
    }
}

/* Copyright 2023 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.adddynamicentitylayer.screens

import android.app.Application
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.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.TextButton
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.runtime.setValue
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import androidx.compose.ui.unit.dp
import com.arcgismaps.toolkit.geoviewcompose.MapView
import com.esri.arcgismaps.sample.adddynamicentitylayer.components.DynamicEntityLayerProperties
import com.esri.arcgismaps.sample.adddynamicentitylayer.components.MapViewModel
import com.esri.arcgismaps.sample.sampleslib.components.BottomSheet
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar

/**
 * Main screen layout for the sample app
 */
@Composable
fun MainScreen(sampleName: String) {
    /// coroutineScope that will be cancelled when this call leaves the composition
    val sampleCoroutineScope = rememberCoroutineScope()
    // get the application context
    val application = LocalContext.current.applicationContext as Application

    // create a ViewModel to handle MapView interactions
    val mapViewModel = remember { MapViewModel(application, sampleCoroutineScope) }

    // display connect/disconnect based on the boolean state
    var isDisconnected by remember { mutableStateOf(false) }

    Scaffold(
        topBar = { SampleTopAppBar(title = sampleName) },
        content = {
            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(it)
            ) {
                // composable function that wraps the MapView
                MapView(
                    modifier = Modifier
                        .fillMaxSize()
                        .weight(1f),
                    arcGISMap = mapViewModel.map,
                    onSingleTapConfirmed = { mapViewModel.dismissBottomSheet() },
                    onPan = { mapViewModel.dismissBottomSheet() }
                )
                Row(
                    modifier = Modifier
                        .padding(12.dp)
                        .fillMaxWidth(),
                    verticalAlignment = Alignment.CenterVertically,
                    horizontalArrangement = Arrangement.SpaceBetween
                ) {
                    TextButton(onClick = {
                        if (!isDisconnected)
                            mapViewModel.disconnectStreamService()
                        else
                            mapViewModel.connectStreamService()
                        isDisconnected = !isDisconnected
                    }) {
                        Text(text = if (!isDisconnected) "Disconnect" else "Connect")
                    }
                    TextButton(onClick = {
                        mapViewModel.showBottomSheet()
                    }) {
                        Text(text = "Dynamic Entity Settings")
                    }
                }

            }
            // display a bottom sheet to set dynamic entity layer properties
            BottomSheet(isVisible = mapViewModel.isBottomSheetVisible.value) {
                DynamicEntityLayerProperties(
                    onTrackLineVisibilityChanged = mapViewModel::trackLineVisibility,
                    onPrevObservationsVisibilityChanged = mapViewModel::prevObservationsVisibility,
                    onObservationsChanged = mapViewModel::setObservations,
                    onPurgeAllObservations = mapViewModel::purgeAllObservations,
                    isTrackLineVisible = mapViewModel.trackLineCheckedState.value,
                    isPrevObservationsVisible = mapViewModel.prevObservationCheckedState.value,
                    observationsPerTrack = mapViewModel.trackSliderValue.floatValue,
                    onDismiss = { mapViewModel.dismissBottomSheet() }
                )
            }
        }
    )
}