ShadowCastAnalysis | References | ArcGIS Maps SDK for JavaScript

import ShadowCastAnalysis from "@arcgis/core/analysis/ShadowCastAnalysis.js";

const ShadowCastAnalysis = await $arcgis.import("@arcgis/core/analysis/ShadowCastAnalysis.js");

Inheritance: ShadowCastAnalysis→Analysis→Accessor

Since: ArcGIS Maps SDK for JavaScript 5.0

The ShadowCastAnalysis visualizes shadows cast by 3D features or sunlight exposure in a SceneView. This type of analysis is helpful in urban development, where projects may need to satisfy shadow or sunlight exposure requirements for a selected day and time range.

By default, the analysis visualizes shadows. When visualizeSunlight is true, it visualizes sunlight exposure instead.

The date, startTimeOfDay, endTimeOfDay, and utcOffset properties define the date, time range, and UTC offset used to compute the analysis overlay. They do not change the lighting in the scene. To control scene lighting, use SunLighting or the Daylight component.

The utcOffset property determines which timezone the selected date and time range are interpreted in for the analysis. This differs from the Daylight component, where selecting a timezone updates the environment lighting's date and time according to the camera position.

When set, the geometry property limits the visualization to a polygonal project area, such as a parcel, park, or courtyard. If no geometry is provided, the analysis applies to the entire scene. For total-duration and discrete visualizations, the TotalDurationOptions.colorStops or DiscreteOptions.colorStops properties define a custom color ramp. In total-duration mode, stops define duration values. In discrete mode, stops define sample-count values. If color stops are not provided, the visualization uses a default transparent-to-color ramp.

The mode property controls how shadow or sunlight exposure is visualized:

Mode	Use for	Details
`min-duration`	Highlighting areas that meet or exceed a minimum shadow or sunlight duration.	The threshold is defined by MinDurationOptions.minDuration.
`total-duration`	Showing cumulative shadow or sunlight duration across the analysis area.	Supports continuous visualization or 1-hour intervals. In hourly mode, each bucket uses the color at the end of the represented hour. Without color stops, areas with no duration remain transparent, intermediate values are interpolated, and the highest duration uses the opacity from TotalDurationOptions.color.
`discrete`	Displaying individual shadow or sunlight samples at regular intervals.	The interval is defined by DiscreteOptions.interval. For example, a one-hour range with a 30-minute interval displays samples at the start, middle, and end of the range.

By default, the analysis also displays a tooltip next to the pointer. In continuous total-duration and min-duration modes, the tooltip reports the total duration at that location, rounded to 15-minute increments. In hourly total-duration mode, the tooltip reports the hourly range represented by the displayed bucket. In discrete mode, the tooltip reports the duration at that location. The tooltip reports shadow duration by default and sunlight duration when visualizeSunlight is true.

To perform a shadow cast analysis in your WebScene:

Create a new instance of ShadowCastAnalysis.
Set the desired mode.
Configure the analysis time range using the date, startTimeOfDay, and endTimeOfDay properties.
Optionally set visualizeSunlight to visualize sunlight duration instead of shadow duration.
Optionally set geometry to limit the analysis to a polygonal project area.
Optionally set the utcOffset property to define the timezone used for the analysis.
If using the discrete mode, optionally set custom properties with DiscreteOptions.
If using the min-duration mode, optionally set custom properties with MinDurationOptions.
If using the total-duration mode, optionally set custom properties with TotalDurationOptions.
Add the ShadowCastAnalysis instance to SceneView.analyses.

const projectArea = new Polygon({
  rings: [
    [
      [-122.421, 37.781],
      [-122.42, 37.781],
      [-122.42, 37.782],
      // ...
    ]
  ]
});

