.. _PCA:
.. currentmodule:: LaserPy

PCA
===

Principle Component Analysis on regions of 3D points.  This is sort of like
fitting an ellipsoid to a region.  It provides good surface normals, and can be
used to distinguish flat, thin and scattered regions (like tree canopies), as
in [lalonde2006natural]_. It's likely the fastest feature here, the main slow-down is in
selecting the 3D regions in the first place.

If you just want surface normals, see :func:`surfNormPCA`. If you want the full
eigenvalues and eigenvectors, see :class:`PCA`.  PCA can also be used to
generate :ref:`keypoints <pca-keypoints>` at highly flat or linear regions, as
in [quadros2012feature]_.

Also note that the points in your 3D region should be representative of the
shape- in velodyne data, some regions on the ground are just a single line,
which PCA will interpret as a thin linear region. See [quadros2012feature]_ for
a simple check, implemented in :func:`minRadiusSelection`.

.. [lalonde2006natural] J.F. Lalonde, N. Vandapel, D.F. Huber, and M. Hebert.
   Natural terrain classification using three-dimensional ladar data for ground
   robot mobility. Journal of Field Robotics, 23(10):839–861, 2006.

.. autoclass:: PCA
   :members:


surfNormPCA
^^^^^^^^^^^

.. autofunction:: surfNormPCA


minRadiusSelection
^^^^^^^^^^^^^^^^^^

.. autofunction:: minRadiusSelection