@arcgis/map-components
Version:
ArcGIS Map Components
568 lines (567 loc) • 28 kB
TypeScript
/// <reference path="../../index.d.ts" />
import type ShadowCastAnalysis from "@arcgis/core/analysis/ShadowCastAnalysis.js";
import type SceneView from "@arcgis/core/views/SceneView.js";
import type Color from "@arcgis/core/Color.js";
import type { PublicLitElement as LitElement } from "@arcgis/lumina";
import type { ArcgisReferenceElement, HeadingLevel } from "../types.js";
import type { ShadowCastMode, ShadowCastTotalDurationMode } from "@arcgis/core/analysis/ShadowCast/types.js";
import type { ScreenPoint } from "@arcgis/core/core/types.js";
import type { T9nMeta } from "@arcgis/lumina/controllers";
import type { Icon as Icon } from "@esri/calcite-components/components/calcite-icon";
/**
* The Shadow Cast component visualizes shadows cast by 3D features or sunlight exposure in an
* [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/). This is helpful in urban development, where projects may need to satisfy shadow or
* sunlight exposure requirements for a selected day and time range.
*
* [](https://developers.arcgis.com/javascript/latest/sample-code/shadow-cast/)
*
* By default, the component visualizes shadows. When [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#visualizeSunlight) is `true`,
* it visualizes sunlight exposure instead.
*
* The component provides controls for the date, time range, timezone, visualization mode, colors, intervals, and whether
* to visualize shadows or sunlight.
*
* The [date](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#date), [startTimeOfDay](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#startTimeOfDay),
* [endTimeOfDay](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#endTimeOfDay), and [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#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 the [arcgis-daylight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-daylight/) component.
*
* The [utcOffset](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#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
* [arcgis-scene.environment](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#environment) date and time according to the camera position.
*
* The [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#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 [minDuration](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDuration). |
* | `total-duration` | Showing cumulative shadow or sunlight duration across the analysis area. | Supports continuous visualization or 1-hour intervals. Areas with no duration remain transparent, intermediate values are interpolated, and the highest duration uses the opacity from [totalDurationColor](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#totalDurationColor). |
* | `discrete` | Displaying individual shadow or sunlight samples at regular intervals. | The interval is defined by [discreteInterval](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#discreteInterval). For example, a one-hour range with a 30-minute interval displays samples at the start, middle, and end of the range. |
*
* Hovering over the scene displays a tooltip showing the shadow or sunlight duration at that location, rounded to
* 15-minute intervals. To disable this tooltip, set
* [hideShadowDurationTooltip](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#hideShadowDurationTooltip) to `true`.
*
* **Known limitations**
*
* * Shadow Cast is only supported in a 3D [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/) component.
* * 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 picker to adjust the offset from the
* Coordinated Universal Time (UTC) and account for daylight saving time.
* * The timezone is automatically detected by the component 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 timezone picker.
*
* **See also**
*
* - [Sample - Shadow Cast component](https://developers.arcgis.com/javascript/latest/sample-code/shadow-cast/)
* - [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/)
*
* @since 4.28
*/
export abstract class ArcgisShadowCast extends LitElement {
/**
* The [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/)
* created or modified by the component.
*
* When connecting the Shadow Cast component to the [arcgis-scene](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/)
* component, it automatically creates an empty analysis and adds it to the [arcgis-scene.analyses](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-scene/#analyses)
* collection.
* You can then wait for the [ShadowCastAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/)
* to be created before accessing the analysis results.
*
* ```js
* // Get the Scene component and the Shadow Cast component, and wait until both are ready.
* const viewElement = document.querySelector("arcgis-scene");
* await viewElement.viewOnReady();
* const shadowCastElement = document.querySelector("arcgis-shadow-cast");
* await shadowCastElement.componentOnReady();
*
* // Get the ShadowCastAnalysis created by the Shadow Cast component.
* const analysis = shadowCastElement.analysis;
*
* // Get the ShadowCastAnalysisView3D.
* const analysisView = await viewElement.whenAnalysisView(analysis);
*
* // Click in the Scene and get the shadow or sunlight duration at that specific point.
* viewElement.addEventListener("arcgisViewClick", async (event) => {
* const screenPoint = { x: event.detail.x, y: event.detail.y };
* const duration = await analysisView.getDurationAtScreen(screenPoint);
* console.log("Duration (milliseconds):", duration);
* });
* ```
* Whenever the component is destroyed, the analysis is automatically removed from the collection.
* Use this property to configure analysis options that are not exposed by the component UI. For example, the component
* does not provide UI controls for setting a polygonal analysis area or custom color stops; configure those directly
* on the analysis.
*
* Alternatively, a programmatically created [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/)
* can be provided to the component.
* Then, the application itself needs to add it to and later remove it from the analyses collection of the Scene component.
*
* ```js
* // Create the ShadowCastAnalysis.
* const analysis = new ShadowCastAnalysis();
*
* // Get the Scene component and the Shadow Cast component, and wait until both are ready.
* const viewElement = document.querySelector("arcgis-scene");
* await viewElement.viewOnReady();
* const shadowCastElement = document.querySelector("arcgis-shadow-cast");
* await shadowCastElement.componentOnReady();
*
* // Add the analysis to the analyses collection of the Scene component.
* viewElement.analyses.add(analysis);
*
* // Connect the analysis to the shadow cast component.
* shadowCastElement.analysis = analysis;
* ```
*
* @since 5.0
*/
accessor analysis: ShadowCastAnalysis;
/**
* If true, the component will not be destroyed automatically when it is
* disconnected from the document. This is useful when you want to move the
* component to a different place on the page, or temporarily hide it. If this
* is set, make sure to call the [destroy()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#destroy) method when you are done to
* prevent memory leaks.
*
* @default false
*/
accessor autoDestroyDisabled: boolean;
/**
* The calendar date used to calculate the shadow or sunlight visualization. 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.
*
* _See also_
*
* * [Date](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date/Date)
*/
get date(): Date;
set date(value: Date | number | string);
/**
* Color of the visualization in `"discrete"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode). The opacity of the
* visualization is mapped to the number of overlapping shadow or sunlight samples. No duration corresponds to opacity
* 0 and the maximum sample count corresponds to the opacity set in this color value. The component UI exposes a single
* color for this mode.
*
* @since 5.0
*/
accessor discreteColor: Color;
/**
* Individual shadow or sunlight samples are displayed at this time interval in `"discrete"`
* [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode), starting with the start time of day. The interval is expressed in
* milliseconds. If set to 0, the analysis uses the smallest possible interval, up to a maximum of 255 samples.
*
* @since 5.0
*/
accessor discreteInterval: number;
/**
* Time (in milliseconds from midnight of the [date](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#date)) when the shadow or sunlight computation should stop.
*
* [Read more](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#endTimeOfDay)
*/
accessor endTimeOfDay: number;
/**
* Indicates the heading level to use for the component title.
*
* @default 4
*/
accessor headingLevel: HeadingLevel;
/**
* If true, the date picker will be hidden.
*
* @default false
*/
accessor hideDatePicker: boolean;
/**
* If true, the color picker will be hidden in the discrete mode options.
*
* @default false
* @since 5.0
*/
accessor hideDiscreteColorPicker: boolean;
/**
* If true, the interval selector will be hidden in the discrete mode options.
*
* @default false
* @since 5.0
*/
accessor hideDiscreteInterval: boolean;
/**
* If true, the visualization options will be hidden in discrete mode.
*
* @default false
* @since 5.0
*/
accessor hideDiscreteOptions: boolean;
/**
* If true, the color picker will be hidden in the minimum duration mode options.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationColorPicker: boolean;
/**
* If true, the color picker will be hidden in the context options in minimum duration mode.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationContextColorPicker: boolean;
/**
* If true, the interval selector will be hidden in the context options in minimum duration mode.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationContextInterval: boolean;
/**
* If true, the context options will be hidden in the minimum duration mode options.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationContextOptions: boolean;
/**
* If true, the toggle used to show or hide the context options will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationContextToggle: boolean;
/**
* If true, the visualization options will be hidden in minimum duration mode.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationOptions: boolean;
/**
* If true, the minimum duration slider will be hidden in the minimum duration mode options.
*
* @default false
* @since 5.0
*/
accessor hideMinDurationSlider: boolean;
/**
* If true, the tooltip which displays the shadow or sunlight duration at a certain location will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideShadowDurationTooltip: boolean;
/**
* If true, the time range slider will be hidden.
*
* @default false
*/
accessor hideTimeRangeSlider: boolean;
/**
* If true, the timezone picker will be hidden.
*
* @default false
*/
accessor hideTimezone: boolean;
/**
* If true, the color picker will be hidden in the total duration mode options.
*
* @default false
* @since 5.0
*/
accessor hideTotalDurationColorPicker: boolean;
/**
* If true, the mode selector will be hidden in the total duration mode options.
*
* @default false
* @since 5.0
*/
accessor hideTotalDurationModeSelect: boolean;
/**
* If true, the visualization options will be hidden in the total duration mode.
*
* @default false
* @since 5.0
*/
accessor hideTotalDurationOptions: boolean;
/**
* Indicates whether the component's visualization is hidden in the view.
*
* @default false
* @since 5.0
*/
accessor hideVisualization: boolean;
/**
* If true, the visualization options will be hidden.
*
* @default false
* @since 5.0
*/
accessor hideVisualizationOptions: boolean;
/**
* Icon which represents the component.
* Typically used when the component is controlled by another component (e.g. by the Expand component).
*
* @default "measure-building-height-shadow"
* @see [Calcite Icons](https://developers.arcgis.com/calcite-design-system/icons/)
*/
accessor icon: Icon["icon"] | undefined;
/** The component's default label. */
accessor label: string | undefined;
/**
* Maximum allowed value for the [minDuration](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDuration) property, in milliseconds.
*
* @since 5.0
*/
accessor maxMinDuration: number;
/** @internal */
protected messages: Partial<{
componentLabel: string;
dateLabel: string;
discrete: {
optionLabel: string;
colorLabel: string;
intervalLabel: string;
};
minDuration: {
optionLabel: string;
colorLabel: string;
minDurationLabel: string;
discreteLabel: string;
discreteColorLabel: string;
};
totalDuration: {
optionLabel: string;
colorLabel: string;
modeLabel: string;
continuousLabel: string;
hourlyLabel: string;
};
sunlight: {
discrete: {
optionLabel: string;
colorLabel: string;
intervalLabel: string;
};
minDuration: {
optionLabel: string;
colorLabel: string;
minDurationLabel: string;
discreteLabel: string;
discreteColorLabel: string;
};
totalDuration: {
optionLabel: string;
colorLabel: string;
modeLabel: string;
continuousLabel: string;
hourlyLabel: string;
};
};
timeInShadow: string;
timeInSunlight: string;
timeRangeHeading: string;
timeRangeSliderLabel: string;
timezoneLabel: string;
visualizationLabel: string;
}> & T9nMeta<{
componentLabel: string;
dateLabel: string;
discrete: {
optionLabel: string;
colorLabel: string;
intervalLabel: string;
};
minDuration: {
optionLabel: string;
colorLabel: string;
minDurationLabel: string;
discreteLabel: string;
discreteColorLabel: string;
};
totalDuration: {
optionLabel: string;
colorLabel: string;
modeLabel: string;
continuousLabel: string;
hourlyLabel: string;
};
sunlight: {
discrete: {
optionLabel: string;
colorLabel: string;
intervalLabel: string;
};
minDuration: {
optionLabel: string;
colorLabel: string;
minDurationLabel: string;
discreteLabel: string;
discreteColorLabel: string;
};
totalDuration: {
optionLabel: string;
colorLabel: string;
modeLabel: string;
continuousLabel: string;
hourlyLabel: string;
};
};
timeInShadow: string;
timeInSunlight: string;
timeRangeHeading: string;
timeRangeSliderLabel: string;
timezoneLabel: string;
visualizationLabel: string;
}>;
/**
* The minimum duration (in milliseconds) used in `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode) to
* determine which shadowed or sunlit areas are displayed.
*
* @since 5.0
*/
accessor minDuration: number;
/**
* Color of the visualization in `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode). Areas with cumulative
* shadow or sunlight time longer than the minimum duration value are displayed with this color.
*
* @since 5.0
*/
accessor minDurationColor: Color;
/**
* The color used when showing additional context in `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode) when
* [minDurationContextEnabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDurationContextEnabled) is true. This context applies to shadow
* visualization and is not used when [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#visualizeSunlight) is `true`.
*
* @since 5.0
*/
accessor minDurationContextColor: Color;
/**
* Whether to enable additional context showing discrete shadows at the same time as displaying shadows above a
* minimum duration when in `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode). The [minDurationContextColor](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDurationContextColor)
* and [minDurationContextInterval](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDurationContextInterval) properties are used to configure the visualization of the
* discrete shadows when context is enabled. This context is hidden when
* [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#visualizeSunlight) is `true` because the equivalent sunlight context would show
* broad areas not in shadow at each sample and can obscure the threshold result.
*
* @default false
* @since 5.0
*/
accessor minDurationContextEnabled: boolean;
/**
* The interval in milliseconds used when showing additional context in `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode) when
* [minDurationContextEnabled](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDurationContextEnabled) is true. This context applies to shadow
* visualization and is not used when [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#visualizeSunlight) is `true`.
*
* @since 5.0
*/
accessor minDurationContextInterval: number;
/**
* Minimum allowed value for the [minDuration](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#minDuration) property, in milliseconds.
*
* @default 0
* @since 5.0
*/
accessor minMinDuration: number;
/**
* 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. When visualizing shadows, optional discrete shadow overlays can provide additional context.
* - `"total-duration"`: Displays total shadow or sunlight accumulation within the selected time range. Supports continuous or 1-hour aggregated modes.
*
* @since 5.0
*/
accessor mode: ShadowCastMode;
/**
* By assigning the `id` attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.
*
* @see [Associate components with a Map or Scene component](https://developers.arcgis.com/javascript/latest/programming-patterns/#associate-components-with-a-map-or-scene-component)
*/
accessor referenceElement: ArcgisReferenceElement | string | undefined;
/**
* Time (in milliseconds from midnight of the [date](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#date)) when the shadow or sunlight computation should start.
*
* [Read more](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#startTimeOfDay)
*/
accessor startTimeOfDay: number;
/**
* The component's state. The values mean the following:
*
* * `disabled` - component is being created
* * `ready` - component is ready
*/
get state(): "disabled" | "ready";
/**
* Color of the visualization in `"total-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode). The opacity is mapped
* to the time spent in shadow or sunlight. Areas with no duration are displayed with zero opacity and areas with the
* maximum duration use the opacity specified in this property. The component UI exposes a single color for this mode.
*
* @since 5.0
*/
accessor totalDurationColor: Color;
/**
* Mode in which the cumulative shadow or sunlight duration should be displayed in `"total-duration"`
* [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode): as a continuous surface or as an hourly aggregation of values.
*
* @since 5.0
*/
accessor totalDurationMode: ShadowCastTotalDurationMode;
/**
* The UTC offset in hours used to interpret the selected date and time range for the analysis. If not specified, the
* component automatically determines an approximate UTC offset based on the camera location.
*/
accessor utcOffset: number | null | undefined;
/**
* The view associated with the component.
* > **Note:** The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this `view` property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-shadow-cast component will be associated with a map or scene component rather than using the `view` property.
*/
accessor view: SceneView | undefined;
/**
* When `true`, the component visualizes sunlight duration instead of shadow duration. This applies to all modes,
* their respective options, and the duration returned by
* [getDurationAtScreen()](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#getDurationAtScreen). In sunlight mode, the discrete context controls in the
* `"min-duration"` [mode](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#mode) are hidden because the equivalent sunlight context
* would show broad areas not in shadow at each sample and can obscure the threshold result.
*
* [Read more](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/#visualizeSunlight)
*
* @default false
* @since 5.1
*/
accessor visualizeSunlight: boolean;
/**
* Specifies the size of the component.
*
* @default "m"
* @experimental
* @since 5.0
*/
accessor visualScale: "l" | "m" | "s";
/** Permanently destroy the component. */
destroy(): Promise<void>;
/**
* Returns the duration (in milliseconds) for a certain point on the screen based on the current analysis settings.
* By default, this method returns the time spent in shadow. When
* [visualizeSunlight](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/#visualizeSunlight) is `true`, this method returns the time spent in sunlight.
*
* [Read more](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ShadowCastAnalysisView3D/#getDurationAtScreen)
*
* @param point
* @since 5.0
*/
getDurationAtScreen(point: ScreenPoint): Promise<number>;
"@setterTypes": {
date?: Date | number | string;
};
/** Emitted when the value of a property is changed. Use this to listen to changes to properties. */
readonly arcgisPropertyChange: import("@arcgis/lumina").TargetedEvent<this, { name: "state"; }>;
/** Emitted when the component associated with a map or scene view is ready to be interacted with. */
readonly arcgisReady: import("@arcgis/lumina").TargetedEvent<this, void>;
readonly "@eventTypes": {
arcgisPropertyChange: ArcgisShadowCast["arcgisPropertyChange"]["detail"];
arcgisReady: ArcgisShadowCast["arcgisReady"]["detail"];
};
}