Point Cloud Library (PCL)  1.11.1
shapes.h
Go to the documentation of this file.
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2009-2012, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of Willow Garage, Inc. nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  * $Id$
37  *
38  */
39 
40 #pragma once
41 
42 #include <pcl/point_cloud.h>
43 #include <pcl/visualization/eigen.h>
44 
45 template <typename T> class vtkSmartPointer;
46 class vtkDataSet;
47 class vtkUnstructuredGrid;
48 
49 /**
50  * \file pcl/visualization/common/shapes.h
51  * Define methods or creating 3D shapes from parametric models
52  * \ingroup visualization
53  */
54 
55 /*@{*/
56 namespace pcl
57 {
58  struct ModelCoefficients;
59  template <typename PointT> class PlanarPolygon;
60 
61  namespace visualization
62  {
63  /** \brief Create a 3d poly line from a set of points.
64  * \param[in] cloud the set of points used to create the 3d polyline
65  * \ingroup visualization
66  */
67  template <typename PointT> vtkSmartPointer<vtkDataSet> inline
68  createPolygon (const typename pcl::PointCloud<PointT>::ConstPtr &cloud);
69 
70  /** \brief Create a 3d poly line from a set of points on the boundary of a planar region.
71  * \param[in] planar_polygon the set of points used to create the 3d polyline
72  * \ingroup visualization
73  */
74  template <typename PointT> vtkSmartPointer<vtkDataSet> inline
75  createPolygon (const pcl::PlanarPolygon<PointT> &planar_polygon);
76 
77  /** \brief Create a line shape from two points
78  * \param[in] pt1 the first point on the line
79  * \param[in] pt2 the end point on the line
80  * \ingroup visualization
81  */
83  createLine (const Eigen::Vector4f &pt1, const Eigen::Vector4f &pt2);
84 
85  /** \brief Create a sphere shape from a point and a radius
86  * \param[in] center the center of the sphere (as an Eigen Vector4f, with only the first 3 coordinates used)
87  * \param[in] radius the radius of the sphere
88  * \param[in] res (optional) the resolution used for rendering the model
89  * \ingroup visualization
90  */
92  createSphere (const Eigen::Vector4f &center, double radius, int res = 10);
93 
94  /** \brief Create a cylinder shape from a set of model coefficients.
95  * \param[in] coefficients the model coefficients (point_on_axis, axis_direction, radius)
96  * \param[in] numsides (optional) the number of sides used for rendering the cylinder
97  *
98  * \code
99  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCylinder)
100  * // Eigen::Vector3f pt_on_axis, axis_direction;
101  * // float radius;
102  *
103  * pcl::ModelCoefficients cylinder_coeff;
104  * cylinder_coeff.values.resize (7); // We need 7 values
105  * cylinder_coeff.values[0] = pt_on_axis.x ();
106  * cylinder_coeff.values[1] = pt_on_axis.y ();
107  * cylinder_coeff.values[2] = pt_on_axis.z ();
108  *
109  * cylinder_coeff.values[3] = axis_direction.x ();
110  * cylinder_coeff.values[4] = axis_direction.y ();
111  * cylinder_coeff.values[5] = axis_direction.z ();
112  *
113  * cylinder_coeff.values[6] = radius;
114  *
115  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createCylinder (cylinder_coeff, numsides);
116  * \endcode
117  *
118  * \ingroup visualization
119  */
121  createCylinder (const pcl::ModelCoefficients &coefficients, int numsides = 30);
122 
123  /** \brief Create a sphere shape from a set of model coefficients.
124  * \param[in] coefficients the model coefficients (sphere center, radius)
125  * \param[in] res (optional) the resolution used for rendering the model
126  *
127  * \code
128  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelSphere)
129  * // Eigen::Vector3f sphere_center;
130  * // float radius;
131  *
132  * pcl::ModelCoefficients sphere_coeff;
133  * sphere_coeff.values.resize (4); // We need 4 values
134  * sphere_coeff.values[0] = sphere_center.x ();
135  * sphere_coeff.values[1] = sphere_center.y ();
136  * sphere_coeff.values[2] = sphere_center.z ();
137  *
138  * sphere_coeff.values[3] = radius;
139  *
140  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createSphere (sphere_coeff, resolution);
141  * \endcode
142  *
143  * \ingroup visualization
144  */
146  createSphere (const pcl::ModelCoefficients &coefficients, int res = 10);
147 
148  /** \brief Create a line shape from a set of model coefficients.
149  * \param[in] coefficients the model coefficients (point_on_line, line_direction)
150  *
151  * \code
152  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelLine)
153  * // Eigen::Vector3f point_on_line, line_direction;
154  *
155  * pcl::ModelCoefficients line_coeff;
156  * line_coeff.values.resize (6); // We need 6 values
157  * line_coeff.values[0] = point_on_line.x ();
158  * line_coeff.values[1] = point_on_line.y ();
159  * line_coeff.values[2] = point_on_line.z ();
160  *
161  * line_coeff.values[3] = line_direction.x ();
162  * line_coeff.values[4] = line_direction.y ();
163  * line_coeff.values[5] = line_direction.z ();
164  *
165  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createLine (line_coeff);
166  * \endcode
167  *
168  * \ingroup visualization
169  */
171  createLine (const pcl::ModelCoefficients &coefficients);
172 
173  /** \brief Create a planar shape from a set of model coefficients.
174  * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
175  *
176  * \code
177  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelPlane)
178  * // Eigen::Vector4f plane_parameters;
179  *
180  * pcl::ModelCoefficients plane_coeff;
181  * plane_coeff.values.resize (4); // We need 4 values
182  * plane_coeff.values[0] = plane_parameters.x ();
183  * plane_coeff.values[1] = plane_parameters.y ();
184  * plane_coeff.values[2] = plane_parameters.z ();
185  * plane_coeff.values[3] = plane_parameters.w ();
186  *
187  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createPlane (plane_coeff);
188  * \endcode
189  *
190  * \ingroup visualization
191  */
193  createPlane (const pcl::ModelCoefficients &coefficients);
194 
195  /** \brief Create a planar shape from a set of model coefficients.
196  * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
197  * \param[in] x,y,z projection of this point on the plane is used to get the center of the plane.
198  * \ingroup visualization
199  */
201  createPlane (const pcl::ModelCoefficients &coefficients, double x, double y, double z);
202 
203  /** \brief Create a 2d circle shape from a set of model coefficients.
204  * \param[in] coefficients the model coefficients (x, y, radius)
205  * \param[in] z (optional) specify a z value (default: 0)
206  *
207  * \code
208  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCircle2D)
209  * // float x, y, radius;
210  *
211  * pcl::ModelCoefficients circle_coeff;
212  * circle_coeff.values.resize (3); // We need 3 values
213  * circle_coeff.values[0] = x;
214  * circle_coeff.values[1] = y;
215  * circle_coeff.values[2] = radius;
216  *
217  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::create2DCircle (circle_coeff, z);
218  * \endcode
219  *
220  * \ingroup visualization
221  */
223  create2DCircle (const pcl::ModelCoefficients &coefficients, double z = 0.0);
224 
225  /** \brief Create a cone shape from a set of model coefficients.
226  * \param[in] coefficients the cone coefficients (cone_apex, axis_direction, angle)
227  *
228  * \code
229  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCone)
230  * // Eigen::Vector3f cone_apex, axis_direction;
231  * // float angle;
232  * // Note: The height of the cone is set using the magnitude of the axis_direction vector.
233  *
234  * pcl::ModelCoefficients cone_coeff;
235  * cone_coeff.values.resize (7); // We need 7 values
236  * cone_coeff.values[0] = cone_apex.x ();
237  * cone_coeff.values[1] = cone_apex.y ();
238  * cone_coeff.values[2] = cone_apex.z ();
239  * cone_coeff.values[3] = axis_direction.x ();
240  * cone_coeff.values[4] = axis_direction.y ();
241  * cone_coeff.values[5] = axis_direction.z ();
242  * cone_coeff.values[6] = angle (); // degrees
243  *
244  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createCone (cone_coeff);
245  * \endcode
246  *
247  * \ingroup visualization
248  */
250  createCone (const pcl::ModelCoefficients &coefficients);
251 
252  /** \brief Create a cube shape from a set of model coefficients.
253  * \param[in] coefficients the cube coefficients (Tx, Ty, Tz, Qx, Qy, Qz, Qw, width, height, depth)
254  * \ingroup visualization
255  */
257  createCube (const pcl::ModelCoefficients &coefficients);
258 
259  /** \brief Create a cube shape from a set of model coefficients.
260  *
261  * \param[in] translation a translation to apply to the cube from 0,0,0
262  * \param[in] rotation a quaternion-based rotation to apply to the cube
263  * \param[in] width the cube's width
264  * \param[in] height the cube's height
265  * \param[in] depth the cube's depth
266  * \ingroup visualization
267  */
269  createCube (const Eigen::Vector3f &translation, const Eigen::Quaternionf &rotation,
270  double width, double height, double depth);
271 
272  /** \brief Create a cube from a set of bounding points
273  * \param[in] x_min is the minimum x value of the box
274  * \param[in] x_max is the maximum x value of the box
275  * \param[in] y_min is the minimum y value of the box
276  * \param[in] y_max is the maximum y value of the box
277  * \param[in] z_min is the minimum z value of the box
278  * \param[in] z_max is the maximum z value of the box
279  */
281  createCube (double x_min, double x_max,
282  double y_min, double y_max,
283  double z_min, double z_max);
284 
285  /** \brief Allocate a new unstructured grid smartpointer. For internal use only.
286  * \param[out] polydata the resultant unstructured grid.
287  */
288  PCL_EXPORTS void
290  }
291 }
292 /*@}*/
293 
294 #include <pcl/visualization/common/impl/shapes.hpp>
PCL_EXPORTS vtkSmartPointer< vtkDataSet > create2DCircle(const pcl::ModelCoefficients &coefficients, double z=0.0)
Create a 2d circle shape from a set of model coefficients.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createCube(const pcl::ModelCoefficients &coefficients)
Create a cube shape from a set of model coefficients.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createPlane(const pcl::ModelCoefficients &coefficients)
Create a planar shape from a set of model coefficients.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createCone(const pcl::ModelCoefficients &coefficients)
Create a cone shape from a set of model coefficients.
PlanarPolygon represents a planar (2D) polygon, potentially in a 3D space.
vtkSmartPointer< vtkDataSet > createPolygon(const typename pcl::PointCloud< PointT >::ConstPtr &cloud)
Create a 3d poly line from a set of points.
Definition: shapes.hpp:54
PCL_EXPORTS void allocVtkUnstructuredGrid(vtkSmartPointer< vtkUnstructuredGrid > &polydata)
Allocate a new unstructured grid smartpointer.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createSphere(const Eigen::Vector4f &center, double radius, int res=10)
Create a sphere shape from a point and a radius.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createCylinder(const pcl::ModelCoefficients &coefficients, int numsides=30)
Create a cylinder shape from a set of model coefficients.
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:430
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createLine(const Eigen::Vector4f &pt1, const Eigen::Vector4f &pt2)
Create a line shape from two points.
#define PCL_EXPORTS
Definition: pcl_macros.h:328