Module segmentation

## Detailed Description

# Overview

The pcl_segmentation library contains algorithms for segmenting a point cloud into distinct clusters. These algorithms are best suited to processing a point cloud that is composed of a number of spatially isolated regions. In such cases, clustering is often used to break the cloud down into its constituent parts, which can then be processed independently.

# Requirements

- common
- search
- sample_consensus
- kdtree
- octree

## Classes

class | pcl::ConditionalEuclideanClustering< PointT >
| ConditionalEuclideanClustering performs segmentation based on Euclidean distance and a user-defined clustering condition. More...
class | pcl::EuclideanClusterExtraction< PointT >
| EuclideanClusterExtraction represents a segmentation class for cluster extraction in an Euclidean sense. More...
class | pcl::LabeledEuclideanClusterExtraction< PointT >
| LabeledEuclideanClusterExtraction represents a segmentation class for cluster extraction in an Euclidean sense, with label info. More...
class | pcl::ExtractPolygonalPrismData< PointT >
| ExtractPolygonalPrismData uses a set of point indices that represent a planar model, and together with a given height, generates a 3D polygonal prism. More...
class | pcl::GrabCut< PointT >
| Implementation of the GrabCut segmentation in "GrabCut — Interactive Foreground Extraction using Iterated Graph Cuts" by Carsten Rother, Vladimir Kolmogorov and Andrew Blake. More...
class | pcl::SACSegmentation< PointT >
| SACSegmentation represents the Nodelet segmentation class for Sample Consensus methods and models, in the sense that it just creates a Nodelet wrapper for generic-purpose SAC-based segmentation. More...
class | pcl::SACSegmentationFromNormals< PointT, PointNT >
| SACSegmentationFromNormals represents the PCL nodelet segmentation class for Sample Consensus methods and models that require the use of surface normals for estimation. More...
class | pcl::SeededHueSegmentation
| SeededHueSegmentation. More...
class | pcl::SegmentDifferences< PointT >
| SegmentDifferences obtains the difference between two spatially aligned point clouds and returns the difference between them for a maximum given distance threshold. More...

## Functions

template<typename PointT >
void | pcl::extractEuclideanClusters (const PointCloud< PointT > &cloud, const boost::shared_ptr< search::Search< PointT > > &tree, float tolerance, std::vector< PointIndices > &clusters, unsigned int min_pts_per_cluster=1, unsigned int max_pts_per_cluster=(std::numeric_limits< int >::max)())
| Decompose a region of space into clusters based on the Euclidean distance between points. More...
template<typename PointT >
void | pcl::extractEuclideanClusters (const PointCloud< PointT > &cloud, const std::vector< int > &indices, const boost::shared_ptr< search::Search< PointT > > &tree, float tolerance, std::vector< PointIndices > &clusters, unsigned int min_pts_per_cluster=1, unsigned int max_pts_per_cluster=(std::numeric_limits< int >::max)())
| Decompose a region of space into clusters based on the Euclidean distance between points. More...
template<typename PointT , typename Normal >
void | pcl::extractEuclideanClusters (const PointCloud< PointT > &cloud, const PointCloud< Normal > &normals, float tolerance, const boost::shared_ptr< KdTree< PointT > > &tree, std::vector< PointIndices > &clusters, double eps_angle, unsigned int min_pts_per_cluster=1, unsigned int max_pts_per_cluster=(std::numeric_limits< int >::max)())
| Decompose a region of space into clusters based on the euclidean distance between points, and the normal angular deviation. More...
template<typename PointT , typename Normal >
void | pcl::extractEuclideanClusters (const PointCloud< PointT > &cloud, const PointCloud< Normal > &normals, const std::vector< int > &indices, const boost::shared_ptr< KdTree< PointT > > &tree, float tolerance, std::vector< PointIndices > &clusters, double eps_angle, unsigned int min_pts_per_cluster=1, unsigned int max_pts_per_cluster=(std::numeric_limits< int >::max)())
| Decompose a region of space into clusters based on the euclidean distance between points, and the normal angular deviation. More...
bool | pcl::comparePointClusters (const pcl::PointIndices &a, const pcl::PointIndices &b)
| Sort clusters method (for std::sort). More...
template<typename PointT >
void | pcl::extractLabeledEuclideanClusters (const PointCloud< PointT > &cloud, const boost::shared_ptr< search::Search< PointT > > &tree, float tolerance, std::vector< std::vector< PointIndices > > &labeled_clusters, unsigned int min_pts_per_cluster=1, unsigned int max_pts_per_cluster=std::numeric_limits< unsigned int >::max(), unsigned int max_label=std::numeric_limits< unsigned int >::max())
| Decompose a region of space into clusters based on the Euclidean distance between points. More...
bool | pcl::compareLabeledPointClusters (const pcl::PointIndices &a, const pcl::PointIndices &b)
| Sort clusters method (for std::sort). More...
template<typename PointT >
bool | pcl::isPointIn2DPolygon (const PointT &point, const pcl::PointCloud< PointT > &polygon)
| General purpose method for checking if a 3D point is inside or outside a given 2D polygon. More...
template<typename PointT >
bool | pcl::isXYPointIn2DXYPolygon (const PointT &point, const pcl::PointCloud< PointT > &polygon)
| Check if a 2d point (X and Y coordinates considered only!) is inside or outside a given polygon. More...
void | pcl::seededHueSegmentation (const PointCloud< PointXYZRGB > &cloud, const boost::shared_ptr< search::Search< PointXYZRGB > > &tree, float tolerance, PointIndices &indices_in, PointIndices &indices_out, float delta_hue=0.0)
| Decompose a region of space into clusters based on the Euclidean distance between points. More...
void | pcl::seededHueSegmentation (const PointCloud< PointXYZRGB > &cloud, const boost::shared_ptr< search::Search< PointXYZRGBL > > &tree, float tolerance, PointIndices &indices_in, PointIndices &indices_out, float delta_hue=0.0)
| Decompose a region of space into clusters based on the Euclidean distance between points. More...
template<typename PointT >
void | pcl::getPointCloudDifference (const pcl::PointCloud< PointT > &src, const pcl::PointCloud< PointT > &tgt, double threshold, const boost::shared_ptr< pcl::search::Search< PointT > > &tree, pcl::PointCloud< PointT > &output)
| Obtain the difference between two aligned point clouds as another point cloud, given a distance threshold. More...

