Filter building scene layer | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample viewer app

Explore details of a building scene by using filters and sublayer visibility.

Image of a building scene layer

Use case

Buildings and their component parts (in this example, structural, electrical, or architectural) can be difficult to explain and visualize. An architectural firm might share a 3D building model visualization with clients and contractors to let them explore these components by floor and component type.

How to use the sample

In the filter controls, select floor and category options to filter what parts of the Building Scene Layer are displayed in the scene. Click on any of the building features to identify them.

How it works

Create an ArcGISScene with the URL to a Building Scene Layer service.
Create a LocalSceneView and add the scene.
Retrieve the BuildingSceneLayer from the scene’s operational layers.
Click the floating action button to view the filtering options.
Select a floor from the “Floor” dropdown to view the internal details of each floor or “All” to view the entire model.
Expand the categories to show or hide individual items in the building model. The entire category may be shown or hidden as well.
Click on any of the building features to view the attributes of the feature.

Relevant API

ArcGISScene
BuildingComponentSublayer
BuildingFilter
BuildingFilterBlock
BuildingSceneLayer
LocalSceneView
Popup

About the data

This sample uses the Esri Building E Local Scene web scene, which contains a Building Scene Layer representing Building E on the Esri Campus in Redlands, CA. The Revit BIM model was brought into ArcGIS using the BIM capabilities in ArcGIS Pro and published to the web as a Building Scene Layer.

Additional information

Buildings in a Building Scene Layer can be very complex models composed of sublayers containing internal and external features of the structure. Sublayers may include structural components like columns, architectural components like floors and windows, and electrical components.

Applying filters to the Building Scene Layer can highlight features of interest in the model. Filters are made up of filter blocks, which contain several properties that allow control over the filter’s function. Setting the filter mode to X-Ray, for instance, will render features with a semi-transparent white color so other interior features can be seen. In addition, toggling the visibility of sublayers can show or hide all the features of a sublayer.

This sample uses the Popup toolkit component. For information about setting up the toolkit, as well as code for the underlying component, visit the toolkit docs.

Sample Code

MainActivity.kt

FilterBuildingSceneLayerScreen.kt

FilterBuildingSceneLayerViewModel.kt

