Merge pull request #172 from Esri/v.next

[Release] 200.1.0

Author: yo1995

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,8 +4,8 @@ This repository contains Swift sample code demonstrating the capabilities of [Ar
 
 ## Requirements
 
-* [ArcGIS Maps SDK for Swift](https://developers.arcgis.com/swift/) 200.0 (or newer)
-* [ArcGIS Maps SDK for Swift Toolkit](https://github.com/Esri/arcgis-maps-sdk-swift-toolkit) 200.0 (or newer)
+* [ArcGIS Maps SDK for Swift](https://developers.arcgis.com/swift/) 200.1 (or newer)
+* [ArcGIS Maps SDK for Swift Toolkit](https://github.com/Esri/arcgis-maps-sdk-swift-toolkit) 200.1 (or newer)
 * Xcode 14.0 (or newer)
 
 The *ArcGIS Maps SDK for Swift Samples app* has a *Target SDK* version of *15.0*, meaning that it can run on devices with *iOS 15.0* or newer.
@@ -44,7 +44,7 @@ Please see [Configure App Secrets](Documentation/ConfigureAppSecrets.md) for add
 * Unfamiliar with SwiftUI? Check out Apple's [SwiftUI documentation](https://developer.apple.com/documentation/swiftui/).
 * Want to start a new project? [Setup](https://developers.arcgis.com/swift/get-started) your development environment
 * New to the API? Explore the documentation: [Guide](https://developers.arcgis.com/swift/) | [API Reference](https://developers.arcgis.com/swift/api-reference/documentation/arcgis/)
-* Got a question? Ask the community on our [forum](https://community.esri.com/t5/arcgis-runtime-sdk-for-ios-questions/bd-p/arcgis-runtime-sdk-for-ios-questions)
+* Got a question? Ask the community on our [forum](https://community.esri.com/t5/swift-maps-sdk-questions/bd-p/swift-maps-sdk-questions)
 
 ## Contributing
 
@@ -54,7 +54,7 @@ Find a bug or want to request a new feature? Please let us know by [creating an
 
 ## Licensing
 
-Copyright 2022 Esri
+Copyright 2022 - 2023 Esri
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

README.md

@@ -0,0 +1,106 @@
+// 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
+//
+//   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 SwiftUI
+import ArcGIS
+
+extension AddDynamicEntityLayerView {
+    /// The model used to store the geo model and other expensive objects
+    /// used in this view.
+    class Model: ObservableObject {
+        /// A map with a streets basemap style.
+        let map = Map(basemapStyle: .arcGISStreets)
+        
+        /// The data source for the dynamic entity layer.
+        let streamService: ArcGISStreamService = {
+            let streamService = ArcGISStreamService(url: .streamService)
+            
+            let filter = ArcGISStreamServiceFilter()
+            filter.whereClause = "speed > 0"
+            streamService.filter = filter
+            
+            streamService.purgeOptions.maximumDuration = TimeInterval(5 * 60)
+            return streamService
+        }()
+        
+        /// The layer displaying the dynamic entities on the map.
+        let dynamicEntityLayer: DynamicEntityLayer
+        
+        /// A Boolean value indicating whether track lines should be displayed.
+        @Published var showsTrackLine: Bool {
+            didSet {
+                dynamicEntityLayer.trackDisplayProperties.showsTrackLine = showsTrackLine
+            }
+        }
+        
+        /// A Boolean value indicating whether previous observations should be displayed.
+        @Published var showsPreviousObservations: Bool {
+            didSet {
+                dynamicEntityLayer.trackDisplayProperties.showsPreviousObservations = showsPreviousObservations
+            }
+        }
+        
+        /// The maximum number of previous observations to display.
+        @Published var maximumObservations: CGFloat {
+            didSet {
+                dynamicEntityLayer.trackDisplayProperties.maximumObservations = Int(maximumObservations)
+            }
+        }
+        
+        /// The maximum observations range.
+        /// Used by slider, which requires `CGFloat` values.
+        let maxObservationRange = CGFloat(1)...CGFloat(16)
+        
+        /// The stream service connection status.
+        @Published var connectionStatus: String
+        
+        init() {
+            // Creates the dynamic entity layer.
+            dynamicEntityLayer = DynamicEntityLayer(dataSource: streamService)
+            
+            // Initializes properties from the dynamic entity layer and stream service.
+            showsTrackLine = dynamicEntityLayer.trackDisplayProperties.showsTrackLine
+            showsPreviousObservations = dynamicEntityLayer.trackDisplayProperties.showsPreviousObservations
+            maximumObservations = CGFloat(dynamicEntityLayer.trackDisplayProperties.maximumObservations)
+            connectionStatus = streamService.connectionStatus.description
+            
+            // Adds the dynamic entity layer to the map's operational layers.
+            map.addOperationalLayer(dynamicEntityLayer)
+        }
+    }
+}
+
+private extension URL {
+    static let streamService = URL(
+        string: "https://realtimegis2016.esri.com:6443/arcgis/rest/services/SandyVehicles/StreamServer"
+    )!
+}
+
+extension ConnectionStatus: CustomStringConvertible {
+    /// A user-friendly string for `ConnectionStatus`.
+    public var description: String {
+        switch self {
+        case .connecting:
+            return "Connecting"
+        case .connected:
+            return "Connected"
+        case .disconnected:
+            return "Disconnected"
+        case .failed:
+            return "Failed"
+        @unknown default:
+            return "Unknown"
+        }
+    }
+}

Samples.xcodeproj/project.pbxproj

@@ -0,0 +1,52 @@
+// 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
+//
+//   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 SwiftUI
+
+extension AddDynamicEntityLayerView {
+    struct SettingsView: View {
+        /// The view model for the sample.
+        @EnvironmentObject private var model: Model
+        
+        var body: some View {
+            List {
+                Section("Track display properties") {
+                    Toggle("Track Lines", isOn: $model.showsTrackLine)
+                    Toggle("Previous Observations", isOn: $model.showsPreviousObservations)
+                }
+                
+                Section("Observations") {
+                    VStack {
+                        HStack {
+                            Text("Observations per track")
+                            Spacer()
+                            Text(model.maximumObservations.formatted())
+                                .foregroundColor(.secondary)
+                        }
+                        Slider(value: $model.maximumObservations, in: model.maxObservationRange, step: 1)
+                    }
+                    HStack {
+                        Spacer()
+                        Button("Purge All Observations") {
+                            Task {
+                                try? await model.streamService.purgeAll()
+                            }
+                        }
+                        Spacer()
+                    }
+                }
+            }
+        }
+    }
+}

Shared/Samples/Add dynamic entity layer/AddDynamicEntityLayerView.Model.swift

@@ -0,0 +1,78 @@
+// 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
+//
+//   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 SwiftUI
+import ArcGIS
+
+struct AddDynamicEntityLayerView: View {
+    /// The view model for the sample.
+    @StateObject private var model = Model()
+    
+    /// A Boolean value indicating whether the settings view should be presented.
+    @State var isShowingSettings = false
+    
+    /// The initial viewpoint for the map.
+    @State var viewpoint = Viewpoint(
+        center: Point(x: -12452361.486, y: 4949774.965),
+        scale: 200_000
+    )
+    
+    /// A Boolean value indicating if the stream service is connected.
+    var isConnected: Bool {
+        model.streamService.connectionStatus == .connected
+    }
+    
+    var body: some View {
+        // Creates a map view to display the map.
+        MapView(map: model.map, viewpoint: viewpoint)
+            .toolbar {
+                ToolbarItemGroup(placement: .bottomBar) {
+                    Button(isConnected ? "Disconnect" : "Connect") {
+                        Task {
+                            if isConnected {
+                                try? await model.streamService.disconnect()
+                            } else {
+                                try? await model.streamService.connect()
+                            }
+                        }
+                    }
+                    Spacer()
+                    Button("Dynamic Entity Settings") {
+                        isShowingSettings = true
+                    }
+                    .sheet(isPresented: $isShowingSettings, detents: [.medium], dragIndicatorVisibility: .visible) {
+                        SettingsView()
+                            .environmentObject(model)
+                    }
+                }
+            }
+            .overlay(alignment: .top) {
+                HStack {
+                    Text("Status:")
+                    Text(model.connectionStatus)
+                        .italic()
+                }
+                .frame(maxWidth: .infinity)
+                .padding(.vertical, 6)
+                .background(.thinMaterial, ignoresSafeAreaEdges: .horizontal)
+            }
+            .task {
+                // This will update `connectionStatus` when the stream service
+                // connection status changes.
+                for await status in model.streamService.$connectionStatus {
+                    model.connectionStatus = status.description
+                }
+            }
+    }
+}

Shared/Samples/Add dynamic entity layer/AddDynamicEntityLayerView.SettingsView.swift

@@ -0,0 +1,43 @@
+# Add dynamic entity layer
+
+Display data from an ArcGIS stream service using a dynamic entity layer.
+
+![Image of add dynamic entity layer](add-dynamic-entity-layer.png)
+![Image of add dynamic entity layer settings](add-dynamic-entity-layer-settings.png)
+
+## Use case
+
+A stream service is a type of service provided by ArcGIS Velocity and GeoEvent Server that allows clients to receive a stream of data observations via a web socket. ArcGIS Maps SDK allows you to connect to a stream service and manage the information as dynamic entities and display them in a dynamic entity layer. Displaying information from feeds such as a stream service is important in applications like dashboards where users need to visualize and track updates of real-world objects in real-time.
+
+Use `ArcGISStreamService` to manage the connection to the stream service and purge options to manage how much data is stored and maintained by the application. The dynamic entity layer will display the latest received observation, and you can set track display properties to determine how to display historical information for each dynamic entity. This includes the number of previous observations to show, whether to display track lines in-between previous observations, and setting renderers.
+
+## How to use the sample
+
+Use the controls to connect to or disconnect from the stream service, modify display properties in the dynamic entity layer, and purge all observations from the application.
+
+## How it works
+
+1. Create an `ArcGIStreamService` using a stream service URL.
+2. Set an `ArcGISStreamServiceFilter` on the stream service to limit the amount of data coming from the server.
+3. Set the `maximumDuration` property of the stream service's `purgeOptions` to limit the amount of data managed by the application.
+4. Create a `DynamicEntityLayer` using the stream service.
+5. Update values in the layer's `trackDisplayProperties` to customize the layer's appearance.
+6. Add the `DynamicEntityLayer` to the map.
+
+## Relevant API
+
+* ArcGISStreamService
+* ArcGISStreamServiceFilter
+* ConnectionStatus
+* DynamicEntity
+* DynamicEntityDataSource.PurgeOptions
+* DynamicEntityLayer
+* TrackDisplayProperties
+
+## About the data
+
+This sample uses a [stream service](https://realtimegis2016.esri.com:6443/arcgis/rest/services/SandyVehicles/StreamServer) that simulates live data coming from snowplows near Sandy, Utah. There are multiple vehicle types and multiple agencies operating the snowplows.
+
+## Tags
+
+data, dynamic, entity, live, purge, real-time, service, stream, track

Shared/Samples/Add dynamic entity layer/AddDynamicEntityLayerView.swift

@@ -0,0 +1,43 @@
+{
+    "category": "Layers",
+    "description": "Display data from an ArcGIS stream service using a dynamic entity layer.",
+    "ignore": false,
+    "images": [
+        "add-dynamic-entity-layer-settings.png",
+        "add-dynamic-entity-layer.png"
+    ],
+    "keywords": [
+        "data",
+        "dynamic",
+        "entity",
+        "live",
+        "purge",
+        "real-time",
+        "service",
+        "stream",
+        "track",
+        "ArcGISStreamService",
+        "ArcGISStreamServiceFilter",
+        "ConnectionStatus",
+        "DynamicEntity",
+        "DynamicEntityDataSource.PurgeOptions",
+        "DynamicEntityLayer",
+        "TrackDisplayProperties"
+    ],
+    "redirect_from": [],
+    "relevant_apis": [
+        "ArcGISStreamService",
+        "ArcGISStreamServiceFilter",
+        "ConnectionStatus",
+        "DynamicEntity",
+        "DynamicEntityDataSource.PurgeOptions",
+        "DynamicEntityLayer",
+        "TrackDisplayProperties"
+    ],
+    "snippets": [
+        "AddDynamicEntityLayerView.swift",
+        "AddDynamicEntityLayerView.Model.swift",
+        "AddDynamicEntityLayerView.SettingsView.swift"
+    ],
+    "title": "Add dynamic entity layer"
+}