.. toctree::
  
The following links describe a set of basic PCL tutorials. Please note that
their source codes may already be provided as part of the PCL regular releases,
so check there before you start copy & pasting the code. The list of tutorials
below is automatically generated from reST files located in our SVN repository.

.. note::

  Before you start reading, please make sure that you go through the higher-level overview documentation at http://www.pointclouds.org/documentation/, under **Getting Started**. Thank you.

As always, we would be happy to hear your comments and receive your
contributions on any tutorial.

Table of contents
-----------------

  * :ref:`basic_usage`
  * :ref:`advanced_usage`
  * :ref:`applications_tutorial`
  * :ref:`features_tutorial`
  * :ref:`filtering_tutorial`
  * :ref:`i_o`
  * :ref:`keypoints_tutorial`
  * :ref:`octree_tutorial`
  * :ref:`range_images`
  * :ref:`registration_tutorial`
  * :ref:`segmentation_tutorial`
  * :ref:`surface_tutorial`
  * :ref:`visualization_tutorial`


.. _basic_usage:

Basic Usage
-----------

  * :ref:`using_pcl`

     ======  ======
     |mi_1|  Title: **Using PCL in own project**

             Author: *Nizar Sallem*

             Compatibility: > PCL 1.0
             
             In this tutorial, we will learn how to link your own project to PCL using cmake.
     ======  ======

     .. |mi_1| image:: images/pcl_logo.png
               :height: 75px

  * :ref:`building_pcl`

     ======  ======
     |mi_2|  Title: **Explaining PCL's cmake options**

             Author: *Nizar Sallem*

             Compatibility: > PCL 1.0
             
             In this tutorial, we will explain the basic PCL cmake options, and ways to tweak them to fit your project.
     ======  ======

     .. |mi_2| image:: images/pcl_ccmake.png
               :height: 100px

  * :ref:`compiling_pcl_windows`

     ======  ======
     |mi_3|  Title: **Compiling PCL and its dependencies from source in Windows**

             Author: *Alessio Placitelli*

             Compatibility: > PCL 1.0
             
             In this tutorial, we will explain how to compile PCL and all its 3rd party dependencies from source in Microsoft Windows.
     ======  ======

     .. |mi_3| image:: images/windows_logo.png
               :height: 100px

  * :ref:`compiling_pcl_windows_3rdparty_installers`

     ======  ======
     |mi_4|  Title: **Compiling PCL in Windows using the provided 3rd Party installers**

             Author: *Mourad Boufarguine*

             Compatibility: > PCL 1.0
             
             In this tutorial, we will explain how to compile PCL in Microsoft Windows using the provided 3rd Party installers.
     ======  ======

     .. |mi_4| image:: images/windows_logo.png
               :height: 100px

  * :ref:`compiling_pcl_macosx`

     ======  ======
     |mi_5|  Title: **Compiling PCL and its dependencies from MacPorts and source on Mac OS X**

             Author: *Justin Rosen*

             Compatibility: > PCL 1.0
             
             This tutorial explains how to build the Point Cloud Library **from MacPorts and source** on Mac OS X platforms.
     ======  ======

     .. |mi_5| image:: images/macosx_logo.png
               :height: 100px

.. _advanced_usage:

Advanced Usage
--------------

  * :ref:`adding_custom_ptype`

     ======  ======
     |au_1|  Title: **Adding your own custom PointT point type**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 0.9, < PCL 2.0
             
             This document explains what templated point types are in PCL, why do they exist, and how to create and use your own `PointT` point type.
     ======  ======

     .. |au_1| image:: images/pcl_logo.png
               :height: 75px

  * :ref:`writing_new_classes`

     ======  ======
     |au_2|  Title: **Writing a new PCL class**

             Author: *Radu B. Rusu, Luca Penasa*

             Compatibility: > PCL 0.9, < PCL 2.0
             
             This short guide is to serve as both a HowTo and a FAQ for writing new PCL classes, either from scratch, or by adapting old code.
     ======  ======

     .. |au_2| image:: images/pcl_logo.png
               :height: 75px

.. _features_tutorial:

