pointcloudprocessing/docs/usecase6.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page pointcloudprocessing_usecase6 Point Cloud Plane Extraction

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

This tutorial demonstrates how to estimate one 3D plane. 

To initialize the module, 
```{.cpp}
dwPointCloudPlaneExtractorHandle_t estimator;
dwPointCloudPlaneExtractorParams params{};
dwPointCloudPlaneExtractor_getDefaultParameters(&params);
dwPointCloudPlaneExtractor_initialize(&estimator, &params, context);
dwPointCloudPlaneExtractor_setCUDAStream(stream, estimator);
```

The plane estimation is based on ransac fitting and non-linear optimization. User can tailor `params.ransacIterationCount` and `params.optimizerIterationCount`
to fulfill the expected performance. `params.rotation` gives the initial guess on the transformation from the point cloud to the 3D plane. `params.boxFilterParams` controls box filter parameters applied before ransac is executed. User is able to vary size of an area and number of points picked for ransac algorithm to make it working more effectively.
If `params.cudaPipelineEnabled = true`, the module expects CUDA memory type point cloud. 

To get the estimated 3D plane, 

```{.cpp}
dwPointCloudPlaneExtractor_bindInput(pointCloud, estimator);
dwPointCloudPlaneExtractor_bindOutput(inliers, outliers, plane, estimator);
dwPointCloudPlaneExtractor_process(estimator);
```

`inliers` is a subset of the input point cloud. It indicates the group that is used for plane estimation.
`outliers` is a subset of the input point cloud but mutual exclusive to `inliers`. It indicates the group that is not used
for plane estimation. It is not guaranteed to get estimated plane for each input point cloud. If `plane.valid = false`, it 
means the estimated plane should not be used. 

Note: the module does not output `inliers` and `outliers` if `params.cudaPipelineEnabled = true`.

To release the module,
```{.cpp}
dwPointCloudPlaneExtractor_release(estimator);
```

For more details see @ref dwx_pointcloudprocessing_sample