Show exploratory viewshed from point in scene | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Perform an exploratory viewshed analysis from a defined vantage point.

Image of exploratory viewshed location

Use case

An exploratory viewshed analysis is a type of visual analysis you can perform at the current rendered resolution of a scene. The exploratory viewshed shows what can be seen from a given location. The output is an overlay with two different colors - one representing the visible areas (green) and the other representing the obstructed areas (red).

Note: This analysis is a form of “exploratory analysis”, which means the results are calculated on the current scale of the data, and the results are generated very quickly but not persisted. If persisted analysis performed at the full resolution of the data is required, consider using a ViewshedFunction to perform a viewshed calculation instead.

How to use the sample

Use the sliders to change the properties (heading, pitch, etc.), of the exploratory viewshed and see them updated in real time.

How it works

Create an ExploratoryLocationViewshed passing in the observer location, heading, pitch, horizontal/vertical angles, and min/max distances.
Set the property values on the exploratory viewshed instance for location, direction, range, and visibility properties.

Relevant API

AnalysisOverlay
ArcGISSceneLayer
ArcGISTiledElevationSource
ExploratoryLocationViewshed
ExploratoryViewshed

About the data

The scene shows a buildings layer in Brest, France hosted on ArcGIS Online.

Additional information

This sample uses the GeoView-Compose Toolkit module to be able to implement a composable SceneView.

Sample Code

MainActivity.kt

SceneViewModel.kt

MainScreen.kt

ViewshedOptionsScreen.kt