Features
--------

  * :ref:`how_3d_features_work`
    
     ======  ======
     |fe_1|  Title: **How 3D features work**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             This document presents a basic introduction to the 3D feature estimation methodologies in PCL.
     ======  ======
     
     .. |fe_1| image:: images/good_features_small.png
               :height: 100px

  * :ref:`normal_estimation`
    
     ======  ======
     |fe_2|  Title: **Estimating Surface Normals in a PointCloud**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             This tutorial discusses the theoretical and implementation details of the surface normal estimation module in PCL.
     ======  ======
     
     .. |fe_2| image:: images/normal_estimation.png
               :height: 100px


  * :ref:`normal_estimation_using_integral_images`
    
     ======  ======
     |fe_3|  Title: **Normal Estimation Using Integral Images**

             Author: *Stefan Holzer*

             Compatibility: > PCL 1.0

             In this tutorial we will learn how to compute normals for an organized point cloud using integral images.
     ======  ======
     
     .. |fe_3| image:: images/normal_estimation_ii.png
               :height: 100px

  * :ref:`pfh_estimation`
    
     ======  ======
     |fe_4|  Title: **Point Feature Histograms (PFH) descriptors**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             This tutorial introduces a family of 3D feature descriptors called PFH (Point Feature Histograms) and discusses their implementation details from PCL's perspective.
     ======  ======
     
     .. |fe_4| image:: images/pfh_estimation.png
               :height: 100px

  * :ref:`fpfh_estimation`
    
     ======  ======
     |fe_5|  Title: **Fast Point Feature Histograms (FPFH) descriptors**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             This tutorial introduces the FPFH (Fast Point Feature Histograms) 3D descriptor and discusses their implementation details from PCL's perspective.
     ======  ======
     
     .. |fe_5| image:: images/fpfh_estimation.jpg
               :height: 100px

  * :ref:`vfh_estimation`
    
     ======  ======
     |fe_6|  Title: **Estimating VFH signatures for a set of points**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 0.8

             This document describes the Viewpoint Feature Histogram (VFH) descriptor, a novel representation for point clusters for the problem of Cluster (e.g., Object) Recognition and 6DOF Pose Estimation.
     ======  ======
     
     .. |fe_6| image:: images/vfh_estimation.png
               :height: 100px
  
  * :ref:`narf_feature_extraction`
    
     ======  ======
     |fe_7|  Title: **How to extract NARF features from a range image**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to extract NARF features from a range image.
     ======  ======
     
     .. |fe_7| image:: images/narf_keypoint_extraction.png
               :height: 100px

.. _filtering_tutorial:

Filtering
---------

  * :ref:`passthrough`
    
     ======  ======
     |fi_1|  Title: **Filtering a PointCloud using a PassThrough filter**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to remove points whose values fall inside/outside a user given interval along a specified dimension.
     ======  ======
     
     .. |fi_1| image:: images/passthrough.jpg
               :height: 100px

  * :ref:`voxelgrid`
    
     ======  ======
     |fi_2|  Title: **Downsampling a PointCloud using a VoxelGrid filter**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to downsample (i.e., reduce the number of points) a Point Cloud.
     ======  ======
     
     .. |fi_2| image:: images/voxel_grid.jpg
               :height: 100px
    

  * :ref:`statistical_outlier_removal` 
    
     ======  ======
     |fi_3|  Title: **Removing sparse outliers using StatisticalOutlierRemoval**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to remove sparse outliers from noisy data, using StatisticalRemoval.
     ======  ======
     
     .. |fi_3| image:: images/statistical_removal.jpg
               :height: 100px

  * :ref:`project_inliers`

     ======  ======
     |fi_4|  Title: **Projecting points using a parametric model**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to project points to a parametric model (i.e., plane).
     ======  ======
     
     .. |fi_4| image:: images/project_inliers.jpg
               :height: 100px

  * :ref:`extract_indices`

     ======  ======
     |fi_5|  Title: **Extracting indices from a PointCloud**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to extract a set of indices given by a segmentation algorithm.
     ======  ======
     
     .. |fi_5| image:: images/extract_indices.jpg
               :height: 100px

  * :ref:`remove_outliers` 
    
     ======  ======
     |fi_6|  Title: **Removing outliers using a Conditional or RadiusOutlier removal**

             Author: *Gabe O'Leary*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to remove outliers from noisy data, using ConditionalRemoval, RadiusOutlierRemoval.
     ======  ======
     
     .. |fi_6| image:: images/radius_outlier.png
               :height: 100px

.. _i_o:

