# filters.head

The Head filter returns a specified number of points from the beginning of a `PointView`.

Note

If the requested number of points exceeds the size of the point cloud, all points are passed with a warning.

Default Embedded Stage

This stage is enabled by default

## Example #1

Thin a point cloud by first shuffling the point order with filters.randomize and then picking the first 10000 using the HeadFilter.

    [
        {
            "type":"filters.randomize"
        },
        {
            "type":"filters.head",
            "count":10000
        }
    ]

## Example #2

Compute height above ground and extract the ten highest points.

    [
        {
            "type":"filters.smrf"
        },
        {
            "type":"filters.hag_nn"
        },
        {
            "type":"filters.sort",
            "dimension":"HeightAboveGround",
            "order":"DESC"
        },
        {
            "type":"filters.head",
            "count":10
        }
    ]

See also

filters.tail is the dual to filters.head.

## Options

count

  Number of points to return. [Default: 10]

where

  An expression that limits points passed to a filter. Points that don’t pass the expression skip the stage but are available to subsequent stages in a pipeline. [Default: no filtering]

where_merge

  A strategy for merging points skipped by a ‘where’ option when running in standard mode. If `true`, the skipped points are added to the first point view returned by the skipped filter. If `false`, skipped points are placed in their own point view. If `auto`, skipped points are merged into the returned point view provided that only one point view is returned and it has the same point count as it did when the filter was run. [Default: `auto`]