Point Cloud Library (PCL)  1.9.1-dev
opennurbs_plane.h
1 /* $NoKeywords: $ */
2 /*
3 //
4 // Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
5 // OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
6 // McNeel & Associates.
7 //
8 // THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
9 // ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
10 // MERCHANTABILITY ARE HEREBY DISCLAIMED.
11 //
12 // For complete openNURBS copyright information see <http://www.opennurbs.org>.
13 //
14 ////////////////////////////////////////////////////////////////
15 */
16 
17 #if !defined(ON_PLANE_INC_)
18 #define ON_PLANE_INC_
19 
20 class ON_CLASS ON_Plane
21 {
22 public:
23 
24  /*
25  Description:
26  The default constructor creates a plane
27  with orgin=(0,0,0), xaxis=(1,0,0), yaxis=(0,1,0)
28  zaxis=(0,0,1), and equation=(0,0,1,0).
29  */
30  ON_Plane();
31 
32  /*
33  Description:
34  Construct a plane from a point and normal vector.
35  Parameters:
36  origin - [in] point on the plane
37  normal - [in] non-zero normal to the plane
38  Remarks:
39  origin = point, zaxis = unitized normal, xaxis
40  xaxis set with xaxis.PerpindicularTo(zaxis).
41  See Also:
42  ON_Plane::CreateFromNormal
43  */
44  ON_Plane(
45  const ON_3dPoint& origin,
46  const ON_3dVector& normal
47  );
48 
49  /*
50  Description:
51  Construct a plane from a point, and two vectors in
52  the plane.
53  Parameters:
54  origin - [in] point on the plane
55  x_dir - [in] non-zero vector in the plane that
56  determines the xaxis direction.
57  y_dir - [in] non-zero vector not parallel to x_dir
58  that is used to determine the yaxis direction.
59  y_dir does not have to be perpendicular to x_dir.
60  */
61  ON_Plane(
62  const ON_3dPoint& origin,
63  const ON_3dVector& x_dir,
64  const ON_3dVector& y_dir
65  );
66 
67  /*
68  Description:
69  Construct a plane from three non-colinear points.
70  Parameters:
71  origin - [in] point on the plane
72  x_point - [in] second point in the plane.
73  The xaxis will be parallel to x_point-origin.
74  y_point - [in] third point on the plane that is
75  not colinear with the first two points.
76  yaxis*(y_point-origin) will be > 0.
77  */
78  ON_Plane(
79  const ON_3dPoint& origin,
80  const ON_3dPoint& x_point,
81  const ON_3dPoint& y_point
82  );
83 
84  /*
85  Description:
86  Construct a plane from an equation.
87  Parameters:
88  equation - [in] an array of 4 doubles with
89  one of equation[0], equation[1], or equation[2]
90  being non-zero.
91  */
92  ON_Plane(
93  const double equation[4]
94  );
95 
96  ~ON_Plane();
97 
98  bool operator==(const ON_Plane&) const;
99  bool operator!=(const ON_Plane&) const;
100 
101  /*
102  Description:
103  Create a plane from a point and normal vector.
104  Parameters:
105  origin - [in] point on the plane
106  normal - [in] non-zero normal to the plane
107  Remarks:
108  origin = point, zaxis = unitized normal, xaxis
109  xaxis set with xaxis.PerpindicularTo(zaxis).
110  Returns:
111  true if valid plane is created.
112  */
113  bool CreateFromNormal(
114  const ON_3dPoint& origin,
115  const ON_3dVector& normal
116  );
117 
118  /*
119  Description:
120  Construct a plane from a point, and two vectors in
121  the plane.
122  Parameters:
123  origin - [in] point on the plane
124  x_dir - [in] non-zero vector in the plane that
125  determines the xaxis direction.
126  y_dir - [in] non-zero vector not parallel to x_dir
127  that is used to determine the yaxis direction.
128  y_dir does not have to be perpendicular to x_dir.
129  Returns:
130  true if valid plane is created.
131  */
132  bool CreateFromFrame(
133  const ON_3dPoint& origin,
134  const ON_3dVector& x_dir,
135  const ON_3dVector& y_dir
136  );
137 
138  /*
139  Description:
140  Construct a plane from three non-colinear points.
141  Parameters:
142  origin - [in] point on the plane
143  point_on_x - [in] second point in the plane.
144  The xaxis will be parallel to x_point-origin.
145  point_on - [in] third point on the plane that is
146  not colinear with the first two points.
147  yaxis*(y_point-origin) will be > 0.
148  Returns:
149  true if valid plane is created.
150  */
151  bool CreateFromPoints(
152  const ON_3dPoint& origin,
153  const ON_3dPoint& point_on_x,
154  const ON_3dPoint& point_on
155  );
156 
157  /*
158  Description:
159  Construct a plane from an equation.
160  Parameters:
161  equation - [in] an array of 4 doubles with
162  one of equation[0], equation[1], or equation[2]
163  being non-zero.
164  Remarks:
165  points on the plane will satisfy
166  x*equation[0] +y*equation[1] + z*equation[2] + equation[3] = 0
167  Returns:
168  true if valid plane is created.
169  */
170  bool CreateFromEquation(
171  const double equation[4]
172  );
173 
174  /*
175  Description:
176  Test plane to see if it is valid.
177  Returns:
178  true if all fields contain reasonable
179  information and equation jibes with point and zaxis.
180  */
181  bool IsValid() const;
182 
183  /*
184  Returns:
185  Plane origin.
186  */
187  const ON_3dPoint& Origin() const;
188 
189  /*
190  Returns:
191  Plane unit x-axis.
192  */
193  const ON_3dVector& Xaxis() const;
194 
195  /*
196  Returns:
197  Plane unit y-axis.
198  */
199  const ON_3dVector& Yaxis() const;
200 
201  /*
202  Returns:
203  Plane unit normal.
204  */
205  const ON_3dVector& Normal() const;
206 
207 
208  /*
209  Description:
210  Set the origin and update the plane equation
211  Parameters:
212  origin - [in] the new origin
213  */
214  void SetOrigin( const ON_3dPoint& origin );
215 
216  /*
217  Description:
218  Evaluate a point on the plane
219  Parameters:
220  u - [in]
221  v - [in] evaulation parameters
222  Returns:
223  plane.origin + u*plane.xaxis + v*plane.yaxis
224  */
225  ON_3dPoint PointAt(
226  double u,
227  double v
228  ) const;
229 
230  /*
231  Description:
232  Evaluate a point on the plane
233  Parameters:
234  u - [in]
235  v - [in] evaluation parameters
236  w - [in] elevation parameter
237  Returns:
238  plane.origin + u*plane.xaxis + v*plane.yaxis + z*plane.zaxis
239  */
240  ON_3dPoint PointAt(
241  double u,
242  double v,
243  double w
244  ) const;
245 
246  /*
247  Description:
248  Get an isoparameteric line on the plane.
249  Parameters:
250  dir - [in] direction of iso-parametric line
251  0: first parameter varies and second parameter is constant
252  e.g., line(t) = plane(t,c)
253  1: first parameter is constant and second parameter varies
254  e.g., line(t) = plane(c,t)
255  c - [in] value of constant parameter
256  Returns:
257  iso-parametric line
258  */
259  ON_Line IsoLine(
260  int dir,
261  double c
262  ) const;
263 
264  /*
265  Description:
266  Get signed distance from the plane to a point.
267  Parameters:
268  point - [in]
269  Returns:
270  Signed distance from a point to a plane.
271  Remarks:
272  If the point is on the plane, the distance is 0.
273  If the point is above the plane, the distance is > 0.
274  If the point is below the plane the distance is < 0.
275  The zaxis determines the plane's orientation.
276  */
277  double DistanceTo(
278  const ON_3dPoint& point
279  ) const;
280 
281 
282  bool GetDistanceToBoundingBox(
283  //returns false if plane has zero length normal
284  const ON_BoundingBox&, // Box
285 
286  //output
287  double* min, // min signed dist from plane to box
288  double* max //max signed dist from plane to box
289  ) const;
290 
291  /*
292  Description:
293  Update the plane equation based on the current values
294  of the origin and zaxis.
295  Returns:
296  true if successful. false if zaxis is zero.
297  Remarks:
298  If you modify a plane's origin or zaxis, call UpdateEquation()
299  to set equation[].
300  */
301  bool UpdateEquation();
302 
303  /*
304  Description:
305  Get point on plane that is closest to a given point.
306  Parameters:
307  world_point - [in] 3d point
308  u - [out]
309  v - [out] The point ON_Plane::PointAt(*u,*v) is the point
310  on the plane that is closest to world_point.
311  Returns:
312  true if successful.
313  */
314  bool ClosestPointTo(
315  ON_3dPoint world_point,
316  double* u,
317  double* v
318  ) const;
319 
320  /*
321  Description:
322  Get point on plane that is closest to a given point.
323  Parameters:
324  point - [in]
325  Returns:
326  A 3d point on the plane that is closest to world_point.
327  */
328  ON_3dPoint ClosestPointTo(
329  ON_3dPoint point
330  ) const;
331 
332  // For intersections see ON_Intersect();
333 
334  /*
335  Description:
336  Transform plane.
337  Parameters:
338  xform - [in] transformation to apply to plane
339  Returns:
340  true if successful
341  */
342  bool Transform(
343  const ON_Xform& xform
344  );
345 
346  /*
347  Description:
348  Transform a plane by swapping coordinates.
349  Parameters:
350  i - [in]
351  j - [in] indices of coordinates to swap.
352  0 = x coordinate, 1 = y coordinate, 2 = z coordinate.
353  Returns:
354  true if successful.
355  */
356  bool SwapCoordinates(
357  int i,
358  int j
359  );
360 
361  /*
362  Description:
363  Rotate a plane about its origin.
364  Parameters:
365  sin_angle - [in] sine of rotation angle
366  cos_angle - [in] cosine of rotation angle
367  axis - [in] axis of rotation
368  Returns:
369  true if successful
370  */
371  bool Rotate(
372  double sin_angle,
373  double cos_angle,
374  const ON_3dVector& axis
375  );
376 
377  /*
378  Description:
379  Rotate a plane about its origin.
380  Parameters:
381  angle - [in] rotation angle in radians
382  axis - [in] axis of rotation
383  Returns:
384  true if successful
385  */
386  bool Rotate(
387  double angle,
388  const ON_3dVector& axis
389  );
390 
391  /*
392  Description:
393  Rotate a plane about a point.
394  Parameters:
395  sin_angle - [in] sine of rotation angle
396  cos_angle - [in] cosine of rotation angle
397  axis - [in] axis of rotation
398  center - [in] center of rotation
399  Returns:
400  true if successful
401  */
402  bool Rotate(
403  double sin_angle,
404  double cos_angle,
405  const ON_3dVector& axis,
406  const ON_3dPoint& center
407  );
408 
409  /*
410  Description:
411  Rotate a plane about a point.
412  Parameters:
413  angle - [in] rotation angle in radians
414  axis - [in] axis of rotation
415  center - [in] center of rotation
416  Returns:
417  true if successful
418  */
419  bool Rotate(
420  double angle,
421  const ON_3dVector& axis,
422  const ON_3dPoint& center
423  );
424 
425  /*
426  Description:
427  Translate a plane.
428  Parameters:
429  delta - [in] translation vector
430  Returns:
431  true if successful
432  */
433  bool Translate(
434  const ON_3dVector& delta
435  );
436 
437  /*
438  Description:
439  Flip plane orientation by swapping x and y axes,
440  reversing the zaxis, and updating the equation.
441  Returns:
442  true if successful
443  */
444  bool Flip();
445 
446 // world plane coordinate system ON_Plane(ON_origin, ON_xaxis, ON_yaxis);
447  const static
449 
450 public:
451  // origin of plane
453 
454  // unit X axis of plane
456 
457  // unit Y axis of plane
459 
460  // unit Z axis of plane
462 
463  // equation of plane
465  //double equation[4];
466 };
467 
468 class ON_CLASS ON_ClippingPlaneInfo
469 {
470 public:
471  // C++ defaults for construction, destruction, copy construction
472  // and operator= work fine.
473 
474  // A point is visible if m_plane_equation.ValueAt(point) <= 0.
475  // (This is the opposite convention from what OpenGL uses.)
479 
480  void Default();
481  bool Write( ON_BinaryArchive& ) const;
482  bool Read( ON_BinaryArchive& );
483 };
484 
485 class ON_CLASS ON_ClippingPlane
486 {
487 public:
489  ~ON_ClippingPlane();
490 
491  void Default();
492 
494  ON_UuidList m_viewport_ids; //ids of viewports that this clipping plane "clips"
496  bool m_bEnabled; // true if this clipping plane is active
497 
498  ON_ClippingPlaneInfo ClippingPlaneInfo() const;
499 
500  bool Read( class ON_BinaryArchive& );
501  bool Write( class ON_BinaryArchive& ) const;
502 };
503 
504 
505 #if defined(ON_DLL_TEMPLATE)
506 
507 // This stuff is here because of a limitation in the way Microsoft
508 // handles templates and DLLs. See Microsoft's knowledge base
509 // article ID Q168958 for details.
510 #pragma warning( push )
511 #pragma warning( disable : 4231 )
512 ON_DLL_TEMPLATE template class ON_CLASS ON_SimpleArray<ON_Plane>;
513 ON_DLL_TEMPLATE template class ON_CLASS ON_ClassArray<ON_ClippingPlane>;
514 ON_DLL_TEMPLATE template class ON_CLASS ON_SimpleArray<ON_ClippingPlaneInfo>;
515 #pragma warning( pop )
516 
517 #endif
518 
519 extern ON_EXTERN_DECL const ON_Plane ON_xy_plane;
520 extern ON_EXTERN_DECL const ON_Plane ON_yz_plane;
521 extern ON_EXTERN_DECL const ON_Plane ON_zx_plane;
522 
523 /*
524 Description:
525  Get a convex hull of a set of 3d points.
526 Parameters:
527  points - [in]
528  List of points. This function can handle tens of points
529  but is too slow for hundreds of points.
530  hull -[out]
531  Equations of the sides of the convex hull are appended to
532  this list.
533  A point P is inside the hull if hull[i].ValueAt(P) <= 0 for
534  every plane equation.
535 Returns:
536  Number of equations appended to hull[] array.
537  If 0, then the points are coincident or colinear.
538  If 2, then the points are coplanar and the returned
539  planes are parallel.
540  If >= 4, then the points are in a 3d convex hull.
541 */
542 ON_DECL
543 int ON_Get3dConvexHull(
544  const ON_SimpleArray<ON_3dPoint> & points,
546  );
547 
548 #endif
ON_PlaneEquation m_plane_equation
ON_3dVector zaxis
ON_3dPoint origin
ON_UuidList m_viewport_ids
ON_3dVector yaxis
static const ON_Plane World_xy
ON_PlaneEquation plane_equation
ON_3dVector xaxis