ElevationProfile | References | ArcGIS Maps SDK for JavaScript

import ElevationProfile from "@arcgis/core/widgets/ElevationProfile.js";

Inheritance:: ElevationProfile→Widget→Accessor

Since: ArcGIS Maps SDK for JavaScript 4.18

The ElevationProfile widget is used to generate and display an elevation profile from an input line graphic. The input graphic can be set interactively by drawing a single or multi-segment line or by selecting a line feature in the view. Alternatively, the widget allows setting an input graphic programmatically at creation or runtime by setting the input property.

ElevationProfile widget used in a city scene, displaying ground and building profiles. See Sample - ElevationProfile widget

The widget can visualize multiple profile lines, depending on the environment (2D versus 3D) and elevation source data:

ElevationProfileLineGround can be used in both MapView and SceneView. In this case, the elevation is sampled directly from Map.ground. Whether your map is displayed in 2D or 3D, the ground property needs to be set on the map.
ElevationProfileLineInput samples elevation data from the geometry of the input graphic. It is typically used with input line data that has z values. If the input line data doesn't have z values, a profile line is computed if the line is displayed with a non-draped elevation mode. An elevation offset can also be applied. Currently, in 2D, z values are not fetched from feature-based layers, so in a MapView, this profile line can only be used with client-side graphics that have z values.
ElevationProfileLineQuery samples elevation data from the elevation source set in the ElevationProfileLineQuery.source property. The elevation source can be an ElevationLayer or any object with a method called queryElevation that has the same signature as ElevationLayer.queryElevation().
ElevationProfileLineView is available only in a SceneView and it displays the elevation sampled directly from the view along the input graphic. All volumetric objects in a SceneView contribute to the resulting profile.

You can choose to display one or several profile lines in the chart, by setting them in the profiles property.

Once all profiles are refined to their maximum resolution, the corresponding 3D profile lines appear in the SceneView (currently no lines are displayed in a MapView), and profile statistics display in the legend for each profile line. Hovering over the chart shows an overlaid tooltip with elevation values of all profiles, and displays colored dot markers in the 3D view at the matching positions.

Checkboxes in the legend allow hiding individual profiles. Chart units can be set via the settings menu to metric, imperial or a specific unit.

Scrolling the chart zooms in to a specific part of the profile chart. When zoomed in, click the minus button to reset the zoom. On touch devices, pinch to zoom in and out.

Drawing a path to get a ground profile.

Profile generated from a line feature with z-values shows a paraglide track above ground.

How distance values are computed depends on the map's spatial reference:

In geographic coordinate systems (GCS) and in Web Mercator, distances are computed geodetically.
In projected coordinate systems (PCS), apart from Web Mercator, distances are computed in a Euclidean manner (in their respective PCS).

Known Limitations

In 3D, ElevationProfileLineInput does not take into consideration the featureExpression set on the elevation mode of the layer. In 2D, z values are not fetched from feature based layers. Therefore, ElevationProfileLineInput can only be used with client-side graphics that have z values in a MapView.

See also

Sample - ElevationProfile widget
ElevationProfileViewModel - Deprecated since 5.0. Use the ElevationProfileAnalysis or Elevation Profile component instead.
ElevationProfileLineGround - Deprecated since 5.0. Use ElevationProfileLineGround from ElevationProfileAnalysis instead.
ElevationProfileLineInput - Deprecated since 5.0. Use ElevationProfileLineInput from ElevationProfileAnalysis instead.
ElevationProfileLineQuery - Deprecated since 5.0. Use ElevationProfileLineQuery from ElevationProfileAnalysis instead.
ElevationProfileLineView - Deprecated since 5.0. Use ElevationProfileLineScene from ElevationProfileAnalysis instead.

Examples

const elevationProfile = new ElevationProfile({ view });
// adds the ElevationProfile to the top right corner of the view
view.ui.add(elevationProfile, "top-right");

