Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/filters/include/pcl/filters/extract_indices.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2010-2012, Willow Garage, Inc.
00006  *
00007  *  All rights reserved.
00008  *
00009  *  Redistribution and use in source and binary forms, with or without
00010  *  modification, are permitted provided that the following conditions
00011  *  are met:
00012  *
00013  *   * Redistributions of source code must retain the above copyright
00014  *     notice, this list of conditions and the following disclaimer.
00015  *   * Redistributions in binary form must reproduce the above
00016  *     copyright notice, this list of conditions and the following
00017  *     disclaimer in the documentation and/or other materials provided
00018  *     with the distribution.
00019  *   * Neither the name of the copyright holder(s) nor the names of its
00020  *     contributors may be used to endorse or promote products derived
00021  *     from this software without specific prior written permission.
00022  *
00023  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00024  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00025  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
00026  *  FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
00027  *  COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
00028  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
00029  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  *  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031  *  CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00032  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
00033  *  ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00034  *  POSSIBILITY OF SUCH DAMAGE.
00035  *
00036  * $Id$
00037  *
00038  */
00039 
00040 #ifndef PCL_FILTERS_EXTRACT_INDICES_H_
00041 #define PCL_FILTERS_EXTRACT_INDICES_H_
00042 
00043 #include <pcl/filters/filter_indices.h>
00044 
00045 namespace pcl
00046 {
00047   /** \brief @b ExtractIndices extracts a set of indices from a point cloud.
00048     * \details Usage example:
00049     * \code
00050     * pcl::ExtractIndices<PointType> eifilter (true); // Initializing with true will allow us to extract the removed indices
00051     * eifilter.setInputCloud (cloud_in);
00052     * eifilter.setIndices (indices_in);
00053     * eifilter.filter (*cloud_out);
00054     * // The resulting cloud_out contains all points of cloud_in that are indexed by indices_in
00055     * indices_rem = eifilter.getRemovedIndices ();
00056     * // The indices_rem array indexes all points of cloud_in that are not indexed by indices_in
00057     * eifilter.setNegative (true);
00058     * eifilter.filter (*indices_out);
00059     * // Alternatively: the indices_out array is identical to indices_rem
00060     * eifilter.setNegative (false);
00061     * eifilter.setUserFilterValue (1337.0);
00062     * eifilter.filterDirectly (cloud_in);
00063     * // This will directly modify cloud_in instead of creating a copy of the cloud
00064     * // It will overwrite all fields of the filtered points by the user value: 1337
00065     * \endcode
00066     * \author Radu Bogdan Rusu
00067     * \ingroup filters
00068     */
00069   template<typename PointT>
00070   class ExtractIndices : public FilterIndices<PointT>
00071   {
00072     protected:
00073       typedef typename FilterIndices<PointT>::PointCloud PointCloud;
00074       typedef typename PointCloud::Ptr PointCloudPtr;
00075       typedef typename PointCloud::ConstPtr PointCloudConstPtr;
00076       typedef typename pcl::traits::fieldList<PointT>::type FieldList;
00077 
00078     public:
00079 
00080       typedef boost::shared_ptr< ExtractIndices<PointT> > Ptr;
00081       typedef boost::shared_ptr< const ExtractIndices<PointT> > ConstPtr;
00082 
00083       /** \brief Constructor.
00084         * \param[in] extract_removed_indices Set to true if you want to be able to extract the indices of points being removed (default = false).
00085         */
00086       ExtractIndices (bool extract_removed_indices = false) :
00087         FilterIndices<PointT>::FilterIndices (extract_removed_indices)
00088       {
00089         use_indices_ = true;
00090         filter_name_ = "ExtractIndices";
00091       }
00092 
00093       /** \brief Apply the filter and store the results directly in the input cloud.
00094         * \details This method will save the time and memory copy of an output cloud but can not alter the original size of the input cloud:
00095         * It operates as though setKeepOrganized() is true and will overwrite the filtered points instead of remove them.
00096         * All fields of filtered points are replaced with the value set by setUserFilterValue() (default = NaN).
00097         * This method also automatically alters the input cloud set via setInputCloud().
00098         * It does not alter the value of the internal keep organized boolean as set by setKeepOrganized().
00099         * \param cloud The point cloud used for input and output.
00100         */
00101       void
00102       filterDirectly (PointCloudPtr &cloud);
00103 
00104     protected:
00105       using PCLBase<PointT>::input_;
00106       using PCLBase<PointT>::indices_;
00107       using PCLBase<PointT>::use_indices_;
00108       using Filter<PointT>::filter_name_;
00109       using Filter<PointT>::getClassName;
00110       using FilterIndices<PointT>::negative_;
00111       using FilterIndices<PointT>::keep_organized_;
00112       using FilterIndices<PointT>::user_filter_value_;
00113       using FilterIndices<PointT>::extract_removed_indices_;
00114       using FilterIndices<PointT>::removed_indices_;
00115 
00116       /** \brief Filtered results are stored in a separate point cloud.
00117         * \param[out] output The resultant point cloud.
00118         */
00119       void
00120       applyFilter (PointCloud &output);
00121 
00122       /** \brief Filtered results are indexed by an indices array.
00123         * \param[out] indices The resultant indices.
00124         */
00125       void
00126       applyFilter (std::vector<int> &indices)
00127       {
00128         applyFilterIndices (indices);
00129       }
00130 
00131       /** \brief Filtered results are indexed by an indices array.
00132         * \param[out] indices The resultant indices.
00133         */
00134       void
00135       applyFilterIndices (std::vector<int> &indices);
00136   };
00137 
00138   //////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
00139   /** \brief @b ExtractIndices extracts a set of indices from a point cloud.
00140     * <br>
00141     * Usage examples:
00142     * \code
00143     * pcl::ExtractIndices<PointType> filter;
00144     * filter.setInputCloud (cloud_in);
00145     * filter.setIndices (indices_in);
00146     * // Extract the points in cloud_in referenced by indices_in as a separate point cloud:
00147     * filter.filter (*cloud_out);
00148     * // Retrieve indices to all points in cloud_in except those referenced by indices_in:
00149     * filter.setNegative (true);
00150     * filter.filter (*indices_out);
00151     * // The resulting cloud_out is identical to cloud_in, but all points referenced by indices_in are made NaN:
00152     * filter.setNegative (true);
00153     * filter.setKeepOrganized (true);
00154     * filter.filter (*cloud_out);
00155     * \endcode
00156     * \note Does not inherently remove NaNs from results, hence the \a extract_removed_indices_ system is not used.
00157     * \author Radu Bogdan Rusu
00158     * \ingroup filters
00159     */
00160   template<>
00161   class PCL_EXPORTS ExtractIndices<pcl::PCLPointCloud2> : public FilterIndices<pcl::PCLPointCloud2>
00162   {
00163     public:
00164       typedef pcl::PCLPointCloud2 PCLPointCloud2;
00165       typedef PCLPointCloud2::Ptr PCLPointCloud2Ptr;
00166       typedef PCLPointCloud2::ConstPtr PCLPointCloud2ConstPtr;
00167 
00168       /** \brief Empty constructor. */
00169       ExtractIndices ()
00170       {
00171         use_indices_ = true;
00172         filter_name_ = "ExtractIndices";
00173       }
00174 
00175     protected:
00176       using PCLBase<PCLPointCloud2>::input_;
00177       using PCLBase<PCLPointCloud2>::indices_;
00178       using PCLBase<PCLPointCloud2>::use_indices_;
00179       using Filter<PCLPointCloud2>::filter_name_;
00180       using Filter<PCLPointCloud2>::getClassName;
00181       using FilterIndices<PCLPointCloud2>::negative_;
00182       using FilterIndices<PCLPointCloud2>::keep_organized_;
00183       using FilterIndices<PCLPointCloud2>::user_filter_value_;
00184 
00185       /** \brief Extract point indices into a separate PointCloud
00186         * \param[out] output the resultant point cloud
00187         */
00188       void
00189       applyFilter (PCLPointCloud2 &output);
00190 
00191       /** \brief Extract point indices
00192         * \param indices the resultant indices
00193         */
00194       void
00195       applyFilter (std::vector<int> &indices);
00196   };
00197 }
00198 
00199 #ifdef PCL_NO_PRECOMPILE
00200 #include <pcl/filters/impl/extract_indices.hpp>
00201 #endif
00202 
00203 #endif  // PCL_FILTERS_EXTRACT_INDICES_H_
00204