Merge branch 'v.next' into Caleb/New-ListContentsOfKMLFile

Shared/Samples/Add KML layer/AddKMLLayerView.swift

@@ -0,0 +1,109 @@
+// Copyright 2024 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 AddKMLLayerView: View {
+    /// The view model for the sample.
+    @StateObject private var model = Model()
+
+    /// The viewpoint used to update the map view.
+    @State private var viewpoint: Viewpoint?
+
+    /// The KML layer source selected by the picker.
+    @State private var selectedLayerSource = KMLLayerSource.url
+
+    var body: some View {
+        MapView(map: model.map, viewpoint: viewpoint)
+            .toolbar {
+                ToolbarItem(placement: .bottomBar) {
+                    Picker("KML Layer Source", selection: $selectedLayerSource) {
+                        ForEach(KMLLayerSource.allCases, id: \.self) { source in
+                            Text(source.label)
+                        }
+                    }
+                    .onChange(of: selectedLayerSource, perform: setKMLLayer(forSource:))
+                }
+            }
+            .task {
+                // Loads all the KML layers when the sample opens.
+                let kmlLayers = [model.urlLayer, model.localFileLayer, model.portalItemLayer]
+                await kmlLayers.load()
+
+                setKMLLayer(forSource: selectedLayerSource)
+            }
+    }
+
+    /// Sets a KML layer on the map.
+    /// - Parameter source: The source that was used to create the KML layer.
+    private func setKMLLayer(forSource source: KMLLayerSource) {
+        let kmlLayer = switch source {
+        case .url: model.urlLayer
+        case .localFile: model.localFileLayer
+        case .portalItem: model.portalItemLayer
+        }
+
+        // Replaces the current KML layer on the map.
+        model.map.removeAllOperationalLayers()
+        model.map.addOperationalLayer(kmlLayer)
+
+        // Zooms the map view's viewpoint to the layer.
+        guard let layerExtent = kmlLayer.fullExtent else { return }
+        let expandedExtent = layerExtent.withBuilder { $0.expand(by: 1.1) }
+        viewpoint = Viewpoint(boundingGeometry: expandedExtent)
+    }
+}
+
+private extension AddKMLLayerView {
+    /// The view model that contains the map and KML layers.
+    final class Model: ObservableObject {
+        /// A map with a dark grey basemap.
+        let map = Map(basemapStyle: .arcGISDarkGrayBase)
+
+        /// A KML layer created from a web URL.
+        let urlLayer: KMLLayer = {
+            let url = URL(string: "https://www.wpc.ncep.noaa.gov/kml/noaa_chart/WPC_Day1_SigWx.kml")!
+            let kmlDataset = KMLDataset(url: url)
+            return KMLLayer(dataset: kmlDataset)
+        }()
+
+        /// A KML layer created from a local file in the bundle.
+        let localFileLayer: KMLLayer = {
+            let kmlDataset = KMLDataset(name: "US_State_Capitals", bundle: .main)!
+            return KMLLayer(dataset: kmlDataset)
+        }()
+
+        /// A KML layer created from a portal item.
+        let portalItemLayer: KMLLayer = {
+            let portalID = PortalItem.ID("9fe0b1bfdcd64c83bd77ea0452c76253")!
+            let portalItem = PortalItem(portal: .arcGISOnline(connection: .anonymous), id: portalID)
+            return KMLLayer(item: portalItem)
+        }()
+    }
+
+    /// A source that was used to create a KML layer.
+    enum KMLLayerSource: CaseIterable {
+        case url, localFile, portalItem
+
+        /// A human-readable label for the KML layer source.
+        var label: String {
+            switch self {
+            case .url: "URL"
+            case .localFile: "Local File"
+            case .portalItem: "Portal Item"
+            }
+        }
+    }
+}

Shared/Samples/Add KML layer/README.md