// elevation profile with all the line profiles
const elevationProfile = new ElevationProfile({
  view,
  profiles: [{
    // displays elevation values from Map.ground
    type: "ground", //autocasts as new ElevationProfileLineGround()
    color: "#61d4a4",
    title: "Ground elevation"
  }, {
    // displays elevation values from the input line graphic
    type: "input", //autocasts as new ElevationProfileLineInput()
    color: "#f57e42",
    title: "Line elevation"
  }, {
    // displays elevation values from a SceneView
    type: "view", //autocasts as new ElevationProfileLineView()
    color: "#8f61d4",
    title: "View elevation"
    // by default ground and all layers are used to compute elevation, but
    // you can define which elements should be included/excluded from the computation
    exclude: [map.ground]
  }, {
    // displays elevation values from a custom source
    type: "query",
    source: new ElevationLayer({
      url: "https://elevation3d.arcgis.com/arcgis/rest/../Terrain3D/ImageServer"
    }),
    color: "#d46189",
    title: "Custom elevation"
  }]
});
view.ui.add(elevationProfile, "bottom-right");

// Line whose elevation profile is to be generated.
const inputLine = new Graphic({
  geometry: new Polyline({
    spatialReference: SpatialReference.WebMercator,
    paths: [
      [
        [950857, 6003812], // Zurich, Switzerland
        [924987, 5950271], // Lucerne, Switzerland
      ]
    ],
  }),
});

// Elevation profile for the existing line.
const elevationProfile = new ElevationProfile({
  view,
  input: inputLine,
  // Don't let the user draw or select a new line because we provide one programmatically.
  visibleElements: {
    sketchButton: false,
    selectButton: false
  }
});
view.ui.add(elevationProfile, "bottom-right");

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	`ElevationProfileProperties`

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.

Property	Type	Class
`container` inherited	`HTMLElement \| null \| undefined`	Widget
`declaredClass` readonly inherited	`string`	Accessor
`destroyed` readonly inherited	`boolean`	Widget
`icon`	`Icon["icon"]`
`id` inherited	`string`	Widget
`input`	`Graphic \| null \| undefined`
`label`	`string`
`profiles`	`Collection<ElevationProfileLineUnion>`
`unit`	`SystemOrLengthUnit`
`unitOptions`	`SystemOrLengthUnit[]`
`view`	`MapViewOrSceneView \| null \| undefined`
`viewModel`	`ElevationProfileViewModel`
`visible` inherited	`boolean`	Widget
`visibleElements`	`ElevationProfileVisibleElements`

container

autocast inherited Property

Type: HTMLElement | null | undefined

Inherited from: Widget

The ID or node representing the DOM element containing the widget. This property can only be set once. The following examples are all valid use case when working with widgets.

Examples

