# filters.normal

The **normal filter** returns the estimated normal and curvature for
a collection
of points. The algorithm first computes the eigenvalues and eigenvectors of the
collection of points, which is comprised of the k-nearest neighbors. The normal
is taken as the eigenvector corresponding to the smallest eigenvalue. The
curvature is computed as

where \(\lambda_i\) are the eigenvalues sorted in ascending order.

The filter produces four new dimensions (`NormalX`

, `NormalY`

, `NormalZ`

,
and `Curvature`

), which can be analyzed directly, or consumed by downstream
stages for more advanced filtering.

The eigenvalue decomposition is performed using Eigen’s SelfAdjointEigenSolver.

Normals will be automatically flipped towards positive Z, unless the always_up flag is set to false. Users can optionally set any of the XYZ coordinates to specify a custom viewpoint or set them all to zero to effectively disable the normal flipping.

Note

By default, the Normal filter will invert normals such that they are always pointed “up” (positive Z). If the user provides a viewpoint, normals will instead be inverted such that they are oriented towards the viewpoint, regardless of the always_up flag. To disable all normal flipping, do not provide a viewpoint and set always_up to false.

In addition to always_up and viewpoint, users can run a refinement step (off by default) that propagates normals using a minimum spanning tree. The propagated normals can lead to much more consistent results across the dataset.

Note

To enable normal propagation, users can set refine to true.

## Example

This pipeline demonstrates the calculation of the normal values (along with curvature). The newly created dimensions are written out to BPF for further inspection.

```
[
"input.las",
{
"type":"filters.normal",
"knn":8
},
{
"type":"writers.bpf",
"filename":"output.bpf",
"output_dims":"X,Y,Z,NormalX,NormalY,NormalZ,Curvature"
}
]
```

## Options

- knn
The number of k-nearest neighbors. [Default: 8]

- viewpoint
A single WKT or GeoJSON 3D point. Normals will be inverted such that they are all oriented towards the viewpoint.

- always_up
A flag indicating whether or not normals should be inverted only when the Z component is negative. [Default: true]

- refine
A flag indicating whether or not to reorient normals using minimum spanning tree propagation. [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`

]