const analysis = new ShadowCastAnalysis({
  date: new Date("March 1, 2026"),
  startTimeOfDay: 10 * 3600 * 1000, // 10AM
  endTimeOfDay: 16 * 3600 * 1000, // 4PM
  mode: "total-duration",
  visualizeSunlight: true,
  geometry: projectArea,
  totalDurationOptions: {
    mode: "continuous",
    colorStops: [
      // Map sunlight duration to colors. Values are in milliseconds.
      { value: 0, color: [255, 255, 255, 0] },
      { value: 2 * 3600 * 1000, color: [255, 198, 87, 0.5] },
      { value: 4 * 3600 * 1000, color: [84, 176, 74, 0.85] }
    ]
  },
  utcOffset: -8 // Pacific Standard Time
});

view.analyses.add(analysis);

Use the ShadowCastAnalysisView3D class and its ShadowCastAnalysisView3D.getDurationAtScreen() method to obtain the shadow or sunlight duration at a specific screen location programmatically. To disable the shadow or sunlight tooltip next to the pointer set the ShadowCastAnalysisView3D.interactive property to false.

// use getDurationAtScreen method from the analysis view once available
const analysisView = await view.whenAnalysisView(analysis);

view.on("pointer-move", async (event) => {
  // duration is the sunlight duration in milliseconds because visualizeSunlight is true.
  // A negative duration means the pointer is outside the project area.
  const duration = await analysisView.getDurationAtScreen({ x: event.x, y: event.y });
  // ... do something with the duration
});

Known Limitations

Terrain does not cast shadows in this analysis.
As a result, shadow duration may be underestimated and sunlight duration may be overestimated in areas where terrain would normally block sunlight. To avoid incorrect visualization, startTimeOfDay should be set after local sunrise and endTimeOfDay before local sunset.
The analysis does not take daylight savings into account. Use the timezone dropdown to adjust the offset from the Coordinated Universal Time (UTC) and account for the daylight saving time.
The timezone is automatically detected based on the camera location. In some situations this might not be accurate. In case of an inaccurate timezone, users can set it manually using the utcOffset.

See also

Constructors

Constructor

Parameters

Parameter	Type	Description	Required
properties	ShadowCastAnalysisProperties

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
date	Date
declaredClass readonly inherited	string	Accessor
discreteOptions	DiscreteOptions
endTimeOfDay	number
geometry	Polygon \| null \| undefined
id readonly inherited	string	Analysis
minDurationOptions	MinDurationOptions
mode	ShadowCastMode
origin inherited	AnalysisOriginWebScene \| null \| undefined	Analysis
startTimeOfDay	number
totalDurationOptions	TotalDurationOptions
type readonly	"shadow-cast"
uid readonly inherited	string	IdentifiableMixin
utcOffset	number \| null \| undefined
valid readonly	boolean
visualizeSunlight	boolean

date

autocast Property

Type: Date

The calendar date used to calculate the shadow cast. This date excludes the time. If a date with a time is set, the time value will be set to midnight (00:00:00) of that date in local system time. If no date is set, then it defaults to the current date in local system time.

declaredClass

readonlyinherited Property

Type: string

Inherited from: Accessor

Since: ArcGIS Maps SDK for JavaScript 4.7

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

discreteOptions

autocast Property

Type: DiscreteOptions

Options specific to the discrete mode.

endTimeOfDay

Property

Type: number

Time (in milliseconds from midnight of the date) when the shadow cast computation should stop. By default the shadow cast end time is set to 4PM (16 * 3600 * 1000ms).

Default value: 57_600_000

geometry

autocast Property

Type: Polygon | null | undefined

Since: ArcGIS Maps SDK for JavaScript 5.1

Polygonal area inside which to apply the shadow cast analysis. Use this property to limit the visualization to a project area, such as a parcel, park, or courtyard. If not set, the analysis applies to the entire scene.

id

readonlyinherited Property

Type: string

Inherited from: Analysis

A user settable identifier for the analysis. A unique value is automatically generated when the analysis is created if it is not set explicitly during construction.

minDurationOptions

autocast Property

Type: MinDurationOptions

Options specific to the min-duration mode.

mode

Property

Type: ShadowCastMode

Mode of analysis to use when computing and displaying shadows or sunlight.