/* Copyright 2025 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.filterbuildingscenelayer

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
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.filterbuildingscenelayer.screens.FilterBuildingSceneLayerScreen
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)
        ArcGISEnvironment.applicationContext = this

        setContent {
            SampleAppTheme {
                FilterBuildingSceneLayerApp()
            }
        }
    }

    @Composable
    private fun FilterBuildingSceneLayerApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            FilterBuildingSceneLayerScreen(
                sampleName = getString(R.string.filter_building_scene_layer_app_name)
            )
        }
    }
}

/* Copyright 2025 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.filterbuildingscenelayer.screens

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxHeight
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.wrapContentSize
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ArrowDropDown
import androidx.compose.material.icons.filled.ArrowDropUp
import androidx.compose.material.icons.filled.Settings
import androidx.compose.material3.Checkbox
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.FloatingActionButton
import androidx.compose.material3.HorizontalDivider
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.ModalBottomSheet
import androidx.compose.material3.Scaffold
import androidx.compose.material3.Text
import androidx.compose.material3.rememberModalBottomSheetState
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.unit.dp
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.data.Feature
import com.arcgismaps.mapping.layers.buildingscene.BuildingComponentSublayer
import com.arcgismaps.mapping.layers.buildingscene.BuildingGroupSublayer
import com.arcgismaps.toolkit.geoviewcompose.LocalSceneView
import com.arcgismaps.toolkit.geoviewcompose.LocalSceneViewProxy
import com.arcgismaps.toolkit.popup.Popup
import com.esri.arcgismaps.sample.filterbuildingscenelayer.components.FilterBuildingSceneLayerViewModel
import com.esri.arcgismaps.sample.sampleslib.components.BottomSheet
import com.esri.arcgismaps.sample.sampleslib.components.DropDownMenuBox
import com.esri.arcgismaps.sample.sampleslib.components.LoadingDialog
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialog
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
import kotlinx.coroutines.delay
import kotlinx.coroutines.launch

/**
 * Main screen layout for the sample app
 */
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun FilterBuildingSceneLayerScreen(sampleName: String) {
    val viewModel: FilterBuildingSceneLayerViewModel = viewModel()

var isBottomSheetVisible by remember { mutableStateOf(false) }

    val sheetState = rememberModalBottomSheetState()

    var showIdentifyProgress by remember { mutableStateOf(false)}

    val localSceneViewProxy = remember { LocalSceneViewProxy() }

    val coroutineScope = rememberCoroutineScope()

    val showLoadingDialog by viewModel.showLoadingDialog.collectAsStateWithLifecycle()

    val popupState by viewModel.popupState.collectAsStateWithLifecycle()

    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 options") }
            }
        },
        content = {
            // display a progress dialog to indicate the map loading status
            if (showLoadingDialog) {
                LoadingDialog(loadingMessage = "Loading layer...")
            }

            // display a progress dialog when an identify is take longer than expected
            if (showIdentifyProgress) {
                LoadingDialog("Identifying...")
            }

            Column(
                modifier = Modifier
                    .fillMaxSize()
                    .padding(it),
            ) {
                LocalSceneView(
                    modifier = Modifier
                        .fillMaxSize()
                        .weight(1f),
                    scene = viewModel.scene,
                    localSceneViewProxy = localSceneViewProxy,
                    onSingleTapConfirmed = { singleTapConfirmedEvent ->
                        coroutineScope.launch {
                            viewModel.sublayerWithSelection?.clearSelection()

                            // only show identify progress if it has been more than one second
                            val identifyInProgress = coroutineScope.launch {
                                delay(1000)
                                showIdentifyProgress = true
                            }

                            localSceneViewProxy.identify(
                                layer = viewModel.buildingSceneLayer!!,
                                screenCoordinate = singleTapConfirmedEvent.screenCoordinate,
                                tolerance = 12.dp,
                                returnPopupsOnly = false,
                                maximumResults = 1
                            ).onSuccess { identifyLayerResult ->
                                identifyInProgress.cancel()
                                showIdentifyProgress = false

                                val results = identifyLayerResult.sublayerResults

                                if (results.isNotEmpty()) {
                                    val element = results.first().geoElements.first()
                                    val popup = com.arcgismaps.mapping.popup.Popup(element)
                                    viewModel.createPopupState(popup)

                                    val sublayer =
                                        results.first().layerContent as BuildingComponentSublayer
                                    sublayer.selectFeature(element as Feature)
                                    viewModel.sublayerWithSelection = sublayer
                                }
                            }.onFailure { throwable ->
                                identifyInProgress.cancel()
                                showIdentifyProgress = false

                                viewModel.messageDialogVM.showMessageDialog(throwable)
                            }
                        }
                    }
                )
            }

            BottomSheet(
                isVisible = isBottomSheetVisible,
                sheetTitle = "Settings",
                onDismissRequest = { isBottomSheetVisible = false },
            ) {
                Column(modifier = Modifier
                    .fillMaxHeight(0.4f),
                    horizontalAlignment = Alignment.CenterHorizontally
                ) {
                    FloorSelector()
                    HorizontalDivider()
                    CategorySelector()
                }
            }

            popupState?.let { popupState ->
                ModalBottomSheet(modifier = Modifier.wrapContentSize(),
                    onDismissRequest = viewModel::dismissPopup,
                    sheetState = sheetState) {
                    Popup(
                        popupState = popupState,
                        onDismiss = viewModel::dismissPopup,
                        modifier = Modifier.fillMaxSize()
                    )
                }
            }

            viewModel.messageDialogVM.apply {
                if (dialogStatus) {
                    MessageDialog(
                        title = messageTitle,
                        description = messageDescription,
                        onDismissRequest = ::dismissDialog
                    )
                }
            }
        }
    )
}

/**
 * A menu to select floors
 */
@Composable
fun FloorSelector() {
    val viewModel: FilterBuildingSceneLayerViewModel = viewModel()

    DropDownMenuBox(
        textFieldValue = viewModel.selectedFloor,
        textFieldLabel = "Floor",
        dropDownItemList = viewModel.floors,
        onIndexSelected = viewModel::selectFloor
    )
}

/**
 * Check boxes to select building categories and sub-categories
 */
@Composable
fun CategorySelector() {
    val viewModel: FilterBuildingSceneLayerViewModel = viewModel()

    Column(
        horizontalAlignment = Alignment.CenterHorizontally
    ) {
        Text(text = "Categories:", modifier = Modifier.padding(8.dp))

        Column {
            viewModel.categories.forEach { buildingSublayer ->
                var categoryChecked by remember { mutableStateOf(buildingSublayer.isVisible) }
                var showSubCategories by remember { mutableStateOf(false) }

                Row(verticalAlignment = Alignment.CenterVertically) {
                    Text(text = buildingSublayer.name, modifier = Modifier.padding(8.dp))
                    Spacer(modifier = Modifier.weight(1f))
                    Checkbox(checked = categoryChecked, onCheckedChange = {
                        categoryChecked = it
                        buildingSublayer.isVisible = categoryChecked
                    })
                    IconButton(
                        onClick = { showSubCategories = !showSubCategories }
                    ) {
                        Icon(
                            imageVector = when {
                                showSubCategories -> Icons.Default.ArrowDropUp
                                else -> Icons.Default.ArrowDropDown
                            },
                            contentDescription = "Show sub-categories",
                            modifier = Modifier
                        )
                    }
                }
                if (showSubCategories) {
                    remember {
                        val buildingGroupSublayer = buildingSublayer as BuildingGroupSublayer
                        buildingGroupSublayer.sublayers.sortedBy { it.name }
                    }.forEach {
                        var subCategoryChecked by remember { mutableStateOf(it.isVisible) }
                        Row(verticalAlignment = Alignment.CenterVertically) {
                            Text(text = it.name, modifier = Modifier.padding(8.dp))
                            Spacer(modifier = Modifier.weight(1f))
                            Checkbox(checked = subCategoryChecked, onCheckedChange = { isChecked ->
                                subCategoryChecked = isChecked
                                it.isVisible = isChecked
                            })
                        }
                    }
                }
                HorizontalDivider()
            }
        }
    }
}