@@ -0,0 +1,41 @@
+# Add KML layer
+
+Display KML from a URL, portal item, or local KML file.
+
+![Screenshot of Add KML layer sample](add-kml-layer.png)
+
+## Use case
+
+Keyhole Markup Language (KML) is a data format used by Google Earth. KML is popular as a transmission format for consumer use and for sharing geographic data between apps. You can use the Maps SDKs to display KML files, with full support for a variety of features, including network links, 3D models, screen overlays, and tours.
+
+## How to use the sample
+
+Use the picker to select a source. A KML layer created from that source will then be displayed in the map.
+
+## How it works
+
+1. To create a KML layer from a URL, create a `KMLDataset` with the URL to the KML file. Then, create a `KMLLayer` using the dataset.
+2. To create a KML layer from a portal item, create a `PortalItem` with a `Portal` and the KML portal item ID. Then, create a `KMLLayer` using the portal item.
+3. To create a KML layer from a local file, create a `KMLDataset` using the absolute file path to the local KML file. Then, create a `KMLLayer` using the dataset.
+4. Add the layer to the map with `addOperationalLayer(_:)`.
+
+## Relevant API
+
+* KMLDataset
+* KMLLayer
+
+## Offline data
+
+This sample uses the [US State Capitals](https://www.arcgis.com/home/item.html?id=324e4742820e46cfbe5029ff2c32cb1f) KML file. It is downloaded from ArcGIS Online automatically.
+
+## About the data
+
+This sample displays three different KML files:
+
+* From URL: This is a map of the significant weather outlook produced by NOAA/NWS. It uses KML network links to always show the latest data.
+* From local file: This is a map of U.S. state capitals. It doesn't define an icon, so the default pushpin is used for the points.
+* From portal item: This is a map of U.S. states.
+
+## Tags
+
+keyhole, KML, KMZ, OGC

Shared/Samples/Add KML layer/README.metadata.json

@@ -0,0 +1,28 @@
+{
+    "category": "Layers",
+    "description": "Display KML from a URL, portal item, or local KML file.",
+    "ignore": false,
+    "images": [
+        "add-kml-layer.png"
+    ],
+    "keywords": [
+        "KML",
+        "KMZ",
+        "OGC",
+        "keyhole",
+        "KMLDataset",
+        "KMLLayer"
+    ],
+    "offline_data": [
+        "324e4742820e46cfbe5029ff2c32cb1f"
+    ],
+    "redirect_from": [],
+    "relevant_apis": [
+        "KMLDataset",
+        "KMLLayer"
+    ],
+    "snippets": [
+        "AddKMLLayerView.swift"
+    ],
+    "title": "Add KML layer"
+}

Shared/Samples/Add elevation source from raster/AddElevationSourceFromRasterView.swift

@@ -0,0 +1,61 @@
+// Copyright 2024 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 AddElevationSourceFromRasterView: View {
+    /// A scene with elevation for Monterey, California.
+    @State private var scene: ArcGIS.Scene = {
+        let scene = Scene(basemapStyle: .arcGISImagery)
+
+        // Creates the raster elevation source using a URL.
+        let rasterElevationSource = RasterElevationSource(fileURLs: [.montereyElevation])
+
+        // Creates a surface to add the elevation source to the scene.
+        let surface = Surface()
+        surface.addElevationSource(rasterElevationSource)
+        scene.baseSurface = surface
+
+        // Sets the scene's initial camera to showcase the elevation.
+        let camera = Camera(
+            latitude: 36.525,
+            longitude: -121.8,
+            altitude: 300,
+            heading: 180,
+            pitch: 80,
+            roll: 0
+        )
+        let viewpoint = Viewpoint(latitude: .nan, longitude: .nan, scale: .nan, camera: camera)
+        scene.initialViewpoint = viewpoint
+
+        return scene
+    }()
+
+    var body: some View {
+        // Displays the scene in a scene view.
+        SceneView(scene: scene)
+    }
+}
+
+private extension URL {
+    /// The URL to the local DTED2 Raster file with elevation for Monterey, California.
+    static var montereyElevation: URL {
+        Bundle.main.url(forResource: "MontereyElevation", withExtension: "dt2")!
+    }
+}
+
+#Preview {
+    AddElevationSourceFromRasterView()
+}

Shared/Samples/Add elevation source from raster/README.md

