mirror of https://github.com/CGAL/cgal
Update doc
This commit is contained in:
Simon Giraudot
parent
502e32e97b
commit
2dbff97e6c
|
|
@ -6,21 +6,23 @@ namespace CGAL {
|
|||
\cgalAutoToc
|
||||
\author Simon Giraudot
|
||||
|
||||
This component implements a generalization of the algorithm described in \cgalCite{cgal:lm-clscm-12}. It classifies a data set into a user-defined set of classes (such as ground, vegetation, buildings, etc.). A flexible API is provided so that the user can classify any type of data, compute its own local attributes on the point cloud and define its own classes based on these attributes.
|
||||
This component implements a generalization of the algorithm described in \cgalCite{cgal:lm-clscm-12}. It classifies a data set into a user-defined set of classification types (such as ground, vegetation, buildings, etc.). A flexible API is provided so that the user can classify any type of data, compute its own local attributes on the point cloud and define its own classification types based on these attributes.
|
||||
|
||||
\section Classification_Organization Package Organization
|
||||
|
||||
%Classification of point sets is achieved as follows:
|
||||
%Classification of data sets is achieved as follows:
|
||||
|
||||
- some analysis is performed on the input point set;
|
||||
- some analysis is performed on the input data set;
|
||||
- attributes are computed based on this analysis;
|
||||
- a set of classification types (for example: ground, building, vegetation) is defined by the user;
|
||||
- attributes are given weights and each pair of attribute/type is assigned a relationship;
|
||||
- classification is computed pointwise by minimizing an energy defined as the sum of the values taken by attributes on input points (which depend on the attribute/type relationship)
|
||||
- classification is computed item-wise by minimizing an energy defined as the sum of the values taken by attributes on input items (which depend on the attribute/type relationship)
|
||||
- additional regularization can be used by smoothing either locally or globally through an Alpha Expansion approach.
|
||||
|
||||
This package is designed to be easily extended by the user: more specifically, attributes and types can be defined by the user to handle any data he/she needs to classify (although \cgal provides a predefined framework for common urban scenes).
|
||||
|
||||
Currently, \cgal provides data structures to handle classification of point sets.
|
||||
|
||||
\cgalFigureBegin{Classification_Organization,organization.png}
|
||||
Organization of the package.
|
||||
\cgalFigureEnd
|
||||
|
|
@ -29,13 +31,13 @@ Organization of the package.
|
|||
|
||||
\subsection Classification_analysis Analysis
|
||||
|
||||
%Classification is based on the computation of local attributes of points. These attributes often require precomputed analysis structures: such data structures might be shared by several attributes and are therefore computed separately.
|
||||
%Classification is based on the computation of local attributes. These attributes often require precomputed analysis structures: such data structures might be shared by several attributes and are therefore computed separately.
|
||||
|
||||
\cgal provides the following structures:
|
||||
|
||||
- `CGAL::Classification::Point_set_neighborhood` stores spatial searching structures and provides adapted queries for points;
|
||||
- `CGAL::Classification::Local_eigen_analysis` precomputes covariance matrices on local neighborhood of points and stores the associated eigenvectors and eigenvalues;
|
||||
- `CGAL::Classification::Planimetric_grid` is a 2D grid used for digital terrain modeling.
|
||||
- [Point_set_neighborhood](@ref CGAL::Classification::Point_set_neighborhood) stores spatial searching structures and provides adapted queries for points;
|
||||
- [Local_eigen_analysis](@ref CGAL::Classification::Local_eigen_analysis) precomputes covariance matrices on local neighborhoods of points and stores the associated eigenvectors and eigenvalues;
|
||||
- [Planimetric_grid](@ref CGAL::Classification::Planimetric_grid) is a 2D grid used for digital terrain modeling.
|
||||
|
||||
The following code snippet shows how to instantiate such data structures from an input PLY point set (the full example is given at the end of the manual).
|
||||
|
||||
|
|
@ -43,34 +45,36 @@ The following code snippet shows how to instantiate such data structures from an
|
|||
|
||||
\subsection Classification_attributes Attributes
|
||||
|
||||
Attributes are defined as scalar fields that associate each input point with a specific value. In the \cgal classification framework, an abstract class `CGAL::Classification::Attribute` defines what method the attribute must provide. All attributes must inherit this class. The attributes provided by \cgal are generally sufficient to handle most cases. However, the user may want to define its own attributes, especially if the input point set comes with additional properties that were not anticipated by \cgal. A user-defined attribute must inherit `CGAL::Classification::Attribute` and provide a method `value()` that associate a scalar value to each input point.
|
||||
Attributes are defined as scalar fields that associate each input point with a specific value. The attributes provided by \cgal are generally sufficient to handle most cases. However, the user may want to define its own attributes, especially if the input point set comes with additional properties that were not anticipated by \cgal.
|
||||
|
||||
A user-defined attribute must inherit `CGAL::Classification::Attribute` and provide a method `value()` that associate a scalar value to each input point.
|
||||
|
||||
Attributes are accessed through `Handle` objects, `CGAL::Classification::Attribute_handle`.
|
||||
|
||||
\cgal provides some predefined attributes that make sense in urban scene classification:
|
||||
\cgal provides some predefined attributes that are relevant for classification of urban scenes:
|
||||
|
||||
- `CGAL::Classification::Attribute_distance_to_plane` measures how far away a point is from a locally estimated plane
|
||||
- `CGAL::Classification::Attribute_elevation` estimates the local distance to an estimated ground
|
||||
- `CGAL::Classification::Attribute_vertical_dispersion` computes how noisy the point set is on a local Z-cylinder
|
||||
- `CGAL::Classification::Attribute_verticality` compares the local normal vector to the vertical vector.
|
||||
- [Attribute_distance_to_plane](@ref CGAL::Classification::Attribute_distance_to_plane) measures how far away a point is from a locally estimated plane
|
||||
- [Attribute_elevation](@ref CGAL::Classification::Attribute_elevation) computes the local distance to an estimation of the ground
|
||||
- [Attribute_vertical_dispersion](@ref CGAL::Classification::Attribute_vertical_dispersion) computes how noisy the point set is on a local Z-cylinder
|
||||
- [Attribute_verticality](@ref CGAL::Classification::Attribute_verticality) compares the local normal vector to the vertical vector.
|
||||
|
||||
For more details about how these different attributes can help identifying one classification type or the other, please refer to their associated reference manual pages. In addition, \cgal also provides attributes solely based on the local eigen values \cgalCite{cgal:mbrsh-raofw-11}. Such attributes are less easy to relate to a specific classification type but can still be useful:
|
||||
For more details about how these different attributes can help identifying one classification type or the other, please refer to their associated reference manual pages. In addition, \cgal also provides attributes solely based on the local eigen values \cgalCite{cgal:mbrsh-raofw-11}. Such attributes are more theoretical and harder to relate to a specific use case, but they can help differenciating some classification types:
|
||||
|
||||
- `CGAL::Classification::Attribute_anisotropy`
|
||||
- `CGAL::Classification::Attribute_eigentropy`
|
||||
- `CGAL::Classification::Attribute_linearity`
|
||||
- `CGAL::Classification::Attribute_omnivariance`
|
||||
- `CGAL::Classification::Attribute_planarity`
|
||||
- `CGAL::Classification::Attribute_sphericity`
|
||||
- `CGAL::Classification::Attribute_sum_eigenvalues`
|
||||
- `CGAL::Classification::Attribute_surface_variation`.
|
||||
- [Attribute_anisotropy](@ref CGAL::Classification::Attribute_anisotropy)
|
||||
- [Attribute_eigentropy](@ref CGAL::Classification::Attribute_eigentropy)
|
||||
- [Attribute_linearity](@ref CGAL::Classification::Attribute_linearity)
|
||||
- [Attribute_omnivariance](@ref CGAL::Classification::Attribute_omnivariance)
|
||||
- [Attribute_planarity](@ref CGAL::Classification::Attribute_planarity)
|
||||
- [Attribute_sphericity](@ref CGAL::Classification::Attribute_sphericity)
|
||||
- [Attribute_sum_eigenvalues](@ref CGAL::Classification::Attribute_sum_eigenvalues)
|
||||
- [Attribute_surface_variation](@ref CGAL::Classification::Attribute_surface_variation)
|
||||
|
||||
Finally, if the input point set has additional properties, these can also be used as attributes. For example, \cgal provides the following attributes:
|
||||
|
||||
- `CGAL::Classification::Attribute_echo_scatter` uses the number of returns (echo) provided by most LIDAR scanners if available
|
||||
- `CGAL::Classification::Attribute_hsv` uses input color information if available.
|
||||
- [Attribute_echo_scatter](@ref CGAL::Classification::Attribute_echo_scatter) uses the number of returns (echo) provided by most LIDAR scanners if available
|
||||
- [Attribute_hsv](@ref CGAL::Classification::Attribute_hsv) uses input color information if available.
|
||||
|
||||
In the following code snippet, a subset of these attributes are instantiated, their weights are set and they are added to a newly created classification object:
|
||||
In the following code snippet, a subset of these attributes are instantiated, their weights are set and they are added to a newly created classifier:
|
||||
|
||||
\snippet Classification/example_point_set_classification.cpp Attributes
|
||||
|
||||
|
|
@ -80,9 +84,9 @@ A classification type represents how a point should be classified, for example:
|
|||
|
||||
\cgal provides a class `CGAL::Classification::Type` to define such a set of attribute effects, along with the associated `Handle` object: `CGAL::Classification::Type_handle`. Each type may define how a specific attribute affects it:
|
||||
|
||||
- `FAVORED_ATT`: the type is favored by high values of the attribute
|
||||
- `NEUTRAL_ATT`: the type is not affected by the attribute
|
||||
- `PENALIZED_ATT`: the type is favored by low values of the attribute
|
||||
- [FAVORED_ATT](@ref CGAL::Classification::Type::FAVORED_ATT): the type is favored by high values of the attribute
|
||||
- [NEUTRAL_ATT](@ref CGAL::Classification::Type::NEUTRAL_ATT): the type is not affected by the attribute
|
||||
- [PENALIZED_ATT](@ref CGAL::Classification::Type::PENALIZED_ATT): the type is favored by low values of the attribute
|
||||
|
||||
Let \f$x=(x_i)_{i=1..N_c}\f$ be a potential classification result with \f$N_c\f$ the number of input points and \f$x_i\f$ the class of the \f$i^{th}\f$ point (for example: vegetation, ground, etc.). Let \f$a_j(i)\f$ be the raw value of the \f$j^{th}\f$ attribute at the \f$i^{th}\f$ point and \f$w_j\f$ be the weight of this attribute. We define the normalized value of the \f$j^{th}\f$ attribute at the \f$i^{th}\f$ point as follows:
|
||||
|
||||
|
|
@ -99,11 +103,11 @@ The following code snippet shows how to add types to the classification object a
|
|||
|
||||
\subsection Classification_regularization Regularization
|
||||
|
||||
%Classification is performed by minizing an energy over the input point set. This energy can be regularized with different methods. \cgal provides 3 different methods for classification, ranging from high speed / low quality to low speed / high quality:
|
||||
%Classification is performed by minizing an energy over the input point set that may include regularization. \cgal provides 3 different methods for classification, ranging from high speed / low quality to low speed / high quality:
|
||||
|
||||
- `CGAL::Point_set_classification::run()`
|
||||
- `CGAL::Point_set_classification::run_with_local_smoothing()`
|
||||
- `CGAL::Point_set_classification::run_with_graphcut()`
|
||||
- `CGAL::Classifier::run()`
|
||||
- `CGAL::Classifier::run_with_local_smoothing()`
|
||||
- `CGAL::Classifier::run_with_graphcut()`
|
||||
|
||||
On a point set of 3 millions points, the first method takes about 4 seconds, the second about 40 seconds and the third about 2 minutes.
|
||||
|
||||
|
|
@ -116,7 +120,7 @@ Mathematical details are provided hereafter.
|
|||
|
||||
\subsubsection Classification_regularized_no No Regularization
|
||||
|
||||
- `CGAL::Point_set_classification::run()`: this is the fastest method
|
||||
- `CGAL::Classifier::run()`: this is the fastest method
|
||||
that provides acceptable but usually noisy results (see Figure
|
||||
\cgalFigureRef{Classification_image}, top-right).
|
||||
|
||||
|
|
@ -137,14 +141,14 @@ This energy is a sum of pointwise energies and involves no regularization. Let \
|
|||
|
||||
\subsubsection Classification_regularized_local Local Smoothing
|
||||
|
||||
- `CGAL::Point_set_classification::run_with_local_smoothing()`: this
|
||||
- `CGAL::Classifier::run_with_local_smoothing()`: this
|
||||
method is a tradeoff between quality and efficiency (see Figure
|
||||
\cgalFigureRef{Classification_image}, bottom-left). The minimized
|
||||
energy is defined as follows:
|
||||
|
||||
|
||||
\f[
|
||||
E(x) = \sum_{i = 1..N_c} E_{di}(x_i)
|
||||
E(x) = \sum_{i = 1..N_c} E_{si}(x_i)
|
||||
\f]
|
||||
|
||||
The pointwise energy \f$E_{di}(x_i)\f$ is replaced by
|
||||
|
|
@ -162,7 +166,7 @@ increases the noise reduction at the cost of higher computation times.
|
|||
|
||||
\subsubsection Classification_regularized_graphcut Global Regularization (Graph Cut)
|
||||
|
||||
- `CGAL::Point_set_classification::run_with_graphcut()`: this method
|
||||
- `CGAL::Classifier::run_with_graphcut()`: this method
|
||||
offers the best quality but requires longer computation time (see
|
||||
Figure \cgalFigureRef{Classification_image}, bottom-right). The
|
||||
total energy that is minimized is the sum of the partial data term
|
||||
|
|
@ -182,9 +186,9 @@ A Graph Cut based algorithm (Alpha Expansion) is used to quickly reach
|
|||
an approximate solution close to the global optimum of this energy.
|
||||
|
||||
This method allows to consistently segment the input point set in
|
||||
piecewise constant parts and to eliminate global variations of
|
||||
assigned classification types. Increasing \f$\gamma\f$ produces more
|
||||
regular result with a constant computation time.
|
||||
piecewise constant parts and to correct large wrongly classified
|
||||
clusters. Increasing \f$\gamma\f$ produces more regular result with a
|
||||
constant computation time.
|
||||
|
||||
|
||||
|
||||
|
|
@ -213,9 +217,9 @@ The classification algorithm is designed to be as flexible as possible: the user
|
|||
|
||||
\section Classification_training Training
|
||||
|
||||
%Classification is based on relationships between attributes and types. Each attribute has a specific weight and each pair of attribute/type has a specific effect. This means that the number of parameters to set up becomes rapidly large: if 6 attributes are used to classify between 4 classification types, 30 parameters have to be set up.
|
||||
%Classification is based on relationships between attributes and types. Each attribute has a specific weight and each pair of attribute/type has a specific effect. This means that the number of parameters to set up can quickly explode: if 6 attributes are used to classify between 4 classification types, 30 parameters have to be set up.
|
||||
|
||||
Though it is possible to set them one by one, \cgal also provides a training algorithm that requires a small set of ground truth points provided by the user. More specifically, the user must provide, for each classification type he/she wants to classify, a set of known inliers among the input point set (for example, selecting one roof, one tree, one section of the ground). The training algorithm works as follows:
|
||||
Though it is possible to set them up one by one, \cgal also provides a training algorithm that requires a small set of ground truth points provided by the user. More specifically, the user must provide, for each classification type he/she wants to classify, a set of known inliers among the input point set (for example, selecting one roof, one tree and one section of the ground). The training algorithm works as follows:
|
||||
|
||||
- for each attribute, a range of weights is tested: the effects each attribute have on each type is estimated. For a given weight, if an attribute has the same effect on each type, it is non-relevant for classification. The range of weights such that the attribute is relevant is estimated;
|
||||
|
||||
|
|
@ -223,7 +227,7 @@ Though it is possible to set them one by one, \cgal also provides a training alg
|
|||
|
||||
- each ground truth points provided by the user is classified using this set of weights and effects;
|
||||
|
||||
- for each classification type, the ratio of correctly classified ground truth points is computed. The minimum of this ratios is used as a score for this set of weights and effects: a ratio of 0.8 means that for each classification type, at least 80\% of the provided ground truth point were correctly classified;
|
||||
- for each classification type, the ratio of correctly classified ground truth points is computed. The minimum of these ratios is used as a score for this set of weights and effects: a ratio of 0.8 means that for each classification type, at least 80\% of the provided ground truth point were correctly classified;
|
||||
|
||||
- the same mechanism is repeated until all attributes' ranges have been tested. Weights are only changed one by one, the other ones kept to the previous value that gave the best score.
|
||||
|
||||
|
|
|
|||
|
|
@ -21,7 +21,7 @@ typedef Kernel::Iso_cuboid_3 Iso_cuboid_3;
|
|||
typedef std::vector<Point>::iterator Iterator;
|
||||
typedef CGAL::Identity_property_map<Point> Pmap;
|
||||
|
||||
typedef CGAL::Classifier<Iterator, Pmap> Classification;
|
||||
typedef CGAL::Classifier<Iterator, Pmap> Classifier;
|
||||
|
||||
typedef CGAL::Classification::Planimetric_grid<Kernel, Iterator, Pmap> Planimetric_grid;
|
||||
typedef CGAL::Classification::Point_set_neighborhood<Kernel, Iterator, Pmap> Neighborhood;
|
||||
|
|
@ -99,7 +99,7 @@ int main (int argc, char** argv)
|
|||
|
||||
|
||||
// Add attributes to classification object
|
||||
Classification psc (pts.begin (), pts.end(), Pmap());
|
||||
Classifier psc (pts.begin (), pts.end(), Pmap());
|
||||
psc.add_attribute (d2p);
|
||||
psc.add_attribute (lin);
|
||||
psc.add_attribute (omni);
|
||||
|
|
|
|||
Loading…
Reference in New Issue