Sync Dev with Master (#464)

* Update readmes to match common design (analysis category) (#444)

* update analyse hotspots

* update distance measurement analysis

* update line of sight geoelement

* update line of sight location

* update viewshed camera

* update viewshed geoelement

* update viewshed geoprocessing

* update viewshed location

* casing of sample names / readme headers

* tap -> click

* implement review changes

* Apply suggestions from code review

Co-Authored-By: Rachael Ellen <[email protected]>

Co-authored-by: Rachael Ellen <[email protected]>

* Display annotation (#442)

* add sample

* update metadata

* better sreenshot

* restore unrelated file

* review comments

* Update display_information/display-annotation/src/main/java/com/esri/samples/display_annotation/DisplayAnnotationSample.java

Co-Authored-By: Tyler Schiewe <[email protected]>

Co-authored-by: Tyler Schiewe <[email protected]>

* Display annotation - fix readme (#446)

* add sample

* update metadata

* better sreenshot

* restore unrelated file

* review comments

* Map -> ArcGISMap

* Update readmes to match common design (Editing category) (#450)

* update readmes to match common design

* update with review comments

* Update README.md

Co-authored-by: Rachael Ellen <[email protected]>
Co-authored-by: Tyler Schiewe <[email protected]>

Author: 3 people

analysis/analyze-hotspots/README.md

@@ -1,31 +1,33 @@
-# Analyze Hotspots
+# Analyze hotspots
 
-Perform hotspot analysis using a geoprocessing service.
+Use a geoprocessing service and a set of features to identify statistically significant hot spots and cold spots.
 
-In this case, frequency of 911 calls in an area are analyzed.
+![Image of analyze hotspots](AnalyzeHotspots.png)
 
-![](AnalyzeHotspots.png)
+## Use case
+
+This tool identifies statistically significant spatial clusters of high values (hot spots) and low values (cold spots). For example, a hotspot analysis based on the frequency of 911 calls within a set region.
 
 ## How to use the sample
 
-Select a start and end date using the datepickers between 1/1/1998 and 5/31/1998 respectively. Click the "Analyze hotspots" button to start the geoprocessing job.
+Select a date range (between 1998-01-01 and 1998-05-31) from the dialog and click "Analyze Hotspots". The results will be shown on the map upon successful completion of the geoprocessing job.
 
 ## How it works
 
-To analyze hotspots using a geoprocessing service:
-
-1. Create a `GeoprocessingTask` with the URL set to the endpoint of the geoprocessing service.
-2. Create a query string with the date range as an input of `GeoprocessingParameters`.
-3. Use the `GeoprocessingTask` to create a `GeoprocessingJob` with the parameters.
-4. Start the job and wait for it to complete and return a `GeoprocessingResult`.
-5. Get the resulting `ArcGISMapImageLayer` using `geoprocessingResult.getMapImageLayer()`.
-6. Add the layer to the map's operational layers.
+1. Create a `GeoprocessingTask` with the URL set to the endpoint of a geoprocessing service.
+1. Create a query string with the date range as an input of `GeoprocessingParameters`.
+1. Use the `GeoprocessingTask` to create a `GeoprocessingJob` with the `GeoprocessingParameters` instance.
+1. Start the `GeoprocessingJob` and wait for it to complete and return a `GeoprocessingResult`.
+1. Get the resulting `ArcGISMapImageLayer` using `GeoprocessingResult.getMapImageLayer()`.
+1. Add the layer to the map's operational layers.
 
 ## Relevant API
 
-* ArcGISMapImageLayer
 * GeoprocessingJob
 * GeoprocessingParameters
 * GeoprocessingResult
-* GeoprocessingString
 * GeoprocessingTask
+
+## Tags
+
+analysis, density, geoprocessing, hot spots, hotspots

analysis/distance-measurement-analysis/README.md

@@ -1,33 +1,33 @@
-# Distance Measurement Analysis
+# Distance measurement analysis
 
-Measure distances within a scene.
+Measure distances between two points in 3D.
 
-The distance measurement analysis allows you to add the same measuring experience found in ArcGIS Pro, City Engine, and the ArcGIS API for JavaScript to your app. You can set the unit system of measurement (metric or imperial) and have the units automatically switch to one appropriate for the current scale. The rendering is handled internally so it doesn't interfere with other analyses like viewsheds.
+![Image of distance measurement analysis](DistanceMeasurementAnalysis.png)
 
-![](DistanceMeasurementAnalysis.png)
+## Use case
+
+The distance measurement analysis allows you to add to your app the same interactive measuring experience found in ArcGIS Pro, City Engine, and the ArcGIS API for JavaScript. You can set the unit system of measurement (metric or imperial). The units automatically switch to one appropriate for the current scale.
 
 ## How to use the sample
 
-Choose a unit system for the measurement in the UI dropdown. Click any location in the scene to start measuring. Move the mouse to an end location, and click to complete the measure. Clicking any new location after this will start a new measurement.
+Choose a unit system for the measurement. Click any location in the scene to start measuring. Move the mouse to an end location, and click to complete the measurement. Click a new location to clear and start a new measurement.
 
 ## How it works
 
-To measure distances with the `LocationDistanceMeasurement` analysis:
-
-1. Create an `AnalysisOverlay` and add it to your scene view's analysis overlay collection: `sceneView.getAnalysisOverlays().add(analysisOverlay)`.
-2. Create a `LocationDistanceMeasurement`, specifying the `startLocation` and `endLocation`. These can be the same point to start with. Add the analysis to the analysis overlay: `analysisOverlay.getAnalyses().add(LocationDistanceMeasurement)`. The measuring line will be drawn for you between the two points.
-3. The `measurementChanged` callback will fire if the distances change. You can get the new values for the `directDistance`, `horizontalDistance`, and `verticalDistance` from the `MeasurementChangedEvent` returned by the callback. The distance objects contain both a scalar value and a unit of measurement.
+1. Create an `AnalysisOverlay` object and add it to the analysis overlay collection of the `SceneView` object.
+2. Specify the start location and end location to create a `LocationDistanceMeasurement` object. Initially, the start and end locations can be the same point.
+3. Add the location distance measurement analysis to the analysis overlay.
+4. The `measurementChanged` callback will trigger if the distances change. You can get the new values for the `directDistance`, `horizontalDistance`, and `verticalDistance` from the `MeasurementChangedEvent` object returned by the callback.
 
 ## Relevant API
 
 * AnalysisOverlay
 * LocationDistanceMeasurement
-* UnitSystem
 
 ## Additional information
 
-The `LocationDistanceMeasurement` analysis only performs planar distance calculations. This may not be appropriate for large distances where the Earth's curvature needs to be taken into account.
+The `LocationDistanceMeasurement` analysis only performs planar distance calculations. This may not be appropriate for large distances where the Earth's curvature must be considered.
 
 ## Tags
 
-Analysis, 3D
+3D, analysis, distance, measure

analysis/line-of-sight-geoelement/README.md

@@ -1,29 +1,34 @@
-# Line of Sight GeoElement
+# Line of sight geoelement
 
 Show a line of sight between two moving objects.
 
-To determine if an observer can see a target, you can show a line of sight between them. The line will be green until it is obstructed, in which case it will turn red. By using the GeoElement variant of the line of sight, the line will automatically update when either GeoElement moves.
+![Image of line of sight geoelement](LineOfSightGeoElement.gif)
 
-![](LineOfSightGeoElement.gif)
+## Use case
+
+A line of sight between `GeoElement`s (i.e. observer and target) will not remain constant whilst one or both are on the move.
+
+A `GeoElementLineOfSight` is therefore useful in cases where visibility between two `GeoElement`s requires monitoring over a period of time in a partially obstructed field of view
+(such as buildings in a city).
 
 ## How to use the sample
 
-A line of sight will display between a point on the Empire State Building (observer) and a taxi (target). The taxi will drive around a block and the line of sight should automatically update. The taxi will be highlighted when it is visibile. You can change the observer height with the slider to see how it affects the target's visibility.
+A line of sight will display between a point on the Empire State Building (observer) and a taxi (target).
+The taxi will drive around a block and the line of sight should automatically update.
+The taxi will be highlighted when it is visible. You can change the observer height with the slider to see how it affects the target's visibility.
 
 ## How it works
 
-To show a line of sight between two graphics:
-
-1. Create an `AnalysisOverlay` and add it to the `SceneView`'s analysis overlays collection.
-2. Create a `GeoElementLineOfSight`, passing in observer and target `GeoElement`s (feautures or graphics). Add the line of sight to the analysis overlay's analyses collection.
-3. To get the target visibility when it changes, add a `TargetVisibilityChangedListener` to the line of sight. The changed event will give the `TargetVisibility`.
+1. Instantiate an `AnalysisOverlay` and add it to the `SceneView`'s analysis overlays collection.
+2. Instantiate a `GeoElementLineOfSight`, passing in observer and target `GeoElement`s (features or graphics). Add the line of sight to the analysis overlay's analyses collection.
+3. To get the target visibility when it changes, react to the target visibility changing on the `GeoElementLineOfSight` instance.
 
 ## Relevant API
 
 * AnalysisOverlay
 * GeoElementLineOfSight
-* LineOfSight.TargetVisibility
+* LineOfSight.getTargetVisibility
 
 ## Tags
 
-Analysis
+3D, line of sight, visibility, visibility analysis

analysis/line-of-sight-location/README.md

@@ -1,28 +1,32 @@
-# Line of Sight Location
+# Line of sight location
 
-Perform line of sight analysis in real-time.
+Perform a line of sight analysis between two points in real time.
+
+![Image of line of sight location](LineOfSightLocation.gif)
+
+## Use case
+
+A line of sight analysis can be used to assess whether a view is obstructed between an observer and a target. Obstructing features could either be natural, like topography, or man-made, like buildings. Consider an events planning company wanting to commemorate a national event by lighting sequential beacons across hill summits or roof tops. To guarantee a successful event, ensuring an unobstructed line of sight between neighboring beacons would allow each beacon to be activated as intended.
 
 ## How to use the sample
 
-Click to turn on the mouse move event listener. Then move the mouse where you want the target location to be. Click again to lock the target location.
+The sample loads with a preset observer and target location, linked by a colored line. A red segment on the line means the view between observer and target is obstructed, whereas green means the view is unobstructed. 
 
-![](LineOfSightLocation.gif)
+Click to turn on the mouse move event listener, then move the mouse to update the target location in real time. Click again to lock the target location.
 
 ## How it works
 
-To create a line of sight and update it with the mouse:
-
 1. Create an `AnalysisOverlay` and add it to the scene view.
 2. Create a `LocationLineOfSight` with initial observer and target locations and add it to the analysis overlay.
 3. Make an `EventHandler<MouseEvent>` to capture mouse movement. Turn the screen point into a scene point with `sceneView.screenToLocationAsync(screenPoint)`.
 4. Update the target location with `lineOfSight.setTargetLocation(scenePoint)`.
 
 ## Relevant API
 
-* 3D
 * AnalysisOverlay
-* ArcGISTiledElevationSource
-* ArcGISScene
-* Camera
 * LocationLineOfSight
 * SceneView
+
+## Tags
+
+3D, line of sight, visibility, visibility analysis

analysis/viewshed-camera/README.md

@@ -1,30 +1,37 @@
-# Viewshed Camera
+# Viewshed camera
 
-Create a viewshed using the current camera viewpoint.
+Analyze the viewshed for a camera. A viewshed shows the visible and obstructed areas from an observer's vantage point. 
 
-A viewshed shows the visible and obstructed areas from an observer's vantage point.
+![Image of viewshed for camera](ViewshedCamera.png)
 
-## How to use the sample
+## Use case
 
-The sample will start with a viewshed created from the initial camera location, so only the visible (green) portion of the viewshed will be visible. Move around the scene to see the obstructed (red) portion. Click the Update from Camera button to update the viewshed to the current camera position.
+A viewshed analysis is a type of visual analysis you can perform on a scene. The viewshed aims to answer the question 'What can I see from a given location?'. The output is an overlay with two different colors - one representing the visible areas (green) and the other representing the obstructed areas (red).
 
-![](ViewshedCamera.gif)
+## How to use the sample
 
-## How it works
+The sample will start with a viewshed created from the initial camera location, so only the visible (green) portion of the viewshed will be visible. Move around the scene to see the obstructed (red) portions. Click the 'Update from Camera' button to update the viewshed to the current camera position.
 
-To create and update a viewshed from a camera:
+## How it works
 
-1. Get a `Camera` either by creating it, or by getting the current camera from the scene with `sceneView.getCurrentViewpointCamera()`.
-2. Create a `LocationViewshed` passing in the `Camera` plus a min/max distance.
-3. To update the viewshed with a new camera, use `viewshed.updateFromCamera(camera)`
+1. Get the current camera from the scene with `SceneView.getCurrentViewpointCamera()`.
+2. Create a `LocationViewshed`, passing in the `Camera` and a min/max distance.
+3. Update the viewshed from a camera.
 
 ## Relevant API
 
-* 3D
 * AnalysisOverlay
-* ArcGISTiledElevationSource
 * ArcGISScene
 * ArcGISSceneLayer
+* ArcGISTiledElevationSource
 * Camera
 * LocationViewshed
 * SceneView
+
+## About the data
+
+The scene shows a [buildings layer in Brest, France](https://tiles.arcgis.com/tiles/P3ePLMYs2RVChkJx/arcgis/rest/services/Buildings_Brest/SceneServer/layers/0) with a [local elevation source image service](https://scene.arcgis.com/arcgis/rest/services/BREST_DTM_1M/ImageServer) both hosted on ArcGIS Online.
+
+## Tags
+
+3D, Scene, viewshed, visibility analysis

analysis/viewshed-geoelement/README.md

@@ -1,29 +1,39 @@
-# Viewshed GeoElement
+# Viewshed geoelement
 
-Attach a viewshed to an object to visualize what it sees.
+Analyze the viewshed for an object (GeoElement) in a scene.
 
-![](ViewshedGeoElement.gif)
+![Image of viewshed for geoelement](ViewshedGeoElement.png)
+
+## Use case
+
+A viewshed analysis is a type of visual analysis you can perform on a scene. The viewshed aims to answer the question 'What can I see from a given location?'. The output is an overlay with two different colors - one representing the visible areas (green) and the other representing the obstructed areas (red).
 
 ## How to use the sample
 
-Once the scene is done loading, click on a location for the tank to drive to. It will automatically turn and drive straight towards the clicked point. The viewshed will automatically move and rotate with the tank.
+Click to set a destination for the vehicle (a GeoElement). The vehicle will 'drive' towards the clicked location. The viewshed analysis will update as the vehicle moves.
 
 ## How it works
 
-To attach a viewshed to a `GeoElement`:
+1. Create and show the scene, with an elevation source and a buildings layer.
+2. Add a model (the `GeoElement`) to represent the observer (in this case, a tank).
+    * Use a `SimpleRenderer` which has a heading expression set in the `GraphicsOverlay`. This way you can relate the viewshed's heading to the `GeoElement` object's heading.
+3. Create a `GeoElementViewshed` with configuration for the viewshed analysis.
+4. Add the viewshed to an `AnalysisOverlay` and add the overlay to the scene.
+5. Configure the SceneView `OrbitGeoElementCameraController` to orbit the vehicle.
+
+## About the data
 
-1. Create a `Graphic` and add it to a `GraphicsOverlay`.
-2. Use a `SimpleRenderer` in the `GraphicsOverlay` which has a heading expression set. This way you can relate the viewshed's heading to the `GeoElement`'s heading.
-3. Create a `GeoElementViewshed` with the graphic, heading/pitch offsets, and min/max distance.
-4. To offset the viewshed's observer location from the center of the graphic, use `viewshed.setOffsetX()`, etc.
+This sample shows a [Johannesburg, South Africa Scene](https://www.arcgis.com/home/item.html?id=eb4dab9e61b24fe2919a0e6f7905321e) from ArcGIS Online. The sample uses a [Tank model scene symbol](http://www.arcgis.com/home/item.html?id=07d62a792ab6496d9b772a24efea45d0) hosted as an item on ArcGIS Online.
 
 ## Relevant API
 
-* 3D
 * AnalysisOverlay
-* ArcGISTiledElevationSource
-* ArcGISScene
-* ArcGISSceneLayer
+* GeodeticDistanceResult
 * GeoElementViewshed
-* Graphic
-* SceneView
+* GeometryEngine.distanceGeodetic (used to animate the vehicle)
+* ModelSceneSymbol
+* OrbitGeoElementCameraController
+
+## Tags
+
+3D, analysis, buildings, model, scene, viewshed, visibility analysis

analysis/viewshed-geoprocessing/README.md

@@ -1,24 +1,26 @@
-# Viewshed Geoprocessing
+# Viewshed geoprocessing
 
-Calculate a viewshed against terrain using a geoprocessing service.
+Calculate a viewshed using a geoprocessing service, in this case showing what parts of a landscape are visible from points on mountainous terrain.
 
-![](ViewshedGeoprocessing.png)
+![Image of viewshed geoprocessing](ViewshedGeoprocessing.png)
+
+## Use case
+
+A viewshed is used to highlight what is visible from a given point. A viewshed could be created to show what a hiker might be able to see from a given point at the top of a mountain. Equally, a viewshed could also be created from a point representing the maximum height of a proposed wind turbine to see from what areas the turbine would be visible. 
 
 ## How to use the sample
 
-After the geoprocessing task finishes loading (the spinner will stop), click anywhere on the map to generate a viewshed at that location. A viewshed will be calculated using the service's default distance of 15km.
+Click the map to see all areas visible from that point within a 15km radius. Clicking on an elevated area will highlight a larger part of the surrounding landscape. It may take a few seconds for the task to run and send back the results.
 
 ## How it works
 
-To create a viewshed from a geoprocessing service:
-
-1. Create a `GeoprocessingTask` with the URL set to the viewshed endpoint of a geoprocessing service .
-2. Create a `FeatureCollectionTable` and add a new `Feature` whose geometry is the `Point` where you want to create the viewshed.
-3. Make `GeoprocessingParameters` with an input for the viewshed operation `parameters.getInputs().put("Input_Observation_Point", new GeoprocessingFeatures(featureCollectionTable))`.
-4. Use the `GeoprocessingTask` to create a `GeoprocessingJob` with the parameters.
-5. Start the job and wait for it to complete and return a `GeoprocessingResult`.
-6. Get the resulting `GeoprocessingFeatures` using `geoprocessingResult.getOutputs().get("Viewshed_Result")`.
-7. Iterate through the viewshed features in `geoprocessingFeatures.getFeatures()` to use their geometry or display the geometry in a graphic.
+1. Create a `GeoprocessingTask` object with the URL set to a geoprocessing service endpoint.
+2. Create a `FeatureCollectionTable` object and add a new `Feature` object whose geometry is the viewshed's observer `Point`.
+3. Make a `GeoprocessingParameters` object passing in the observer point.
+4. Use the geoprocessing task to create a `GeoprocessingJob` object with the parameters.
+5. Start the job and wait for it to complete and return a `GeoprocessingResult` object.
+6. Get the resulting `GeoprocessingFeatures` object.
+7. Iterate through the viewshed features to use their geometry or display the geometry in a new `Graphic` object.
 
 ## Relevant API
 
@@ -27,4 +29,8 @@ To create a viewshed from a geoprocessing service:
 * GeoprocessingJob
 * GeoprocessingParameters
 * GeoprocessingResult
-* GeoprocessingTask
+* GeoprocessingTask
+
+## Tags
+
+geoprocessing, heat map, heatmap, viewshed