@arcgis/core/widgets/ShadowCast.d.ts

ArcGIS Maps SDK for JavaScript: A complete 2D and 3D mapping and data visualization API

import type SceneView from "../views/SceneView.js";
import type Widget from "./Widget.js";
import type ShadowCastViewModel from "./ShadowCast/ShadowCastViewModel.js";
import type ShadowCastVisibleElements from "./ShadowCast/ShadowCastVisibleElements.js";
import type { Icon } from "@esri/calcite-components/components/calcite-icon";
import type { WidgetProperties } from "./Widget.js";
import type { HeadingLevel } from "./support/types.js";
import type { ShadowCastViewModelProperties } from "./ShadowCast/ShadowCastViewModel.js";
import type { ShadowCastVisibleElementsProperties } from "./ShadowCast/ShadowCastVisibleElements.js";

export interface ShadowCastProperties extends WidgetProperties, Partial<Pick<ShadowCast, "headingLevel" | "view">> {
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-building-height-shadow"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  icon?: Icon["icon"] | null;
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  label?: string | null;
  /**
   * 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 [ShadowCastViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ShadowCast/ShadowCastViewModel/)
   * class to access all properties and methods on the widget.
   */
  viewModel?: ShadowCastViewModelProperties;
  /**
   * This property provides the ability to display or hide the individual elements of the widget.
   *
   * @example
   * shadowCast.visibleElements = {
   *   timeRangeSlider: true,
   *   timezone: true,
   *   datePicker: true,
   *   visualizationOptions: true,
   *   colorPicker: true,
   *   tooltip: true
   * }
   */
  visibleElements?: ShadowCastVisibleElementsProperties;
}

/**
 * The ShadowCast widget displays the cumulative shadows of 3D features in a
 * [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). This type of analysis is helpful in urban development,
 * where new projects have to satisfy certain shadow duration constraints.
 *
 * The widget calculates the cumulative shadows for a time range during a single day. The user can
 * configure the time range and select a calendar date. This time range and calendar date are only used
 * for the shadow analysis and are not connected to the lighting in the scene.
 * To control the lighting in the scene, the [Daylight](https://developers.arcgis.com/javascript/latest/references/core/widgets/Daylight/) widget can be used.
 * Changing the timezone in the widget updates the visualization by interpreting the time range as being
 * in that timezone. This behavior is different than for the [Daylight](https://developers.arcgis.com/javascript/latest/references/core/widgets/Daylight/) widget
 * where selecting a timezone updates the scene date and time according to the camera position.
 *
 * The widget provides three visualization modes.
 *
 * In the **threshold** mode, only the areas that receive
 * shadows for more than a certain amount of time are displayed. In the image below, on May 1, 2021 the red areas receive
 * shadow for more than 4 hours within the time interval of 10AM to 4PM.
 *
 * [![threshold mode](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/shadow-cast/shadow-cast-threshold.png)](https://developers.arcgis.com/javascript/latest/sample-code/widgets-shadow-cast/)
 *
 * **Total shadow duration** mode displays the duration of the cumulative shadow using opacity: areas that don't
 * receive any shadow are fully transparent and areas that receive a maximum amount of shadow have a default opacity
 * of 0.7. The values in between are interpolated. Hovering over the view will display a tooltip showing the
 * amount of time that location is in shadow, rounded to 15 minute intervals. In this mode, the visualization
 * can display shadow cast in a continuous way or in 1 hour intervals.
 *
 * [![duration mode](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/shadow-cast/shadow-cast-duration.png)](https://developers.arcgis.com/javascript/latest/sample-code/widgets-shadow-cast/)
 *
 * **Discrete shadows** is a third visualization mode which displays individual shadows at a given time interval.
 * For example, setting the time range to 10AM-11AM and the visualization time interval to 30 minutes will display
 * shadows for 10AM, 10:30AM and 11:00AM.
 *
 * [![discrete mode](https://developers.arcgis.com/javascript/latest/assets/references/core/widgets/shadow-cast/shadow-cast-discrete.png)](https://developers.arcgis.com/javascript/latest/sample-code/widgets-shadow-cast/)
 *
 * The defaults for the time range and visualization settings can be changed using the
 * [ShadowCastViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ShadowCast/ShadowCastViewModel/).
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > Terrain does not cast shadows and it is therefore not taken into account in this analysis.
 * >
 * > The widget does not take into account the daylight savings.
 * > 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 by the widget 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 dropdown.
 *
 * You can use the view's [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/) to add widgets to the view's user interface via the
 * `ui` property on the view. See the example below.
 *
 * @deprecated since version 5.0. Use the [Shadow Cast component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/) instead. For information on widget deprecation, read about [Esri's move to web components](https://developers.arcgis.com/javascript/latest/components-transition-plan/).
 * @since 4.21
 * @see [ShadowCastViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ShadowCast/ShadowCastViewModel/) - _Deprecated since 5.0. Use the [ShadowCastAnalysis](https://developers.arcgis.com/javascript/latest/references/core/analysis/ShadowCastAnalysis/) or [Shadow Cast component](https://developers.arcgis.com/javascript/latest/references/map-components/components/arcgis-shadow-cast/) instead._
 * @see [SceneView.environment](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#environment)
 * @see [DefaultUI](https://developers.arcgis.com/javascript/latest/references/core/views/ui/DefaultUI/)
 * @see [Sample - Shadow cast](https://developers.arcgis.com/javascript/latest/sample-code/widgets-shadow-cast/)
 * @example
 * const shadowCast = new ShadowCast({
 *   view: view
 * });
 * // Adds the shadow cast widget in
 * // the top right corner of the view
 * view.ui.add(shadowCast, "top-right");
 */
