Release v200.5.0 (#224)

README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-ArcGIS Maps SDK for Kotlin v200.4.0 samples.  The `main` branch of this repository contains sample app modules for the latest available version of the [ArcGIS Maps SDK Android Kotlin](https://developers.arcgis.com/kotlin/). Samples released under older versions can be found through the [git tags](https://github.com/Esri/arcgis-maps-sdk-kotlin-samples/tags).  Please read our [wiki](https://github.com/Esri/arcgis-maps-sdk-kotlin-samples/wiki) for help with working with this repository.
+ArcGIS Maps SDK for Kotlin v200.5.0 samples.  The `main` branch of this repository contains sample app modules for the latest available version of the [ArcGIS Maps SDK Android Kotlin](https://developers.arcgis.com/kotlin/). Samples released under older versions can be found through the [git tags](https://github.com/Esri/arcgis-maps-sdk-kotlin-samples/tags).  Please read our [wiki](https://github.com/Esri/arcgis-maps-sdk-kotlin-samples/wiki) for help with working with this repository.
 
 ## Prerequisites
 
@@ -25,7 +25,12 @@ Accessing Esri location services, including basemaps, routing, and geocoding, re
 
 ### API key
 
-A permanent key that gives your application access to Esri location services. Visit your [ArcGIS Developers Dashboard](https://developers.arcgis.com/dashboard) to create a new API key or access an existing API key.
+A long-lived access token that gives your application access to ArcGIS location services. Go to the [Create an API key](https://links.esri.com/create-an-api-key) tutorial to obtain a new API key access token. Ensure that the following privileges are enabled:
+
+  * **Location services** > **Basemaps**
+  * **Location services** > **Geocoding**
+  * **Location services** > **Routing**
+
 The Android samples in this repository have been structured to use an API key, set once, which will run in all samples.
 Set your API key in the `gradle.properties` file located in the `/.gradle` folder within your home directory.
 The API_KEY property should contain quotes around the key itself:

add-3d-tiles-layer/.gitignore

@@ -0,0 +1 @@
+/build

add-3d-tiles-layer/README.md

@@ -0,0 +1,39 @@
+# Add 3d tiles layer
+
+Add a layer to visualize 3D tiles data that conforms to the OGC 3D Tiles specification.
+
+![Add 3D Tiles Layer](add-3d-tiles-layer.png)
+
+## Use case
+
+In addition to offering a 3D view, a 3D tiles layer can assist in performing visual analysis, such as line of sight analysis. A [line of sight analysis](https://developers.arcgis.com/documentation/mapping-apis-and-services/spatial-analysis/tutorials/apis/display-a-line-of-sight/) can be used to assess whether a view is obstructed between an observer and a target.
+
+## How to use the sample
+
+When loaded, the sample will display a scene with an `Ogc3DTilesLayer`. Pan around and zoom in to observe the scene of the `Ogc3DTilesLayer`. Notice how the layer's level of detail changes as you zoom in and out from the layer.
+
+## How it works
+
+1. Create a `Scene`.
+2. Create an `Ogc3DTilesLayer` with the URL to a 3D tiles layer service.
+3. Add the layer to the scene's operational layers.
+
+## Relevant API
+
+* Camera
+* Ogc3DTilesLayer
+* SceneView
+
+## About the data
+
+A layer to visualize 3D tiles data that conforms to the OGC 3D Tiles specification. As of 200.4, it supports analyses like viewshed and line of sight, but does not support other operations like individual feature identification.
+
+The 3D Tiles Open Geospatial Consortium (OGC) specification defines a spatial data structure and a set of tile formats designed for streaming and rendering 3D geospatial content. A 3D Tiles data set, known as a tileset, defines one or more tile formats organized into a hierarchical spatial data structure. For more information, see the [OGC 3D Tiles specification](https://www.ogc.org/standard/3DTiles).
+
+## Additional information
+
+This sample uses the GeoViewCompose Toolkit module to be able to implement a Composable SceneView.
+
+## Tags
+
+3d tiles, geoviewcompose, layers, OGC, OGC API, scene, service

add-3d-tiles-layer/README.metadata.json

@@ -0,0 +1,34 @@
+{
+    "category": "Layers",
+    "description": "Add a layer to visualize 3D tiles data that conforms to the OGC 3D Tiles specification.",
+    "formal_name": "Add3DTilesLayer",
+    "ignore": false,
+    "images": [
+        "add-3d-tiles-layer.png"
+    ],
+    "keywords": [
+        "3d tiles",
+        "OGC",
+        "OGC API",
+        "geoviewcompose",
+        "layers",
+        "scene",
+        "service",
+        "Camera",
+        "Ogc3DTilesLayer",
+        "SceneView"
+    ],
+    "language": "kotlin",
+    "redirect_from": "",
+    "relevant_apis": [
+        "Camera",
+        "Ogc3DTilesLayer",
+        "SceneView"
+    ],
+    "snippets": [
+        "src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/MainActivity.kt",
+        "src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/components/SceneViewModel.kt",
+        "src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/screens/MainScreen.kt"
+    ],
+    "title": "Add 3d tiles layer"
+}

add-3d-tiles-layer/build.gradle.kts

@@ -0,0 +1,54 @@
+plugins {
+    id("com.android.application")
+    id("org.jetbrains.kotlin.android")
+}
+
+android {
+    compileSdk = libs.versions.compileSdk.get().toInt()
+
+    defaultConfig {
+        applicationId = "com.esri.arcgismaps.sample.add3dtileslayer"
+        minSdk = libs.versions.minSdk.get().toInt()
+        targetSdk = libs.versions.targetSdk.get().toInt()
+        versionCode = libs.versions.versionCode.get().toInt()
+        versionName = libs.versions.versionName.get()
+        buildConfigField("String", "API_KEY", project.properties["API_KEY"].toString())
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro")
+        }
+    }
+
+    buildFeatures {
+        compose = true
+        buildConfig = true
+    }
+
+    composeOptions {
+        kotlinCompilerExtensionVersion = libs.versions.kotlinCompilerExt.get()
+    }
+
+    namespace = "com.esri.arcgismaps.sample.add3dtileslayer"
+}
+
+dependencies {
+    // lib dependencies from rootProject build.gradle.kts
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.lifecycle.viewmodel.compose)
+    implementation(libs.androidx.activity.compose)
+    // Jetpack Compose Bill of Materials
+    implementation(platform(libs.androidx.compose.bom))
+    // Jetpack Compose dependencies
+    implementation(libs.androidx.compose.ui)
+    implementation(libs.androidx.compose.material3)
+    implementation(libs.androidx.compose.ui.tooling)
+    implementation(libs.androidx.compose.ui.tooling.preview)
+    implementation(project(":samples-lib"))
+    // Toolkit dependencies
+    implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
+    implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
+}

add-3d-tiles-layer/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.kts.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

add-3d-tiles-layer/src/main/AndroidManifest.xml

@@ -0,0 +1,24 @@
+<?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
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme">
+        <activity
+            android:exported="true"
+            android:name=".MainActivity">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

add-3d-tiles-layer/src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/MainActivity.kt

@@ -0,0 +1,55 @@
+/* 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
+ *
+ *    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.add3dtileslayer
+
+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.add3dtileslayer.screens.MainScreen
+import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
+
+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.API_KEY)
+
+        setContent {
+            SampleAppTheme {
+                Add3DTilesLayerApp()
+            }
+        }
+    }
+
+    @Composable
+    private fun Add3DTilesLayerApp() {
+        Surface(
+            color = MaterialTheme.colorScheme.background
+        ) {
+            MainScreen(
+                sampleName = getString(R.string.app_name)
+            )
+        }
+    }
+}

add-3d-tiles-layer/src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/components/SceneViewModel.kt

@@ -0,0 +1,65 @@
+/* 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
+ *
+ *    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.add3dtileslayer.components
+
+import android.app.Application
+import androidx.lifecycle.AndroidViewModel
+import com.arcgismaps.mapping.ArcGISScene
+import com.arcgismaps.mapping.ArcGISTiledElevationSource
+import com.arcgismaps.mapping.BasemapStyle
+import com.arcgismaps.mapping.Viewpoint
+import com.arcgismaps.mapping.layers.Ogc3DTilesLayer
+import com.arcgismaps.mapping.view.Camera
+import com.arcgismaps.toolkit.geoviewcompose.SceneViewProxy
+
+class SceneViewModel(application: Application) : AndroidViewModel(application) {
+
+    // Create a SceneViewProxy which is passed to the composable SceneView
+    val sceneViewProxy = SceneViewProxy()
+
+    // Create a scene with a dark gray basemap that gets passed to the composable SceneView.
+    val scene = ArcGISScene(BasemapStyle.ArcGISDarkGray).apply {
+
+        // Add an elevation source to the scene's base surface.
+        baseSurface.elevationSources.add(
+            ArcGISTiledElevationSource(
+                "https://elevation3d.arcgis.com/arcgis/rest/services/WorldElevation3D/Terrain3D/ImageServer"
+            )
+        )
+
+        // Add a 3D tiles layer to the scene. The URL points to a 3D tiles layer that shows
+        // buildings in Stuttgart, Germany.
+        operationalLayers.add(
+            Ogc3DTilesLayer(
+                "https://tiles.arcgis.com/tiles/ZQgQTuoyBrtmoGdP/arcgis/rest/services/Stuttgart/3DTilesServer/tileset.json"
+            )
+        )
+
+        // Set the initial viewpoint of the scene. The viewpoint is set to a location in Stuttgart.
+        initialViewpoint = Viewpoint(
+            latitude = 48.8466, longitude = 9.1627, scale = 1000.0,
+            camera = Camera(
+                latitude = 48.84553,
+                longitude = 9.16275,
+                altitude = 450.0,
+                heading = 0.0,
+                pitch = 60.0,
+                roll = 0.0
+            )
+        )
+    }
+}

add-3d-tiles-layer/src/main/java/com/esri/arcgismaps/sample/add3dtileslayer/screens/MainScreen.kt

@@ -0,0 +1,49 @@
+/* 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
+ *
+ *    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.add3dtileslayer.screens
+
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.Scaffold
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.lifecycle.viewmodel.compose.viewModel
+import com.arcgismaps.toolkit.geoviewcompose.SceneView
+import com.esri.arcgismaps.sample.add3dtileslayer.components.SceneViewModel
+import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
+
+/**
+ * Main screen layout for the sample app
+ */
+@Composable
+fun MainScreen(sampleName: String) {
+    // create a ViewModel to handle SceneView interactions
+    val sceneViewModel = viewModel<SceneViewModel>()
+
+    Scaffold(
+        topBar = { SampleTopAppBar(title = sampleName) },
+        content = {
+            SceneView(
+                modifier = Modifier
+                    .fillMaxSize()
+                    .padding(it),
+                sceneViewProxy = sceneViewModel.sceneViewProxy,
+                arcGISScene = sceneViewModel.scene
+            )
+        }
+    )
+}