Merge pull request #560 from Esri/Caleb/New-CreateKMLMultiTrackView

[New] Create KML multi-track

Author: CalebRas

Samples.xcodeproj/project.pbxproj

@@ -250,6 +250,8 @@
 		D713C6D72CB990600073AA72 /* AddKMLLayerView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D713C6D12CB990600073AA72 /* AddKMLLayerView.swift */; };
 		D713C6D82CB990800073AA72 /* AddKMLLayerView.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D713C6D12CB990600073AA72 /* AddKMLLayerView.swift */; };
 		D713C6F72CB9B9A60073AA72 /* US_State_Capitals.kml in Resources */ = {isa = PBXBuildFile; fileRef = D713C6F52CB9B9A60073AA72 /* US_State_Capitals.kml */; settings = {ASSET_TAGS = (AddKmlLayer, ); }; };
+		D71563E92D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D71563E32D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift */; };
+		D71563EA2D5AC2D500D2E948 /* CreateKMLMultiTrackView.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D71563E32D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift */; };
 		D718A1E72B570F7500447087 /* OrbitCameraAroundObjectView.Model.swift in Sources */ = {isa = PBXBuildFile; fileRef = D718A1E62B570F7500447087 /* OrbitCameraAroundObjectView.Model.swift */; };
 		D718A1E82B571C9100447087 /* OrbitCameraAroundObjectView.Model.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D718A1E62B570F7500447087 /* OrbitCameraAroundObjectView.Model.swift */; };
 		D718A1ED2B575FD900447087 /* ManageBookmarksView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D718A1EA2B575FD900447087 /* ManageBookmarksView.swift */; };
@@ -416,6 +418,8 @@
 		D7848F012CBD987B00F6F546 /* AddElevationSourceFromRasterView.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D7848EFA2CBD986400F6F546 /* AddElevationSourceFromRasterView.swift */; };
 		D78666AD2A2161F100C60110 /* FindNearestVertexView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D78666AC2A2161F100C60110 /* FindNearestVertexView.swift */; };
 		D78666AE2A21629200C60110 /* FindNearestVertexView.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D78666AC2A2161F100C60110 /* FindNearestVertexView.swift */; };
+		D789AAAD2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift in Sources */ = {isa = PBXBuildFile; fileRef = D789AAAC2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift */; };
+		D789AAAE2D66C737007A8E0E /* CreateKMLMultiTrackView.Model.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D789AAAC2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift */; };
 		D78FA4942C3C88880079313E /* CreateDynamicBasemapGalleryView.Views.swift in Sources */ = {isa = PBXBuildFile; fileRef = D78FA4932C3C88880079313E /* CreateDynamicBasemapGalleryView.Views.swift */; };
 		D78FA4952C3C8E8A0079313E /* CreateDynamicBasemapGalleryView.Views.swift in Copy Source Code Files */ = {isa = PBXBuildFile; fileRef = D78FA4932C3C88880079313E /* CreateDynamicBasemapGalleryView.Views.swift */; };
 		D79482D42C35D872006521CD /* CreateDynamicBasemapGalleryView.swift in Sources */ = {isa = PBXBuildFile; fileRef = D79482D02C35D872006521CD /* CreateDynamicBasemapGalleryView.swift */; };
