import type Analysis from "./Analysis.js";
import type Viewshed from "./Viewshed.js";
import type Collection from "../core/Collection.js";
import type { ViewshedProperties } from "./Viewshed.js";
import type { ReadonlyArrayOrCollection } from "../core/Collection.js";
import type { AnalysisProperties } from "./Analysis.js";

export interface ViewshedAnalysisProperties extends AnalysisProperties {
  /** A list of viewsheds. */
  viewsheds?: ReadonlyArrayOrCollection<ViewshedProperties>;
}

/**
 * ViewshedAnalysis enables the creation and display of viewshed and view dome type of visibility analysis in a 3D [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
 *
 * The analysis can contain multiple viewsheds. These can be created interactively or programmatically, and the analysis can be added directly to
 * [SceneView.analyses](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#analyses) or to the
 * [ViewshedLayer.source](https://developers.arcgis.com/javascript/latest/references/core/layers/ViewshedLayer/#source) in a [SceneView.map](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/#map).
 *
 * ```js
 * const viewshed = new Viewshed({
 *   observer: new Point({ }),
 *   farDistance: 900,
 *   heading: 64,
 *   tilt: 84,
 *   horizontalFieldOfView: 85,
 *   verticalFieldOfView: 52
 * });
 * const viewshedAnalysis = new ViewshedAnalysis({
 *   viewsheds: [viewshed],
 * });
 *
 * // add the analysis to the view
 * view.analyses.add(viewshedAnalysis);
 * ```
 *
 * To add a viewshed interactively, use the
 * [ViewshedAnalysisView3D.place()](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ViewshedAnalysisView3D/#place) method.
 *
 * ```js
 * const abortController = new AbortController();
 *
 * try {
 *   // get a view for the analysis
 *   const analysisView = await view.whenAnalysisView(viewshedAnalysis);
 *
 *   // start placing a new viewshed interactively
 *   await analysisView.place({ signal: abortController.signal });
 * } catch (error) {
 *   if (error.name === "AbortError") {
 *     console.log("Placement operation was cancelled.");
 *   }
 * }
 *
 * // cancel the placement operation at some later point
 * abortController.abort();
 * ```
 *
 * To edit existing viewsheds interactively, set the
 * [ViewshedAnalysisView3D.interactive](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ViewshedAnalysisView3D/#interactive) property
 * `true` and select a viewshed by hovering and clicking on their field-of-view manipulators.
 *
 * ```js
 * // allow existing viewsheds in the analysis to be selected and edited
 * analysisView.interactive = true;
 * ```
 *
 * A ViewshedAnalysis can be persisted in a [WebScene](https://developers.arcgis.com/javascript/latest/references/core/WebScene/) as part of a [ViewshedLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ViewshedLayer/).
 *
 * > [!WARNING]
 * >
 * > **Known Limitations**
 * >
 * > This analysis is only supported in a 3D [SceneView](https://developers.arcgis.com/javascript/latest/references/core/views/SceneView/).
 * > The results of the tool vary depending on the zoom level, as changes in zoom level affect the level of detail (LOD) of the scene geometry.
 *
 * @since 4.30
 * @see [ViewshedAnalysisView3D](https://developers.arcgis.com/javascript/latest/references/core/views/3d/analysis/ViewshedAnalysisView3D/)
 * @see [Viewshed](https://developers.arcgis.com/javascript/latest/references/core/analysis/Viewshed/)
 * @see [ViewshedLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/ViewshedLayer/)
 * @see [ViewshedLayerView](https://developers.arcgis.com/javascript/latest/references/core/views/layers/ViewshedLayerView/)
 * @see [Sample - Interactive viewshed analysis](https://developers.arcgis.com/javascript/latest/sample-code/analysis-viewshed/)
 * @see [Sample - Analysis objects](https://developers.arcgis.com/javascript/latest/sample-code/analysis-objects/)
 * @see [3D viewshed overview](https://developers.arcgis.com/documentation/spatial-analysis-services/3d-visual/3d-viewshed/)
 */
export default class ViewshedAnalysis extends Analysis {
  constructor(properties?: ViewshedAnalysisProperties);
  /** The type of analysis. For viewshed analysis, this is always "viewshed". */
  get type(): "viewshed";
  /**
   * Indicates whether the analysis is ready to be computed and interacted with in the view.
   * It requires each of the [viewsheds](https://developers.arcgis.com/javascript/latest/references/core/analysis/ViewshedAnalysis/#viewsheds) to be valid, that is, to have an observer with a position and a far
   * distance greater than 0. If the analysis has no viewshed, it is considered valid.
   *
   * @since 4.33
   */
  get valid(): boolean;
  /** A list of viewsheds. */
  get viewsheds(): Collection<Viewshed>;
  set viewsheds(value: ReadonlyArrayOrCollection<ViewshedProperties>);
  /**
   * Clears the analysis by removing all [viewsheds](https://developers.arcgis.com/javascript/latest/references/core/analysis/ViewshedAnalysis/#viewsheds).
   *
   * @since 5.0
   */
  clear(): void;
}