Renaming filter and adding doc

doc/references.rst

@@ -38,8 +38,12 @@ Reference
 
 .. [Cook1986] Cook, Robert L. "Stochastic sampling in computer graphics." *ACM Transactions on Graphics (TOG)* 5.1 (1986): 51-72.
 
+.. [Demantke2011] Demantké J., Mallet C., David N., Vallet, B. "Dimensionality Based Scale Selection in 3d LIDAR Point Clouds."  Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci, XXXVIII-5/W12, 97-102, 2011
+
 .. [Dippe1985] Dippé, Mark AZ, and Erling Henry Wold. "Antialiasing through stochastic sampling." *ACM Siggraph Computer Graphics* 19.3 (1985): 69-78.
 
+.. [Guinard2017] Guinard S., Landrieu L. "Weakly Supervised Segmented-Aided Classification of Urban Scenes From 3D LIDAR Point Clouds." Int. Arch. Photogramm. Remote Sens. Spatial Inf. Sci., XLII-1/W1, 151-157, 2017
+
 .. [Kazhdan2006] Kazhdan, Michael, Matthew Bolitho, and Hugues Hoppe. "Poisson surface reconstruction." Proceedings of the fourth Eurographics symposium on Geometry processing. Vol. 7. 2006.
 
 .. [Li2010] Li, Ruosi, et al. "Polygonizing extremal surfaces with manifold guarantees." Proceedings of the 14th ACM Symposium on Solid and Physical Modeling. ACM, 2010.

doc/stages/filters.dimensionality.rst

@@ -0,0 +1,49 @@
+.. _filters.dimensionality:
+
+===============================================================================
+filters.dimensionality
+===============================================================================
+
+This filter implements the local feature descriptors introduced in [Demantke2011]_ and [Guinard2017]_.
+The features introduced in [Demantke2011]_ 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
+[Guinard2017]_ adds the idea of a structure being vertical.
+
+The filter introduces the following four descriptors that are computed from the covariance matrix of the `knn` neighbors:
+
+    linearity - higher for long thin strips
+    planarity - higher for planar surfaces
+    scattering - higher for complex 3d neighbourhoods
+    verticality - higher for thin vertical strips
+
+It introduces four new dimensions that hold each one of these values: ``Linearity``  ``Planarity``  ``Scattering``
+and  ``Verticality``
+
+Example
+-------------------------------------------------------------------------------
+
+.. code-block:: json
+
+  [
+      "input.las",
+      {
+          "type":"filters.dimensionality",
+          "knn":8,
+          "threads": 2
+      },
+      {
+          "type":"writers.bpf",
+          "filename":"output.las",
+          "output_dims":"X,Y,Z,Linearity,Planarity,Scattering,Verticality"
+      }
+  ]
+
+Options
+-------------------------------------------------------------------------------
+
+knn
+  The number of k nearest neighbors used for calculating the covariance matrix. [Default: 10]
+
+threads
+  The number of threads used for computing the feature descriptors
+

filters/LocalFeaturesFilter.cpp → filters/DimensionalityFilter.cpp

@@ -36,7 +36,7 @@
 // WEAKLY SUPERVISED SEGMENTATION-AIDED CLASSIFICATION OF URBANSCENES FROM 3D LIDAR POINT CLOUDS
 // Stéphane Guinard, Loïc Landrieu, 2017
 
-#include "LocalFeaturesFilter.hpp"
+#include "DimensionalityFilter.hpp"
 
 #include <pdal/EigenUtils.hpp>
 #include <pdal/KDIndex.hpp>
@@ -53,33 +53,33 @@ namespace pdal
 
 static StaticPluginInfo const s_info
 {
-    "filters.localfeatures",
-    "Filter that calculates local features based on the covariance matrix",
-    "http://pdal.io/stages/filters.localfeatures.html"
+    "filters.dimensionality",
+    "Filter that calculates local features that capture the dimensionality of a neighborhood.",
+    "http://pdal.io/stages/filters.dimensionality.html"
 };
 