// Create the HTML div element programmatically at runtime and set to the widget's container
const basemapGallery = new BasemapGallery({
  view: view,
  container: document.createElement("div")
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// Specify an already-defined HTML div element in the widget's container

const basemapGallery = new BasemapGallery({
  view: view,
  container: basemapGalleryDiv
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

// HTML markup
<body>
  <div id="viewDiv"></div>
  <div id="basemapGalleryDiv"></div>
</body>

// Specify the widget while adding to the view's UI
const basemapGallery = new BasemapGallery({
  view: view
});

// Add the widget to the top-right corner of the view
view.ui.add(basemapGallery, {
  position: "top-right"
});

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

destroyed

readonlyinherited Property

Type: boolean

Inherited from: Widget

When true, this property indicates whether the widget has been destroyed.

icon

autocast Property

Type: Icon["icon"]

Since: ArcGIS Maps SDK for JavaScript 4.27

Icon which represents the widget. It is typically used when the widget is controlled by another one (e.g. in the Expand widget).

See also

Default value: "altitude"

id

inherited Property

Type: string

Inherited from: Widget

The unique ID assigned to the widget when the widget is created. If not set by the developer, it will default to the container ID, or if that is not present then it will be automatically generated.

input

autocast Property

Type: Graphic | null | undefined

The input line graphic along which elevation will be queried in order to generate an elevation profile.

Typically not set when creating the widget. In this case the widget starts empty, and waits for the user to either draw a new profile or generate a profile from selecting a line feature. The result of this action populates input. input can be set when constructing the widget, or set or changed at runtime. The input graphic must contain a geometry of type Polyline, symbol and attributes of the input graphic are ignored.

label

autocast Property

Type: string

The widget's default label.

profiles

autocast Property

Type: Collection<ElevationProfileLineUnion>

Collection of elevation profile lines which are to be generated and displayed in the widget's chart. See the different profile line types for details on usage and behavior.

Once an elevation profile is generated, each line will contain the raw data used to generate the chart and profile statistics. The order of the profiles within the collection determines the drawing order on the chart.

In a MapView ElevationProfileLineView is not supported.

Example

const elevationProfile = new ElevationProfile({
  view: view,
  profiles: [{
    // displays elevation values from Map.ground
    type: "ground", //autocasts as new ElevationProfileLineGround()
  }, {
    // displays elevation values from the input line graphic
    type: "input", //autocasts as new ElevationProfileLineInput()
  }, {
    // displays elevation values from an elevation source
    type: "query", //autocasts as new ElevationProfileLineQuery()
    source: elevationLayer
  }, {
    // displays elevation values from a SceneView
    type: "view" //autocasts as new ElevationProfileLineView()
  }]
});

unit

Property

Type: SystemOrLengthUnit

Unit system (imperial, metric) or specific unit used for displaying the elevation and distance values.

unitOptions

Property

Type: SystemOrLengthUnit[]

List of available units and unit systems (imperial, metric) for displaying the elevation and distance values.

view

Property

Type: MapViewOrSceneView | null | undefined

A reference to the SceneView or the MapView.

viewModel

autocast Property

Type: ElevationProfileViewModel

The view model for this widget. This is a class that contains all the logic (properties and methods) that controls this widget's behavior. See the ElevationProfileViewModel class to access all properties and methods on the widget.

visible

inherited Property

Type: boolean

Inherited from: Widget

Indicates whether the widget is visible.

If false, the widget will no longer be rendered in the web document. This may affect the layout of other elements or widgets in the document. For example, if this widget is the first of three widgets associated to the upper right hand corner of the DefaultUI, then the other widgets will reposition when this widget is made invisible. For more information, refer to the css display value of "none".

Default value: true

Example

// Hides the widget in the view
widget.visible = false;

visibleElements

autocast Property

Type: ElevationProfileVisibleElements

This property provides the ability to display or hide the individual elements of the widget.

Example

elevationProfile.visibleElements = {
   legend: true,
   chart: true,
   clearButton: true,
   settingsButton: true,
   sketchButton: true,
   selectButton: true,
   uniformChartScalingToggle: true
}

Methods

Method	Signature	Class
`classes` inherited	`classes(...classNames: ((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]): string`	Widget
`destroy` inherited	`destroy(): void`	Widget
`emit` inherited	`emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean`	EventedMixin
`hasEventListener` inherited	`hasEventListener<Type extends EventNames<this>>(type: Type): boolean`	EventedMixin
`isFulfilled` inherited	`isFulfilled(): boolean`	EsriPromiseMixin
`isRejected` inherited	`isRejected(): boolean`	EsriPromiseMixin
`isResolved` inherited	`isResolved(): boolean`	EsriPromiseMixin
`on` inherited	`on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle`	EventedMixin
`postInitialize` inherited	`postInitialize(): void`	Widget
`render` inherited	`render(): any \| null`	Widget
`renderNow` inherited	`renderNow(): void`	Widget
`scheduleRender` inherited	`scheduleRender(): void`	Widget
`when` inherited	`when<TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> \| null \| undefined, onRejected?: OnRejectedCallback<TResult2> \| null \| undefined): Promise<TResult1 \| TResult2>`	EsriPromiseMixin

classes

inherited Method

Signature: classes (...classNames: ((string | null | undefined) | ((string[] | Record<string, boolean>) | null | undefined) | false | null | undefined)[]): string

Inherited from: Widget

A utility method used for building the value for a widget's class property. This aids in simplifying css class setup.

Parameters

Parameter	Type	Description	Required
classNames	`((string \| null \| undefined) \| ((string[] \| Record<string, boolean>) \| null \| undefined) \| false \| null \| undefined)[]`	The class names.

Returns: string
The computed class name.

Example

// .tsx syntax showing how to set css classes while rendering the widget

render() {
  const dynamicClasses = {
    [css.flip]: this.flip,
    [css.primary]: this.primary
  };

  return (
    <div class={classes(css.root, css.mixin, dynamicClasses)} />
  );
}

destroy

inherited Method

Signature: destroy (): void

Inherited from: Widget

Destroys the widget instance.

Returns: void

emit

inherited Method

Signature: emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.
event	`this["@eventTypes"][Type]`	The event payload.

Returns: boolean
true if a listener was notified

hasEventListener

inherited Method

Signature: hasEventListener <Type extends EventNames<this>>(type: Type): boolean

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameters

Parameter	Type	Description	Required
type	`Type`	The name of the event.

Returns: boolean
Returns true if the class supports the input event.

isFulfilled

inherited Method

Signature: isFulfilled (): boolean

Inherited from: EsriPromiseMixin

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).

isRejected

inherited Method

Signature: isRejected (): boolean

Inherited from: EsriPromiseMixin

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been rejected.

isResolved

inherited Method

Signature: isResolved (): boolean

Inherited from: EsriPromiseMixin

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns: boolean
Indicates whether creating an instance of the class has been resolved.

on

inherited Method

Signature: on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle

Type parameters: <Type extends EventNames<this>>

Inherited from: EventedMixin

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters

Parameter	Type	Description	Required
type	`Type`	An event or an array of events to listen for.
listener	`EventedCallback<this["@eventTypes"][Type]>`	The function to call when the event fires.

Returns

ResourceHandle

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

Property	Type	Description
remove	Function	When called, removes the listener from the event.

Example

view.on("click", function(event){
  // event is the event handle returned after the event fires.
  console.log(event.mapPoint);
});

postInitialize

inherited Method

Signature: postInitialize (): void

Inherited from: Widget

Executes after widget is ready for rendering.

Returns: void

render

inherited Method

Signature: render (): any | null

Inherited from: Widget

This method is implemented by subclasses for rendering.

Returns: any | null
The rendered virtual node.

renderNow

inherited Method

Signature: renderNow (): void

Inherited from: Widget

Renders widget to the DOM immediately.

Returns: void

scheduleRender

inherited Method

Signature: scheduleRender (): void

Inherited from: Widget

Schedules widget rendering. This method is useful for changes affecting the UI.

Returns: void

when

inherited Method

Signature: when <TResult1 = this, TResult2 = never>(onFulfilled?: OnFulfilledCallback<this, TResult1> | null | undefined, onRejected?: OnRejectedCallback<TResult2> | null | undefined): Promise<TResult1 | TResult2>

Type parameters: <TResult1 = this, TResult2 = never>

Inherited from: EsriPromiseMixin

when() may be leveraged once an instance of the class is created. This method takes two input parameters: an onFulfilled function and an onRejected function. The onFulfilled executes when the instance of the class loads. The onRejected executes if the instance of the class fails to load.

Parameters

Parameter	Type	Description	Required
onFulfilled	`OnFulfilledCallback<this, TResult1> \| null \| undefined`	The function to call when the promise resolves.
onRejected	`OnRejectedCallback \| null \| undefined`	The function to execute when the promise fails.

Returns: Promise<TResult1 | TResult2>
Returns a new promise for the result of onFulfilled that may be used to chain additional functions.

Example

// Although this example uses MapView, any class instance that is a promise may use when() in the same way
let view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});