## Function Documentation

bool pcl::compareLabeledPointClusters | ( | const pcl::PointIndices & | a,
|  | const pcl::PointIndices & | b
| ) |  |

inline

Sort clusters method (for std::sort).

Definition at line 183 of file extract_labeled_clusters.h.

References pcl::PointIndices::indices.

bool pcl::comparePointClusters | ( | const pcl::PointIndices & | a,
|  | const pcl::PointIndices & | b
| ) |  |

inline

Sort clusters method (for std::sort).

Definition at line 418 of file extract_clusters.h.

References pcl::PointIndices::indices.

Referenced by pcl::LabeledEuclideanClusterExtraction< PointT >::extract(), and pcl::EuclideanClusterExtraction< PointT >::extract().

template<typename PointT >

void pcl::extractEuclideanClusters | ( | const PointCloud< PointT > & | cloud,
|  | const boost::shared_ptr< search::Search< PointT > > & | tree,
|  | float | tolerance,
|  | std::vector< PointIndices > & | clusters,
|  | unsigned int | min_pts_per_cluster = `1`,
|  | unsigned int | max_pts_per_cluster = `(std::numeric_limits<int>::max) ()`
| ) |  |

Decompose a region of space into clusters based on the Euclidean distance between points.

Parameters

  cloud | the point cloud message
  tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  tolerance | the spatial cluster tolerance as a measure in L2 Euclidean space
  clusters | the resultant clusters containing point indices (as a vector of PointIndices)
  min_pts_per_cluster | minimum number of points that a cluster may contain (default: 1)
  max_pts_per_cluster | maximum number of points that a cluster may contain (default: max int)

Definition at line 45 of file extract_clusters.hpp.

References pcl::PointIndices::header, pcl::PointCloud< PointT >::header, pcl::PointIndices::indices, and pcl::PointCloud< PointT >::points.

Referenced by pcl::EuclideanClusterExtraction< PointT >::extract().

template<typename PointT >

void pcl::extractEuclideanClusters | ( | const PointCloud< PointT > & | cloud,
|  | const std::vector< int > & | indices,
|  | const boost::shared_ptr< search::Search< PointT > > & | tree,
|  | float | tolerance,
|  | std::vector< PointIndices > & | clusters,
|  | unsigned int | min_pts_per_cluster = `1`,
|  | unsigned int | max_pts_per_cluster = `(std::numeric_limits<int>::max) ()`
| ) |  |

Decompose a region of space into clusters based on the Euclidean distance between points.

Parameters

  cloud | the point cloud message
  indices | a list of point indices to use from cloud
  tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud and indices

Parameters

  tolerance | the spatial cluster tolerance as a measure in L2 Euclidean space
  clusters | the resultant clusters containing point indices (as a vector of PointIndices)
  min_pts_per_cluster | minimum number of points that a cluster may contain (default: 1)
  max_pts_per_cluster | maximum number of points that a cluster may contain (default: max int)