@@ -585,6 +589,8 @@
 			dstPath = "";
 			dstSubfolderSpec = 7;
 			files = (
+				D789AAAE2D66C737007A8E0E /* CreateKMLMultiTrackView.Model.swift in Copy Source Code Files */,
+				D71563EA2D5AC2D500D2E948 /* CreateKMLMultiTrackView.swift in Copy Source Code Files */,
 				D74F6C452D0CD54200D4FB15 /* ConfigureElectronicNavigationalChartsView.swift in Copy Source Code Files */,
 				D7A85A092CD5AC0B009DC68A /* QueryWithCQLFiltersView.swift in Copy Source Code Files */,
 				D771D0C92CD5522A004C13CB /* ApplyRasterRenderingRuleView.swift in Copy Source Code Files */,
@@ -953,6 +959,7 @@
 		D71371752BD88ECC00EB2F86 /* MonitorChangesToLayerViewStateView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = MonitorChangesToLayerViewStateView.swift; sourceTree = "<group>"; };
 		D713C6D12CB990600073AA72 /* AddKMLLayerView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AddKMLLayerView.swift; sourceTree = "<group>"; };
 		D713C6F52CB9B9A60073AA72 /* US_State_Capitals.kml */ = {isa = PBXFileReference; lastKnownFileType = text.xml; path = US_State_Capitals.kml; sourceTree = "<group>"; };
+		D71563E32D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CreateKMLMultiTrackView.swift; sourceTree = "<group>"; };
 		D718A1E62B570F7500447087 /* OrbitCameraAroundObjectView.Model.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = OrbitCameraAroundObjectView.Model.swift; sourceTree = "<group>"; };
 		D718A1EA2B575FD900447087 /* ManageBookmarksView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = ManageBookmarksView.swift; sourceTree = "<group>"; };
 		D71C5F632AAA7A88006599FD /* CreateSymbolStylesFromWebStylesView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = CreateSymbolStylesFromWebStylesView.swift; sourceTree = "<group>"; };
@@ -1045,6 +1052,7 @@
 		D7848ED42CBD85A300F6F546 /* AddPointSceneLayerView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AddPointSceneLayerView.swift; sourceTree = "<group>"; };
 		D7848EFA2CBD986400F6F546 /* AddElevationSourceFromRasterView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = AddElevationSourceFromRasterView.swift; sourceTree = "<group>"; };
 		D78666AC2A2161F100C60110 /* FindNearestVertexView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = FindNearestVertexView.swift; sourceTree = "<group>"; };
+		D789AAAC2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CreateKMLMultiTrackView.Model.swift; sourceTree = "<group>"; };
 		D78FA4932C3C88880079313E /* CreateDynamicBasemapGalleryView.Views.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CreateDynamicBasemapGalleryView.Views.swift; sourceTree = "<group>"; };
 		D79482D02C35D872006521CD /* CreateDynamicBasemapGalleryView.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = CreateDynamicBasemapGalleryView.swift; sourceTree = "<group>"; };
 		D79EE76D2A4CEA5D005A52AE /* SetUpLocationDrivenGeotriggersView.Model.swift */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.swift; path = SetUpLocationDrivenGeotriggersView.Model.swift; sourceTree = "<group>"; };
@@ -1290,6 +1298,7 @@
 				D7B3C5C02A43B71E001DA4D8 /* Create convex hull around geometries */,
 				D744FD132A2112360084A66C /* Create convex hull around points */,
 				D79482D32C35D872006521CD /* Create dynamic basemap gallery */,
+				D71563E62D5AC2B600D2E948 /* Create KML multi-track */,
 				1C19B4EA2A578E46001D2506 /* Create load report */,
 				D73FABE82AD4A0370048EC70 /* Create mobile geodatabase */,
 				E004A6EB28495538002A1FE6 /* Create planar and geodetic buffers */,
@@ -2111,6 +2120,15 @@
 			path = 324e4742820e46cfbe5029ff2c32cb1f;
 			sourceTree = "<group>";
 		};