ViewshedSlider.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.showexploratoryviewshedfrompointinscene

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.showexploratoryviewshedfrompointinscene.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 {
                ViewshedLocationApp()
            }
        }
    }

    @Composable
    private fun ViewshedLocationApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            MainScreen(sampleName = getString(R.string.show_exploratory_viewshed_from_point_in_scene_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.showexploratoryviewshedfrompointinscene.components

import android.app.Application
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.setValue
import androidx.lifecycle.AndroidViewModel
import com.arcgismaps.analysis.interactive.ExploratoryLocationViewshed
import com.arcgismaps.geometry.Point
import com.arcgismaps.mapping.ArcGISScene
import com.arcgismaps.mapping.ArcGISTiledElevationSource
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.Surface
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.mapping.layers.ArcGISSceneLayer
import com.arcgismaps.mapping.view.AnalysisOverlay
import com.arcgismaps.mapping.view.Camera
import com.esri.arcgismaps.sample.showexploratoryviewshedfrompointinscene.R

class SceneViewModel(private val application: Application) : AndroidViewModel(application) {

    // initialize location viewshed parameters
    private var viewShed: ExploratoryLocationViewshed
    private val initHeading = 82.0
    private val initPitch = 60.0
    private val initHorizontalAngle = 75.0
    private val initVerticalAngle = 90.0
    private val initMinDistance = 0.0
    private val initMaxDistance = 1500.0

    val initLocation = Point(
        x = -4.50,
        y = 48.4,
        z = 1000.0
    )
    private val camera = Camera(
        lookAtPoint = initLocation,
        distance = 20000000.0,
        heading = 0.0,
        pitch = 55.0,
        roll = 0.0
    )
    var scene by mutableStateOf(ArcGISScene(BasemapStyle.ArcGISNavigationNight))
    var analysisOverlay by mutableStateOf(AnalysisOverlay())


    init {
        // create a surface for elevation data
        val surface = Surface().apply {
            elevationSources.add(ArcGISTiledElevationSource(application.getString(R.string.elevation_service)))
        }

        // create a layer of buildings
        val buildingsSceneLayer = ArcGISSceneLayer(application.getString(R.string.buildings_layer))

        // create a scene and add imagery basemap, elevation surface, and buildings layer to it
        val buildingsScene = ArcGISScene(BasemapStyle.ArcGISImagery).apply {
            baseSurface = surface
            operationalLayers.add(buildingsSceneLayer)
        }

        val initLocation = Point(-4.50, 48.4, 1000.0)
        // create viewshed from the initial location
        viewShed = ExploratoryLocationViewshed(
            location = initLocation,
            heading = initHeading,
            pitch = initPitch,
            horizontalAngle = initHorizontalAngle,
            verticalAngle = initVerticalAngle,
            minDistance = initMinDistance,
            maxDistance = initMaxDistance
        ).apply {
            frustumOutlineVisible = true
        }

        // add the buildings scene to the sceneView
        scene = buildingsScene.apply {
            baseSurface = surface
            initialViewpoint = Viewpoint(initLocation, camera)
        }
        // add the viewshed to the analysisOverlay of the  scene view
        analysisOverlay.apply {
            analyses.add(viewShed)
            isVisible = true
        }
    }

    fun setHeading(sliderHeading: Float) {
        viewShed.heading = sliderHeading.toDouble()
    }

    fun setMaximumDistanceSlider(sliderValue: Float) {
        viewShed.maxDistance = sliderValue.toDouble()

    }

    fun setMinimumDistanceSlider(sliderValue: Float) {
        viewShed.minDistance = sliderValue.toDouble()
    }

    fun setVerticalAngleSlider(sliderValue: Float) {
        viewShed.verticalAngle = sliderValue.toDouble()
    }

    fun setHorizontalAngleSlider(sliderValue: Float) {
        viewShed.horizontalAngle = sliderValue.toDouble()
    }

    fun setPitch(sliderValue: Float) {
        viewShed.pitch = sliderValue.toDouble()
    }

    fun frustumVisibility(checkedValue: Boolean) {
        viewShed.frustumOutlineVisible = checkedValue
    }

    fun analysisVisibility(checkedValue: Boolean) {
        viewShed.isVisible = checkedValue
    }
}

/* 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.showexploratoryviewshedfrompointinscene.screens

import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Settings
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.Icon
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.mapping.view.OrbitLocationCameraController
import com.arcgismaps.toolkit.geoviewcompose.SceneView
import com.esri.arcgismaps.sample.sampleslib.components.BottomSheet
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
import com.esri.arcgismaps.sample.showexploratoryviewshedfrompointinscene.components.SceneViewModel

/**
 * Main screen layout for the sample app
 */
@Composable
fun MainScreen(sampleName: String) {
    var isBottomSheetVisible by remember { mutableStateOf(true) }
    // create a ViewModel to handle SceneView interactions
    val sceneViewModel: SceneViewModel = viewModel()

    Scaffold(
        topBar = { SampleTopAppBar(title = sampleName) },
        floatingActionButton = {
            if (!isBottomSheetVisible) {
                FloatingActionButton(
                    modifier = Modifier.padding(bottom = 36.dp, end = 24.dp),
                    onClick = { isBottomSheetVisible = true }
                ) { Icon(Icons.Filled.Settings, contentDescription = "Viewshed options") }
            }
        },
        content = {
            Box {
                Column(
                    modifier = Modifier
                        .fillMaxSize()
                        .padding(it)
                ) {

                    val cameraController = remember {
                        OrbitLocationCameraController(
                            targetPoint = sceneViewModel.initLocation,
                            distance = 5000.0
                        )
                    }
                    // composable function that wraps the SceneView
                    SceneView(
                        modifier = Modifier
                            .fillMaxSize()
                            .weight(1f),
                        arcGISScene = sceneViewModel.scene,
                        onDown = { isBottomSheetVisible = false },
                        cameraController = cameraController,
                        analysisOverlays = listOf(sceneViewModel.analysisOverlay)
                    )
                }
            }
            BottomSheet(
                sheetTitle = "Viewshed Options",
                isVisible = isBottomSheetVisible,
                onDismissRequest = { isBottomSheetVisible = false }
            ) {
                // display list of options to modify viewshed properties
                ViewshedOptionsScreen(
                    onHeadingChanged = sceneViewModel::setHeading,
                    onPitchChanged = sceneViewModel::setPitch,
                    onHorizontalAngleChanged = sceneViewModel::setHorizontalAngleSlider,
                    onVerticalAngleChanged = sceneViewModel::setVerticalAngleSlider,
                    onMinDistanceChanged = sceneViewModel::setMinimumDistanceSlider,
                    onMaxDistanceChanged = sceneViewModel::setMaximumDistanceSlider,
                    isFrustumVisible = sceneViewModel::frustumVisibility,
                    isAnalysisVisible = sceneViewModel::analysisVisibility
                )
            }
        }
    )
}

/* 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.showexploratoryviewshedfrompointinscene.screens

import android.content.res.Configuration
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Checkbox
import androidx.compose.material3.Surface
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
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

/**
 * Viewshed options screen for sliders and checkboxes
 */
@Composable
fun ViewshedOptionsScreen(
    onHeadingChanged: (Float) -> Unit = {},
    onPitchChanged: (Float) -> Unit = {},
    onHorizontalAngleChanged: (Float) -> Unit = {},
    onVerticalAngleChanged: (Float) -> Unit = {},
    onMinDistanceChanged: (Float) -> Unit = {},
    onMaxDistanceChanged: (Float) -> Unit = {},
    isFrustumVisible: (Boolean) -> Unit = {},
    isAnalysisVisible: (Boolean) -> Unit = {}
) {
    Column {
        // sliders
        HeadingSlider(onHeadingChanged)
        PitchSlider(onPitchChanged)
        HorizontalAngleSlider(onHorizontalAngleChanged)
        VerticalAngleSlider(onVerticalAngleChanged)
        MinimumDistanceSlider(onMinDistanceChanged)
        MaximumDistanceSlider(onMaxDistanceChanged)
        // checkbox
        Row {
            FrustumCheckBox(isFrustumVisible)
            AnalysisCheckBox(isAnalysisVisible)
        }
    }
}

@Composable
private fun HeadingSlider(onHeadingChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Heading",
        initialSliderValue = 82f,
        sliderRangeValue = 0f..360f,
        functionChanged = onHeadingChanged
    )
}

@Composable
private fun PitchSlider(onPitchChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Pitch",
        initialSliderValue = 60f,
        sliderRangeValue = 0f..180f,
        functionChanged = onPitchChanged
    )
}