@@ -0,0 +1,50 @@
+# Add elevation source from raster
+
+Set the terrain surface with elevation described by a raster file.
+
+![Screenshot of Add elevation source from raster sample](add-elevation-source-from-raster.png)
+
+## Use case
+
+In a scene view, the terrain surface is what the basemap, operational layers, and graphics are draped onto. For example, when viewing a scene in a mountainous region, applying a terrain surface to the scene will help in recognizing the slopes, valleys, and elevated areas.
+
+## How to use the sample
+
+When opened, the sample displays a scene with a terrain surface applied. Pan and zoom to explore the scene and observe how the terrain surface allows visualizing elevation differences.
+
+## How it works
+
+1. Create a `Scene` and add it to a `SceneView`.
+2. Create a `RasterElevationSource` with an array of raster file URLs.
+3. Add the source to the scene's base surface.
+
+## Relevant API
+
+* RasterElevationSource
+* Surface
+
+## Offline data
+
+This sample uses the [MontereyElevation](https://arcgisruntime.maps.arcgis.com/home/item.html?id=98092369c4ae4d549bbbd45dba993ebc) raster. It is downloaded from ArcGIS Online automatically.
+
+## Additional information
+
+ Supported raster formats include:
+
+* ASRP/USRP
+* CIB1, 5, 10
+* DTED0, 1, 2
+* GeoTIFF
+* HFA
+* HRE
+* IMG
+* JPEG
+* JPEG 2000
+* NITF
+* PNG
+* RPF
+* SRTM1, 2
+
+## Tags
+
+3D, elevation, raster, surface, terrain

Shared/Samples/Add elevation source from raster/README.metadata.json

@@ -0,0 +1,29 @@
+{
+    "category": "Scenes",
+    "description": "Set the terrain surface with elevation described by a raster file.",
+    "ignore": false,
+    "images": [
+        "add-elevation-source-from-raster.png"
+    ],
+    "keywords": [
+        "3D",
+        "elevation",
+        "raster",
+        "surface",
+        "terrain",
+        "RasterElevationSource",
+        "Surface"
+    ],
+    "offline_data": [
+        "98092369c4ae4d549bbbd45dba993ebc"
+    ],
+    "redirect_from": [],
+    "relevant_apis": [
+        "RasterElevationSource",
+        "Surface"
+    ],
+    "snippets": [
+        "AddElevationSourceFromRasterView.swift"
+    ],
+    "title": "Add elevation source from raster"
+}

Shared/Samples/Add elevation source from tile package/AddElevationSourceFromTilePackageView.swift

@@ -0,0 +1,61 @@
+// Copyright 2024 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 AddElevationSourceFromTilePackageView: View {
+    /// A scene with elevation for Monterey, California.
+    @State private var scene: ArcGIS.Scene = {
+        let scene = Scene(basemapStyle: .arcGISImagery)
+
+        // Creates the tiled elevation source using a URL.
+        let rasterElevationSource = ArcGISTiledElevationSource(url: .montereyElevationTilePackage)
+
+        // Creates a surface to add the elevation source to the scene.
+        let surface = Surface()
+        surface.addElevationSource(rasterElevationSource)
+        scene.baseSurface = surface
+
+        // Sets the scene's initial camera to showcase the elevation.
+        let camera = Camera(
+            latitude: 36.525,
+            longitude: -121.8,
+            altitude: 300,
+            heading: 180,
+            pitch: 80,
+            roll: 0
+        )
+        let viewpoint = Viewpoint(latitude: .nan, longitude: .nan, scale: .nan, camera: camera)
+        scene.initialViewpoint = viewpoint
+
+        return scene
+    }()
+
+    var body: some View {
+        // Displays the scene in a scene view.
+        SceneView(scene: scene)
+    }
+}
+
+private extension URL {
+    /// The URL to the local tile package file with elevation data for Monterey, California.
+    static var montereyElevationTilePackage: URL {
+        Bundle.main.url(forResource: "MontereyElevation", withExtension: "tpkx")!
+    }
+}
+
+#Preview {
+    AddElevationSourceFromTilePackageView()
+}