-CREATE_STATIC_STAGE(LocalFeaturesFilter, s_info)
+CREATE_STATIC_STAGE(DimensionalityFilter, s_info)
 
-std::string LocalFeaturesFilter::getName() const
+std::string DimensionalityFilter::getName() const
 {
     return s_info.name;
 }
 
-void LocalFeaturesFilter::addArgs(ProgramArgs& args)
+void DimensionalityFilter::addArgs(ProgramArgs& args)
 {
     args.add("knn", "k-Nearest neighbors", m_knn, 10);
     args.add("threads", "Number of threads used to run this filter", m_threads, 1);
 }
 
-void LocalFeaturesFilter::addDimensions(PointLayoutPtr layout)
+void DimensionalityFilter::addDimensions(PointLayoutPtr layout)
 {
     m_linearity = layout->registerOrAssignDim("Linearity", Dimension::Type::Float);
     m_planarity = layout->registerOrAssignDim("Planarity", Dimension::Type::Float);
     m_scattering = layout->registerOrAssignDim("Scattering", Dimension::Type::Float);
     m_verticality = layout->registerOrAssignDim("Verticality", Dimension::Type::Float);
 }
 
-void LocalFeaturesFilter::filter(PointView& view)
+void DimensionalityFilter::filter(PointView& view)
 {
 
     KD3Index& kdi = view.build3dIndex();
@@ -100,7 +100,7 @@ void LocalFeaturesFilter::filter(PointView& view)
         t.join();
 }
 
