Point Cloud Library (PCL)  1.7.0
/tmp/buildd/pcl-1.7-1.7.0/visualization/include/pcl/visualization/common/shapes.h
00001 /*
00002  * Software License Agreement (BSD License)
00003  *
00004  *  Point Cloud Library (PCL) - www.pointclouds.org
00005  *  Copyright (c) 2009-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 Willow Garage, Inc. 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 #ifndef PCL_PCL_VISUALIZER_SHAPES_H_
00040 #define PCL_PCL_VISUALIZER_SHAPES_H_
00041 
00042 #include <pcl/ModelCoefficients.h>
00043 #include <pcl/point_cloud.h>
00044 #include <pcl/visualization/eigen.h>
00045 #include <pcl/geometry/planar_polygon.h>
00046 
00047 template <typename T> class vtkSmartPointer;
00048 class vtkDataSet;
00049 class vtkUnstructuredGrid;
00050 
00051 /**
00052   * \file pcl/visualization/common/shapes.h
00053   * Define methods or creating 3D shapes from parametric models
00054   * \ingroup visualization
00055   */
00056 
00057 /*@{*/
00058 namespace pcl
00059 {
00060   namespace visualization
00061   {
00062     /** \brief Create a 3d poly line from a set of points. 
00063       * \param[in] cloud the set of points used to create the 3d polyline
00064       * \ingroup visualization
00065       */
00066     template <typename PointT> vtkSmartPointer<vtkDataSet> inline 
00067     createPolygon (const typename pcl::PointCloud<PointT>::ConstPtr &cloud);
00068 
00069     /** \brief Create a 3d poly line from a set of points on the boundary of a planar region. 
00070       * \param[in] planar_polygon the set of points used to create the 3d polyline
00071       * \ingroup visualization
00072       */
00073     template <typename PointT> vtkSmartPointer<vtkDataSet> inline 
00074     createPolygon (const pcl::PlanarPolygon<PointT> &planar_polygon);
00075 
00076     /** \brief Create a line shape from two points
00077       * \param[in] pt1 the first point on the line
00078       * \param[in] pt2 the end point on the line
00079       * \ingroup visualization
00080       */
00081     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00082     createLine (const Eigen::Vector4f &pt1, const Eigen::Vector4f &pt2);
00083 
00084     /** \brief Create a sphere shape from a point and a radius
00085       * \param[in] center the center of the sphere (as an Eigen Vector4f, with only the first 3 coordinates used)
00086       * \param[in] radius the radius of the sphere
00087       * \param[in] res (optional) the resolution used for rendering the model
00088       * \ingroup visualization
00089       */
00090     PCL_EXPORTS vtkSmartPointer<vtkDataSet>
00091     createSphere (const Eigen::Vector4f &center, double radius, int res = 10);
00092 
00093     /** \brief Create a cylinder shape from a set of model coefficients.
00094       * \param[in] coefficients the model coefficients (point_on_axis, axis_direction, radius)
00095       * \param[in] numsides (optional) the number of sides used for rendering the cylinder
00096       *
00097       * \code
00098       * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCylinder)
00099       * // Eigen::Vector3f pt_on_axis, axis_direction;
00100       * // float radius;
00101       *
00102       * pcl::ModelCoefficients cylinder_coeff;
00103       * cylinder_coeff.values.resize (7);    // We need 7 values
00104       * cylinder_coeff.values[0] = pt_on_axis.x ();
00105       * cylinder_coeff.values[1] = pt_on_axis.y ();
00106       * cylinder_coeff.values[2] = pt_on_axis.z ();
00107       *
00108       * cylinder_coeff.values[3] = axis_direction.x ();
00109       * cylinder_coeff.values[4] = axis_direction.y ();
00110       * cylinder_coeff.values[5] = axis_direction.z ();
00111       *
00112       * cylinder_coeff.values[6] = radius;
00113       *
00114       * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createCylinder (cylinder_coeff, numsides);
00115       * \endcode
00116       *
00117       * \ingroup visualization
00118       */
00119     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00120     createCylinder (const pcl::ModelCoefficients &coefficients, int numsides = 30);
00121 
00122     /** \brief Create a sphere shape from a set of model coefficients.
00123       * \param[in] coefficients the model coefficients (sphere center, radius)
00124       * \param[in] res (optional) the resolution used for rendering the model
00125       *
00126       * \code
00127       * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelSphere)
00128       * // Eigen::Vector3f sphere_center;
00129       * // float radius;
00130       *
00131       * pcl::ModelCoefficients sphere_coeff;
00132       * sphere_coeff.values.resize (4);    // We need 4 values
00133       * sphere_coeff.values[0] = sphere_center.x ();
00134       * sphere_coeff.values[1] = sphere_center.y ();
00135       * sphere_coeff.values[2] = sphere_center.z ();
00136       *
00137       * sphere_coeff.values[3] = radius;
00138       *
00139       * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createSphere (sphere_coeff, resolution);
00140       * \endcode
00141       *
00142       * \ingroup visualization
00143       */
00144     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00145     createSphere (const pcl::ModelCoefficients &coefficients, int res = 10);
00146 
00147     /** \brief Create a line shape from a set of model coefficients.
00148       * \param[in] coefficients the model coefficients (point_on_line, line_direction)
00149       * 
00150       * \code
00151       * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelLine)
00152       * // Eigen::Vector3f point_on_line, line_direction;
00153       *
00154       * pcl::ModelCoefficients line_coeff;
00155       * line_coeff.values.resize (6);    // We need 6 values
00156       * line_coeff.values[0] = point_on_line.x ();
00157       * line_coeff.values[1] = point_on_line.y ();
00158       * line_coeff.values[2] = point_on_line.z ();
00159       *
00160       * line_coeff.values[3] = line_direction.x ();
00161       * line_coeff.values[4] = line_direction.y ();
00162       * line_coeff.values[5] = line_direction.z ();
00163       *
00164       * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createLine (line_coeff);
00165       * \endcode
00166       *
00167       * \ingroup visualization
00168       */
00169     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00170     createLine (const pcl::ModelCoefficients &coefficients);
00171 
00172     /** \brief Create a planar shape from a set of model coefficients.
00173       * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
00174       *
00175       * \code
00176       * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelPlane)
00177       * // Eigen::Vector4f plane_parameters;
00178       *
00179       * pcl::ModelCoefficients plane_coeff;
00180       * plane_coeff.values.resize (4);    // We need 4 values
00181       * plane_coeff.values[0] = plane_parameters.x ();
00182       * plane_coeff.values[1] = plane_parameters.y ();
00183       * plane_coeff.values[2] = plane_parameters.z ();
00184       * plane_coeff.values[3] = plane_parameters.w ();
00185       *
00186       * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createPlane (plane_coeff);
00187       * \endcode
00188       *
00189       * \ingroup visualization
00190       */
00191     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00192     createPlane (const pcl::ModelCoefficients &coefficients);
00193 
00194     /** \brief Create a planar shape from a set of model coefficients.
00195       * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
00196       * \param[in] x,y,z projection of this point on the plane is used to get the center of the plane.
00197       * \ingroup visualization
00198       */
00199     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00200     createPlane (const pcl::ModelCoefficients &coefficients, double x, double y, double z);
00201     
00202     /** \brief Create a 2d circle shape from a set of model coefficients.
00203       * \param[in] coefficients the model coefficients (x, y, radius)
00204       * \param[in] z (optional) specify a z value (default: 0)
00205       *
00206       * \code
00207       * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCircle2D)
00208       * // float x, y, radius;
00209       *
00210       * pcl::ModelCoefficients circle_coeff;
00211       * circle_coeff.values.resize (3);    // We need 3 values
00212       * circle_coeff.values[0] = x;
00213       * circle_coeff.values[1] = y;
00214       * circle_coeff.values[2] = radius;
00215       *
00216       * vtkSmartPointer<vtkDataSet> data = pcl::visualization::create2DCircle (circle_coeff, z);
00217       * \endcode
00218       *
00219       * \ingroup visualization
00220       */
00221     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00222     create2DCircle (const pcl::ModelCoefficients &coefficients, double z = 0.0);
00223 
00224     /** \brief Create a cone shape from a set of model coefficients.
00225       * \param[in] coefficients the cone coefficients (point_on_axis, axis_direction, radius)
00226       * \ingroup visualization
00227       */
00228     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00229     createCone (const pcl::ModelCoefficients &coefficients);
00230 
00231     /** \brief Creaet a cube shape from a set of model coefficients.
00232       * \param[in] coefficients the cube coefficients (Tx, Ty, Tz, Qx, Qy, Qz, Qw, width, height, depth)
00233       * \ingroup visualization 
00234       */
00235     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00236     createCube (const pcl::ModelCoefficients &coefficients);
00237 
00238     /** \brief Creaet a cube shape from a set of model coefficients.
00239       *
00240       * \param[in] translation a translation to apply to the cube from 0,0,0
00241       * \param[in] rotation a quaternion-based rotation to apply to the cube 
00242       * \param[in] width the cube's width
00243       * \param[in] height the cube's height
00244       * \param[in] depth the cube's depth
00245       * \ingroup visualization 
00246       */
00247     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00248     createCube (const Eigen::Vector3f &translation, const Eigen::Quaternionf &rotation,
00249                 double width, double height, double depth);
00250     
00251     /** \brief Create a cube from a set of bounding points
00252       * \param[in] x_min is the minimum x value of the box
00253       * \param[in] x_max is the maximum x value of the box
00254       * \param[in] y_min is the minimum y value of the box 
00255       * \param[in] y_max is the maximum y value of the box
00256       * \param[in] z_min is the minimum z value of the box
00257       * \param[in] z_max is the maximum z value of the box
00258       * \param[in] id the cube id/name (default: "cube")
00259       * \param[in] viewport (optional) the id of the new viewport (default: 0)
00260       */
00261     PCL_EXPORTS vtkSmartPointer<vtkDataSet> 
00262     createCube (double x_min, double x_max,
00263                 double y_min, double y_max,
00264                 double z_min, double z_max);
00265     
00266     /** \brief Allocate a new unstructured grid smartpointer. For internal use only.
00267       * \param[out] polydata the resultant unstructured grid. 
00268       */
00269     PCL_EXPORTS void
00270     allocVtkUnstructuredGrid (vtkSmartPointer<vtkUnstructuredGrid> &polydata);
00271   }
00272 }
00273 /*@}*/
00274 
00275 #include <pcl/visualization/common/impl/shapes.hpp>
00276 
00277 #endif