/* Copyright 2025 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.filterbuildingscenelayer.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 androidx.lifecycle.viewModelScope
import com.arcgismaps.mapping.ArcGISScene
import com.arcgismaps.mapping.layers.BuildingSceneLayer
import com.arcgismaps.mapping.layers.buildingscene.BuildingComponentSublayer
import com.arcgismaps.mapping.layers.buildingscene.BuildingFilter
import com.arcgismaps.mapping.layers.buildingscene.BuildingFilterBlock
import com.arcgismaps.mapping.layers.buildingscene.BuildingGroupSublayer
import com.arcgismaps.mapping.layers.buildingscene.BuildingSolidFilterMode
import com.arcgismaps.mapping.layers.buildingscene.BuildingSublayer
import com.arcgismaps.mapping.layers.buildingscene.BuildingXrayFilterMode
import com.arcgismaps.mapping.popup.Popup
import com.arcgismaps.toolkit.popup.PopupState
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialogViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.asStateFlow
import kotlinx.coroutines.launch

class FilterBuildingSceneLayerViewModel(app: Application) : AndroidViewModel(app) {
    val scene = ArcGISScene("https://www.arcgis.com/home/item.html?id=b7c387d599a84a50aafaece5ca139d44")

    // State to control if a loading progress indicator is shown
    private val _showLoadingDialog = MutableStateFlow(true)
    val showLoadingDialog = _showLoadingDialog.asStateFlow()

    // Building scene layer that will be filtered. Set after the WebScene is loaded.
    var buildingSceneLayer: BuildingSceneLayer? = null

    // The selected floor
    var selectedFloor by mutableStateOf("All")

    // The list of available floors
    val floors: MutableList<String> = mutableListOf(selectedFloor)

    // The list of building sublayer categories
    val categories: MutableList<BuildingSublayer> = mutableListOf()

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

    // Building scene layer sublayer that contains the currently selected feature
    var sublayerWithSelection : BuildingComponentSublayer? = null

    // State that will contain a popup state for an identify result
    private val _popupState = MutableStateFlow<PopupState?>(null)
    val popupState = _popupState.asStateFlow()

    init {
        viewModelScope.launch {
            scene.load().onFailure {
                messageDialogVM.showMessageDialog(it)
                _showLoadingDialog.value = false
            }.onSuccess {
                _showLoadingDialog.value = false

                buildingSceneLayer =
                    scene.operationalLayers.first { layer ->
                        layer is BuildingSceneLayer
                    } as BuildingSceneLayer

                buildingSceneLayer?.let { buildingSceneLayer ->
                    // Get the floor listing from the statistics
                    buildingSceneLayer.fetchStatistics().onSuccess { statistics ->
                        statistics["BldgLevel"]?.mostFrequentValues?.let {
                            floors.addAll(0, it.sorted())
                        }

                        // The top-level sublayer groups will be the categories
                        buildingSceneLayer.sublayers.find { sublayer ->
                            sublayer.modelName == "FullModel"
                        }?.let { buildingSublayer ->
                            buildingSublayer as BuildingGroupSublayer
                            categories.addAll(buildingSublayer.sublayers.sortedBy { it.name })
                        }
                    }
                }
            }
        }
    }

    /**
     * Updates the building filters based on the selected floor
     */
    fun selectFloor(index: Int) {
        selectedFloor = floors[index]

        buildingSceneLayer?.let { buildingSceneLayer ->
            if (selectedFloor == "All") {
                // No filtering applied if 'All' floors are selected
                buildingSceneLayer.activeFilter = null
                return
            }
            // Build a building filter to show the selected floor and an xray view of the floors below.
            // Floors above the selected floor are not shown at all.
            val buildingFilter = BuildingFilter(
                name = "Floor filter",
                description = "Show selected floor and xray filter for lower floors.",
                listOf(
                    BuildingFilterBlock(
                        title = "solid block",
                        whereClause = "BldgLevel = $selectedFloor",
                        mode = BuildingSolidFilterMode()
                    ),
                    BuildingFilterBlock(
                        title = "x ray block",
                        whereClause = "BldgLevel < $selectedFloor",
                        mode = BuildingXrayFilterMode()
                    )
                )
            )
            buildingSceneLayer.activeFilter = buildingFilter
        }
    }

    /**
     * Creates a popup state to display identify result
     */
    fun createPopupState(popup: Popup) {
        _popupState.value = PopupState(popup = popup, scope = viewModelScope)
    }

    /**
     * Dismisses an identify result
     */
    fun dismissPopup() {
        _popupState.value = null
    }
}