Merge pull request #1986 from chambbj/improved-filter-docs

Improved filter docs

doc/references.rst

@@ -19,6 +19,8 @@ References
 
 .. [Li2010] Li, Ruosi, et al. "Polygonizing extremal surfaces with manifold guarantees." Proceedings of the 14th ACM Symposium on Solid and Physical Modeling. ACM, 2010.
 
+.. [Limberger2015] Limberger, Frederico A., and Manuel M. Oliveira. “Real-Time Detection of Planar Regions in Unorganized Point Clouds.” Pattern Recognition 48.6 (2015): 2043–2053. Web.
+
 .. [Mesh2009] ALoopingIcon. "Meshing Point Clouds." *MESHLAB STUFF*. n.p., 7 Sept. 2009. Web. 13 Nov. 2015.
 
 .. [Mongus2012] Mongus, D., Zalik, B., 2012. Parameter-free ground filtering of LiDAR data for automatic DTM generation. ISPRS J. Photogramm. Remote Sens. 67, 1–12.

doc/stages/filters.approximatecoplanar.rst

@@ -3,26 +3,24 @@
 filters.approximatecoplanar
 ===============================================================================
 
-``filters.approximatecoplanar`` filter estimates the planarity of a neighborhood
-of points by first computing eigenvalues for the points and then tagging those
-points for which the following is true:
+``filters.approximatecoplanar`` implements a portion of the algorithm presented
+in [Limberger2015]_. Prior to clustering points, the authors first apply an
+approximate coplanarity test, where points that meet the following criteria are
+labeled as approximately coplanar.
 
 .. math::
 
-  \lambda_1 > (thresh_1 * \lambda_0) \&\& (\lambda_1 * thresh_2) > \lambda_2
+  \lambda_2 > (s_{\alpha}\lambda_1) \&\& (s_{\beta}\lambda_2) > \lambda_3
 
-where :math:`\lambda_0`, :math:`\lambda_1`, :math:`\lambda_2` are the
-eigenvalues in ascending order. The threshold values :math:`thresh_1` and
-:math:`thresh_2` are user-defined and default to 25 and 6 respectively.
+:math:`\lambda_1`, :math:`\lambda_2`, :math:`\lambda_3` are the eigenvalues of
+a neighborhood of points (defined by ``knn`` nearest neighbors) in ascending
+order. The threshold values :math:`s_{\alpha}` and :math:`s_{\beta}` are
+user-defined and default to 25 and 6 respectively.
 
-The filter returns a point cloud with a new dimension  ``Coplanar`` that
+The filter returns a point cloud with a new dimension ``Coplanar`` that
 indicates those points that are part of a neighborhood that is approximately
 coplanar (1) or not (0).
 
-Eigenvalue estimation is performed using Eigen's ``SelfAdjointEigenSolver``. For
-more information see
-https://eigen.tuxfamily.org/dox/classEigen_1_1SelfAdjointEigenSolver.html.
-
 .. embed::
 
 Example

doc/stages/filters.estimaterank.rst

@@ -3,17 +3,26 @@
 filters.estimaterank
 ===============================================================================
 
-``filters.estimaterank`` computes the rank (i.e., the number of nonzero singular
-values) of a neighborhood of points.
-
-This method uses Eigen's JacobiSVD class to solve the singular value
-decomposition and to estimate the rank using the user-specified threshold. A
-singular value will be considered nonzero if its absolute value is greater than
-the product of the user-supplied threshold and the absolute value of the maximum
-singular value.
-
-More on JacobiSVD can be found at
-https://eigen.tuxfamily.org/dox/classEigen_1_1JacobiSVD.html.
+``filters.estimaterank`` uses singular value decomposition (SVD) to estimate
+the rank of a set of points. Point sets with rank 1 correspond to linear
+features, while sets with rank 2 correspond to planar features. Rank 3
+corresponds to a full 3D feature. In practice this can be used alone, or
+possibly in conjunction with other filters to extract features (e.g.,
+buildings, vegetation).
+
+Two parameters are required to estimate rank (though the default values will be
+suitable in many cases). First, the ``knn`` parameter defines the number of
+points to consider when computing the SVD and estimated rank. Second, the
+``thresh`` parameter is used to determine when a singular value shall be
+considered non-zero (when the absolute value of the singular value is greater
+than the threshold).
+
+The rank estimation is performed on a pointwise basis, meaning for each point
+in the input point cloud, we find its ``knn`` neighbors, compute the SVD, and
+estimate rank. ``filters.estimaterank`` creates a new dimension called ``Rank``
+that can be used downstream of this filter stage in the pipeline. The type of
+writer used will determine whether or not the ``Rank`` dimension itself can be
+saved to disk.
 
 .. embed::