"discrete": Displays individual shadow or sunlight snapshots at regular time intervals within the selected time range.
"min-duration": Displays areas where accumulated shadow or sunlight exceeds a user-defined minimum duration within the selected time range. Optional discrete shadow overlays can provide additional context when visualizing shadows.
"total-duration": Displays total shadow or sunlight accumulation within the selected time range. Supports continuous or 1-hour aggregated modes, where hourly buckets use the color at the end of the represented hour.

When visualizeSunlight is true, the selected mode displays sunlight duration instead of shadow duration.

Default value: "min-duration"

origin

autocast inherited Property

Type: AnalysisOriginWebScene | null | undefined

Inherited from: Analysis

The origin of the analysis. The origin can be of type web-scene when the analysis was applied from the WebScene.initialViewProperties or a Slide.

startTimeOfDay

Property

Type: number

Time (in milliseconds from midnight of the date) when the shadow cast computation should start. By default the shadow cast start time is set to 10AM (10 * 3600 * 1000ms).

Default value: 36_000_000

totalDurationOptions

autocast Property

Type: TotalDurationOptions

Options specific to the total-duration mode.

type

readonly Property

Type: "shadow-cast"

The analysis type.

uid

readonlyinherited Property

Type: string

Inherited from: IdentifiableMixin

Since: ArcGIS Maps SDK for JavaScript 4.33

An automatically generated unique identifier assigned to the instance. The unique id is generated each time the application is loaded.

utcOffset

Property

Type: number | null | undefined

The UTC offset in hours (e.g., -8 for PST, 1 for CET). This value determines how the date, startTimeOfDay, and endTimeOfDay properties are interpreted when computing the shadow cast analysis.

If not specified, the analysis will automatically determine an approximate UTC offset based on the longitude of the view's camera position.

Known Limitations

Full support for time zones with daylight saving time is not yet supported.

valid

readonly Property

Type: boolean

Indicates whether the analysis is ready to be computed and interacted with in the view.

visualizeSunlight

Property

Type: boolean

Since: ArcGIS Maps SDK for JavaScript 5.1

When true, the analysis visualizes sunlight duration instead of shadow duration. This applies to all modes, their respective options, and the duration reported by ShadowCastAnalysisView3D.getDurationAtScreen().

Default value: false

Methods

Method	Signature	Class
fromJSON inherited static	fromJSON(json: any): any	JSONSupportMixin
clone inherited	clone(): this	ClonableMixin
equals inherited	equals(other: this): boolean	Analysis
toJSON inherited	toJSON(): any	JSONSupportMixin

fromJSON

inheritedstatic Method

Signature: fromJSON (json: any): any

Inherited from: JSONSupportMixin

Creates a new instance of this class and initializes it with values from a JSON object generated from an ArcGIS product. The object passed into the input json parameter often comes from a response to a query operation in the REST API or a toJSON() method from another ArcGIS product. See the Using fromJSON() topic in the Guide for details and examples of when and how to use this function.

Parameters

Parameter	Type	Description	Required
json	any	A JSON representation of the instance in the ArcGIS format. See the ArcGIS REST API documentation for examples of the structure of various input JSON objects.

Returns: any
Returns a new instance of this class.

clone

inherited Method

Signature: clone (): this

Inherited from: ClonableMixin

Creates a deep clone of this object. Any properties that store values by reference will be assigned copies of the referenced values on the cloned instance.

Returns: this
A deep clone of the class instance that invoked this method.

equals

inherited Method

Signature: equals (other: this): boolean

Inherited from: Analysis

Compares this analysis with another analysis to determine whether they are equivalent.

Parameters

Parameter	Type	Description	Required
other	this	The other analysis to compare against.

Returns: boolean
true if the analyses are equivalent and false otherwise.

toJSON

inherited Method

Signature: toJSON (): any

Inherited from: JSONSupportMixin

Converts an instance of this class to its ArcGIS portal JSON representation. See the Using fromJSON() guide topic for more information.

Returns: any
The ArcGIS portal JSON representation of an instance of this class.