Point Cloud Library (PCL)  1.14.1-dev
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 
44 template <typename T> class vtkSmartPointer;
45 class vtkDataSet;
46 class vtkUnstructuredGrid;
47 
48 /**
49  * \file pcl/visualization/common/shapes.h
50  * Define methods or creating 3D shapes from parametric models
51  * \ingroup visualization
52  */
53 
54 /*@{*/
55 namespace pcl
56 {
57  struct ModelCoefficients;
58  template <typename PointT> class PlanarPolygon;
59 
60  namespace visualization
61  {
62  /** \brief Create a 3d poly line from a set of points.
63  * \param[in] cloud the set of points used to create the 3d polyline
64  * \ingroup visualization
65  */
66  template <typename PointT> vtkSmartPointer<vtkDataSet> inline
67  createPolygon (const typename pcl::PointCloud<PointT>::ConstPtr &cloud);
68 
69  /** \brief Create a 3d poly line from a set of points on the boundary of a planar region.
70  * \param[in] planar_polygon the set of points used to create the 3d polyline
71  * \ingroup visualization
72  */
73  template <typename PointT> vtkSmartPointer<vtkDataSet> inline
74  createPolygon (const pcl::PlanarPolygon<PointT> &planar_polygon);
75 
76  /** \brief Create a line shape from two points
77  * \param[in] pt1 the first point on the line
78  * \param[in] pt2 the end point on the line
79  * \ingroup visualization
80  */
82  createLine (const Eigen::Vector4f &pt1, const Eigen::Vector4f &pt2);
83 
84  /** \brief Create a sphere shape from a point and a radius
85  * \param[in] center the center of the sphere (as an Eigen Vector4f, with only the first 3 coordinates used)
86  * \param[in] radius the radius of the sphere
87  * \param[in] res (optional) the resolution used for rendering the model
88  * \ingroup visualization
89  */
91  createSphere (const Eigen::Vector4f &center, double radius, int res = 10);
92 
93  /** \brief Create a cylinder shape from a set of model coefficients.
94  * \param[in] coefficients the model coefficients (point_on_axis, axis_direction, radius)
95  * \param[in] numsides (optional) the number of sides used for rendering the cylinder
96  *
97  * \code
98  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCylinder)
99  * // Eigen::Vector3f pt_on_axis, axis_direction;
100  * // float radius;
101  *
102  * pcl::ModelCoefficients cylinder_coeff;
103  * cylinder_coeff.values.resize (7); // We need 7 values
104  * cylinder_coeff.values[0] = pt_on_axis.x ();
105  * cylinder_coeff.values[1] = pt_on_axis.y ();
106  * cylinder_coeff.values[2] = pt_on_axis.z ();
107  *
108  * cylinder_coeff.values[3] = axis_direction.x ();
109  * cylinder_coeff.values[4] = axis_direction.y ();
110  * cylinder_coeff.values[5] = axis_direction.z ();
111  *
112  * cylinder_coeff.values[6] = radius;
113  *
114  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createCylinder (cylinder_coeff, numsides);
115  * \endcode
116  *
117  * \ingroup visualization
118  */
120  createCylinder (const pcl::ModelCoefficients &coefficients, int numsides = 30);
121 
122  /** \brief Create a sphere shape from a set of model coefficients.
123  * \param[in] coefficients the model coefficients (sphere center, radius)
124  * \param[in] res (optional) the resolution used for rendering the model
125  *
126  * \code
127  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelSphere)
128  * // Eigen::Vector3f sphere_center;
129  * // float radius;
130  *
131  * pcl::ModelCoefficients sphere_coeff;
132  * sphere_coeff.values.resize (4); // We need 4 values
133  * sphere_coeff.values[0] = sphere_center.x ();
134  * sphere_coeff.values[1] = sphere_center.y ();
135  * sphere_coeff.values[2] = sphere_center.z ();
136  *
137  * sphere_coeff.values[3] = radius;
138  *
139  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createSphere (sphere_coeff, resolution);
140  * \endcode
141  *
142  * \ingroup visualization
143  */
145  createSphere (const pcl::ModelCoefficients &coefficients, int res = 10);
146 
147  /** \brief Create a line shape from a set of model coefficients.
148  * \param[in] coefficients the model coefficients (point_on_line, line_direction)
149  *
150  * \code
151  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelLine)
152  * // Eigen::Vector3f point_on_line, line_direction;
153  *
154  * pcl::ModelCoefficients line_coeff;
155  * line_coeff.values.resize (6); // We need 6 values
156  * line_coeff.values[0] = point_on_line.x ();
157  * line_coeff.values[1] = point_on_line.y ();
158  * line_coeff.values[2] = point_on_line.z ();
159  *
160  * line_coeff.values[3] = line_direction.x ();
161  * line_coeff.values[4] = line_direction.y ();
162  * line_coeff.values[5] = line_direction.z ();
163  *
164  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createLine (line_coeff);
165  * \endcode
166  *
167  * \ingroup visualization
168  */
170  createLine (const pcl::ModelCoefficients &coefficients);
171 
172  /** \brief Create a planar shape from a set of model coefficients.
173  * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
174  *
175  * \code
176  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelPlane)
177  * // Eigen::Vector4f plane_parameters;
178  *
179  * pcl::ModelCoefficients plane_coeff;
180  * plane_coeff.values.resize (4); // We need 4 values
181  * plane_coeff.values[0] = plane_parameters.x ();
182  * plane_coeff.values[1] = plane_parameters.y ();
183  * plane_coeff.values[2] = plane_parameters.z ();
184  * plane_coeff.values[3] = plane_parameters.w ();
185  *
186  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createPlane (plane_coeff);
187  * \endcode
188  *
189  * \ingroup visualization
190  */
192  createPlane (const pcl::ModelCoefficients &coefficients);
193 
194  /** \brief Create a planar shape from a set of model coefficients.
195  * \param[in] coefficients the model coefficients (a, b, c, d with ax+by+cz+d=0)
196  * \param[in] x,y,z projection of this point on the plane is used to get the center of the plane.
197  * \ingroup visualization
198  */
200  createPlane (const pcl::ModelCoefficients &coefficients, double x, double y, double z);
201 
202  /** \brief Create a 2d circle shape from a set of model coefficients.
203  * \param[in] coefficients the model coefficients (x, y, radius)
204  * \param[in] z (optional) specify a z value (default: 0)
205  *
206  * \code
207  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCircle2D)
208  * // float x, y, radius;
209  *
210  * pcl::ModelCoefficients circle_coeff;
211  * circle_coeff.values.resize (3); // We need 3 values
212  * circle_coeff.values[0] = x;
213  * circle_coeff.values[1] = y;
214  * circle_coeff.values[2] = radius;
215  *
216  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::create2DCircle (circle_coeff, z);
217  * \endcode
218  *
219  * \ingroup visualization
220  */
222  create2DCircle (const pcl::ModelCoefficients &coefficients, double z = 0.0);
223 
224  /** \brief Create a cone shape from a set of model coefficients.
225  * \param[in] coefficients the cone coefficients (cone_apex, axis_direction, angle)
226  *
227  * \code
228  * // The following are given (or computed using sample consensus techniques -- see SampleConsensusModelCone)
229  * // Eigen::Vector3f cone_apex, axis_direction;
230  * // float angle;
231  * // Note: The height of the cone is set using the magnitude of the axis_direction vector.
232  *
233  * pcl::ModelCoefficients cone_coeff;
234  * cone_coeff.values.resize (7); // We need 7 values
235  * cone_coeff.values[0] = cone_apex.x ();
236  * cone_coeff.values[1] = cone_apex.y ();
237  * cone_coeff.values[2] = cone_apex.z ();
238  * cone_coeff.values[3] = axis_direction.x ();
239  * cone_coeff.values[4] = axis_direction.y ();
240  * cone_coeff.values[5] = axis_direction.z ();
241  * cone_coeff.values[6] = angle (); // degrees
242  *
243  * vtkSmartPointer<vtkDataSet> data = pcl::visualization::createCone (cone_coeff);
244  * \endcode
245  *
246  * \ingroup visualization
247  */
249  createCone (const pcl::ModelCoefficients &coefficients);
250 
251  /** \brief Create a cube shape from a set of model coefficients.
252  * \param[in] coefficients the cube coefficients (Tx, Ty, Tz, Qx, Qy, Qz, Qw, width, height, depth)
253  * \ingroup visualization
254  */
256  createCube (const pcl::ModelCoefficients &coefficients);
257 
258  /** \brief Create a cube shape from a set of model coefficients.
259  *
260  * \param[in] translation a translation to apply to the cube from 0,0,0
261  * \param[in] rotation a quaternion-based rotation to apply to the cube
262  * \param[in] width the cube's width
263  * \param[in] height the cube's height
264  * \param[in] depth the cube's depth
265  * \ingroup visualization
266  */
268  createCube (const Eigen::Vector3f &translation, const Eigen::Quaternionf &rotation,
269  double width, double height, double depth);
270 
271  /** \brief Create a cube from a set of bounding points
272  * \param[in] x_min is the minimum x value of the box
273  * \param[in] x_max is the maximum x value of the box
274  * \param[in] y_min is the minimum y value of the box
275  * \param[in] y_max is the maximum y value of the box
276  * \param[in] z_min is the minimum z value of the box
277  * \param[in] z_max is the maximum z value of the box
278  */
280  createCube (double x_min, double x_max,
281  double y_min, double y_max,
282  double z_min, double z_max);
283 
284  /** \brief Create an ellipsoid shape from the given parameters.
285  *
286  * \param[in] transform a transformation to apply to the ellipsoid from 0,0,0
287  * \param[in] radius_x the ellipsoid's radius along its local x-axis
288  * \param[in] radius_y the ellipsoid's radius along its local y-axis
289  * \param[in] radius_z the ellipsoid's radius along its local z-axis
290  * \ingroup visualization
291  */
293  createEllipsoid (const Eigen::Isometry3d &transform,
294  double radius_x, double radius_y, double radius_z);
295 
296  /** \brief Allocate a new unstructured grid smartpointer. For internal use only.
297  * \param[out] polydata the resultant unstructured grid.
298  */
299  PCL_EXPORTS void
301  }
302 }
303 /*@}*/
304 
305 #include <pcl/visualization/common/impl/shapes.hpp>
PlanarPolygon represents a planar (2D) polygon, potentially in a 3D space.
shared_ptr< const PointCloud< PointT > > ConstPtr
Definition: point_cloud.h:414
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createPlane(const pcl::ModelCoefficients &coefficients)
Create a planar shape from a set of model coefficients.
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 vtkSmartPointer< vtkDataSet > createEllipsoid(const Eigen::Isometry3d &transform, double radius_x, double radius_y, double radius_z)
Create an ellipsoid shape from the given parameters.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createCylinder(const pcl::ModelCoefficients &coefficients, int numsides=30)
Create a cylinder shape from a set of model coefficients.
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 > createCube(const pcl::ModelCoefficients &coefficients)
Create a cube shape from a set of model coefficients.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createLine(const Eigen::Vector4f &pt1, const Eigen::Vector4f &pt2)
Create a line shape from two points.
PCL_EXPORTS vtkSmartPointer< vtkDataSet > createCone(const pcl::ModelCoefficients &coefficients)
Create a cone shape from a set of model coefficients.
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 void allocVtkUnstructuredGrid(vtkSmartPointer< vtkUnstructuredGrid > &polydata)
Allocate a new unstructured grid smartpointer.
#define PCL_EXPORTS
Definition: pcl_macros.h:325