Point Cloud Library (PCL)  1.10.0-dev
opennurbs_arc.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_ARC_INC_)
18 #define ON_ARC_INC_
19 
20 /*
21 Description:
22  An ON_Arc is a subcurve of 3d circle.
23 Details:
24  The curve is parameterized by an angle expressed in radians. For an IsValid() arc
25  the total subtended angle AngleRadians() = Domain()(1) - Domain()(0) must satisfy
26  0< AngleRadians() <2*Pi .
27 
28  The parameterization of the ON_Arc is inherited from the ON_Circle it is derived from.
29  In particular
30  t -> center + cos(t)*radius*xaxis + sin(t)*radius*yaxis
31  where xaxis and yaxis, (part of ON_Circle::m_plane) form an othonormal frame of the plane
32  containing the circle.
33 */
34 class ON_CLASS ON_Arc : public ON_Circle
35 {
36 public:
37  // Create a radius one arc with angle = 2*pi
38  ON_Arc();
39 
40  /*
41  Description:
42  Construct an arc from a circle and an angle in radians
43  Parameters:
44  circle - [in]
45  angle_in_radians - [in]
46  */
47  ON_Arc(
48  const ON_Circle& circle,
49  double angle_in_radians
50  );
51 
52  /*
53  Parameters:
54  circle - [in]
55  angle_interval_in_radians - [in] increasing angle interval
56  in radians with angle_interval_in_radians.Length() <= 2.0*ON_PI.
57  */
58  ON_Arc(
59  const ON_Circle& circle,
60  ON_Interval angle_interval_in_radians
61  );
62 
63  /*
64  Description:
65  Construct an arc from a plane, radius and an angle in radians.
66  The center of the arc is at the plane's origin.
67  Parameters:
68  plane - [in]
69  circle is in this plane with center at m_origin
70  center - [in]
71  circle's center point
72  radius - [in]
73  angle_in_radians - [in]
74  */
75  ON_Arc(
76  const ON_Plane& plane,
77  double radius,
78  double angle_in_radians
79  );
80 
81  /*
82  Description:
83  Construct an arc parallel to the world XY plane from a
84  center point, radius, and angle in radians.
85  The arc starts at center+(radius,0,0).
86  Parameters:
87  center - [in]
88  radius - [in]
89  angle_in_radians - [in]
90  */
91  ON_Arc(
92  const ON_3dPoint& center,
93  double radius,
94  double angle_in_radians
95  );
96 
97  /*
98  Description:
99  Construct an arc parallel to plane from a center point,
100  radius, and angle in radians.
101  The arc starts at center+radius*plane.xaxis.
102  Parameters:
103  plane - [in]
104  The plane x, y and z axis are used to defines the circle
105  plane's x, y and z axis. The plane origin is ignorned.
106  center - [in]
107  circle's center point
108  radius - [in]
109  angle_in_radians - [in]
110  */
111  ON_Arc(
112  const ON_Plane& plane,
113  const ON_3dPoint& center,
114  double radius,
115  double angle_in_radians
116  );
117 
118  /*
119  Description:
120  Construct an arc that passes through three 2d points.
121  Parameters:
122  start_point - [in]
123  interior_point - [in]
124  end_point - [in]
125  */
126  ON_Arc(
127  const ON_2dPoint& start_point,
128  const ON_2dPoint& interior_point,
129  const ON_2dPoint& end_point
130  );
131 
132  /*
133  Description:
134  Construct an arc that passes through three 3d points.
135  Parameters:
136  start_point - [in]
137  interior_point - [in]
138  end_point - [in]
139  */
140  ON_Arc(
141  const ON_3dPoint& start_point,
142  const ON_3dPoint& interior_point,
143  const ON_3dPoint& end_point
144  );
145 
146  /*
147  Description:
148  Create an arc from a circle and an angle in radians
149  Parameters:
150  circle - [in]
151  angle_in_radians - [in]
152  Returns:
153  true if input is valid and a valid arc is created.
154  */
155  bool Create(
156  const ON_Circle& circle,
157  double angle_in_radians
158  );
159 
160  /*
161  Description:
162  Create an arc from a circle and an increasing angle interval
163  Parameters:
164  circle - [in]
165  angle_interval_in_radians - [in] increasing angle interval in radians
166  with angle_interval_in_radians.Length() <= 2.0*ON_PI
167  Returns:
168  true if input is valid and a valid arc is created.
169  */
170  bool Create(
171  const ON_Circle& circle,
172  ON_Interval angle_interval_in_radians
173  );
174 
175  /*
176  Description:
177  Create an arc from a plane, radius and an angle in radians.
178  The center of the arc is at the plane's origin.
179  Parameters:
180  plane - [in]
181  circle is in this plane with center at m_origin
182  center - [in]
183  circle's center point
184  radius - [in]
185  angle_in_radians - [in]
186  */
187  bool Create(
188  const ON_Plane& plane,
189  double radius,
190  double angle_in_radians
191  );
192 
193  /*
194  Description:
195  Create an arc parallel to the world XY plane from a
196  center point, radius, and angle in radians.
197  The arc starts at center+(radius,0,0).
198  Parameters:
199  center - [in]
200  radius - [in]
201  angle_in_radians - [in]
202  */
203  bool Create(
204  const ON_3dPoint& center,
205  double radius,
206  double angle_in_radians
207  );
208 
209  /*
210  Description:
211  Create an arc parallel to plane from a center point,
212  radius, and angle in radians.
213  The arc starts at center+radius*plane.xaxis.
214  Parameters:
215  plane - [in]
216  The plane x, y and z axis are used to defines the circle
217  plane's x, y and z axis. The plane origin is ignorned.
218  center - [in]
219  circle's center point
220  radius - [in]
221  angle_in_radians - [in]
222  */
223  bool Create(
224  const ON_Plane& plane,
225  const ON_3dPoint& center,
226  double radius,
227  double angle_in_radians
228  );
229 
230  /*
231  Description:
232  Create an arc that passes through three 2d points.
233  Parameters:
234  start_point - [in]
235  interior_point - [in]
236  end_point - [in]
237  */
238  bool Create(
239  const ON_2dPoint& start_point,
240  const ON_2dPoint& interior_point,
241  const ON_2dPoint& end_point
242  );
243 
244  /*
245  Description:
246  Create an arc that passes through three 3d points.
247  Parameters:
248  start_point - [in]
249  interior_point - [in]
250  end_point - [in]
251  */
252  bool Create(
253  const ON_3dPoint& start_point,
254  const ON_3dPoint& interior_point,
255  const ON_3dPoint& end_point
256  );
257 
258  /*
259  Description:
260  Create an arc from a 2d start point, 2d start direction
261  and a 2d end point.
262  Parameters:
263  start_point - [in]
264  dir_at_start - [in]
265  end_point - [in]
266  */
267  bool Create(
268  const ON_2dPoint& start_point,
269  const ON_2dVector& dir_at_start,
270  const ON_2dPoint& end_point
271  );
272 
273  /*
274  Description:
275  Create an arc from a 3d start point, 3d start direction
276  and a 3d end point.
277  Parameters:
278  start_point - [in]
279  dir_at_start - [in]
280  end_point - [in]
281  */
282  bool Create(
283  const ON_3dPoint& start_point,
284  const ON_3dVector& dir_at_start,
285  const ON_3dPoint& end_point
286  );
287 
288  ON_Arc& operator=( const ON_Circle& );
289 
290 
291  ~ON_Arc();
292 
293  // Description:
294  // Creates a text dump of the arc listing the normal, center
295  // radius, start point, end point, and angle.
296  // Remarks:
297  // Dump() is intended for debugging and is not suitable
298  // for creating high quality text descriptions of an
299  // arc.
300  void Dump( ON_TextLog& dump ) const;
301 
302  // Description:
303  // Checks an arc to make sure it is valid.
304  // Detail:
305  // Radius>0 and 0<AngleRadians()<=2 ON_PI
306  // Returns:
307  // true if the arc is valid.
308  bool IsValid() const;
309 
310  // Description:
311  // Get arc's 3d axis aligned bounding box.
312  // Returns:
313  // 3d bounding box.
314  ON_BoundingBox BoundingBox() const;
315 
316  // Description:
317  // Get arc's 3d axis aligned bounding box or the
318  // union of the input box with the arc's bounding box.
319  // Parameters:
320  // bbox - [in/out] 3d axis aligned bounding box
321  // bGrowBox - [in] (default=false)
322  // If true, then the union of the input bbox and the
323  // arc's bounding box is returned in bbox.
324  // If false, the arc's bounding box is returned in bbox.
325  // Returns:
326  // true if arc has bounding box and calculation was successful.
327  bool GetBoundingBox(
328  ON_BoundingBox& bbox,
329  int bGrowBox = false
330  ) const;
331 
332  /*
333  Description:
334  Get tight bounding box.
335  Parameters:
336  tight_bbox - [in/out] tight bounding box
337  bGrowBox -[in] (default=false)
338  If true and the input tight_bbox is valid, then returned
339  tight_bbox is the union of the input tight_bbox and the
340  arc's tight bounding box.
341  xform -[in] (default=NULL)
342  If not NULL, the tight bounding box of the transformed
343  arc is calculated. The arc is not modified.
344  Returns:
345  True if a valid tight_bbox is returned.
346  */
347  bool GetTightBoundingBox(
348  ON_BoundingBox& tight_bbox,
349  int bGrowBox = false,
350  const ON_Xform* xform = 0
351  ) const;
352 
353  // Returns:
354  // true if the arc is a complete circle; i.e., the arc's
355  // angle is 360 degrees.
356  bool IsCircle() const;
357 
358  // Returns:
359  // The arc's subtended angle in radians.
360  double AngleRadians() const;
361 
362  // Returns:
363  // The arc's subtended angle in degrees.
364  double AngleDegrees() const;
365 
366 
367  /*
368  Description:
369  Get evaluation domain.
370  Returns:
371  Evaluation domain (same as DomainRadians()).
372  */
373  ON_Interval Domain() const;
374 
375  // Returns:
376  // The arc's domain in radians.
377  ON_Interval DomainRadians() const;
378 
379  // Returns:
380  // The arc's domain in degrees.
381  ON_Interval DomainDegrees() const;
382 
383  // Description:
384  // Set arc's subtended angle in radians.
385  // Parameters:
386  // angle_in_radians - [in] 0 <= angle_in_radians <= 2.0*ON_PI
387  //
388  bool SetAngleRadians(
389  double angle_in_radians
390  );
391 
392  /*
393  Description:
394  Set arc's angle interval in radians.
395  Parameters:
396  angle_in_radians - [in] increasing interval with
397  start and end angle in radians.
398  Length of the interval <= 2.0*ON_PI.
399  Returns:
400  true if successful.
401  */
402  bool SetAngleIntervalRadians(
403  ON_Interval angle_in_radians
404  );
405 
406  // Description:
407  // Set arc's domain as a subdomain of the circle.
408  // Parameters:
409  // domain_radian - [in] 0 < domain_radian[1] - domain_radian[0] <= 2.0 * ON*PI
410  //
411  bool Trim(
412  ON_Interval domain_radian
413  );
414 
415  // Description:
416  // Set arc's subtended angle in degrees.
417  // Parameters:
418  // angle_in_degrees - [in] 0 < angle_in_degrees <= 360
419  bool SetAngleDegrees(
420  double angle_in_degrees
421  );
422 
423  // Returns:
424  // Point at start of the arc.
425  ON_3dPoint StartPoint() const;
426 
427 
428  // Returns:
429  // Point at middle of the arc.
430  ON_3dPoint MidPoint() const;
431 
432  // Returns:
433  // Point at end of the arc.
434  ON_3dPoint EndPoint() const;
435 
436  // Description:
437  // Get the point on the arc that is closest to test_point.
438  // Parameters:
439  // test_point - [in]
440  // t - [out] parameter (in radians) of the point on the arc that
441  // is closest to test_point. If test_point is the center
442  // of the arc, then the starting point of the arc is
443  // (arc.Domain()[0]) returned.
444  bool ClosestPointTo(
445  const ON_3dPoint& test_point,
446  double* t
447  ) const;
448 
449  // Description:
450  // Get the point on the arc that is closest to test_point.
451  // Parameters:
452  // test_point - [in]
453  // Returns:
454  // The point on the arc that is closest to test_point.
455  // If test_point is the center of the arc, then the
456  // starting point of the arc is returned.
458  const ON_3dPoint& test_point
459  ) const;
460 
461  // Returns:
462  // Length of the arc = radius*(subtended angle in radians).
463  double Length() const;
464 
465  /*
466  Returns:
467  Area of the arc's sector.
468  Remarks:
469  The arc's sector is the region bounded by the arc,
470  the line segment from the arc's end to the center,
471  and the line segment from the center to the arc's
472  start.
473  */
474  double SectorArea() const;
475 
476  /*
477  Returns:
478  Area centroid of the arc's sector.
479  Remarks:
480  The arc's sector is the region bounded by the arc,
481  the line segment from the arc's end to the center,
482  and the line segment from the center to the arc's
483  start.
484  */
485  ON_3dPoint SectorAreaCentroid() const;
486 
487  /*
488  Returns:
489  Area of the arc's segment.
490  Remarks:
491  The arc's segment is the region bounded by the arc and
492  the line segment from the arc's end to the arc's start.
493  */
494  double SegmentArea() const;
495 
496  /*
497  Returns:
498  Area centroid of the arc's segment.
499  Remarks:
500  The arc's segment is the region bounded by the arc and
501  the line segment from the arc's end to the arc's start.
502  */
503  ON_3dPoint SegmentAreaCentroid() const;
504 
505  // Description:
506  // Reverse the orientation of the arc. Changes the domain
507  // from [a,b] to [-b.-a].
508  bool Reverse();
509 
510  // Description:
511  // Get a rational degree 2 NURBS curve representation
512  // of the arc. Note that the parameterization of NURBS curve
513  // does not match arc's transcendental paramaterization.
514  // Use GetRadianFromNurbFormParameter() and
515  // GetParameterFromRadian() to convert between the NURBS curve
516  // parameter and the transcendental parameter
517  // Parameters:
518  // nurbs_curve - [out] nurbs_curve returned here.
519  // Returns:
520  // 0 for failure and 2 for success.
521  int GetNurbForm(
522  ON_NurbsCurve& nurbs_curve
523  ) const;
524 
525  /*
526  Description:
527  Convert a NURBS curve arc parameter to a arc radians parameter.
528  Parameters:
529  nurbs_parameter - [in]
530  arc_radians_parameter - [out]
531  Example:
532 
533  ON_Arc arc = ...;
534  double nurbs_t = 1.2345; // some number in interval (0,2.0*ON_PI).
535  double arc_t;
536  arc.GetRadianFromNurbFormParameter( nurbs_t, &arc_t );
537 
538  ON_NurbsCurve nurbs_curve;
539  arc.GetNurbsForm( nurbs_curve );
540  arc_pt = arc.PointAt(arc_t);
541  nurbs_pt = nurbs_curve.PointAt(nurbs_t);
542  // arc_pt and nurbs_pt will be the same
543 
544  Remarks:
545  The NURBS curve parameter is with respect to the NURBS curve
546  created by ON_Arc::GetNurbForm. At nurbs parameter values of
547  0.0, 0.5*ON_PI, ON_PI, 1.5*ON_PI, and 2.0*ON_PI, the nurbs
548  parameter and radian parameter are the same. At all other
549  values the nurbs and radian parameter values are different.
550  See Also:
551  ON_Arc::GetNurbFormParameterFromRadian
552  */
554  double nurbs_parameter,
555  double* arc_radians_parameter
556  ) const;
557 
558  /*
559  Description:
560  Convert a arc radians parameter to a NURBS curve arc parameter.
561  Parameters:
562  arc_radians_parameter - [in] 0.0 to 2.0*ON_PI
563  nurbs_parameter - [out]
564  Example:
565 
566  ON_Arc arc = ...;
567  double arc_t = 1.2345; // some number in interval (0,2.0*ON_PI).
568  double nurbs_t;
569  arc.GetNurbFormParameterFromRadian( arc_t, &nurbs_t );
570 
571  ON_NurbsCurve nurbs_curve;
572  arc.GetNurbsForm( nurbs_curve );
573  arc_pt = arc.PointAt(arc_t);
574  nurbs_pt = nurbs_curve.PointAt(nurbs_t);
575  // arc_pt and nurbs_pt will be the same
576 
577  Remarks:
578  The NURBS curve parameter is with respect to the NURBS curve
579  created by ON_Arc::GetNurbForm. At radian values of
580  0.0, 0.5*ON_PI, ON_PI, 1.5*ON_PI, and 2.0*ON_PI, the nurbs
581  parameter and radian parameter are the same. At all other
582  values the nurbs and radian parameter values are different.
583  See Also:
584  ON_Arc::GetNurbFormParameterFromRadian
585  */
587  double arc_radians_parameter,
588  double* nurbs_parameter
589  ) const;
590 
591 private:
592  friend bool ON_BinaryArchive::ReadArc( ON_Arc& );
593  friend bool ON_BinaryArchive::WriteArc( const ON_Arc& );
594 
595  // increasing interval with start and end angle in radians
596  ON_Interval m_angle;
597 };
598 
599 #endif
600 
bool GetRadianFromNurbFormParameter(double nurbs_parameter, double *circle_radians_parameter) const
bool ReadArc(ON_Arc &)
bool GetTightBoundingBox(ON_BoundingBox &tight_bbox, int bGrowBox=false, const ON_Xform *xform=0) const
int GetNurbForm(ON_NurbsCurve &nurbs_curve) const
bool GetNurbFormParameterFromRadian(double circle_radians_parameter, double *nurbs_parameter) const
bool WriteArc(const ON_Arc &)
ON_BoundingBox BoundingBox() const
bool IsValid() const
bool Create(const ON_Plane &plane, double radius)
bool ClosestPointTo(const ON_3dPoint &point, double *t) const
bool Reverse()