Definition at line 118 of file extract_clusters.hpp.

References pcl::PointIndices::header, pcl::PointCloud< PointT >::header, pcl::PointIndices::indices, and pcl::PointCloud< PointT >::points.

template<typename PointT , typename Normal >

void pcl::extractEuclideanClusters | ( | const PointCloud< PointT > & | cloud,
|  | const PointCloud< Normal > & | normals,
|  | float | tolerance,
|  | const boost::shared_ptr< KdTree< PointT > > & | tree,
|  | std::vector< PointIndices > & | clusters,
|  | double | eps_angle,
|  | unsigned int | min_pts_per_cluster = `1`,
|  | unsigned int | max_pts_per_cluster = `(std::numeric_limits<int>::max) ()`
| ) |  |

Decompose a region of space into clusters based on the euclidean distance between points, and the normal angular deviation.

Parameters

  cloud | the point cloud message
  normals | the point cloud message containing normal information
  tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  tolerance | the spatial cluster tolerance as a measure in the L2 Euclidean space
  clusters | the resultant clusters containing point indices (as a vector of PointIndices)
  eps_angle | the maximum allowed difference between normals in radians for cluster/region growing
  min_pts_per_cluster | minimum number of points that a cluster may contain (default: 1)
  max_pts_per_cluster | maximum number of points that a cluster may contain (default: max int)

Definition at line 99 of file extract_clusters.h.

References pcl::PointIndices::header, pcl::PointCloud< PointT >::header, pcl::PointIndices::indices, and pcl::PointCloud< PointT >::points.

template<typename PointT , typename Normal >

void pcl::extractEuclideanClusters | ( | const PointCloud< PointT > & | cloud,
|  | const PointCloud< Normal > & | normals,
|  | const std::vector< int > & | indices,
|  | const boost::shared_ptr< KdTree< PointT > > & | tree,
|  | float | tolerance,
|  | std::vector< PointIndices > & | clusters,
|  | double | eps_angle,
|  | unsigned int | min_pts_per_cluster = `1`,
|  | unsigned int | max_pts_per_cluster = `(std::numeric_limits<int>::max) ()`
| ) |  |

Decompose a region of space into clusters based on the euclidean distance between points, and the normal angular deviation.

Parameters

  cloud | the point cloud message
  normals | the point cloud message containing normal information
  indices | a list of point indices to use from cloud
  tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  tolerance | the spatial cluster tolerance as a measure in the L2 Euclidean space
  clusters | the resultant clusters containing point indices (as PointIndices)
  eps_angle | the maximum allowed difference between normals in degrees for cluster/region growing
  min_pts_per_cluster | minimum number of points that a cluster may contain (default: 1)
  max_pts_per_cluster | maximum number of points that a cluster may contain (default: max int)

Definition at line 198 of file extract_clusters.h.

References pcl::PointIndices::header, pcl::PointCloud< PointT >::header, pcl::PointIndices::indices, and pcl::PointCloud< PointT >::points.

template<typename PointT >

void pcl::extractLabeledEuclideanClusters | ( | const PointCloud< PointT > & | cloud,
|  | const boost::shared_ptr< search::Search< PointT > > & | tree,
|  | float | tolerance,
|  | std::vector< std::vector< PointIndices > > & | labeled_clusters,
|  | unsigned int | min_pts_per_cluster = `1`,
|  | unsigned int | max_pts_per_cluster = `std::numeric_limits<unsigned int>::max ()`,
|  | unsigned int | max_label = `std::numeric_limits<unsigned int>::max ()`
| ) |  |

Decompose a region of space into clusters based on the Euclidean distance between points.

Parameters

  [in] | cloud | the point cloud message
  [in] | tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  [in] | tolerance | the spatial cluster tolerance as a measure in L2 Euclidean space
  [out] | labeled_clusters | the resultant clusters containing point indices (as a vector of PointIndices)
  [in] | min_pts_per_cluster | minimum number of points that a cluster may contain (default: 1)
  [in] | max_pts_per_cluster | maximum number of points that a cluster may contain (default: max int)
  [in] | max_label |

Definition at line 44 of file extract_labeled_clusters.hpp.

References pcl::PointIndices::header, pcl::PointCloud< PointT >::header, pcl::PointIndices::indices, and pcl::PointCloud< PointT >::points.

Referenced by pcl::LabeledEuclideanClusterExtraction< PointT >::extract().

template<typename PointT >

void pcl::getPointCloudDifference | ( | const pcl::PointCloud< PointT > & | src,
|  | const pcl::PointCloud< PointT > & | tgt,
|  | double | threshold,
|  | const boost::shared_ptr< pcl::search::Search< PointT > > & | tree,
|  | pcl::PointCloud< PointT > & | output
| ) |  |

