Merge branch 'v.next' into trev8939/filterFeaturesInScene

samples/create-kml-multi-track/README.md

@@ -0,0 +1,42 @@
+# Create KML multi-track
+
+Create, save and preview a KML multi-track, captured from a location data source.
+
+![Create KML multi-track](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 **Start Navigation** to begin moving along a simulated trail. Tap **Record Track** to start recording your current path. Tap **Stop Recording** to end recording and capture a KML track. Repeat steps to capture multiple KML tracks in a single session. Tap the **Save** button to save your recorded tracks as a `.kmz` file to local storage. Then load the created `.kmz` file containing your KML multi-track to view all created tracks on the map.
+
+## How it works
+
+1. Create an `ArcGISMap` with a basemap 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. On recording stopped, 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
+* LocationDisplay
+* SimulatedLocationDataSource
+
+## Additional information
+
+This sample uses the GeoView-Compose Toolkit module to be able to implement a composable MapView.
+
+## Tags
+
+export, geoview-compose, hiking, kml, kmz, multi-track, record, track

samples/create-kml-multi-track/README.metadata.json

@@ -0,0 +1,43 @@
+{
+    "category": "Edit and Manage Data",
+    "description": "Create, save and preview a KML multi-track, captured from a location data source.",
+    "formal_name": "CreateKmlMultiTrack",
+    "ignore": false,
+    "images": [
+        "create-kml-multi-track.png"
+    ],
+    "keywords": [
+        "export",
+        "geoview-compose",
+        "hiking",
+        "kml",
+        "kmz",
+        "multi-track",
+        "record",
+        "track",
+        "KmlDataset",
+        "KmlDocument",
+        "KmlMultiTrack",
+        "KmlPlacemark",
+        "KmlTrack",
+        "LocationDisplay",
+        "SimulatedLocationDataSource"
+    ],
+    "language": "kotlin",
+    "redirect_from": "",
+    "relevant_apis": [
+        "KmlDataset",
+        "KmlDocument",
+        "KmlMultiTrack",
+        "KmlPlacemark",
+        "KmlTrack",
+        "LocationDisplay",
+        "SimulatedLocationDataSource"
+    ],
+    "snippets": [
+        "src/main/java/com/esri/arcgismaps/sample/createkmlmultitrack/components/CreateKMLMultiTrackViewModel.kt",
+        "src/main/java/com/esri/arcgismaps/sample/createkmlmultitrack/MainActivity.kt",
+        "src/main/java/com/esri/arcgismaps/sample/createkmlmultitrack/screens/CreateKMLMultiTrackScreen.kt"
+    ],
+    "title": "Create KML multi-track"
+}

samples/create-kml-multi-track/build.gradle.kts

@@ -0,0 +1,22 @@
+plugins {
+    alias(libs.plugins.arcgismaps.android.library)
+    alias(libs.plugins.arcgismaps.android.library.compose)
+    alias(libs.plugins.arcgismaps.kotlin.sample)
+    alias(libs.plugins.gradle.secrets)
+}
+
+secrets {
+    // this file doesn't contain secrets, it just provides defaults which can be committed into git.
+    defaultPropertiesFileName = "secrets.defaults.properties"
+}
+
+android {
+    namespace = "com.esri.arcgismaps.sample.createkmlmultitrack"
+    buildFeatures {
+        buildConfig = true
+    }
+}
+
+dependencies {
+    // Only module specific dependencies needed here
+}

samples/create-kml-multi-track/src/main/AndroidManifest.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application><activity
+            android:exported="true"
+            android:name=".MainActivity"
+            android:label="@string/create_kml_multi_track_app_name">
+
+        </activity>
+    </application>
+
+</manifest>

samples/create-kml-multi-track/src/main/java/com/esri/arcgismaps/sample/createkmlmultitrack/MainActivity.kt

@@ -0,0 +1,53 @@
+/* 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.createkmlmultitrack
+
+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.sampleslib.theme.SampleAppTheme
+import com.esri.arcgismaps.sample.createkmlmultitrack.screens.CreateKMLMultiTrackScreen
+
+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)
+
+        setContent {
+            SampleAppTheme {
+                CreateKMLMultiTrackApp()
+            }
+        }
+    }
+
+    @Composable
+    private fun CreateKMLMultiTrackApp() {
+        Surface(color = MaterialTheme.colorScheme.background) {
+            CreateKMLMultiTrackScreen(
+                sampleName = getString(R.string.create_kml_multi_track_app_name)
+            )
+        }
+    }
+}