@Composable
private fun HorizontalAngleSlider(onHorizontalAngleChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Horizontal Angle",
        initialSliderValue = 75f,
        sliderRangeValue = 1f..120f,
        functionChanged = onHorizontalAngleChanged
    )
}

@Composable
private fun VerticalAngleSlider(onVerticalAngleChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Vertical Angle",
        initialSliderValue = 90f,
        sliderRangeValue = 1f..120f,
        functionChanged = onVerticalAngleChanged
    )
}

@Composable
private fun MinimumDistanceSlider(onMinDistanceChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Minimum Distance",
        initialSliderValue = 0f,
        sliderRangeValue = 0f..8999f,
        functionChanged = onMinDistanceChanged
    )
}

@Composable
private fun MaximumDistanceSlider(onMaxDistanceChanged: (Float) -> Unit) {
    ViewshedSlider(
        title = "Maximum Distance",
        initialSliderValue = 1500f,
        sliderRangeValue = 0f..9999f,
        functionChanged = onMaxDistanceChanged
    )
}

@Composable
fun FrustumCheckBox(isFrustumVisible: (Boolean) -> Unit) {
    // set the state of the checkbox
    val checkedState = remember { mutableStateOf(true) }
    // display a row and create a checkbox and text in a row
    Row {
        Checkbox(
            checked = checkedState.value,
            onCheckedChange = {
                checkedState.value = it
                isFrustumVisible(checkedState.value)
            },
        )
        Text(modifier = Modifier.padding(top = 10.dp), text = "Frustum Outline")
    }
}

@Composable
fun AnalysisCheckBox(isAnalysisVisible: (Boolean) -> Unit) {
    // set the state of the checkbox
    val checkedState = remember { mutableStateOf(true) }
    // display a row and create a checkbox and text in a row
    Row {
        Checkbox(
            checked = checkedState.value,
            onCheckedChange = {
                checkedState.value = it
                isAnalysisVisible(checkedState.value)
            },
        )
        Text(modifier = Modifier.padding(top = 10.dp), text = "Analysis Overlay")
    }
}

@Preview(showBackground = true)
@Preview(uiMode = Configuration.UI_MODE_NIGHT_YES, showBackground = true)
@Composable
fun PreviewViewshedOptions() {
    SampleAppTheme {
        Surface {
            ViewshedOptionsScreen()
        }
    }
}

package com.esri.arcgismaps.sample.showexploratoryviewshedfrompointinscene.screens

import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.size
import androidx.compose.foundation.layout.width
import androidx.compose.material3.Slider
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableFloatStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

/**
 * Custom slider implementation to be used by various viewshed slider options
 */
@Composable
fun ViewshedSlider(
    title: String,
    initialSliderValue: Float,
    sliderRangeValue: ClosedFloatingPointRange<Float>,
    functionChanged: (Float) -> Unit
) {
    var sliderValue by remember {
        mutableFloatStateOf(initialSliderValue)
    }
    Row {
        Text(
            modifier = Modifier.padding(start = 10.dp, top = 10.dp, end = 10.dp).width(150.dp),
            text = title
        )
        Slider(
            modifier = Modifier.weight(1f),
            value = sliderValue,
            onValueChange = {
                sliderValue = it
                // update view model viewshed value
                functionChanged(sliderValue)
            },
            valueRange = sliderRangeValue
        )
        Text(
            modifier = Modifier.padding(start = 10.dp, top = 10.dp, end = 10.dp).size(40.dp),
            text = sliderValue.toInt().toString()
        )
    }
}