## Handbook

Welcome to the PCL Handbook. The purpose of this section is to provide a compendium of the algorithms implemented on PCL. The goal is to provide an introduction to the tools readily available on PCL.

Keep in mind this is a work in progress! More algorithms will be added to the list as time goes by!

### Modules

#### common

The pcl_common library contains the common data structures and methods used by the majority of PCL libraries. The core data structures include the `PointCloud` class and a multitude of point types that are used to represent points, surface normals, RGB color values, feature descriptors, etc. It also contains numerous functions for computing distances/norms, means and covariances, angular conversions, geometric transformations, and more.

#### features

The pcl_features library contains data structures and mechanisms for 3D feature estimation from point cloud data. 3D features are representations at a certain 3D point or position in space, which describe geometrical patterns based on the information available around the point. The data space selected around the query point is usually referred as the k-neighborhood. This module contains algorithms for computing a number of useful features, ranging from simple 3D surface normals to complex high-dimensional feature descriptors.

You can learn more about some of these features in the following tutorials:

#### filters

The pcl_filters library contains outlier and noise removal mechanisms for 3D point cloud data filtering applications.

Some examples of these filters can be found in the following tutorials:

#### io

The pcl_io library contains classes and functions for reading and writing point cloud data and capturing from OpenNI-compatible depth cameras.

An introduction to some of these capabilities can be found in the following tutorials:

#### kdtree

The pcl_kdtree library provides the kd-tree data-structure, using FLANN, that allows for fast nearest neighbor searches.

A Kd-tree (k-dimensional tree) is a space-partitioning data structure that stores a set of k-dimensional points in a tree structure that enables efficient range searches and nearest neighbor searches. Nearest neighbor searches are a core operation when working with point cloud data and can be used to find correspondences between groups of points or feature descriptors or to define the local neighborhood around a point or points.

#### keypoints

The pcl_keypoints library contains implementations of two point cloud keypoint detection algorithms. Keypoints (also referred to as interest points) are points in an image or point cloud that are stable, distinctive, and can be identified using a well-defined detection criteron. Typically, the number of interest points in a point cloud will be much smaller than the total number of points in the cloud, and when used in combination with local feature descriptors at each keypoint, the keypoints and descriptors can be used to form a compact—yet descriptive—representation of the original data.

#### octree

The pcl_octree library provides efficient methods for creating a hierarchical tree data structure from point cloud data. This enables spatial partitioning, downsampling and search operations on the point data set. Each octree node the has either eight children or no children. The root node describes a cubic bounding box which encapsulates all points. At every tree level, this space becomes subdivided by a factor of 2 which results in an increased voxel resolution.

The pcl_octree implementation provides efficient nearest neighbor search routines, such as "Neighbors within Voxel Search”, “K Nearest Neighbor Search” and “Neighbors within Radius Search”. It automatically adjusts its dimension to the point data set. A set of leaf node classes provide additional functionality, such as spacial "occupancy" and "point density per voxel" checks. Functions for serialization and deserialization enable to efficiently encode the octree structure into a binary format. Furthermore, a memory pool implementation reduces expensive memory allocation and deallocation operations in scenarios where octrees needs to be created at high rate.

You can learn more about using octrees in the following tutorials:

#### range_image

The pcl_range_image library contains two classes for representing and working with range images. A range image (or depth map) is an image whose pixel values represent a distance or depth from the sensor's origin. Range images are a common 3D representation and are often generated by stereo or time-of-flight cameras. With knowledge of the camera's intrinsic calibration parameters, a range image can be converted into a point cloud

An introduction to working with range images can be found in the following tutorial:

#### registration

The pcl_registration library contains algorithms that can be used to combine several datasets into a globally consistent model. The key idea is to identify corresponding points between the data sets and find a transformation that minimizes the distance (alignment error) between corresponding points. This process is repeated, since correspondence search is affected by the relative position and orientation of the data sets. Once the alignment errors fall below a given threshold, the registration is said to be complete.

#### sample_consensus

The pcl_sample_consensus library holds SAmple Consensus (SAC) methods like RANSAC and models like planes and cylinders. These can combined freely in order to detect specific models and their paramters in point clouds.

Some of the models implemented in this library include: lines, planes, cylinders, and spheres. Plane fitting is often applied to the task of detecting common indoor surfaces, such as walls, floors, and table tops. Other models can be used to detect and segment objects with common geometric structures (e.g., fitting a cylinder model to a mug).

You can find examples of how to use these algorithms in the following tutorials:

#### segmentation

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.

The following tutorial provides an example of how to perform clustering on a point cloud:

#### surface

The pcl_surface library deals with reconstructing the original surfaces from 3D scans. Depending on the task at hand, this can be for example the hull, a mesh representation or a smoothed/resampled surface with normals.

- Creating a convex or concave hull is useful for example when there is a need for a simplified surface representation or when boundaries need to be extracted.
- Meshing is a general way to create a surface out of points, and currently there are two algorithms provided: a very fast triangulation of the original points, and a slower meshing that does smoothing and hole filling as well.
- Smoothing and resampling can be important if the cloud is noisy, or if it is composed of multiple scans that are not aligned perfectly. The complexity of the surface estimation can be adjusted, and normals can be estimated in the same step if needed

Some examples of these capabilities can be found in the following tutorials:

#### visualization

The pcl_visualization library was built for the purpose of being able to quickly prototype and visualize the results of algorithms operating on 3D point cloud data. Similar to OpenCV's highgui routines for displaying 2D images and for drawing basic 2D shapes on screen, the library offers:

* methods for rendering and setting visual properties (colors, point sizes, opacity, etc) for any n-D point cloud datasets in `pcl::PointCloud<T>` format * methods for drawing basic 3D shapes on screen (e.g., cylinders, spheres,lines, polygons, etc) either from sets of points or from parametric equations * a histogram visualization module (`PCLHistogramVisualizer`) for 2D plots * a multitude of Geometry and Color handler for `pcl::PointCloud<T>` datasets * a `pcl::RangeImage` visualization module.