Obtain the difference between two aligned point clouds as another point cloud, given a distance threshold.

Parameters

  src | the input point cloud source
  tgt | the input point cloud target we need to obtain the difference against
  threshold | the distance threshold (tolerance) for point correspondences. (e.g., check if f a point p1 from src has a correspondence > threshold than a point p2 from tgt)
  tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching built over tgt
  output | the resultant output point cloud difference

Definition at line 46 of file segment_differences.hpp.

References pcl::copyPointCloud(), pcl::PointCloud< PointT >::header, pcl::PointCloud< PointT >::height, pcl::PointCloud< PointT >::is_dense, pcl::isFinite(), pcl::PointCloud< PointT >::points, and pcl::PointCloud< PointT >::width.

Referenced by pcl::SegmentDifferences< PointT >::segment().

template<typename PointT >

bool pcl::isPointIn2DPolygon | ( | const PointT & | point,
|  | const pcl::PointCloud< PointT > & | polygon
| ) |  |

General purpose method for checking if a 3D point is inside or outside a given 2D polygon.

Note
  this method accepts any general 3D point that is projected onto the 2D polygon, but performs an internal XY projection of both the polygon and the point.

Parameters

  point | a 3D point projected onto the same plane as the polygon
  polygon | a polygon

Definition at line 47 of file extract_polygonal_prism_data.hpp.

References pcl::computeMeanAndCovarianceMatrix(), pcl::eigen33(), pcl::EIGEN_ALIGN16, pcl::isXYPointIn2DXYPolygon(), and pcl::PointCloud< PointT >::points.

template<typename PointT >

bool pcl::isXYPointIn2DXYPolygon | ( | const PointT & | point,
|  | const pcl::PointCloud< PointT > & | polygon
| ) |  |

Check if a 2d point (X and Y coordinates considered only!) is inside or outside a given polygon.

This method assumes that both the point and the polygon are projected onto the XY plane.

Note
  (This is highly optimized code taken from http://www.visibone.com/inpoly/) Copyright (c) 1995-1996 Galacticomm, Inc. Freeware source code.

Parameters

  point | a 3D point projected onto the same plane as the polygon
  polygon | a polygon

Definition at line 107 of file extract_polygonal_prism_data.hpp.

References pcl::PointCloud< PointT >::points.

Referenced by pcl::isPointIn2DPolygon(), and pcl::ExtractPolygonalPrismData< PointT >::segment().

void pcl::seededHueSegmentation | ( | const PointCloud< PointXYZRGB > & | cloud,
|  | const boost::shared_ptr< search::Search< PointXYZRGB > > & | tree,
|  | float | tolerance,
|  | PointIndices & | indices_in,
|  | PointIndices & | indices_out,
|  | float | delta_hue = `0.0`
| ) |  |

Decompose a region of space into clusters based on the Euclidean distance between points.

Parameters

  [in] | cloud | the point cloud message
  [in] | tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  [in] | tolerance | the spatial cluster tolerance as a measure in L2 Euclidean space
  [in] | indices_in | the cluster containing the seed point indices (as a vector of PointIndices)
  [out] | indices_out |
  [in] | delta_hue |

Definition at line 46 of file seeded_hue_segmentation.hpp.

References pcl::_PointXYZHSV::h, pcl::PointIndices::indices, pcl::PointCloud< PointT >::points, and pcl::PointXYZRGBtoXYZHSV().

Referenced by pcl::SeededHueSegmentation::segment().

void pcl::seededHueSegmentation | ( | const PointCloud< PointXYZRGB > & | cloud,
|  | const boost::shared_ptr< search::Search< PointXYZRGBL > > & | tree,
|  | float | tolerance,
|  | PointIndices & | indices_in,
|  | PointIndices & | indices_out,
|  | float | delta_hue = `0.0`
| ) |  |

Decompose a region of space into clusters based on the Euclidean distance between points.

Parameters

  [in] | cloud | the point cloud message
  [in] | tree | the spatial locator (e.g., kd-tree) used for nearest neighbors searching

Note
  the tree has to be created as a spatial locator on cloud

Parameters

  [in] | tolerance | the spatial cluster tolerance as a measure in L2 Euclidean space
  [in] | indices_in | the cluster containing the seed point indices (as a vector of PointIndices)
  [out] | indices_out |
  [in] | delta_hue |

Definition at line 122 of file seeded_hue_segmentation.hpp.

References pcl::_PointXYZHSV::h, pcl::PointIndices::indices, pcl::PointCloud< PointT >::points, and pcl::PointXYZRGBtoXYZHSV().