+		D71563E62D5AC2B600D2E948 /* Create KML multi-track */ = {
+			isa = PBXGroup;
+			children = (
+				D71563E32D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift */,
+				D789AAAC2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift */,
+			);
+			path = "Create KML multi-track";
+			sourceTree = "<group>";
+		};
 		D718A1E92B575FD900447087 /* Manage bookmarks */ = {
 			isa = PBXGroup;
 			children = (
@@ -3508,6 +3526,7 @@
 				00CCB8A5285BAF8700BBAB70 /* OnDemandResource.swift in Sources */,
 				D7635FFE2B9277DC0044AB97 /* ConfigureClustersView.swift in Sources */,
 				1C19B4F32A578E46001D2506 /* CreateLoadReportView.swift in Sources */,
+				D71563E92D5AC2B600D2E948 /* CreateKMLMultiTrackView.swift in Sources */,
 				7900C5F62A83FC3F002D430F /* AddCustomDynamicEntityDataSourceView.Vessel.swift in Sources */,
 				D71099702A2802FA0065A1C1 /* DensifyAndGeneralizeGeometryView.SettingsView.swift in Sources */,
 				D7201D042CC6D3B5004BDB7D /* AddVectorTiledLayerFromCustomStyleView.swift in Sources */,
@@ -3547,6 +3566,7 @@
 				D7497F3C2AC4B4C100167AD2 /* DisplayDimensionsView.swift in Sources */,
 				D7C97B562B75C10C0097CDA1 /* ValidateUtilityNetworkTopologyView.Views.swift in Sources */,
 				D73FCFF72B02A3AA0006360D /* FindAddressWithReverseGeocodeView.swift in Sources */,
+				D789AAAD2D66C718007A8E0E /* CreateKMLMultiTrackView.Model.swift in Sources */,
 				0005580A2817C51E00224BC6 /* SampleDetailView.swift in Sources */,
 				D75F66362B48EABC00434974 /* SearchForWebMapView.swift in Sources */,
 				D7058B102B59E44B000A888A /* StylePointWithSceneSymbolView.swift in Sources */,

Shared/Samples/Create KML multi-track/CreateKMLMultiTrackView.Model.swift

@@ -0,0 +1,186 @@
+// 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 SwiftUI
+
+struct CreateKMLMultiTrackView: View {
+    /// The view model for the sample.
+    @StateObject private var model = Model()
+    
+    /// The KML multi-track loaded from the KMZ file.
+    @State private var multiTrack: KMLMultiTrack?
+    
+    /// A Boolean value indicating whether the recenter button is enabled.
+    @State private var isRecenterEnabled = false
+    
+    /// The error shown in the error alert.
+    @State private var error: Error?
+    
+    /// Represents the various states of the sample.
+    private enum SampleState {
+        /// The sample is navigating without recording.
+        case navigating
+        /// A KML track is being recorded.
+        case recording
+        /// The KML multi-track is being saved, loaded, and viewed.
+        case viewingMultiTrack
+        /// The sample is being reset.
+        case reseting
+    }
+    
+    /// The current state of the sample.
+    @State private var state = SampleState.navigating
+    
+    /// The text shown in the status bar. This describes the current state of the sample.
+    private var statusText: String {
+        return switch state {
+        case .recording: "Recording KML track. Elements added: \(model.trackElements.count)"
+        case .viewingMultiTrack: "Saved KML multi-track to 'HikingTracks.kmz'."
+        default: "Tap record to capture KML track elements."
+        }
+    }
+    
+    var body: some View {
+        MapViewReader { mapViewProxy in
+            MapView(map: model.map, graphicsOverlays: model.graphicsOverlays)
+                .locationDisplay(model.locationDisplay)
+                .overlay(alignment: .top) {
+                    Text(statusText)
+                        .multilineTextAlignment(.center)
+                        .frame(maxWidth: .infinity, alignment: .center)
+                        .padding(8)
+                        .background(.regularMaterial, ignoresSafeAreaEdges: .horizontal)
+                }
+                .toolbar {
+                    ToolbarItemGroup(placement: .bottomBar) {
+                        if let multiTrack {
+                            Button("Delete", systemImage: "trash", role: .destructive) {
+                                state = .reseting
+                            }
+                            
+                            Spacer()
+                            
+                            TrackPicker(tracks: multiTrack.tracks) { geometry in
+                                await mapViewProxy.setViewpointGeometry(geometry.extent, padding: 25)
+                            }
+                        } else {
+                            Button("Recenter", systemImage: "location.north.circle") {
+                                model.locationDisplay.autoPanMode = .navigation
+                            }
+                            .disabled(!isRecenterEnabled)
+                            
+                            Spacer()
+                            
+                            Toggle(
+                                state == .recording ? "Stop Recording" : "Record Track",
+                                isOn: .init {
+                                    state == .recording
+                                } set: { newValue in
+                                    state = newValue ? .recording : .navigating
+                                }
+                            )
+                            
+                            Spacer()
+                            
+                            Button("Save", systemImage: "square.and.arrow.down") {
+                                state = .viewingMultiTrack
+                            }
+                            .disabled(model.tracks.isEmpty)
+                        }
+                    }
+                }
+                .task(id: state) {
+                    // Runs the asynchronous action associated with the sample state.
+                    do {
+                        switch state {
+                        case .navigating:
+                            break
+                        case .recording:
+                            for await location in model.locationDisplay.$location where location != nil {
+                                model.addTrackElement(at: location!.position)
+                            }
+                            
+                            model.addTrack()
+                        case .viewingMultiTrack:
+                            await model.locationDisplay.dataSource.stop()
+                            
+                            try await model.saveKMLMultiTrack()
+                            multiTrack = try await model.loadKMLMultiTrack()
+                        case .reseting:
+                            model.reset()
+                            multiTrack = nil
+                            
+                            await mapViewProxy.setViewpointScale(model.locationDisplay.initialZoomScale)
+                            try await model.startNavigation()
+                        }
+                    } catch {
+                        self.error = error
+                    }
+                }
+                .task {
+                    // Starts the navigation when the sample opens.
+                    do {
+                        try await model.startNavigation()
+                    } catch {
+                        self.error = error
+                    }
+                    
+                    // Monitors the auto pan mode to determine if recenter button should be enabled.
+                    for await autoPanMode in model.locationDisplay.$autoPanMode {
+                        isRecenterEnabled = autoPanMode != .navigation
+                    }
+                }
+                .errorAlert(presentingError: $error)
+        }
+    }
+}
+
+private extension CreateKMLMultiTrackView {
+    /// A picker for selecting a track from a KML multi-track.
+    struct TrackPicker: View {
+        /// The KML tracks options shown in the picker.
+        let tracks: [KMLTrack]
+        
+        /// The closure to perform when the selected track has changed.
+        let onSelectionChanged: (Geometry) async -> Void
+        
+        /// The track selected by the picker.
+        @State private var selectedTrack: KMLTrack?
+        
+        var body: some View {
+            Picker("Track", selection: $selectedTrack) {
+                Text("All Tracks")
+                    .tag(nil as KMLTrack?)
+                
+                ForEach(Array(tracks.enumerated()), id: \.offset) { offset, track in
+                    Text("KML Track #\(offset + 1)")
+                        .tag(track)
+                }
+            }
+            .task(id: selectedTrack) {
+                guard let geometry = selectedTrack?.geometry
+                        ?? GeometryEngine.union(of: tracks.map(\.geometry)) else {
+                    return
+                }
+                
+                await onSelectionChanged(geometry)
+            }
+        }
+    }
+}
+
+#Preview {
+    CreateKMLMultiTrackView()
+}

Shared/Samples/Create KML multi-track/CreateKMLMultiTrackView.swift

@@ -0,0 +1,39 @@
+# Create KML multi-track
+
+Create, save, and preview a KML multi-track captured from a location data source.
+
+![Create KML multi-track sample](create-kml-multi-track.png)
+
+## Use case
+
+When capturing location data for outdoor activities such as hiking or skiing, it can be useful to record and share your path. This sample demonstrates how you can collect individual KML tracks during a navigation session, then combine and export them as a KML multi-track.
+
+## How to use the sample
+
+Tap "Record Track" to start recording your current path on the simulated trail. Tap "Stop Recording" to end recording and capture a KML track. Repeat these steps to capture multiple KML tracks in a single session. Tap the save button to convert the recorded tracks into a KML multi-track and save it to a local `.kmz` file. Then, use the picker to select a track from the saved KML multi-track. Tap the Delete button to remove the local file and reset the sample.
+
+## How it works
+
+1. Create a `Map` with a basemap style and a `GraphicsOverlay` to display the path geometry for your navigation route.
+2. Create a `SimulatedLocationDataSource` to drive the `LocationDisplay`.
+3. As you receive `Location` updates, add each point to a list of `KMLTrackElement` objects while recording.
+4. Once recording stops, create a `KMLTrack` using one or more `KMLTrackElement` objects.
+5. Combine one or more `KMLTrack` objects into a `KMLMultiTrack`.
+6. Save the `KMLMultiTrack` inside a `KMLDocument`, then export the document to a `.kmz` file.
+7. Load the saved `.kmz` file into a `KMLDataset` and locate the `KMLDocument` in the dataset's `rootNodes`. From the document's `childNodes`, get the `KMLPlacemark` and retrieve the `KMLMultiTrack` geometry.
+8. Retrieve the geometry of each track in the `KMLMultiTrack` by iterating through the list of tracks and obtaining the respective `KMLTrack.geometry`.
+
+## Relevant API
+
+* KMLDataset
+* KMLDocument
+* KMLMultiTrack
+* KMLPlacemark
+* KMLTrack
+* KMLTrackElement
+* LocationDisplay
+* SimulatedLocationDataSource
+
+## Tags
+
+export, hiking, KML, KMZ, multi-track, record, track

Shared/Samples/Create KML multi-track/README.md

@@ -0,0 +1,41 @@
+{
+    "category": "Edit and Manage Data",
+    "description": "Create, save, and preview a KML multi-track captured from a location data source.",
+    "ignore": false,
+    "images": [
+        "create-kml-multi-track.png"
+    ],
+    "keywords": [
+        "KML",
+        "KMZ",
+        "export",
+        "hiking",
+        "multi-track",
+        "record",
+        "track",
+        "KMLDataset",
+        "KMLDocument",
+        "KMLMultiTrack",
+        "KMLPlacemark",
+        "KMLTrack",
+        "KMLTrackElement",
+        "LocationDisplay",
+        "SimulatedLocationDataSource"
+    ],
+    "redirect_from": [],
+    "relevant_apis": [
+        "KMLDataset",
+        "KMLDocument",
+        "KMLMultiTrack",
+        "KMLPlacemark",
+        "KMLTrack",
+        "KMLTrackElement",
+        "LocationDisplay",
+        "SimulatedLocationDataSource"
+    ],
+    "snippets": [
+        "CreateKMLMultiTrackView.swift",
+        "CreateKMLMultiTrackView.Model.swift"
+    ],
+    "title": "Create KML multi-track"
+}