# filters.covariancefeatures#

This filter implements various local feature descriptors that are based on the covariance matrix of a point’s neighborhood.

The user can pick a set of feature descriptors by setting the `feature_set`

option. The [dimensionality] set of feature descriptors introduced below is the
default. The user can also provide a comma-separated list of features to
explicitly itemize those covariance features they wish to be computed. This can
be combined with any suppported presets like “Dimensionality”. Specifying “all”
will compute all available features.

Supported features include:

Anisotropy

DemantkeVerticality

Density

Eigenentropy

Linearity

Omnivariance

Planarity

Scattering

EigenvalueSum

SurfaceVariation

Verticality

Note

Density requires both `OptimalKNN`

and `OptimalRadius`

which can be
computed by running filters.optimalneighborhood prior to
`filters.covariancefeatures`

.

## Example #1#

```
[
"input.las",
{
"type":"filters.covariancefeatures",
"knn":8,
"threads": 2,
"feature_set": "Dimensionality"
},
{
"type":"writers.bpf",
"filename":"output.bpf",
"output_dims":"X,Y,Z,Linearity,Planarity,Scattering,Verticality"
}
]
```

## Example #2#

```
[
"input.las",
{
"type":"filters.optimalneighborhood"
},
{
"type":"filters.covariancefeatures",
"knn":8,
"threads": 2,
"optimized":true,
"feature_set": "Linearity,Omnivariance,Density"
},
{
"type":"writers.las",
"minor_version":4,
"extra_dims":"all",
"forward":"all",
"filename":"output.las"
}
]
```

## Options#

- knn
The number of k nearest neighbors used for calculating the covariance matrix. [Default: 10]

- threads
The number of threads to use. Only valid in standard mode. [Default: 1]

- feature_set
A comma-separated list of individual features or feature presets (e.g., “Dimensionality”) to be computed. To compute all available features, specify “all”. [Default: “Dimensionality”]

- stride
When finding k nearest neighbors, stride determines the sampling rate. A stride of 1 retains each neighbor in order. A stride of two selects every other neighbor and so on. [Default: 1]

- min_k
Minimum number of neighbors in radius (radius search only). [Default: 3]

- radius
If radius is specified, neighbors will be obtained by radius search rather than k nearest neighbors, subject to meeting the minimum number of neighbors (

`min_k`

).- mode
By default, features are computed using the standard deviation along each eigenvector, i.e., using the square root of the computed eigenvalues (

`mode="SQRT"`

).`mode`

also accepts “Normalized” which normalizes eigenvalue such that they sum to one, or “Raw” such that the eigenvalues are used directly. [Default: “SQRT”]- optimized
`optimized`

can be set to`true`

to enable computation of features using precomputed optimal neighborhoods (found in the`OptimalKNN`

dimension). Requires filters.optimalneighborhood be run prior to this stage. [Default: false]

- 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`

]

### Dimensionality feature set#

The features introduced in [Demantké *et al.*, 2011] describe the shape of the
neighborhood, indicating whether the local geometry is more linear (1D), planar
(2D) or volumetric (3D) while the one introduced in [Guinard and Landrieu, 2017] adds the
idea of a structure being vertical.

The dimensionality filter introduces the following four descriptors that are
computed from the covariance matrix of a point’s neighbors (as defined by
`knn`

or `radius`

):

linearity - higher for long thin strips

planarity - higher for planar surfaces

scattering - higher for complex 3d neighbourhoods

verticality - higher for vertical structures, highest for thin vertical strips

It introduces four new dimensions that hold each one of these values:
`Linearity`

, `Planarity`

, `Scattering`

and `Verticality`

.