export default class ShadowCast extends Widget {
  constructor(properties?: ShadowCastProperties);
  /**
   * Indicates the heading level to use for the titles "Time range" and "Visualization". By default, this message is rendered
   * as level 4 headings (e.g. `<h4>Time range</h4>`). Depending on the widget's placement
   * in your app, you may need to adjust this heading for proper semantics. This is
   * important for meeting accessibility standards.
   *
   * @default 4
   * @see [Heading Elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements)
   * @example shadowCast.headingLevel = 3;
   */
  accessor headingLevel: HeadingLevel;
  /**
   * Icon which represents the widget. It is typically used when the widget is controlled by another
   * one (e.g. in the Expand widget).
   *
   * @default "measure-building-height-shadow"
   * @since 4.27
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   * @see [Calcite Icon Search](https://developers.arcgis.com/calcite-design-system/icons/)
   */
  get icon(): Icon["icon"];
  set icon(value: Icon["icon"] | null | undefined);
  /**
   * The widget's default label.
   *
   * @since 4.11
   */
  get label(): string;
  set label(value: string | null | undefined);
  /** A reference to the [View](https://developers.arcgis.com/javascript/latest/references/core/views/View/). This widget is only supported in a [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/). */
  accessor view: SceneView | null | undefined;
  /**
   * 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 [ShadowCastViewModel](https://developers.arcgis.com/javascript/latest/references/core/widgets/ShadowCast/ShadowCastViewModel/)
   * class to access all properties and methods on the widget.
   */
  get viewModel(): ShadowCastViewModel;
  set viewModel(value: ShadowCastViewModelProperties);
  /**
   * This property provides the ability to display or hide the individual elements of the widget.
   *
   * @example
   * shadowCast.visibleElements = {
   *   timeRangeSlider: true,
   *   timezone: true,
   *   datePicker: true,
   *   visualizationOptions: true,
   *   colorPicker: true,
   *   tooltip: true
   * }
   */
  get visibleElements(): ShadowCastVisibleElements;
  set visibleElements(value: ShadowCastVisibleElementsProperties);
}