Explore details of a building scene by using filters and sublayer visibility.
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
Once the scene is loaded, tap the "Settings" gear button to view the filtering options.
- Select a floor from the "Floors" menu to view the internal details of each floor or "All" to view the entire model. Selecting a floor applies a filter that hides all floors above the selected floor and gives the floors below a transparent, X-ray renderer.
- Expand the categories under the top-level disciplines to show or hide individual categories in the building model. The entire discipline may be shown or hidden as well.
- Tap on any features in the building to view the attributes of the feature.
How it works
- Create a
Scenewith the URL to a Building Scene Layer service. - Create a
LocalSceneViewwith the scene. - Retrieve the
BuildingSceneLayerfrom the scene's operational layers. - When a floor is selected:
- A new
BuildingFilteris created with twoBuildingFilterBlockobjects. - One block defines the solid renderer for features on the selected floor.
- The second block defines the X-ray filter for features on the floors below the selected floor.
- Features that exist on floors above the selected floor are not rendered.
- If “All” is selected, the
activeFilterproperty on the building scene layer is set tonilso all features are rendered according to their default settings.
- A new
- Architectural disciplines and categories are represented by
BuildingGroupSublayerandBuildingSublayerobjects containing features within a building scene layer. When checked or unchecked, the visibility of the group or sublayer is set to true (visible) or false (hidden). - When a building feature is tapped on:
- A call to
identify(on:screenPoint:tolerance:returnPopupsOnly:maximumResults:)on theLocalSceneViewProxyis initiated based on a change of the tap location. - The
sublayerResultsproperty of the returnedIdentifyLayerResultwill contain the identified features. Note that the building scene layer features are NOT returned in thegeoElementsproperty of the results. - The details of the first identified feature are shown in a popup.
- A call to
Relevant API
- BuildingComponentSublayer
- BuildingFilter
- BuildingFilterBlock
- BuildingGroupSublayer
- BuildingSceneLayer
- LocalSceneView
- Scene
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.
Tags
3D, building scene layer, layers
Sample Code
// 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
//
// https://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.
import ArcGIS
import ArcGISToolkit
import SwiftUI
struct FilterBuildingSceneLayerView: View {
/// A scene with the building scene layer which displays ESRI building E.
@State private var scene = Scene(url: URL(string: "https://www.arcgis.com/home/item.html?id=b7c387d599a84a50aafaece5ca139d44")!)!
/// The building scene layer used in the scene.
///
/// This is used to set the active filter on the layer.
@State private var buildingSceneLayer: BuildingSceneLayer?
/// A Boolean value indicating if the settings are visible or not.
@State private var settingsAreVisible = false
/// The available floors to show in the settings.
@State private var availableFloors: [String] = []
/// The selected floor from the floor picker in the settings.
@State private var selectedFloor: String = .allFloorsLabel
/// The group sublayers used to build the visibility toggles in the settings.
@State private var groupSublayers: [BuildingGroupSublayer] = []
/// The error shown in the error alert.
@State private var error: (any Error)?
/// The point where the user has tapped on the screen.
@State private var tapPoint: CGPoint?
/// The building sublayer that has a feature selected.
///
/// This is used to clear the feature selection.
@State private var selectedSublayer: BuildingComponentSublayer?
/// The popup to be shown as the result of the layer identify operation.
@State private var popup: Popup?
/// A Boolean value specifying whether the popup view should be shown or not.
@State private var showPopup = false
var body: some View {
LocalSceneViewReader { proxy in
LocalSceneView(scene: scene)
.onSingleTapGesture { screenPoint, _ in
tapPoint = screenPoint
}
.task {
do {
try await setup()
} catch {
self.error = error
}
}
.task(id: tapPoint) {
// Clears any previous selection if there was a new
// tap on the screen.
selectedSublayer?.clearSelection()
guard let tapPoint, let buildingSceneLayer else { return }
let result = try? await proxy
.identify(on: buildingSceneLayer, screenPoint: tapPoint, tolerance: 5)
let sublayerResult = result?.sublayerResults
// Get the first sublayer result that has geo elements.
.first(where: { !$0.geoElements.isEmpty })
guard let sublayerResult,
let feature = sublayerResult.geoElements.first as? Feature,
let component = sublayerResult.layerContent as? BuildingComponentSublayer
else { return }
component.selectFeature(feature)
popup = sublayerResult.popups.first
showPopup = popup != nil
selectedSublayer = component
}
}
.errorAlert(presentingError: $error)
.toolbar {
ToolbarItem(placement: .bottomBar) {
Button("Settings", systemImage: "gear") {
settingsAreVisible = true
}
.popover(isPresented: $settingsAreVisible) { [settings] in
settings
.frame(idealWidth: 400, idealHeight: 500)
.presentationCompactAdaptation(.popover)
}
}
}
.popover(isPresented: $showPopup, attachmentAnchor: .point(.top)) { [popup] in
PopupView(root: popup!, isPresented: $showPopup)
.frame(idealWidth: 320, idealHeight: 600)
}
}
/// Sets up the view by loading the scene and the building scene layer to get the
/// information needed for the settings.
private func setup() async throws {
try await scene.load()
guard let buildingSceneLayer = scene.operationalLayers.first as? BuildingSceneLayer else { return }
try await buildingSceneLayer.load()
self.buildingSceneLayer = buildingSceneLayer
// Gets the full model which contains all the sublayers.
guard let fullModelSublayer = buildingSceneLayer.sublayers
.first(where: { $0.name == "Full Model" }) as? BuildingGroupSublayer else { return }
groupSublayers = fullModelSublayer.sublayers
.compactMap { $0 as? BuildingGroupSublayer }
// Gets the attribute statistics to get the floor
// information.
let statistics = try await buildingSceneLayer.statistics
// Gets the floor statistics.
guard let floorStatistics = statistics[.floorFieldKey] else { return }
// Gets all the available floors and sorts the floors
// from top to bottom floor.
availableFloors = floorStatistics.mostFrequentValues.sorted { $0 > $1 } + [.allFloorsLabel]
}
/// The floor filter used with the building scene layer to show only the
/// selected floor from the floor picker in the settings.
private var floorFilter: BuildingFilter? {
// To see all the floors we need to remove the filter
// by setting it to 'nil'.
guard selectedFloor != .allFloorsLabel else { return nil }
return BuildingFilter(
name: "Floor filter",
description: "Show selected floor using filter blocks.",
blocks: [
BuildingFilterBlock(
title: "Solid",
whereClause: "\(String.floorFieldKey) = \(selectedFloor)",
mode: .solid()
),
BuildingFilterBlock(
title: "Xray",
whereClause: "\(String.floorFieldKey) < \(selectedFloor)",
mode: .xray()
)
]
)
}
/// The settings used to filter the sublayer by floors and sublayers.
private var settings: some View {
NavigationStack {
Form {
Section("Floors") {
Picker("Floor", selection: $selectedFloor) {
ForEach(availableFloors, id: \.self) { floor in
Text(floor)
}
}
.onChange(of: selectedFloor) {
// If the selected floor changed then we need
// to update the active filter to show
// the selected floor.
buildingSceneLayer?.activeFilter = floorFilter
}
}
Section("Disciplines & Categories") {
ForEach(groupSublayers) { sublayer in
BuildingGroupSublayerToggleView(groupSublayer: sublayer)
}
}
}
.navigationTitle("Settings")
.navigationBarTitleDisplayMode(.inline)
.toolbar {
ToolbarItem(placement: .confirmationAction) {
Button("Done") {
settingsAreVisible = false
}
}
}
}
}
}
private extension String {
/// The attribute name for the floors.
static var floorFieldKey: String { "BldgLevel" }
/// The label used in the floor picker to see all the floors.
static var allFloorsLabel: String { "All" }
}
#Preview {
FilterBuildingSceneLayerView()
}