-void LocalFeaturesFilter::setSinglePoint(PointView &view, const PointId &id, const KD3Index &kdi)
+void DimensionalityFilter::setSinglePoint(PointView &view, const PointId &id, const KD3Index &kdi)
 {
     using namespace Eigen;
 
@@ -130,9 +130,9 @@ void LocalFeaturesFilter::setSinglePoint(PointView &view, const PointId &id, con
         v3[i] = eigenVectors.col(0)(i);
     }
 
-    float linearity  = (std::sqrtf(lambda[0]) - std::sqrtf(lambda[1])) / std::sqrtf(lambda[0]);
-    float planarity  = (std::sqrtf(lambda[1]) - std::sqrtf(lambda[2])) / std::sqrtf(lambda[0]);
-    float scattering =  std::sqrtf(lambda[2]) / std::sqrtf(lambda[0]);
+    float linearity  = (sqrtf(lambda[0]) - sqrtf(lambda[1])) / sqrtf(lambda[0]);
+    float planarity  = (sqrtf(lambda[1]) - sqrtf(lambda[2])) / sqrtf(lambda[0]);
+    float scattering =  sqrtf(lambda[2]) / sqrtf(lambda[0]);
     view.setField(m_linearity, id, linearity);
     view.setField(m_planarity, id, planarity);
     view.setField(m_scattering, id, scattering);
@@ -141,10 +141,10 @@ void LocalFeaturesFilter::setSinglePoint(PointView &view, const PointId &id, con
     float norm = 0;
     for (int i=0; i <3 ; i++)
     {
-        unary_vector[i] = lambda[0] * std::fabsf(v1[i]) + lambda[1] * std::fabsf(v2[i]) + lambda[2] * std::fabsf(v3[i]);
+        unary_vector[i] = lambda[0] * fabsf(v1[i]) + lambda[1] * fabsf(v2[i]) + lambda[2] * fabsf(v3[i]);
         norm += unary_vector[i] * unary_vector[i];
     }
-    norm = std::sqrt(norm);
+    norm = sqrtf(norm);
     view.setField(m_verticality, id, unary_vector[2] / norm);
 }
 

filters/LocalFeaturesFilter.hpp → filters/DimensionalityFilter.hpp

@@ -40,12 +40,12 @@
 
 namespace pdal {
 
-class PDAL_DLL LocalFeaturesFilter: public Filter
+class PDAL_DLL DimensionalityFilter: public Filter
 {
 public:
-    LocalFeaturesFilter() : Filter() {}
-    LocalFeaturesFilter &operator=(const LocalFeaturesFilter &) = delete;
-    LocalFeaturesFilter(const LocalFeaturesFilter &) = delete;
+    DimensionalityFilter() : Filter() {}
+    DimensionalityFilter &operator=(const DimensionalityFilter &) = delete;
+    DimensionalityFilter(const DimensionalityFilter &) = delete;
 
     std::string getName() const;
 

test/unit/CMakeLists.txt

@@ -221,6 +221,7 @@ PDAL_ADD_TEST(pdal_filters_crop_test
 PDAL_ADD_TEST(pdal_filters_decimation_test FILES
     filters/DecimationFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_delaunay_test FILES filters/DelaunayFilterTest.cpp)
+PDAL_ADD_TEST(pdal_filters_dimensionality_test FILES filters/DimensionalityTest.cpp)
 PDAL_ADD_TEST(pdal_filters_divider_test FILES filters/DividerFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_mongoexpression_test
     FILES
@@ -236,7 +237,6 @@ PDAL_ADD_TEST(pdal_filters_ferry_test FILES filters/FerryFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_groupby_test FILES filters/GroupByFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_ht_test FILES filters/HeadTailFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_info_test FILES filters/InfoFilterTest.cpp)
-PDAL_ADD_TEST(pdal_filters_localfeatures_test FILES filters/LocalFeaturesTest.cpp)
 PDAL_ADD_TEST(pdal_filters_neighborclassifier_test FILES filters/NeighborClassifierFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_locate_test FILES filters/LocateFilterTest.cpp)
 PDAL_ADD_TEST(pdal_filters_merge_test FILES filters/MergeTest.cpp)

test/unit/filters/LocalFeaturesTest.cpp → test/unit/filters/DimensionalityTest.cpp

@@ -37,21 +37,21 @@
 #include <pdal/PointView.hpp>
 #include <io/BufferReader.hpp>
 #include <io/TextReader.hpp>
-#include <filters/LocalFeaturesFilter.hpp>
+#include <filters/DimensionalityFilter.hpp>
 
 #include "Support.hpp"
 
 namespace pdal {
 
-TEST(LocalFeaturesTest, Linearity)
+TEST(DimensionalityTest, Linearity)
 {
     using namespace Dimension;
 
     PointTable table;
     table.layout()->registerDims({Id::X, Id::Y, Id::Z});
 
     BufferReader bufferReader;
-    LocalFeaturesFilter filter;
+    DimensionalityFilter filter;
     Options ops;
     ops.add("knn", 3);
     filter.setInput(bufferReader);
@@ -87,15 +87,15 @@ TEST(LocalFeaturesTest, Linearity)
     }
 }
 
-TEST(LocalFeaturesTest, Planarity)
+TEST(DimensionalityTest, Planarity)
 {
     using namespace Dimension;
 
     PointTable table;
     table.layout()->registerDims({Id::X, Id::Y, Id::Z});
 
     BufferReader bufferReader;
-    LocalFeaturesFilter filter;
+    DimensionalityFilter filter;
     Options ops;
     filter.setInput(bufferReader);
     filter.prepare(table);
@@ -134,15 +134,15 @@ TEST(LocalFeaturesTest, Planarity)
     }
 }
 
-TEST(LocalFeaturesTest, Scattering)
+TEST(DimensionalityTest, Scattering)
 {
     using namespace Dimension;
 
     PointTable table;
     table.layout()->registerDims({Id::X, Id::Y, Id::Z});
 
     BufferReader bufferReader;
-    LocalFeaturesFilter filter;
+    DimensionalityFilter filter;
     Options ops;
     filter.setInput(bufferReader);
     filter.prepare(table);