import type PointCloudFilter from "./PointCloudFilter.js";
import type { PointCloudFilterProperties } from "./PointCloudFilter.js";

export interface PointCloudReturnFilterProperties extends PointCloudFilterProperties, Partial<Pick<PointCloudReturnFilter, "includedReturns">> {}

/**
 * Laser pulses emitted from a lidar system can have several returns depending on the surfaces that they encounter.
 * The return number is stored within each point in the `RETURNS` field. For example, the first return is associated with the highest point
 * in the landscape. In some cases the laser pulse returns only one point representing the ground.
 *
 * ![pcl-return-filter](https://developers.arcgis.com/javascript/latest/assets/img/apiref/layers/pcl-return-filter.png)
 *
 * A [PointCloudLayer](https://developers.arcgis.com/javascript/latest/references/core/layers/PointCloudLayer/) can be filtered using a PointCloudReturnFilter based on the information
 * in the `RETURNS` field. Points can be filtered using the values in the [includedReturns](https://developers.arcgis.com/javascript/latest/references/core/layers/pointCloudFilters/PointCloudReturnFilter/#includedReturns).
 *
 * For example, to filter points representing the highest features in the landscape, the following filter can be set:
 *
 * ```js
 * const pointCloudLayer = new PointCloudLayer({
 *  ...,
 *  filters: [{
 *    type: "return",
 *    field: "RETURNS",
 *    includedReturns: ["firstOfMany", "single"]
 *  }]
 * });
 * ```
 *
 * @since 4.10
 * @see [Sample - Filter points in a PointCloudLayer](https://developers.arcgis.com/javascript/latest/sample-code/layers-pointcloud-filters/)
 */
export default class PointCloudReturnFilter extends PointCloudFilter {
  constructor(properties?: PointCloudReturnFilterProperties);
  /**
   * An array of return types used to filter points. Possible values for the return types are:
   *
   * Value | Description
   * ------|------------
   * `firstOfMany` | The point was the first to be collected in a series of many returns.
   * `last` | The last point in a series of many returns or a single point.
   * `lastOfMany` | The last point in a series of many returns.
   * `single` | All the points that were collected from laser pulses with a single return.
   */
  accessor includedReturns: PointCloudStatus[];
  /** The type of filter. */
  get type(): "return";
}

export type PointCloudStatus = "last" | "firstOfMany" | "lastOfMany" | "single";