Introduction to analyses

In the ArcGIS Maps SDK for JavaScript ArcGIS Maps SDK for JavaScript, previously known as ArcGIS API for JavaScript, is a developer product for building mapping and spatial analysis applications for the web. Learn more , analyses provide interactive tools for exploring, measuring, and understanding spatial relationships and real-world phenomena in 2D maps and 3D scenes.

Below is a list of analyses available in the SDK.

Analysis objects, analysis views, and analysis layers

Analysis objects are classes that you create and manage in code to build precise interactive measurements, visibility studies, profiles, and other spatial workflows. You typically add them to the analyses collection of a Map or the analyses collection of a Scene, and for some 3D workflows you can also manage them as analysis layers.

const mapComponent = document.querySelector("arcgis-map");
const analysis = new ElevationProfileAnalysis({
  geometry: {
    type: "polyline",
    spatialReference: { wkid: 4326 },
    paths: [[[-122.68, 45.53], [-122.58, 45.55], [-122.48, 45.5]]],
  },
});

mapComponent.analyses.add(analysis);

An analysis view is the view-specific representation of that object. Obtain it from the map or scene when you need interactive placement, editing, or access to the results of the analysis.

const analysisView = await mapComponent.whenAnalysisView(analysis);

Some analyses can be driven directly by input geometry, while others are configured through observer, target, time, direction, field-of-view, or other analysis-specific properties. For example, AreaMeasurementAnalysis uses a polygon, ElevationProfileAnalysis uses a line or feature, and VolumeMeasurementAnalysis uses a polygon area on supported surfaces.

When you need the workflow to persist in a WebScene, appear in a layer list, or behave like other scene content, some analysis workflows can be managed as layers in a 3D scene.

• ViewshedLayer stores a ViewshedAnalysis in its source.
• DimensionLayer stores a DimensionAnalysis in its source.
• LineOfSightLayer stores a LineOfSightAnalysis in its analysis.

This lets you move supported workflows between the scene’s analyses collection and layer-based management as your application’s needs change.

The analysis lifecycle

Most analysis workflows follow the same pattern:

1. Create an analysis object.
2. Add it to the map or scene.
3. Obtain the corresponding analysis view.
4. Optionally place or edit it interactively.
5. Update its properties or clear it when the workflow changes.

The following code creates a ViewshedAnalysis, creates a Viewshed, adds the viewshed to the analysis, and then adds the analysis to the scene component.

const sceneComponent = document.querySelector("arcgis-scene");
const analysis = new ViewshedAnalysis();
const viewshed = new Viewshed({
  observer: {
    spatialReference: SpatialReference.WebMercator,
    x: -9754426,
    y: 5143111,
    z: 330,
  },
  farDistance: 900,
  tilt: 84,
  heading: 63,
  horizontalFieldOfView: 85,
  verticalFieldOfView: 60,
});

analysis.viewsheds.add(viewshed);

sceneComponent.analyses.add(analysis);

Analysis views support interactive placement with the place() method, which starts an interactive placement workflow for the current analysis view. Use this when you want to build your own toolbar, guided workflow, or analysis-specific UI.

const analysisView = await sceneComponent.whenAnalysisView(analysis);
const abortController = new AbortController();

try {
  await analysisView.place({ signal: abortController.signal });
} catch (error) {
  if (error.name !== "AbortError") {
    throw error;
  }
}

This method is not yet supported for ShadowCastAnalysisView3D.

Because analyses expose properties and collections, they can be updated directly in response to user input or other events, and reset when needed with clear().

selectedViewshed.horizontalFieldOfView = 90;
selectedViewshed.verticalFieldOfView = 60;

if (resetAnalysis) {
  analysis.clear();
}

This method is not yet supported for ShadowCastAnalysis.

Analyses, geometry operators, and spatial analysis

Now that you have seen what analyses do in the SDK, it is useful to distinguish them from geometry operators and spatial analysis, which solve different kinds of problems.

Use geometry operators when you need a direct client-side calculation on one or more geometries and want the returned value immediately, without creating an analysis that remains in the view.

Use spatial analysis when you are looking for analytical workflows based on operators, calculations, or analysis services rather than classes that are managed directly in the map or scene.

Related tutorials and samples

Learn more about the analysis lifecycle in the Create and manage a viewshed analysis tutorial, or see the full set of analysis samples.