I/O
---

  * :ref:`pcd_file_format`

     ======  ======
     |i_o0|  Title: **The PCD (Point Cloud Data) file format**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 0.9

             This document describes the PCD file format, and the way it is used inside PCL.
     ======  ======
     
     .. |i_o0| image:: images/PCD_icon.png
               :height: 100px

  * :ref:`reading_pcd`

     ======  ======
     |i_o1|  Title: **Reading Point Cloud data from PCD files**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to read a Point Cloud from a PCD file.
     ======  ======
     
     .. |i_o1| image:: images/read_pcd.jpg
               :height: 100px

  * :ref:`writing_pcd`

     ======  ======
     |i_o2|  Title: **Writing Point Cloud data to PCD files**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to write a Point Cloud to a PCD file.
     ======  ======
     
     .. |i_o2| image:: images/write_pcd.jpg
               :height: 100px

  * :ref:`concatenate_clouds`

     ======  ======
     |i_o3|  Title: **Concatenate the fields or points of two Point Clouds**

             Author: *Gabe O'Leary / Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to concatenate both the fields and the point data of two Point Clouds.  When concatenating fields, one PointClouds contains only *XYZ* data, and the other contains *Surface Normal* information.
     ======  ======

     .. |i_o3| image:: images/concatenate_fields.jpg
               :height: 100px

  * :ref:`openni_grabber`

     ======  ======
     |i_o4|  Title: **Grabbing Point Clouds from an OpenNI camera**

             Author: *Nico Blodow*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to acquire point cloud data from an OpenNI camera.
     ======  ======

     .. |i_o4| image:: images/openni_grabber.png
               :height: 100px

.. _keypoints_tutorial:

Keypoints
---------

  * :ref:`narf_keypoint_extraction`
    
     ======  ======
     |kp_1|  Title: **How to extract NARF keypoints from a range image**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to extract NARF keypoints from a range image.
     ======  ======
     
     .. |kp_1| image:: images/narf_keypoint_extraction.png
               :height: 100px

.. _octree_tutorial:

Octree
------

  * :ref:`octree_compression`
  
     ======  ======
     |oc_1|  Title: **Point cloud compression**

             Author: *Julius Kammerl*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to compress a single point cloud and streams of point clouds.
     ======  ======
     
     .. |oc_1| image:: images/compression_tutorial.png
               :height: 100px

  * :ref:`octree_search`
  
     ======  ======
     |oc_2|  Title: **Octrees for spatial partitioning and neighbor search**

             Author: *Julius Kammerl*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to use octrees for spatial partitioning and nearest neighbor search.
     ======  ======
     
     .. |oc_2| image:: images/octree_img.png
               :height: 100px
               
  * :ref:`octree_change_detection`
  
     ======  ======
     |oc_3|  Title: **Spatial change detection on unorganized point cloud data**

             Author: *Julius Kammerl*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to use octrees for detecting spatial changes within point clouds.
     ======  ======
     
     .. |oc_3| image:: images/changedetectionThumb.png
               :height: 100px

.. _range_images:

Range Images
------------

  * :ref:`range_image_creation`

     ======  ======
     |ri_1|  Title: **Creating Range Images from Point Clouds**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0
             
             This tutorial demonstrates how to create a range image from a point cloud and a given sensor position. 
     ======  ======

     .. |ri_1| image:: images/range_image_visualization.png
               :height: 100px

  * :ref:`range_image_border_extraction`

     ======  ======
     |ri_2|  Title: **Extracting borders from Range Images**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0
             
             This tutorial demonstrates how to extract borders (traversals from foreground to background) from a range image. 
     ======  ======

     .. |ri_2| image:: images/range_image_border_points.gif
               :height: 100px

.. _registration_tutorial:

Registration
------------

  * :ref:`iterative_closest_point`

     ======  ======
     |re_1|  Title: **How to use iterative closest point algorithm**

             Author: *Gabe O'Leary*

             Compatibility: > PCL 1.0

             This tutorial gives an example of how to use the iterative closest point algorithm to see if one PointCloud is just a rigid transformation of another PointCloud.
     ======  ======

     .. |re_1| image:: images/iterative_closest_point.gif
               :height: 100px

.. _segmentation_tutorial:
  
Segmentation
------------

  * :ref:`planar_segmentation`
    
     ======  ======
     |se_1|  Title: **Plane model segmentation**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to segment arbitrary plane models from a given point cloud dataset.
     ======  ======
     
     .. |se_1| image:: images/planar_segmentation.jpg
               :height: 100px

  * :ref:`cylinder_segmentation`

     ======  ======
     |se_2|  Title: **Cylinder model segmentation**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to segment arbitrary cylindrical models from a given point cloud dataset.
     ======  ======
     
     .. |se_2| image:: images/cylinder_segmentation.jpg
               :height: 100px

  * :ref:`cluster_extraction`

     ======  ======
     |se_3|  Title: **Euclidean Cluster Extraction**

             Author: *Serkan Tuerker*

             Compatibility: > PCL 1.0

             In this tutorial we will learn how to extract Euclidean clusters with the ``pcl::EuclideanClusterExtraction`` class.
     ======  ======
     
     .. |se_3| image:: images/cluster_extraction.jpg
               :height: 100px

.. _surface_tutorial:

Surface
-------

  * :ref:`moving_least_squares`

     ======  ======
     |su_1|  Title: **Smoothing and normal estimation based on polynomial reconstruction**

             Author: *Zoltan-Csaba Marton*

             Compatibility: > PCL 1.0

             In this tutorial, we will learn how to construct and run a Moving Least Squares (MLS) algorithm to obtain smoothed XYZ coordinates and normals.
     ======  ======
     
     .. |su_1| image:: images/resampling.jpg
               :height: 100px

  * :ref:`hull_2d`

     ======  ======
     |su_2|  Title: **Construct a concave or convex hull polygon for a plane model**

             Author: *Gabe O'Leary, Radu B. Rusu*

             Compatibility: > PCL 1.0

             In this tutorial we will learn how to calculate a simple 2D concave or convex hull polygon for a set of points supported by a plane.
     ======  ======
     
     .. |su_2| image:: images/convex_hull_2d.jpg
               :height: 100px

  * :ref:`greedy_triangulation`

     ======  ======
     |su_3|  Title: **Fast triangulation of unordered point clouds**

             Author: *Zoltan-Csaba Marton*

             Compatibility: > PCL 1.0

             In this tutorial we will learn how to run a greedy triangulation algorithm on a PointCloud with normals to obtain a triangle mesh based on projections of the local neighborhood.
     ======  ======
     
     .. |su_3| image:: images/greedy_triangulation.png
               :height: 100px

.. _visualization_tutorial:

Visualization
-------------

  * :ref:`cloud_viewer`

     ======  ======
     |vi_1|  Title: **Visualizing Point Clouds**

             Author: *Ethan Rublee*

             Compatibility: > PCL 1.0

             This tutorial demonstrates how to use the pcl visualization tools.
     ======  ======

     .. |vi_1| image:: images/cloud_viewer.jpg
               :height: 100px

  * :ref:`range_image_visualization`

     ======  ======
     |vi_2|  Title: **Visualizing Range Images**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0

             This tutorial demonstrates how to use the pcl visualization tools for range images.
     ======  ======

     .. |vi_2| image:: images/range_image_visualization.png
               :height: 100px

  * :ref:`pcl_visualizer`

     ======  ======
     |vi_3|  Title: **PCLVisualizer**

             Author: *Geoffrey Biggs*

             Compatibility: >= PCL 1.0

             This tutorial demonstrates how to use the PCLVisualizer class for powerful visualisation of point clouds and related data.
     ======  ======

     .. |vi_3| image:: images/pcl_visualizer_viewports.png
               :height: 100px

  * :ref:`narf_descriptor_visualization`
    
     ======  ======
     |vi_4|  Title: **Visualization of how the NARF descriptor is calculated**

             Author: *Bastian Steder*

             Compatibility: > PCL 1.0

             This tutorial is about the visualization of how the NARF descriptor is calculated and to test how the descriptor distances between certain points in a range image behave.
     ======  ======
     
     .. |vi_4| image:: images/narf_descriptor.jpg
               :height: 100px

.. _applications_tutorial:

Applications
------------

  * :ref:`template_alignment`

     ======  ======
     |ap_1|  Title: **Aligning object templates to a point cloud**

             Author: *Michael Dixon*

             Compatibility: > PCL 1.0

             This tutorial gives an example of how some of the tools covered in the previous tutorials can be combined to solve a higher level problem --- aligning a previously captured model of an object to some newly captured data.
     ======  ======

     .. |ap_1| image:: images/template_alignment_1.png
               :height: 100px

  * :ref:`vfh_recognition`
    
     ======  ======
     |ap_2|  Title: **Cluster Recognition and 6DOF Pose Estimation using VFH descriptors**

             Author: *Radu B. Rusu*

             Compatibility: > PCL 0.8

             In this tutorial we show how the Viewpoint Feature Histogram (VFH) descriptor can be used to recognize similar clusters in terms of their geometry.
     ======  ======
     
     .. |ap_2| image:: images/vfh_recognition.jpg
               :height: 100px

 ..
  * :ref:`normal_estimation_integral_images`
    Surface normal estimation
  * Range Image
    * :ref:`range_image_visualization`
      How to visualize a range image
    * :ref:`range_image_creation`
      How to create a range image from a point cloud
    * :ref:`range_image_border_extraction`
      How to extract borders from range images
    * :ref:`narf_keypoint`
      How to extract NARF keypoints from a range image
    * :ref:`narf_descriptor`
      How to extract NARF descriptors from points in a range images
    * :ref:`narf_descriptor_visualization`
      Visualization of how the NARF descriptor is calculated and of the descriptor distances to a marked point.
    * :ref:`octree_search`
      Octrees for spatial partitioning and neighbor search.     

